G
Gait

ContextSpec v1

ContextSpec v1 Contract

Status: normative for v2.5+ producers and consumers.

ContextSpec v1 defines deterministic context evidence for run capture, gate enforcement, pack inspect/diff, and regress conformance.

Schemas:

  • schemas/v1/context/envelope.schema.json
  • schemas/v1/context/reference_record.schema.json
  • schemas/v1/context/budget_report.schema.json

Envelope Contract

Schema identity:

  • schema_id: gait.context.envelope
  • schema_version: 1.0.0

Required fields:

  • schema_id
  • schema_version
  • created_at
  • producer_version
  • context_set_id
  • context_set_digest
  • evidence_mode (best_effort|required)
  • records[]

Required record fields:

  • ref_id
  • source_type
  • source_locator
  • query_digest (sha256 hex)
  • content_digest (sha256 hex)
  • retrieved_at
  • redaction_mode
  • immutability (unknown|mutable|immutable)

Optional record fields:

  • freshness_sla_seconds
  • sensitivity_label
  • retrieval_params

Determinism Rules

  • Producers MUST canonicalize digest-bearing JSON with RFC 8785 / JCS.
  • context_set_digest MUST be deterministic for equivalent normalized records.
  • Record ordering MUST NOT change digest outcome.
  • Envelope validation MUST fail on digest mismatch.

Safety and Enforcement Rules

  • evidence_mode=required means missing/invalid context evidence blocks high-risk execution paths.
  • For gait gate eval, raw intent.context_set_digest, intent.context_evidence_mode, and context.auth_context.context_age_seconds claims are non-authoritative on their own.
  • Required context-proof enforcement at the gate boundary must be satisfied with a verified --context-envelope so Gait can verify the envelope and derive digest, mode, and freshness from it.
  • Accepted boundary bindings are:
    • gait gate eval --context-envelope
    • gait mcp proxy --context-envelope
    • gait mcp serve --context-envelope
    • gait mcp serve plus call.context.context_envelope_path, but only when the server was started with --allow-client-artifact-paths
  • Raw context evidence requires explicit unsafe operator intent:
    • gait run record --unsafe-context-raw
  • Gate policies may enforce:
    • require_context_evidence
    • required_context_evidence_mode: required
    • max_context_age_seconds

Stable reason-code surface:

  • context_evidence_missing
  • context_set_digest_missing
  • context_evidence_mode_mismatch
  • context_freshness_exceeded

Trace Binding Rules

Signed trace records may include:

  • context_set_digest
  • context_evidence_mode
  • context_ref_count

Tampering with context linkage fields MUST fail signature verification.

Wrkr Context Enrichment Contract

Wrkr enrichment is an optional local-file context source for gate matching.

Accepted inventory keys per entry:

  • tool_name
  • data_class
  • endpoint_class
  • autonomy_level

Normalization and matching rules:

  • tool names and class values are normalized to lowercase during load.
  • inventory is local-file only and does not require network.
  • policy matching keys are explicit:
    • context_tool_names
    • context_data_classes
    • context_endpoint_classes
    • context_autonomy_levels

Fail-closed expectations:

  • missing/invalid inventory blocks in high-risk contexts (risk_class high/critical) and oss-prod profile.
  • lower-risk contexts may continue without enrichment and should emit an explicit warning.

CLI Contract Examples

Capture with required context evidence:

gait run record \
  --input ./run_record.json \
  --context-envelope ./context_envelope.json \
  --context-evidence-mode required \
  --json

Fail-closed context policy evaluation:

gait gate eval \
  --policy ./policy.yaml \
  --intent ./intent.json \
  --context-envelope ./context_envelope.json \
  --json

MCP serve with a pinned context envelope:

gait mcp serve \
  --policy ./policy.yaml \
  --context-envelope ./context_envelope.json \
  --json

Pack inspect context summary:

gait pack inspect ./pack_<id>.zip --json

Deterministic context drift signal:

gait pack diff ./pack_a.zip ./pack_b.zip --json

Regression context conformance gate:

gait regress run --context-conformance --allow-context-runtime-drift --json

Compatibility Policy

  • ContextSpec v1 fields are additive to existing v1 contracts.
  • v1 consumers MUST ignore unknown optional fields.
  • v2.5 producers MUST remain backward-compatible with v1.0.0 envelope and record schemas.

Frequently Asked Questions

What is a context envelope?

A context envelope is a deterministic JSON artifact that captures what context material the model was working from, with configurable privacy modes (metadata, hashes, or raw).

When does context evidence fail-closed?

When policy requires context evidence for a high-risk action class and the evidence is missing, stale, or not supplied through a verified context envelope, the gate blocks execution with an explicit reason code. Raw intent.context_set_digest, intent.context_evidence_mode, and context.auth_context.context_age_seconds claims are stripped before evaluation unless a matching envelope is verified at the boundary.

What privacy modes are available?

Three modes: metadata-only (file names), hashes (SHA-256 digests), and raw (full content). Raw requires explicit unsafe flags.

How does context drift classification work in pack diff?

Pack diff separates semantic drift (different context inputs) from runtime-only drift (same context, different execution). This reduces noise in CI regressions.

Does context evidence add latency?

Context envelopes are computed during capture, not gate evaluation. The overhead is bounded by the configured evidence mode and budget limits.