Context Pack Compiler

Reference Architecture

The Context Pack Compiler is the only Context-plane component. It turns the pinned Context Pack plus the materialized Run Context into the CompiledContext envelope that drives the Decision plane.

Definition

A pure pipeline (no I/O, no clock, no global state) with eight ordered stages. Reads pack + Run Context + caller-retrieved structured evidence + promoted memory; emits compiled_prompt, manifests, runtime_controls, budget_report, and context_ledger.

Why it exists

Without a single deterministic compiler, every team builds its own prompt assembly and drifts. The compiler centralizes the policy/tool/evidence/memory composition so the same pack on the same snapshot always produces the same CompiledContext — the property that makes replay possible.

The eight stages

1. Intent classification — confirm intent from Run Context against the Intent-Task Catalog.
2. Policy resolution — JsonLogic over the merged eval context (Run Context + request); fire applicable rules in priority order.
3. Tool surfacing — compute Registry ∩ Permissions − Prohibitions and apply approval-mode filter against RunContext.safety_mode.
4. Evidence normalization — caller supplies retrieved candidates and conflict markers; compiler verifies supplied hashes and labels source, integrity, freshness, and covered requirements. It does not call out.
5. Memory recall — caller supplies promoted memory only (never raw capture) with source refs and freshness.
6. Token budget allocation — distribute RunBudget.bucket_tokens across context buckets (default proportional split if not declared).
7. Bucket admission and assembly — assign instruction treatment, admit eligible evidence, pack each bucket by priority, and emit structured omissions — never silently.
8. Manifests + runtime controls — evaluate sufficiency and emit the admitted evidence_manifest, context_admission, conflict-aware per-decision evidence_gates, policy/tool manifests, and the audit ledger.

Inputs

• Pinned ContextPack
• RunContext with RunBudget
• InvokeRequest (intent, message, channel, locale, structured context)
• Caller-retrieved RetrievedEvidence objects with source, content, integrity, freshness, and satisfies
• Caller-retrieved EvidenceConflictMarker objects with evidence refs, affected requirements, status, and explicit resolution when closed
• Caller-supplied PromotedMemory objects with source lineage and freshness

Outputs

• CompiledContext envelope:
  • compiled_prompt (system, developer, task, context_blocks)
  • provenance-bearing compiled_prompt.context_blocks
  • manifests (policy_manifest, tool_manifest, admitted evidence_manifest)
  • runtime_controls (context_admission, evidence_gates, policy controls)
  • budget_report (allocations, usage, bucket_truncations, dropped_block_ids, structured omissions, warnings)
  • context_ledger (pack, request, policy, tool, admitted evidence, memory, budget, omissions, hash)

Implementation learning

The reference compiler should expose the audit information that operators need when a compile looks wrong. A downstream implementation surfaced three fields that are worth keeping in the canonical contract:

• context_ledger: a deterministic audit summary for the compile, including pack ref, request id, policy bundles, surfaced tool identifiers, evidence refs, memory refs, budget summary, and a content hash for replay comparison.
• budget_report.dropped_block_ids: the exact blocks that did not fit, grouped by bucket. A boolean bucket_truncations flag is useful for dashboards, but it is not enough for debugging.
• tool_manifest[].capability_metadata: per-capability metadata such as kind, risk_level, approval_mode, and derivation/source. This lets the Critic and UI explain why a tool was surfaced without re-reading the registry.
• ContextBlock.provenance: the source_refs, origin, integrity, freshness, instruction_treatment, inclusion_reason, and derived content_hash for every material block.
• runtime_controls.evidence_gates: the deterministic explanation of which required evidence is satisfied, unresolved, conflicted, or rejected; its sufficiency and commit_allowed fields are derived rather than model-authored.
• budget_report.omissions: structured block, bucket, reason, token, priority, and source-ref data shared with the context ledger.

These are diagnostics, not execution knobs. They should be produced by the compiler from pinned inputs and included in replay fixtures; callers should not mutate them after compile.

How it works (sequence)

RunContext + InvokeRequest + ContextPack
   ↓ classify intent
   ↓ resolve policies (JsonLogic, priority-sorted bundles)
   ↓ surface tools (registry ∩ perms − prohibits, approval-mode filter)
   ↓ normalize evidence + memory (hash, integrity, freshness, conflicts, lineage)
   ↓ admit blocks (control vs data_only; reject ineligible evidence)
   ↓ pack to bucket budgets (priority-sorted; structured omissions)
   ↓ evaluate evidence sufficiency (coverage + admission + conflict state)
   ↓ emit manifests + runtime_controls + budget_report + context_ledger
CompiledContext

Failure modes

• Pack pinned by name without version — refuse at the boundary, before the compiler runs.
• Enforced JsonLogic rule throws — fail closed and emit policy_eval_error. Only rules explicitly marked non_enforcing may be skipped with a diagnostic.
• Bucket assembly silently truncates — bug; the compiler must always set bucket_truncations[bucket] = true and list the dropped block IDs.
• Budget omission is recorded only as a block ID — diagnosability gap; emit a structured omission in both the budget report and ledger.
• Tool surfacing surfaces a capability whose approval_mode exceeds safety_mode — bug; safety filter rejected at write time.
• Tool manifest omits capability metadata — not a runtime failure, but a diagnosability gap; the Critic can still enforce modes, but operators lose the local explanation.
• Caller supplies a content hash that does not match the evidence or memory content — reject the compile visibly.
• Evidence is untrusted, stale, unknown-freshness, or omitted by budget — retain it in rejection diagnostics; it must not satisfy an evidence gate.
• Required evidence has an unresolved conflict — retain every branch and the marker, report sufficiency: insufficient, and block commit until a recorded resolution selects evidence.
• Legacy string evidence has no integrity metadata — normalize it as untrusted/unknown and emit a migration warning.
• Retrieval or memory block is emitted as control — bug; external content must remain data_only.

Operational concerns

• Cold-start latency dominated by pack registry hydration; cache aggressively.
• Token estimation discrepancy between compiler and runtime LLM tokenizer; reconcile at the edge.
• Compile-time idempotency: identical inputs must return identical outputs (tested via replay).
• Treat all caller-retrieved content as data. Verification raises factual integrity; it does not grant instruction authority.
• Alert when a required-evidence gate changes from closed to open after a pack/compiler change.
• Per-pack-version compile-time metrics for regression detection.

Evaluation metrics

• Compile-success rate per pack version.
• Compile-time p50 / p99.
• Bucket-truncation rate per bucket per intent (target: low; alert on spikes).
• Evidence-gate closure rate and unresolved requirements per decision key.
• Untrusted-evidence gate-satisfaction rate (target: zero).
• Stale/unknown/legacy evidence rejection rate and content-hash mismatch failures.
• Tool-surface size at compile time per intent (target: minimal sufficient set).
• Replay determinism (identical CompiledContext on identical inputs).

Reference implementation

src/lib/contextos/compiler.ts is a typed reference implementation of the pipeline. It is not the production runtime but mirrors the contract.