Compile a request into a bundle or a typed failure

The chapter that owns the implementation. A compiler here is a function from a request, a candidate pool and a policy to either a bundle or a typed failure, and it leaves a decision trace either way. The point of the trace is that a reader can disagree with a decision after the fact.

Run it

git clone https://github.com/ernanhughes/project-context-compiler.git
cd project-context-compiler
git checkout 8d8bd31a20788c4c3298dfdffac741c507211a58
npm ci
node src/cli.ts compile --request conformance/compiler-v1/mandatory-overflow.request.json --candidates conformance/compiler-v1/mandatory-overflow.candidates.json --policy conformance/compiler-v1/compiler-policy-v1.json

Node 22 or later. The command is offline and deterministic.

Expected outcome

The mandatory item was admitted, the budget was spent, and then the compile failed with a typed reason and the item that blocked it:

    "failure": {
      "schema_version": "project_context.compile_failure.v1",
      "request_id": "mandatory-overflow-req",
      "policy_version": "compiler-policy-v1",
      "reason": "INSUFFICIENT_BUDGET",
      "blocking_ids": [
        "mand-b"
      ],
      "budget_used": 2000,
      "budget_total": 4400,
      "diagnostic": "mandatory mand-b closure exceeds remaining budget"
    }

The trace records the decision for every candidate, with the reason code and the budget before and after:

      "entries": [
        {
          "candidate_id": "mand-a",
          "content_identity": "mand-a",
          "representation_id": "full",
          "decision": "ADMITTED",
          "reason_code": "admitted",
          "reason_detail": "mandatory",
          "priority_band": "MANDATORY",
          "relevance": 1,
          "marginal_cost": 2000,
          "dependency_closure": [],
          "pulled_in_by": [],
          "budget_before": 4400,
          "budget_after": 2400,
          "position": null
        }
      ]

The trace is the product

Two commands are enough to read the whole surface. version names the implementation:

context-compiler 0.3.0

And inspect runs one fixture at one budget and prints the admitted set with its token count and a content hash:

budget-slack/tight: success=true
admitted: ["instr-1","taskreq-1","useful-disc"]
tokens: 265 hash: 66beba878f7cdd5bb4c94dce2501820120978ad7c0e56bbc006166a4eab9a4a6

The hash is what makes the run checkable: the same inputs at the same budget have to produce the same content hash, or something moved.

Mechanism and limitations

Documented: the CLI surface and the schema versions are in src/cli.ts and src/core/index.ts; the trace projection is project_context.decision_trace.v2 and the failure schema is project_context.compile_failure.v1.

Observed: the run above. One request, one policy, one candidate admitted and one refused for a stated reason, with the budget accounted for at each step. inspect over two different fixtures produced different admitted sets and different hashes.

Not shown. The candidates and the policy are synthetic fixtures. A trace explains the compiler’s decisions; it does not show that the decisions were right, and the relevance field in the trace is a declared ordering, not a computed score. A content hash detects a change; it does not explain one. The compiler decides what can be assembled under a budget, and the chapter’s other question, whether the assembled context helps, is a different measurement.

Canonical source and the compiler’s core .