Runtime API Schemas

Reference Architecture

This page is the routing table for executable runtime schemas. Earlier versions of this page embedded compact illustrative snippets; the published /schemas/*.json artifacts below are now the validation surface.

Published schemas

Additive execution profiles

ExecutionContractEnvelope is a separate attachment bound to the run, trace and tenant by a trusted admission store. It adds no required field to the eight existing envelopes. Schema validation checks the closed structure and resource bounds: one to 16 profiles, at most 128 required controls, optional controls and release references per array, and identifiers/revisions up to 256 Unicode characters. A schema-valid unknown revision still fails semantic negotiation when the implementation cannot support it.

negotiateExecutionContract in the TypeScript reference verifies content-addressed registry definitions, expands mandatory and feature-conditional controls and compares exact support declarations. Mandatory obligations cannot be demoted to optional. Trusted admission derives all eight feature booleans from the actual workflow and runtime configuration; caller or model flags do not authenticate themselves. An accepted result is compatibility evidence. Current authority, approval, active containment, mediated data movement and effect safety require separate runtime enforcement and observations.

The new schema’s $defs validate its reference attachments directly. The root remains ExecutionContractEnvelope; it is not a union accepting an arbitrary attachment in place of an admitted run contract. There are exactly nine public schema files: eight compatible base schemas and this additive schema. The public TypeScript facade uses aliases to each owning module rather than copied field definitions.

Execution attachment entry points

Use the full schema ID followed by #/$defs/TypeName as the validator entry point. The schema includes every non-generic exported attachment from the new contract modules, including input/result objects and enum aliases. These are the principal boundaries:

TransitionResult<T> is generic in TypeScript; a serialized schema needs a concrete state. The three named transition entry points above instantiate it for run, operation and budget ledgers. ResumeValidationResult is the specialized checkpoint result with explicit non-dispatch rejection obligations.

Attachment objects are closed; finite dictionaries such as action arguments intentionally accept JSON content and still require bounded safe canonical processing. New counters are non-negative safe integers. Exact accounting declares currency and a power-of-ten quantum; legacy fractional-cent fields retain their original schemas. The schema cannot establish cross-field budget sums, attenuation, current revocation, stored approval identity or valid state transitions. The actual module validators check those semantics separately.

Register the schema’s contextos-utc string format with isContractTimestamp from the TypeScript reference. It accepts bounded valid UTC calendar labels ending in Z, preserves arbitrary fractional precision within the 256-character bound, and rejects offsets and leap-second labels pending an explicit time-scale adapter. A validator that skips unknown formats has not performed the required timestamp check. The repository’s Ajv 2020 tests register this format explicitly; legacy schemas continue to use their existing date-time format.

An attachment’s structural validity does not verify referenced bytes or authenticate its publisher. Verify canonical content digests, trust roots, current observations and trusted run/tenant/trace correlation separately. A well-formed wrong proposal, expired stored approval or unsupported revision remains schema-valid where the shape permits it and must still fail semantic admission/authorization. See Execution Contract, Control Profiles and Conformance.

New profile bindings use complete RFC 8785 canonical JSON with explicit domain separation. The helper rejects non-JSON values, accessors, cycles, malformed Unicode and reference traversal limits (64 nesting levels, 10,000 values, 1 MiB UTF-8 output). Byte-ingestion adapters must reject duplicate keys before object construction. Existing compiler/replay hash behavior is preserved. The repository provides a deterministic reference and published schemas; it does not provide a production runtime or certification.

Canonical flow

invokeAgent(request_envelope, run_context)
  -> admit(exact profiles, actual features, implementation support)
  -> compile(packs, request, run_context) -> CompiledContext
  -> loop {
       planner(CompiledContext) -> Plan
       critic.verify(Plan) -> ok | replan | reject
       executor(Plan, ToolGateway) -> ToolEnvelope[]
       critic.score(step_results) -> accept | retry | replan | escalate
       consolidate(effects, evidence) -> memory_proposals
     }
  -> DecisionRecord
  -> ReplayPacket when sampled, failed, corrected, or promoted

Field invariants

Naming rules

Naming must stay consistent across examples:

Do not record the approval gate id as a policy rule id. Do not treat model-routing records as business decision records; routing decisions can appear in DecisionRecord.lineage, but the governed business outcome is still the DecisionRecord.

ApprovalMode remains required in the v1 ToolEnvelope for compatibility. ActionRisk is optional in v1 so existing consumers continue to validate; new adapters should emit both. Requiring the native vector in a future major envelope remains a candidate migration decision until telemetry shows that active capabilities have a conservative projection and consumers have a bounded upgrade path.

The provenance, context-admission, evidence-gate, and structured-omission fields are likewise additive in compiled-context.v1.schema.json: legacy producer payloads still validate, while the canonical reference compiler always emits them. Consumers should treat their absence as legacy/unknown, never as trusted or complete context.

Relationship to docs

• API Contracts explains the runtime flow and envelope examples.
• Context Pack explains the pack lifecycle and compiler contract.
• Decision Record explains replay, storage, validation, and audit semantics.
• Evaluation and Observability explains scorecards, replay datasets, and release gates.
• Improvement Loop explains replay cases, source-pressure closure, and gated learning.