ContextOS Contract Sync
Keep every executable representation of a runtime contract semantically aligned and versioned. Do not treat successful JSON parsing as proof of compatibility.
Inventory the affected surface
Read the repository instructions, then locate:
- TypeScript declaration and every producer/consumer;
- published JSON Schema and its
$defs dependencies;
- canonical scenario/compiler or test harness;
- implementation and reference documentation;
- drift, schema-surface, runtime-schema, compiler, and admission tests.
Read references/surface-map.md for the current contract bundle, parity invariants, and test routing. Confirm the active repository still matches that map before editing.
Decide compatibility first
Classify the change:
- Additive: an optional field or compatible enum-free extension that legacy producers/consumers may omit.
- Tightening: stronger validation or newly required behavior; requires migration analysis even if the filename stays the same.
- Breaking: removed/renamed field, changed meaning, narrowed enum accepted by existing producers, or new required field; use a major contract version and explicit migration.
Separate schema compatibility from runtime trust. An additive field may remain optional for old payloads while the canonical producer always emits it; consumers must treat absence as legacy/unknown, never trusted.
Change the contract coherently
- Update the TypeScript semantic type and comments.
- Update deterministic producers and consumers; unsupported values fail closed.
- Update every published schema copy of shared definitions. Preserve draft 2020-12 and canonical
$id conventions.
- Update canonical examples from the reference scenario or actual compiler output.
- Update the API schema index and explanatory docs.
- Add or strengthen tests that compare semantic definitions and producer output; do not merely assert wording.
- Remove superseded public schema versions only when the repository's single-authoritative-surface policy and migration plan require it. Never leave ambiguous duplicates.
Check cross-contract invariants
trace_id, tenant, identity, and lineage propagate across request, compiled context, tools, decision, and replay.- delegation scopes and sub-budgets narrow the parent.
ActionRisk has identical definitions where declared, compiled, and executed.- compiled context admission/evidence-gate definitions remain identical in the DecisionRecord audit surface.
- tool call and result IDs correlate; policy decision and approval references resolve.
- evidence, omissions, controls, hashes, and release pins required for replay survive to the audit record.
- replay consumes recorded transcripts and does not repeat live effects.
Validate
Run targeted schema-surface, runtime-schema, spec-drift, compiler, and context-admission tests as applicable, followed by typecheck and the full test suite. Parse every published schema and inspect the exact public schema file set.
Return a compatibility note, changed-surface matrix, migration implications, test evidence, and any consumer behavior that remains unverified.
1---2name: contextos-contract-sync3description: Add or evolve ContextOS runtime contracts across TypeScript types, JSON Schemas, canonical examples, documentation, and drift tests. Use for RunContext, ContextPack, CompiledContext, ToolEnvelope, DecisionRecord, ReplayPacket, or delegation changes; not for prose-only edits.4---56# ContextOS Contract Sync78Keep every executable representation of a runtime contract semantically aligned and versioned. Do not treat successful JSON parsing as proof of compatibility.910## Inventory the affected surface1112Read the repository instructions, then locate:1314- TypeScript declaration and every producer/consumer;15- published JSON Schema and its `$defs` dependencies;16- canonical scenario/compiler or test harness;17- implementation and reference documentation;18- drift, schema-surface, runtime-schema, compiler, and admission tests.1920Read [references/surface-map.md](references/surface-map.md) for the current contract bundle, parity invariants, and test routing. Confirm the active repository still matches that map before editing.2122## Decide compatibility first2324Classify the change:2526- **Additive:** an optional field or compatible enum-free extension that legacy producers/consumers may omit.27- **Tightening:** stronger validation or newly required behavior; requires migration analysis even if the filename stays the same.28- **Breaking:** removed/renamed field, changed meaning, narrowed enum accepted by existing producers, or new required field; use a major contract version and explicit migration.2930Separate schema compatibility from runtime trust. An additive field may remain optional for old payloads while the canonical producer always emits it; consumers must treat absence as legacy/unknown, never trusted.3132## Change the contract coherently33341. Update the TypeScript semantic type and comments.352. Update deterministic producers and consumers; unsupported values fail closed.363. Update every published schema copy of shared definitions. Preserve draft 2020-12 and canonical `$id` conventions.374. Update canonical examples from the reference scenario or actual compiler output.385. Update the API schema index and explanatory docs.396. Add or strengthen tests that compare semantic definitions and producer output; do not merely assert wording.407. Remove superseded public schema versions only when the repository's single-authoritative-surface policy and migration plan require it. Never leave ambiguous duplicates.4142## Check cross-contract invariants4344- `trace_id`, tenant, identity, and lineage propagate across request, compiled context, tools, decision, and replay.45- delegation scopes and sub-budgets narrow the parent.46- `ActionRisk` has identical definitions where declared, compiled, and executed.47- compiled context admission/evidence-gate definitions remain identical in the DecisionRecord audit surface.48- tool call and result IDs correlate; policy decision and approval references resolve.49- evidence, omissions, controls, hashes, and release pins required for replay survive to the audit record.50- replay consumes recorded transcripts and does not repeat live effects.5152## Validate5354Run targeted schema-surface, runtime-schema, spec-drift, compiler, and context-admission tests as applicable, followed by typecheck and the full test suite. Parse every published schema and inspect the exact public schema file set.5556Return a compatibility note, changed-surface matrix, migration implications, test evidence, and any consumer behavior that remains unverified.
contextosai