Context Pack

Author, validate, publish, compile, and replay the versioned Context Pack contract that drives the ContextOS Context plane.

Implementation GuideLast reviewed: 2026-05-09 Edit on GitHub

At a glance

Definition

A Context Pack is a signed, immutable JSON document identified as pack_id@semver. It is loaded by reference, compiled with a RunContext, and produces a CompiledContext.

invokeAgent.context_pack_refs[]
  -> Pack Registry
  -> Context Pack + resolved overlays
  -> ContextPackCompiler
  -> CompiledContext
       compiled_prompt
       manifests{policy,tool,evidence}
       runtime_controls
       budget_report

The pack is the unit of deployment for the Context plane. A runtime should refuse to execute governed work without a pinned pack reference.

What a pack controls

Concern	Controlled by
Which ontology and identity namespaces are valid	`intelligence_refs`
Which business facts and non-negotiables matter	`business_context`
Which policies, guardrails, redactions, and approvals apply	`policy_layer`
Which adapters and capabilities may be surfaced	`tooling_layer`
Which typed decisions can be emitted	`decision_layer`
Which memories can be recalled or proposed for write-back	`memory_layer`
Which score targets and release gates judge the run	`evaluation_layer`
Which communication constraints shape final text	`tone_and_comms`

What does not belong in a pack

Do not put this in a pack	Put it here instead
raw customer records	Knowledge Graph or evidence store, referenced by `evidence_ref`
secrets or live access tokens	credential vault and Tool Gateway token exchange
mutable conversation state	`RunContext`, session state, or runtime transcript
one-off operator notes	Feedback Store or memory candidate with provenance
unreviewed prompt edits	versioned pack change with replay and release gates
adapter implementation code	adapter service or MCP/A2A/OpenAPI server

The pack declares how runtime state may be used. It should not become a data dump.

Minimum viable pack

A useful MVP pack needs one workflow, one decision, one safe read tool, one governed write tool, one policy bundle, and one evaluator target.

MVP element	Example
Intent	`support.refund`
Primary entity refs	`Customer`, `Order`
Read tool	`adp_orders.lookup` with `read_only` mode
Write tool	`adp_payments.issue_refund` with `destructive` mode
Decision	`support.refund.execute`
Required evidence	identity verified, order lookup, policy evaluation
Replay artifact	request, pack version, graph snapshot, policy bundle, tool transcripts, evaluator set

Start here. Do not begin by modeling every workflow or every adapter.

Pack structure

The current schema has ten required top-level layers.

Layer	Purpose	Compiler output affected
`contract_meta`	artifact identity, issuer, compatibility	registry validation
`pack_meta`	tenant, environment defaults, TTL, data classification	compile defaults and tenancy
`intelligence_refs`	ontology, graph snapshot rule, CEID namespaces, embeddings	`evidence_manifest`, retrieval scope
`business_context`	business summary and non-negotiables	business context blocks
`policy_layer`	policy bundles, guardrails, approval gates	`policy_manifest`, `runtime_controls`
`tooling_layer`	adapter registry and permissions	`tool_manifest`
`decision_layer`	`DecisionSpec` entries	decision checkpoints and DecisionRecord shape
`memory_layer`	memory TTLs, write classes, consent gates	memory recall and write proposals
`evaluation_layer`	evaluator targets and release gates	scorecards and promotion checks
`tone_and_comms`	communication constraints	final response shaping

Layer contracts

`contract_meta`

Use this for artifact-level compatibility.

{
  "contract_name": "ctxpack.support",
  "contract_version": "1.0.0",
  "issuer": "tenant_acme_prod",
  "created_at": "2026-05-09T00:00:00Z",
  "compatibility": {
    "requires": {
      "runtime": ">=1.0.0",
      "ontology": ">=1.0.0"
    }
  }
}

Rules:

Rule	Reason
`contract_name` must be stable.	Consumers pin by identity and version.
`contract_version` tracks schema compatibility.	It is separate from `pack_meta.pack_version`.
`issuer` must name the publishing tenant or authority.	The registry needs an audit owner.
`compatibility.requires` must be explicit.	Old runtimes must fail closed.

`pack_meta`

Use this for deployable pack identity and environment defaults.

{
  "pack_id": "ctxpack.support",
  "pack_version": "1.0.0",
  "tenant": {
    "tenant_id": "tenant_acme_prod",
    "name": "Acme Support"
  },
  "environment_defaults": {
    "language": "en",
    "timezone": "Asia/Kolkata",
    "currency": "INR",
    "region": "ap-south-1"
  },
  "ttl_seconds": 86400,
  "data_classification": "INTERNAL"
}

Rules:

Rule	Reason
`pack_id@pack_version` is immutable.	Replay and rollback depend on fixed artifacts.
`tenant.tenant_id` must match invocation tenancy unless explicitly shared.	Prevents cross-tenant pack leakage.
`ttl_seconds` controls cache freshness, not mutability.	Expired cache should refetch the same version.
`data_classification` constrains export, trace, and tool behavior.	Prevents low-trust surfaces from receiving restricted data.

`intelligence_refs`

Use this to pin the meaning layer.

{
  "ontology": {
    "namespace": "ont.support",
    "version": "1.0.0",
    "entity_types": ["Customer", "Order"],
    "relationship_types": ["order_belongs_to_customer"]
  },
  "knowledge_graph": {
    "snapshot_pin_rule": "alias:prod"
  },
  "identity_layer": {
    "ceid_namespaces": ["customer", "order"]
  },
  "embedding_keys": ["support_orders_v1"]
}

Rules:

Rule	Reason
Ontology version must exist in the target environment.	Entity meaning must be stable at compile time.
Graph reads can use aliases; replay must resolve to fixed snapshots.	Live reads and replay have different freshness requirements.
CEID namespaces must cover every subject in the `DecisionRecord` `subject_ids` field.	Audit needs stable subject identity.
Embedding keys are optional but must be versioned when used.	Retrieval changes can alter decisions.

`business_context`

Use this for durable business constraints, not transient instructions.

{
  "summary": {
    "what_we_do": "Post-purchase customer support",
    "who_we_serve": ["customers"],
    "differentiators": ["fast, policy-compliant resolution"]
  },
  "non_negotiables": [
    "never promise a refund before policy verification",
    "never disclose payment details in final customer messages"
  ]
}

Rules:

Rule	Reason
Keep it short.	This layer competes for the business context budget.
Prefer constraints over slogans.	The Compiler can only enforce concrete guidance.
Do not duplicate policy.	Policy belongs in `policy_layer`; business context explains intent.

`policy_layer`

Use this for deterministic rules, guardrails, approval gates, and decision bindings.

{
  "policy_bundles": [
    {
      "bundle_id": "POLICY_RETURNS_V4",
      "priority": 10,
      "policy_dsl": {
        "language": "jsonlogic",
        "rules": [
          {
            "rule_id": "R_REFUND_REQUIRES_IDV",
            "applies_to": { "intent": "support.refund" },
            "if": { "==": [{ "var": "request.context.identity_verified" }, true] },
            "then": {
              "allow": true,
              "requires": ["order_lookup"]
            },
            "else": { "allow": false, "reason": "Identity not verified; refund path blocked." },
            "decision_binding": "support.refund.execute",
            "rationale": "Refunds require verified identity."
          },
          {
            "rule_id": "R_HIGH_VALUE_REQUIRES_APPROVAL",
            "applies_to": { "intent": "support.refund" },
            "if": {
              "and": [
                { "==": [{ "var": "user.role" }, "support_agent"] },
                { ">": [{ "var": "request.context.refund_amount" }, 3000] }
              ]
            },
            "then": {
              "allow": true,
              "approval_mode": "destructive",
              "requires_approval_gate": "GATE_FINANCE_APPROVAL"
            },
            "decision_binding": "support.refund.execute",
            "rationale": "High-value refunds require finance approval."
          }
        ]
      }
    }
  ],
  "guardrails": {
    "must_refuse": ["refund_without_identity"],
    "must_escalate": ["fraud_signal_high"],
    "redaction_rules": ["pan", "credit_card"]
  },
  "approval_gates": [
    {
      "gate_id": "GATE_FINANCE_APPROVAL",
      "when": { ">": [{ "var": "request.context.refund_amount" }, 3000] },
      "required_approver_role": "finance_lead",
      "ttl_seconds": 7200
    }
  ]
}

Rules:

Rule	Reason
Guardrails are evaluated before ordinary policy.	Refusals and escalations must override local permissions.
Every `decision_binding` must resolve to `decision_layer.decision_specs[]`.	Policy and typed decisions cannot drift.
Every `requires_approval_gate` must resolve to `approval_gates[]`.	The Orchestrator needs a concrete gate to freeze evidence and route approval.
Policy may constrain a tool but must not create a new capability.	Capability comes from `tooling_layer.adapter_registry`.
Rules should include `rationale`.	Operators need to understand why a policy fired.

`tooling_layer`

Use this to declare adapters and the permissions that expose their capabilities.

{
  "adapter_registry": [
    {
      "adapter_id": "adp_orders",
      "type": "OPENAPI",
      "endpoint_ref": "internal://orders",
      "capabilities": ["lookup"],
      "approval_mode": "read_only"
    },
    {
      "adapter_id": "adp_policy",
      "type": "INTERNAL",
      "endpoint_ref": "internal://policy",
      "capabilities": ["eval"],
      "approval_mode": "read_only"
    },
    {
      "adapter_id": "adp_payments",
      "type": "OPENAPI",
      "endpoint_ref": "internal://payments",
      "capabilities": ["issue_refund"],
      "approval_mode": "destructive"
    }
  ],
  "permissions": [
    {
      "permission_id": "p_orders_lookup",
      "adapter_id": "adp_orders",
      "capability": "lookup",
      "allow": true
    },
    {
      "permission_id": "p_policy_eval",
      "adapter_id": "adp_policy",
      "capability": "eval",
      "allow": true
    },
    {
      "permission_id": "p_issue_refund",
      "adapter_id": "adp_payments",
      "capability": "issue_refund",
      "allow": true,
      "requires_approval_gate": "GATE_FINANCE_APPROVAL",
      "arg_constraints": {
        "amount_inr": { "min": 1, "max": 50000 },
        "idempotency_key": { "required": true }
      }
    }
  ]
}

Rules:

Rule	Reason
Capabilities are declared on adapters; permissions expose them.	Keeps tool inventory separate from workflow authorization.
`approval_mode` is the maximum risk the adapter can produce.	The Compiler filters tools above `RunContext.safety_mode`.
Write-class capabilities must require idempotency.	Retries must not duplicate side effects.
`endpoint_ref` must point to a registry entry, not a raw secret.	Runtime credentials are exchanged by the Tool Gateway.
Tool schema validation happens at the Gateway.	The model must not be trusted to call tools correctly.

`decision_layer`

Use this to bind the workflow to typed decisions.

{
  "decision_specs": [
    {
      "decision_key": "support.refund.execute",
      "version": "1.0.0",
      "owner_role": "support_ops",
      "required_evidence": ["identity_verified", "order_lookup", "policy_eval"],
      "allowed_outcomes": ["approved", "denied", "escalated"],
      "approval_mode": "destructive",
      "decision_right": "execute",
      "inputs_schema_ref": "schema://decision.support.refund.execute.inputs.v1",
      "outputs_schema_ref": "schema://decision.support.refund.execute.outputs.v1"
    }
  ]
}

Rules:

Rule	Reason
Every governed workflow needs at least one `DecisionSpec`.	Otherwise the runtime returns free-form text.
`required_evidence` must be satisfiable by tools, policy, request context, or graph retrieval.	The Critic must be able to verify before commit.
`allowed_outcomes` must be closed.	Audit and evaluation need comparable outcomes.
`approval_mode` must be at least as strict as any effect the decision can produce.	A low-risk decision cannot authorize a high-risk tool.

`memory_layer`

Use this to declare recall and write-back rules.

{
  "memory_policy": {
    "tier_ttls": {
      "working": "1h",
      "episodic": "24h",
      "semantic": "365d",
      "durable": "1825d"
    },
    "write_classes_allowed": ["evidence_link", "preference", "decision_outcome", "correction"],
    "consent_gating": {
      "pii_write_back_allowed": false
    }
  },
  "promotion_thresholds": {
    "auto_promote_confidence": 0.95
  }
}

Rules:

Rule	Reason
Recall promoted memory only.	Captures and candidates are not trusted context.
Write-back should produce proposals, not direct durable facts.	Memory needs review, consent, and contradiction checks.
PII write-back should default to false.	Consent gates must be explicit.
Promotion thresholds belong in the pack.	Runtime behavior must be replayable and reviewable.

`evaluation_layer`

Use this to make release and runtime quality measurable.

{
  "eval_targets": [
    {
      "intent": "support.refund",
      "policy": 1.0,
      "utility": 0.9,
      "latency_p99_ms": 3000,
      "safety": 1.0,
      "economics_cents_per_decision": 1.5
    }
  ],
  "release_gates": [
    { "metric": "policy", "max_delta": 0 },
    { "metric": "safety", "max_delta": 0 },
    { "metric": "economics_cents_per_decision", "max_delta": 0.25 }
  ]
}

Rules:

Rule	Reason
Every intent needs score targets.	A pack cannot be improved if success is undefined.
Release gates must include policy and safety.	Utility gains cannot buy policy regressions.
Cost and latency targets should be per decision or intent.	Global averages hide workflow regressions.

`tone_and_comms`

Use this for response style and communication constraints.

{
  "voice_attributes": ["clear", "neutral"],
  "do": ["cite policy", "explain approval status"],
  "dont": ["promise outcomes before approval", "expose internal rule IDs to customers"]
}

Rules:

Rule	Reason
Keep communication rules subordinate to policy.	Tone must never override Trust-plane controls.
Separate operator-facing and customer-facing constraints when needed.	Internal audit language should not leak into customer messages.
Do not hide decision uncertainty.	The final answer should reflect gate state and evidence status.

Binding graph

The pack must form a connected graph. These bindings are mandatory for governed work.

policy_layer.policy_bundles[].rules[].decision_binding
  -> decision_layer.decision_specs[].decision_key
 
policy_layer.policy_bundles[].rules[].then.requires_approval_gate
  -> policy_layer.approval_gates[].gate_id
 
tooling_layer.permissions[].adapter_id
  -> tooling_layer.adapter_registry[].adapter_id
 
tooling_layer.permissions[].capability
  -> selected adapter_registry[].capabilities[]
 
decision_layer.decision_specs[].required_evidence
  -> request context | policy eval | tool result | evidence manifest | graph retrieval

If any edge is missing, the pack should fail validation before publication.

Runtime resolution order

The Compiler resolves a pack deterministically.

Order	Stage	Output
1	load pinned `pack_id@semver`	immutable pack document
2	verify signature and compatibility	accepted or refused pack
3	apply declared environment overlay	resolved pack view
4	resolve ontology, graph snapshot, and identity namespaces	intelligence scope
5	evaluate guardrails and policy bundles	`policy_manifest`, active controls
6	compute tool surface from registry and permissions	`tool_manifest`
7	retrieve evidence and recall promoted memory	`evidence_manifest`, memory blocks
8	allocate token budgets and assemble buckets	`compiled_prompt`, `budget_report`
9	emit runtime controls	`must_refuse`, `must_escalate`, approvals, redactions

The model receives compiled output. It does not receive permission to reinterpret the pack.

Compiled output

The pack compiles into a CompiledContext.

This is the actual output of the reference compiler for the pack above, the support_agent role, refund_amount: 4200, and safety_mode: destructive — the same scenario the playground below starts from. Evidence carries one block per retrieved ref (five here; ev_1–ev_4 elided for brevity).

{
  "compiled_prompt": {
    "system": "You are an agent governed by ContextOS...",
    "developer": "Honor the policy_manifest, tool_manifest, runtime_controls, and required_evidence at every step.",
    "task": "Handle: \"Refund order ord_881 for INR 4200.\" (intent=support.refund).",
    "context_blocks": [
      { "block_id": "biz_summary", "bucket": "business", "priority": 90 },
      { "block_id": "pol_0", "bucket": "policy", "priority": 80 },
      { "block_id": "pol_1", "bucket": "policy", "priority": 80 },
      { "block_id": "tool_0", "bucket": "tool", "priority": 70 },
      { "block_id": "tool_1", "bucket": "tool", "priority": 70 },
      { "block_id": "tool_2", "bucket": "tool", "priority": 70 },
      { "block_id": "ev_0", "bucket": "evidence", "priority": 60 },
      { "block_id": "mem_0", "bucket": "memory", "priority": 50 },
      { "block_id": "session", "bucket": "session", "priority": 40 }
    ]
  },
  "manifests": {
    "policy_manifest": [
      {
        "bundle_id": "POLICY_RETURNS_V4",
        "rule_ids": ["R_REFUND_REQUIRES_IDV", "R_HIGH_VALUE_REQUIRES_APPROVAL"]
      }
    ],
    "tool_manifest": [
      { "adapter_id": "adp_orders", "capabilities": ["lookup"] },
      { "adapter_id": "adp_policy", "capabilities": ["eval"] },
      { "adapter_id": "adp_payments", "capabilities": ["issue_refund"] }
    ],
    "evidence_manifest": [
      { "evidence_ref": "kg:order:ord_881#snapshot_kg_2026_05_03_T0930" }
    ]
  },
  "runtime_controls": {
    "must_refuse": ["refund_without_identity"],
    "must_escalate": ["fraud_signal_high"],
    "approval_gates_active": ["GATE_FINANCE_APPROVAL"],
    "redaction_rules_active": ["pan", "credit_card"]
  },
  "budget_report": {
    "tokens_allocated": {
      "business": 1500,
      "policy": 1800,
      "tool": 1500,
      "evidence": 400,
      "memory": 1500,
      "session": 2200
    },
    "tokens_used_at_compile": 171,
    "tokens_used_by_bucket": {
      "business": 23,
      "policy": 50,
      "tool": 17,
      "evidence": 58,
      "memory": 13,
      "session": 10
    },
    "bucket_truncations": {}
  }
}

Required properties:

Property	Why it matters
`policy_manifest`	explains which rules shaped the run
`tool_manifest`	bounds what the Planner and Executor may use
`evidence_manifest`	supports `DecisionRecord` `evidence_refs`
`runtime_controls`	makes guardrails executable
`budget_report`	exposes truncation and context pressure

Compile it yourself

The example above is static. The widget below runs the actual reference compiler against the canonical support pack — the same ContextPackCompiler documented here, executed on every knob change. Change an input and watch the policy manifest, tool surface, runtime controls, budget report, and the deterministic compiled_context_hash recompile:

Set identity_verified to false and the refund path’s guard rule flips.
As a support_agent, push refund_amount past 3000 and GATE_FINANCE_APPROVAL activates with a destructive approval mode.
Lower safety_mode to read_only and adp_payments.issue_refund drops out of the tool surface — the compiler refuses to surface an adapter whose approval mode exceeds the run’s ceiling.
Starve the evidence budget and the bucket truncates visibly, never silently.

intent

identity_verified

refund_amount (INR)

> 3000 trips GATE_FINANCE_APPROVAL

user.role

safety_mode

evidence budget (tokens)

400 — lower it to force bucket truncation

CompiledContext

compiling…

The hash is the point: identical inputs always produce the same compiled_context_hash, which is what makes a run replayable. Change one input and the hash moves.

Versioning

Treat pack versions as contract versions. The question is not “did JSON parse?” but “can existing invocations, replay packets, and operator expectations still hold?”

Change	Version class	Examples
metadata only	patch	typo in description, non-runtime documentation, owner note
constrained behavior	minor	stricter threshold, additional redaction, new evaluator target, additional read-only evidence source
expanded or changed behavior	major	new write capability for existing intent, removed capability, changed DecisionSpec outcome set, changed ontology semantics, changed required evidence
unsafe or ambiguous	reject until redesigned	permission without adapter, policy binding missing decision spec, destructive capability without approval gate

Guidelines:

New versions are immutable; never rewrite ctxpack.support@1.0.0.
Runtime compatibility is checked through contract_meta.compatibility.requires.
Deprecation is a registry state, not a mutation of the pack.
Rollback means re-pin a prior version and replay golden runs.

Environment overlays

Overlays may exist, but they must be declared and auditable.

Allowed overlays:

Overlay	Example
endpoint reference	staging `internal://orders-staging`, prod `internal://orders`
policy threshold tightening	lower refund threshold in high-risk region
locale and currency default	`en-IN`, `INR`, `Asia/Kolkata`
evaluator threshold tightening	stricter latency or policy target in production

Disallowed overlays:

Overlay	Why
grant a capability absent from base pack	bypasses review
lower the declared approval-mode maximum	weakens Trust-plane controls
change DecisionSpec outcomes silently	breaks audit and replay
swap ontology namespace without version bump	changes meaning
insert raw secrets	violates credential boundary

Overlays can constrain. They should not expand power.

Validation gates

Validation should fail before publication, not during a live run.

Gate	Checks
schema	valid against `context-pack.v2.schema.json`; required layers present
referential integrity	adapters, capabilities, gates, decision bindings, evidence names resolve
policy	no unreachable critical rule, no unsatisfiable approval gate, priority conflicts resolved
risk	no tool above allowed approval mode, no destructive capability without gate, no missing idempotency
tenancy	tenant, endpoint refs, graph snapshots, and memory policies are scoped
replay	golden cases compile to stable manifests and budget reports
evaluation	score targets and release gates exist for every pack intent
security	no secrets, no raw PII dumps, no unrestricted tool surface

CI checklist

For every pack change:

Parse and validate JSON Schema.
Validate all internal references.
Compare generated tool_manifest against expected minimal surface.
Compile golden requests.
Replay prior incident and correction cases.
Run policy, safety, utility, latency, and cost evaluators.
Review diff by layer.
Sign and publish only after gates pass.

Publishing lifecycle

draft
  -> linted
  -> reviewed
  -> signed
  -> published
  -> pinned in environment
  -> observed in runs
  -> promoted or rolled back

State	Meaning
`draft`	authoring only; never used by runtime
`linted`	schema and local references pass
`reviewed`	architecture, security, data, and evaluation reviewers signed off
`signed`	content hash and issuer signature attached
`published`	immutable registry entry exists
`pinned`	environment references this version
`deprecated`	still resolvable for replay; not allowed for new traffic
`revoked`	blocked for new execution; retained for audit with reason

Full example

{
  "contract_meta": {
    "contract_name": "ctxpack.support",
    "contract_version": "1.0.0",
    "issuer": "tenant_acme_prod",
    "created_at": "2026-05-09T00:00:00Z",
    "compatibility": {
      "requires": { "runtime": ">=1.0.0", "ontology": ">=1.0.0" }
    }
  },
  "pack_meta": {
    "pack_id": "ctxpack.support",
    "pack_version": "1.0.0",
    "tenant": { "tenant_id": "tenant_acme_prod", "name": "Acme Support" },
    "environment_defaults": {
      "language": "en",
      "timezone": "Asia/Kolkata",
      "currency": "INR",
      "region": "ap-south-1"
    },
    "ttl_seconds": 86400,
    "data_classification": "INTERNAL"
  },
  "intelligence_refs": {
    "ontology": {
      "namespace": "ont.support",
      "version": "1.0.0",
      "entity_types": ["Customer", "Order"],
      "relationship_types": ["order_belongs_to_customer"]
    },
    "knowledge_graph": { "snapshot_pin_rule": "alias:prod" },
    "identity_layer": { "ceid_namespaces": ["customer", "order"] },
    "embedding_keys": ["support_orders_v1"]
  },
  "business_context": {
    "summary": {
      "what_we_do": "Post-purchase customer support",
      "who_we_serve": ["customers"],
      "differentiators": ["fast, policy-compliant resolution"]
    },
    "non_negotiables": [
      "never promise a refund before policy verification",
      "never expose payment details in customer messages"
    ]
  },
  "policy_layer": {
    "policy_bundles": [
      {
        "bundle_id": "POLICY_RETURNS_V4",
        "priority": 10,
        "policy_dsl": {
          "language": "jsonlogic",
          "rules": [
            {
              "rule_id": "R_REFUND_REQUIRES_IDV",
              "applies_to": { "intent": "support.refund" },
              "if": { "==": [{ "var": "request.context.identity_verified" }, true] },
              "then": {
                "allow": true,
                "requires": ["order_lookup"]
              },
              "else": { "allow": false, "reason": "Identity not verified; refund path blocked." },
              "decision_binding": "support.refund.execute",
              "rationale": "Refunds require verified identity."
            },
            {
              "rule_id": "R_HIGH_VALUE_REQUIRES_APPROVAL",
              "applies_to": { "intent": "support.refund" },
              "if": {
                "and": [
                  { "==": [{ "var": "user.role" }, "support_agent"] },
                  { ">": [{ "var": "request.context.refund_amount" }, 3000] }
                ]
              },
              "then": {
                "allow": true,
                "approval_mode": "destructive",
                "requires_approval_gate": "GATE_FINANCE_APPROVAL"
              },
              "decision_binding": "support.refund.execute",
              "rationale": "High-value refunds require finance approval."
            }
          ]
        }
      }
    ],
    "guardrails": {
      "must_refuse": ["refund_without_identity"],
      "must_escalate": ["fraud_signal_high"],
      "redaction_rules": ["pan", "credit_card"]
    },
    "approval_gates": [
      {
        "gate_id": "GATE_FINANCE_APPROVAL",
        "when": { ">": [{ "var": "request.context.refund_amount" }, 3000] },
        "required_approver_role": "finance_lead",
        "ttl_seconds": 7200
      }
    ]
  },
  "tooling_layer": {
    "adapter_registry": [
      {
        "adapter_id": "adp_orders",
        "type": "OPENAPI",
        "endpoint_ref": "internal://orders",
        "capabilities": ["lookup"],
        "approval_mode": "read_only"
      },
      {
        "adapter_id": "adp_policy",
        "type": "INTERNAL",
        "endpoint_ref": "internal://policy",
        "capabilities": ["eval"],
        "approval_mode": "read_only"
      },
      {
        "adapter_id": "adp_payments",
        "type": "OPENAPI",
        "endpoint_ref": "internal://payments",
        "capabilities": ["issue_refund"],
        "approval_mode": "destructive"
      }
    ],
    "permissions": [
      {
        "permission_id": "p_orders_lookup",
        "adapter_id": "adp_orders",
        "capability": "lookup",
        "allow": true
      },
      {
        "permission_id": "p_policy_eval",
        "adapter_id": "adp_policy",
        "capability": "eval",
        "allow": true
      },
      {
        "permission_id": "p_issue_refund",
        "adapter_id": "adp_payments",
        "capability": "issue_refund",
        "allow": true,
        "requires_approval_gate": "GATE_FINANCE_APPROVAL",
        "arg_constraints": {
          "amount_inr": { "min": 1, "max": 50000 },
          "idempotency_key": { "required": true }
        }
      }
    ]
  },
  "decision_layer": {
    "decision_specs": [
      {
        "decision_key": "support.refund.execute",
        "version": "1.0.0",
        "owner_role": "support_ops",
        "required_evidence": ["identity_verified", "order_lookup", "policy_eval"],
        "allowed_outcomes": ["approved", "denied", "escalated"],
        "approval_mode": "destructive",
        "decision_right": "execute",
        "inputs_schema_ref": "schema://decision.support.refund.execute.inputs.v1",
        "outputs_schema_ref": "schema://decision.support.refund.execute.outputs.v1"
      }
    ]
  },
  "memory_layer": {
    "memory_policy": {
      "tier_ttls": {
        "working": "1h",
        "episodic": "24h",
        "semantic": "365d",
        "durable": "1825d"
      },
      "write_classes_allowed": ["evidence_link", "preference", "decision_outcome", "correction"],
      "consent_gating": { "pii_write_back_allowed": false }
    },
    "promotion_thresholds": { "auto_promote_confidence": 0.95 }
  },
  "evaluation_layer": {
    "eval_targets": [
      {
        "intent": "support.refund",
        "policy": 1.0,
        "utility": 0.9,
        "latency_p99_ms": 3000,
        "safety": 1.0,
        "economics_cents_per_decision": 1.5
      }
    ],
    "release_gates": [
      { "metric": "policy", "max_delta": 0 },
      { "metric": "safety", "max_delta": 0 }
    ]
  },
  "tone_and_comms": {
    "voice_attributes": ["clear", "neutral"],
    "do": ["cite policy", "explain approval status"],
    "dont": ["promise outcomes before approval", "expose internal rule IDs to customers"]
  }
}

Failure modes

Failure	Runtime behavior
`context_pack_refs[]` contains `ctxpack.support` without version	refuse invocation
pack signature missing or invalid	refuse invocation
runtime does not satisfy `compatibility.requires`	refuse invocation
ontology version missing	fail compile before model call
policy `decision_binding` missing from `decision_specs[]`	fail validation before publish
permission references missing adapter or capability	fail validation before publish
destructive capability lacks approval gate	fail security review and validation
required evidence cannot be resolved	Critic returns `replan`, `reject`, or `escalate`
bucket truncates silently	compiler bug; release gate fails
replay produces different manifest for pinned inputs	block promotion and open incident

Operational metrics

Metric	Why it matters
compile success rate by pack version	catches invalid packs and environment drift
compile latency p95/p99	pack complexity can slow every request
tool-surface size by intent	large surfaces increase planning and safety risk
policy rule activation rate	detects dead rules and unexpected policy shifts
bucket truncation rate	shows context pressure and missing compression
required-evidence resolution rate	predicts DecisionRecord quality
replay determinism rate	measures audit reliability
release-gate pass rate	shows whether improvements are actually safe
rollback time	measures operational readiness

Refresh and invalidation triggers

A pack version should be re-reviewed or superseded when any referenced dependency changes.

Trigger	Required action
`POLICY_BUNDLE_UPDATED`	rerun policy lint, golden replay, and approval-gate checks
`ONTOLOGY_UPDATED`	verify entity types, relationships, CEID namespaces, and evidence mappings
`ADAPTER_SCHEMA_UPDATED`	rerun tool schema validation and arg-constraint tests
`DECISION_CATALOG_UPDATED`	verify bindings, outcomes, and required evidence
`MEMORY_POLICY_UPDATED`	rerun recall/write-back and consent checks
`EVALUATOR_UPDATED`	replay golden set and compare score deltas
`MODEL_CONFIG_UPDATED`	replay representative cases before promotion

Schema and references

Schema: Context Pack JSON Schema v2
TypeScript reference: src/lib/contextos/types.ts (ContextPack)
Compiler reference: src/lib/contextos/compiler.ts
Compiler output schema: CompiledContext JSON Schema v1
Runtime envelopes: API Contracts
Replay packet schema: ReplayPacket JSON Schema v1
Decision binding: Decision Catalog
End-to-end MVP: Quickstart

The JSON Schema and TypeScript type are reference artifacts for this documentation repo. Production runtimes should treat published pack versions, schema validation, registry signatures, and replay gates as the operational source of truth.

Common misconceptions

Misconception	Correction
A Context Pack is a prompt template.	It is the contract that compiles into a prompt, manifests, controls, and budget report.
A pack can be edited in production.	Published versions are immutable; changes create a new version.
Tool capability means permission.	Capability describes what an adapter can do; permission describes what this workflow may use.
Policy belongs in the prompt.	Policy belongs in `policy_layer` and is evaluated outside model code.
Memory write-back is automatic learning.	Write-back creates proposals governed by memory policy, consent, and promotion.
Replay only needs the prompt.	Replay needs request, pack, graph snapshot, policies, tool transcripts, evaluator set, and model config.