Build the Context Pack Compiler: Eight Stages, One Typed Reference

A compiler becomes easier to operate when each stage answers a distinct question: which intent, policy, tools, evidence, memory, allocation, blocks and controls produced this context?

ContextOS keeps those eight logical stages in the typed ContextPackCompiler reference. They are boundaries to inspect and test, not a requirement to create eight files. The earlier independent tutorial implementation has been replaced because its local field shapes, implicit dependencies and policy shortcuts disagreed with that reference.

The canonical explanations are Context Pack Compiler, Context Pack and the execution contract. This repository is a typed reference and documentation site, not a deployed enterprise runtime.

Use the actual compiler interface

This repository-local wrapper uses the existing class and types. The caller supplies a validated pack, request, run context and recorded dependencies; it does not hide retrievers in an untyped ctx.deps field.

import { ContextPackCompiler } from "@/lib/contextos/compiler"
import type { CompileDeps } from "@/lib/contextos/compiler"
import type {
  ContextPack, InvokeRequest, RunContext, CompiledContext,
} from "@/lib/contextos/types"
 
export async function compileContext(
  pack: ContextPack,
  request: InvokeRequest,
  runContext: RunContext,
  deps: CompileDeps,
): Promise<CompiledContext> {
  return new ContextPackCompiler(pack).compile(request, runContext, deps)
}

CompileDeps accepts supplied evidence, evidence_conflicts and promoted_memory. Collection, retrieval, current identity/authority verification and protected storage are caller/runtime responsibilities. Supplying the same fixed dependencies is necessary for replay; injecting a live retriever alone does not make network results deterministic.

Stage 1 — intent classification

The reference uses the declared request.input.intent when present. Otherwise it applies a small deterministic message heuristic for refund, lookup/query or general query. It does not perform the catalog-membership rejection claimed by the old tutorial.

A deployment must validate allowed intents and input contracts at its ingress. An intent label identifies proposed work; it cannot authenticate the requester or authorize that work. Pin the catalog, request and relevant configuration for replay.

Stage 2 — policy resolution

The compiler builds an explicit evaluation context from intent, request context, user, agent and tenant. It evaluates applicable JsonLogic rules in declared bundle-priority order and preserves selected branches and obligations. A legitimate false predicate can select else; an inapplicable rule is not evaluated.

An applicable expression error rejects compilation with ContextCompileError, code policy_eval_error, stage policy_resolution, bounded bundle/rule identifiers and expression path. Its serialized message excludes raw request/predicate secrets and stack/cause details. It must not become false and select a permissive branch.

Compiler prohibition accumulation remains distinct from normalized business-rule precedence. A winning business allow cannot erase an independent denial, escalation, required approval or obligation. Do not add random decision IDs, ambient-time branching or silent defaults to policy decisions.

Stage 3 — tool surfacing

The reference constructs the permitted surface from registry, permissions and prohibitions, with native ActionRisk checks and the five v1 compatibility modes. Keep read_only, local_write, network, delegated and destructive unchanged; their projection is not the multidimensional risk model.

Do not derive a downgrade by matching a rule-name suffix, cast an undeclared field to any, or treat a surfaced tool as execute-time permission. Dispatch still needs current scoped authority, exact approval when required, active containment/credentials/data controls, external preconditions and reserved capacity. Provider-hosted tools and generated subprocesses need an admitted enforcement path too.

Stage 4 — evidence admission

The caller supplies retrieved evidence. The compiler normalizes provenance, integrity, freshness and instruction treatment, records rejections/conflicts and determines which admitted blocks can satisfy required evidence gates. Legacy strings remain accepted for compatibility as untrusted/unknown evidence; they cannot close a required gate.

An ID containing a snapshot substring is not proof of that snapshot. Resolve actual immutable source and content references, preserve current validity and conflicts, and supply trusted retrieval observations through the defined shape. Collection and retrieval must already obey actual recipient/processor, purpose, classification and retention requirements.

Stage 5 — promoted memory

The supplied canonical PromotedMemory uses memory_ref, content, source_refs and freshness, with optional hash and observed/valid-until timestamps. It is not the old tutorial’s application object with id, tier, text and promoted_at.

Raw capture is not promoted recall. The memory owner must verify current namespace ownership, readers, purpose, provenance and retention before delivery. Candidate storage is also governed. A past promotion cannot renew expired permission; corrections and deletion require copy-specific receipts across derived stores, caches, exports and delegation. Pending or externally unknown copies remain incomplete.

Stage 6 — token allocation

The compiler allocates the declared RunBudget context capacity to the canonical buckets: business, policy, tool, evidence, memory and session. Prompt roles such as system/developer are not extra ContextBucket enum values.

Context allocation is separate from the protected aggregate budget ledger. Runtime token/tool/replan/cost ceilings, current spent/reserved capacity and deadlines survive retries, children, reviewers and resume. Business refund amounts are separate currency/minor-unit constraints, not compute-cost limits. Do not grant a default fresh allowance because a dependency or checkpoint is missing.

Stage 7 — bucket packing

The reference packs prioritized blocks within allocation and records dropped block IDs, truncation flags, omission reasons and warnings. A required fact omitted for capacity cannot satisfy its gate merely because retrieval found it.

Inspect budget_report and context admission together. Do not silently remove required evidence or fabricate a successful manifest from pre-packing inputs. The reference uses approximate token accounting for context construction; a deployment needs its selected model’s tokenizer and trusted usage accounting where exact resource enforcement is required.

Stage 8 — manifests and runtime controls

The output contains compiled_prompt, policy/tool/evidence manifests, runtime_controls, budget_report and context_ledger. Prompt content is structured, including system/developer/task and context blocks; it is not a single untyped string.

Current typed producers include context_admission and evidence_gates controls. Preserve provenance for admitted and omitted data. Compilation can emit redaction, refusal, escalation and approval obligations; the result does not prove those controls were enforced, a credential was brokered, or a provider committed an effect.

Do not silently replace the legacy context-ledger hashing format with the new strict canonical-JSON digest domain. Compatibility bytes and execution-contract digests have distinct versioned purposes. An exact hash proves the hashed content, not the trustworthiness or current permission of its source.

Verify the boundaries

Run the repository’s existing tests while following the implementation:

rtk npx vitest run tests/compiler-hardening.test.ts tests/context-admission.test.ts tests/spec-reference-drift.test.ts

These check reference behavior, including policy-expression failure, native risk, evidence admission and contract consistency. They do not exercise a live identity provider, credential broker, sandbox, atomic store or external supplier. A stage-by-stage trace in a production implementation needs explicit instrumentation; this article does not claim the reference exports a separate hash for each stage.

Carry the compiled result into execution

An implementation admits exact control profiles and enabled feature requirements before dependent work. Unknown required versions or missing support block admission without demotion.

Durable work uses protected operation, approval and budget stores. A scheduled wake or resume rechecks current grant/ancestor revocation, approval, actual boundary/data controls, external preconditions and original shared budget under current worker fencing. A timeout cannot imply not-applied; reconcile using the provider’s declared recovery semantics before retry. Cancellation cannot prove stop or reversal.

Conformance combines useful positive work and required denials with current independently verified evidence for the actual workflow, implementation, release and environment. Passing compiler tests establishes reference checks; runtime controls remain unevaluated until their owners provide the required evidence.

What to read next

• Context Packs in Practice
• Context Engineering in Production
• End-to-End Refund Walkthrough