Tutorial 1: Ship your first Context Pack

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 its required runtime/ontology versions. The registry/admission adapter must resolve and verify compatibility before supplying the pack; the reference compiler does not implement a general semantic-version resolver. Exact execution-profile/control revision negotiation is a separate additive contract and cannot silently fall back to weaker requirements.

{
  "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.

An applicable predicate error stops reference compilation with structured ContextCompileError. False/else remains normal policy logic; an error cannot become a permissive default. Structured identity_verified input still needs upstream authentication/verification.

{
  "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 native risk plus a conservative v1 mode. We will start with a no-effect lookup.

{
  "tooling_layer": {
    "adapter_registry": [
      {
        "adapter_id": "adp_orders",
        "type": "OPENAPI",
        "endpoint_ref": "internal://orders",
        "capabilities": ["lookup"],
        "capability_risks": {
          "lookup": {
            "effect": "none",
            "authority": "service",
            "reversibility": "read_only",
            "interaction": "api",
            "data_scope": "CONFIDENTIAL"
          }
        },
        "approval_mode": "read_only"
      }
    ],
    "permissions": [
      { "permission_id": "p1", "adapter_id": "adp_orders", "capability": "lookup", "allow": true }
    ]
  }
}

The capability class is observe. The risk vector establishes no mutation and the mode preserves v1 compatibility. read_only

Run the mock harness with a separately available TypeScript runner (tsx is not a declared repository dependency; use an explicitly reviewed/pinned runner in your environment), or use the existing Vitest command below for executable reference checks:

npx tsx src/lib/contextos/test-harness.ts

npx vitest run tests/compiler-hardening.test.ts tests/context-admission.test.ts tests/execution-workflows.test.ts

The harness prints the fixed Run Context, request, compiled summary, proposed Plan and a DEFERRED decision receipt. It uses the full canonical refund fixture with three declared tools; none is dispatched. The initial compile has unresolved policy.eval evidence and commit_allowed: false. The receipt reports zero tool calls, no approvals or tool lineage, and execution controls not evaluated. It does not fabricate successful effects or Critic scores. The composed execution-workflow tests exercise real validators with explicitly synthetic broker/store/provider facts; they still report runtime controls unevaluated.

An abridged display for the one-tool authoring example (illustrative counts, not the full fixture’s exact printed output):

{
  "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": { "policy": 12, "tool": 8, "evidence": 22 }, "tokens_used_at_compile": 42, "bucket_truncations": {} }
}

Notice four properties:

• tool_manifest lists only what your permissions allow — Registry ∩ Permissions − Prohibitions.
• runtime_controls.redaction_rules_active carries forward the guardrails from the pack.
• The caller supplies retrieved candidates; the compiler derives the admitted evidence_manifest, hashes, data-only treatment and evidence gates. Trusted upstream adapters must verify source/freshness labels; a hash does not authenticate a source.
• budget_report.bucket_truncations is always explicit — the compiler never silently drops content.