Developer implementation guide
1. Start here
P Build a C# platform that executes durable cases over IPAL, INSIS and the surrounding estate. LLMs interpret and propose; deterministic software owns execution, authority and evidence. The first delivery is a complete, bounded Configuration case using the same runtime the other modules will use. This is an implementation specification, not a claim that the platform already exists.
| Read in this order | Developer question answered |
|---|---|
| Software Architecture | which projects exist, who depends on whom, what is copied, what runs where |
| Modules | how the four business modules become versioned declarations and task graphs |
| Model Execution | what one model call receives/returns and what the copied provider seam actually supplies |
| Agent Runtime | scheduling, calls, messages, state transitions, checkpoint and recovery procedures |
| Case journeys and Case Protocol | all 68 real case types, exact screen/API/storage transitions, agent initialization and prompts, messages, results, reversal and learning |
| Gating and Trust and Data | permission composition, exact packet binding, roles and data boundaries |
| Data Model and Contracts | persisted fields, JSON/C# contracts, validators and proposed SQL |
| The selected module's stages and Components page | domain algorithms, assertions, inputs, outputs and target operations |
2. The first three implementation increments
P Build against the case journeys. All 68 catalogue cases have a first-run path, post-result processing, next-request behaviour and falsifying variant. Start the Configuration slice with CF-05 (two rating templates), then CF-18 (a requirement revision); use DC-02, DC-19 and DV-02 as cross-module conformance cases for family proof, restoration and mixed release. The offline checker and fixtures define required joins; passing them does not establish real agent or connector behaviour.
P Each increment produces running software and tests. Documentation and fixtures can be developed concurrently; unknown estate access does not prevent a local replay implementation.
| Increment | Build | Acceptance |
|---|---|---|
| 1. Durable case and execution core | host composition; persistence; papers; ledger/outbox; task leases; inbox deduplication; call journal and checkpoint state; fake provider and connector | stop after each persistence/dispatch boundary and resume; no completed mutation repeated; an unknown outcome remains blocked; duplicate messages produce one transition |
| 2. LLM loop and authority | structured model actions, context assembler, pinned profiles/routes/manifests, skill runner, auditor, gate/grant service and execution coordinator | a replayed model proposes an out-of-scope action and never contacts the target; a changed packet or expired grant is refused; a valid gate resumes exactly the saved action; isolated verifier cannot read author context |
| 3. One complete Configuration slice | minimal intake/Support route for client requests, Configuration S1 and required stages, one bounded connector path, operator decisions, client preview/acceptance and requested target release | validate input, show a preview, apply only the approved set, prove the actual target, record unresolved limits truthfully and obtain the corresponding acceptance |
P This does not add a new product feature or change the Configuration-first wave. The minimal desk route is a platform prerequisite of client-originated work; six investigators and the full support skill catalogue still belong to wave 2. The client surface uses the existing four screens, not a new portal. Offline replay precedes authorised target testing; no target write is implied by a passing fixture.
3. What each developer implements
| Owner by discipline | Concrete implementation responsibility | Contract and test boundary |
|---|---|---|
| Service/persistence | atomic state transitions, optimistic concurrency, task leases, immutable paper revisions, journal/outbox/inbox and ledger append | Runtime; Data Model |
| Runtime/model | render context, invoke IInferenceClient, validate actions, dispatch through registered tools, persist results and resume |
Model Execution; fake provider plus real adapter contract tests |
| Connector | input validation, credential resolution, effect classification, preflight, exact execution, evidence and WhatLandedAsync |
Connector SDK; known-before/after/unknown outcomes, with refusal before unauthorised contact |
| Skill/projection | validated inputs → declared operations/assertions; deterministic template binding and same-step revert | module stage/coverage map; valid and deliberately bad cases |
| UI | query resources, case cards and decisions, reconnect by ledger cursor, revision/hash-aware commands, customer filtering | OpenAPI, realtime schema, UI |
| Prompt/domain author | profile prompt, input examples, owned domain proposals, expected outcomes and rubric dimensions | Agent Framework; each profile's eval corpus |
4. The state a first implementation must carry
P An accepted arrival produces an ARRIVALS row and a case identity before any case paper or handle is created. The selected policy/case-type/manifest versions are pinned. A task has an immutable profile version, a worker lease and fencing epoch. A provider/tool call has a stable identity, request hash, dispatch status and result reference. A checkpoint names an immutable state paper containing the exact pending actions, messages, gates and consumed revisions. Hashes without retrievable bytes are not a checkpoint.
P A target commit and a platform checkpoint are separate transactions. RUNTIME_CALLS records intent before dispatch and reconciles an uncertain result. The target must provide either idempotency or a conclusive read-back for automatic retry. Otherwise the case waits for evidence; neither a zero row count nor a timeout proves that nothing happened. Full procedures and mappings are in Runtime §§ 2,5,7.
5. Checks before a real target is enabled
P The offline schema and fixtures prove contract consistency only. The first authorised environment additionally needs the target identity and scope, tested input/effect/recovery semantics, source-to-target mapping, working backup/recovery for platform records and papers, export verification and the operational kill switch. Run the installation/upgrade tests on a disposable authorised schema before treating the proposed guards as implemented. The setup is a named delivery prerequisite, not an extra approval inside every case.
P The live slice must prove refusal, safe execution, a deliberately failed assertion, compensation where applicable, and loss of a worker after the target succeeds. Post-commit UI verification is a separate test. Never report an offline DDL lint or a green pipeline as deployed acceptance.
6. Decisions already fixed and remaining estate facts
P Developers do not need to reopen the language, host placement, four modules, native loop, copied provider seam, gate authority, owned memory or customer-lineage decisions. The decision register and canonical pages state them.
P Environment-specific facts are obtained through the existing probes and inventories: approved identity assignments, reachable endpoints, source layout/ref, operation capability, exact table shape, and restore proof. A missing fact blocks that connector or live acceptance, not implementation of the state machines, fake adapters, UI contracts or profile fixtures. A capability that cannot safely reconcile an unknown effect is explicitly human-reconciled until the connector can prove more.
P Scope stays the requested control of existing software. This revision adds no change-calendar product, client spending controls, new sandbox service, purchasing funnel or extra orchestration framework.