121 unreachable, unchecked or wrongly-measured things, the gates that derive them, and the times those gates caught me

CLAUDE.md

@@ -410,6 +410,83 @@ whose regex carries the prefix by construction, and probe validity is **self-che
 must match its own route), so an unhandled converter reds the build. *A list of known cases is a list
 somebody stopped widening; a self-check is not.*
 
+**A seventeenth joined them on 2026-09-25: `services/api/test_schema_types_agree.py`** — does the
+committed `apps/web/src/api/schema.d.ts` describe the API this server serves? It is generated from the
+FastAPI spec and checked in, so it is a claim about the server sitting beside the client, and nothing
+was checking the claim: **500 of 947 paths, 541 of 1,021 operations**, 482 undeclared across 165 of 203
+path groups. **Filed as "SCHEMA-STALE", and the name was the first thing wrong with it** — stale
+implies it was once right, and that file and the `.gitignore` line hiding its input were written in the
+SAME commit, with the app carrying *fewer* route decorators today (1016 vs 1022) than when it was
+generated. *A stale-sounding name sends the next reader at the one action that cannot fix it*, which
+here was re-running the generator: `gen:api-types` read `src/api/openapi.json`, **a gitignored file**,
+so it regenerated from whatever dump sat on that machine, printed a green tick and wrote the same file.
+*"Regenerate the types" did not mean "read the server", and nothing said so* — the generator now dumps
+from `aec_api.main:app` into a temp file it deletes, so there is no persistent input left to be stale.
+**The rule is method-level and that is load-bearing:** `openapi-typescript` emits all eight verbs per
+path and marks the unserved ones `?: never`, so a path-level check passes a file declaring all 947 URLs
+and none of their verbs — which is the shape a half-regenerated file actually has. Both arms are
+mutation-proved, and the parser REFUSES a group it cannot classify rather than narrowing, because a
+silent narrowing reports that path as missing everything, reading as "regeneration due" instead of "the
+parser no longer understands this file".
+**The reason it went unseen is worth more than the fix: SEVEN audits here exempt this file by name**
+(`deadFieldScope`, `docComments`, `unfiledMap`, `deadFieldTyped`, `noRespelledShapes`,
+`test_route_reachability`, `test_file_sizes`), each for a good reason of its own. *Seven exemptions and
+no owner is how an artifact stops being checked by anybody.* And `test_route_reachability`'s is the
+opposite error, still instructive: it once counted this file as CLIENT code, so **29 routes were
+"called" by a generated file restating the server's own route table.** It is only ever a claim about
+the SERVER. **The item had also been parked on a decision that was not load-bearing** — commit
+`openapi.json`, or produce it in CI? — and needed neither answer, because an input that does not
+persist needs no home, and the agreement check needs no node and no artifact crossing jobs. *An item
+parked on a decision stays parked until somebody re-derives whether the decision was load-bearing.*
+**And the gate's own first draft asked its newest precondition from the wrong place.** The
+env-independence scan globbed `Path("src")`, relative to the working directory — which `run_tests.py`
+sets to `services/api`, while `ci.yml` invokes `python services/api/run_tests.py` from the repo ROOT.
+`rglob` over a missing directory yields nothing and raises nothing, so it would have reported a clean
+tree under CI and nowhere else. *A wrong question returns a confident number* — the same failure
+`test_scratch_ignored` paid for twice, in a file written days after reading its lesson. **A relative
+path is a question about where somebody stood**; it is anchored on `__file__` now, the population
+count is returned rather than discarded and floored beside the verdict, and the gate is run from both
+directories.
+**And its parity check was not a check.** A path group whose shape the group regex cannot match is
+absent from the parse *silently*, and is then reported as "served but undeclared" — a parser failure
+wearing the costume of a stale file — so the path keys are counted independently. The first draft
+counted them with a regex that **fails in exactly the same way the group regex does**, so a
+trailing-whitespace mutation broke both derivations and the counts stayed equal. *A parity check
+between two derivations that share a failure mode is not a check* — the crude count catches what the
+strict one cannot, and both mutations are now folded in and must be refused before the gate reports.
+
+**An eighteenth joined them on 2026-09-25: `services/api/test_verdict_coverage.py`** — does a screen
+that reads a verdict about a SUBSET also read what the engine could not evaluate? Five engines in one
+session returned a boolean beside a count of the unevaluated, and the boolean was meaningless without
+the count: `soft_clash.coordinated` over a page of the matrix (CLASH-TRUNC), `rent_scrub.clean` =
+`bool(ran) and not failed` with 1 of 7 checks run, `t12.tie_out.reconciles` against a reference derived
+from the answer, `covenants.clean`/`at_risk` on counts that are zero for want of inputs, and
+`sequence_clash.clean` over the activities that happened to have a date and a location. **Every one of
+those engines is careful** — each hands the caller the coverage and three attach a sentence saying why.
+*The defect is always in the consumer*, and four of the five had none, so nothing was wrong until
+somebody wrote one. **A subset verdict is derived structurally, not by name:** a dict key whose value
+is `bool(A) and (all(…) | not B)`, the guard being the author writing down that the subset can be
+empty. Matching coverage-ish WORDS instead returned 24 candidates of mostly unrelated senses — a
+sprinkler's coverage area, a `dry_run` flag — and *a rule that needs an exemption list is a rule whose
+population is wrong.* The structural form returns 5 with no exemptions, and **three of the five were
+instances nobody had found by hand.**
+**Four more drafts were wrong in ways only measurement showed.** Linking consumers by shared
+VOCABULARY cross-talked — a net-effective-rent card was reported as a `sequence_clash` consumer on
+`skipped`, `findings` — so the link is the call site of the owning client method, the only thing that
+claims *this file reads THIS response*. Treating `not_` as a coverage prefix matched `not_covered`, a
+prose note about a **different dimension**, which *would have blessed the one consumer the rule exists
+to catch*. Detecting a read as `.name` missed `const { not_applicable: notRun } = …` and called a
+careful card bare; widening to a bare word boundary then matched the English word "skipped" inside an
+unrelated prose string in the same file. *A detector keyed on one spelling cannot see the others, and
+one keyed on none sees everything.*
+**And mutating it found the limit it does not cover:** wrapping the coverage render in `if (false)`
+leaves the text in place and PASSES. It is a source-level check — the same bargain
+`test_route_reachability` makes for URL literals — and the complement is the consumer's own test,
+where `apps/web/src/proforma/rentRollQuality.test.ts` and
+`apps/web/src/proforma/covenantCard.test.ts` assert the coverage is *rendered*. Written down rather
+than discovered later, because a gate whose reach is assumed is the thing these eighteen entries are
+about.
+
 "Cite a gate only after `git ls-files` confirms it" is itself a rule held as prose, so it is now
 `services/api/test_claude_md_gates.py`: every backticked code file named here, in
 `docs/roadmap-directions.md` **and in `docs/roadmap.md`** must resolve to a tracked path — including
@@ -490,7 +567,7 @@ never contingent on the npm question.
 
 **What an agent working in `apps/web/src/viewer` should know.** **Seventy-nine** commits have touched that
 directory since extraction began on 2026-08-06, and `apps/web/src/viewer/app.ts` has gone from 5,064 lines to
-**2,442** — largely R39-DECOMP-VIEWER, which is the same decomposition the extraction plan asks for and is being
+**2,410** — largely R39-DECOMP-VIEWER, which is the same decomposition the extraction plan asks for and is being
 done here first. That is good and it is also divergence: every one of those commits is a change the swap will
 have to reconcile. So:
 
@@ -513,6 +590,19 @@ have to reconcile. So:
   The `wc -l` in the re-measure command above was also bare and would have waited on stdin — an instruction to
   verify that hangs is an instruction nobody runs twice.)*
 
+  *(**2,442 → 2,410 on 2026-10-12**, BATCH-DARK: the "Script this" window left for
+  `apps/web/src/viewer/tools/scriptThis.ts`, and this line moved in the same edit because
+  `services/api/test_claude_md_gates.py` refuses the build otherwise — which is the lesson above being
+  enforced rather than remembered. **And the commit count above was deliberately NOT re-measured, which
+  is the more useful half.** `git log --since=2026-08-06 -- apps/web/src/viewer | wc -l` returns **24**
+  in this cloud container, against the seventy-nine stated — because the checkout is **shallow** (two
+  grafts, 123 commits, oldest dated 2026-09-11), so `--since` cannot see past the graft and the small
+  number is an artefact of clone depth rather than a correction. *A re-measure that depends on the depth
+  of somebody's clone is not a measurement*, which is the same thing `services/api/test_gap_records.py`
+  had to learn when its replay used `git show` and failed only in CI. Check with
+  `git rev-list --count HEAD` and `test -f .git/shallow` before believing a history count here; the LINE
+  count is safe because `wc -l` reads the working tree.)*
+
 - **Keep shipping.** Blocking this roadmap for the extraction would make the extraction expensive and it would
   die. Landing viewer work here is the correct default.
 - **Prefer changes that survive the swap** — new behaviour behind the existing seams, rather than new coupling

apps/web/.gitignore

@@ -1,2 +1,9 @@
 *.local
+# Vestigial, deliberately kept. `gen:api-types` no longer writes here — it dumps the spec into the OS
+# temp directory and deletes it, because an input that persists is an input that can be stale, and this
+# very line is what hid that: the generator's one documented invocation read a file git was told to
+# ignore, so "regenerate the types" silently meant "re-read whatever dump is on this machine". See
+# apps/web/scripts/gen-api-types.mjs and services/api/test_schema_types_agree.py. The pattern stays so
+# that a leftover dump from before 2026-09-25 does not surface as untracked work in every lane's
+# `git status` — the residue problem services/api/test_scratch_ignored.py exists for.
 src/api/openapi.json

apps/web/index.html

@@ -25,6 +25,9 @@
         <input id="convert-input" type="file" accept=".rvt,.dwg,.nwc" hidden />
         <input id="ref-input" type="file" accept=".obj,.stl,.ply,.gltf,.glb,.pcd,.xyz,.las,.laz,.e57,.geojson,.json,.tif,.tiff,.gml,.citygml,.splat,.ksplat" hidden />
         <div id="workspaces" role="tablist" aria-label="Workspace"></div>
+        <!-- App-level, and OUTSIDE the tablist: one live subscription, not one per room, and a
+             focusable control inside a role="tab" button is invalid in both HTML and ARIA. -->
+        <div id="live-refused" hidden></div>
         <div id="next-action" hidden></div>
         <span class="grow"></span>
         <label id="persona-wrap" title="Gear the workspace to your role — every screen leads with what your job needs (all data stays reachable)">

apps/web/package.json

@@ -31,7 +31,7 @@
     "cap:sync": "cap sync",
     "mobile:android": "npm run build:mobile && cap sync android && cap open android",
     "mobile:ios": "npm run build:mobile && cap sync ios && cap open ios",
-    "gen:api-types": "openapi-typescript src/api/openapi.json -o src/api/schema.d.ts"
+    "gen:api-types": "node scripts/gen-api-types.mjs"
   },
   "dependencies": {
     "@mkkellogg/gaussian-splats-3d": "^0.4.7",

apps/web/scripts/bundle-budget.mjs

@@ -11,7 +11,69 @@ const DIST_ROOT = join(process.cwd(), "dist");
 const DIST = join(DIST_ROOT, "assets");
 // Budget in KB (Brotli). Set generously above the current shell so it catches regressions, not noise.
 // Bump this deliberately (with a note) when the shell legitimately grows.
-const BUDGET_KB = Number(process.env.BUNDLE_BUDGET_KB || 220);
+//
+// 220 -> 224 on 2026-10-12, and the measurement is the point. The shell hit **220.4 KB** and the
+// budget had never moved since it was written, so "generously above the current shell" had quietly
+// become a ceiling the shell was touching — the next change to land anywhere eager was going to pay
+// for everyone's growth. CODE-READY-DARK tipped it: `Web typecheck + test + build` was green through
+// b57490e7 and red on the next push, whose only bundle-affecting commit was that one.
+//
+// WHAT IT COST, measured per feature rather than assumed, by grepping the built chunks for a string
+// only each module emits:
+//
+//   viewer/tools/*            -> app-*.js        EAGER SHELL   (macroTool, codeReadiness, mepSection)
+//   portal/panels/*           -> jurisdictionPanel-*.js  lazy
+//   reportCenter + its helpers-> reportCenter-*.js        lazy
+//
+// So of four features shipped that day, two cost shell bytes and two cost none, and nothing told
+// anybody which — a tool added to the viewer rail is downloaded by every first-time visitor before
+// anything is interactive, while the same amount of code in a portal panel is not. **That asymmetry
+// is the useful finding here, not the number.** The honest alternative to this bump is to lazy-load
+// a tool's body behind its click, which is the right shape and is a pattern no tool in that
+// directory uses today (measured: zero `await import(` under `viewer/tools/`); applying it to two
+// of some forty tools would buy 0.4 KB and leave an inconsistency for the next reader to explain.
+//
+// **That last measurement went out of date the same day, and in the direction that flatters the
+// bump.** Re-measured 2026-10-12: FOUR files under `viewer/tools/` reach a module through
+// `await import(` in code — `analyseSection`, `modelReviewPanel`, `projectPanel`, `qaSection`, five
+// call sites between them — every one of them added by this gate refusing a build, not chosen. The
+// last one was refused TWICE: deferring only the rendering left the shell **five bytes** over, so
+// the fetch, the toast, the status line and the `showResult` call went behind the click as well.
+// So the alternative this paragraph declined on grounds of inconsistency is now what the newest
+// tools do, and the next legitimate growth should pay for itself the same way before this number
+// moves again.
+//
+// *A number that decays toward the conclusion it supports is the hardest kind to notice, because
+// nothing it predicts ever looks wrong.* Re-derive it, never read it — and count CODE, not
+// comments, because two of the six files that match the string only discuss it:
+//   grep -c "await import(" apps/web/src/viewer/tools/*.ts
+//
+// **224 -> 225 on 2026-10-12, later the same day, and the measurement is again the point.**
+// FIRM-RULES-OPTIONAL slice (2) wired four routes that had no client method between them --
+// `GET`/`PUT /projects/{pid}/rules` and `GET`/`PUT /firm/rules` -- so the parametric rule library
+// every check in the product evaluates could finally be AUTHORED from the product. Measured: the
+// shell went 223.8 -> **224.03 KB, which is 229,407 brotli bytes against a 229,376 limit: 31 over**
+// -- and all of it is the four client methods. The figure is given in BYTES because the display
+// rounds to one decimal and "224.0 KB" is what both a pass and a 31-byte failure look like; this
+// file's own history is a chain of numbers that rotted, so the one that decides a build is written
+// in the unit the decision is made in. The editor itself,
+// `portal/panels/ruleStandards.ts` at 310 lines, cost ZERO shell bytes, because `portal/panels/*`
+// is lazily imported by construction. That is the same asymmetry the paragraph above measures,
+// seen from the other side: the UI was free and the four fetch wrappers were not.
+//
+// **What was tried before bumping, and why it was rejected.** The `ApiClient` mixins are composed
+// eagerly, so a method on one is shell bytes by construction; the only way to defer these four
+// would be to expose a generic request helper for a lazy panel to build its own URLs on -- which
+// is more eager bytes, and it would put URL construction outside the one place
+// `services/api/test_route_reachability.py` and `apps/web/src/api/clientCallers.test.ts` both look
+// for it. *Contorting the API surface to fit a byte budget costs more than the byte budget is
+// worth*, and a client method per route is the shape two gates depend on.
+//
+// **The bump is 1 KB, not a round-up to a comfortable number.** 220 -> 224 was four, and what that
+// bought was four releases of nobody deciding anything; this leaves ~0.9 KB, which is roughly one
+// more feature's worth of client methods. The next thing to land eager should pay for itself by
+// deferring, the way the three tools above now do.
+const BUDGET_KB = Number(process.env.BUNDLE_BUDGET_KB || 225);
 
 // The eager shell = exactly what index.html loads up front: the entry chunk + its CSS, plus the split
 // first-party `app-*` chunk the entry statically imports. Everything else is a lazy chunk that doesn't