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: todo
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.

Task: ADR-0007 — the render port

id: CB-WP-0012-T03
status: todo
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.

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.