Primitive Contract (Normative)

Status: normative for OSS v1.x producers and consumers.

This document defines the four execution primitives that integrations must use and preserve:

• IntentRequest
• GateResult
• TraceRecord
• Runpack

Within a major version, these contracts are backward-compatible.

Onboarding Surface Contract

These file locations and command roles are part of the public OSS onboarding contract:

• .gait.yaml: additive repo-root policy file for gait init and gait check
• .gait/config.yaml: project defaults loaded by gait gate eval unless --no-config is set
• gait.yaml: regress fixture config written and consumed by gait regress init|add|bootstrap|run
• gait policy *: explicit policy authoring commands that remain supported for custom file paths, including gait.policy.yaml
• gait regress *: deterministic regress workflow commands; regress add is a convenience path over the same fixture semantics as regress init
• gait trace: observe-only wrapper for integrations that already emit Gait trace references
• gait trace verify: shipped trace verification command
• gait doctor --json: install-safe diagnostics for a clean writable directory; repo-only checks are additive and appear only in a Gait repo checkout

Onboarding JSON obligations:

• gait doctor --json MUST remain truthful for the installed-binary lane and MAY add fields such as onboarding_mode or per-check scope only additively.
• gait doctor --json MAY add machine-readable binary provenance fields only additively, including binary_path, binary_path_source, binary_version, and path_binary_path when the invoked executable differs from the PATH-resolved gait.
• gait init --json and gait check --json next_commands MUST be executable in the environment they are emitted for, or MUST include an explicit repo/fetch step in the command text.

Canonical migration notes:

• Policy DSL stays on the shipped repo-root contract: schema_id, schema_version, default_verdict, optional fail_closed, optional mcp_trust, and rules.
• Draft proposal keys such as version, name, boundaries, defaults, trust_sources, and unknown_server are not alternate supported syntax; they return deterministic migration guidance instead.
• The canonical CLI surface is gait mcp verify and gait capture --out ...; draft proposal spellings such as gait mcp-verify and gait capture --save-as ... are not separate commands.

Intent + receipt continuity conformance profile:

• docs/contracts/intent_receipt_conformance.md

Versioning and compatibility rules

• Producers MUST emit schema_id and schema_version for every primitive.
• Producers and consumers MUST treat schema_id and schema_version as contract selectors.
• Required fields for a schema version MUST NOT be removed or renamed without a major version change.
• Semantic changes to required fields MUST NOT occur without a version bump.
• Optional fields MAY be added in minor/patch versions if consumers can ignore unknown fields safely.

Standard Relationship Envelope (`relationship`, optional)

Purpose: emit graph-ready topology without changing required primitive contracts.

Fields (all optional):

• parent_ref (kind, id)
• entity_refs[] (kind, id)
• policy_ref (policy_id, policy_version, policy_digest, matched_rule_ids[])
• agent_chain[] (identity, role)
• edges[] (kind, from, to)

Producer obligations when present:

• MUST keep relationship additive-only within v1.x.
• MUST normalize digest identifiers to lowercase.
• MUST deduplicate and deterministically sort entity_refs and edges.
• MUST include relationship fields in canonical JSON hashing/signing naturally (no out-of-band exclusion).

Consumer obligations:

• MUST tolerate absence of relationship.
• MUST ignore unknown additive fields within relationship in v1.x readers.
• MUST NOT treat relationship presence as required for base primitive validity.

IntentRequest (`gait.gate.intent_request`, `1.0.0`)

Purpose: normalized tool-call intent at the execution boundary.

Required fields:

• schema_id
• schema_version
• created_at
• producer_version
• tool_name
• args
• targets
• context

Producer obligations:

• MUST normalize and canonicalize values before computing digests.
• MUST provide a non-empty tool_name.
• MUST provide context.identity, context.workspace, and context.risk_class.
• MAY include enterprise passthrough context when available:
  • context.auth_context (object)
  • context.credential_scopes (string array)
  • context.environment_fingerprint (string)
• MAY include context-proof linkage fields:
  • context.context_set_digest (sha256 hex)
  • context.context_evidence_mode (best_effort|required)
  • context.context_refs (string array of reference ids)
• SHOULD provide args_digest and intent_digest when available.
• MAY include script intent fields for compound workflows:
  • script.steps[] (ordered step list with per-step tool_name, args, optional targets, optional arg_provenance)
  • script_hash (sha256 hex over canonical script payload)
• SHOULD provide skill_provenance when execution originates from a packaged skill.
• SHOULD provide delegation when tool execution is delegated across agents:
  • requester_identity
  • delegation chain links
  • scope_class
  • token_refs

Delegation obligations:

• Producers MUST keep delegation.chain[] contiguous: each link's delegator_identity must equal the previous link's delegate_identity.
• Producers MUST terminate delegation.chain[] at delegation.requester_identity.
• Consumers MUST require signed token evidence for every claimed delegation hop before treating the chain as authorizing input.
• Consumers MUST enforce policy-required delegation scope against the delegation token's signed scope or signed scope_class, not against unsigned intent fields alone.

Consumer obligations:

• MUST fail closed for high-risk paths when intent cannot be evaluated.
• MUST NOT execute side effects on non-allow outcomes.
• MUST treat incoming context.context_set_digest, context.context_evidence_mode, and context.auth_context.context_age_seconds as transport claims only; context-required enforcement becomes authoritative only after gait gate eval binds a verified --context-envelope at the boundary.

Script mode semantics:

• Producers MUST keep script.steps[] order stable because evaluation and digesting are order-sensitive.
• Producers MUST keep step payloads canonicalizable (objects/arrays only, no non-JSON values).
• Consumers MUST evaluate script mode deterministically and preserve stable reason-code ordering.

GateResult (`gait.gate.result`, `1.0.0`)

Purpose: deterministic policy decision output for one IntentRequest.

Required fields:

• schema_id
• schema_version
• created_at
• producer_version
• verdict
• reason_codes
• violations

Verdicts:

• allow
• block
• dry_run
• require_approval

Producer obligations:

• MUST emit one of the allowed verdicts.
• MUST provide deterministic reason_codes ordering.

Consumer obligations:

• MUST execute tool call only when verdict is allow.
• MUST block execution on block, require_approval, dry_run, or evaluation error.

TraceRecord (`gait.gate.trace`, `1.0.0`)

Purpose: signed, auditable decision trace linked to intent and policy digests.

Required fields:

• schema_id
• schema_version
• created_at
• producer_version
• trace_id
• tool_name
• args_digest
• intent_digest
• policy_digest
• verdict

Producer obligations:

• MUST bind verdict to intent_digest and policy_digest.
• SHOULD include signature data for tamper-evident traces in production paths.
• SHOULD carry skill_provenance through from intent when present.
• SHOULD carry delegation_ref when delegated execution evidence is present.
• SHOULD include observed_at for runtime wall-clock incident reconstruction.
• SHOULD include event_id as a per-emission runtime identity.
• SHOULD include script-governance metadata when script mode is evaluated:
  • script, step_count, script_hash
  • composite_risk_class
  • step_verdicts[]
  • pre_approved, pattern_id, registry_reason
  • context_source when Wrkr enrichment is applied
• SHOULD include mcp_trust when MCP trust preflight or runtime trust enforcement is active so audits can see the local decision source and fail-closed reason codes.
• SHOULD carry context-proof linkage when present in intent:
  • context_set_digest
  • context_evidence_mode
  • context_ref_count
• MAY carry standardized graph links in relationship for topology queries.

Consumer obligations:

• MUST verify trace integrity when verification is required by policy/profile.
• MUST treat signature verification failure as non-passing.

Time-field semantics:

• created_at: deterministic decision timestamp used in cryptographic binding.
• observed_at: operational runtime timestamp for timeline reconstruction only.
• event_id: emission identity for retained runtime events; multiple events may share one deterministic trace_id.

Runpack (`gait.runpack.*`, `1.0.0`)

Purpose: deterministic artifact for replay, diff, verify, and regress.

Manifest schema:

• schema_id: gait.runpack.manifest
• schema_version: 1.0.0
• required fields:
  • schema_id
  • schema_version
  • created_at
  • producer_version
  • run_id
  • capture_mode
  • files
  • manifest_digest

Archive file contract:

• Runpack zip MUST contain:
  • manifest.json
  • run.json
  • intents.jsonl
  • results.jsonl
  • refs.json
• Runpack refs MAY include context-proof summary:
  • context_set_digest
  • context_evidence_mode
  • context_ref_count

Producer obligations:

• MUST generate byte-stable artifacts for identical inputs.
• MUST use RFC 8785 (JCS) canonicalization for digest-bearing JSON.
• MUST record capture_mode (reference default, raw explicit).
• SDK or wrapper helper inputs MAY omit digest-bearing fields only when a Go-authoritative normalization path computes them before artifact emission.

Consumer obligations:

• MUST verify manifest and file digests before trust.
• MUST treat missing required files or digest mismatches as verification failure.
• MUST treat duplicate ZIP entry names in artifact archives as verification failure.
• MUST treat context_evidence_mode=required with missing context_set_digest as invalid input.

PackSpec (`gait.pack.*`, `1.0.0`)

Purpose: unified artifact envelope for run and job evidence types.

Manifest schema:

• schema_id: gait.pack.manifest
• schema_version: 1.0.0
• required fields:
  • schema_id
  • schema_version
  • created_at
  • producer_version
  • pack_id
  • pack_type (run|job)
  • source_ref
  • contents

Producer obligations:

• MUST produce deterministic zip bytes for identical inputs.
• MUST include only declared files in contents.
• MUST use JCS canonicalization for digest/signature inputs.
• SHOULD include context_envelope.json in run packs when context evidence is present.

Consumer obligations:

• MUST verify declared file hashes and reject undeclared files.
• MUST treat schema mismatch and hash mismatch as verification failure.
• MUST treat duplicate ZIP entry names as verification failure even when one duplicate would otherwise satisfy the declared hash.
• SHOULD support legacy runpack/evidence verification during v2.4 compatibility window.
• SHOULD expose deterministic context drift summary in diff outputs when context data exists.

Command Contract Additions (v2.5)

• gait run record:
  • --context-envelope
  • --context-evidence-mode best_effort|required
  • --unsafe-context-raw
  • additive normalization helpers may be used by thin SDK/wrapper lanes so Go computes digest-bearing record fields before runpack emission
• gait regress run:
  • --context-conformance
  • --allow-context-runtime-drift
• gait pack diff --json:
  • emits context_drift_classification, context_changed, context_runtime_only_changes when applicable

Command Contract Additions (Script Governance)

• gait gate eval:
  • supports script-intent evaluation with deterministic step rollup metadata in JSON output
  • supports Wrkr enrichment via --wrkr-inventory
  • supports signed pre-approved fast-path via:
    • --approved-script-registry
    • --approved-script-public-key or --approved-script-public-key-env
  • missing approved-script verify keys disable fast-path in standard low-risk mode and fail closed in high-risk / oss-prod paths
• gait approve-script:
  • creates signed approved-script entries bound to policy digest + script hash
• gait list-scripts:
  • lists registry entries with expiry/active status

Session Chain Artifacts (`gait.runpack.session_*`, `1.0.0`)

Purpose: append-only, crash-tolerant long-running capture with verifiable checkpoints.

Artifacts:

• SessionJournal (gait.runpack.session_journal)
• SessionCheckpoint (gait.runpack.session_checkpoint)
• SessionChain (gait.runpack.session_chain)

Producer obligations:

• MUST append session events with monotonic sequence IDs.
• MUST link checkpoints using prev_checkpoint_digest.
• MUST preserve deterministic checkpoint runpack emission for identical journal prefixes.

Consumer obligations:

• MUST verify linkage continuity and per-checkpoint runpack integrity for chain-level trust.
• MUST treat missing checkpoints or digest-link mismatch as verification failure.

Interop contract for wrappers and sidecars

• Python wrappers and non-Python sidecars are transport/adoption layers.
• Go core remains authoritative for:
  • canonicalization
  • hashing/signing
  • policy evaluation
  • artifact verification
• Integrations MUST pass through these primitive contracts unchanged in meaning.

Enterprise consumer compatibility guard

• Enterprise control-plane consumers are downstream readers of OSS artifacts.
• Enterprise consumers MUST treat OSS primitive contracts as append-only within major v1.x.
• Enterprise consumers MUST ignore additive unknown fields.
• OSS MUST remain executable without any enterprise control plane dependency.

CI proof point:

• scripts/test_ent_consumer_contract.sh generates live v1.7 artifacts (runpack, trace, regress_result, signal_report) and validates deterministic enterprise-style ingestion plus additive-field tolerance.