Tutorial 1: Ship your first Context Pack
Author a versioned Context Pack, compile it against an inbound request, and inspect the resulting CompiledContext.
By the end of this tutorial you will have a working Context Pack — pinned by version, with a policy bundle, a tool capability, a Decision Spec, and a memory policy — and you will have run the reference compiler against an invokeAgent envelope and read the resulting CompiledContext.
What we are building
A pack has ten layers. For this tutorial we’ll fill the minimum that produces a runnable compile: contract_meta, pack_meta, intelligence_refs, business_context, policy_layer, tooling_layer, decision_layer, memory_layer, evaluation_layer, tone_and_comms. See Context Pack for the full schema.
Every pack declares the runtime + ontology versions it requires. The compiler refuses to load a pack whose compatibility.requires is not satisfied.
{
"contract_meta": {
"contract_name": "ctxpack.support",
"contract_version": "2.0.0",
"issuer": "tenant_acme_prod",
"created_at": "2026-05-04T10:00:00Z",
"compatibility": { "requires": { "runtime": ">=2.0.0", "ontology": ">=4.2.0" } }
}
}The bundle owns the JsonLogic rules that the Policy Engine evaluates at every plane boundary.
{
"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"] },
"rationale": "Refunds require verified identity." }
]
}
}
],
"guardrails": { "must_refuse": [], "must_escalate": [], "redaction_rules": ["pan", "credit_card"] },
"approval_gates": []
}
}Capabilities declare their highest approval_mode. We’ll start with read_only to keep things safe.
{
"tooling_layer": {
"adapter_registry": [
{ "adapter_id": "adp_orders", "type": "OPENAPI", "endpoint_ref": "internal://orders",
"capabilities": ["lookup"], "approval_mode": "read_only" }
],
"permissions": [
{ "permission_id": "p1", "adapter_id": "adp_orders", "capability": "lookup", "allow": true }
]
}
}The capability classification is observe (no mutation). Both class and mode bound it. read_only
The reference TS module mirrors the spec. Run the harness to compile against a mock invokeAgent envelope and print the resulting CompiledContext.
npx tsx src/lib/contextos/test-harness.tsYou will see, in order: the materialized RunContext, the inbound invokeAgent envelope, the compiler stages, the CompiledContext with its manifests + runtime_controls, the stub Planner / Executor / Critic walk, and the final DecisionRecord.
The shape you should see (truncated):
{
"manifests": {
"policy_manifest": [{ "bundle_id": "POLICY_RETURNS_V4", "rule_ids": ["R_REFUND_REQUIRES_IDV"] }],
"tool_manifest": [{ "adapter_id": "adp_orders", "capabilities": ["lookup"] }],
"evidence_manifest": [{ "evidence_ref": "kg:order:ord_881#snapshot_kg_2026_05_03_T0930" }]
},
"runtime_controls": {
"must_refuse": [], "must_escalate": [],
"approval_gates_active": [],
"redaction_rules_active": ["pan", "credit_card"]
},
"budget_report": { "tokens_allocated": { /* per-bucket */ }, "tokens_used_at_compile": 42, "bucket_truncations": {} }
}Notice four properties:
tool_manifestlists only what yourpermissionsallow —Registry ∩ Permissions − Prohibitions.runtime_controls.redaction_rules_activecarries forward the guardrails from the pack.evidence_manifestis supplied by the caller (Knowledge Substrate retrieval), not invented by the compiler.budget_report.bucket_truncationsis always explicit — the compiler never silently drops content.
What’s next
Tutorial 2: Bind a destructive tool through the Tool Gateway - onboard adp_payments.issue_refund with approval_mode: destructive and a GATE_FINANCE_APPROVAL approval gate.