Resolve once: a delivery reads each technique one time, and says what it cost

[m2ux]

Summary

When the server hands a worker its next piece of work, it decorates each step with a note saying
where each input the step consumes comes from. Building that note means reading every technique the
workflow binds, to learn which outputs each one declares — and the answer does not depend on which
step is being decorated. Only the step's position in the workflow does. So the whole scan was being
repeated once per step the delivery inlines: one observed call walked the technique catalog three
times, over a catalog that currently holds 184 files.

The scan now happens once for the whole request, and every step reads its position out of that one
index. Each delivery also says what it cost, and the batch benchmark reports two fan-out ratios that
were measured during the SOLID review but had nowhere to be seen from.

Work items W1, W2, W6 and the budget half of W4 of the delivery-cost epic #404. Subsumes stages 1, 2
and 4 of #269.

Resolve each technique once — W1

buildProducerIndex walks the workflow once and returns the producer list, the declared-variable
set, and a map from each step to its document-order position. provenanceContextFor reads one step's
view out of that index. buildProvenanceContext remains, as the single-step composition of the two,
which is what a lazy get_technique needs.

The decoration output is unchanged, and there are two independent checks that it is:

• A new test builds one index, reads three steps out of it, and asserts each context is
  field-for-field identical to what a per-step scan produces for the same step.
• The reference-walk snapshots over every workflow in the corpus are unmoved.

A second new test counts the loader reads behind both shapes. Three steps served from one index cost
exactly the reads of the index; three steps served by a scan apiece cost three times that. That is
the figure that regresses if the scan ever moves back inside the per-step loop.

Say what each delivery cost — W2

One line per delivery call, on the info channel:

• get_activity — the distinct techniques the producer scan resolved, the steps decorated from that
  one scan, the steps and resources bundled and how many of each collapsed to a marker, the
  characters drawn against the eager budget, and the response length.
• get_technique — the resolve work behind one step's decoration, the composed size, and what the
  response carried after any shared block collapsed.
• get_resource — the resource size and what the response carried.

This extends the technique_bundled / resource_fetched events #353 already writes, which report
per-item delivered and saved characters. What was missing was the per-request summary: how much
resolve work one call did, and what it spent against its budget.

Fan-out, reported and not gated — W6

Two things ride along with every operation inside a container. Rules declared on a root or group
TECHNIQUE.md reach every operation in that container, and inherited I/O entries reach every
operation that composes the contract. npm run bench:batch now reports both, warn-only:

fan-out (warn-only, nothing gates on these): 28 operations composed
container rules: 16504 chars over 72 entries, 8.3% naming the operation they arrive with (589 chars an operation)
inherited I/O: 26930 chars over 215 items, 1.4% templated by the receiving protocol (962 chars an operation)

Nothing fails on either figure, and that is deliberate. A container rule is meant to apply to
operations that do not name it, so a threshold would fail the corpus on its intended design. The
8.3% here corroborates the 8.9% the review measured over a full work-package walk — this run covers
three activities rather than all of them.

The bootstrap budget — W4's enforceable half

The definitions half of W4 is #439, which drops the whole-workflow-schema read from the bootstrap and
states a budget of 110,000 characters for everything fixed the orchestrator reads before deciding.
This branch measures the three deliveries that make up that content and asserts the total is inside
the budget. The figure is parsed out of the protocol text, so the number an agent is told and the
number enforced cannot diverge.

Measured on the corpus this branch points at: 100,273 of 110,000 — discover 5,602,
start_session 348, get_workflow 94,323. The operations bundle is 94% of what remains, and it is
what a future trim has to reach.

Scope of change

• src/utils/binding-provenance.ts — the index/position split.
• src/tools/workflow-tools.ts, src/tools/resource-tools.ts — build the index once per request;
  the three cost lines.
• src/utils/fan-out.ts (new), scripts/run-batch-benchmark.ts — the two ratios.
• tests/provenance-resolve-once.test.ts, tests/bootstrap-budget.test.ts (new).
• The corpus pointer moves to Startup weight: the bootstrap stops reading the definition schema, and the setup ceremony commits once #439's definitions, and the walk baseline is re-stamped for it.

No schema change. No response-payload change — the cost lines go to the log, not the wire.

Verification

• npx tsc --noEmit clean.
• Full suite: 995 tests, all passing (the one corpus-stamp failure from bumping the submodule is
  resolved by the re-stamp in this branch).
• All 24 guards pass.

Non-goals

• Eager-budget defaults and headroom, which stay as they are.
• Caching technique reads across requests. The scan is per-request by design: a corpus edit between
  two calls is visible to the second without invalidation logic.
• What a delivery re-sends. That is W7, W9 and W10, and they land on top of this.
• The running-dispatch signal that extends W2 towards the user rather than the log — that is
  orchestrator behaviour and lands with the corpus guidance.

Investigation detail

engineering/artifacts/planning/2026-08-02-delivery-cost-epic
— the status check against main with hot-path locations, the captured #269 body, and this epic's
sequencing plan with its baselines.