clay-borg/workplans/CB-WP-0012-render-port.md

id	kind	title	status
CB-WP-0012	product	Stage 1, second slice: the rendering port	todo

Purpose

Tier L, the declaration CB-WP-0011 deferred and owed.

structural tier  L   (INTENT stage 1 creates a new capability port)
chaos            d4 = 1  → no override
declared tier    L

Declaration 7 of 12 in the calibration window. The CHAOS gate earned its first caught entry last pass by rolling this same declaration down to S; this time it rolls nothing, so the pass runs at full weight — survey, adversarial review, ADR, then code. The hard gate applies as stated: no implementation code for the render capability exists before ADR-0007 is committed.

What this pass owes

INTENT stage 1 is "Inspectable 2D table — card/token/hand/relationship- graph visualization, drag-to-propose, debug inspector, hot-seat play." CB-WP-0011 shipped the debug inspector. This pass owes the other three, and the port they hang from:

cb-render-api
├── cb-render-null
└── cb-render-???        <- the survey's question

The leading constraint is AM-4a: 246,250 lines of 250,000, measured — 3,750 lines of headroom. Every candidate implementation of a 2D table is a five- or six-figure line count. This is the first capability in the project whose obvious implementation costs more than the entire remaining budget, so the survey's first duty is to establish whether that is a real obstacle or an artifact of how AM-4a is instrumented.

Task: survey the render port and its dependency cost

id: CB-WP-0012-T01
status: done
priority: high

Write research/CB-RES-0006-render-port.md.

Measure, do not estimate. The candidate line counts must come from the same method tools/dep-weight.py uses — cargo tree --edges normal over a real resolved graph, then counted .rs lines in vendored source — so the numbers are comparable to the AM-4a figure rather than merely adjacent. Last pass's correction was a hand-counted number; this pass has no excuse for one.

Measure the marginal cost, not the total. What AM-4a charges is what a candidate adds to a graph that already holds 23 crates. A candidate's headline size overstates its cost by whatever it shares with the base.

Cover at minimum: an immediate-mode GUI (egui/eframe), a 2D game framework (macroquad), the raw stage-2 stack (wgpu + winit), a CPU rasterizer (softbuffer + tiny-skia), a terminal UI (ratatui), and at least one option that is not a Rust toolkit at all.

Ask whether the instrument is right. If AM-4a's figure counts code that never reaches a shipped binary, the headroom it reports is wrong, and that has been true for every pass that has cited it. Check this before recommending any budget change — a survey that argues for raising a target it has not first audited is arguing in its own favour.

Done 2026-08-02. CB-RES-0006. Two findings, and they point opposite ways.

The cheapest candidate that opens a window (macroquad) costs a marginal 480,501 lines — 128× the headroom. egui + eframe costs 2,782,849. ratatui, the option one expects to be cheap, costs more than macroquad (1,067,013) because rustix pulls linux-raw-sys at 479,901 lines.

And AM-4a is mis-instrumented: 36.2% of the shipped-runtime figure (89,048 lines) is proc-macro crates — syn alone is 66,916 — which run in the compiler and never reach a binary. Real headroom is 92,798, not 3,750. Every pass that cited 3,750, this workplan's own Purpose included, cited a number wrong in the conservative direction.

The recommendation survives the correction: macroquad is still 5.2× over at 92,798. That was the condition for proposing the correction at all, and the correction is filed separately rather than bundled with the decision it would unblock.

Recommended: cb-render-api + cb-render-null + cb-render-html — emitted HTML/SVG/JS, marginal AM-4a cost zero, with cb-render-wgpu left to stage 2 where it becomes the interface's second use.

Task: adversarial review of the survey

id: CB-WP-0012-T02
status: done
priority: high

Step 2 of the inner loop, run against T01's recommendation rather than for it. The review must name, at minimum:

• what the recommended option cannot do that a windowed toolkit can, stated concretely rather than as a caveat;
• the failure mode of building the port around a single implementation when the second-use rule exists precisely to stop that;
• whether the survey's dependency argument would survive if AM-4a's target were simply wrong, i.e. whether the recommendation is load-bearing on a number the same pass proposes to correct.

A review that ratifies the survey without producing a control the survey lacked has not run.

Done 2026-08-02. challenge, response. Not approvable as written — four of six challenges conceded, and the survey's two main arguments replaced.

• C1: the survey concluded the sub-100k region was empty without measuring it. It is not empty. tiny-skia fits at 83,956; the real windowed floor is fltk at 140,079 — 1.5× corrected headroom, not 128×. "Two orders of magnitude" withdrawn.
• C1b, which the concession exposed: wgpu + winit is 1,741,979 marginal lines against a 250,000 target. AM-4a is incompatible with INTENT stage 2 — 7× the whole target — and has been since both were written. Raised for the maintainer, deliberately not decided here.
• C2: "marginal cost zero" was scored on an axis chosen to produce zero, and the same move already flattered sdl2/fltk. One acquisition rule now covers all three, and it raises two candidates' cost.
• C3: the survey contradicted itself on the second-use rule. cb-render-api and cb-render-null are withdrawn from this pass.
• C4/C5: six controls adopted as binding on ADR-0007 — a loopback token with a mutation-backed refusal test, JS barred from constructing commands, and the coverage gate crossing the language boundary.
• C6: the candidate measurements did carry a positive control (empty unlocated for all seven, verified). The C1 batch did not — it copied the measurement function without the guards — and was re-measured under them before being cited. The HTML row is relabelled 0 by construction, not by measurement.

Fidelity note: the review ran in the same session as the survey rather than a separate one, per this environment's standing instruction not to spawn agents unasked. It therefore inherits the author's sampling and is a lower bound on what a separate reviewer would find.

Note on tier: this pass no longer creates a capability port, which was its structural trigger for tier L. The declaration and its roll stand — a tier that changes because review shrank the work would be a function of the outcome. Recorded as the CHAOS window's second entry.

Task: ADR-0007 — the render port

id: CB-WP-0012-T03
status: done
priority: high

Record the decision, the rejected alternatives with their measured costs, and the controls the implementation must carry. No implementation code lands before this commits.

Done 2026-08-02. ADR-0007 — render to HTML, and do not declare the port yet. Five decisions, eight rejected alternatives with measured costs, six binding controls, and two items reserved for the maintainer: AM-4a's 7× incompatibility with stage 2, and whether the acquisition rule proposed by the pass that benefits from it is the right rule.

The hard gate held: no render implementation code existed before this commit.

Task: the port and its first implementation

id: CB-WP-0012-T04
status: todo
priority: high

cb-render-api plus cb-render-null and the implementation ADR-0007 chooses, delivering visualization, drag-to-propose and hot-seat play.

K13 binds here. The renderer consumes a Projection and can never feed back into validation; a drag that proposes a move must go through the same command path a CLI move takes. The inspector's coverage gate is the precedent for the control this needs.

Task: evidence

id: CB-WP-0012-T05
status: todo
priority: medium

evidence/CB-EV-0010-render-port.md. Carry the standing items: the falsifiable prediction from CB-EV-0009 §4 that the trailing-3 meta share drops to 0% this pass, SH-3 at 0.0% for a sixth pass, and whether tier L at full weight produced anything the rolled-down pass would have missed — the CHAOS window's second data point, and the first from a non-override.