Contracts
P Case-driven additions: execution obligations joins plan steps, scoped assertions, external work, effects, restoration and completion in a versioned paper; configuration change describes an existing-product delta and multiple template leaf specifications; configuration input admits either that delta or the existing full product specification. Examples, the two-template delta and the conformance checker test these rules offline. Case journeys owns their execution meaning. The service resolves references against authoritative case records; model-supplied references alone prove nothing.
What one component owes another, written as schemas a tool validates — the phase-1 deliverable that lets the tracks of Delivery § 1.3 start without talking to each other, and the acceptance criterion of Delivery § 1.4.4 item 5: contracts written and validated against a deliberately broken fixture. Two kinds, deliberately different in strictness (D139):
| Kind | Strictness | Why |
|---|---|---|
| Platform seams (P-14, five) | closed — additionalProperties: false; adding a field or a kind is a governed runtime version |
every module and every connector is written against them; drift here is drift everywhere |
| Inter-stage contracts (the modules' eleven) | drafts — a small required core the platform validates, an open body a case may extend (additionalProperties: true, x-status: draft) |
the stage authors learn what the next stage needs on real cases; a schema that forbade the learning would be wrong on day one. A draft graduates to a closed seam only when three modules' cases have stopped extending it |
Every schema is Draft 2020-12; validate_contracts.py runs the structural layer and a semantic layer that recomputes what a schema cannot express (the ledger hash, the auditor's exactness rules, the grader isolation), against the fixtures in contracts/fixtures/ — one valid and one broken per platform seam; the broken one must be refused with the reason named. python validate_contracts.py → all fixture expectations must match.
1. The five platform seams (P-14)
| # | Seam | Schema | Fixtures | What it fixes | Stated in |
|---|---|---|---|---|---|
| 1 | Message envelope | message-envelope.schema.json |
valid · broken | the twelve typed kinds and their payloads; small typed payloads plus hash-checked artefact references for larger material; a consult is addressed to a domain, depth one; free text to a parent is not an output | Agent Runtime § 4 |
| 2 | Connector capability | connector-capability.schema.json |
valid · broken | the operation row whose absence fails closed: effect class, authorization, idempotency key, timeout and its effect, recovery, evidence returned, write shape; reach rows direct or unreachable (D132) | Failure and Recovery § 4 |
| 3 | Eval set | eval-set.schema.json |
valid · broken | input/ oracle/ tolerances.json per case; deterministic checks first, rubric to the isolated grader with an Unknown exit; a Development case is a lineage pair |
Agent Framework § 6.5 |
| 4 | Ledger record | ledger-record.schema.json |
valid · broken | the 51 kinds; actor, versions, lineage, target, requested and actual action, counts, hashes; record_hash = SHA-256(prev_hash ‖ canonical) — the broken fixture is a record edited after hashing, and the validator catches it |
Architecture § 3.2, Trust and Data § 5 |
| 5 | Write shape and write packet | write-shape.schema.json |
valid · broken | the approved template with declared parameters, counts as an expression, derived teardown, case types, expiry (D133); the instance packet with every parameter bound and every count a number — the auditor's four checks stated as rules | Gating § 4, § 6, § 9.1 |
The persisted forms are the CLOB … IS JSON columns of the Data Model; the C# forms are the records of AI.Contracts (copied and owned — Software Architecture § 9.1).
2. The inter-stage drafts (D139)
P Required core only. A stage that needs a field the draft lacks adds it in its case and writes the addition into its sign-out; the stage author lifts recurring additions into the next draft version. The platform refuses a paper that lacks the core and accepts everything else — contracts.inter_stage.mode = draft in the policy seed.
| Module | Draft | Between | Core it fixes |
|---|---|---|---|
| Configuration | configuration-summary |
S2 → S3 | versions deployed on the working environment, rated covers (unpriced ones with their note, D122), rating factors POL-only, worked examples asserting the version priced (D113), what nothing holds |
| Configuration | sign-out-document |
every phase → the next | tested by which skill to which proof level, what the next phase needs, open items, artefacts each with its revert (D120), who signed at which gate |
| every module | stage-contract |
the stage set of a case type | consumes/produces with their contracts, proves-with skills, gates and when they fire, proof rungs reachable, memory domain, parallel stages (D75) |
| Support | normalised-arrival |
connector → S1 | channel, origin key, reporter handle, body as a paper, identifiers as handles with structural facets, scanned attachments, mirrors, channel hints and intake initiation outcome; classifier and route outputs are separate |
| Support | solution-packet |
S3 → H2 (the route) → S4/H3 | mechanism with the verifier's verdict, kind, the exact change per step (with its write packet or Hd request), expected counts, revert path, replay including the customer-surface check, uncertainties, predicted minutes |
| Support | experience-entry |
S8 → support/experience |
symptom verbatim + normalised + hash, systems, mechanism layer-named, fix shape, skill, links, observed version; no PII by construction |
| Development | brief |
S1–S2 → H2 | reproduction and the configuration-or-code pre-question, the chosen seam and the three rejected, the split of a mixed change, blast radius, test plan per lineage, predicted minutes, the three-part definition of done, the port plan |
| Development | branch-set |
S1 → everything after | start flow, repositories with layout/branch/head and their counterpart with measured divergence, the database's stored code with signatures and snapshot ids, deploy targets with the D130 rule |
| Development | cross-repo-shape |
implementer ↔ implementer | the sides, the contract artefact both read, compatibility strategy, deploy order, interface tests |
| every module | handover-packet — example |
root → root at Hd, both directions (D142) | request: what/why/kind, what the sub-case inherits (papers, grants narrowed to reads, the same handle map), what done means for the requester, the requester owns closure; response: accepted with sub-case and predicted minutes, or rejected with a reason — never hangs; completion: result, proof level, what changed with write-log ids, the standing revert path, the done-means checked |
| platform | skill-manifest |
memory tree → SKILLS.MANIFEST |
inputs, operations, assertions, writes → dry-run default and teardown, the coverage map per configuration object (D74/D136) |
3. The service contracts the UI and the connectors are written against
| Developer example | Valid | Deliberately refused |
|---|---|---|
| Model action | tool call | non-object arguments |
| Restorable checkpoint | pending gate/call | complete with pending work |
| Bound write proposal | no pre-existing grant required | changed parameter under the old hash |
P HTTP command protocol. Mutating commands carry Idempotency-Key. The server derives the INBOX_MESSAGES key from authenticated caller + operation + supplied key and binds the request-body hash. Existing-resource commands compare the shown row version; decision commands additionally compare the artefact hash. Store the command disposition/response reference, state change and outbox together. Recheck current access before returning a cached result. HTTP commands have CONSUMER_KEY and no recipient task where no task exists yet; a task message must name its recipient. Stale state or different bytes under the same key returns 409.
P Developer execution contracts. module-manifest.schema.json declares the four graphs (Modules); model-turn.schema.json is the closed structured model action; runtime-state.schema.json is the restorable checkpoint content. route-packet.schema.json separates a route decision from a final solution whose mechanism may not yet be known. validate_runtime_contracts.py checks the manifests, valid/broken examples and gate/recovery truth tables offline.
P These supplement the five existing platform seams; they do not replace their message, capability, eval, ledger or write contracts. A seed declaration is not a published profile. Service activation must additionally resolve referenced versions, validate handler bindings and exercise the acceptance tests in Implementation Guide.
| Contract | File | Fixes |
|---|---|---|
| HTTP API | openapi.yaml — OpenAPI 3.1, 43 paths |
the eight workspaces and the client's four screens as resources: inbox decisions in one action, cases and the card stream with a ledger cursor, gates with their packets and a hash-checked decide, held batches, shape extension (D133), the token-gated papers, studio try → evaluate → approve → publish → rollback, the knowledge tree and proposals, metrics as ledger projections, control (connectors, policies, roles, the N-12 register, exceptions, kill switch, audit tail, ledger verify), the client's requests and acceptance. Every mutating call names the role it needs and answers 403 with who holds it |
| Realtime events | realtime-events.schema.json |
the 23 event kinds over SignalR groups case:<id> · gates:<role> · control · client:<customer>; references only; every event carries the ledger seq_no so a reconnect re-reads /cases/{id}/cards?after= — the hub never replays |
| Connector SDK | Connectors.Abstractions.cs |
IConnector with ProbeAsync (direct or unreachable), ReadAsync, WriteCollapsedAsync (shape A), the five lease methods BeginLeasedWriteAsync · ApplyUnderLeaseAsync · VerifyUnderLeaseAsync · CommitLeaseAsync · RollbackLeaseAsync (shape B), ExecuteEffectAsync (non-transactional form E), WhatLandedAsync (four-valued resume handshake), VerifyAsync; ConnectorOperation, GrantView, ToolResultEnvelope, Refusal as a value; IPermissionPipeline — policy, grant, scope, deny beats everything |
4. Where the older contract stands
20 Configuration/contracts/product.schema.json with its validator and broken fixture predates this page (02.09.2026) and stays the specification contract of S1. Three drifts are recorded rather than hidden: the fixture's comment says 7 blockers and the validator finds 9; the validator's docstring cites a Whitelabel Specification page that became Stage Normalization; the schema pins schema_version "1" while the stage pages speak of 1.1. All three are closed in the same change that lifts the schema to 1.1.
Challenges
- C The drafts have been exercised against the eight Configuration, ten Support and eight Development written cases, not against a running stage. The first real case of each module either confirms a core field or moves it to the open body; the count of fields moved is the measure of how good the drafts were.
- P The OpenAPI file is a draft in the same sense: its resources and roles are fixed, its DTO fields extend during wave 1. The UI track codes against it from day one (Delivery § 1.3 ordering 4).
- P
Connectors.Abstractions.csuses a minimalEither; whether the module adopts a result library is a code-style decision of the platform track.