03 — agent_api Plan-Only Contract (Workstream B)

Delivered LIVE: dot_agent_api_contract — a generic, additive contract registry. Birth-free, reversible.

Schema (generic, keyed by dot_code)

id, dot_code (UNIQUE), candidate_code, operation, role∈{producer,verifier}, paired_dot, mode∈{PLAN_ONLY,VERIFY_ONLY,DRY_RUN} default PLAN_ONLY, fixture_ref, output_namespace (CHECK LIKE 'DRYRUN-NS:%'), no_mutation_assertion (CHECK = true), endpoint_ref (NULL = no real endpoint), expected_output_schema jsonb, verifier_schema jsonb, error_behavior default 'fail_closed_no_mutation', observation_write_policy default 'SIMULATED_DRY_RUN_ONLY_UNTIL_ENDPOINT', contract_status default 'contract_ready', source_macro, created_at, notes.

Defense-in-depth constraints

• CHECK (no_mutation_assertion = true) — a mutating contract literally cannot be stored.
• CHECK (output_namespace LIKE 'DRYRUN-NS:%') — production namespaces rejected at write.
• CHECK (mode <> 'DRY_RUN' OR endpoint_ref IS NOT NULL) — a DRY_RUN-mode contract is illegal until an endpoint is bound. This is the schema-level encoding of the blocker.

Contract field coverage vs macro spec §6

dot_code ✓ · operation ✓ · mode (PLAN_ONLY/VERIFY_ONLY/DRY_RUN) ✓ · fixture_ref ✓ · output_namespace ✓ · process_run_id / correlation_id / component_run_id (supplied by the dispatcher per call, not stored on the contract — they are run-scoped) ✓ · idempotency_key (dispatcher-derived) ✓ · no_mutation_assertion ✓ · expected_output_schema ✓ · verifier_schema ✓ · error behavior ✓ · observation_write_policy ✓.

Why this is not hardcoded to dot-kg

The table is keyed by dot_code and joined generically in the v5 views via evidence_graph_v2.component_ref. Any of the 12 agent_api KG DOTs (or any future agent_api DOT) becomes contract-ready by inserting one row. The pilot pair is simply the first two rows.

Status

Contract layer LIVE for the pilot pair (contract_status=contract_ready, endpoint_ref=NULL). The other 10 agent_api KG DOTs show contract_missing in v_process_discovery_agent_api_contract_status — correct and uninflated.