feat: state coverage as two targets and gate the three figures nothing read

[skyoo2003]

Summary

docs/coverage.md published 431 registered at the top and, further down, called the target "205 services, not 431" while describing those 431 as not targeted. Both halves were written honestly at different times, and the page could not be read as one claim. The summary table has been gated against the binary since Milestone 6; the target table under #the-target never was — so every number there could be wrong with CI green, and for a while every number there was.

This PR stops pretending there is one target, and gates the published figures that can be gated. One of them turned out not to be, and that story is below.

Changes

The two axes

Axis	Services	Governed by
Routing target	431 / 431 — met	leak-zero; every published model is registered
Serving target	205 — met	the demand study, sampled 2026-09-05
Registered and engine-served, outside the serving target	226	no depth promise

Routing is a safety property: a registered service is answered at localhost:4747, an unregistered one leaves the machine and bills a real AWS account. The only number that satisfies it is all of them. Depth is the separate, smaller promise — still 205, still where the demand study put it, because what that study refused was the cost of hand-building 283 services, and the codegen scaffold removed that cost without producing any evidence of demand.

A service count can no longer be read as a promise of fidelity, because the page no longer states one number that could carry both meanings.

New gates

1. TestPublishedTargetTableMatchesTheBinary — reads the two-axis table the way tierRow reads the tiers. The routing target is checked against plugin.DefaultRegistry.RegisteredServices(); the serving target is a decision rather than a measurement, so it is read from the page and used as the arithmetic the third row must satisfy. The table can neither drift from the binary nor contradict itself.

2. Binary size ceiling in CI — fails the build past 45 MiB. Measured: 35 MiB arm64, 37 MiB amd64, against a published 36.8 MiB on Apple Silicon.

3. Every registered service must initialize — main.go brings the long tail up with fatal=false, so a service that is registered but can no longer start degrades to a warning in a log nobody reads. budget_test.go fails on it. This is narrower than the startup gate originally intended here, for the reason below.

Stale figures

sync_test.go and contributing.md still said 194 vendored models; now 420. The 2026-09-06 churn measurement is unchanged but now says what it was taken at, since the diff a reviewer faces today is larger by roughly the same factor.

The startup gate: two wrong answers before the right one

Worth reading, because both mistakes were caught by something other than my own confidence.

First version — blind. It timed Registry.Construct, which only calls the factory, and every factory in the tree is a struct literal (return &S3Provider{}). It measured 84 µs against a 150 ms budget. The real cost is in Init, where S3Provider.Init does an os.MkdirAll and opens a SQLite database. Caught in local review; proven by injecting time.Sleep(8 * time.Millisecond) into Registry.Init:

--- PASS: TestOldGateConstructOnly          79µs        <-- unmoved by the injection
--- FAIL: TestRegisteredFleetComesUpWithinItsBudget      4.018s over a 2s budget

Second version — flaky. Rewritten to time Init the way main.go does, with a 2 s ceiling picked as ~14x the 141 ms it takes locally. CI failed it at 2.048 s on arm64: the runner is itself ~10x slower, so the entire margin was the machine and none of it was headroom.

Why raising the number does not fix it. The next run, on identical code, measured 1.414 s arm64 and 1.375 s amd64 — a 45% swing:

Run	arm64	amd64
8e95b52	2.048 s (failed)	canceled by fail-fast
17d2415	1.414 s	1.375 s
local	0.141–0.168 s	—

The regression worth catching — a provider that starts opening a file or a database per service — costs 1.2x to 2x, which is smaller than the runner's own variance. A ceiling that survives 45% noise cannot fail on a 2x regression. docs/coverage.md raised this objection before the gate was written; the gate overrode it and CI settled it.

Resolution. The correctness half is asserted on every run (all 431 must initialize). The timing is logged, and becomes an assertion only when a budget is named on a machine whose speed is known:

DEVCLOUD_STARTUP_BUDGET=300ms go test ./cmd/devcloud/

That is how the published figure is re-taken per release. The docs now say startup is measured and not gated, rather than claiming a gate that cannot fire.

Files Changed

File	Change
docs/coverage.md	Modified — two-axis target, runtime section rewritten
docs/demand.md, docs/README.md, README.md	Modified — depth vs routing wording
docs/contributing.md	Modified — 194 → 420 models, rewrap
cmd/devcloud/coverage_test.go	Modified — target-table gate
cmd/devcloud/budget_test.go	Added — fleet initialization gate + startup measurement
cmd/devcloud/sync_test.go	Modified — 194 → 420 models
.github/workflows/ci.yml	Modified — binary size ceiling
docs/testing/phase-4-review-followup.tdd.md	Added — full RED/GREEN record including both wrong answers
changes/unreleased/*.yaml	Added — changelog

Testing

go vet ./...                  # clean
gofmt -l ./cmd ./internal     # clean
go test ./... -count=1        # all packages ok

CI green on all 9 checks. cmd/devcloud's 0.0% statement coverage is expected and unchanged — that package asserts the binary's published claims against the registry it ships, not main.go's statements.

Known gaps, stated deliberately in docs/testing/phase-4-review-followup.tdd.md: startup is not gated in CI at all; the 45 MiB ceiling has ~8 MiB of slack; Init is exercised with default options only.

Related Issues

None. Follows #160, #161, #162.