# Changelog

All notable changes to Massing. Releases are signed, auto-updating desktop builds
(Windows / macOS / Linux); the updater always serves the latest. Format loosely follows
[Keep a Changelog](https://keepachangelog.com/).

## Unreleased

### ROUTE-SHADOW — four routes were registered on a URL another route already owned

Starlette matches the **first** route whose path and method fit, so a second registration on the same
pair is not an override — it is dead code that looks live. FastAPI then builds the OpenAPI document
into a dict keyed by path and method, so the **last** registration is the one that gets described.
The server ran one handler and `/docs`, the OpenAPI JSON and `apps/web/src/api/schema.d.ts` all
described the other.

| URL | served | never ran |
|---|---|---|
| `GET …/drawings/plan.svg` | `routers/drawings.py::plan` | `routers/authoring_docs.py::plan_svg` |
| `GET …/drawings/sheet.svg` | `routers/drawings.py::sheet_svg` | `routers/authoring_docs.py::sheet_svg` |
| `GET …/drawings/sheet.pdf` | `routers/drawings.py::sheet_pdf` | `routers/authoring_docs.py::sheet_pdf` |
| `GET …/mep` | `routers/analysis.py::mep` | `routers/authoring_analysis.py::mep_summary` |

**Fixed — the MEP systems browser has never worked.** `apps/web/src/api/mep.ts` declared two shapes
for `/projects/{pid}/mep`: `mepSummary()` with `systems` as a **list** of per-system counts, and
`mep()` with `systems` as a **Record**. The inventory handler served, so
`apps/web/src/viewer/tools/mepSection.ts` read `s.systems.length` off a Record, got `undefined`, and
printed *"No distribution systems yet — add duct/pipe runs + fittings."* on every model that has ever
had one — then returned, hiding the by-discipline rollup, the fire-protection check and the sizing
checks below it. `/projects/{pid}/mep` now resolves to `mep_summary`, which is what the panel, the
client method and the published contract all already expected.

**Also fixed: the sheet parameters `apps/web/src/viewer/sheetSpecs.ts` was written to work around.**
That module records, from a measurement on 2026-08-09, that the rail sent `number`, `title` and
`scale` and the route dropped all three. It fixed the caller and diagnosed the cause as a caller
speaking a dialect the callee does not. The dialect was real and published: `number`, `title` and
`scale` are exactly the shadowed handler's parameters, which is what `/docs` describes for that URL.

**The decisions ran in opposite directions, and consumers is what decides.** The three drawing
handlers in `authoring_docs.py` went, because `drawings.py` serves a strict superset and the whole
client is built on it. The **serving** `/mep` handler went, because `energy.mep_inventory` had one
caller in the tree — that route — and its client method `api.mep()` had none at all. The engines stay
in `aec_data`, still tested, so publishing the ARCH-D titleblock sheet under its own URL remains
available as a product decision rather than a gap.

**Gated: `services/api/test_route_shadow.py`.** Derives every `(path, method)` the app holds by
walking FastAPI's deferred router placeholders; fails closed on any route object it cannot classify;
floors the walk's size and requires the four routers that carried the collisions to be present, so a
broken walk cannot report a clean tree in the words of a clean tree. It replays the four shipped
registrations (built here, not fetched from git, which CI's shallow checkout cannot do) and must find
**all four and nothing else**, and a walk narrowed to top-level routes must **miss** all four.

**The gate asks Starlette, not `==`.** The four shipped instances were identical path strings, so an
equality test would have found all four — but equality is a *precondition*, not the rule. Starlette
matches by regex, so `/projects/{pid}/drawings/{name}` registered before `/projects/{pid}/drawings/sheet.svg`
swallows it just as completely. Measured before widening: the live tree holds **0** of that
non-identical form, so using Starlette's own matcher costs no exemptions and no noise — it removes a
precondition rather than chasing a finding. What it buys is visible under mutation: a single misplaced
`/projects/{pid}/mep/{probe}` silently kills **eleven** MEP endpoints, and the widened rule names every
one while the equality version reports that tree clean. Its soundness rests on no route declaring a
`:path` converter, which is now asserted rather than assumed.

**FastAPI's own warning saw two of the four.** It keys on a duplicate *operationId*, built from the
function name plus the path, so it fired for `sheet_svg` and `sheet_pdf` — two handlers spelled the
same — and stayed silent for `plan`/`plan_svg` and `mep`/`mep_summary`. *A warning keyed on the name
cannot see a collision that is about the path*, and half a population reported confidently reads
exactly like all of it.

**Review found two ways the gate could still report clean, and both were preconditions I had not
written down.** It probed `{param}` with a plain segment, so an `:int`, `:float` or `:uuid` route
rejected its own probe and a duplicate on one came back clean — the first draft asserted only that no
`:path` converter existed, which is *asserting the one case you thought of, not the property*. And it
read a `prefix` attribute off FastAPI's deferred-inclusion placeholder; **this FastAPI has no such
attribute**, so it silently walked the un-prefixed router and two handlers colliding at a prefixed URL
passed. Every replay fixture used an empty prefix, so **no test in the file could have caught it**.
Both are now fixed at the source rather than patched: the walk takes FastAPI's own effective route
contexts, whose `path_regex` already carries the prefix, and probe validity is *self-checking* — every
probe must match the route it was built from, so an unhandled converter reds the build instead of
quietly shrinking the population. Two fixtures added (`:int` collision, prefixed collision), each
mutation-verified to red the right check.

**Why nothing went red.** Every MEP assertion in `services/api/test_mep_systems.py` calls the engine
`mep.mep_summary(m)` directly; not one goes through the route. *A test of the engine is not a test of
the door.*

**And the gate that would have named it misdiagnosed instead.** `apps/web/src/api/clientCallers.test.ts`
already held `mep` in `UNCALLED` — it had measured the method as callerless and frozen that. Removing
the method made its check fail with *"1 method(s) in UNCALLED now HAVE a caller: mep"*. An entry
leaves that set either because it gained a caller or because it stopped existing, and the message
asserted the first for both. The named repair happened to be right and the stated reason would have
sent a reader looking for a screen that does not exist; the two are now separate assertions, each
mutation-checked.

Everything below ships in the next release. **These were 34 separate `## Unreleased` headings**
until 2026-09-07 — one per change, each a peer of a real version — so the word had stopped
meaning anything as a heading and the file read as 34 pending releases rather than one. The
titles are unchanged and now sit at `###` beneath this, in the same order; no text was edited,
added or dropped in the fold.

### A wire type declared twice is a field no audit can see

`ClashResult.truncated` was returned by the server and read by nobody for months, and the reason was
never that anyone decided to ignore it: the clash panel had re-spelled the response shape, so no
property access resolved to the declared field and no type error, lint or unread-field audit could
reach it. Two more shapes were written out twice the same way — `Vital` and `LogisticsResource`, both
character-for-character copies of `api/types.ts`, one of them under a comment reading "as the API
returns it". Both now import the type they were copying.

A new check refuses the next **exact** copy: same type name and same member set. That is narrower
than the case above — a local shape that drops a field, as the clash panel's inline cast did, has a
different member set and is not caught. The narrowness is deliberate: a subset rule flags twenty
shapes here, eighteen of them deliberate narrowings, and gating it would need an exemption list.

### The Discipline Spine says how many spec sections it is NOT counting

The chain-coverage bars are computed over the *enforced* spec population — sections a withdrawal has
taken out of the chain are excluded, and correctly so: a withdrawn section is not an unpackaged one.
The card printed the enforced number and nothing else, so on a job with a void section its "18
specs" silently disagreed with the 21 in the spec register, with nothing on the page accounting for
the difference. It now reads "21 spec sections on the job · **3 withdrawn (excluded)**, so every bar
above is taken over 18", with the sections themselves in a disclosure below it. The server has always
returned both numbers for exactly this reason, and the submittal-log card has always rendered the
same caveat.

Two of the four bars, not all four: `sheets_specced_pct` divides by the drawing count and
`packages_costed_pct` by the package count, neither of which a withdrawn spec changes. The caveat
names the two it applies to.

### Sources & Uses shows the loan fees

The PDF's Sources & Uses itemises six rows; the on-screen table showed five. The missing one is the
origination points — real money, and invisible because its absence balances: the fee is folded into
Total uses and funded out of equity, so uses still equalled debt plus equity and every visible number
reconciled. On two points against a $13m loan that is $260k of the equity cheque with no line of its
own.

### The coordination matrix now counts the whole clash run, not the first page of it

A federated clash run returns two numbers: `count`, every interference it found, and `clashes`, the
first 200 of them. The Clash panel printed the first beside the list and used the second to build
the discipline-pair matrix — the screen a coordination meeting reads to decide which trades still
have to talk to each other.

That matrix is the one place this product makes a claim about what was *checked*, and it has a
third state for exactly this: a pair nobody ran is `untested`, never `clean`. Building it from the
page defeated that from outside. Every returned clash on a large model tends to belong to one or two
busy pairs, so a pair whose interferences all sat past the 200th arrived with no evidence at all —
and with every pair declared tested, it was reported **clean**. Measured on a 1,438-clash fixture
with 918 of them between architecture and MEP, none on the first page: the matrix said 100% pair
coverage, nothing untested, and called that pair clean.

Both federated paths now tally clashes per discipline pair over the *whole* run, where the full list
still exists, and the tally travels beside the page: the list is what a person clicks, the tally is
what a report may claim. Against an older server that truncates and sends no tally, the panel
declares nothing tested rather than guessing — those pairs read `untested`, which is what the third
state is for.

Two smaller things on the same screen. The list header counted the page while the summary above it
counted the run, so two different numbers sat under the word "clashes" with nothing saying a cap was
in play; it now reads "200 of 1438 clashes — click to inspect (list capped)". And a single-model run
that creates issues says when the cap is why fewer issues exist than clashes.

`truncated` was a field the server had always returned and nothing had ever read, which is how this
survived: the panel re-spelled the response shape inline rather than using the declared one, so no
type, lint or audit could see the omission. The shapes are now declared once in
`apps/web/src/api/clash.ts` and the audit pins them as read.

Review then found the same premise one level further down. The panel declared *every* pair of
discipline models tested, including each model against itself — and a federated run excludes
same-model overlaps by construction, because a beam meeting its own column is a joint, not a
coordination finding. So the diagonal was reported clean by a run that could not have looked at it.
It is now filtered on the model key, which keeps two distinct models that happen to share a
discipline label correctly counted as tested.

### Clicking a register pin on the model now opens its record

A pin on the 3D model is a register record's marker — an RFI, a punch item, an observation. Clicking
one selected the element it sits on and wrote a line to the status bar, and that was all: the record
the pin stood for had no way in. It now selects, reports, and opens the record.

The behaviour was already written down as shipped. `apps/web/src/pins/pins.ts` branches
topic-versus-record on click and explains why — *"a topic restores a saved viewpoint, a record opens
its register row"*. Only the first half was true.

Nothing new was designed for it. `apps/web/src/main.ts` has jumped to a record since the command
palette shipped, whenever a search hit is chosen; the pin now goes through that same
`jumpToRecord`, so there is one answer to "where does a record open" rather than two that drift.
The item had been filed as needing a UX decision on the strength of a grep over the viewer directory
finding no opener — there is none *there*, and the opener was one directory over.

Selection stays in the viewer rather than following the user across: coming back to the Model
workspace finds the element still highlighted.

The handler lives in `apps/web/src/viewer/pinOpen.ts` so the viewer's `app.ts` did not grow, and the
opener reaches the viewer as a required callback rather than an import — required so a dropped wire
is a compile error instead of a dead pin, injected so the viewer never reaches into the portal.

Three things review found, all real. A pin marker's click also reached the viewport, whose raycast
misses a DOM overlay and then clears the selection a few frames later — so the highlight the click
had just set was being undone; both marker kinds now stop the event. A rejected `selectByGuid` took
the record jump with it, although the record id came from the pin and not from the scene; selection
is best effort now, and says so rather than failing silently. And the jump waited on a fixed 500 ms
instead of the portal's own init — **there were three copies of that guess**, and all three now share
one wait that resolves when the portal is actually ready and reports when it cannot open at all.

That last fix created a fourth defect, which the next review round found. Making the portal's init
retryable turned every partial mutation on the way to a failure into reachable state: `init()`
reassigns its own root to the content pane and registers a window listener before it awaits the
first render, which can reject — so a retry would have nested a second shell inside the first and
added a duplicate listener. Making a failure recoverable makes every partial mutation on the way to
it reachable.

### The project's parcel boundary now draws on the model

Load a cadastral boundary on Feasibility → Massing and the lot line is available in the 3D viewer,
under Open ▾ → Site context. It is the same ring the building was sized against, not a second copy
loaded separately — the two cannot drift.

The roadmap carried this as "parcel overlays", which sounds like a drawing task, and both halves of
the drawing already shipped: the viewer draws OSM land-use parcels, and the server parses a real
cadastral boundary that sizes the building on the lot's true outline. What was missing sat one layer
down — nothing persisted the ring. The feasibility tab held it in a local variable and sent it
straight to the massing engine; a tab re-render dropped it, and no other screen could ask for it.

The ring is stored beside the parcel and tax keys it belongs with, through the merging write that
already serialises the property form against the feasibility tab. It is drawn in metres rather than
being re-projected through a lon/lat anchor, which is how a lot line ends up a continent from its
building.

Review then found the frame was wrong in a smaller, quieter way. A saved ring is shifted to its own
bounding-box *minimum*, so it lies wholly in the positive quadrant, while a generated massing model
is built around the origin — the lot line sat off the corner of its own building. It is now
recentred on the bounding-box **centre**, which is the anchor the massing generator already uses to
put the parcel in the building's frame. The test that claimed to pin the frame passed before and
after that fix, because its only fixture was a square centred on the origin and the translation was
a no-op on it.

And the save is now serialised per project. Selecting one parcel and then another fired two
independent writes; the project lock decides which lands last by arrival, not by which was chosen,
so the viewer could end up drawing a parcel the tab was not showing — and a select-then-clear pair
could resurrect a parcel the user had removed. Selecting a parcel with no project open now says so
instead of skipping the save silently.

The queue outlives one render of the tab, which is what makes it a queue: the feasibility tab
re-renders whenever the proforma does, including immediately after "Generate IFC model", and a queue
rebuilt at that moment cannot order the save that was already in flight across it.

**Saving the property no longer deletes the rest of it.** `PUT /projects/{pid}/property` preserved
one key across a write — the saved appraisal — and let the request body replace everything else. That
read as a merge for as long as the only caller was the property form, which reads the whole record,
edits it and sends it back. This change added a caller that sends the parcel boundary alone, and that
write took the address, the block and lot, the purchase price, the areas and every tax line with it.
The route now merges the body over the stored record: the body still wins where they overlap, so the
form can still edit, and an explicit null still clears, because what matters is a key omitted versus
a key sent as null.

The viewer also waits for a pending boundary save before reading the property back, so opening the
overlay straight after selecting a parcel no longer reports that none is saved.

### Four records called concurrency gaps open that the sweep had already closed

`services/api/test_rmw_sweep.py` reports *"43 ORM sites: 43 reasoned exempt or locked, 0 named
open"*. `docs/roadmap.md` still carried RMW-LOCKGAP and RMW-TOKEN as 🟡 **OPEN**, and
`docs/security/threat-model.md` still carried G-10 and G-12 as open gaps with a summary line reading
"**Four** sites remain open". All four are corrected against the code, each naming the pull request
that closed it and the date.

A stale OPEN is a work item, not a typo: the roadmap's ranking sends the next reader at it, the
threat model presents a reviewer with a live exposure, and RMW-TOKEN's entry had priced its fix as
"a migration (add the column, backfill, route both writers through a CAS)" — work nobody ever did,
because both of its sites closed with an advisory lock already in the tree and already serving the
gap next door. Half of that entry was wrong on the day it was written: `realestate.save_appraisal`
took its lock the day before.

`services/api/test_gap_records.py` now fails the build on the class. It derives the sites from the
sweep's own ledgers by AST and the records from both documents by indentation, and holds any record
that cites the sweep and reads as open to naming at least one still-open site. It replays the four
records as they shipped at `53cfa71a` — frozen under `services/api/tests/fixtures/gap_records/` —
and must re-find all four, and nothing else, before it may report a clean tree.

The first draft read those records out of git history instead of copying them. That works on a
full clone and not in CI, whose checkout is shallow, so the gate failed closed on every build. A
proof that an analyser finds anything cannot depend on the depth of somebody's clone.

Review found two more. The replay was evaluating those frozen records against today's ledger, so a
site that legitimately reopened would have red the build blaming the analyser for being right; the
statuses are frozen alongside the records now. And the gate's roadmap-marker list knew `✅ ◧ 🟡 ⭐`
but not `⛔`, `❌` or a struck-through code — 12 of 90 roadmap items were outside its population
entirely, reported as a clean tree in exactly the same words as a clean tree. A loose-versus-strict
parity check now reds the build on a marker it does not know, and found one of the three itself.

`services/api/test_roadmap_status.py` gained the self-tests it was missing. Its loop reads
`if not marked_open(code): PASS; continue`, so a `marked_open` that can never say yes sent every
registered item down the passing branch — measured by mutation: breaking its bullet regex with one
literal left every line green, the exit status 0, and the verdict *"every item with a measurement
agrees with its marker"* printed over nothing.

### The desktop IFC converter can now be interrupted — it runs in a child process the server kills

`from_ifc.convert`'s deadline is cooperative: checked between elements and every 4,096 entities.
That bounds a model that overran because it had a lot in it, and cannot reach the two costs outside
every checkpoint — `ifcopenshell.open`, one call whose time scales with file size and is paid in
full before the first check, and any single `create_shape` that never returns. On the desktop app,
where there is no Node runtime and the Python path is the only one, `edit_preview` passes
`timeout=120` on a synchronous route: a model that hit either cost held a request worker
indefinitely instead of returning the 503 the caller is written to expect.

The conversion now runs in a child process, and the parent kills it. The entry point re-enters
itself through an argv sentinel, so `sys.executable` is the bundle when frozen and the interpreter
when not — no `multiprocessing`, and therefore no `freeze_support()` to wire, which is what the
roadmap entry had recorded as the blocker for a fortnight.

Behaviour where nothing is wrong is unchanged: the child gets the caller's full budget and an
ordinary overrun still comes back from its own checkpoint, naming the phase it was in. The kill
fires five seconds later, so the outer bound is `timeout + 5s` rather than `timeout` — stated
plainly, because shortening the child's deadline to keep the bound exact would make the two
branches disagree about what the parameter means.

There is no in-process fallback. Spawning failures are not something anyone reports, so a fallback
would mean the conversion quietly went back to being uninterruptible while the reader still believed
it was bounded.

### The reachability gate was reading 708,650 characters of somebody else's product as evidence about ours

`_web_source()` — the blob both reachability gates ask "does any client call this route?" — included
`apps/web/src/vendor/**`: verbatim, unedited copies of `MassingCloud/massingifc` and
`MassingCloud/massing-pdf`, 83 files. A route leaf occurring there is a fact about another
repository. The blob already excluded the generated OpenAPI types for exactly that reason, and the
sentence simply had not been finished.

**It was not a theory; the consumer had written the defect down twice without naming it.** The
gate's own notes blame `/projects/{pid}/cost/calibration` on "85 hits of PDF-takeoff SCALE
calibration under `vendor/massingpdf/`, a different trade entirely", and its deterministic
regression fixture is a line lifted out of `vendor/massingifc/project-schema/coordination.ts`. The
diagnosis stopped at "a leaf that is also a common domain noun" — true, and one layer short, because
a vendored tree is a bulk supplier of exactly that noun. *Two symptoms written up separately are how
one cause stays unnamed.*

Measured: uncalled 57 → 59, nothing lost. Both routes that move —
`/projects/{pid}/project-package/contents` and `/projects/{pid}/workflow/{key}` — were already
frozen as **invisible** in `LEAF_COLLISION_BLIND`, so this finds no new debt; it converts two routes
the rule could not see into two it reports. **That is the direction the ratchet punishes**, which is
why nothing was going to drift into it unprompted, and it is also a third way out of the blind-spot
list that the list did not anticipate: not "it gained a caller" and not "it was renamed", but *the
text that vouched for it was deleted*.

The exclusion is asserted the same two ways the generated-types one is — the vendored text is
genuinely absent from the blob (probed per package, since the two were vendored on different dates
from different repositories), and putting it back changes the answer — plus a third the older check
does not have: the differential is **named**, not just counted. Two is small enough that a different
pair silently swapping in would leave every other check green.

### The budget form put back the $9,000,000 the GMP sync had just replaced, and both calls said 200

Two findings raised in review on the lock-boundary work and declined there as pre-existing rather
than regressions of that diff. They are one mistake in two shapes: **a lock orders writers; it does
not tell the second one that what it read is out of date.**

**`PUT /projects/{pid}/dev-budget` replaces the whole blob.** An editor whose screen loaded before a
"Sync GMP" or "Sync from model" click saves the hard lines that sync had just rebuilt. Serialising
the two changes nothing — the stale body lands *after* the sync, in perfect order, and the sync is
gone with a 200 on both calls. The route now carries a content-derived `rev`
(`dev_budget.budget_rev`), captured under the same lock that does the write, and answers **409** when
the budget has moved. `projects` has no `modified_at` to swap on, so the token is the blob's own
canonical-JSON hash: two callers holding the same bytes hold the same revision, and no migration is
needed.

**The comment over that lock justified it by an argument belonging to a different route.** It said
the two edits touch different line categories, so serialising lets both survive — which is
`connections.update_connection`'s reasoning, and true *there* because that route merges keys into the
blob. This one assigns over it. *A justification copied from the route that inspired the control
describes that route, not this one,* and it reads as settled precisely because it is true somewhere.

**`POST …/dev-budget/sync-from-model` committed a hard cost derived from a model the project no
longer had.** It reads the IFC and runs a full geometry takeoff outside the lock — correctly, since
holding the project lock across a parse would block every publication for as long as it runs — and a
publication landing in between leaves the committed number describing the old model under a 200
saying "synced". *The expensive read belongs outside the lock; what belongs inside is the proof that
it is still the right read.*

**And the obvious check could not have worked.** `publish_source_ifc` writes to a unique staged path
and `os.replace`s it onto the **same** final path, so `Project.source_ifc` is re-assigned the string
it already held — comparing it passes on exactly the interleaving it would exist to catch. *A
staleness check against a field the writer does not move always passes, and reads as though it were
guarding something.* `authoring_shared.ifc_identity` compares `(st_ino, st_size, st_mtime_ns)`
instead, and `os.replace` always changes the inode. It lives beside `publish_source_ifc` on purpose:
whoever changes how a model is promoted should see what detects the promotion.

`services/api/test_budget_rev.py` asserts behaviour and mutation-checks both guards — neutering the
`rev` comparison brings back the 200 that loses the synced hard line, and swapping the file identity
for the path string (what a check written against `p.source_ifc` compares) lets the mid-takeoff
republish commit. It also pins the one caller that actually races: the budget panel must send `rev`,
re-read the one the server returns, and handle the 409 by **reloading** rather than retrying — a
retry carrying the fresh token would re-send exactly the body the server refused.

**`rev` is optional, and that is a bounded decision rather than a fail-open default.** Requiring it
would refuse `build_demo_data.py`, `e2e_dome.py` and `e2e_vertfarm.py`, which write a whole budget
onto a project they have just created and race nothing. What bounds the decision is the web-source
check above, not the sentence in the route saying so.
### Two LPs granted access to one scenario, and one of the grants was never there

`proforma.share_scenario` unions a grantee into `Scenario.shared_with` over a value it has already
read, so two LPs granted access at the same moment leave one grant behind. **Both callers get a 201
naming their own person** — the response echoes the winner's list — so nothing surfaces until the
loser's LP cannot open the scenario and somebody goes looking for a grant that was acknowledged and
does not exist. `drawingset.revise_sheet` is the same shape on a sheet's `revisions` list: an
accepted revision is counted in its own response and is absent from the sheet and from the
cross-sheet register. The scenario site is gap G-10's last band-2 entry, and with it **the ORM
read-modify-write sweep closes outright: 43 sites, 43 reasoned exempt or locked, 0 named open.**

*That number was rewritten at the moment it became true, not before.* On the base this work was
built against it read "four to two, and both survivors are the `dev_budget` pair" — accurate then,
and false the instant the lock-boundary change landed and locked that pair. A count carried across a
rebase is a measurement of a tree that no longer exists, so it was re-read from `test_rmw_sweep`
rather than carried forward. The same failure this file records about narrative copies of a pinned
number, arriving by the other door: not prose drifting away from a gate, but prose staying still
while the gate moved under it.

**A lock, not a compare-and-swap**, for the reason `connections.update_connection` already states in
this file: two grants are *independent* claims, so serialising lets both survive where a 409 would
refuse an edit that does not conflict.

**`db.refresh` inside the lock is half the fix, and the half a lock alone cannot supply.**
`_scenario_for` loads the row *before* the wait, so without the refresh SQLAlchemy's identity map
hands the loser the list it read on the far side of the lock and the lock serialises two writes of
the same stale value — perfectly ordered, and still losing a grant. *A lock makes writers take
turns; it does not make the second one re-read.* The key is the scenario, not `Scenario.project_id`,
which is nullable.

**The ledger keyed the drawing site on `m.data`, and that is the milder half of what is wrong there.**
The markup tag it names is guarded by `"carried_from" not in d2` and has no other read-modify-writer;
the `revisions` list beside it loses an accepted revision outright. *A derivation keyed by attribute
names the site it matched, not the worst thing happening inside it* — so a finding's title is a
starting point for reading the function, never a summary of it.

**The first fix was wrong in a way that looked like tidying.** Hoisting the body into a
`_revise_sheet_locked` helper moved the `with` into the *caller*, and `test_rmw_sweep`'s
`under_pid_lock` went red on exactly that: a lock it cannot see in the function it is asked about is
a lock it cannot verify. Inlined instead. *A refactor that relocates a guard out of the scope a
checker examines turns a verified claim into an asserted one.*

`services/api/test_share_revise_lock.py` asserts BEHAVIOUR — both grants survive, both revisions
survive, and with the lock neutered the same forced interleaving loses one of each (`shared_with`
comes back holding only `lp-a`, `revisions` only `C`). A test that grepped for `pid_lock` would pass
on a lock wrapped around the assignment alone.

### LOCK-XPROC — the cross-process lock was proven by two threads in one process

**CodeQL flagged this file HIGH on its first push, and it was right.** The connect-failure message
printed the DSN verbatim, so a wrong port or an unreachable service container would have written
`PGPASSWORD` into the CI log in clear text. *A diagnostic is an output like any other* — and the
string most worth printing when a connection fails is exactly the one carrying the credential. **Two rounds of redaction were the wrong fix, and the alert said so by not clearing.** `_safe` and
`_scrub` were both correct and neither closed it: CodeQL traces the *flow* from the environment read
to the printer, and `str.replace` changes the value without removing the edge. The DSN no longer
embeds the password at all — libpq reads `PGPASSWORD` from the environment the children already
inherit, so putting it in the URL bought nothing and put the credential into a string that is handed
to subprocesses, set as `DATABASE_URL`, and printed on failure. *Sanitising a sink answers "is this
output safe"; removing the source answers "is this value sensitive at all", and only the second makes
the question stop existing.* The scrubbers stay as defence in depth, and review narrowed what they
actually claim: `_safe` redacts userinfo **and** a `password=` query parameter — libpq accepts the
secret there, so the `@` split alone never saw it — while `_scrub` removes only `PGPASSWORD`'s value
from child output and derives nothing from a caller-supplied `AEC_TEST_PG_URL`. The first wording
here said they "cover a caller-supplied URL", which was wider than the code. *A claim about a guard's
coverage is a claim like any other, and it is checkable the same way* — so both the function and the
sentence were corrected, not just the sentence.

**And fixing the sink it named exposed a second one.** The children are handed the DSN through
`DATABASE_URL` in their environment and their stdout and stderr are reported in a failure detail, so
CodeQL flagged one HIGH after the other was cleared. *Fixing the sink that was reported closes that
sink* — the same lesson this branch's lock work keeps arriving at, met again in the security rules.
Captured output is scrubbed **where it is captured**, not at each print: a sanitiser applied at every
sink is a list that has to stay complete, one applied at the boundary is a property of the value.

That call is pinned by reading this file's own source, because `_run_pair` never runs on a machine
with no PostgreSQL server — so the guard with the widest blast radius was the one no behavioural
check here could reach. *A check that exercises a helper is not a check that the helper is called.*

The first draft of the scrub assertion read `… if os.environ.get("PGPASSWORD") == "sekret" else True`
— **vacuous on every ordinary run**, the same shape as the `web_files()` sortedness check two entries
below. Caught before it was pushed, by the entry about it. The password is a parameter now. It is
redacted, splitting on the **last** `@` rather than the first, because a password may contain one
and a first-`@` split leaves the tail of the secret in the log. Three assertions cover it, since the
only place it runs is a failure path a green run never takes: *a guard that runs only when something
has already gone wrong needs a test that runs always.*


`test_pid_lock_xproc.py` is named for cross-process serialisation and asserts a great deal about it.
Its one exclusion check is **two threads, in one process, on SQLite** — the suite's default database,
where `_advisory()` takes nothing and yields `False`, so the exclusion it observes is entirely the
in-process `RLock`. `pg_advisory_lock`, the whole of R35-PIDLOCK-XPROC, was therefore exercised by no
line of this tree and could have shipped acquiring nothing. **A test named for a property can assert
every neighbouring property and never the one in its name.** What it does prove across processes is
that two workers derive the same KEY: necessary, and silent on whether taking it excludes anybody.

`services/api/test_pid_lock_pgxproc.py` asks the question. Two real OS processes contend for one
project's lock against a real server; their held intervals must not overlap. Two mutations, because
either alone passes a lock that has stopped locking: two DIFFERENT projects must overlap — otherwise
the positive check is measuring the order the harness starts things in, and a lock that excluded
everything would look identical — and a per-process advisory key must overlap, which is note 1's
`hash()` defect reinstated across real processes.

Verified by deleting the acquisition outright rather than by reasoning: the behavioural check reds
independently of the static one. One check *stayed green* under that mutation and had its label
narrowed rather than left standing — `cross_process_status()` reports the DIALECT, so it says the
advisory path was available, never that a lock was taken.

It also pins the acquisition as the BLOCKING form. `_advisory` sets `acquired = True` without reading
a result, because `pg_advisory_lock` returns void; a `pg_try_advisory_lock` "don't block the request"
change would leave the code reporting a lock it does not hold. That static pin is redundant wherever a
server exists — with the swap applied the behavioural check reds too, deterministically, since B starts
only once A is demonstrably inside. It earns its place on the run with NO server, where the exclusion
arm cannot run at all.

With no server it does not pass quietly: it asserts that `.github/workflows/db-migrations.yml` still
runs it with `AEC_PG_REQUIRED`, so deleting that step reds the ordinary suite instead of silently
removing the only place the check is real — the construction `services/api/test_pin_pgnull.py` uses,
for the same reason.
### RMW-LOCKBOUND — a bounded wait, and the correctness bug that bounding it nearly introduced

`pid_lock.mutating` serialises sidecar read-modify-write per project with `pg_advisory_lock`, which
blocks until the holder releases — **with no ceiling**. All 30 call sites are plain `def`, so FastAPI
runs them in the threadpool: a stuck holder does not wedge the event loop, it pins threadpool
workers, and Starlette's default pool is 40. *The entry on record described it as blocking the
server, and named 11 call sites. Both were wrong, and the mechanism mattered more than the count —
"it blocks the event loop" and "it exhausts the threadpool" send a reader to different fixes.*

`SET LOCAL lock_timeout` now bounds the wait; a timeout raises `LockTimeout(TimeoutError)`.

**Three premises, each probed against PostgreSQL 16 rather than recalled.** That `lock_timeout`
bounds an ADVISORY lock is not stated in so many words anywhere, so it was measured: SQLSTATE
`55P03`. That a plain `SET` is connection-scoped and rides the pool back out was measured too —
1500 ms still in force on the next checkout of the same backend — which is why the statement is
`SET LOCAL`, and why the advisory lock surviving that `SET LOCAL`'s commit had to be measured as
well. Any one of the three being false sinks the shape.

**The third premise is the dangerous one.** A lock timeout and an unreachable server raise the *same*
SQLAlchemy class; only the sqlstate separates them. `_advisory` already catches broadly and degrades
to in-process, loudly — correct for "there is no Postgres here". Caught as `except OperationalError`,
a timeout lands in that same branch and the contended write **proceeds having taken no cross-process
lock at all**. Bounding the wait would have converted an availability problem into a silent
correctness one, strictly worse than what it replaced. *A bound is only safe if it cannot be mistaken
for the absence of the thing it bounds.*

**Two bugs in the first draft, both found by the gate rather than by reading.**
`SET LOCAL lock_timeout = :ms` is a **syntax error** — `SET` takes no bind parameter — so it did not
merely fail to apply the timeout: it raised, fell into the degrade branch, and let the write proceed
unserialised. The exact failure above, reached by a door it did not anticipate, in the change written
to prevent it. And the static check read its own **prose**: `"SET lock_timeout" not in src` failed on
*correct* code, because the comment explaining why a plain `SET` is wrong contains that string.
*A check that greps a source file is reading whatever a future author writes ABOUT the code alongside
the code — and prose is exactly where the forbidden form gets named.* Comments and docstrings are now
stripped, with a self-test in both directions.

**A measured limit, stated rather than hidden.** The degrade-branch mutation **survives** a
static-only run: the sqlstate constant stays in the source, unreachable. Only the two-process arm
sees it, and that needs a server the API gate's job does not have — so it runs in
`.github/workflows/db-migrations.yml`, and `services/api/test_pid_lock_bound.py` asserts that step is
still there. *A gate whose real arm runs in exactly one place is one deletion away from decoration,
and the deletion is in a different file from the gate.*

Four mutations: removing the `SET LOCAL` reds five checks (B waits out the full hold); folding the
timeout into the degrade branch reds two (B enters the critical section having timed out and written
anyway); deleting the CI step reds two; dropping `AEC_PG_REQUIRED` from it reds one.

**Review round 2 found the lock's lifetime was wrong in BOTH directions, and the fix is the shape
that satisfies neither constraint alone.** A session-level advisory lock lives on a connection, so
its lifetime IS that connection's lifetime — and two requirements pull opposite ways:

* **End the transaction and the connection goes back to the pool.** Measured under contention: the
  backend changed between acquisition and unlock, `pg_advisory_unlock` returned `False`, and the real
  lock stayed stranded until recycling while another caller held that connection.
* **Leave it open across the critical section and `idle_in_transaction_session_timeout` kills it.**
  Measured with that timeout at 1 s and a 3 s section: the acquiring session was terminated, the lock
  died with it, and a rival writer walked in. **A lost update** — precisely what the lock exists to
  prevent, arriving through the fix for the other half.

A `Session` can satisfy neither cleanly. A checked-out `Connection` whose acquisition transaction is
*committed* satisfies both: the connection is held to `close()`, nothing is left idle in a
transaction, and `SET LOCAL` still reverts before the connection is released.

*Three of this change's verifications were themselves wrong before they were right, each in the same
shape.* The connection probe cleared the pooling bug because an idle pool hands the same connection
straight back — five rival Sessions were needed to tell "retained" from "released and re-issued". The
static check for it matched a substring that tokenising makes unmatchable. And the idle-timeout check
set the GUC on **its own** connection while `pid_lock` opens another, so the Session-shape mutation
sailed through it; it now sets it on the DATABASE, which is also how a managed PostgreSQL imposes it.
**Each one reported success while measuring nothing, and only a mutation distinguished them from a
real check.**

### DESKTOP-CONVERT-TIMEOUT — the parameter reached one of the two branches

`fragconvert.convert_ifc` has always taken a `timeout`. It reached `subprocess.run` on the Node
path, where an overrunning child can be killed, and reached **nothing at all** on the Python path,
which calls IfcOpenShell in the caller's own process. `_publish` runs on a background worker and
does not care. **`edit_preview` is a synchronous route passing `timeout=120`**, so a slow model held
a request worker past its own deadline instead of returning the 503 that route is written to give —
and the parameter's *presence* is what made the gap invisible.

It was filed rather than fixed because the obvious repair is a killable child process, which is
net-new spawning machinery in a PyInstaller bundle. **That was the right call about that repair and
the wrong conclusion about the problem**: `from_ifc.convert` already had a per-element loop with a
progress hook, so a *cooperative* deadline fits with no process isolation at all. It now checks the
clock after the parse, between elements, and every 4,096 entities in the index loop; `convert_ifc`
computes the deadline from the caller's `timeout` (not the duration — the callee would restart the
clock, and `edit_preview` authors a one-element IFC before it calls). Both paths raise
`TimeoutError`: Node's `subprocess.TimeoutExpired` is a `SubprocessError`, so telling "too slow"
from "broke" meant knowing which converter ran, which is the fact this function exists to hide.

**The entry stays OPEN, deliberately — and the first draft of this paragraph overstated what the
fix does.** It said the change "bounds the cost that scales". It does not: `ifcopenshell.open` is a
single call whose time scales with file size, and the checkpoint is *after* it, so a large file is
parsed in full and only then refused. The accurate claim is **enforced at phase boundaries and
within the two loops** — the geometry loop per element, the entity index every 4,096 — with the
parse and any one hanging `create_shape` still outside every checkpoint. *Caught by re-reading my
own claim against the code before review did, which is the only reason it is not in the shipped
prose.* *A partial fix described as a fix is how the original asymmetry became invisible in the
first place.*

**Two defects in the gate, both found by its own mutations rather than by review.** Reinstating the
pre-fix state red it, but deleting the parse and geometry checkpoints while leaving the entity-index
one **passed** — that tick fires at entity 0, so the deadline was still detected, after all the
geometry work was done. The timing assertion meant to catch that was vacuous: `elapsed < max(0.25,
baseline * 0.9)` against a 33 ms fixture is satisfied by doing the whole conversion. *A threshold
generous enough not to flake on a slow runner is generous enough to measure nothing.* The check now
asserts the **stage name** in the raised message — a deadline already past must be caught at
`parse`, before any geometry — and a second case crosses the deadline mid-loop through a deliberately
slow `progress` hook, so both checkpoints are load-bearing. And the always-raise mutation used to
kill the run with a traceback instead of naming a contract; the positive control now catches it.

The first draft of that positive control also failed on *correct* code, asserting byte equality
between two conversions — `metadata` embeds `"created": datetime.now(...)`. It compares the parsed
model instead. *An assertion that fails on correct code costs a round exactly like one that passes on
broken code.*

**And forcing one branch to reach the code under test stopped testing the other.** Every check above
sets `have_converter()` false to drive the Python path, so the Node half of "both paths raise
`TimeoutError`" was asserted by nothing — a regression letting `subprocess.TimeoutExpired` escape
would have passed the gate that exists for exactly that promise. Raised in review. *The act of
forcing a branch is itself an act of un-testing its alternative, and it leaves no trace in the
output.*

Two arms, because neither covers the other. **Injected**: `subprocess.run` raises `TimeoutExpired`
directly, proving the handler converts it; runs everywhere. **Real**: a Node process that does not
finish, under a real budget, proving the whole chain including the argument being passed. Measured
rather than argued — with `timeout=timeout` deleted from the call, the injected arm still **passes**,
because its exception came from the stub and not from the runtime. The real arm needs a `node` the
API gate's job does not install, so it is conditional, and a conditional arm that skips everywhere is
a check reporting good news: the arms that ran are named in the output and at least one is required.

**The real arm's first draft turned that mutation into a hang rather than a failure.** Its script only
blocked, so dropping `timeout=` left `subprocess.run` waiting for ever — caught, in the sense that the
gate never went green, but reported as nothing at all and paid for with a CI job's whole budget. The
script now exits on its own timer too, so the same mutation returns normally and the arm fails **by
name**, and a margin check separates "gave up at the budget" from "waited for the script". *Make a
check fail; do not settle for it not passing.* The lane table's row for this item was also still
carrying the pre-fix text two paragraphs of narrowing later — and its stated REASON, "the fix is
process/packaging shape", is why the item read as unactionable for thirteen days: that is the repair
the residue needs, recorded as the repair the whole item needed. *A correct decision with a wrong
reason attached is worse than no reason, because the reason is what the next reader plans against.*

### An exclusion whose own differential is blind to what it wrongly excludes

The vendored-tree exclusion below shipped as `"/src/vendor/" in q` — a match on the *parent*
directory rather than on the packages. Review named the hole, and it is the same shape the exclusion
exists to close, one level out.

A first-party caller added under `apps/web/src/vendor/` would be dropped from the blob. **And the
differential beside the exclusion cannot see that**, because it asks what restoring the vendored text
*vouches for*: if the new caller calls `/projects/{pid}/workflow/{key}`, the vendored copies already
vouch for that route, the difference is unchanged, and the route stays frozen as uncalled while the
client calls it. *A differential over what an exclusion REMOVES says nothing about what it removes
WRONGLY* — a file wrongly excluded is absent from **both** sides of that subtraction, so it moves
nothing and is invisible.

The excluded set is now named — `vendor/massingifc/`, `vendor/massingpdf/`, matched on the path
relative to the web root. Two checks, because the first alone would rot:

- The tuple must equal the directories under `vendor/` carrying a `VENDOR.md`, **in both
  directions**, so the list cannot drift from the tree.
- A synthetic sibling package the tree does not contain must still be READ. Every real directory
  under `vendor/` is vendored, so the tree *cannot* distinguish a named exclusion from a
  parent-directory one — the same empty-population trap that made the `.tsx` sort check vacuous.

The list is literal rather than derived from the `VENDOR.md` markers, deliberately: a blob that
decides what to read from a marker file changes meaning when somebody deletes one. The marker checks
the list instead. *Hardcode what is load-bearing; derive the proof that it is right.*

Reinstating the parent-directory match reds the sibling probe **and nothing else**, which is the
finding restated as a measurement: no check that existed could catch it. Dropping a package from the
list reds five, the derivation check among them. And the fixture itself was wrong on its first run —
it restored `glob` from a name bound two hundred lines further down the file, so it crashed instead
of asserting. *A fixture that restores from a name defined later restores nothing.*

### Looking one way down the list is not reading the list

The round below stopped asking "is it written down" and started asking "can it fail the job", and
then answered it by looking at the separator that **follows** the invocation. A review pass named two
shapes that pass with the status masked by nothing at all:

- `true || python <file>` — nothing follows the invocation, so nothing is masked, and bash never
  reaches it. Reading one token forward is not reading the command list.
- `python <file> && echo passed` on one line, `echo done` on the next. `bash -e` suspends itself for
  every command of a `&&`/`||` list except the last, so a failing test does not end the step; the
  list's own status is then discarded, because a later list runs and the step exits with `echo
  done`'s zero. **The single-line form of that same text is correct** — there the failing list is the
  last one and its status *is* the step's — and the check added in the round below tested only the
  single-line form. *A shape and the same shape one line longer are different programs.*

`bash -e` reasons about command **lists**, not about commands, so the guard now does too: a `run:`
block is cut into lists at `;` and at line ends, each list into segments at `&&`/`||`/`|`/`&`, and an
invocation counts only when its status can reach the runner — nothing masking after it, no `||`
before it in the same list, and, if the list is conditional at all, that list must be the last in the
block. A `&&` *before* the invocation is deliberately still accepted: `cd services/api && python
<file>` is the ordinary idiom, and the same limit `_parked` already states applies — a constant
written to be false is caught, a condition that merely evaluates false is not.

Three new self-tests, and the command test is split out from the control-flow test so each can be
mutated alone. Deleting either guard reds exactly its own self-test and nothing else; widening the
conditional-list rule to reject *every* conditional list reds four positive checks, including the
shipped step's own shape. Three further mutations against the real `db-migrations.yml` — the step
behind `true ||`, the step as a two-line `&&` block, and the status masked with `|| true` — each take
the found-step count to zero.

### "Does it run" and "can it fail the job" are different questions

I had asked review whether `_invokes` could ever fail **open**. It can, three ways, none of them the
way I asked about — and all three are the same class the last four rounds were about, one level
further out than any of them reached.

**The step can be skipped, its failure can be ignored, or its exit status can be thrown away.**
`if: false` is the ordinary way to park a step; `continue-on-error: true` runs it and shrugs;
`python <file> || true` discards the status, and `python <file> | tee log` hands it to `tee`, because
GitHub runs `bash -e {0}` with no `pipefail` unless `shell:` says otherwise. In the last two the
file *is* executed — which is exactly what the previous rounds established — and in the first it is
not executed at all; what all three share is that the `run:` text, the `AEC_PG_REQUIRED` value and
the step selection are identical to a live step, so every check added so far stays green while CI
asserts nothing. (The first draft of this paragraph claimed execution in all three, which `if: false`
plainly contradicts — found in review. *A sentence generalising over cases it lists is worth
re-reading against each of them.*) *Each round asked a sharper version of "is it written
down" and none asked "can it fail".*

The separator that **follows** a command segment now decides whether it counts (`;` and `&&` keep the
status; `||`, `|` and `&` do not), and a job or step that is parked or cannot fail is excluded.
Explicit `continue-on-error: false` still counts, however it is spelled — `bool("false")` is `True`,
so the obvious predicate would have red a correct workflow, and a gate that cries wolf gets deleted.
Only the *constant* false is treated as parked: a real condition is not evaluated here and is not
assessed, which is stated rather than implied.

**And the budget panel's reload was still racing the editor.** Holding the request slot across the
conflict reload stops a save from *leaving*; it does nothing about the keystroke. `lines.splice`
replaces the array and `paint` rebuilds the inputs from it, so an edit typed in that window is gone
from both the model and the screen, and the queued follow-up then saves the server's copy back.
Editing is now closed while the reload runs and restored by `paint` — which is also what the reload
calls when it finishes, so a disable applied anywhere else would be undone by the next repaint.
Reconciling a keystroke against a list replaced wholesale needs a rule nobody has chosen, and
guessing one silently is how a budget acquires a number no one typed.

Seven new self-tests. Four mutations, three of them against the real workflow: the step's failure
masked with `|| true`, the step parked with `if: false`, and `continue-on-error: true` — each takes
the found-step count to zero.

### Three fixes that each narrowed the right thing and stopped one question short

A second review pass over the round above found one more defect behind each of its three fixes. The
shape repeats, which is the interesting part: every one of them narrowed the correct subject and
then asked the old question about it.

**Serialising the requests was not serialising the state.** One save in flight stops two sends
carrying one `rev` — but `again` only covers a send *that flow* queued, and says nothing about a
`setTimeout` the debounce armed while the save was on the wire. That timer fires during the reload
carrying the pre-conflict lines and the stale rev (another self-inflicted 409) or after it, carrying
the server's own copy straight back. And the reload is asynchronous: releasing the in-flight slot
when the *save* settles lets a keystroke start a request against a `lines` that is mid-replacement.
The 409 path now cancels the pending timer and holds the slot until the reload resolves. *The reload
mutates the state every request is built from.*

**Extracting the right workflow step was not asking whether that step runs anything.** The guard
matched a step whose `run:` merely *contained* the filename — so commenting the invocation out, the
ordinary way somebody parks a slow step, leaves the substring in place, the step is still found, its
`AEC_PG_REQUIRED` is still set, and the guard reports that CI runs this file while CI runs nothing.
Comments are stripped per line and the name is compared as a whole basename. The `#` split is crude
and fails in the safe direction: a `#` inside a quoted string can only *lose* an invocation, which
reds the caller, because the caller requires exactly one step.

**And that first fix was still wrong, for the reason it was written.** It rejected a commented-out
invocation and a longer filename and went on accepting `echo test_pid_lock_pgxproc.py` — review
declined to close the finding on exactly that ground. *Excluding the shapes you were shown is not
answering the question those shapes were examples of.* The head word of the command segment holding
the name must now be a Python runner, or be the script itself. The runner list can go stale, and it
does so in the direction that gets noticed: a missing runner makes the step invisible, the caller
requires exactly one step, the build reds, somebody adds the name — while the opposite error passes
quietly. Emptying the list is a mutation and it reds three self-tests. *When a list must be
incomplete, put the incompleteness where it fails loudly.*

**The positive control earned its place the same hour.** The first version of that narrowing matched
the filename as a whole token before asking what the command was, and the token pattern excludes a
preceding `/` on purpose — so a direct exec `./test_pid_lock_pgxproc.py` never reached the command
test. Comparing basenames answers both questions at once with no lookbehind to get wrong. Without a
check that real invocations are still *accepted*, that would have shipped as a stricter-looking gate
that had quietly stopped recognising a legitimate way to run the file.

**And then the claim I put to review turned out to be false.** Asking whether the command split
could ever *invent* an invocation, I asserted that every parsing error loses one instead — and
measured it before the answer came back. `echo "a; python test_pid_lock_pgxproc.py ; true"` returned
true: a regex split cannot see quotes, so a `;` inside a string ended the `echo` early and handed the
rest back as its own command. *A claim about which way a heuristic fails is a claim like any other,
and this file's entire subject is that an unchecked one reads as settled.* The line is now tokenised
with `shlex` in POSIX mode with `punctuation_chars`, which respects quoting for the comment marker
**and** the separators, so one change closes both — including a case the character-level strip got
wrong in the other direction, where a quoted `#` swallowed a real invocation after it. Per line,
because a `run: |` block is a sequence of commands and newlines are whitespace to `shlex`. An
unbalanced quote raises and that line is skipped: unreadable is not "runs it", and the caller
requires exactly one step, so skipping reds rather than vouches.

**Merging the environment in force was not reading the value.** `AEC_PG_REQUIRED: ""` is exported by
GitHub as an empty string, which the consumer reads as opted *out* — so the key-presence check passed
a workflow whose step would take the no-server branch and exit 0. The predicate is now derived from
the consumer rather than restated, which is also why `"false"` and `"0"` count: a workflow `env:`
value is exported as a string, and any non-empty string is truthy there. That is a fact about GitHub
Actions, not a choice.

Four mutations, two of them against the real workflow — commenting out the invocation, and setting
the flag to `""` — plus two on the panel. The cross-process gate was re-run against a live
PostgreSQL 16 after the change: 24 checks, all green.

### The budget panel manufactured its own 409, and two of this PR's own checks were measuring the runner

Three findings from a full review pass on the head that added the `rev` precondition. All three are
inside work landed earlier in this same branch, and the first is a product defect the precondition
itself created.

**A debounced save that races itself supplies its own stale write.** `clearTimeout` cancels a save
that has not left yet; it does nothing to one already on the wire. On a connection slower than the
500 ms debounce, two saves go out carrying the same `rev` — the server commits the first, refuses the
second, and `reloadAfterConflict` replaces the user's newest keystroke with the server's copy while
telling them "the development budget changed elsewhere (a GMP or model sync, or another editor)".
*A staleness token turns a lost write into a refused one; it does not decide WHOSE write is stale.*
One send is now in flight at a time, the body is built when the request starts, and a keystroke
during a save sets a flag rather than queueing a second request — so one follow-up send carries every
edit made while the first was in flight, instead of N sends of the same final state.

**The workflow guard searched the whole file for a flag its neighbour also sets.** With no PostgreSQL
server the cross-process gate cannot run its assertions, so it proves instead that
`db-migrations.yml` still runs it *with* `AEC_PG_REQUIRED`. It asked whether that string occurred
anywhere in the workflow — and the pin-sweep step sets it too. Measured: deleting the flag from this
file's own step leaves three occurrences and the old check green, so the CI step would have taken the
no-server branch and exited 0 with nothing exercising the advisory lock anywhere. The workflow is now
parsed, the step that runs this file is extracted, and the flag is looked for in the environment
actually in force for *that* step — workflow, job and step `env` merged, so hoisting the flag to the
job stays valid. *A check scoped to the FILE cannot speak about a STEP, and a neighbour's correct
configuration is what makes the difference invisible.*

**And two timing checks had a window that was a constant.** Child A held the lock for a fixed 1.5 s
while the parent started child B; if B's interpreter, import, status call and connection took longer
than that, B entered after A left, and the two MUTATION checks — which *require* an overlap — failed
on a lock working perfectly. A now waits for B's own log line before starting its hold. Measured on
a real server: with the hold shrunk to 50 ms, the old shape fails both mutations and the new one
passes all three. *A timing check whose window is a constant is measuring the runner.*

The extractor's three self-tests run on **every** invocation, including the one with a server —
otherwise the only branch that exercises it is the branch a broken extractor would make vacuous.

### Round 16: the RVT translation was still on the event loop, and the sort check could not fail

A full review pass over the current head found two, and both were inside this PR's own earlier fixes.

**The APS translation in `import_rvt` still ran on the event loop.** Round 12 moved `staged.write_bytes`
off it, with a comment explaining that a converted IFC is hundreds of megabytes and blocking the
coroutine freezes every other request in the process. The call that *produces* those bytes —
`aps.translate_rvt_to_ifc`, which `convert.py` documents as running "for many minutes" and already
sends to the threadpool for that reason — sat directly above it, unwrapped. *Fixing the blocking call
you are looking at is not the same as fixing the blocking call that dominates the route*, and the
smaller one was the one that already had a comment pointing at it.

**And the new determinism check could not fail.** `web_files()` sorted inside its glob loop, yielding
`[every .ts sorted] + [every .tsx sorted]` — deterministic, but not sorted. The assertion that it is
sorted passed anyway, because the tree holds **0 `.tsx` files against 658 `.ts`**: the fix was
accidentally right and the check was accidentally green. The day somebody added a `.tsx` the check
would have gone red with a message blaming the glob — *a check whose failure message can misdiagnose
is worse than one that stays silent, because somebody acts on it.* The sort is now one pass over the
whole list, and the contract is probed by feeding a synthetic `.tsx` through the real function, since
the tree cannot supply one.

*A check that passes because its population is empty has the same shape as one that passes because
the code is correct.* Reverting either fix reds exactly one assertion, naming the right cause.

### The "CI flake" in the reachability gate was a backtick in a comment, and the answer depended on directory order

`test_route_reachability` went red on 2026-09-23, passed on a re-run of a byte-identical tree, and
went red again on the next push. It was filed as a transient of unknown cause. It is neither
transient nor unknown: **one call in the file handed `leaf_is_called` the RAW web source instead of
the comment-stripped one**, and that one argument made the gate's answer depend on the order
`glob.glob` happened to return ~400 files in.

`string_blob`'s template-literal alternative spans newlines, because a real template literal does.
This tree quotes identifiers in backticks throughout its **comments**, so an unpaired backtick in one
comment opens a phantom template that closes at the next comment's backtick — and everything between
is emitted as a single string body **with its inner quotes intact**. A leaf whose only vouching
occurrence is a quoted word then sits in that body preceded by `"` rather than by the NUL that
anchors "opens a string", and reads as *uncalled*. Which comments pair with which depends entirely on
the concatenation order. Measured: **1 of 25 shuffled orders flips `workflow`**, and
`string_blob(BLOB)` ranges from **933k to 2,014k characters** across orders; read through the stripped
source, the derived verdicts are identical in every order.

*A gate whose answer depends on directory enumeration order cannot be reproduced from its own
failure* — which is exactly why the first instance was dismissed. "Flake" was a description of the
symptom standing in for a cause, and it bought a second red build.

**Fixed four ways, because the one-word fix is the one that drifts back.** The call is stripped;
`web_source.web_files()` is split out and **sorted**, so the blob is at least the same blob twice;
and both properties are asserted — a four-line fixture that reproduces the backtick swallow without
depending on anything in the tree, and an order-invariance check that rebuilds the real blob reversed
and requires the same uncalled set. The fourth is the one that matters most: **the file now reads its
own source** and fails if any call passes the raw blob, because neither behavioural check reds when
somebody writes `BLOB` there again, and *for a 1-in-25 defect "run it again" is not an alternative to
a check.*

All four are mutation-checked — reverting the call, inverting the fixture, blinding the AST scan, and
dropping `sorted` each red exactly one assertion, with a message that names the right cause. The
`sorted` assertion exists precisely because dropping it changes no verdict today: *the change nobody
can measure is the change nobody notices reverting.*

### LOCK-BOUNDARY round 15 — the answer collected and then discarded, and a test sharing a directory with its own failures

Two findings. The first is inside round 14's fix; the second is a test-hygiene defect that would have
broken the suite permanently for anyone whose run died at the wrong moment.

**1. `pid_lock_names` collected the bare-lock names and returned a boolean.** The names were gathered
into `bare_names`, the shadowing was subtracted correctly — and then the function answered yes/no, so
`is_the_lock` fell back to the literal spelling `mutating`. Both directions are wrong at once:

```python
from aec_api.pid_lock import mutating as held
def writer(db, pid, mutating):
    with mutating(pid):          # the PARAMETER certifies
        p.source_ifc = "x"
```

`bare_names` is `{"held"}`, `shadowed` holds `"mutating"`, the intersection is empty, the flag says
yes — about a name nobody bound to the lock. And the genuine `held(pid)` is **never** certified, so
the docstring promising the bare form was false for the one spelling that actually reaches it.

*Asking the right question and then throwing the answer away* — the lesson
`services/api/test_pin_pgnull.py` already records, arriving here by a different door. `lock_spans`
now checks membership in the names the import bound. Probes `aliased_bare` (must certify) and
`bare_alias_shadow` (must not); restoring the boolean reds them by name.

**2. `test_ifc_publish_atomic` ran in a fixed `./_ifc_atomic` and never removed it.** That file
deliberately *keeps* one `.rollback-*` backup and then asserts there is exactly one and that no other
rollback scratch is left behind. In a shared directory those two assertions are armed by any run that
dies between creating the kept backup and the cleanup at the end — a crash, a timeout, a cancelled CI
job — and then **every later run fails**, for a reason unrelated to the code under test, until
somebody deletes the file by hand. `run_tests.py` reports `_ifc_*` as residue it does not own, so the
runner never clears it either.

**Demonstrated, not argued**: with the old fixed directory and a single planted
`.rollback-stale-from-a-crashed-run`, the run fails on *both* named assertions. The directory is now
`tempfile.mkdtemp()` per run, removed only on a pass — a failed run's staged files, backups and
published bytes are the evidence somebody will want. *A test that asserts "nothing was left behind"
must not share a directory with its own previous failures.*

### LOCK-BOUNDARY round 14 — the same fail-open, in the two spellings the fix did not look at

One finding, and it is inside round 13's own fix.

Round 13 closed a fail-open where `_lock_import_names` accepted `pid_lock` imported from **any**
module, so `from .fakes import pid_lock` certified as the project lock. The repair was to recognise
the lock by its **source module** — and the docstring said exactly that. The code under it went on
matching a **suffix**:

- `(node.module or "").endswith("pid_lock")` accepts `from .fake_pid_lock import mutating`,
  `from .fakes.pid_lock import mutating`, and `from tests.pid_lock import mutating`. Each returns
  `mutating`, `pid_lock_names` returns `bare=True`, and `lock_spans` certifies `with mutating(pid):`.
- the `ast.Import` branch matched `a.name.split(".")[-1]`, so `import fakes.pid_lock as pid_lock` is
  certified too — and for `import x.pid_lock` **without** `as`, Python binds `x`, not `pid_lock`, so
  the analyser was recording a binding the language does not make.

*A fix aimed at the spelling that was reported closes that spelling.* The rule was right and stated
plainly one paragraph above the code that ignored it, which is the part worth keeping: **the prose
was true and the test was not**, and prose agreeing with itself is not evidence. Recognition is now
by exact module path — relative `pid_lock` or absolute `aec_api.pid_lock`, with `level` checked so a
top-level module of that name cannot stand in — and the `import` form is accepted only when aliased,
the one shape that binds a usable name.

Two probes added, `fake_bare_import` and `fake_module_import`; restoring either the suffix test or
the last-segment match reds the violation list by name.

### LOCK-BOUNDARY round 13 — a live unlocked writer the analyser could not see, by construction

Four findings, all real. One is a **product defect**, not a gate defect, and it is the kind this
whole pull request exists to close.

**1. `bim.patch_project` swapped `Project.source_ifc` outside the lock.** `ProjectPatch` declares
`source_ifc`, so an admin PATCH can move the pointer that `bake_layers`, `edit` and every authoring
route read, spend a recipe on, and write back — the same race the five writers in this PR's title
had. It survived twelve rounds of a gate built to find exactly this, **for a structural reason
rather than an oversight**: the write is `setattr(p, k, v)`, which carries no `Store` context and no
`Attribute` node, so an analyser that asks the grammar for attribute writes is blind to it however
carefully it reads.

`_stored_attrs`' docstring claimed `ctx=Store` was *"the complete, exact marking of an attribute
write in EVERY spelling."* It is every **syntactic** spelling — a different and smaller claim. Python
spells attribute writes two ways, syntactically and through the reflection API, and *a derivation
that asks the grammar is only as complete as the grammar's own account of what it is looking for.*
`dynamic_writes` now covers `setattr`, judged by the same `lock_spans` traversal keyed on the call
node; the route takes `pid_lock.mutating(pid)` around the lookup, the refresh and the commit.
**The gate found the defect on its own once taught the spelling** — it reported
`patch_project writes Project.<setattr> with mentions outside the lock at [759]` before the fix.

The dynamic rule is coarse in the fail-closed direction — an unlocked `setattr` on a model with
*any* protected attribute is a violation, because the analyser cannot prove it wrote a different one
— and that is affordable because the population is seven sites tree-wide, measured. Three receivers
do not resolve (two ifcopenshell entities, one `Viewpoint` reached through a generator) and are
declared in the exemption ledger with stated reasons rather than inferred away.

**2. The shadowing list was short again — a fifth family.** `case pid_lock:` binds through
`MatchAs.name`, with no `Name` node anywhere, so a captured subject certified as the project lock.
`MatchAs`, `MatchStar` and `MatchMapping.rest` are now handled. The sting is where the claim was
made: round 12's docstring said the list of string-field binding forms was **"closed by the
language"** while naming four of seven. *A completeness claim about a hand-written list is a claim
the list cannot check* — asserted in the very sentence explaining why enumerations fail. The
docstring now says what is true: as complete as the last reading of the grammar.

**3. Lock recognition disagreed with itself in both directions at once.** `_lock_import_names` and
`pid_lock_names` each matched `a.name == "pid_lock"` from *any* module, so
`from .fakes import pid_lock` certified — the `import_shadow` probe missed it because that probe
renames and this substitution does not. *A probe written against one spelling of a substitution does
not cover the substitution.* And in the other direction, round 12's own shadowing fix made
`from ..pid_lock import mutating` **unreachable**: the import bound no lock name, so `"mutating"`
entered the shadow set and `bare` could never be true. The form the docstring promised to accept had
been switched off by a fix, invisibly, because nothing in this tree spells it that way. Recognition
is now by **source module**, in one place both callers read.

**4. `_rel` emitted backslashes on Windows**, which is where this repository is developed, so the
`/`-separated keys in the exemption ledger never matched, `stamp_conformance`'s receiver fell through
to UNRESOLVED and the real-tree verdict red — **there and only there**, because the ledger self-test
normalises separators before comparing. *A check that normalises in one place and not the other is
green where it looks and red where it runs.* The self-test uses `PureWindowsPath`, which is
platform-independent, so it reproduces the Windows string on Linux instead of asserting something
that can only hold here.

Each fix is mutation-checked: dropping the match forms, matching the lock import by name alone,
returning `str()` from `_rel`, removing the `setattr` collector, and unlocking `patch_project` each
red a specific named self-test.

**One of those five did not, at first, and the gap was in the check rather than the fix.** The
Windows self-test asserted the property against `PureWindowsPath` directly and never called `_rel`,
so reverting `_rel` to `str()` red nothing — a check written beside the guard instead of through it.
The separable half is now `_posix_rel(p, root)`, which the self-test calls, and the mutation reaches
it. *A static check that still passes with the guard removed is not testing the guard* — this file
states that rule about `_system_field` and then broke it about itself one round later, which is the
argument for running every mutation rather than the ones expected to bite.

### LOCK-BOUNDARY round 12 — the third statement-type list, and a sentinel spent as a model

Four findings, all in-diff, all real. Three are in `services/api/test_lock_boundary.py`; one is a
route that blocks the event loop.

**1. The scope merge inherited the enclosing model for a name the inner scope had taken over.**
`_bindings` marked a name meaning two models `CONFLICT` and then *dropped the entry at its own
return* — so `collect`'s `dict.update` chain found nothing for that name in the inner scope and the
**outer** function's model flowed in. An unlocked `Project.source_ifc` write inside a helper that
rebinds `p` was therefore classified as the outer `SavedView`, and reached neither the violations nor
the unknowns. Two sentinels now survive the merge — `CONFLICT` for a name meaning two models and a
new `UNRESOLVED` for one this analyser cannot pin down at all — and `_resolved` removes them **after
the last merge**. *A sentinel filtered before the merge cannot shadow anything*, which is the whole
mechanism by which an inner binding is supposed to beat an outer one. The probe runs through
`collect` in a temp directory, because nothing calling `_bindings` alone can see a defect in the
merge.

**2. The shadowing check in `pid_lock_names` was a list of statement types, and the list was short.**
Third time in this analyser, third time short. It named five forms and still certified an arbitrary
object as the project lock for `pid_lock, _x = other, 1`, `from .fakes import stub as pid_lock`,
`except Exception as pid_lock:`, a nested `def pid_lock(...)` — and a **module-level** rebinding
beside the import, which a per-function scan cannot see at all although it is the one rebinding whose
blast radius is the entire file. **The fix for an incomplete enumeration is not a longer
enumeration**: the new `_bound_names` asks the grammar — `ctx=Store` on `ast.Name` is the exact,
complete marking of a name assignment in every spelling, exactly as `_stored_attrs` learned one node
type over — and names explicitly only the four forms that carry their name as a plain string field
rather than as a node (`except ... as`, `def`/`class`, import aliases, `global`/`nonlocal`). That
list is closed by the language, not by what this tree happens to contain. Module scope is now in the
chain the check scans.

**3. `NOT_A_MODEL` was spendable as a model.** The sentinel meaning *"proved not to be a mapped
instance"* is a non-empty string, so `if m and ok` accepted it and a locked write through `self` in
any non-mapped class seeded a protected pair keyed on the sentinel. Nothing ever resolves *to* it, so
no violation could match — but its **attribute** entered `prot_attrs`, the set that decides whether
an unresolved receiver is worth reporting, so unrelated unlocked writes were raised as UNKNOWN on the
strength of a pair protecting nothing.

**4. `import_rvt` wrote a whole converted IFC on the event loop** — `staged.write_bytes(ifc)` on the
coroutine, one line above a `run_in_threadpool` the same route already used for the publish. A
converted model is routinely hundreds of MB; the loop stalls for every other request while it
lands. This is the v0.3.703 SSE failure in miniature.

Deriving that shape over the tree found **three more instances, all in one other route plus the
converter**, and fixing only the line review pointed at would have left the *largest* blocker two
lines above it: `raise_plan_to_bim` ran the DXF parse, the ifcopenshell raise, a whole-file read, a
whole-file write and a `storage.put` network round trip on the loop; `convert` read its fragments
output back on the loop having just handed the translation *off* it. All are now awaited through the
threadpool. **No gate is claimed for this** — a check matching `read_bytes`/`write_bytes` would be a
completeness claim with a filter under it, since the honest population of "blocking work in an
`async def`" also includes `storage`, `subprocess` and every synchronous `db` call. That axis is
filed as its own task rather than half-gated here.

Each of the three analyser fixes is mutation-checked: filtering the sentinels inside `_bindings`
reds the scope-merge probe by name; narrowing `_bound_names` back to statement types loses all four
shadow probes from the violation list; taking module scope back out reds the module-rebinding probe;
letting `NOT_A_MODEL` seed again brings back both the phantom pair and the UNKNOWN it manufactured.

### LOCK-BOUNDARY round 11 — the third traversal, and a correction to what round 10 claimed

Two High findings, both real, both fail-opens, both in `test_lock_boundary.py`.

**1. `lock_spans` crossed nested function boundaries — and round 10's commit message said this could
not happen.** That commit asserted *"there are now exactly two function-taking traversals and both
use `_own_nodes`."* **That claim was false.** `lock_spans` is a third, and it was missed because the
search that produced the claim was `grep 'ast.walk(fn)'` — and `lock_spans` does not call `ast.walk`,
it recurses through a hand-written closure. **Searching for a spelling is not searching for the
property**, and the property was "descends into a nested scope". The same lesson this PR has been
prosecuting for four rounds, applied to my own verification of it and not caught by me.

The consequence is round 10's shape exactly: a nested helper's *unlocked* mention of an attribute made
the **enclosing** function's locked write report as unlocked; that write is the SEED; losing it means
an unlocked writer of the pair elsewhere is no longer a violation. All three function-taking
traversals now stop at `FunctionDef`, `AsyncFunctionDef` and `ClassDef`.

**2. `pid_lock_names` accepted shadowed names.** `def writer(p, pid_lock):` binds a *parameter*, and
Python resolves `with pid_lock.mutating(...)` inside that function to the parameter, not the imported
module — as does `pid_lock = other`. The analyser kept `"pid_lock"` in `lock_names` and certified an
arbitrary object as the project lock. The `impostor_alias` probe added in round 9 could not reach
this: it binds the name in a *different* function. **The dangerous case is the same scope, where the
name is right and the binding is wrong.** Names bound by a parameter, assignment, `for` target or
`with ... as` in any scope on the chain are now subtracted — removed rather than resolved, because
this is a certifier and refusing what it cannot prove is the fail-closed direction.

**And the reviewer confirmed, unprompted, the thing this round was asked to check:** *"The stable
432 sites / 6 pairs count does not detect either defect."* It was right to say so. Finding 1 can
remove one seed while a second locked writer keeps the pair alive; finding 2 can add a **false** seed
without changing the count at all. That number has been cited in five consecutive entries as evidence
the tightenings lost nothing — **it is evidence of much less than that**, and it is now retired as an
argument. The probes are the evidence; the count is a description.

Sites unchanged at **432**, six protected pairs. Each fix mutation-checked: restoring the nested
descent drops `(Project, prop_layers)` and loses `span_victim`; restoring the unshadowed names loses
`param_shadow` and `local_shadow`.

### LOCK-BOUNDARY round 10 — two defensible rules that were a hole together

One finding, and it is the one I asked for: *is there another place where the two traversals still
disagree about where a function ends?* Yes — `_bindings` was the last `ast.walk(fn)` in the analyser.

Round 9 fixed `_stored_attrs` to use `_own_nodes` (writes belong to their innermost function) and
added `_bind` (a name meaning two models resolves to neither). Each is right on its own. **Together
they opened a fail-open neither could cause alone**, because `_bindings` still descended into nested
bodies: a name rebound inside a *helper* polluted the enclosing function's map, `_bind` marked it
CONFLICT, and the enclosing function's **locked** write lost its receiver. That write is what SEEDS
the `(model, attribute)` pair. Lose the seed and an unlocked writer of the same pair elsewhere is no
longer a violation — because nothing is protecting it.

**This is a fail-open that works by REMOVING A SEED rather than by excusing a write**, which is why
it survived every self-test aimed at the judgement. All of those ask "is this unlocked write
reported?"; none asked "did the thing that makes it reportable survive?" The new probe is built the
other way round: a correct locked writer whose nested helper rebinds the same name, plus a genuine
unlocked writer of that pair. Reverting `_bindings` to `ast.walk` drops `(Connection, config)` out of
the protected set entirely and the unlocked writer silently leaves the violations — exactly the shape
described, reproduced.

Two lessons, and the second is the one worth carrying:

- **Every traversal in this analyser must agree on where a function ends.** Third instance in two
  rounds: round 9's first attempt attributed a nested write to its enclosing function while the scope
  maps stopped at the boundary, and this is the same disagreement in the remaining direction.
- **A rule can be correct in isolation and unsafe in composition.** `_own_nodes` and `_bind` were each
  argued for on their own merits and reviewed on their own merits. The hole existed only in the
  interaction, which is precisely what a diff-shaped review cannot see and why every round of this PR
  has been requested as a full pass over the whole state.

Sites unchanged at **432**, six protected pairs, no new violations — the fix corrects *which scope*
a binding belongs to, not how many there are.

### LOCK-BOUNDARY round 9 — three fail-opens in the analyser, and a completeness claim with a filter under it

Three findings from the round-9 review, all inside the diff, all in `test_lock_boundary.py`, all
real. Each mutation-checked.

**1. `_stored_attrs` claimed completeness and then filtered.** Round 8's docstring argued that an
attribute write *is* `ast.Attribute` carrying `ctx=Store` — the grammar's own marking, complete by
construction — and the very next line required `isinstance(n.value, ast.Name)`. So
`ctx.project.source_ifc = v`, whose outer node carries `Store` exactly like any other write, never
entered the site list and the gate **accepted** it. *A completeness claim with a filter under it is
not a completeness claim* — and this is the third round running where the fix for an over-narrow
population was itself over-narrow, now at the level of a single `and` clause. Receivers are no longer
filtered here: resolving one is `collect`'s job, and an unresolvable receiver is reported UNKNOWN,
which reds. **The narrow version traded a fail-CLOSED report for silence**, which is the worse of the
two by the same argument this whole PR rests on.

**2. Imports were collected file-wide, not lexically.** `_alias_map` and `pid_lock_names` walked the
whole module, so a function-local `from .. import pid_lock` — how most of this tree spells it —
became a binding for *every* function in the file. One function's `import pid_lock as lock` would
certify an unrelated `lock.mutating(...)` elsewhere, and a reused model alias could resolve another
function's receiver to the wrong mapped model. Bindings now resolve along the real scope chain:
module level, then each enclosing function, then the function itself, with normal shadowing.

**3. One binding per name, applied to every write in the function.** `_bindings` kept the last
binding and `collect` applied it everywhere, so in `p = Project(...)` → `p.source_ifc = v` →
`p = SavedView(...)` the unlocked `Project.source_ifc` write was reclassified by a later line and
left the violations entirely. Resolving per source position needs real flow analysis; refusing to
resolve a name that means two different things does not, and errs the only safe way — UNKNOWN, which
reds. Every real site in this tree has one consistent meaning, so nothing legitimate is affected.

**The first version of fix 2 produced two false positives, and reading the code is what caught it.**
It reported `authoring.py::import_families` and `::content_import` as unlocked writers of
`Project.source_ifc`. Both are in fact correct — the write sits inside a nested helper that holds
`pid_lock.mutating(pid)` and imports it locally, the `run_in_threadpool` shape every `async def`
route here uses. The bug was mine: `_stored_attrs` walked *into* nested functions while the new scope
maps stopped *at* them, so a write was attributed to the enclosing function while its lock and its
import were not. **Two traversals over one tree must agree on where a function ends.** Writes are now
attributed to the innermost enclosing function — which `collect` visits in its own right, so nothing
is lost — while bindings accumulate down the chain, because a nested helper closes over the receiver
its caller fetched. *Had this been reported instead of read, it would have been two invented defects
in working concurrency code.*

Sites scanned **375 → 432**. Fifty-seven more real attribute writes, no new violations, and the six
protected pairs are unchanged before and after — which is the evidence that the scoping tightened
nothing legitimate. Three self-tests are planted and each fix is mutation-checked: restoring the
`Name` filter loses the chained receiver, going back to file-wide imports makes the impostor alias
*vanish from the violations*, and keeping the last binding loses the rebound site.

One implementation note worth keeping: the first scope-chain build was quadratic (a parent map per
call, three calls per function) and the gate stopped finishing. It is memoised per module now.

### LOCK-BOUNDARY round 8 (review) — a certifier that matches on a method NAME, and an inference wearing the shape of a proof

Four findings from the round-8 review, all inside the diff, all real, all fixed.

**1. `lock_spans` certified on the method name alone.** It matched any `<anything>.mutating(...)`, so
`with session.mutating(pid):` — an unrelated object exposing a method of that name — marked every
write in its body as locked. *A certifier that matches on a method NAME is trusting a string anybody
may define*, and it fails in the one direction a certifier must not: silently, toward "yes". The
receiver is now resolved against the file's own `pid_lock` imports (`pid_lock_names`, per file,
because most call sites import it function-locally), so a module with no such import certifies
nothing. An impostor is planted in the self-test population; loosening back to name-matching reds it.
Six protected pairs before and after — the tightening lost no real lock.

**2. Form 7 was an inference wearing the shape of a proof.** Round 6 reasoned: "a variable bound from
an attribute chain touching no mapped attribute name cannot be a mapped instance, because reaching one
by attribute access means traversing a mapped relationship." That holds for chains *through the ORM*
and says nothing about a chain through anything else — `p = ctx.row` on a plain container holding a
`Project` touches no mapped attribute name and is a mapped instance. **It was a tree-wide fail-open,
the same defect as the module predicate it replaced, one layer smaller and better argued.**

The repair is the `test_court_primary` move: *a premise that cannot be checked has already drifted;
stop inferring it and DECLARE it.* What made that affordable is that the population turned out to be
**one site** — measured by deleting the rule and re-deriving, not assumed. `NON_MODEL_RECEIVERS` now
carries that one entry with its reason, everything else falls through to UNKNOWN (fail-closed), and
the ledger is checked in **both** directions: emptying it must bring every declared site back as an
unresolvable unlocked write (so no entry is decoration, and none can rot into an exemption for its
next occupant), and nothing undeclared may need one (the direction round 6 failed in).

`MAPPED_ATTRS` and `_chain_attrs` went with the inference. Its self-test went too — a check on a
variable nothing reads is precisely the thing this PR is about — and the lesson it carried moved to
`MODELS`, which *is* load-bearing: an unconfigured registry resolves no receiver and leaves an empty
seed. **That repointed check immediately failed on a threshold copied from the old one** (34 models,
not the 183 attributes), which is the argument for pointing a check at something live.

**3. `test_ifc_publish_atomic` asserted SOURCE TEXT.** One check read `authoring_shared.py` and looked
for the literal `"os.link(final, backup)"`. Same defect `test_pin_pgnull` exists to record: *asking the
right question and then asserting something adjacent to the answer.* It passes on a spelling and on
dead code alike, and a faithful rewrite (`os.link(src=…, dst=…)`, or the call moved into a helper) reds
it for nothing. It now wraps `authoring_shared.os.link` and runs a real publication through it;
reverting the helper to `os.replace` reds it with the call list empty.

**4. A stale `LOCK-BOUNDARY` comment in `generate.py`.** Two paragraphs had stacked: the first still
claimed generation runs inside the lock and writes the fixed published path, which round 1 stopped
being true. The second, correct one stays. *The same failure as round 6's "`mutating` is reentrant, so
this nests safely" — a comment asserting the property the code no longer has, which reads as reasoning
rather than as the claim it is.*

### LOCK-BOUNDARY round 8 — the fix for an incomplete enumeration is not a longer enumeration

Round 7 replaced `test_lock_boundary`'s `ast.Assign`-only matcher with a three-statement one
(`+AnnAssign`, `+AugAssign`) and called the hole closed. It was the same mistake one size larger.
**Five further spellings of an attribute write were still invisible, and the gate ACCEPTED each:**

```python
p.source_ifc, _rest = a, b        # a Tuple target -- the top-level target is not an Attribute
p.source_ifc, *_tail = xs
(_a, (p.source_ifc, _c)) = v      # nested arbitrarily deep
for p.source_ifc in rows: ...     # `For.target` -- reached by no assignment statement at all
with ctx as p.source_ifc: ...     # `withitem.optional_vars` -- likewise
```

All legal Python, all writes, none of them a target of the three statements the matcher knew.

The repair is not a sixth case. **An attribute write is not a list of statement types — it is
`ast.Attribute` carrying `ctx=Store`, which is how Python itself marks one, in every form it has.**
`_stored_attrs` now yields exactly those, and admits nothing else: a read (`v = p.x`), a call
argument (`f(p.x)`) and `del p.x` carry `Load`, `Load` and `Del`. There is no seventh form to miss,
because the set is no longer a list somebody maintains. Sites scanned went **346 → 375** — twenty-nine
more real attribute writes in the tree, none of them a new violation.

*This is the third round in a row where the previous round's fix was the next round's defect, and
the first where the shape repeated at the same layer rather than a deeper one.* Round 6 removed a
module-level predicate for excluding what it had not proved; round 7 widened a statement matcher
from one spelling to three; round 8 stopped spelling. The lesson the first two did not quite reach:
**widening an enumeration leaves an enumeration, and its remaining blind spot is invisible in exactly
the same way** — the count looked more complete each time, and 331, 346 and 375 are all confident
numbers. Only the last one is derived from something that cannot silently shrink.

Seven non-plain spellings are now planted unlocked in the self-test population, and narrowing
`_stored_attrs` back to the three statement forms reds two checks, naming the five it stopped seeing.

Worth stating because it is the *reason* only this one site needed fixing: the analyser's other two
`ast.Assign`-only matchers — Form 7's `NOT_A_MODEL` exclusion and the model-resolving pass — fail
**closed**. A form they miss leaves the receiver unresolved, which the gate reports as UNKNOWN and
reds. `collect` was the only one where a missed form meant a site was never looked at.

### LOCK-BOUNDARY round 7 — a `finally` that deletes the only copy, and two spellings of a write

Three fixed, two declined. The first is the most serious defect this PR has produced, and round 6
made it worse.

**1. The rollback backup was deleted even when the restore FAILED.** The `finally` unlinked it
unconditionally. If `os.replace(backup, final)` raises, the published path is left holding bytes the
system refused **and the backup — the user's previous model — is destroyed.** Round 6's `os.link`
sharpens it: backup and `final` begin as one inode, so after the promotion the backup holds the
**last** reference to the old bytes. *Cleanup in a `finally` runs on the branch where cleanup is
exactly the wrong thing to do* — the one case that still needs the file is the case that got there by
failing. The backup is now removed only when publication succeeded **or** restoration succeeded; a
surviving `.rollback-*` is evidence that a publication failed and could not be undone, not litter.

**2. `test_lock_boundary` matched `ast.Assign` only.** `p.source_ifc: str = v` is an `AnnAssign` and
`p.source_ifc += v` an `AugAssign` — both writes, and the augmented one is *literally* a
read-modify-write, the shape the gate exists for. Neither ever entered the site list, so the gate
**accepted** them. Same defect as round 6's module predicate one layer down: *a population derived by
matching one spelling of a thing silently excludes the others, and the exclusion never appears in the
output.* Sites scanned went **331 → 346** — fifteen attribute writes the gate had never seen. Both
forms are now planted unlocked in the self-test population, and narrowing the matcher back to
`ast.Assign` reds two checks.

**3. The hard-link continuity claim was unconditional.** It is a property of the hard-link path; on a
filesystem without hard links the helper falls back to the rename and the window returns. Qualified.

**Declined, both real, both about the proforma module rather than this diff:** a full-budget `PUT`
can still overwrite a concurrent sync's hard lines (needs a revision token, i.e. a client contract
change); and `source_ifc_path` / `takeoff_file` / `open_model` run before the lock in the model-sync
route, so a publication can swap the IFC between the read and the commit. Both predate this PR, both
need their own change, and both are tracked.

### LOCK-BOUNDARY round 6 — the gate's own look-at predicate, and a fix that cost an unrelated property

Three real findings from a full re-review of the head. Two are defects **inside earlier rounds of this
PR**, which is now the pattern rather than the exception.

**1. The published path was briefly ABSENT, and that is not the same property as "never partial".**
Round 4 took its rollback backup with `os.replace(final, backup)`, so `source.ifc` did not exist
between that rename and the promotion. `bake_layers` calls `project_with_source` **before** it takes
the lock, and that helper raises 409 *"project has no accessible source IFC"* on a missing file — so a
concurrent read could be refused during a publication that then **succeeded**. The backup is now an
`os.link` — the same inode under two names, so the path stays present and `os.replace` still swaps it
atomically. **That continuity is a property of the hard-link path, not an unconditional guarantee:**
on a filesystem without hard links (FAT, some network mounts) the helper falls back to the rename and
the window returns, because copying what may be hundreds of MB on every publish is the worse trade.
The fallback costs a spurious 409 on a concurrent read, never data. *A fix for one property can cost an unrelated one that nothing was asserting* —
the bare rename had given continuity for free since the beginning, and round 4 spent it without
noticing.

**And the first test written for this was vacuous.** It asserted no `<missing>` observation during a
normal publish; reverting the fix left it **passing**, because two back-to-back renames take
microseconds and the reader polls every millisecond. *A check that cannot observe the interval it
describes reports on nothing.* It now tests the primitive with a deliberately wide window — with a
rename the reader must catch the gap, with a link there is no gap at any width — plus an assertion
that the helper is what uses the link.

**2. `test_lock_boundary`'s module filter was the defect its own docstring warned about.**
`touches_orm` skipped any module importing neither `models` nor `Session`, justified as *"provably
incapable of the defect"*. That is **false**: `def stamp(p): p.source_ifc = v` holds a mapped instance
its caller passed in, with neither import. Such a file was skipped whole, so the write never reached
`verdicts` and could not be reported UNKNOWN — **the fail-closed rule was defeated one layer above the
code enforcing it.** The docstring quotes CLAUDE.md's lesson that *a predicate deciding what to LOOK
at is more dangerous than one deciding what to report* two lines before violating it.

The module skip is gone. Two per-receiver rules replace it, both derived and provable in both
directions: `self` inside a class resolves to that class when it is mapped and to a proven non-model
when it is not; and a receiver bound from an attribute chain touching **no** mapped attribute name
cannot be a mapped instance, because reaching one by attribute access means traversing a mapped
relationship. Deliberately not *"an attribute chain is not a model"* — `project.owner` would be — so
the test is against the registry, not the shape.

`MAPPED_ATTRS` needs `configure_mappers()`: the first probe returned **0 of 183**, because mappers
configure lazily. An empty set would mark every chain "provably not a model" — a fail-open across the
tree — so a self-test asserts it is populated before any verdict prints. The removal itself has a
regression test with a mutation: reinstating the predicate makes the planted site disappear.

**3. Wording corrected in three places.** "`os.replace` undoes itself for free" overstates it: a rename
is cheap to undo — one more rename, nothing copied — but nothing undoes it automatically.

**Declined, with reasons:** the object-storage arm of a failed commit is the residual already recorded
in the helper's docstring and filed as **#558**, blocked on a retention decision that is the
maintainer's; and `pid_lock._advisory` degrading to in-process on an acquisition error is a
pre-existing, documented property of that module affecting all eleven call sites, not something this
PR introduced — it is tracked separately rather than changed inside a PR already six rounds deep.

### LOCK-BOUNDARY round 5 — the rollback had a branch that existed doing nothing

Round 4 made publication failure-atomic by moving the previous `source.ifc` aside and putting it back
on any exception. Review found the half that does not exist: **when there is no previous file, there
is no backup, and the `except` branch did nothing at all** — while `os.replace(staged, final)` had
already put the refused bytes at the published path. That is every FIRST publication: blank create,
first upload, first generate, first `ensure_model`.

*The inverse of a rename is a rename OR a delete, depending on what was displaced, and a rollback
written only for the first case is a no-op in the second.*

The orphan is the smaller half. The larger one is what it does to the NEXT publication: that one finds
`final.exists()` true, adopts the refused bytes as its backup, and on its own failure **restores them**
— promoting a model the system refused into "the previous model worth keeping".

**Why the round-4 test could not see it.** `test_ifc_publish_atomic`'s rollback arm calls `reset()`,
which writes the old model to the published path every time, so `final.exists()` was always true and
the no-backup branch was never entered. *A rollback test that always has something to roll back never
exercises the branch where there is nothing.* The new arm deletes the published file first, asserts the
failure leaves nothing behind, and then asserts the follow-on — a later successful publish has no
refused model to inherit. Deleting the fix reds it with `source.ifc survived holding 4144 refused
bytes`, so the branch is exercised rather than merely present.

### LOCK-BOUNDARY round 4 — a comment that asserted the safety property the code lacked

Two Major review findings, both real.

**The publication and the budget seed were two lock intervals, not one.** `publish_source_ifc` took
the lock and RELEASED it; a second `with` then re-took it — and the comment beside it said
"`mutating` is reentrant, so this nests safely", describing a nesting that did not exist because the
publisher had already returned. **A comment can assert the exact safety property the code lacks, and
it reads as the reasoning rather than as the claim it is.** The gap lets generations A and B publish
in order A, B — so the model is B's — and then A, still to seed, finds `dev_budget` empty and seeds
it from A's metrics: model B priced by budget A, reported by nothing. Now one outer interval, with
the publisher re-entering it — which is what the comment had claimed all along.

**Publication was not failure-atomic.** A rename is CHEAP to undo — one more rename, no data
copied — but nothing undoes it automatically, and `put_stream` and
`commit` do not. A failure after the rename left the published local path — the file `bake_layers`
and the converter open — holding the new bytes while nothing else had been published. *Atomic at
each step is not atomic across the sequence.* The previous file is now kept aside and restored on
any failure.

**What that does NOT cover is stated in the helper rather than implied:** if `put_stream` succeeds
and the commit then fails, object storage holds newer bytes than the local file and the row. Storage
is the durable copy rather than what readers open, and the next successful publish overwrites it —
but it is a real window, and closing it means publishing immutable versioned artifacts and moving
the pointer last, which is a design change rather than a guard.

`test_ifc_publish_atomic` gains three checks: a midway failure raises rather than reporting success,
the previous model is restored byte-for-byte, and no rollback scratch is left. Removing the restore
reds the second one (`final is 4144 bytes, expected the old 57`) — the guard is exercised, not
merely present.

### LOCK-BOUNDARY round 3 — the gate's own seed was failing open, and it hid three live defects

Round 1's gate reported nothing about `Project.dev_budget`, and the reason was in the gate, not the
code. `generate._finalize_generated` wrote it entirely inside the lock — but took `p` as an
**un-annotated parameter**, so the receiver was UNKNOWN, the pair never entered the protected seed,
and the three unlocked writers in `routers/proforma.py` were never compared against anything.

**UNKNOWN was fail-CLOSED where it could excuse an unlocked write and fail-OPEN where it could
establish that a field is protected at all.** *A predicate that decides what to LOOK at is more
dangerous than one that decides what to report* — and a seed is exactly such a predicate, so the gate
was not exempt from the rule it enforces. Found by running the analyser and reading its output, not
by any test: nothing was red.

Closed in both halves, because either alone is useless. A fifth binding form (a parameter's type
annotation) put the pair in the seed, which immediately named `proforma.put_dev_budget`,
`sync_gmp_to_hard` and `sync_model_to_hard`; all three now hold `pid_lock.mutating(pid)`. **Note
which half did the finding: a one-line signature annotation turned a silent gate into one that named
three live defects.**

The defect itself is the `connections` shape again on money. `put_dev_budget` replaces the whole
budget blob from the editor's form; the two `sync_*_to_hard` routes rebuild only the `hard` lines and
preserve soft/acquisition/contingency. An editor saving the budget while someone clicks "sync GMP"
lost one of the two silently — each caller's 200 was true of its own write. A lock and not a
compare-and-swap, for the same reason `connections` chose one: the edits are claims on different line
categories of one blob, so serialising lets both survive where a 409 would refuse an edit that
conflicts with nothing.

`test_rmw_sweep`'s ledger is updated from OPEN to LOCKED for the two sync routes, with the reason
recorded: that sweep could only ever see two of the four writers, because the third is a plain
replace and the fourth a conditional seed. **A pair is only as closed as its widest member, and that
derivation could not see the widest.** Sweep open count 4 → 2; the two remaining are
`drawingset.revise_sheet` and `share_scenario`.

### LOCK-BOUNDARY round 2 — the lock covered the pointer and not the bytes

Review on #557 caught that the first pass locked the `source_ifc` POINTER and left the file
PRODUCTION outside. Every producer wrote the published `source.ifc` directly: `import_rvt` with a
bare `write_bytes`, both massing generators and the blank create onto the fixed path, and the upload
through `stream_to_path` — which does write `<dest>.part` and rename, but **the part name is derived
from the destination**, so two concurrent uploads to one project share `source.ifc.part` and
interleave into it before either renames. *A staging name that is a function of the destination is
not staging, it is a second shared path.*

`bake_layers` and `/edit` take the project lock and then open `p.source_ifc`, so a reader could open
a file being rewritten underneath it. Locking the assignment alone moved the race rather than
closing it — the same correction PR #552 forced on `under_pid_lock`, one layer down: *a lock proves
something about the interval it spans, and the interval has to contain the bytes as well as the
pointer.*

Now every producer writes to a unique staged path and `authoring_shared.publish_source_ifc` promotes
it — `os.replace`, storage publish, pointer, commit — inside one critical section. One helper rather
than the same critical section at five producers, for the reason `connections._lock_key` is one.
`staged_ifc` is a context manager so a producer that fails before promoting cannot leak its staged
file; this tree has already run a disk out on orphaned scratch once.

`services/api/test_ifc_publish_atomic.py` is the behavioural half, and it exists because
`test_lock_boundary` structurally cannot see this: an AST analyser can confirm every
`p.source_ifc = ...` sits inside the lock and says nothing about which path the bytes went to — the
whole defect passes it. The test polls the published path while a producer runs and asserts the
reader only ever sees a complete old or complete new model; the mutation writes straight to the
published path and the reader catches partial files, so it measures the staging and not the timing.

### LOCK-BOUNDARY — G-11 was closed yesterday and five writers of the same column were still unlocked

`test_rmw_sweep` derives **read-modify-writes**. `p.source_ifc = str(ifc_path)` reads nothing — it
installs a new pointer — so it was never in that population, and neither was the conditional-create
`if not p.source_ifc: ...`. G-11 was closed on 2026-09-13 by locking every `source_ifc`
read-modify-write in `routers/authoring.py`; **five writers of that same column were left open, two
of them inside that file.** A pointer swap that reads nothing still orphans the version a concurrent
`bake_layers` is deriving from.

Now locked: `authoring.upload_source_ifc`, `authoring.import_rvt` (both `async def`, so the lock is
taken off the event loop via `run_in_threadpool` — the v0.3.703 SSE failure otherwise),
`generate.create_blank_model`, `generate.ensure_model`, `generate._finalize_generated`.
`generate.py` had no `pid_lock` import at all.

**`ensure_model` was the sharpest.** It is a CHECK-THEN-ACT, not a read-modify-write: it reads
`source_ifc`, concludes from its emptiness that no model exists, and installs a blank one. Unlocked,
two concurrent calls both read empty, both generate over the same fixed `source.ifc` path, and both
answer `created: true`. The lock spans the DECISION — the early returns are inside it — because a
lock taken after the branch protects nothing this route does.

**The first diagnosis was wrong, and the correction is the point.** It looked like a FILE boundary:
`generate.py` contained no lock at all, so the closure seemed to have stopped at the edge of the file
being worked in. It had not — two of the five are in the "closed" file. What bounds the coverage is
the SHAPE. *A coincidence that corroborates a wrong theory is the expensive kind, because it ends the
search.*

`services/api/test_lock_boundary.py` derives the rule from the code rather than a ledger: a
`(model, attribute)` pair locked in **any** writer must be locked in **every** writer. It resolves
each receiver to a mapped model — four binding forms, every one added because a probe reported
UNKNOWN rather than because it was anticipated — and fails closed, because a resolver that guesses
turns each of those into a confident wrong answer. Receiver resolution is load-bearing, not tidy:
`modules.save_view` writes `.config` and matches `Connection.config` by NAME, but it is a `SavedView`
and not a violation at all.

**It states its own limit rather than hiding it:** this finds INCONSISTENT protection, not ABSENT
protection. `Project.dev_budget` has four writers and no lock anywhere, so it never enters the seed
and this gate is silent on it — the sweep names two of those four instead. Each derivation is blind
where the other sees, which is why both exist.

### Two admins saving one connection: one of the two saves vanished

`Connection.config` had **two** writers and neither took a lock. `update_connection` merges the
body's keys into the blob — keeping a stored secret where the form sent it blank — and
`put_mappings` rewrites the whole blob to replace its `mappings` key. So an admin saving credentials
while another saved field mappings lost one of the two, silently: each caller's 200 is true of its
own merge. Gap G-12's `connections` pair is closed; the sweep's open count drops six to four.

**A lock, not a compare-and-swap — deliberately the opposite call from the register rows.** There
the whole row is one logical edit, so a stale write should be REFUSED with a 409. Here the two
writers touch near-disjoint keys, credentials against `mappings`, so serialising lets the second
merge onto the first's committed blob and **both survive**, where a 409 would refuse an edit that
does not actually conflict. *The right control depends on whether the concurrent edits are rival
claims on one value or independent claims on different ones.* `connections` carries no token to swap
on in any case — only `created_at`.

**Two checks, and the measurement showing neither is sufficient alone.**
`services/api/test_connection_lock.py` asserts both edits survive and that neutering the lock loses
one. Then two mutations were run:

| mutation | sweep | behavioural test |
|---|---|---|
| one route's lock deleted | ❌ red | ❌ red |
| the two routes lock on **different keys** | ✅ **green** | ❌ red |

*Static analysis can see that a lock is present; only behaviour can see that it is the SAME lock.*
`under_pid_lock` asks whether each mention sits inside *a* `pid_lock.mutating(...)`, and under the
second mutation both still do — "a lock one side does not take protects nothing" wearing the shape
of a lock. Hence `_lock_key` is a shared helper rather than an f-string at each call site.

**And the first mutation found a hole in the gate itself.** `test_rmw_sweep`'s "every site this
ledger calls locked IS lexically under `pid_lock.mutating`" derived from `IFC_PIPELINE` only — the
one ledger that had LOCKED rows when the check was written. The two new LOCKED rows landed in
`CROSS_FIELD`, where **nothing asserted them**: the status was prose again, and deleting either lock
left the sweep green. The derivation now spans every ledger, taking verified locked sites from 6 to
18. *A gate scoped to the ledger that existed when it was written silently stops covering the
ledgers that arrive later* — and only mutating the shipped fix surfaced it.

### Two people authoring at once: one of them lost the whole model version

Six routes in `services/api/src/aec_api/routers/authoring.py` — `bake_layers`, `import_families`,
`import_family_pack`, `place_family`, `content_import` and the shared `_restore_version` behind
undo/redo — read `Project.source_ifc`, produced a NEW IFC version from it, and wrote the pointer
back, all outside the per-project lock. **Five sibling routes in the same file do the identical
thing inside `pid_lock.mutating(pid)`**, and `edit` carries a comment describing exactly this race.
So two concurrent authoring operations each derived from version N, each wrote their own N+1, and
the second commit orphaned the first user's work — **silently, because each caller's response is
true of its own run**. What is lost is a baked override set, an imported family pack, a placed
family, a content import, or a restored version: the model the product exists to author.

All six now hold the lock across the whole read → derive → apply → pointer-swap. Gap G-11 is closed
and the sweep's open count drops from twelve to six.

**The lock is proved by behaviour, not by its presence.** `services/api/test_authoring_lock.py`
runs two concurrent bakes against a stubbed recipe and asserts the second reads the FIRST's output;
neutering `pid_lock.mutating` makes both read the same base. A test that grepped for the lock would
pass on a lock spanning only the assignment — the defect review caught one level up on PR #552.

**Three things the uniform fix got wrong**, each corrected before it shipped:

- **Two of the six are `async def`.** `pid_lock.mutating` is synchronous and blocks on a Postgres
  advisory lock, so taking it inline would park the event loop behind somebody else's upload —
  *a rare lost model version traded for a routine server-wide stall*, which is the v0.3.703 SSE
  failure arriving by a different door. Both now run the locked section through `run_in_threadpool`.
- **`import_family_pack` first had `db.commit()` outside the lock.** An uncommitted pointer swap is
  invisible to the next lock-holder, which reads the old version and derives from it — the same race
  moved rather than closed. *A lock proves something about the interval it spans, and that interval
  has to end after the write is durable.*
- **`_restore_version` re-read the column once more after the lock released.** Harmless today, and
  the sweep refused to certify it anyway — *a certifier that reasons about which stragglers are
  harmless is one bad reading away from blessing one.*

The undo/redo lock sits in the shared helper rather than in `edit_undo` and `edit_redo`: the
narrowest place that can carry the fact, so both routes inherit it instead of two call sites having
to remember.

### The re-key voided one of the gate's own regression checks, silently

Found in review, and it is the same defect the pull request exists to fix, committed by the fix.

The gate carried a regression check that the share-token view counter is no longer an ORM
read-modify-write, written as `("…client_portal.py", "model_fragment") not in ORM`. That was true
while `ORM` held `(path, function)` pairs — and it stayed true, permanently, the instant this
change re-keyed `ORM` to `(path, function, attribute)`: **a 2-tuple is not a member of a set of
3-tuples no matter what is in it.** Reinstating the original `row.view_count += 1` would have left
those three lines printing PASS.

*A membership test written against a key SHAPE fails OPEN the moment the shape changes*, and
nothing about the diff looks like it touched that check. The projection to `(path, function)` is
now derived by a named function rather than written out at the call site, and the gate plants a
synthetic site and requires the projection to find one that raw membership cannot — so the shape
bug has to come back through an assertion that is watching for it.

The canary's first draft was itself conditioned on the real population, and reinstating the genuine
regression made it report *"the projection did not distinguish the planted site"* — blaming the
analyser for a defect in its subject. It now runs on a two-element synthetic population and touches
the tree not at all. *A check whose failure message can misdiagnose is worse than one that stays
silent, because somebody acts on it.*

### The concurrency ledger was keyed by function, and reasoned about one field at a time

`services/api/test_rmw_sweep.py` keys its read-modify-write ledgers by `(path, function)`. **Six
functions write more than one field**, so a single status and a single sentence covered several
distinct races — and the sentence names whichever field the author happened to be looking at. The
rest are exempted by reasoning about a different line.

That is this file's own subject one level up: *an exemption that reasons about part of its subject
and reports on all of it.* And it had already hidden something. `connections.update_connection` was
EXEMPT because "`body.name or c.name` is a PATCH keeping an unsent field" — true of `name`, and
silent about `merged = dict(c.config or {})` … `c.config = merged`, an accumulating merge that keeps
a stored secret where the form sent it blank. `connections` carries no version column at all, only
`created_at`.

Worse, it is the **second** writer of the blob `connections.put_mappings` writes, which was already
listed OPEN. One admin saving connection settings while another saves field mappings loses a write,
and whatever control that table eventually gets must cover both — *a lock one side does not take
protects nothing*, the lesson the `dev_property` pair paid for a day earlier.

The key is now `(path, function, attribute)`. The derived population went **32 → 41** and the open
count **11 → 12**; the count going up is the sweep working rather than failing. Two side effects
worth naming: `under_pid_lock(*k)` now takes the column straight from the key instead of being told
it a second time, and the `dev_property` pair is derived by `k[2] == "dev_property"` rather than by
searching for that string **inside the reason prose** — *a derivation over prose, in the file whose
own lesson is that a count derived by grepping prose is prose.*

The other five multi-field functions were re-read and their exemptions hold for every field, now
said per field rather than inherited: `bim._with_kind` sets non-column serialisation fields,
`verification.set_status` and the three `cloud` sites take whole values or fallbacks from a provider
response. `cloud_refresh_profile`'s `cloud_roles` and `cloud_tier` get their own sentences despite
reaching the same verdict, because they are authorisation-bearing and inheriting a reason about a
display name is how that stops being examined.

A check now asserts that at least one function's fields carry **different** statuses — the thing the
old key could not express, so the extra column is load-bearing rather than decorative. Its failure
message names both causes, because today `update_connection` is the only such function and closing
it legitimately would red the check for the opposite reason: *a check whose failure message can
misdiagnose is worse than one that stays silent, because somebody acts on it.*

### Two people pressing "promote" on one markup got two RFIs, and one of them vanished

`bim.promote_markup` checked `if m.topic_id: 409` and then claimed the back-link with a plain
`m.topic_id = t.id`. The check reads the session's own copy, and `SessionLocal` is
`expire_on_commit=False`, so a request that loaded the markup before a concurrent promote committed
still sees `None` however long it holds it. Both requests therefore passed the guard, both minted an
RFI Topic, and the later write won — leaving **two Topics for one markup, the first orphaned**
because nothing points at it any more, with both callers told 201. A double-click is enough; no load
is required.

It now claims the link with a conditional `UPDATE ... WHERE topic_id IS NULL` and rolls back the
flushed Topic on a loss, so the loser leaves nothing behind. That is not a new idea here — it is
exactly what `modules.promote_comment` was given when the same defect was fixed there, one module
over. **This instance was found by the read-modify-write sweep's derivation, not by anyone reading
the route**, which is the argument for deriving a population rather than listing one: *an
already-solved defect living on elsewhere is the cheapest kind to close and the easiest to never
look for.*

Two smaller things the fix exposed. The Core `UPDATE` bypasses the ORM, so the session's `m` kept
its null `topic_id` and the response would have reported the markup unpromoted **in the very call
that promoted it** — a `db.refresh` before the response fixes that. And closing the site made its
own ledger entry stale, which `services/api/test_rmw_sweep.py` reported before the ledger was
touched: *closing a gap has to force the record to move, or the tree ends up describing a defect
nobody can still find.* Open gaps 12 → 11; G-12 five → four.

### Two people editing one record both saved; only one of the edits survived

RMW-SWEEP. `transition` was one instance of a class, and PR #551 fixed only that instance. The shape
is: **read a column, compute a new value FROM what you read, write it back under `where(id == rid)`
alone.** Nothing holds the row still in between, so two callers both read the old value and the
second write erases the first — and *both* callers are told they succeeded. Reproduced against the
real functions before anything was written:

```
set_element_guids: A reads ['GUID-A'] · B commits ['GUID-A','GUID-B'] · A commits ['GUID-A','GUID-C']
                   FINAL ['GUID-A','GUID-C']        GUID-B survived? False
link_record:       B commits a link · A commits a link · FINAL holds one of the two
```

*A lost update that refuses one caller is nearly fixed; one that tells both they succeeded has to be
found twice* — the same severity inversion the seeding sweep recorded, where a primary key refuses
the loser and a non-unique index refuses nothing.

**Five sat on the register row**, and `update_record` is the one that matters. It is the path the
register's inline text and select cells use; it writes `{**what we read, **what you sent}`; and the
control `docs/security/threat-model.md` names for exactly this threat — `expected_modified_at` — is
**opt-in**, passed by one of five web call sites. So two people editing *different fields* of one
record both merged onto the same pre-image and the second erased the first person's field. The
documented control was real and it was not on the path people use.

All five now route through `modules._cas_row_edit`, which re-reads, recomputes, and writes under
`WHERE id = ? AND modified_at = ?` — a compare-and-swap in SQL rather than a check in Python.

**Three decisions in it are worth naming, because each has a wrong-looking alternative.**

- **The swap is on `modified_at`, not on the collection.** `element_guids` is a JSON column and JSON
  equality is not comparable the same way on SQLite and Postgres — the exact trap `with_for_update()`
  is, which Postgres honours and SQLite silently ignores. `modified_at` is a plain timestamp on both.
  And **every register-row writer sets it**, which is now asserted rather than assumed: the dynamic
  register table declares the column with **no `onupdate=`**, so that coverage is a property of the
  call sites, and one writer forgetting it would make this predicate match a row somebody else had
  just changed — *a lock that looks present.*
- **It retries rather than refusing.** A lost `transition` race means the action genuinely is no
  longer available, so a 409 is honest. "Add GUID-C" is still the caller's intent after somebody else
  adds GUID-B, so re-reading and re-applying gives the user what they asked for.
- **…except where the caller does not own the transaction.** A retry rolls back, and
  `update_record(commit=False)` has callers (`responsibility`, renaming a role column across every
  row) that have already staged rows in that transaction. Rolling those back and then succeeding here
  would commit a partial edit and report it as whole — *the very shape of bug this exists to remove.*
  So `commit=False` gets one attempt and a 409, which aborts the caller's whole edit.

**`revise` was hiding a second defect behind the first.** Its "record already revised" check was
itself a read-then-write: two concurrent revises both passed it, both minted a revision row, and the
second supersede write erased the first's `superseded_by` — leaving two live revisions of one record,
each believing it is the only one, and only one findable from the source. The CAS refuses the second.

**Two off-register instances were found, and one of them was not a race at all.**
`client_portal`'s share-token view counter was `row.view_count = (row.view_count or 0) + 1` — two
people opening the same link both read 7 and both wrote 8, so the count drifts *down* under exactly
the load that makes it interesting. It moved into SQL (`view_count + 1` evaluated by the database),
with no CAS and no retry, because there is then nothing read in this process for anyone to
invalidate. The other was the opposite of what the sweep was looking for: `proforma.save_property`
wrote `p.dev_property = body` **wholesale**, and `realestate.save_appraisal` keeps `appraisal` inside
that same blob — so every ordinary re-save of the property tab deleted the saved appraisal overrides.
No concurrency required. *A write that reads nothing cannot lose an update — it just deletes one.*

*That sentence is about the code as it WAS, and review pointed out it stops being true of the fix:
carrying `appraisal` across means reading `dev_property` first, so the repaired route can now lose a
concurrent appraisal save — a smaller fault than the one it removes, on a table with no concurrency
token, and it is filed as open rather than implied away.* The same round found the response still
answering with `body` while the merged dict was what got stored — persisting one value and returning
another, which is the kind of mismatch that gets discovered from two screens away.

**What the sweep could NOT reach is named rather than left silent**, because that is precisely how
the seeding sweep lost four sites. `Scenario.shared_with` (a share grant) and `Project.dev_property`
(the appraisal merge) still lose a concurrent write: neither table carries a `modified_at`, so the
register row's token does not exist for them. They are frozen in `test_rmw_sweep.py`'s `BAND_2`
ledger and filed as gap **G-10** — the set cannot grow silently, because a new instance reds the
build.

**The gate**, `services/api/test_rmw_sweep.py`, derives the population by AST with transitive taint
from `get_record`, fails **closed** on an `update()` whose target it cannot resolve, and runs itself
against the shipped pre-fix bodies of `set_element_guids` *and* `update_record` before it may print
any verdict — the second because `update_record` splats `**vals`, which is the blind spot that cost
PR #551 a review round. The behavioural half asserts the **outcome** through the real functions on a
hand-built interleaving, and a mutation removing the swap predicate must lose the GUID again.

**The review round found three more things, and two of them were holes in this gate rather than in
the code it guards.** The swap-predicate test asked only whether the `WHERE` named a non-identity
column — so `WHERE deleted_at IS NULL` read as a compare-and-swap though it compares against a
constant and swaps on nothing: *a fail-OPEN verdict inside a gate whose whole design is failing
closed.* Tightening it then flagged two correct writers, which taught the distinction the first two
drafts had collapsed: a constant predicate on the column being **written** (`promote_comment`'s
`topic_id IS NULL`) is a real guard, and one on a column the statement does not write is a filter.
And the token-coverage check searched the function's text for `"modified_at"` — which a **docstring**
satisfies, and every function here has a long one. It now reads the assignment with docstrings
stripped and demands `_next_stamp`; strengthening it immediately found `transition`, whose stamp sits
in a dict literal the detector could not see. *Three shapes write that column and the first draft of
the detector knew two.*

**The third was a real hole in the lock, not the token.** `_now()` can equal the row's existing
`modified_at` — same microsecond, or an NTP step backwards — and then the winning write leaves its
own predicate reusable by the writer it just excluded. Every register-row writer now stamps through
`modules._next_stamp`, which is strictly monotonic per row. *Rare is not impossible, and a
concurrency control that is correct except under contention is wrong exactly where it is
load-bearing.*

**And widening the gate's ORM derivation caught this pull request hiding a site from itself.** The
`save_property` fix hoisted its read into a local (`prior = p.dev_property or {}`), and the analyser
only looked for the object named directly on the right-hand side — so the commit that created an RMW
site removed it from the count in the same edit, and nothing said anything. *Hoisting a read into a
variable is the cheapest way to make a pattern-matching check stop matching, and it is what a tidy-up
commit looks like.* With taint propagated one hop the population went **12 → 33**, and the 21 new
sites are read and classified rather than counted.

**One of them is the biggest thing this round turned up, and no reviewer asked for it.** Twelve routes
read `Project.source_ifc`, derive a new IFC version from it, and write the pointer back. **Six wrap
that in `pid_lock.mutating(pid)` and six do not** — and one of the six that does carries the comment
*"same RMW race as /edit — serialize per project"*, so the control exists, is named in the threat
model, and covers half its population. Two concurrent `place_family` calls lose one placement with
both callers answered 200. It is **filed, not fixed** (gap G-11, roadmap RMW-LOCKGAP): wrapping six
routes that do long IFC I/O is a different blast radius from the register row, in a lane this change
did not otherwise touch. The set is frozen instead — the gate asserts the split in *both* directions,
so a new unlocked writer reds the build and closing one of the six forces the ledger to be updated
rather than leaving a recorded gap that no longer exists.

**A second review round found four more, and three were the gate reporting safety it had not
established.** Each is the same failure wearing a different mask, and each was introduced by the fix
for the one before it:

- **The conditional-write exemption protected the wrong column.** The first tightening made a
  constant predicate count as a swap when the statement *writes* that column — correct for
  `promote_comment`. But `.where(status == "open").values(status=…, element_guids=<from the read>)`
  also satisfied it, and a concurrent `element_guids` change does not move `status`, so the stale
  write still lands. The guard now has to cover **every** column carrying a read-derived value, and
  a splatted `**vals` — which hides the column-to-expression mapping — makes coverage unprovable
  rather than assumed. *Fixing an over-broad rule by narrowing one clause can leave the same hole one
  column to the left.*
- **The stamp check asked "somewhere", not "every".** It returned on the first valid
  `modified_at=_next_stamp(...)` anywhere in the function, so a writer with two updates passed while
  the second omitted the stamp. Now validated per update — and doing so immediately failed
  `_cas_row_edit`, whose stamp is a *subscript assignment* into a dict built earlier. That is the
  third shape, and **every draft of this detector has known one fewer than exist**.
- **The lock check measured the write, not the interval.** `under_pid_lock` asked only whether the
  `source_ifc` assignment sat inside `pid_lock.mutating`. A route can read the pointer, spend a
  minute deriving a new IFC from it, and *then* enter the lock to assign — passing a check that
  looks at the write alone while two callers derive from the same old version. Every mention of the
  column, read or write, must now be inside. *A lock proves nothing about the statement it contains;
  it proves something about the interval it spans.* All six certified routes survive the stricter
  test, which is the answer that makes the certification worth having.
- **And the open-gap count was computed by grepping its own prose.** `_open` matched the substring
  `"OPEN"`; one entry had been written `"Open"`; the gate reported **13** open sites where there are
  **14**, and the threat model inherited the wrong number. Status is now a structured field with a
  declared value set, asserted, so a typo reds the build instead of deleting a gap from the tally.
  The six non-IFC sites that tally had been under-reporting are now their own named gap (**G-12**),
  `bim.promote_markup` among them — which is `promote_comment`'s pre-fix shape, a live instance of a
  defect already solved one module over.

**And the monotonic-stamp branch was itself untested until it was asked to be.** `_next_stamp`'s
`prev + 1µs` path runs only when the clock fails to advance, so no ordinary test reaches it — *a
branch that only runs under contention is a branch only production runs.* It is now exercised against
the real table with the clock frozen, which also settles a question the fix quietly raised: that path
returns a **tz-aware** datetime while SQLite hands `modified_at` back **naive**, and if the two
rendered differently the next `WHERE modified_at = <what we just read>` would match nothing and every
edit would 409.

**A third review round found two more, and both were the gate accepting a SHAPE where it meant to
check a FACT.** Neither is a live defect in this tree — the population and every count are unchanged
— which is precisely what makes them worth recording: each one would have gone quiet on the *next*
ordinary edit, with every number still printing.

- **Naming the guard counted as calling it.** The stamp check asked whether the name `_next_stamp`
  occurred anywhere in the `modified_at` expression, so `_next_stamp(None)` satisfied it in all three
  shapes. That argument is not a near-miss: `None` skips the `now <= prev` comparison inside the
  helper and it returns a bare `_now()` — the exact unguarded clock the helper exists to replace.
  Under a frozen clock the writer re-emits the token it just read, the loser's CAS predicate still
  matches, and the swap protects nothing while the gate reports it protected. The argument is now
  traced back to the row's prior `modified_at`, through a local if it was hoisted into one, and all
  three shapes route through one function so a fourth inherits the rule. *Naming the guard is not
  calling it, and calling it is not feeding it.*
- **Both taint analyses walked `ast.Assign` and not `ast.AnnAssign`.** An annotated
  `rec: dict = get_record(...)` breaks the Core chain and the write behind it classifies as PLAIN;
  an annotated `prior: dict = p.dev_property` drops the ORM site out of the population *entirely*,
  taking its ledger entry with it — at which point the staleness check would have blamed the ledger
  entry and pointed the next reader at the wrong file. **The blind spot is one `mypy --strict` pass
  wide.** Adding annotations changes no behaviour, is the most ordinary edit in the language, and
  would have silently emptied both derivations. *A gate whose reach depends on the syntax somebody
  happened to use is measuring the author, not the code.*

The ORM analyser was also split out per-file so a **fixture** can be run through it. It could
previously only be fed the repository — and the shape review found missing does not occur here, so no
amount of reading the source would have produced a failing case. *An analyser that can only be fed
the tree cannot be given the input it gets wrong.*

**A fourth review round found three more, and the first two are the third round's own fixes failing
one level down.** The pattern is worth naming on its own: *a fix can recreate, at the next level of
detail, exactly the defect it just closed — and it reads as the same code both times.*

- **Data dependence is not identity.** Tracing the `_next_stamp` argument accepted a `"modified_at"`
  read off *any* object, and carried names through *any* expression mentioning an accepted one — so
  `_next_stamp(metadata.get("modified_at"))` and `_next_stamp(stamp + timedelta(days=1))` both
  passed. Neither is the value the CAS predicate is compared against, so a writer feeding either
  would swap on a token no row ever held and be certified correct on the way past. Row *aliases* are
  now tracked separately (`rec = get_record(...)`, `other = rec`), the read must be off one of them,
  and prior-token names propagate through a bare name only. *An alias is an identity claim;
  provenance is a different question, and this file has now been wrong in both directions by
  conflating them.*
- **"Yes, somewhere" came back for the dicts.** Round two fixed it for updates — each is validated
  against its own `.values(...)`. That fix then pooled every `modified_at` assignment in the
  function into one list, so one correctly-stamped dict authorised a second `.values(**other)` whose
  dict had no stamp at all. Verdicts are now keyed by dict name, and each splat resolves its own.
- **And the `dev_property` merge was the class this sweep is about, created by this sweep's own
  fix.** Preserving `appraisal` turned a wholesale write into a read-modify-write, with
  `realestate.save_appraisal` merging into the same blob from the other side. Both now take
  `pid_lock.mutating(pid)` — a lock rather than a swap, because that table has no token to swap on —
  and **both** is the load-bearing word: *a lock one side does not take protects nothing*, so
  locking only the route review named would have left the pair exactly as racy. `db.refresh` matters
  as much as the lock, since `db.get` can answer from the session identity map and the waiter would
  otherwise merge into the pre-image it read before the winner committed. Open gaps 14 → 12.

*The first draft of that check passed under its own mutation.* It asserted that a frozen-clock edit
LANDS and that the next edit matches — both still true with the branch deleted, because SQLite
serialises writers and each session sees its own write. It is now the losing interleaving run with
the clock frozen, and removing the branch reproduces the loss exactly: `['GUID-A', 'GUID-C']`, GUID-B
gone. **Two checks that pass under the mutation are two checks measuring the round-trip, not the
guard.**

*Its own self-tests earned their keep within the hour.* Teaching the analyser about mapped model
classes — so two correctly-guarded writes stopped reporting as UNKNOWN — made it read the `t.c`
accessor as a column name, so every write looked swapped-on and both pre-fix bodies came back clean.
The population check would have printed "0 blind" over a tree it had not examined. *A widening and a
rule change are different edits, and widening one can break the other.* And the sibling gate did the
same for its neighbour: routing `revise` through the helper removed `update(` from its body, so
`test_transition_cas`'s exemption for it went stale and redded the build the hour the helper landed.
*An exemption that outlives its site is a hole nobody opened on purpose.*

### A second "send RFQ" minted a second solicitation, and a test called that idempotent

`POST /projects/{pid}/procurement/packages/{rid}/send-rfq` called `create_record` — which commits —
and only THEN looked at `workflow_state`, under an `if … == "draft"` that took the transition and an
`else` that skipped it and reported the unchanged state as a success. So a second send persisted
**another** Bid Solicitation while making no move. Measured on the old code: three sends produced
**ITB-001, ITB-002 and ITB-003**, every response 200 / `rfq_sent`. The same three sends now produce
**one ITB and two 409s**. *(That sentence read "one ITB and a 409" — singular — against a three-send
example, which is the kind of count a reader checks against the numbers directly above it. Caught in
review.)*

**The roadmap filed this as needing a contract decision** between a 409, an idempotent no-op, and a
deliberate re-solicitation with its own round number. **It was already decided, in
`services/api/modules/procurement_package/module.json`.** That workflow is linear — draft → rfq_sent
→ quotes_in → awarded — with no path back to draft and no re-solicit action, so `modules.transition`
answers a second `send_rfq` with a 409 of its own accord; the probe prints
`action 'send_rfq' not allowed from state 'rfq_sent'`. Deliberate re-solicitation would need a new
declared transition, which is a product change and not this fix. *The only thing that made the
refusal invisible was a branch written to route around it* — so there was no decision to take, only
a declaration to stop overriding. The route now moves first and mints only if the move landed.

**The existing test asserted the bug as the contract, and could not have noticed.** It read *"a
second send on the already-sent package doesn't error and reports the current state"*, asserted a 200
and an unchanged `package_state`, and its summary line called the route *"idempotent on re-send"*. It
asserted the two things that stay the same and **never counted the solicitations** — the one thing
that changed. *A word like "idempotent" in a summary is a claim, and this one had a test shaped
around it.* It now asserts the 409 **and** that the refused send minted nothing.

### And reversing the order installed a worse bug than the one it fixed

Raised in review on PR #551, before this shipped anywhere. The fix above moved the package FIRST and
minted second — correct about the duplicate, and **wrong about a failure in between**. `transition`
commits, so a solicitation refused after the move left the package in `rfq_sent` with no ITB — and
this workflow declares **no path back to `draft`**, so the package was stranded where a retry earns
only another 409. The old bug was recoverable by retrying (with a duplicate); the new one was not
recoverable at all.

**It needed no bug to reach.** `create_record` consults `fin_gov.locked_reason`, which raises 409 on
a locked accounting period — an ordinary business rule, on an ordinary day.

The fix is to STAGE rather than reorder: `create_record(..., commit=False)` writes the solicitation
into the session without committing, and `transition`'s own commit then carries both writes as one
transaction. Every refusal now leaves nothing behind — a refused mint never reaches the move, and a
refused move (sequential 409 or a lost CAS race) discards the staged ITB with the transaction.
Nothing in `transition` had to change; `create_record` already took `commit=False`.

*A fix that reverses an order can install a worse fault than the one it removes, because the second
write's failure is the one with nothing left to roll back.* The test drives the real
`fin_gov.locked_reason` path and asserts the package is still `draft`; reinstating move-first fails
it with **"refused mint left the package moved"**, so the ordering cannot quietly come back.

### `transition` was a read-then-write race — in all 139 modules at once

Found while fixing the above, and the more severe half. `modules.transition` read the record, proved
the move legal **from the state it read**, and then wrote with `update(t).where(t.c.id == rid)` —
keyed on the id ALONE, with no state predicate and no row lock. Two callers could both read `draft`,
both pass the check, and both commit. Two concurrent `award` calls both succeeded.

The reach is what makes it worth a release note rather than a line: `transition` is the **only** place
a record's `workflow_state` moves after creation (`revise` inserts a new row; every other mention of
the column reads it), so that one statement backed **139 modules and 342 declared transitions**. It is
now a compare-and-swap — the decided-from state is a predicate, and `rowcount != 1` is a 409 naming
the race, deliberately worded differently from the ordinary "not allowed from state" refusal so the
two are distinguishable by something other than a status code.

Not `with_for_update()`: Postgres honours a row lock and **SQLite treats it as a no-op**, so it would
read as protected on the backend the suite runs on while protecting nothing — the identical trap
`next_counter` had to be dug out of in August. `services/api/test_race_conditions.py` gated the job
claim and the ref counter; transitions were never in its population.

**The gate is `services/api/test_transition_cas.py`**, and two of its twelve checks exist because of
mistakes made writing it. It reinstates the **pre-fix statement shape** against an already-moved row
and requires the blind write to land, so it cannot pass with the guard removed. And its derivation of
"who writes this column" is taken at FUNCTION scope rather than from the text inside `.values(...)`:
the first attempt read only the call's own source, and because `transition` builds a dict and splats
it as `**vals`, **it found one writer and missed the one under repair** — reporting a tree that looked
clean. The gate now asserts it reaches `transition` before it may print any verdict. *A predicate that
decides what to LOOK at is more dangerous than one that decides what to report.*

`apps/web/src/portal/panels/buyoutKeep.ts`'s `rfqSummary` was written against the old rule and told
the user *"a solicitation has been minted anyway, so check whether this package already had one"*.
After the fix that is the one thing such a response has failed to establish, and the duplicates it
sends them hunting for can no longer be created. The branch is kept — a response that is not
`rfq_sent` now contradicts the contract — but it says that instead. *A defensive branch that outlives
its cause keeps giving the advice that fitted the bug.*

### The 3D pin overlay made two calls, and the route meant to replace them had no caller

`apps/web/src/pins/pins.ts` fetched BCF topics through `api.pins()` and register records through
`api.modulePins()`, building a marker from each of two row shapes. It now makes **one** request to
`/pins/all` and runs one loop; the only remaining branch is the CLICK, which is genuinely different —
a topic restores a saved viewpoint, a record opens its register row.

**The roadmap entry understated this by one whole half.** It said the remaining gap was *"what each
row CARRIES"*. That was true and incomplete: **`/pins/all` had ZERO frontend consumers** — no client
method, no call site anywhere in `apps/web`. The route was built, server-tested and dark, so the
overlay made two calls not only because the envelope lacked fields but because nothing had ever been
wired to the route that replaces them. *An item scoped from what a file lacks will miss what nothing
does.*

**CORRECTION, made before this shipped rather than left standing.** The paragraph above originally
ended *"Route-to-client reachability is a different question, and no gate here asks it."* **That is
false.** `services/api/test_route_reachability.py` asks exactly that question, and it is the gate
that caught this change. `services/api/test_reachable.py` — the one I checked — measures whether a
MODULE is reachable, and `pins.py` is imported by two routers, so it passes honestly; I concluded
from one gate's silence that no gate was listening.

**And the real finding is worse than the one I claimed.** The route-reachability gate did not miss
`/pins/all` — it VOUCHED for it. Measured both ways: on `origin/main` its uncalled set has 56
entries and `/pins/all` is not among them, while a grep of `apps/web` finds no reference to it at
all. Its leaf is the single common word `all`, and `leaf_is_called` is the rule that file's own
comments already describe as a standing cost (*"a shared leaf decides nothing"*; *"an English word
containing a route leaf, which no naming convention prevents"*). *A false negative in a reachability
gate is worse than no gate, because the question looks asked.* I did not isolate which string
vouched for it, and say so rather than guess.

PIN-ONE-CALL corrects the gate in both directions at once: `/pins/all` becomes genuinely called, and
`/module-pins` becomes genuinely uncalled — which the gate immediately reported as a new unreachable
route. It is recorded in `KNOWN_UNCALLED` with a reason and an expiry condition (delete the entry
and the route together at the next public-API revision), not silently exempted.

**The design question the entry left open is settled by measurement.** It asked whether the envelope
should carry the viewer's presentation fields or whether the viewer should look them up from
`/modules`. The viewer does not fetch `/modules` anywhere, so the lookup trades one request for
another and defeats the item. The envelope carries `icon` and `source_name` for BOTH kinds: a
register's `source_name` and `icon` from its own `module.json` — which is where the old
`/module-pins` row already read them — and a topic's from a glyph table lifted out of `pins.ts`,
where it was a literal the server could not see, so no server could name a topic pin.

*That last clause replaces a claim that was simply false, and it is worth leaving the correction
visible.* This read "which is precisely why the overlay needed a branch per topic type and a second
loop for register records". Neither half survives looking: the glyph was a **map lookup**, not a
branch per type, and the register loop **already took `icon` off the server row**, so the literal
cannot have been what forced it. What forced the second loop was the two ROW SHAPES — `Topic`
(`anchor`/`title`/`type`) against `ModulePin` (`anchor`/`ref`/`module_name`/`icon`) — which one
envelope collapses. The click branch stays, because restoring a viewpoint and opening a register row
are different acts. *A causal sentence is the easiest kind to write without checking, because it
reads as an explanation whether or not anything caused anything.* Found in review, not by me.

`api.modulePins()` is deleted as the dead client method it became; the `/module-pins` route stays.

**The gate already existed and was asserting the wrong number.**
`apps/web/src/kernel/markupPlugin.test.ts` pinned `["load:proj-1", "modulePins:proj-1"]` — the
two-call behaviour, recorded as a fact. It now pins one entry and a length, so a second request
fails a build. Mutation-verified: reinstating a second `pins.load` reports
`expected [ 'load:proj-1', 'load:proj-1' ] to deeply equal [ 'load:proj-1' ]`.

One test changed meaning rather than being deleted. *"A failure part-way through is still contained"*
asserted that a failure in the SECOND call left the first one's pins drawn — "it got that far". That
half-loaded overlay is unreachable now, so the test asserts its **absence**; deleting it would have
removed the record that the state was ever possible.

*And `test_file_sizes` caught `app.ts` at 2,445 against its 2,442 cap — three lines of comment, the
same shape as the `register.ts` growth one PR earlier. The explanation belongs on the `ResolvedPin`
type, not inside a file under a shrink ratchet. Learning a lesson and applying it are apparently
still two events.*

### Ball-in-court was computed twice, by two rules, and 10 states disagreed

The register screen and every server-side report answered "whose move is it" differently.
`modules_query.court_party` took the primary outgoing transition; `register.ts` unioned the parties
of **every** outgoing transition. Derived over all 139 modules and 267 workflow states, **10 states
in 9 modules** produced different answers. On an open RFI the screen showed Consultant, OwnersRep
*and* GC, while `changeorders.py`, `closeout.py`, `quality.py` and every `ball_in_court` rollup said
Consultant/OwnersRep — the GC appearing only because it can `void`. *An escape hatch is not a move
somebody owes.*

The server's reading survives, because it is what the money reports are built on. But it rested on a
premise nothing could check: *"module authors list the primary forward action first."* **That premise
is false in two places, and they are the ones that matter:**

| | listed first | actually owed |
|---|---|---|
| `pull_plan_task.made_ready` | `reconstrain` (back to `pulled`) | `commit`, by the Subcontractor |
| `permit.applied` | `issue` | `start_review` — nothing is issued before review |

**And it cannot be rescued by deriving "forward" from the declared state order**, which was the
obvious fix and is measurably wrong: `action_item.states` is `['done', 'open']` — alphabetical, not a
progression. Under that reading 45 states have no forward transition at all and 39 have several.
*A convention nothing can check is a convention that has already drifted.*

So the primary is **declared**: `"primary": true` on one transition, or the state is listed as
`resting` — reachable, but owing nobody anything. **Only 17 of 267 states need to declare anything**,
because 199 have a single outgoing transition and 51 have several that all carry the same parties; for
250 of them the choice cannot change the answer. That bound is the design — a rule demanding 267 edits
would have been abandoned halfway and left the tree half-declared.

Five answers change. Two are the corrections above. Three states become **resting** —
`decision.decided`, `information_container.published`, `spec_section.issued` — and stop naming a
party at all, which is what had been putting closed records into ball-in-court rollups as though
someone were sitting on them. Transitioning into a resting state leaves `party_owner` as it was,
exactly as a terminal state already does.

The register now **reads** the value instead of deriving it, and deliberately has no local fallback:
recomputing would be the second implementation again. Both the list and the single-record route send
it, resolved through `workflow_config.effective` — the project's overridden workflow, which is what
`transition` uses, so the screen and the engine cannot disagree by that door either. Enriched at the
two **routes** rather than in `modules_query.list_records`, which has **274 call sites** including a
BCF export built from the row's keys: *the narrowest place that can carry a fact is where it belongs.*

Gated by `services/api/test_court_primary.py`, which derives the ambiguous states rather than listing
them, strips a declaration and requires that to be caught, and mutates `court_party` back to the
first-transition rule and requires **both** wrong answers to return — so the assertions test the
reader and not merely the config.

Two gates went red on that change and both were right, so both are recorded rather than quietly
re-pinned:

**`test_json_null_filter` exempted its sites by LINE NUMBER, and went stale twice in two days.** Not
because the code it describes changed — because unrelated edits further up `modules_query.py` pushed
those sites down the file. *A line number is a coordinate every edit to the file moves, so an
exemption keyed on one measures when the file was last touched rather than whether the site is still
there.* Re-pinning it a second time would have been a fix already known to fail, so the key is now
`(file, enclosing function, subject)`, which moves only when the code genuinely moves.

Collapsing the line into the function costs the ability to tell two sites in one function apart —
`_apply_filters` has two — so each entry now carries **how many sites it covers**, and the gate
deletes one of that pair and requires the count to catch it. Otherwise this would have traded a
noisy failure for a silent one: an exemption still covering the survivor after its twin was deleted.
Three mutations pin it: claiming a wrong count, restoring the line-number key, and dropping an entry
outright are each reported.

**`test_file_sizes` caught `register.ts` growing past its ratchet — by six lines of COMMENT.** The
code shrank five lines (the local ball-in-court union went away); a seventeen-line doc comment
explaining why replaced it. The ratchet was right: the substance of that comment is about the
SERVER's rule and belongs with `court_party` and its gate, not restated in a 2,458-line file that is
under a shrink ratchet precisely because it accumulates. Trimmed to six lines and the now-dead
`ModuleDef` parameter dropped from `ballCell`; **2,458 → 2,447**.

*Both were found by running the suite rather than by reading the diff, and CI's API gate failed on
the same two — which is the argument for running it before claiming a PR is green.*

**A review round on that fix found three more, and two of them were the same defect I had just
fixed one file over.** `test_court_primary`'s list lookup unwrapped `{"items": ...}` and then
iterated whatever was left — a 4xx body is a dict with no `items`, so the unwrap hands the ERROR
OBJECT back, iteration yields its string keys, and `x.get` raises before `check` can report the
route failure. And the new self-tests in `test_json_null_filter` opened with a bare `next(...)`,
which raises `StopIteration` and kills the gate if the site they are built on is ever deleted.
*Both are "dies instead of reporting", written hours after fixing that exact shape — knowing a
defect class by name is not the same as recognising it in your own next paragraph.* Both now report
through `check` and reach the summary; each is mutation-proved by breaking its precondition.

The third was in the rekey itself. `_sites()` mapped each node to its enclosing function with
`ast.walk` + `setdefault`, which binds to the **outermost** enclosing function, not the nearest — so
a NULL test inside a nested `def` resolves against the wrong locals. That was already true when the
owner map only fed `_resolve`; making the function name part of the site's **identity** is what
turned it into a misattributed key no exemption could match. Replaced with a scope-stack descent.
**Measured on today's tree the two walkers agree on every one of the 21 sites** — which is precisely
why a synthetic nested case is asserted: *a fix nothing can distinguish from the bug is a fix nobody
can keep.*

**And the first draft of THAT self-test tested a copy of the fix.** It mirrored the traversal into a
local `_probe` instead of calling `_owners`, so `_owners` could regress to outer-function
attribution and the check would still pass — *a self-test written to stop a fix being silently
reverted, unable to observe the fix.* Worse, the mutation run to verify it was aimed at the copy, so
it proved the copy behaved as advertised and said nothing about the gate. **Mutate the thing under
test, and prove the test can reach it.** It now calls `_owners` directly, and regressing `_owners`
itself is what reds the build. The fixture was also shadowing an unrelated `_NESTED` used by the
resolver self-tests, harmless only because those happen to run first; renamed.

### The PostgreSQL pin gate could be handed a dead server and still exit 0

Follow-up to the pin-sweep work, and a finding that survived two review rounds because it sat in the
review **body** rather than an inline thread — every inline finding was fixed, and this one was not
seen until after the PR merged. *Where a finding is posted decides whether it gets read.*

`test_pin_pgnull.py` connects to the PostgreSQL a run asks for, and failed the build on an
unreachable one only `if _REQUIRED` — that is, only when `AEC_PG_REQUIRED` was set. But `_url()`
returns a URL under **two** opt-ins: that one, and `AEC_TEST_PG_URL`. So a run that set only
`AEC_TEST_PG_URL`, pointing at a dead port, took the connect-failure branch, recorded nothing, fell
through to the no-server path and exited **0** — printing *"no opt-in"* at a caller who had just
opted in.

Measured before the fix, not reasoned about:

    AEC_TEST_PG_URL=postgresql+psycopg://postgres@127.0.0.1:1/nope   (AEC_PG_REQUIRED unset)
    -> test_pin_pgnull OK  (no opt-in; ...)      exit 0

This is the same shape as the defect the file's own comment already records one flag earlier —
*"a flag that guards one branch of two guards nothing"* — and it recurred because the fix at the
time asked *is this run required to reach a server*, when the question the branch needed was *did
anything ask for this server at all*. By the time that `except` runs, something always has: the
failure is now unconditional. **A message that names the wrong cause is worse than a bare failure,
because somebody acts on it** — the reader would have gone hunting for the opt-in they had supplied.

Verified in four directions: the dead explicit URL now exits 1; `AEC_PG_REQUIRED` with a dead
`PGHOST` still exits 1; no opt-in at all still passes through the genuine no-server path; and the
live-PostgreSQL run still passes. CI was never exposed — it sets `AEC_PG_REQUIRED` — which is
exactly why nothing went red.

### Sorting a register by `updated_at` was a 500; `SYSTEM_COLUMNS` named two columns that do not exist

`modules_query.SYSTEM_COLUMNS` is the allowlist of row columns a caller may filter and sort a
register by. Two of its six names were not columns at all: **`updated_at`** — the register column is
`modified_at` — and **`ball_in_court`**, which is derived from `workflow_state` by `court_party` and
never stored. `_resolve_field` returned `{"_system": True}` for both, so `_field_expr` and
`_display_expr` went straight to `t.c[name]` and raised `KeyError` inside the request handler.

Measured over HTTP against the pre-fix code, on a live register:

| request | before | after |
|---|---|---|
| `?sort=not_a_field` | 400 | 400 |
| `?sort=workflow_state` | 200 | 200 |
| `?sort=updated_at` | **500** | **400** |
| `?sort=ball_in_court` | **500** | **400** |
| `?sort=modified_at` | 400 | **200** |
| save a view with `{"sort": "updated_at"}` | **201, accepted** | **400, refused** |

That last row is the one worth reading twice. `validate_view_config` resolves `sort`, `group_by`,
`agg_field`, `columns` and `filters` through the same `_resolve_field`, with no table in scope at
all — so the phantom could be **stored**. The view saved, the view list returned 200, and the 500
arrived only when somebody applied it. *The stored form is not a louder version of the transient
one; it is a quieter one, and its cause sits two screens from its symptom.*

The fix is both halves, because either alone passes while the other is broken. `_system_field`
validates the name against the register table before the system stub may be returned, so the next
phantom is the 400 an unknown field was always supposed to get; and the list is corrected —
`updated_at` renamed to the column it meant (checked against all 139 modules: none declares a field
by that name, so it shadows nothing), `ball_in_court` dropped. **`?sort=modified_at` now works**,
which is the capability the wrong name was reaching for.

`updated_at` is the **third** instance of that typo on a module row. `quality.py` and `rfi.register`
both read it and got a permanent `None` for `avg_days_to_close`, fixed in August. Those two failed
silently and this one is reachable from a URL — *the same wrong name is not the same severity in two
places, and the loud one was found last.*

Gated by `services/api/test_system_columns.py`, which asserts the allowlist against the live
`TABLES` metadata (139 tables), requires its own derivation to re-find both shipped phantoms before
it may report anything, and then **deletes the runtime guard and requires the `KeyError` to come
back** — a static check that passes with the guard gone is not testing the guard.

### The pin sweep skipped exactly the rows it was written to convert, on PostgreSQL only

`b3c9e42d18a5` — the migration that clears empty pin values so `/pins/all` stops counting them as
candidates — selects every row where either pin column is non-NULL and then decides per column in
Python, beginning `if v is None: continue`. A `json` column holding the JSON scalar `null` is **not
SQL NULL**, and psycopg decodes it, so the driver hands back Python `None`: by the time that line
runs, a row that was never pinned and a row holding `null` are indistinguishable. It walked past
every one of them.

Those are precisely the legacy rows the sweep exists for. Every `None` written to `anchor` or
`element_guids` before that same change added `JSON(none_as_null=True)` went in as the scalar
`null`; they satisfy the SQL half of the pin predicate, fail the exact test in `pins.pin_fields`,
and are what puts the `~` on the plan sheet's project total. Measured against PostgreSQL 16 on a
four-row fixture before anything was written: **the `null` row came out exactly as it went in, and
`SKIPPED` was empty** — so the run neither converted it nor said anything about having seen it.

*(An earlier draft of this entry led with "`changed=1` → `changed=4`", and review was right that the
comparison is unsound: the corrected sweep issues one UPDATE per column where the old one grouped a
row's columns into one, so the number moved from ROWS to COLUMN VALUES in the same change. Two
counts in different units read as a measurement and are not one. The row states are the evidence;
the unit change is now pinned by a both-columns fixture in `services/api/test_pin_empty.py`, which
nothing caught before because every earlier fixture seeded a single column.)*

**SQLite hid it, and not by accident.** There a JSON column is TEXT, the scalar arrives as the four
characters `null`, and the decode happens *after* the guard has already let the row through — so the
conversion works and every local test passes. This is the same `null`-is-not-`NULL` distinction that
migration was itself about, reappearing one layer up in its own reader. *A migration that fixes a
representation problem has to be careful not to inherit it.*

`d7f1a5c3e094` re-sweeps with the question asked in SQL instead: one SELECT per column, each
narrowed to that column being non-NULL, so everything it returns is non-NULL in SQL and a Python
`None` can only be the scalar. It is a new revision rather than an edit, because `b3c9e42d18a5` has
run — editing it would change nothing on any database that ran it while making the file disagree
with what was executed there. Verified on the same fixture: the `null` rows are now SQL NULL, the
already-NULL row is untouched, and a real anchor survives.

**The dialect was never the mechanism — the driver decoding the column is**, and that is why the
gate does not need a PostgreSQL to be real. `test_pin_empty.py` registers a sqlite3 converter so its
driver decodes too, and asserts the corrected sweep converts the row while the migration it corrects
walks past it. The first draft of that section checked only the emitted SQL, and **reinstating the
exact defect on top of the corrected SELECT passed it** — asking the right question and then
throwing the answer away are two different failures, and only one is visible in the statement.
`test_pin_pgnull.py` runs the same shapes against a live PostgreSQL in `db-migrations.yml`; with no
server it does not pass quietly, it asserts that the CI step which runs it is still there.

### A NULL test on a JSON column is a filter that filters nothing — now a gate

Second half of the same defect, as a class rather than an instance. SQLAlchemy persists a Python
`None` in a `JSON` column as the scalar `null` unless the column declares `none_as_null=True`, so
`WHERE <json col> IS NOT NULL` matches every row ever written and `IS NULL` matches none.

`services/api/test_json_null_filter.py` derives every NULL test in `services/api/src/aec_api` by AST
— **21 sites**, re-derived rather than taken from the roadmap's 20 — and resolves each subject
against the model metadata. Three answers are safe: not a JSON column, a JSON column with
`none_as_null=True`, or a JSON *extraction* (`data ->> 'x'`), which is a text scalar and yields SQL
NULL on both backends for a missing key and for a stored `null` alike. One is not. Result: 15 safe,
5 unresolvable subjects each read and exempted with what the subject actually is, and **one live
member of the class** — `Topic.labels` in `client_portal.py`, which narrows on `type == "info"`
first and applies the real test in Python, so it over-fetches and does not answer wrongly. It is
recorded rather than fixed: making it right needs a sweep of the existing `'null'` rows.

It fails closed — an unresolved subject reds the build rather than being assumed safe — and it runs
itself against the known instance before it is allowed to report anything, because a derivation that
reports a clean tree is indistinguishable from one that reports nothing.

**What it deliberately does not assert** is that every JSON column declares `none_as_null=True`.
Measured: 588 JSON columns, 308 without it. Turning those on is a write-behaviour change on 308
columns, not a gate, and almost none of them is ever the subject of a NULL test — which is what
makes the reader the right place to stand.

### @thatopen/ui dropped — the guard was demanding a browser verification of a package that cannot reach the browser

`@thatopen/ui` was a declared dependency that **nothing imported**: zero source references tree-wide,
absent from the built bundle, and a peer dependency of nothing here — it appears only as a
*devDependency* of the upstream `components` packages, which imposes nothing on us. Yet
`scripts/check-fragments-version.mjs` pinned it in `KNOWN_GOOD`, and that guard's failure message
sets a specific contract: re-verify the viewer — load a model, author, section — and move the pin in
the same commit.

So every dependabot patch bump demanded a full live viewer pass for a library that **cannot affect
the running app**. That bill was paid twice: #416 was closed on exactly this cost/benefit, and #545
paid it again — the live pass was done, and its most useful finding was that there was nothing to
verify.

Removed from `apps/web/package.json`, the README pinned-version table, `KNOWN_GOOD`, and
`docs/credits.md` — the last of those mattering because credits name what is *shipped*, and it no
longer is. The npm lock was regenerated with `--package-lock-only` rather than hand-edited: the
removal orphans fourteen packages in total (`lit` and its three internals, `chart.js`,
`chartjs-plugin-datalabels`, `iconify-icon`, the three `@floating-ui` packages, `@iconify/types`,
`@kurkle/color`), and computing a transitive orphan closure by hand is how a lockfile stops matching
what `npm ci` will install. **Zero packages added, zero versions changed** — verified by diffing the
two lockfiles rather than by reading npm's summary, which matters because twenty-one dependencies
carry `^` ranges that a careless regeneration could have floated.

The general point is worth keeping: **a guard that names something unreachable does not protect it,
it only charges for it.** The pin looked like coverage and behaved like a toll.

### numpy 2.5.3 and manifold3d 3.5.3 — two dependabot PRs that could never have gone green alone

#516 (`numpy>=2.5.3`) and #517 (`manifold3d>=3.5.3`) both failed the API test gate, and the reason is
written in the tree they were editing. `services/api/requirements.in` carries it on the numpy line
itself: *"floor raised WITH services/data/requirements.txt: pip-compile reads only this file, so a
floor raised only there cannot move the lock."* Dependabot edits `services/data/requirements.txt`,
which pip-compile never reads — so the lock kept pinning 2.5.2 and 3.5.2, and
`test_lock_satisfies_requirements`, which deliberately reads **both** requirements files, kept
failing. **Structural, not incidental:** no amount of rebasing could have fixed either PR.

Raising both floors lets the recompile follow, and it moves **exactly two pins** — nothing added,
nothing removed. That was predicted from a measurement before the change was made, then confirmed by
CI's `Verify` step on the committed bytes.

**This lock was compiled locally, which is the opposite of the previous entry's conclusion — and the
reversal is the point.** There the bytes were transcribed out of CI because a local resolve had
produced an unrecognisable answer. Once the cause was understood (a fresh output path preserves
nothing; an in-place one constrains to the existing pins), the local tool became the same tool CI
runs, and `Verify` confirmed byte-identity on a lock carrying hundreds of hash lines rather than
alembic's two.

**The clock said it before the diff did.** The fresh-path compile took over forty minutes because it
re-resolved and re-hashed the whole graph; the in-place compile took **thirty-nine seconds** because
it only fetched what moved. A forty-minute run and a forty-second run were never doing the same work,
and nobody had to read a single package name to see that. *When two runs of "the same" command differ
by sixty-fold in cost, they are not the same command, and the cheap explanation for their differing
output is probably not the true one.*

Transcription would not have worked here in any case: the `Verify` step prints `head -60` of its
diff, which alembic's two hashes fit inside and `manifold3d`'s dozens of wheel hashes do not, and the
artifact holding the full file sits behind an egress block. Either route ends at the same gate, which
is what makes either safe.

### alembic 1.18.5 → 1.20.0, and a local resolver that confidently reported the wrong answer

Dependabot's #519 carried this floor bump with a recompiled lock and went fully green, including the
Postgres `alembic upgrade + check + runtime-parity` job. It then became unmergeable: three later
bumps each recompiled `services/api/requirements.lock`, so the branch conflicted in a generated file
that must never be merged by hand. Handing it back to dependabot was not available either — comment
commands posted from this session are rewritten in transit, with U+00B7 injected around the `@` and
inside the command word, so `recreate` and `rebase` both read correctly in the timeline and did
nothing. **A command that looks delivered and is inert is worse than one that visibly fails.**

Redone here, with the lock taken from `lockfile.yml`'s own compile in `python:3.12-slim` rather than
from a local one — and that distinction turned out to matter enormously.

**The local resolve said 34 packages would move.** `anthropic` 1.2.0 → 1.5.0, `websockets` 16.1 →
17.1, `cryptography`, `sqlalchemy`, `certifi`, and thirty more: a one-line floor bump becoming a
tree-wide sweep, which is exactly the kind of scope change worth stopping for. It was wrong. CI's
`Verify` step prints its own diff, and that diff carries `annotated-doc==0.0.4` as an unchanged
**context** line — the very next package after alembic — while the local resolve moved it. `Verify`
then passed on the transcribed lock, proving the real change is alembic **and nothing else**.

**The cause was the invocation, not the environment** — and the first explanation written here was
wrong in a way worth preserving. It blamed the sandbox's package index for serving something
different from the prod container. That was a guess dressed as a diagnosis, and it would have
libelled perfectly good local tooling. `pip-compile` treats an EXISTING output file as constraints
and moves only what the inputs force; the local runs wrote to fresh scratch paths, where there were
no pins to preserve, so everything resolved to latest. Compiling into a copy of the real lock
instead moves **zero** packages — which is also why only alembic moved in CI: its floor was the only
one that changed.

So the reproduction rule is concrete: **compile in place, to the lock you intend to replace.** A
lockfile regeneration aimed at a new path is not the same operation and does not answer the same
question.

*A number with a package list attached reads as evidence.* The list was specific, ordered and
plausible — it was very nearly reported as a finding, and its wrong explanation very nearly outlived
it. What exposed the number was a context line in someone else's diff; what exposed the explanation
was checking whether the two versions even existed upstream, and finding that they did, with cp312
wheels, which left no room for an index story. **When a measurement and a gate disagree, the gate is
the one that graded the artifact — and the first story that explains the gap is not automatically
the true one.**

Worth recording that the floor and the pin differ on purpose. `requirements.in` asks `>=1.19.2`,
what dependabot requested; the lock resolves to the latest satisfying release, 1.20.0. So the
behaviour under test is 1.18.5 → 1.20.0, wider than the floor names, with alembic 1.19's
autogenerate CHECK-constraint change inside that span.

### A digest pin freezes the base image, and the CRITICAL gate blocks on it going stale

The API container build went red on three fixed CRITICAL CVEs in `perl-base` — CVE-2026-13221,
CVE-2026-42496 and CVE-2026-8376, all `Status: fixed` at `5.40.1-6+deb13u1` — with nothing in the
diff that touched a Dockerfile. `services/api/Dockerfile` is byte-identical to main, the base images
are pinned by digest, and the two other images in the same matrix (`node:24-slim`,
`nginx:1.31-alpine`) passed. Nothing about the change caused it; the pinned `python:3.12-slim`
simply predates a Debian security update, and the Trivy CRITICAL gate is doing exactly its job.

**The obvious fix is a bet, not a fix.** Bumping to a newer `python:3.12-slim` digest only helps if
upstream happened to rebuild after the DSA landed — and the tag's head at the time was built
2026-09-01, with no way from here to establish which packages that rebuild picked up. The egress
policy in this environment blocks both the Docker blob CDN and `deb.debian.org`, so the candidate
digest could not be opened and read either; a digest chosen and pushed on the assumption it was
newer-and-therefore-fixed would have been a guess wearing a checksum.

So the runtime stage applies Debian security updates at build time instead. That is not a weaker
supply-chain position than what the stage already did — the same `apt`, the same signed archive, the
same build-time resolution as the `apt-get install` one line below it — and the digest pin is
untouched, so the base layers are still the reviewed ones. **A pin fixes the starting point; it does
not stop the starting point going stale**, and a gate that blocks on staleness needs a fix aimed at
staleness.

**And the first draft of that fix was stale by construction — review caught it.** This entry claimed
the upgrade "keeps working: the next DSA is picked up by the next build". It would not have. Both
container jobs build with `cache-from: type=gha`, and the cache key for that `RUN` is its parent
(a pinned digest, which never moves) plus its command string (which also never moves). The layer
would have been restored from cache on every later build, so the upgrade would have run **exactly
once** — on the build that introduced it — and then frozen at whatever the archive held that day.
`ci.yml` now passes `no-cache-filters: runtime` for the api image, and the stage is named `AS
runtime` to be addressable; the expensive `pybuild` and `converter` stages stay cached.

The shape is the one this repo keeps meeting: **a mitigation whose self-maintaining property was
asserted rather than checked.** It is the same failure as a gate that answers instead of failing,
moved one layer out — the remediation would have been real on the day it was written and inert
every day after, with a green build both times. *A fix that depends on re-running needs the
re-running proved, not assumed.* Worth noting where it was caught: not by a test, because nothing
here can execute a container build — no docker daemon in the authoring environment, and the egress
policy blocks the registry's blob CDN. The check that could fail was CI, and the reader who spotted
the gap ahead of it was a review bot.

### The escaping gate could not see a helper's parameters, so 108 sinks sat outside it

The identity ratchet shipped in the previous entry freezes `file :: expression`. That constrains a
sink whose expression NAMES its source — `${a.filename}` cannot start carrying something else
without the identity moving. It does nothing for a bare value binding:

```ts
const card = (label: string, value: string) => {
  c.innerHTML = `<div>${value}</div><div class="meta">${label}</div>`;   // identity: "value"
};
```

`value` is the identity whatever the caller passes. Every call site could switch from a literal to
a user-controlled field and the baseline would not move — **the sink goes live while the gate stays
green**. That is the same defect the ratchet was built to fix, one level up: there the frozen key
was a count with no identity, here it is an identity with no source.

**108 interpolations across 27 files**, all now escaped. The population was derived by AST — bare
identifiers reaching `innerHTML` that resolve to a function parameter or a destructuring binding —
and the fix is verifiable in a way most sweeps are not: escaping a sink can only ever REMOVE entries
from the ratchet's baseline, never add one. It went **119 → 74 with zero additions**.

Three things this found that the existing gate could not:

- **The HOT term list was hiding 53 of them.** `budget.ts` interpolated a bare `val` and `evm.ts` a
  bare `sub`; neither word matches any term in the list, so both were invisible to the ratchet while
  being exactly the shape the new rule exists to catch. Under the term filter the population read
  32; under the shape rule it read 85. *A keyword list derived from what someone happened to be
  looking at cannot bound a population — a shape can.*
- **The first draft of the new rule tested only for parameters, and reported the tree clean at 85
  fixed sites.** 23 more were live in `for (const [label, val] of cards)` — a destructuring binding
  is a value handed in from elsewhere exactly as a parameter is, and the name says nothing about the
  source either way. *A predicate that decides what to LOOK at hides everything it excludes from its
  own count*, which is why the count looked complete both times.
- **`register.ts` carried a comment reading "textContent/esc throughout: ref+title are user data
  (stored-XSS guard)"** directly above the one interpolation on that line that was not escaped.

The new rule takes **no baseline and admits no exemption** — the fix is always available and always
correct, so there is nothing to grandfather, and grandfathering one would freeze a sink open by
definition. Its boundary is stated rather than implied: a plain `const x = …` local is out of scope,
because 157 of those reach `innerHTML` in this tree and most hold markup assembled a few lines
earlier (`rows`, `thead`, `bars`, `cells`) where escaping would destroy it. A local assigned from
user data and interpolated bare is caught by neither rule in this file, and the test says so.

**The excluded class was then triaged, not assumed** — an exclusion nobody measures is a blind spot
with a justification attached. All 134 bare locals were classified by their declaration's initialiser
(41 build markup, 39 literal, 15 numeric, 1 already escaped, 36 suspect, 2 unresolvable) and every
suspect and unresolvable one was read. Exactly **one was a real sink**: the CPM panel's critical-path
line, where the server builds `critical_path` as `[r["ref"] or r["id"] …]` — stored, user-entered
activity refs — and the panel joined and interpolated them raw into `innerHTML`. Anyone who can name
a schedule activity could put markup in it and have it run for everyone who opens that panel. Fixed.

Two things about that triage are worth keeping. Its first draft resolved declarations **file-wide and
kept the last match**, so one panel's `gap` (a number) was attributed to an unrelated `el("div")`
hundreds of lines away and reported suspect — the lookup is scope-aware now, and the bug surfaced
only because the suspects were *read* rather than counted. And the single real finding was a **local**,
i.e. in the class the new rule deliberately excludes: *the documented gap was live, not theoretical,*
which is the whole argument for measuring an exclusion instead of asserting one.

**A review round then found the detector's real boundary, and it was hiding a live sink.** The
scanner walked only the interpolations lexically inside an `innerHTML =` expression. But markup is
usually assembled into a local FIRST and only then interpolated — `const rows = deals.map(d =>
\`<tr><th>${d.name}</th>\`)`, then `panel.innerHTML = \`…${rows}…\``. Every span inside that builder
was invisible to **both** rules: not baselined, not flagged, live. The reviewer found one symptom
(`d.name`, a saved scenario name that any user can set); behind that one hop sat **15 hot
interpolations across 8 files**. *The scanner was measuring syntax where the question is
reachability.* It now follows one hop, and stops there deliberately — a local built from another
local is still uncovered, and the test asserts that limit rather than leaving it to be discovered.

Nine of the fifteen were real and are escaped: a scenario name, vendor names in a bid-levelling
matrix, carbon hotspot element names, a takt trade name, project-health domain labels, sources-uses
line labels, forecast line names, and test-fit scheme names. The remaining six are one shape — a
ternary whose branches are literal markup or a glyph (`s.name === r.best ? " ★" : ""`) — which match
the term list on their *condition*, never their value. Escaping any of them would render markup as
visible text, so they are baselined with that reason: **the fix would be the bug.**

Three more findings from the same round, all real. The value-binding rule ignored **constructor and
setter parameters** — a coverage hole in a security gate. It resolved bindings **file-wide**, so a
destructured `rows` in one function made an unrelated plain local `rows` in a sibling fail the
plain-local exclusion; the rationale written beside that code ("a false positive only costs one
`esc()` that was already correct") was wrong, because for *this* exclusion the suggested fix escapes
assembled HTML and breaks the page — *a false positive is only cheap when the fix it suggests is
safe.* Bindings resolve lexically now. And a milestone `<option>` escaped its **text but not its
value**: `esc` turns `&` into `&amp;` and the old `.replace(/"/g, …)` did not, so a milestone named
`A &amp; B` parsed back out as `A & B` and the next request queried the wrong one — asserted now
through a real DOM parse rather than by reading the template.

One test had to be repaired as a consequence, and the repair is the point. The substitution check
hardcoded `portal/panels/evm.ts` and the identity `"value"` as its fixture; this change escaped
every sink in that file, so a legitimate improvement red the test with a message about a missing
baseline entry rather than about the substitution it guards. The fixture is derived now. *A failure
message that can misdiagnose is worse than one that stays silent, because somebody acts on it.*

### A stored XSS the security ratchet had been counting for months

`apps/web/src/ui/innerHtmlGuard.test.ts` froze a per-file **number** of unescaped `innerHTML`
interpolations. A number has no identity, so a file sitting inside its allowance was never looked at
again -- you could delete a safe sink and add a live one in the same file and the gate stayed green
both times.

It was doing exactly that. `register.ts` was allowed 6 and had 4, and two of the four were
`${a.filename}`:

| step | where |
|---|---|
| raw multipart filename, unsanitised | `services/api/src/aec_api/routers/modules.py` (single + bulk upload) |
| persisted verbatim | `modules.py` -> `record_attachments.filename` |
| returned verbatim | `modules.py` list_attachments |
| rendered **unescaped** into `innerHTML` | `apps/web/src/portal/register/register.ts`, both branches |

A user with the `reviewer` role uploads an attachment named `<img src=x onerror=...>.pdf`; everyone
who opens that record's attachment list runs it. The default CSP is framing-only, so inline handlers
execute; `AEC_CSP=1` blocks the script but not the content injection. `esc` was already imported in
that file and used 200 lines away -- the inconsistency the gate's own docstring diagnoses, on the
exact vector it names ("an upload filename").

**There was headroom at the top, too.** `BASELINE_TOTAL` was 85 against 77 actual, and SEVEN files
the baseline had never heard of were sitting in that slack, passing silently. All seven read benign;
the defect is that nothing had assessed them.

**And it was blind to half its own population**, which is the worse of the two defects. The rule
needed `innerHTML` and `${` on the SAME LINE, so any statement wrapped across lines -- the normal
shape for a non-trivial row -- was scanned only as far as its first chunk. Measured while converting
it: **under the OLD same-line rule**, 62 sinks visible and **58 more on continuation lines it could
not see**, among them `v.vendor`, `s.company`, `r.text`, `t.title` and `cert.ref`. *Scope is a
separate question from rule, and a green ratchet is what makes a scope error invisible* -- the same
lesson `services/api/test_ruff_scope.py` paid for.

**Those 62/58 figures are a diagnostic of the old detector, not a remediation count.** They are not
comparable with the numbers below, which come from the new whole-statement detector with widened
terms: the two rules see different populations, so 62 + 58 and 146 do not describe the same set and
no arithmetic relates them. The scan now accumulates the whole statement AND parses interpolations
by brace depth.

**The baseline is now keyed on IDENTITY -- `file :: expression` -- and the count is derived, never
asserted.** An expression the list has not seen fails even when the total is flat or under. A
vanished entry still never fails, deliberately: improving the code must not red the build.

Fixed in the same change: **33 sinks escaped, 30 identities removed** -- measured under ONE
rule against `origin/main` (146 sinks / 125 identities) and this head (113 / 95), because the first
attempt at that figure ADDED two counts taken under the narrow and wide detectors and got 29. *An
arithmetic total across two different scopes is not a measurement.*

Escaped: the filename pair, kanban `title`/`assignee`/`ref`, BCF topic fields in `viewer/app.ts`,
imported schedule activity + trade, an `<option value>` attribute pair, vendor/company/trade across
the analytics panels, a saved-search name, an AI-topic code/section/title row, a certificate ref, a
field-capture label + subject, and a portal comment body. Two PARTIAL escapes were completed -- they
escaped `&`/`<` only, or `"` only, which is worse than none because it reads as handled.

**Two escapers had different coverage.** `ui/feedback.escapeHtml` covers `& < > " '`; `ui/charts.esc`
omitted `'`, and `esc(x)` reads identically whichever you imported. There is now one.

Server side, `serving.stored_filename` normalises the persisted value (basename, control characters,
length) at both upload doors. It deliberately does NOT strip `&` or `<`: those are legal in a
filename, and mangling them would corrupt real names while giving false assurance. **Escaping stays
the renderer's job** -- input filtering fixes an XSS only until the next sink.

The decisive test is a SUBSTITUTION: delete one baselined sink, add a different one in the same
file, count identical. The old rule passed it; the new one names the identity. Verified by mutating
a real source file and watching the gate go red, not by reading it.

### The API client could not take another mixin, and now it can

`apps/web/src/api/client.ts` composed its 49 mixins in one nested `extends` expression. Adding a
50th made `tsc` fail outright — TS2589, *"Type instantiation is excessively deep and possibly
infinite"* — which is how BSDD-LOOKUP ended up lodging two `/bsdd` methods in `ids.ts` against the
route-seam rule ~20 SCALE-SEAM PRs have followed. **A ceiling nobody had measured was silently
setting architecture.**

Measured in both directions, and two plausible fixes ruled out before the working one:

| composition | mixins | `tsc` |
|---|---|---|
| one nested `extends` | 49 | passes |
| one nested `extends` | 50 | **TS2589** |
| `const Stage = withA(withB(…))` split | 50 | **TS2589** |
| `class _StageA extends …` declarations | 50 | **passes** |

- **It is depth, not accumulated members.** A 50th mixin declaring *no methods at all* fails
  identically, so trimming the API surface would have bought nothing.
- **A `const` split does not work** — it infers the same nested anonymous type, so the depth is
  unchanged. Only a `class` *declaration* names the type nominally, letting the second stage start
  from a resolved base instead of re-walking the first.

`client.ts` now stages 25 + 24 through two class declarations, and `api/mixinStaging.test.ts` holds
the shape: a tidy refactor that inlines the stages compiles fine *today* at 49 and strands the next
person at 50, with an error naming neither the cause nor the limit.

**Two corrections this forced.** The BSDD-LOOKUP entry above said the chain broke at a *51st* mixin;
it held **49**, so it was the 50th. That number was asserted, never counted — `git grep -c` would
have settled it in a second, and it shipped. *An unmeasured number reads exactly like a measured one.*
And while mutation-testing the new gate, one mutation **silently failed to apply** and the suite
reported green — indistinguishable from a correct implementation. The mutation now asserts the file
changed before running. *A mutation that does not apply is a test that was never exercised.*

### The reachability gate's blind spot was 70 routes wide, and only two were written down

`LEAF_COLLISION_DARK` is a **triaged** list — routes somebody read, confirmed dark, and recorded. It
was never the population, and the note above it described it as though it were. The population is
every route the reachability rule cannot see *at all*: leaf long enough to check, leaf vouched by an
ordinary English or HTML word (so the rule stays silent), and no caller that builds the path.
Deriving that instead of listing it gives **70 of 947 routes**.

`services/api/test_route_reachability.py` now derives and freezes that set as `LEAF_COLLISION_BLIND`,
the way `KNOWN_UNCALLED` already freezes the routes the rule *can* see. It is a **record, not an
allowlist**: 70 is not a target, and most of the set is probably correct. `/scim/v2/Users` is for an
identity provider and `/bcf/2.1/projects` for external BIM tools — neither should ever have a web
caller. Some are false positives of the probe itself: `openDrawing("plan.dxf?…")` builds
`/projects/{pid}/drawings/plan.dxf` through a helper, so the literal never appears.

**The point is not the number, it is that the number exists.** Before this, the blind spot had no
measured size and nothing could report a new member; now it can only shrink, and route 71 arrives
with a name. Triage is deliberately *not* done here — no syntactic probe can classify these, because
the leaf being vouched is the whole problem (a leaf-based search returns 685 hits for `projects` and
44 for `status`). Each needs a read, and that is its own work.

**Two review findings, both real, both applied.** The derivation matched its probe against all
code; `leaf_is_called` directly above it matches inside STRING LITERALS, for the documented reason
that a bare substring test cannot tell a route from a token containing it — so a probe appearing in
an identifier could drop a route from the set, and since the ratchet fails only on *additions*, that
removal would never be reported. *This file's own recurring defect, one level down, inside the
derivation written to measure it.* The differential was **measured, not assumed: 0 routes today**,
both controls unmoved — so it is preventive rather than corrective, and applied because it closes the
silent-shrink path for nothing. Second: a route *leaving* the frozen set only printed. It now fails,
on `KNOWN_UNCALLED`'s stated reasoning — an entry leaves either because it gained a caller, or
because it was renamed, and then the frozen name is a stale string pre-authorising whatever reuses
that path. *"Both need a human; neither should print and pass."* The weaker precedent in the same
file was the wrong one to copy.

**This took four measurements to get right** — 377 and 35 in a previous gate, then 26 and 70 here —
and the pattern is identical each time: *the checker did not fail, it answered.* So the derivation
carries two live controls it must separate: `/bsdd/search`, wired an hour earlier, must fall out;
`/scim/v2/Users`, callerless by design, must stay in. Mutating the derivation to return nothing reds
the controls rather than silently reporting a clean tree.

### You can now look up a buildingSMART class, not just be told how few you have

The standards panel has always scored *what fraction* of the model carries a bSDD classification
URI -- "bSDD / classification coverage, 38%" -- and offered no way whatsoever to look one up. **A
coverage number with no means of closing the gap it reports.** The engine was already complete:
`services/api/src/aec_api/bsdd.py` is a read-only buildingSMART Data Dictionary client, and
`GET /bsdd/search` and `GET /bsdd/class` had been exposed for months with **no client caller at
all**. There is now a lookup card beside that figure: search the dictionary, open a class, read the
properties it defines.

**An outage must not render as an empty result.** bSDD is a remote service, so three states look
identical as a blank list and mean opposite things -- the dictionary is unreachable (try again), the
dictionary has no such class (it does not exist), your search matched nothing (your query was
wrong). `routers/standards.py` already separated the first two into 502 and 404 for exactly this
reason; `apps/web/src/portal/panels/bsddLookup.ts` is the pure rule that spends them, tested without
a DOM. 500 and 503 deliberately do **not** fold into "unavailable": those are our own bug and our own
deployment, not evidence about buildingSMART, and saying otherwise sends the reader to wait for a
recovery that is not coming.

#### A slower answer could overwrite a newer one

Review (CodeRabbit, PR #540) found a stale-render race, and it was real: the card's two actions —
search, and open a class — both write their result into the **same** element after an await, so the
slower request won regardless of which was asked for last. Search "wall", search "door", and if
"wall" resolved second you read wall results under the door query; clicking a class and then
"← results" raced the same way.

`requestGate()` in `apps/web/src/portal/panels/bsddLookup.ts` is one shared generation counter for
both actions. **One gate, not one per action** — two independent counters would each be internally
consistent and still let a stale class detail overwrite a newer search, because what is contended is
the output element, not the endpoint. Its own test then caught an off-by-one in it: generations count
from 1, so `0` — the value a caller holds before claiming anything — compared equal to the initial
state and read as the live request.

And asserting the gate's behaviour is not the same as asserting the panel uses it that way: giving
each action its own gate **typechecks cleanly** and leaves every behavioural test green. So the tests
also read `standards.ts` and assert one `requestGate()` construction with a guard on both writers.
*Asserting an outcome without asserting the path to it ran is vacuous.*

#### Two corrections to the reachability gate, both about the list rather than the routes

`/bsdd/class` was one of three routes frozen in `LEAF_COLLISION_DARK` in
`services/api/test_route_reachability.py` -- routes the reachability rule cannot see because their
last segment is also an ordinary English or HTML word (`class` is vouched for by ~1,756
`class="..."` attributes). Wiring it turned up two problems with the *list*:

**It was never complete.** `/bsdd/search` is the identical case -- same route group, same absent
`/bsdd/` fragment, leaf vouched by the English word -- and was not in it. The list describes itself
as the output of screening "every route whose leaf this rule reads as called but which never appears
path-shaped anywhere in the web source"; re-running exactly that query returns **twenty-six** routes
against three entries. Most of the remainder are legitimately web-callerless (`/scim/v2/Users` is for
an identity provider, `/bcf/2.1/projects` for external BIM tools), so twenty-six is an upper bound on
candidates and not a defect count
*(Superseded within the hour: **the real figure is 70 of 947 routes.** Twenty-six was measured with a
looser probe that asked whether the route's PARENT fragment appeared, which any sibling route
satisfies — so a called `/lod/assessment` vouched for an uncalled `/lod/matrix`, the same collision
one segment up. DARK-LIST-DERIVE below carries the corrected derivation and freezes it. Recorded
rather than edited away: a number that drifts toward the conclusion it supports is the hardest kind
to catch, and this one drifted in the flattering direction.)* -- but *a hand-curated list that describes itself as derived reads
exactly like a complete one.* The remaining candidates are filed as their own axis rather than
smuggled into a wiring change.

**And nothing could have noticed the fix.** All three per-entry checks assert the blind spot
*persists* -- not flagged, still a live route, leaf still vouched -- and every one of them stays green
after the route is wired, because the blindness is a fact about the leaf collision and has nothing to
do with whether a caller exists. That was measured, not assumed: `/bsdd/class` was wired and the file
re-run unchanged, all green. So the list could only ever decay in one direction, toward naming routes
that are actually reachable. A fourth check now probes for a real caller and reds when one appears,
with a positive control (`/bsdd/search`, wired by this change) so it cannot pass by measuring nothing.

#### `client.ts` has hit a hard compiler ceiling, and it changes where new routes can live

`/bsdd` is its own route group, so by the rule the API client has followed for ~20 SCALE-SEAM PRs --
*the seam is the ROUTE* -- these two methods should have been their own `withBsdd` mixin. They are
not. **Adding one more mixin to the chain in `apps/web/src/api/client.ts` makes `tsc` fail outright**
*(Corrected by MIXIN-CEILING below: this said "a 51st" and the chain held **49**, so it was the 50th.
The count was asserted, never counted. And the 50-mixin ceiling is now BYPASSED, not gone: staging
clears the measured failure, but TS2589 is a property of instantiation depth and a deep enough
composition still hits it. Where the staged limit actually sits has not been measured — saying
"gone" would repeat, in the correction itself, the exact error it corrects. See that entry.)*
with TS2589, *"Type instantiation is excessively deep and possibly infinite"*, on the `extends`
clause; removing it makes the error vanish, so the count is the cause and not anything in the new
code. New route groups can no longer get their own mixin -- they must lodge with a neighbour -- until
the chain is composed in stages. Recorded in `apps/web/src/api/ids.ts`, which took them, because the
next person to reach for `withX()` will hit the same wall and the error message names neither the
cause nor the limit.

### Test scratch directories no longer make `git status` read as uncommitted work

A stop hook flagged `services/api/_shelf_famgeom/` as work somebody had forgotten to commit. It was
not work -- `test_family_geometry.py` creates and removes it -- but nothing ignored it, so for the
seconds it existed it was indistinguishable from the real thing. **That is the entire cost, and it is
not cosmetic: a dirty `git status` from a concurrent or crashed suite run looks exactly like
uncommitted changes, to a hook and to a person.** Thirteen scratch directories were uncovered. The
suite already counted the residue on every run -- "N dir(s) this runner does not own" -- so it was
visible to the tooling and invisible to `.gitignore`.

`services/api/test_scratch_ignored.py` derives the population (every `"./<name>"` directory literal
in `services/api/*.py`) and delegates the verdict to **git itself** rather than reimplementing its
matcher. **Its first two drafts were both wrong in the way this repository keeps re-learning: the
checker did not fail, it answered.** Asked without a trailing slash, git cannot tell an absent path
is a directory, so every directory-only pattern missed and it reported 377 uncovered. Asked from
`services/` instead of the repo root, the paths resolved nowhere, the per-directory
`services/api/.gitignore` was never consulted, and it reported 35 -- which would have had nineteen
redundant patterns added to fix nothing. *A wrong question returns a confident number, and a number
with a list attached reads as evidence.*

So the gate now carries three self-tests, one per way of asking wrongly, and they run **before**
anything else -- a failed classifier prints no verdicts at all. The per-directory canary is
**derived** rather than named: an earlier draft hardcoded `test_ifc*/`, which made removing that
pattern for a legitimate reason red the self-test with a message confidently blaming the wrong cause.
*A check whose failure message can misdiagnose is worse than one that stays silent, because somebody
acts on it.*

### A saved scenario's name could run script in the Finance home

`ScenarioIn.name` is an unconstrained `str` that `create_scenario` persists verbatim, and the Finance
home interpolated it into `innerHTML` unescaped — stored XSS, one `escapeHtml()` away, in a line the
SCENARIO-SOURCES change happened to touch. Now escaped, like every other interpolation in that file.

**The interesting part is why nothing caught it.** `apps/web/src/ui/innerHtmlGuard.test.ts` exists
precisely for this class and was green over it for months, because that file's BASELINE listed
`"main.ts": 2` — and this was one of the two. **The ratchet is one-directional by design (a count may
fall, never rise), so a frozen sink is invisible for as long as nobody adds another.** The entry
means "a future reader should check this"; the check never happened, and a review bot found it by
reading the code the baseline had frozen. The baseline is now `1`, verified by counting rather than
assumed. *A number that licenses a defect is indistinguishable from a number that merely records
one — only reading the site tells them apart.*

### Which deal assumptions have a document behind them, and which came from nowhere

`GET /proforma/scenarios/{sid}/provenance` walks a saved scenario's material numeric drivers — the
numbers under timing, debt, equity, operations, exit and waterfall that produce the IRR an investment
committee acts on — and reports, per dotted path, whether a document citation is recorded against it.
It is R22-PROVENANCE ②, and **it had no client caller**: its leaf `provenance` was read as reachable
because `ProformaResult.provenance` is a *field* of that name on a different reply. **🔎 Sources**, in
Finance → home beside the returns it qualifies, is the first way to see it.

**The engine's own docstring sets the rule the screen has to honour:** *"A coverage figure with no
named gaps is the shape that gets quoted in a memo; the named list is the part that gets fixed."* So
the percentage is never the deliverable — the named paths are, and a `To fix` list renders every one
of them rather than a sample.

**Two ways a true number reads as a stronger claim than it is, and the screen refuses both.**

A scenario can report **100% coverage while every citation points at a superseded revision**. The
engine marks a path `cited` whenever any readable citation exists, regardless of the revision it
names, so coverage and currency are different axes and the headline carries only one. Currency is now
its own line, always.

And **`stale_citation_count: 0` means two different things.** Staleness is computed only when the
caller supplies `?revision=`, so with no revision the count is zero *because nothing was compared* —
indistinguishable from zero because everything is current. The response echoes `current_revision`,
which is the only thing separating them; the screen reads it and says **not checked** rather than
printing a check that never ran. It also offers the input that would actually run it.

**Two distinctions the screen keeps that a summary would collapse.** "No source recorded" and "a
source is recorded but is not a readable citation" are different fixes — find one, versus repair the
one you made — and the engine allows a path to be both. And this is **not** the provenance
`proforma/provenanceLine.ts` already renders: that one is declared-vs-defaulted, this one is
cited-vs-uncited. A number can be declared by the underwriter and have nothing behind it, which is the
ordinary and dangerous case.

**A third instance of the leaf-collision class, created by this change rather than found by it.** The
rules module declared `type Headline = … | "stale" | …`, and a bare `"stale"` string literal is a
whole path segment — so `/projects/{pid}/coordination/stale`, frozen as callerless, read as called and
`services/api/test_route_reachability.py`'s rot check fired within a minute. Renamed to
`"superseded-sources"`, which matches its sibling `"unreadable-sources"` and is the better word anyway.
*Three instances, three syntactic categories — a route path, an identifier, now a string-literal union
member. That the categories cannot be enumerated is the argument for the rot check rather than for a
naming rule.*

### The estimate can be calibrated against what this job actually cost

`GET /projects/{pid}/cost/calibration` compares the model's takeoff estimate with what the project has
**committed** (awarded subcontracts) and **spent** (posted direct costs) and returns the ratio as a
factor. It is the "learns from historical cost data" half of COST-AGENT, it has worked since v0.3.475,
`docs/roadmap-completed.md` records it under "P2 ring (shipped through 492)" — and **no client has
ever called it.** *A completed-roadmap entry is a claim about an engine; it was read as a claim about
reach, and nothing distinguishes the two.* **Calibrate from this job**, in the Estimate card of
Finance → Budget, is the first way to see it.

**Two things the screen refuses to do, and they are the reason it is more than a button.**

The engine clamps the factor to 0.5–2.0. One $500 mobilisation invoice against a $10M estimate is a
raw ratio of 0.00005, which comes back as a confident-looking **0.5** — read plainly, a finding that
the model over-prices by half. *The clamp does not make an unreliable ratio safe; it makes it look
reliable.* All three totals are returned, so `apps/web/src/portal/panels/costCalibration.ts` recovers
the raw ratio and says whether the figure was measured or is a boundary.

It also names what the basis IS. `cost.py` picks actuals over commitments whenever any direct cost has
been posted — right at completion, where actuals are the truth, and wrong at the start, where they are
a fraction of the job. *The preference that is correct at the end is wrong at the beginning, and
nothing in the route knows which end it is at.* Detected rather than guessed: while a job runs, more is
committed than posted, so `actual < committed` is "still running".

**The route's own advice was pointing at the wrong parameter.** Its `apply_hint` and docstring said to
apply the factor by passing `benchmark_factor` to `estimate_from_takeoff`. No HTTP surface accepts a
caller-supplied one — every call site derives it from the project's cost vintage — and the parameter is
already spoken for: it puts the GFA benchmark in the same **dollar-year** as the model total. Feeding
it a calibration ratio raises the benchmark, and since the engine trusts the model only while
`total >= 0.4 * benchmark`, that pushes `recommended` *away* from the model and reports an inflated
benchmark instead. `services/api/test_cost_calibration.py` asserts that direction on the real function
rather than arguing it, and refuses a hint that names the parameter without an explicit negation —
checking itself against the pre-fix wording first.

**Reachability.** The route was invisible to `services/api/test_route_reachability.py` because its leaf
`calibration` is vouched for by 85 uses of PDF-takeoff *scale* calibration. Screening that axis found
four more dark routes hidden the same way — `/bsdd/class` behind ~1,756 `class="…"` attributes,
`/proforma/provenance` and its scenario sibling behind a response *field* of that name, and
`/projects/{pid}/workflow/{key}` behind the plain English noun. They are now recorded there as a named
blind spot that asserts the collision is real, not merely that nothing was flagged. **A route leaf that
is also a common domain noun will be vouched for by the noun** — the rule matches a string without
matching its role, and unlike the earlier one-off collisions this one is a class, not an accident.

### The pay application can be read before it is signed

A GC could **freeze** a pay application and **download** it as a PDF, but never *look* at it. The nine
G702 certificate lines and the G703 continuation sheet existed on screen nowhere. **Review pay app**
in Finance → Budget now renders both from data, between seeding the SOV and creating the owner
invoice — which is the order the work actually happens in.

**This is the direct sequel to the over-billing bug below, and the reason it is worth doing.** That
defect lived in line 7, "less previous certificates for payment". Line 7 could only be seen inside a
PDF blob, so a wrong zero there was invisible until the next draw asked for the whole job again.
*A number a person cannot see is a number nothing checks.*

The screen does more than print. It verifies the certificate's own arithmetic — line 3 = 1 + 2,
line 6 = 4 − 5, line 8 = 6 − 7, line 9 = 3 − 6, and lines 4 and 5 against the continuation sheet's
totals — and says so above the numbers, because a certificate that does not add up is what a reviewer
most needs told. Comparisons are in integer cents: this codebase has already had HALF_EVEN and
HALF_UP disagree by a penny inside one G702, and `0.1 + 0.2 !== 0.3`. Line 5 is *skipped* rather than
failed on a final application, where `release_retainage` zeroes it by design — a check that reports a
correct certificate as broken teaches the reviewer to ignore the checks.

It also names **where line 7 came from**: deducted from what a submitted application actually
certified, or equal to the schedule of values re-added. Those are not the same fact — the first is
historical and does not move when the SOV is edited; the second is a reconstruction that does. Saying
which keeps a reconstruction from reading as a signature.

`GET …/cost/g702` and `GET …/cost/g703` had answered all of this since they were built and had no
client caller. They sat in the reachability gate's `CONFIRMED_DARK_SHORT_LEAF` with a note saying a
screen rendering the application from data would use them and none existed — and that note was the
whole entry, naming the missing work and waiting. Short-leaf ratchet **5 → 3**, and the three that
remain are all *correctly* dark: the SAML assertion-consumer endpoint the IdP POSTs to, and two
scheduler polls the server-side runner reads. **The ratchet no longer records any parked work.**

### A submitted pay application no longer makes the next one re-bill the whole job

**This is an over-billing bug that shipped**, and it is fixed. On a $100k line at 10% retainage with
$18,000 genuinely due, creating an owner invoice with the button in Finance → Budget and submitting
it moved G702 **line 7 from $45,000 to $0 and line 8 from $18,000 to $63,000**. The next draw asked
for everything earned to date, again.

**Why.** There were two builders for the same document. `cost.build_application` freezes the whole
application — the G703 continuation sheet, all nine certificate lines, `sov_snapshot_at` — and sat
behind `POST …/cost/pay-application` with **no client caller ever**. The route the button actually
called, `…/cost/pay-app/invoice`, assembled its own record from `g702()` **line 8 alone** and stored
`{number, amount, period, status, prime_contract}`.

The thin record was not merely smaller. `cost._certified_to_date` fills line 7 by reading
`current_payment_due` off submitted applications — a key the thin record does not have. So the sum
came out `0.0`, and **`0.0` is not `None`**. `None` is the sentinel meaning *fall back to
reconstructing from `completed_prev`*, which would have been right. A real number suppresses the
fallback. Creating the invoice therefore replaced a correct answer with a wrong zero — *the failure
needed the feature to be used*, which is why nothing caught it.

**The fix, and it is a consolidation rather than a patch.** `…/cost/pay-app/invoice` now calls
`build_application`, so there is exactly one builder and the record it writes carries its own
arithmetic. `…/cost/pay-application` is retired. The `prime_contract` link, the one field the thin
route set and the builder did not, is carried into the builder so consolidating trades no fact away.

Two more things fell out of reading it:

- **Every application was called "App 1."** `app_no` defaulted to `1` server-side *and* the client
  always sent `1`. It is optional now in both places, and the server allocates the number from the
  same atomic `ref_counters` row the human refs use. The button is relabelled **"Owner application
  from draw"**, because that is what it makes.
- **The period roll had two implementations too**, and they disagreed. `…/cost/pay-app/advance` was
  dark and counted *every* SOV row; the live `…/cost/advance-period` counts only rows with work
  billed this period. The dark one also returned a `next_application_no` derived from an
  `application_no` field on SOV lines that nothing sets. It is retired, and `test_closeout.py` — which
  had been written against the dark route's response shape — now exercises the live one.

**Review found that the first draft of that numbering was itself a defect, and named the wrong half
of it.** It read `app_no = 1 + len(records)`. `RefCounter`'s own docstring, in `services/api/src/aec_api/models.py`,
says that counter exists *because* a COUNT(*) scheme let a later create reuse a number after a
delete — so the fix for a money bug had reintroduced, on a money register, the exact scheme this
codebase retired for refs. The review described it as a race between concurrent requests, which is
real: no unique index on `data.number` refuses either writer, so two applications both become
"App 3". But the reuse half needs no concurrency at all — delete application 3 and the next one is
"App 3" again, every time — and that is the half that leaves a register unable to say which
application was paid. *A race-shaped description hides the half that reproduces deterministically,
and the deterministic half is the worse one.*

The allocation now goes through `modules.next_counter`, extracted from `_next_ref` so the primitive
is shared rather than private to its first caller. Its seed is a callable, consulted only when the
counter row does not yet exist, so the ordinary path stays one atomic `UPDATE … RETURNING`.
**And a second review round found the counter half-wired.** Only the *allocating* path moved the
mark, so a number chosen explicitly by a caller did not. Measured rather than argued: applications
1, explicit 7, then omitted produced **[1, 7, 2]** — no duplicate yet, which is exactly why the
first round missed it. The collision is deferred to whichever allocation later climbs back to 7 and
names an application that already exists. `modules.raise_counter` now lifts the mark to any explicit
number, atomically and portably (`CASE WHEN n < :v THEN :v ELSE n END` — Postgres spells the scalar
maximum `GREATEST`, SQLite has no such function and its `MAX` is the aggregate). *An off-by-one you
can see is safer than a collision you have to wait for.*

Two more from the same review: a non-positive `app_no` stored `"App -2"` while the route's
trailing-digit parse reported `2` — refused now at the builder, so a direct caller cannot bypass it —
and the "Owner application from draw" button is disabled for its own round trip, since creating an
application is not idempotent and server-side numbering labels duplicates rather than preventing
them.

Six regression assertions pin the money, including that the retired builder stays retired: its
response shape differed, so a caller written against it would silently receive a record where the
survivor returns an envelope. Routes 949 → 947, uncalled 58 → 56, short-leaf ratchet 5 → 3.

*A record that keeps the answer and discards the arithmetic is not a smaller record — it is one that
something downstream was already trying to read.*

### Every trade partner's record with your firm, and what it does not cover

`GET /benchmarks/vendors` has reported each subcontractor's cross-project commercial and compliance
history since R22-PROCURE-DEPTH ③ — subcontracts, commitments, invoices, COIs, lien waivers and
warranties, from six registers — and had no client caller the whole time. Its five `/benchmarks/*`
siblings all had one. It now renders in the Benchmarks panel, worst first.

**It is the route the entry below blinded the reachability gate to, wired in the same pull request.**
LEDGER-BROWSE's entity list contains `vendors`, so `/connections/{cid}/erp/vendors` became a URL this
client builds and the leaf `vendors` read as called — by something else. Wiring this removes the
blind spot's *subject* rather than leaving a record of it. The gate's two assertions pass unchanged
either way, which is exactly why they stay: **it could not see this route dark and cannot see it
wired.** Its verdict was, and remains, no verdict.

Three rules in `apps/web/src/portal/panels/vendorScorecard.ts` (20 tests), and all three are the
server's own — stated there in prose and enforced here, because a caveat that lives only in a JSON
field nobody renders is a caveat nobody reads:

- **`no_history` is NOT `clear`.** A sub who has never worked for you is an unknown. The engine calls
  a clean-looking record for an unexamined vendor "the single most expensive mistake this module
  could make" — and it is a *rendering* mistake as much as an engine one: three verdicts that reach
  the same pixel are one verdict. An unrecognised fourth verdict does not inherit green either.
- **A clean record here is silence about quality, not a pass.** `ncr` and `inspection` carry no vendor
  field, so nothing in this scorecard has looked at quality or schedule performance. The attribution
  line is stated even when the payload omits it — the silence is a property of the route, and a
  missing caveat reads as no caveat.
- **A certificate with no expiry is not cover.** "Expired", "expiry unknown" and "none recorded" are
  three states; printing "0 expired" for a vendor with no certificate at all is the `no_history`
  error one field down.

The headline states how many vendors have no record at all beside the watch count, so "3 on watch"
cannot be read as "and the rest are fine".

### An accounting connection's books can be read from the app

`GET /connections/{cid}/quickbooks/{entity}` and `GET /connections/{cid}/erp/{entity}` return a
QuickBooks or Sage/Viewpoint chart of accounts, vendor list or bill list. Both were finished on the
server and callable by nothing. A **Books** action now sits on every QuickBooks, Sage and Viewpoint
connection in the Data-connections modal.

**The two halves were dark for two different reasons, and only one of them was recorded.**
`erp` is three characters, under the reachability gate's `MIN_SEGMENT`, so the short-leaf ratchet
held it and named it as the next wiring candidate. `quickbooks` is ten characters, IS assessed by
the main rule, and the rule believed it called — off the string `"quickbooks"` in the connection-TYPE
`<select>`. A product vocabulary word, not a URL. The listed one was the one anybody could see.

Three rules in `apps/web/src/connections/ledgerBrowse.ts`, each because the server's answer and the
obvious rendering of it say different things:

- **A vendor failure is HTTP 200 with `{"error": …}`.** The route catches the vendor exception and
  puts the message in the body, so `res.ok` is true and the row list is absent. Rendering that as an
  empty table tells an accountant their books are EMPTY when the truth is that we could not read
  them. `outcome()` refuses to collapse the two, and checks `error` first and on its own — testing
  the rows first would classify every failure as "no records".
- **The QuickBooks count is capped at 50 and nothing pages past it**, so `count: 50` there is a floor
  and a company with 200 accounts sees 50 with no indication. The ERP read is uncapped. The same
  field means different things on the two routes, so it is never printed bare.
- **Row keys are vendor-cased** — Intuit's `Name`/`Id` against a generic ERP's lowercase — which is
  the COL-PAIR defect class, and is why the server's own `_info_erp` already hedges.

**Wiring a route blinded the gate to a different one, in the same commit.** The entity list contains
`vendors`, so `/connections/{cid}/erp/vendors` is now a URL this client builds, and
`/benchmarks/vendors` — dark since the gate was written, and frozen in `KNOWN_UNCALLED` ever since —
immediately read as called. It is not; its five `/benchmarks/*` siblings have client methods and it
still has none. Reachability work is not monotone: a new URL adds a segment to the corpus, and any
dark route sharing that last segment leaves the gate's sight. It is recorded now as a blind spot in
neither set, beside `/asset-rights/verify` and the two jurisdiction routes. The rot check earned its
keep — it was a bare `print` until 2026-08-20, and under that version this route would have dropped
out of the frozen list with no output at all.
### Two type-aware gates now see the tree on Windows

`deadFieldTyped.test.ts` and `responseUndeclared.test.ts` failed 9 tests on Windows and passed on
CI. Both compared a root built with `path.resolve` — backslashed on Windows — against TypeScript's
`sf.fileName`, which is forward-slashed on every OS, so `startsWith` rejected every source file and
both derivations walked an empty tree. Linux has no backslashes, which is why CI never saw it.
(`ts.sys.resolvePath` is not the fix: it hands the backslashed path back unchanged.)

They failed closed, which is the point of their vacuity guards — with one exception worth naming:
*"the tree's undeclared keys are exactly the known ones"* **passed** on the empty tree, because
`KNOWN_GAPS` is empty and so is a walk that looked at nothing. Only the guard beside it went red.

The fix had a trap in it. `deadFieldTyped`'s two filesystem scans compared their walked paths
against the same `API` prefix, and matched on Windows only because both sides were backslashed.
Normalising the prefix alone lets `api/` into both scans and every assertion still passes —
measured: the sound candidate set fell from 386 to 348, all green. So the two identical walks are
now one normalised walk, and a new assertion requires every declaring file the checker found to be
one the scans' `api/` exclusion removes; the un-normalised walk now fails it. `extract()` normalises
its own root, and a new self-test hands it a backslashed one, so the regression is caught on Linux
CI too.

### An npm override can no longer disagree with the dependency it overrides

`eslint` moves to **10.10.0**, and the engineering standards say so — `toolchainDocs.test.ts`
refused the bump until the prose caught up, which is exactly what it is for.

The new part is `apps/web/src/tooling/npmOverrides.test.ts`. The root manifest pins some packages
through `overrides`, and when such a pin drifts from the range a workspace declares, npm refuses
the whole install with `EOVERRIDE`. That already happened here once, on this same pair. The rule
has lived only in a changelog entry since — and a changelog does not run.

The population is derived rather than listed: every overridden package that is also a declared
dependency. Three of the four current overrides pin transitive packages nothing here declares, so
there is no pair to disagree and they are outside the population rather than exempted. The
comparator returns `null`, not `false`, for a shape it cannot read, and `null` reds the build — a
checker that quietly approves what it cannot parse goes green exactly when it stops understanding
its subject.

**npm applies two different rules, and the gate now applies each in its own position.** In the
root manifest — the same file as the `overrides` block — the two specs must match as RAW STRINGS;
`">=10.9.0"` beside an override of `"10.10.0"` is semver-compatible and npm still refuses it. In a
workspace manifest the raw rule does not reach, and npm resolves the declared range and rewrites
it to the override; `package-lock.json` records `apps/web` resolving `^10.10.0` to `10.10.0`,
which is npm's own proof. A single rule applied to both positions is wrong in one direction or the
other: too loose at the root, and red on a configuration that demonstrably installs in the
workspace. `$name`, npm's own escape hatch, is accepted in both.

### Extension-of-time claims, with the method that produced them

**Schedule** now assembles an **extension of time**. Pick an analysis method, and it grades each
delay event against the activity's float, states what the claim is worth, and shows its working.

It will not compute one without a method. The published taxonomies exist because the same facts give
different answers under different methods, so an EOT figure without its method cannot be weighed by
whoever reads it — and this one ends up in a claim. The method list comes from the engine itself, and
choosing one shows that method's own published weakness before you run it.

Two ways to run it, and the default is the auditable one: **from the captured baseline**, measuring
slip against a named, dated artefact and taking causes from the project's own detected events, so
both can be re-derived later. Typed dates still work for a claim argued before a baseline exists, and
are labelled as what they are — the baseline is the single most contested input in a delay claim, and
typed it cannot be checked.

Four things it refuses to round off, each because rounding it off would favour one party:

- **A delay absorbed by float is reported as absorbed, not as zero.** It earns no extension and it
  still happened; only the second reading says nothing occurred.
- **Slip with no matching cause is unattributed, never non-excusable.** Defaulting unexplained
  overrun to contractor risk hands somebody a finding nobody demonstrated.
- **Concurrent delays are named, never split.** Whether overlapping employer-risk and
  contractor-risk delay gives time, money, both or neither is a contract question the protocols
  themselves disagree on; a silent 50/50 would present the most argued number in the discipline as
  arithmetic.
- **A detected event with no stated duration is excluded and counted.** Detection establishes that
  something happened, never what it cost.

### Pedestrian wind comfort, screened from the massing

**📐 Design Metrics** now carries a **pedestrian wind comfort** screen. Give it a height, width and
depth — or leave them blank and they come off the model's bounding box — plus the site's mean
pedestrian-level wind, and it grades corner acceleration, downwash and channelling against the
**Lawson comfort categories**, lists the zone speeds, and names the standard mitigations: corner
chamfers, a podium, an entrance canopy, porous screens in a passage.

It answers in a second, which is the point: massing decides most pedestrian wind outcomes, and a
wind-tunnel study arrives long after the massing is fixed. **It is a screening heuristic, not CFD
and not a wind study** — no external service, no simulation licence, no weeks of turnaround — and it
says so on every result.

Three things it will not do. It will not call a result acceptable when a check did not run —
channelling is only looked at if you give it the gap to the neighbouring building, and without that
the screen says plainly that it is partial. It will not let the default site wind pass as a
measurement, because every speed on the screen scales directly with it. And when the dimensions came
off the model it says so, since a bounding box spans the site and context geometry as well as the
building.

### Buyout packages can be kept, and their RFQs sent

**Budget → Buyout packages** has always grouped the model's priced quantities into packages, each
with an RFQ scope. There was no way to keep them: the grouping vanished when you navigated away, and
the buyout workflow it feeds — draft → RFQ sent → quotes in → awarded — could not be reached from the
screen that produces its input.

Keeping them now creates one **Buyout Packages** record per group, in draft, visible to the whole
project and quotable by ref; each one then offers **Send RFQ**, which mints a Bid Solicitation
carrying the package's name, trade and due date and moves the package to RFQ sent. The confirmation
says what is being created before it is created, and re-grouping and keeping again is described as
adding a second set rather than replacing the first, because that is what it does.

Two refusals are reported rather than hidden. A grouping that produced nothing is reported as nothing
kept, not as a save of zero. And because the server mints a solicitation whether or not the package
was still in draft, a send that does **not** move the package says so and names the state it is
actually in — so a second send cannot look like a first one.

### An authority's data requirements can now be imported, applied and checked

A **requirement pack** is a set of data requirements published by an authority for a jurisdiction —
what a submitted model has to carry before it will be accepted. The whole mechanism was built and
none of it could be reached from the app: not the shared library, not the import, not the delete,
and not the two reads that apply a pack to a project and check the model against it.

All of it is now under **CDE / Standards → Data requirements (jurisdiction)**. Packs resolve from
the project's jurisdiction; a project with none is told so rather than given a default, because
requirements from the wrong authority are a different answer that looks exactly like the right one.
Every pack must carry its **authority, edition and source** before it can be stored, and every
result says whose rules produced it — a compliance number detached from that is the kind that gets
quoted at somebody. The built-in demonstration pack is labelled as one wherever its results appear,
so it can never be mistaken for a finding. An import that is refused shows the server's own reason,
which names the missing citation or the exact selector that would have silently matched nothing.

### The triangle census offered a saving you could not take

Model QA → Standards has always measured where a model's triangle budget goes and told you what a
coarse stand-in would save — *"proxy would save 47%"*. There was no way to build it.

There is now, in the same place the saving is quoted. It writes a **separate** file beside the
model; the model itself is untouched, and every box in the proxy is stamped as a stand-in that must
not be measured, scheduled or priced — a coarse shape mistaken for real geometry is worse than no
coarse shape at all. When a model has nothing worth replacing, the button is absent and says why
instead, and a build that stores nothing reports that plainly rather than as a success.

### Prefab kits are on the screen, and a released kit's scope can finally be written down

The prefab-kit register was built and had no way in. Every kit, worst first, now appears under
**Work → Prefab Kits**: its scope, its bill of materials, and the specific things blocking it, in
the order the shop cares about — a kit whose released scope has *drifted* from the model outranks
one that is merely late, because a late kit is a known problem and a drifted one is an unknown
wrong one.

The write that matters is **writing the scope**. Until a kit's scope is written down it is a
selector — a live query against the model — and a released kit in that state hands the shop
something that can change under it without anyone being told. Writing it resolves the selector once
and records the exact list of elements, after which any divergence is reported here instead of
silently changing what is being fabricated. Re-writing a scope says so plainly, because it can
change what a fabricator is already building.

The register refuses to write a scope that is empty, that comes from a selector which does not
parse, or that was cut short by a result cap — the last being the one nobody would notice, since
the count looks plausible and the list is quietly short. When no model is loaded the panel says the
figures cannot be checked rather than showing zeroes, which would be a wrong answer in the shape of
a right one.

### You can share a saved view — and delete now tells the truth about it

Saved views on a register could already be shared with the whole project. The app just never offered
it, so every view anyone made here was private whether they wanted it or not. Saving one now asks.

Three related things were wrong and are fixed together. Shared views from colleagues looked exactly
like your own private filters in the dropdown — they now say whose they are. The delete list offered
every view on screen, including other people's, which the server refuses; picking one reported *"was
already gone"* and then it was still there. It now offers only views you can actually delete. And the
confirmation claimed a view was *"yours alone"* even when deleting it would remove it for everyone
using it — it now says which.

### A lender draw package shows the schedule of values it was computed from

Generating a G702 draw package reported the payment due and how many schedule-of-values lines were
created, and stopped there. Two things it had already worked out went unseen: the G703 totals the
certificate is computed from — completed to date, retainage held, balance to finish — and the deal's
returns re-forecast with your actuals folded in.

That second one is the entire point of running the draw off the underwriting model: it answers "is
this still the deal we signed?" Both are now on screen beside the payment due.

### A pro forma now says how much of it you actually supplied

Solve a deal and Massing reports an equity IRR, a yield on cost, a development spread. Some of the
inputs behind those are yours; the rest the engine filled in with defaults. Until now the screen
could not tell you which, even though it had the answer — the server works it out on every single
solve and the app was discarding it.

Under the underwriting guardrails you'll now see a line like *"4 inputs behind these 6 figures were
defaulted by the engine: exit.cap_rate, debt.rate, ..."*, or confirmation that every input was
declared. It doesn't change any number. It tells you which numbers are worth arguing about, which is
the difference between a pro forma you can review and one you can only read.

If your server is older and doesn't send the breakdown, the line is omitted rather than claiming
everything was declared.

### A mistyped spec section is now caught while you can still fix it

Attaching a MasterFormat or UniFormat code to an element used to be typing into an empty box with an
example beside it. `80 51 00` instead of `08 51 00` — two digits swapped, into a division that does
not exist — was accepted without comment and became a permanent classification on that element.

Massing already knew the answer: the server publishes the full MasterFormat division master and the
UniFormat-to-MasterFormat crosswalk, and the app was throwing both away as they arrived. It now
reads your code back to you as you name it: *"Division 08 · Openings (Architectural)"* for a section
it recognises, and a warning for one it does not. UniFormat codes get the crosswalk — *"B20 ·
Exterior Enclosure → MasterFormat 04, 07, 08"* — so you can see what an element will be bought
through.

It warns, it never blocks: MasterFormat reserves whole ranges for divisions you define yourself, and
those are legitimate codes. If the reference can't be reached, classifying works exactly as before.

### Sealing a project now tells you the key people need to check it

When you save a project as a sealed `.mass` file, Massing signs it so that anyone else can confirm
the file is authentic and unaltered. The dialog said exactly that — and then could not tell you
which verification key to publish, because the app was never given it. It now names the issuer and
prints the key alongside, so you can hand it to whoever needs to check your releases. On a server
with sealing switched on but no signing key configured, nothing is shown, because there would be
nothing to verify against.

### The offline cost baseline can now actually be installed

The budget panel has been telling cost managers that an offline cost baseline is *"installable — no
subscription"*, and the app had no way to install one. The server has always had the importer; no
screen ever called it.

It is now in Profile & settings → Administration, under Server. It is deliberately not on the budget
card: installing a vintage reprices **every project that has not pinned one**, which is a server-wide
change and not something to offer beside one project's numbers. The budget card now names who can do
it instead of implying you can. The confirmation spells out the consequence, and projects with a
pinned vintage are unaffected.

### SAML single sign-on now works, and has a button

If your organisation runs its own identity provider — Okta, Entra ID, Ping, Google Workspace as a
SAML IdP, anything that speaks SAML 2.0 — Massing could already be configured to accept it, and the
sign-in screen still had nowhere to click. Worse, a server with SAML configured and no OAuth
provider showed a note advising you to set up Google or Microsoft sign-in instead, which was the
opposite of the truth. The login window now leads with **Continue with single sign-on** whenever
your server has an IdP configured and your plan includes SSO.

Two things had to be true for that button to be worth adding, and only one of them was. Signing in
through SAML had never actually worked: the server verified the assertion, created or found the
account, issued a valid session — and then stored it under a name the rest of the server does not
read, so the browser came back to Massing still signed out. The automated test covering that flow
checked that *a* session cookie was written, using the same wrong name the code did, so it reported
success for a sign-in that had never once let anybody in. Both are fixed; the test now asks the
server who it thinks you are, which is a question no spelling mistake can answer correctly.

If you had SAML configured and gave up on it, it is worth another try.

### A check that looks for unreachable features stopped being fooled by coincidences

Massing has an automated check whose job is to notice when part of the server ships with nothing in
the app able to reach it — a feature that exists, is tested, and that no user can get to. It decided
whether something was reachable by searching the app's source for the feature's name, and it searched
for that name *anywhere*, including in the middle of longer words.

So it could be satisfied by an accident. Adding a field called `available_public` to the cost screen
was enough to convince it that an entirely unrelated public-listing feature had been reached, because
the letters matched. The check then reported all clear — for something nobody had ever wired up. It
had been fooled this way twice before, each time noticed only by chance.

It now requires a whole-word match. That change found five more features the app cannot currently
reach, which are recorded for a later pass; it was verified not to lose any of the ones that really
are reachable. The first attempt at the fix was stricter still and would have wrongly declared 23
working features unreachable — the drawing exports among them — so the check now carries examples of
both what it must reject and what it must accept.

### Clearing an imported schedule now tells you whether it cleared anything

The "Clear import" button in the schedule panel undoes a Primavera P6 or MS-Project import by
deleting the activities that import created, leaving anything hand-entered alone. It reported
success the same way whether it removed four hundred activities or found no import at all — the
server always answers "cleared", and the count that distinguishes the two was never read. It now
says how many activities were removed, or that there was no import on record to remove — and when
it is talking to an older server that does not send the count, it keeps the previous wording rather
than guessing which of the two happened.

That was one of nine places where the app was throwing away something the server had already told
it. All nine now read the field; five of them show it:

- **Project health** reports what the incidents *were*, not just how many. The safety figures are
  broken down by OSHA classification — the first thing the server works out, and the one figure the
  card could not display — so five incidents no longer read the same whether they were near-misses
  or recordables.
- **Waiting for a model to convert** shows how long it has been going. A large model legitimately
  takes minutes, and the status said "running" from the first second to the last, which is also what
  a stuck job looks like. The elapsed time comes from the server, so it stays right across a page
  reload — and it is left out entirely rather than guessed at if the two clocks disagree.
- **Saving a pro forma scenario** reports the returns it solved to. The server solves the scenario
  as it saves it and sends the result back; the app discarded it, so a scenario that solved to
  nothing looked exactly like one that solved well until you opened the Portfolio.
- **The cost-database card** says what can still be installed. With nothing installed it read "0
  vintages installed", which sounds like there is no cost data to be had — when an offline public
  baseline needs no subscription at all.

The remaining four are values that repeat something the app already knew, or belong to screens that
do not exist yet; they are declared so the compiler and the audits can see them, and noted as such.

### The app now checks that it declares every field the server sends it

A field the server returns but the web app never declares is invisible — not just on screen, but to
the compiler, the linter, and every automated audit, all of which start from the declarations. So it
does not look like a bug. It looks like nothing.

Fifteen such gaps are now named and held by a check, and six have been read closely so far. Three of
them are not missing text on a page but a whole capability that cannot be reached: single sign-on is
fully built on the server and has no button anywhere in the app, so an organisation that configures
it still cannot use it; a signed release publishes the key needed to verify it and the app never
shows that key, which leaves a verifier trusting the document's own copy rather than an independent
one; and a saved view can be shared by the server but the app can only ever create a private one.
Another drops the payment-application schedule of values from a draw package; one fetches four
classification vocabularies over the network and keeps one; and one works out where an underwriting
result's assumptions came from and then never shows it.

None of this was reachable by searching for names. A name can mean two different things in two
places, and two different fields can share a name — so a text search answers confidently and wrongly
in both directions. The check reads the real types instead, and refuses to report at all on anything
it cannot resolve, because "found nothing" and "did not look" must never produce the same result.

### The desktop app is now started and checked before it is published

The installers for Windows, macOS and Linux were built, signed and put in front of users without
anything ever launching them. That is how the Linux app shipped in a state where it could not start
at all: every automated check reads the source code, and the fault only existed in the packaged
copy. The checks were green and the app was broken, and those two facts had nothing to do with each
other.

Every build now starts the server the app runs on and uses it before the release is allowed to
proceed — under the exact conditions the crash needed, since the same build started fine under
slightly different ones. It has to answer, reach its database, list every one of the 139 registers,
and serve the interface. On Linux that happens twice, and the second time is the one that counts:
the server is taken back out of the finished installer, the file a user would actually download, and
started from there. On Windows and macOS only the first check runs — the installers themselves are
still built and published without being opened.

The check is deliberately unable to pass quietly. If the app it is supposed to test is missing, that
is a failure rather than a skip — "nothing was wrong" and "nothing was looked at" are the two
outcomes that must never be confused. It compares the registers it gets against the registers the
project defines — by name, one for one — rather than against a round number, because an app that had
silently lost thirty of them would clear a round number, and one that lost a register while
double-loading another would clear a count. And it was itself tested against three deliberately
broken builds before being trusted, including a reproduction of the crash that shipped.

It also builds a model and opens it, which is the part that matters most and the part a startup
check cannot reach. The machinery that turns a building model into something the 3D view can draw is
only loaded at the moment someone publishes — so an installer that lost it along the way starts
perfectly, passes every other check, and disappoints the first person who tries to use it. That is
exactly what happened once already. Each build now creates a small model inside the packaged app,
publishes it, and requires the finished geometry back before the release may continue.

It insists on the right machinery, too. The desktop app has no copy of the tooling the server
version uses, so it has to fall back to its own — and every machine that assembles these builds
happens to have the server tooling installed. A check that accepted either would pass without ever
testing what a user actually runs, so this one names which is required and fails if the other
answers.

Proven both ways before being trusted: a deliberately broken build fails in one second and says
exactly what is missing, and a correctly built one passes and produces real geometry — because a
test that only ever fails could be failing for the wrong reason.

### The desktop app can show you the model it just built

Install the desktop app, create a project, upload an IFC and publish it, and everything worked
except the part people install it for: the 3D view stayed empty, permanently, and the app reported
success while doing it. Converting a model into something the viewer can draw was a step that only
existed on the server — the desktop download never contained it, so the app quietly skipped the
conversion and then had nothing to show. The web and hosted versions were never affected.

The conversion now happens inside the desktop app itself, using the model library it already ships
with. Publish a model and the 3D view fills in, offline, on a fresh install, with nothing else to
install.

It is a second implementation of the same file format, which is a real risk: two converters that
quietly disagree would be worse than one that plainly does nothing. So the two are run against the
same model on every build and checked against each other — same elements, same identifiers — and
both are opened with the viewer's own reader rather than with anything we wrote. Where they are
allowed to differ, they say so out loud instead of being made to match.

### An issue pinned on the model shows in the same place on the sheet and in 3D

An RFI, NCR or clash tied to the model can reach it two ways: somebody drops a marker at a point, or
the record names the element it is about. The plan sheet only ever read the second, and the 3D
viewer only ever read the first — so a marker dropped in the viewer appeared on no printed plan, and
an issue tied to a wall appeared nowhere in 3D. One issue, two surfaces, two different answers.
Both now read both, and the sheet is the full set.

A record placed at a point also draws immediately, with no model loaded — its position is where
somebody put it, so nothing has to be resolved first. Records tied to an element still need the
model, and the list continues to say how many it could not place rather than quietly returning
fewer.

**Underneath that was a bigger one: "no pin here" had never actually been stored as empty.** The
database recorded an absent marker as the *word* "null" rather than as nothing at all, so the query
that was supposed to fetch "only the records with a pin" matched every record in the register. The
pin overlay has a ceiling of 2,000; it was spending that ceiling on ordinary records, and the "N
pins on this project" count included them. Nothing was ever drawn in the wrong place — a second
check in the application caught them — but on a busy project the count was inflated and the overlay
could fill up with records that have no pin at all. Absent is now stored as absent, existing rows
are converted on upgrade, and the create form no longer writes an empty marker where it means none.

One more thing it fixes, found because a test started failing: the viewer's pin list was returning
**every issue on the project**, not the pinned ones. It has a ceiling of 2,000 and keeps the newest,
so on a project with more than that many issues the viewer could show almost no pins while having
plenty — the ceiling was being spent on issues that were never pins. It now returns exactly the
pinned ones. Note that this means the number it returns gets smaller, and correctly so: an issue
recorded against the whole model rather than a specific element has nowhere to be drawn, and is
still in the issue list.

**The gate written for this could not detect the bug it was written for, and only deliberately
re-breaking the code found that out.** The test passed with the fix removed, because the "null"
problem underneath made the broken and fixed versions behave identically.

### The Linux desktop app could not start

The published AppImage and .deb quit before they drew a window. The bundled server looked for the
web build by walking a fixed number of directories up from its own file — a number that is right in
a source checkout and wrong inside a packaged app, where the code is unpacked into a temporary
directory. On Linux the default temporary path is exactly one level too shallow, so the walk ran off
the top of the filesystem and the process died with `IndexError` before it ever reached the copy of
the web build packaged beside it.

The same binary starts normally when the temporary directory is deeper, which is why macOS and
Windows were unaffected: their temporary paths are twice as deep. It was found by downloading the
released build and running it, not by reading code.

**Fixing that one file would not have fixed the app.** Three modules counted directories the same
way, and two of them did it while being imported rather than inside a function — so the app would
have stopped one line later, in a different file, with the same kind of error. Every place that
looks for the program's own files now asks one shared question that recognises a packaged build and
says "there is no source checkout here", instead of counting directories and hoping.

Twelve more places were counting correctly enough not to crash and still pointing outside the
packaged app — two of them at directories that have never existed in the source either. Because each of them checks whether the directory is there before using it, none
of that ever surfaced: a wrong answer and a missing folder look identical, and something else quietly
answered instead. Those are corrected too, and a build-time check now refuses any new one.

Nothing in the release pipeline launches the application it builds, which is why every check was
green. That gap is now recorded as work of its own.

### The guard against a test writing into your database was itself half blind

An earlier change added a rule: a test that can create a schema must decide which database it creates
it in, rather than inheriting whatever the shell is carrying. That rule was real and the check for it
was real. What the check *looked at* was not — it decided whether a test could create a schema by
searching for a literal call to the table-creating function.

Starting the application creates the schema too, and a test that starts the application contains no
such call. **355 test files were in that blind spot, and four of them named no database at all.** One
of them, run the way its own instructions describe with the variable set, was measured creating 173
tables in the wrong database and reporting success — the same number that motivated the original
rule, in the part of the codebase the rule could not see.

The four are fixed, and the check now recognises a test that starts the application. The rule was
being enforced on 32 files; it is now enforced on 383.

A follow-up widened it again, after review pointed out that the check recognised only one of the
three ways a test can start the application. It now also recognises a client that is stored in a
variable before being started, and one imported under a different name. **No file in the suite was
being missed** — every file written the first way is also written the second — but a check that is
narrower than the rule it stands for is a gap with nobody in it yet, and the tree agreeing with it
today is exactly what makes the gap invisible.

### An issue tied to a wall shows on the model, whatever register it lives in

Binding a record to an element by GlobalId is how you say *this problem is here*. It worked for RFIs
and punch items. For a coordination issue, an NCR, a deficiency, an incident — and thirty-two other
registers — the record saved, reported that it was attached, and then appeared on no drawing and in
no viewer.

The pin resolver decided which registers hold pins from a list written by hand, and six of the eleven
names on it were not registers at all: they were the *words* for those ideas. Every clash imported
from Solibri or Navisworks becomes a "coordination issue", and the list said "clash" — so the clashes
the resolver exists to place were the ones it could not see.

Which records can carry a pin is now read from the registers themselves, from the same setting the
3D viewer has always used. The plan sheet and the model now show the same set, which is what the
sheet already claimed to do.

### Field-verification coverage says how much of the work is actually photographed

The coverage card showed how much of the model is verified and installed, and how many deviations
were logged. It did not say how much of that is backed by a photo — even though the server has been
computing exactly that, including the count of deviations with no photo at all, which it describes as
the handover number: a deviation with no photo is an assertion with nothing behind it.

The card now shows the share of tracked work that is photographed, names the denominator it is
measured against, and warns when deviations are unevidenced. Twelve deviations and twelve deviations
with nine unphotographed are different things to hand a client at closeout.

### A valuation that could not be computed no longer reads as a valuation of zero

When a project has no proforma and no comparables, none of the three appraisal approaches produces a
value. The valuation screen used to print **$0** as the opinion of value, in the same large type it
uses for a real one — so a property that could not be appraised looked like a property worth nothing.
It now shows a dash and says what is missing and what to add.

The same screen was quietly showing less than the valuation report built from the identical data. It
now names which of the three approaches reconciled into the value and says when the others were
excluded, shows the implied cap rate the comparables carry, shows the median that matches the basis in
force (a per-unit valuation used to display an empty "$/SF" row), shows the depreciation percentage
beside the amount deducted, and shows a missing cap rate as absent rather than as 0.00%.

It also names comparables the appraiser excluded. The server has been reporting those for some time,
precisely so a valuation whose sample shrank reads as a decision somebody made rather than as a
thinner market — but the web app had no field for them at all, so no one ever saw it.

### The pin count and the pins it describes are proven to come from one read

The pin overlay fetches a page of pins and the project-wide total in a single database read, so the
number beside the list always describes the list. That was implemented two releases ago and never
verified — the code could have been reverted to two separate reads and every one of the project's
tests would still have passed.

It is now checked directly, and the check fails if the single read is broken apart.

The concurrency scenario itself — another user filing an issue in the instant between two reads —
turned out not to be reproducible in the project's local test database, for reasons recorded next to
the test. Rather than write a check that would pass whether or not the code was correct, the test
states the limit plainly and verifies the property a different way.

### Pin totals on older projects stop being approximate

A pin total on a capped project was reported as an upper bound, and the printed plan sheet said so
with a `~`, because records saved before the previous release could hold an *empty but not absent*
value where a pin's location goes. Those records looked like pins to the fast database filter and
were then rejected, so they inflated the count without ever appearing.

A migration clears them. New records have not been able to carry these values since the previous
release, so this is a one-time cleanup of history rather than a patch over an ongoing problem — the
eleven other places that write a pin location were read and none of them can produce one.

Records at the project origin are explicitly preserved: a location of 0,0,0 is a place, not a
missing value, and treating it as empty would have deleted real pins.

### A printed plan sheet now says when its pin list was capped

The pin overlay was fixed to report a cap; the **printed sheet stayed silent**. A superintendent
walks the building with paper, so the half that reaches the person at risk was the half still
missing — a capped sheet printed a confident subset and looked complete.

A capped sheet now carries a note: *"Pin list capped at 2000 of ~2400 project pins — this sheet may
not show every issue on this level."* It is deliberately **qualitative about the sheet and
quantitative only about the project**. The cap is spent before pins are filtered to a storey, so how
many of the dropped pins belonged to *this* level cannot be known at either end, and printing a
per-sheet number would repeat the original defect in a new place. The `~` marks the total as an
upper bound while legacy records with empty-but-not-null pin fields still exist.

A sheet with **no** pins left after a cap still warns — that case is the blank overlay reaching
paper, and it is exactly when "this level looks clean" is most wrong.

The blocker recorded for this in the roadmap was false: it said the drawing engine takes positions
and labels, not notes, when the engine had been printing *"N pin(s) not located on this sheet"* all
along. Nobody had checked the claim against the code.

### The pin overlay went blank on busy projects, and nothing said so

Pins are how an issue gets a place in the building — an RFI on *that* wall, a punch item at *that*
door. The engine that resolves them took the project's 2,000 oldest issues and then discarded the
ones that are not pins.

Most issues are not pins. On a project with more than 2,000 of them — which is an ordinary
mid-size job, not a stress case — the 2,000 oldest were mostly ordinary un-pinned RFIs, so the
overlay came back with **nothing on it**, and a pin you placed this morning never showed up, because
the window never moved past those same 2,000 rows. It did not fade as a project got busier. It went
blank and stayed blank, on the model and on every plan sheet, with no message.

The test for "is this a pin" now runs in the database, before the limit, so the limit is spent on
actual pins. The eleven registers that can also carry pins used to get 2,000 each and then have the
combined list chopped back to 2,000. They now share one budget — which does not change which pins
you see, but does mean the ones that did not fit are counted rather than quietly discarded, so the
number beside them is the project's.

And the count that comes back is the project's, not the screen's. Where the overlay has more pins
than it can show it says how many there are — and where that number is an estimate rather than an
exact count, it says that too, instead of quietly rounding in its own favour.

Two things this does not yet do, said plainly rather than left to be discovered: a printed plan sheet
still cannot show that its pins were capped, and the total is an upper bound rather than an exact
figure on projects carrying older records.

### Three screens that showed you part of the answer and called it the answer

The sibling of the fix below, and the milder half. There the rows were wrong; here the rows are
right and the **number beside them** describes only what fitted on screen while being named for the
whole.

**The equipment schedule was the one that costs money.** It groups a model's procurable equipment
into RFQ line items, and it caps the list — reasonably, since a schedule is a document rather than a
data dump. But it reported the capped figure as the line count *and* summed the quantities of only
the lines that survived, so on a large model the RFQ you sent out was short in both the item list
and the numbers, in the direction that under-buys. It now says how many lines there are in total and
marks itself truncated; the lines are ordered largest-first, so a capped schedule drops the smallest
items rather than arbitrary ones.

**A topic's timeline** reported the number of events it was showing, not the number the topic has —
and the ones it drops are the oldest, which is where a decision's origin sits. **Viewer load
timings** reported the capped row count as the period's total, with every percentile beside it
computed from the newest slice while labelled as the period's.

Nothing was hidden deliberately in any of the three; each simply had one name doing duty for two
different numbers. All three now carry a total beside the count and say when they truncated.

### Two more screens that said "nothing here" while something was there

Fixing the agent trail (below) raised an obvious question nobody had asked: *how many other screens
answer a question by taking the most recent N of something and then narrowing?* Two more did, and
both were reporting an empty answer to a person who had every reason to trust it.

**Import history.** Finance ▸ where these numbers came from listed the newest hundred import
batches across the whole installation and *then* kept the ones belonging to the project you were
looking at. On a system where another project has been importing more recently, a project's import
history came back **completely empty while imports existed** — measured with one import on a quiet
project and 150 newer on a busy one. An empty lineage is the worst possible shape for that
particular answer: somebody reading it is trying to find out where a figure came from, and "nothing
was imported here" is a conclusion they will act on.

**The notification bell.** The feed took the project's two hundred most recent events and then
worked out which of them concerned *you*. On a busy project that window can be a single day, so a
person whose assigned work was older than it saw **an empty bell while holding open records
assigned to them** — measured going from one item to zero behind 250 events by other people. The
"my work" list directly beside it had always done this correctly; the two now work the same way.

Both now narrow first and cap second, so what you see is the newest N *of your things* rather than
your things among the newest N. A capped import history also now says how many batches there are in
total, so a hundred-of-a-hundred-and-fifty view stops reading as the whole file — the ledger's
**Import lineage** heading reads "newest 100 of 150" when there is more than it is showing.

### The agent trail said "nothing ran here" while runs existed

Every AI agent run against a project is recorded — which tool, through which named pack, by whom,
and whether it failed. That trail is the thing an organisation checks before letting an agent near
its projects, and the thing it reads first after something goes wrong.

It was quietly dropping runs. The console asked the database for the most recent activity and only
*then* narrowed it to the project you were looking at — so on a deployment where one project is
busier than the rest, a quieter project's console could report **no agent activity at all while
activity existed**. Measured: one run on a quiet project, a few hundred newer runs elsewhere, and
the quiet project's console showed nothing. The busy project lost older rows the same way, without
saying so.

For this screen that is not a blank, it is a wrong answer — "no agent touched this project" is
exactly the claim someone acts on. The narrowing now happens in the query, and a capped view says
how many runs there are in total beside how many it is showing.

**Settings ▸ Diagnostics ▸ Agent runs** is new: every agent run across every project, who ran it,
which pack it came through, and which failed — instead of opening each project's console in turn and
adding them up. It is admin-only because these are audit records, and the audit log is already
restricted to administrators. A run nobody could attribute is listed as unattributed rather than
hidden, since those are the ones worth looking at.

### Resourcing "by department" — the axis your firm defines, not one we invent

Portfolio resourcing already showed weekly demand per trade summed across every project, which is
the only place a crew promised to three jobs in the same week is visible at all. It could not group
those trades into the units a firm actually staffs by, because nothing in the schema is called a
department — and rather than invent a column, that was left open as a product question.

Checking how the industry's own tools model it settled it: the dominant AEC ERPs ship **no
department dimension either.** They give a configurable organisation breakdown whose levels and
labels the firm chooses. The axis is firm-defined, and the two readings the question was stuck
between turn out to be different *populations* rather than different labels — a general
contractor's departments are office functions (preconstruction, estimating, operations, safety)
whose people are salaried staff, not the field trades on a resource plan, while a design firm's
axis is discipline, which is already exactly what the field holds.

So no field was added. **Settings ▸ Portfolio resource grouping** takes a declaration
(`Structure:ironworker,concrete; MEP:electrician,plumber`) and the portfolio panel rolls the whole
book up by it, beneath the trades it is made of. A group cap flags a department over-committed
across projects where no single trade in it is. `Test` in that Settings group validates the
grouping on the spot instead of leaving you to discover a typo on someone else's screen.

The roll-up refuses two shapes outright, because a group total that is quietly wrong looks exactly
like one that is right: a trade claimed by two groups (the totals would then sum to more than the
book, and neither group is the right one to charge it to) and a group with no trades (which would
report a confident zero). It also names what it did *not* cover in both directions — demand no
group claimed, and a group naming a trade the book does not have — and a group whose trades are all
absent is shown as carrying no demand rather than zero demand.

### The dead-field sweep was asking a question its method cannot answer

An internal audit axis checks whether every field the API declares is actually *read* by the web
app — a field with no reader is a candidate for "a caveat that never reaches the screen", which is
how a number gets shown without the warning that qualifies it. The roadmap recorded that axis as
blocked on reading ~35 remaining fields one by one.

Re-deriving it found a different blocker. **The scan matches a bare identifier, not a type.** So
`SpatialNode.elevation` — referenced in dozens of files and by none of them as a `SpatialNode`,
because storeys, drawing grids and GIS overlays all happen to name a field `elevation` — is counted
as read while nothing renders it. Across the tree, **256 of the 719 fields counted as read, 35%, have
no reader that even names the declaring interface.** It fails hardest on `name`, `key`, `id`,
`title`, `status` and `count`, each referenced in 200+ files — which are the names most likely to be
displayed. A freeze list built on this would be guaranteed wrong rather than merely unverified.

The population is now re-run by a test rather than remembered, with the collision pinned as a fact:
identifier readers present, typed readers zero. Making the scan sound needs a type-aware pass over
the TypeScript symbol table, and that is now what the entry says. Two bugs in the derivation itself
turned up on the way — matching only top-level fields cannot see a *nested* one, and this axis's one
real defect was nested; and including the generated OpenAPI types reports 730 instead of 32.

Seven more fields were read while doing it and none was a defect, which is consistent with the
earlier rate. One is worth naming: a cost-variance figure that looked unread turns out to be a
documented refusal — comparing a realised overrun against an entered contingency is a claim about
what an underwriting asserts, not a unit conversion.

### Renaming a responsibility column moves its cells with it, or moves nothing

The RACI/DACI matrix stores two halves of one fact in two places: the **role columns** in a config
record, and the **letters keyed by those column names** on every activity row. The panel changed
them separately — one `PATCH` per row from the browser, then the config update — so a failure
anywhere in that sequence committed the rows it had already reached and abandoned the rest.

A half-applied **rename** was the bad one. Some rows carried `GC / PM`, some carried
`Project Manager`, and the column list still said `GC / PM` — one logical role under two names, one
of which was no longer a column, so its cells rendered as blank and counted toward nothing. That is
indistinguishable on screen from an orphaned column, and re-running the rename did not repair it:
the rows that had already moved no longer matched the name being renamed. Reproduced at five rows
splitting three-to-two.

The column edit and the cell migration are now one server-side transaction.
`PUT /projects/{pid}/responsibility/config` takes an optional `rename` map and a `drop` list
alongside `roles` and `mode`; the rename moves cells with their column, `drop` clears a removed
column's cells, and a mode change remaps the doer letter (R↔D) on every existing row. Nothing is
written unless all of it can be, and a request whose `roles`, `rename` and `drop` contradict each
other is refused with a 400 before anything is touched — renaming one live column onto another was
a silent merge that ate a column's cells. The panel's four row loops are now four single calls.

**A second, quieter instance of the same split, fixed with it.** Loading a starter template in the
other mode moved the matrix to DACI without migrating the rows already on it. Those rows kept `R`,
which is not a DACI letter — and the grid hides any letter invalid in the current mode, so they did
not render *wrong*, they rendered **empty**, and five activities reported having nobody Responsible.

**And a third, found by touching the transaction boundary rather than by looking for it.** Both
responsibility write routes recorded an audit entry *after* the engine had already committed, into a
session nothing commits again — so every change to the role columns, the one edit that can orphan an
entire matrix, left no trace in the audit log. `audit.record` only `db.add()`s, and `get_db` closes
without committing. The route now owns the only commit in the request, so the change and its trail
land together or not at all.

The class is a gate — `services/api/test_audit_commit.py`, which fails closed on any of the 106
`audit.record` call sites it cannot resolve. **Its first version asked the wrong question**, and
review caught it: "is there a `.commit()` at a later line in this function?" is not the same as "is
a commit reached on every path out of here". `run_clash_federated` was a live third instance the
whole time — its coordination branch records an audit row, and the only commit sat inside
`if create_topics and not coordinate`, a branch that is mutually exclusive with it. Later in the
file, never on the same path. The classifier now climbs out through enclosing blocks and counts only
commits that always execute, and it is proved against that branch shape before it may report.

### Feasibility sizes the building on the real parcel, not on its bounding rectangle

The "Generate from zoning" tab could describe a lot only as **lot width × lot depth**. For any parcel
that is not a rectangle — a corner lot, a flag lot, anything with a cut corner — that describes a box
*around* the lot, and a box's area is always larger. The error is not cosmetic: lot area sets max
GFA, which sets floors, which sets the unit count, which sets rent and the acquisition proforma's
IRR. Every one of those came out optimistic and none of them said so. On an L-shaped 1,600 m² lot
inside a 50 × 50 m box, the rectangle yields **5,000 m² of buildable GFA against the parcel's true
3,200** — 56% more building, on the number a deal gets priced from.

Three pieces existed and had never been connected. The parcel reader parsed a real GeoJSON/WKT
boundary and projected it to metres — then returned the area and threw the projected outline away.
The massing engine had always accepted a `lot_polygon` and offset it inward for a true buildable
footprint, and nothing could reach it: the request type had no such field. And the parcel reader
itself had no caller on any screen.

Now: paste a boundary (or load a `.geojson` / `.wkt` file) on the feasibility tab — one outer ring,
so a WKT `MULTIPOLYGON` is refused by name rather than sent to an endpoint that would reject it, and
a ring that encloses no area (repeated or collinear points) is refused with the reason rather than
priced as a lot of zero square metres. It reports the
parcel's area, the rectangle it replaces, and the percentage between them, and the width/depth boxes
become the parcel's own bounding extents, disabled — so it is clear which figure the building is
being sized on. The result summary says the same thing again beside the GFA. Nothing is substituted
silently; a user who prefers the rectangle can clear the boundary and still have it.

**A gate was wrong in the same direction.** `test_body_param_reach.py` decides whether the web app
sends a given request field by looking for it in the source — and only recognised object-literal
syntax (`key:`). A body assembled field by field (`p.dome_radius = …`, which is how this tab has
always sent its optionals) was invisible to it, so `dome_radius` sat on the "nothing sends this" list
while a control on that very tab had been sending it all along. Two false positives out of 27, in the
direction its own docstring calls the expensive one. Assignments now count; comparisons and arrow
parameters still do not, and a self-test pins the distinction.

### Parcel boundaries and T&M reports: four corrections from review

- **A line with no rate but an amount already entered was reported as excluded.** Only a line with a
  *typed rate* was counted as being in the ticket total, but an amount entered directly never reaches
  the rate-extension step at all — it survives untouched and is summed into the total regardless. The
  same contradiction the previous entry fixed, one path over, and the fixture there could not see it
  because it had a rate.
- **A parcel boundary with a repeated point produced a wrong buildable footprint.** Stripping the
  duplicated closing point is not enough; an interior repeat survives it. The setback offset divides
  by each edge's length and guards against division by zero, so a zero-length edge does not fail —
  it leaves that corner un-inset while its neighbours move, and returns a plausible polygon with the
  wrong area. Repeated points are now removed before anything is measured, and a boundary with fewer
  than three distinct points is refused.
- **Clearing a parcel while it was still loading could bring it back.** Press "Use this parcel", then
  Clear before the response arrives, and the late response republished the parcel just dismissed —
  after which "Generate IFC model + apply" would save a model and a proforma for a lot the panel no
  longer showed.
- **A WKT `MULTIPOLYGON` was accepted by the panel and rejected by the server.** Refused locally now,
  by name, with the export that works. Supporting it properly is a design question rather than a
  cleanup: the buildable footprint comes from offsetting one outer ring, and a lot split by a
  right-of-way has no single ring to offset.

### T&M pricing: an unpriced line that was in the total after all

A follow-up review found the pricing report contradicting the figure printed beside it. An equipment
line with a rate the user typed, a blank amount, and a register rate quoted per Day/Week/Month was
listed as unpriced — *"8 hours are NOT in the figures above"* — directly beneath the $800 the engine
had just added to that line.

Both halves were doing something defensible. The register genuinely cannot price the line: converting
a weekly rate against hours needs a working day nobody stated. But `equipment_lines.rate` is declared
in `$/hr`, so when a rate is typed, `rate × hours` is the **line's own** arithmetic and is computed
like any other line — the register's unit is a fact about the register, not about the line, and
refusing the sum would drop a line the superintendent priced out of the ticket total.

So the sum was right and the sentence was wrong. A pricing run now says which of the two happened:
a quantity nothing could price still reads "NOT in the figures above", while one the line priced
itself reads "in the figures above at the rate you entered, not the register's". Overtime and idle
hours are unchanged — nothing multiplies those, here or anywhere, because a 1.5× premium is a
contract term rather than a default.

The fixture that missed it gave the line no rate of its own, so the old sentence was true by
accident. That is the fourth time in this item that the case distinguishing two behaviours was the
case nobody wrote.

### T&M pricing: five corrections to the first cut

Review of the merged TM-RATES change found the pricing engine wrong in five ways. All are fixed, and
none of them was reachable from the original tests:

- **Material never priced.** The line table's item name lives in `description`; the code looked for a
  `material` column, which `material_lines` does not have. Labour and equipment happened to use the
  same name on both sides, so one conflated field looked right in two cases out of three.
- **A hand-entered amount was overwritten.** 8 hours plus 2 overtime written up at $1,045 became
  $760, and a lump-sum line with no hours became $0. A typed amount is evidence for the same reason
  a typed rate is — it may carry a premium or an allowance both parties agreed. It is now reported
  when it disagrees with rate × quantity, never replaced.
- **A register row with no rate priced the line at $0** and reported it as a success.
- **A rate quoted per Day or Week was extended against hours** — a $1,200/week crane read as $9,600
  for an eight-hour day. It is now reported unpriced, for the same reason overtime is: converting
  needs a working day nobody stated.
- **A closed (superseded) rate beat its live replacement** and was snapshotted onto the line.

Review of those fixes found three more, also fixed here: an unpriced line labelled its quantity with
the rate column (*"8 rate are NOT in the figures above"*), the rate comparison still rounded
half-even while the amount beside it rounded half-up — which can report a rate variance over a
figure that agrees to the cent — and one test sequenced its setup so a fixture failure would have
skipped the pricing rather than failing.

### T&M tickets price themselves from the project rate registers

**TM-RATES.** The eTicket register carries three line tables — labour, material, equipment — and the
project carries three rate registers to price them from. Nothing connected the two: a superintendent
typed the rate onto every line by hand, which on a T&M ticket is the number that gets argued about
when the change order is negotiated. **Price from rate tables** on the ticket now fills each blank
rate from `labor_rate` / `material_rate` / `equipment_rate` and recomputes the amounts, and the
totals follow from the lines.

It answers for what it did NOT price, which is the point:

- a rate somebody **typed** is kept as typed, and its disagreement with the register is shown with
  both numbers — a T&M rate that diverges from the contract rate table is what a GC needs to see
  before signing, not something to correct silently;
- a trade or material no register knows is left untouched and named, with the register that would
  fix it;
- **overtime and idle hours come back unpriced.** Neither register holds an OT or idle rate, and a
  1.5x nobody agreed to is a contract term, not a default.

Re-pricing after a register changes does not re-rate work already done — the rate is a snapshot —
but it does report that the register has moved since.

**The route existed since June and nothing called it, and worse than that.** It wrote the totals
straight onto the record; `apply_table_totals` — six weeks younger — recomputes every total from its
table inside the same write, so the priced figure was replaced by the sum of the untouched `amount`
cells while the response returned the correct number. Measured: `200 {"labor_total": 760.0}` over a
record holding `0.0`. It also wrote `tm_lines`, a field the module does not declare and nothing
reads. `test_cost.py` asserted the stored total and passed, because its fixture ticket had no line
tables at all — the one shape in which the write-back survives.

Found by a new derivation: **which required request parameter no web client sends** — the mirror of the
response-field sweep. `services/api/test_body_param_reach.py` now gates it, and reaches inside
`test_route_reachability.py`'s documented blind spot: that gate skips any path segment under five
characters, and this route's leaf is `tm`.

### the review-cycles card says how many rounds it could not measure

"Whose court did the time sit in" is the question that card exists to settle, and it was answering
over fewer rounds than the register holds. A review round with no submitted date cannot start a
clock, so it is left out of the split entirely — correctly — but the round count printed beside the
days was the *scored* count, with nothing saying so. Two dated rounds out of five recorded read as a
complete answer.

It now says it: **"3 more round(s) carry no submitted date and are NOT in the figures above — the
split covers 2 of 5 recorded rounds"**, with a nudge to add the dates. The card already handled the
sibling case, rounds still open, with exactly this care; this is the harder one, because an undated
round is not counted at all.

The days figures also now name their basis — **calendar days**, because a statutory review clock
does not pause for a weekend, while durations elsewhere in this system are working days. The engine
had always returned that axis and nothing printed it.

### the responsibility matrix stops telling you it is complete when it is not

Load a second starter template into a RACI matrix that already has rows and the columns changed
under them. The earlier rows survived — the dialog promises they will — but every letter on them was
now keyed to a role column that no longer existed, so those rows rendered as blank lines. And the
validation banner still said **"Every activity has exactly one Accountable and at least one
Responsible"**, because it counted assignments the grid had no cell to draw.

Validity is now counted over the columns you can actually see, so a row whose letters have been
orphaned reads as what it is: no Accountable, no Responsible. The letters are not lost — the banner
names the columns they are stranded on, and offers to **restore those columns** (nothing was
deleted, so bringing them back makes the assignments visible again) or to **clear them** if they are
genuinely finished with.

Applying a template no longer replaces your columns either: when the matrix already has rows, the
template's roles are merged in after yours instead of taking their place. If that would push past
the sixteen-column limit the whole thing is refused before anything is written, rather than
truncating and orphaning the very rows it was about to create.

### you can now see which property values this element overrides — and put them back

The viewer has always let you set a property on a selected element. It has never shown you that a
value you were looking at was **this element's own**, written over what its type says — and once you
had done it, there was no way back. Both halves are here now.

Properties that override their type are marked, and the panel prints the value the type carries
underneath, because a badge saying "overridden" without saying *what it replaced* is half an answer.
Next to it is **Reset to type**, which drops this element's value so the type's shows through again.
It appears only on properties that actually override something, since that is exactly when it can
work.

If the panel cannot find out which values are overridden — a request that fails, an index still
rebuilding — it **says so** rather than showing an unmarked list. An unmarked list would look
identical to "nothing here is overridden", which is a different and much more reassuring claim than
the one we can actually make.

### a project can change its units, and move a far-flung model back to the origin

Two things a modelling tool is expected to do had no control anywhere in the app. Both engines were
built, tested, and reachable through the edit API the whole time; the coverage matrix listed them
under *"a capability no user can reach"*, which is that file's own words for a defect.

**Project units.** A project can now be converted between metres, millimetres and centimetres. The
building does not move or change size — only the numbers do — and the panel names the unit the
project reads in *now* before offering to change it. That last part is why this could not just be a
button: nothing exposed the current unit, so "convert to millimetres" was a coin flip the user was
being asked to call. The list of units offered comes from the converter itself, so the app cannot
offer one the engine would refuse.

**Project origin.** A model authored against a survey grid can sit kilometres from the file origin,
which costs precision in the viewer and is a common complaint about federated models. Rebasing moves
the geometry near the origin **and pushes the same offset into the georeference**, so the real-world
position of every element is unchanged — the whole point, since moving geometry without fixing the
survey basis is how a building quietly ends up in the wrong place. Nothing is created or destroyed,
so pins, RFIs and clashes keyed by GlobalId all survive. The panel first reports how far out the
model actually is, so the repair is offered against a measurement rather than a hunch.

Both panels **re-measure after the change lands** rather than leaving the figures they opened with on
screen. That matters most for the origin: the point you give it is in the coordinates the model has
*now*, so pressing Rebase a second time against the first reading would move the building twice — and
the georeference would absorb the second offset too, which is the failure that shows up only when
somebody opens the model against the survey.

The existing **Georeferencing** report moved to sit beside them. It is the diagnosis for exactly the
condition rebasing repairs, and this codebase has already paid once for keeping a detector and its
fix on opposite sides of the app — each looks complete on its own.

**Converting a project measured in feet would have shrunk the building to a third of its size.**
Found in review, on this entry's own change, and reproduced before it was fixed. The converter
rescales the geometry and then rewrites the length unit — but it only knows how to rewrite metric
unit declarations, so on a foot-based file (ordinary in a US survey model) the geometry moved and the
declared unit did not. A 10 ft wall came out as 3.048 **feet**, and the report said it had worked.
The engine now refuses such a file before touching anything, saying why, and the panel no longer
offers the control at all — it also stops claiming the file "carries no length unit", which was
simply untrue of it. *The flaw was older than the button; putting a button on it is what would have
let anyone reach it.*

That guard then had to be narrowed twice more, both found in review. It was asking about every length
unit *defined* in the file rather than the one the project is actually measured in — so a metric
project that merely carried an unused foot definition (an import leftover) was refused a conversion it
should have been allowed. The same mistake had an older half: converting a project could rewrite a
stray unit definition used as a conversion factor elsewhere in the file, changing what that factor
meant by a thousandfold while leaving its number alone.

**The check that was supposed to catch an inert button could not see any of these.**
`apps/web/src/viewer/tools/sectionButtonsWired.test.ts` exists for one failure — a tool that is built,
returned, and never put on screen, which typechecks and passes its own unit test and is
indistinguishable from a tool nobody wrote. It claimed to be *"derived from the interfaces rather than
from a list"* one line above a hardcoded list of three modules, and it read the wiring out of one file.
Every button in this entry, plus five that shipped earlier, sat outside it. Both halves are derived now
and the scan covers the whole viewer. **Widening it found nothing broken** — which is the point worth
recording: a gate whose scope happens to contain no defect today looks exactly like a gate that works.

### a queued site photo the server refuses stops holding up the ones behind it

The previous entry fixed this for field capture. The portal's offline **attachment** queue had the
identical defect and it was worse, because these entries hold the actual files. Anything that failed
was re-queued unchanged — a validation refusal and an unreachable server were the same event — so a
photo the server would never accept was resent on every reconnect, sat in front of the good ones on
every pass, and **never left the device**, since nothing in the UI could discard a single queued
upload. The record's notice went on saying "will upload when back online" about a file that would not.

A permanent refusal is now recorded with its reason and skipped from then on. The attachment notice
counts pending and refused separately, says why each refusal happened, and offers a Discard —
previously the only way to reclaim that storage was to clear the site's data. Nothing is discarded
automatically: the person who took the photo decides.

**Where IndexedDB is unavailable it was also dropping the wrong file.** Without it the queue falls
back to memory, and those entries carried no id, so removing one fell back to position — it discarded
whichever entry was *first*. With two queued files where the earlier one fails and the later one
uploads, the file that never reached the server was thrown away and the one already stored was
queued to upload again. Fallback entries now carry ids and every operation addresses them by id.

**A refusal can be overturned.** The rule for "permanent" is a judgement made from a status code,
and review of this change caught it getting one wrong: an expired sign-in (401) was being treated as
final, stranding work that signing in again would have sent. That is fixed — but the more useful
answer is that the judgement is no longer the last word. Each refused entry now offers **Try again**
beside Discard — which sends it, rather than merely un-marking it and waiting for a reconnect that
on an already-online device may never come — so a wrong call costs a tap rather than a photo. A refusal is also only reported once
it has actually been stored, so the count a worker sees matches what is on the device.

**Every HTTP failure this app raises now carries its status.** The previous entry gave one call path
an error with a `status` field; the other fifty threw a plain error whose only record of the status
was the wording of its message, which is why the upload queue could not be fixed at the time. All of
them now carry it, with their messages unchanged so nothing else had to move, and the cloud-model
error — which had been carrying its own status privately — sits under the same type. A test derives
the list of failure sites from the source and fails the build if a new one buries its status again.

### a field capture the server refuses no longer blocks the ones behind it

Offline field capture queued everything and retried everything. Any failure re-queued the item
unchanged, with no distinction between a server that was unreachable and a server that had answered
"no". So a capture the server will never accept — a validation failure, or a worker removed from the
project between capturing and reconnecting — was resent on every reconnect for as long as the app
was installed. The sync badge never cleared, the queue sheet showed the item as merely "pending"
with no reason, and the worker's only recourse was to discard captures one at a time until the badge
went away, guessing which one was poisoned.

A permanent refusal is now recorded on the item with the reason, and that item is not retried again.
It is **not discarded** — the capture stays in the queue, marked, so the person who took it decides
what happens to it. The sheet counts pending and refused separately and says why each refusal
happened; **Sync now** stops being blocked by items that cannot sync.

The rule for "permanent" is deliberately narrow: a 4xx other than 408 and 429, both of which
explicitly invite a retry. Everything else — offline, DNS, 5xx, a proxy dropping the connection —
stays a retry, because **guessing "permanent" wrongly loses a field worker's capture, and guessing
"transient" wrongly only costs another attempt.** The asymmetry sets the default, not a judgement
about which failures are more likely.

The status had to become reachable first. The API client threw `Error("POST /path -> 400")`, which
puts the status somewhere only a string match can read; a classifier keyed on that spelling is the
brittleness the rounding-scan work had just finished removing elsewhere. `HttpError` now carries the
status as a field, extends `Error`, and keeps the identical message — so it is additive and no
existing `catch` had to change.

### six more money figures round the way an invoice rounds — and a 0% retainage stays 0%

The previous entry fixed one line. The check that was supposed to cover the whole tree could not
see it: it scanned three named files and required the word "retain" on the line, and the line it
missed said `ret_pct`. Reading the source structurally instead found five more places computing
money to the cent with the wrong rounding — the GMP budget's overhead, fee and contingency lines,
earned value against the model, and work-in-progress retainage.

**A contract that holds no retainage now reports none.** Work-in-progress treated an explicit 0%
retainage as a missing one and substituted the 5% default, so a project the owner agreed to hold
nothing on showed retainage held — on a $40,000 billing, $2,000 that does not exist. That figure
drives over- and under-billing, which posts to the ledger.

### a subcontractor billing row no longer contradicts itself by a penny

The subcontractor billing summary reported `billed`, `retainage` and `paid` for each subcontract,
and the row's own `paid` disagreed with its own `billed − retainage`. Retainage was computed exactly
and rounded half-up, the way an invoice rounds; `paid` was computed on floats with Python's
`round()`, which rounds half to even. Two conventions in one row: a subcontract billing $2.50 at 5%
retainage held $0.13 and was paid $2.38, which implies $0.12. `paid` is now derived from the same
retainage the row reports, so the two cannot diverge however the rate rounds. Totals are quantized
once more, since summing rounded values drifts on its own.

### every spreadsheet export escapes formulas — and stops mangling negative numbers

The previous entry fixed formula injection in the module CSV export. It fixed two writers; there
were nine. A vendor named `=cmd|'/c calc'!A1` reached the Vendor column of the general-ledger CSV
verbatim, and openpyxl wrote it into every XLSX export — the COBie workbook handed to an owner at
turnover included — as a live formula, not text. Element names out of an uploaded IFC, survey point
descriptions, door and window marks and rebar bar marks were all in the same position. Every
spreadsheet writer in both packages now shares one guard, and a new one is caught by a derived
check rather than by remembering.

**The QuickBooks IIF export can no longer be made to forge a record.** IIF is tab-separated with
newline-terminated records and no quoting, so a tab or newline in a vendor name, memo or cost code
did not corrupt a field — it wrote extra rows into an accounting import. Measured before the fix: a
single hostile vendor name turned one bill into five records. The formula guard deliberately still
does *not* apply here, because QuickBooks does not evaluate a leading `=` and an apostrophe would
corrupt the vendor name on import; the delimiters are the exposure, and they are what is fixed.

**Negative numbers are no longer escaped.** The previous fix guarded every cell, and a negative
number begins with `-` — so `-500.00` in a cost column exported as text, in a sheet somebody sums,
and survey coordinates would have been corrupted outright. Plain numbers now pass through
untouched; an expression that opens with a sign, like `-1+1`, is still escaped.

### a report and a spreadsheet stop naming a firm by its UUID

REF-SORT made a register *order* by what it renders. Two consumers still rendered the stored value,
both outside the web register where the cell renderer does the resolving.

**A grouped report** returned category keys like `730b6f2e-38ec-…` — a chart of opaque ids — and
split one firm in two: rows that linked the company record grouped under its id, rows that typed the
name grouped under blank. Groups now merge on the rule the filter already uses (a typed name exactly
equal to the record's title, case-insensitively, never a substring), so the report and the filter
agree on what "this firm" means. Grouping folds case so variants merge; the label keeps the record's
own casing, so a group reads `Acme Electrical` rather than `acme electrical`.

🔒 **The module CSV export was open to spreadsheet formula injection, and still is not the column the
review named.** Excel and Sheets execute a cell beginning `=`, `+`, `-` or `@`, so a company name is
code in the reader's spreadsheet. A review flagged the new label cell; the exposure measured wider —
`title`, `description` and every text field already carried `=1+1` and `+SUM(A1)` straight into the
file, so this export was injectable before the label existed. Every cell now passes through the guard
`roundtrip_export` already used, lifted into one shared function rather than copied: two spellings of
a security guard is how one of them stops being applied.

**The CSV export** put the uuid in the reference column, so the sheet forwarded to accounting read an
id where a firm name belongs. Each reference column now gains a read-only `__label` companion
carrying the referenced record's title.

**The two fixes are deliberately different shapes.** A group key is display-only, so it is replaced.
A CSV column is not: the importer maps headers back onto fields, so export → edit → re-import is a
supported round-trip, and writing the title into the reference column would read better while
silently turning a linked record into loose text on the way back. So the export *adds* and never
substitutes — and that claim is asserted by running the real importer over the real export, not by
reasoning about the suffix.

Two limits kept deliberately. A reference this project cannot resolve still groups under its stored
id rather than merging into the blank group: an unresolvable link is a data problem, and a report
that hides it behind a tidier chart is worse than an ugly key. And fields that store what they show
are untouched, so grouping a status field does not start folding `Open` into `open`.

⚠️ **A gate shipped two releases ago was passing vacuously, and this change is how it was found.**
The module registry loads on application startup, not on import — so a precondition sweep written at
module scope iterated an empty dictionary, found nothing, and reported the tree clean. The same
mistake here failed loudly with a `KeyError` instead, which is the only reason it surfaced. Both
files now assert the registry is populated *before* anything is computed from it.

### sorting a register by a party column stops answering in UUIDs

PARTY-REFS made *"which deliveries are Acme's"* representable, COL-PAIR made it visible and
PAIR-FILTER made it askable. **Ordering was the half still answering in uuid4s.** Sorting `delivery`
by its supplier reference, ascending, returned Delta, Mid Atlantic, Acme, Zeta — the stored ids in
lexical order, under an ascending arrow. 33 register columns are reference fields.

**The paired direction was worse.** Sorting the *text* half put every linked row first as a NULL —
while COL-PAIR renders company names into those very cells. The column showed a list of firms in no
order at all, beneath a sort indicator, across ~19 more registers.

A sorted column is now ordered by **what it renders**: the referenced record's title when the link
resolves, the stored value verbatim when it does not (a legacy free-text value is text, not a blank,
and it is the only handle anyone has for re-linking the record), and the pair twin when the column's
own half is empty. That is the rule the register's cell renderer already draws, expressed in SQL, so
the order and the screen cannot disagree.

**Blanks now sort last in both directions.** The web register documented that rule for the columns
the server cannot order, and the server disagreed with it, so the same register ordered differently
depending on which column was clicked.

### a joined report stops dropping records whose reference crosses a project

Found while building the sort above, and independent of it. A grouped report over a joined reference
LEFT-joined the target and then filtered `project_id` in a trailing `WHERE`. A base row joined to a
record in **another** project satisfied neither arm of that clause and was deleted from the result:
**a predicate on the nullable side of an outer join is an inner join** — precisely what the code's
own comment said it must not be (*"a base record with no related record still counts"*).

Measured: three deliveries in a register, the joined report counted **two**, with no error and no
truncation flag. Nothing validates a reference *value* on write — the schema check covers the
manifest's shape, not whether an id exists or is local — so a cross-project id is reachable rather
than theoretical. The scope moved into the `ON` clause: the reference simply fails to resolve, and
the row keeps its place under the empty group.

### filtering a register by a firm stops hiding the rows that typed its name

*"Everything open with this subcontractor"* is the question the reference fields were added to make
askable. The filter answered it with a **short list**: rows that linked the company record matched,
rows still carrying the name somebody typed did not. Nothing on screen looked wrong — the count was
simply lower than the truth, and **a short filtered list is indistinguishable from "there are none"**.
`modules_query` already names this failure for sorting (*"the wrong 200 rows"*); the filter had it too.

Filtering a reference field by a record now also matches a text twin **equal to that record's title**,
case-insensitively. Strictly more matches, every one of them right.

**Exact, never a substring** — that is the whole of the judgement. A `contains` match would also catch
`"Acme Electrical Supply"` in a filter for `"Acme Electrical"`: a different firm, on a register people
ask money questions against. A row whose typed name is a *variant* is therefore still missed; that is
a deliberate limit, and the honest fix for it is linking the record.

The pair rule moved from `services/api/test_module_fields.py` to
`services/api/src/aec_api/modules_registry.py`. It now decides which **rows** a query returns rather
than only asserting about the manifests, and a rule that shapes results is production code. The test
imports it instead of restating it; the TypeScript mirror's drift gate reads the new home.

**Two things this change got wrong first, both worth keeping.** The test's first draft used
`f_supplier_company` where the convention is `f.<field>` — so no filter ran, every row came back, and
the headline assertion passed on a list that proved nothing. The *negative* assertions caught it, and
there is now an explicit check that the filter narrows at all: a positive-only filter test cannot tell
"widened correctly" from "never ran". And `services/api/test_unique_read_guard.py` **failed on this
change's own code** — the first version resolved the title with its own `scalar_one_or_none()`, which
that gate correctly reported as an unresolvable unique-demanding read. It fails closed, which is it
working. Folding the lookup into a scalar subquery on the primary key was a better answer than
arguing an exemption, and costs one query rather than two.

### a register column stops going blank when a record links the party instead of typing it

MOD-SWEEP's additive pattern adds a reference **beside** the free text it names rather than
converting it, so existing records keep whatever somebody typed. That is right for the data and it
left the register table showing only one era: a column naming one half is blank for every record
that filled the other.

Measured across all 139 registers: **19 registers list the text half** while its reference exists and
is not a column, and one (`subcontract`) lists the reference while the text is not. Four of the 19
are registers that only just gained a reference — `delivery.supplier`, `asset_register.manufacturer`,
`assumption.owner`, `project_charter.project_manager` — whose help text now tells the user to pick the
linked record, which is exactly the input that would have blanked the column.

**Swapping which half is the column is not the fix** — it only moves which era goes blank. So the
column renders the **pair**: the linked record when the reference is set, the typed name when it is
not. One column, right for records from both sides of the conversion, and no manifest changed.

Read-only by construction. While inline editing is on, each half stays its own editor — a cell that
silently edits a different field than its header names is worse than a blank one.

The resolve set widened with it: a text column can now end up rendering its reference twin, so that
twin's module is fetched too. Without that the cell would find the twin, render it, and `refCell`
would correctly and uselessly report every linked record as unresolvable — the rule would look wired
and leave those 19 registers **worse** than the blank they had.

Held by `apps/web/src/portal/register/fieldPairs.test.ts`, which also reads the suffix list out of
`services/api/test_module_fields.py` and fails if the two disagree. That list now exists in two
languages, and a drift between them is silent: the pair simply stops being detected and the column
goes back to showing one era with nothing to say so.

### sixteen registers can now point at the firm or the person they name

Sixteen registers named a party — a supplier, a consultant, an assignee, a risk owner — across
**nineteen** text fields, while `company` and `contact` sat there as registers with nothing pointing
at them. A party typed two ways is two parties, so *everything open with this subcontractor* and
*what is assigned to this person* could not be asked at all. Three of the sixteen were **islands**:
`due_diligence`, `risk` and `lessons_learned` pointed at nothing whatsoever.

*(Sixteen registers, nineteen fields: `info_requirement` takes three and `asset_register` two. This
entry said "nineteen registers" until review caught it — a change whose whole subject is a count
that drifted from the thing it counts, shipped with exactly that defect in its own release note.
The roadmap entry said "nineteen references", which is right; the two numbers are different
questions and only one of them is 19.)*

Reference fields 178 → 197, islands 44 → 41. Each reference is added **beside** the text it names,
never converting it, so existing records keep whatever somebody typed. No engine changed:
`REVERSE_REFS` is derived from `reference_fields()` at registry load, so a new reference flows into
`related_records`, the "Referenced by" panel and the rollups by itself.

The population was derived by scanning all 139 registers, but the split was made by hand, because it
is the part a script gets silently wrong: `owner` is a person on a risk and an organisation on a
lease. `incident.reported_to` — "OSHA/Owner" — takes `company`, since `company.type` already offers
`Authority` and a client is a company too. `info_requirement` took **three** references, not one:
ISO 19650 names appointing, appointed and lead appointed party, and closing the island with one of
them would have left two thirds of the standard's vocabulary in prose while every count said done.

Two fields are confirmed as leave-alone and pinned so a later sweep cannot "finish the job":
`asset_register.manufacturer_url` is a link to product data, and `drawing_issuance.recipients` is
**plural** — a single reference would keep the first recipient and silently drop the rest.

One is held back deliberately: `company.contact_name`. `contact.company` already exists, so a
company's people already come back as `incoming`, and adding the reverse would create the module
graph's first mutual 2-cycle. It is asserted *absent*, with the reasoning beside the assertion, so
deciding it later means editing a check rather than noticing a gap.

**The gate had a hole in itself.** Its pair rule strips a suffix off the reference and looks for that
stem, so `issue.assignee_name` beside `assignee_contact` matched nothing — one of the nineteen was
silently exempt from every adjacency, fieldset and workflow-trap check in the file, and nothing went
red: the summary counted 18 pairs where 19 existed. The stem resolution is now one function shared by
both rules, since a pair one can see and the other cannot is a trap reported by nothing. A derived
rule joins it: a `_company` suffix must resolve against `company`, `_contact` against `contact`,
`_loc` against `location` — the suffix is the only promise the form makes about which picker opens.

**And the mutation harness lied first.** Each of the nineteen assertions was checked by deleting its
field and confirming that assertion fires — but the first probe neutralised the count floors with an
edit that left an unbalanced paren, so the file did not parse and all nineteen mutations "failed"
with a `SyntaxError`. A harness whose baseline is red reports every mutation as caught. The rerun
asserts the unmutated baseline is green first, and that exposed a second thing: three mutations had
been dying on the count floor rather than on the named assertion, so the earlier ratchet was hiding
whether the specific check worked.

### a file dropzone with no outline, and a chart marker that was never drawn

Found by asking the pinned-rail question the other way round: **what else does this CSS name that
nothing defines?** `apps/web/src/style.css` referenced `var(--border)` at six sites, and TypeScript
referenced five void tokens at thirteen more — none with a fallback, none defined anywhere in the
tree or set through `setProperty`.

**A `var()` that resolves to nothing does not skip the property.** It makes the declaration invalid
at computed-value time, so the property takes its *unset* value — inherited for an inherited
property, initial for everything else. What that costs depends on the **property**, not the token,
and the two halves came out opposite. Measured in Chromium:

| | before | after |
|---|---|---|
| `.att-drop` — the **file dropzone** | `border-style: none`, `width: 0px` | `dashed 1px` |
| `.att-drop.over` — drag-over feedback | accent colour computed, **0px painted** | `dashed 1px` accent |
| `.pf-addopt` — outline *is* the button (`background: transparent`) | `none 0px` | `dashed 1px` |
| `.att-cell`, `.pnav-khint kbd`, `.portal-fieldset-head` | `none 0px` | `solid 1px` |
| QA/repair row separators (×6, inline in `.ts`) | `none 0px` | `solid 1px` |
| profile row `background` | `rgba(0, 0, 0, 0)` — none at all | `#25272b` |
| "Sign out" `color: var(--danger)` | the body colour — **not danger red** | `#d9534f` |
| Pareto baseline `stroke="var(--fg)"` on a `fill="none"` rect | `none` — **invisible** | `#e7e7e7` |

**Six sites were not defects, and saying so mattered.** `color: var(--fg)` is an *inherited*
property, so it landed on the ancestor's colour — which is exactly `--text`, which is what it
wanted. The same token as an SVG `stroke` inherited `none` and erased a chart's baseline marker
entirely. *Same token, opposite severity, decided by the property.* A rename sweep would have been
right by luck and wrong in every word of its description.

Tokens mapped to the ones the palette actually defines: `--border`/`--border-subtle` → `--line`,
`--fg` → `--text`, `--danger` → `--err`, `--bg-elev` → `--panel2`. Only the last is a judgement
call — the palette has no "elevated" tone, and `--panel2` is its second surface. The dropzone's
outline is now `--line` as the design system specifies; if it wants more prominence than the system
border, that is a separate design decision and not this fix's to make.

New gate `apps/web/src/shell/cssVars.ts` + `apps/web/src/shell/cssVars.test.ts`: every `var()`
without a fallback must name a defined token, and every defined token must be referenced. A
reference carrying a fallback is not reported — the token's absence is then not what breaks it, and
seven tokens here exist only in that form. **That is a claim about the gate, not about CSS:** a
fallback does not make a declaration valid. Measured — `border: 1px solid var(--nope, #3a3f47)`
computes `solid 1px`, but `border: 1px solid var(--nope, notacolor)` computes `none 0px`, because
the substituted value is still checked against the property at computed-value time. Whether a
fallback suits its property needs a browser, and this gate does not check it.

**Its scope is CSS *and* TypeScript, and that is the load-bearing part.** A CSS-only sweep is a
predicate deciding what to look at: `--err` is declared in `style.css` and referenced only from
`accountUI.ts`, so a CSS-only "unused token" pass would have called it dead and invited deleting a
token used in eight places — while thirteen of the nineteen void sites live in `.ts` files, where
it could not see them at all. Both directions need both sources.

**The first draft of the scan excluded the palette itself and reported every token undefined.** Its
glob was `apps/web/src/**.css`, which does not match `apps/web/src/style.css` — no intervening
directory — so `--status-crit`, `--mono` and the rest came back "void". The population now comes
from `git ls-files`, and the test asserts the file count and that `style.css` is in it, because a
glob that matches nothing reports a clean tree. **And then the gate failed CI by flagging its own docstring.** The table above writes
`color: var(--fg)` as prose; a scan of raw text counts that as a reference to a token nothing
defines. It had passed locally first, which is the part worth keeping: `git ls-files` lists only
**tracked** files, and when the test first ran `cssVars.ts` was not yet `git add`ed — **so the
population excluded the one file that would have failed it.** A test now asserts the gate is in its
own population, because "it passed locally" meant "it never looked at itself".

**The first fix was a character-level comment stripper, and it was worse than the bug.** It tracked
`'`/`"` strings, and the regex literal `SET_VIA_JS` contains the character class `["']` — so the
lone `'` opened a "string" that ran on to the next apostrophe several lines away, swallowing a real
`//` comment inside it. Over 582 TypeScript files a naive tokenizer mis-classifies in *both*
directions, and the fail-open one — silently eating a live reference — is the one you never see. It
is replaced by a rule with no string tracking at all: a line whose first non-space characters are
`//` or `*` is documentation, every other line is scanned as written. Nothing that ships is written
on such a line.

Four mutations were run against the finished gate: stop ignoring comment lines (this reproduces the
CI failure); ignore *every* line rather than only comments (the fail-open direction); count test
fixtures as real sites; and make `voidVars()` always return clean. Each reds the tests it should.
The earlier round — reverting the stylesheet fix, and narrowing scope back to CSS only, which trips
on `--err` — still holds.

### the pinned rail has been rendering in the bottom-right corner since July

`#pinned-rail` carried `grid-area: pins` from v0.3.764 (2026-07-28) and **no `grid-template-areas`
anywhere in the tree ever defined a `pins` area.** `#app`'s template was `"topbar" "stage"
"statusbar"` in a single column, so the rail was auto-placed into implicit tracks instead of beside
the stage. Measured in Chromium at 1440x900 with the rail populated, before the fix:

| | before | after |
|---|---|---|
| `#pinned-rail` | x=1368 y=774, 72x126 — the bottom-**right** corner | x=0 y=44, 72x824 — a full-height left rail |
| `#stage` | 1368x698 | 1368x824 |
| `#statusbar` | y=742, width 1368 — **detached from the bottom of the window** | y=868, width 1440 |
| `#app` tracks | rows `44 698.156 32 0 125.844`, cols `1368 0 72` | rows `44 824 32`, cols `72 1368` |

The rail's own CSS gives it `width: 72px` and a `border-right`, which is a left rail; it was drawn
on the opposite side, and it took 126px of height away from the model viewport and pushed the status
bar 126px up into the middle of the window.

**It survived six weeks because a first run looks perfect.** The rail is `hidden` until the user has
a favourite or a recent, so the session that shipped it saw nothing wrong — and every session after
it was wrong. There was no console error and nothing to go red: jsdom performs no layout, so a DOM
test would have passed too.

`#app` now defines `"topbar topbar" / "pins stage" / "statusbar statusbar"` over
`auto minmax(0, 1fr)`. `auto` rather than a flat `72px` is the load-bearing choice: the rail is
`display: none` both when nothing is pinned and below 900px, and an auto track holding only a
`display: none` item collapses to zero — so the stage keeps the full width in exactly the cases the
rail is absent. Verified in all four states (desktop/phone x rail-empty/rail-populated); the two
rail-absent states measure **byte-identical before and after**, which is the half that proves the
fix is inert when the rail is not there.

New gate `apps/web/src/shell/gridAreas.ts` + `apps/web/src/shell/gridAreas.test.ts`: every
`grid-area` must name an area some `grid-template-areas` defines, **in both directions** — an area
used but undefined fails, and an area defined but claimed by nothing fails too, which is what would
catch the reverse edit. Population is derived, not listed: 4 `grid-area` declarations, 3 defined
names, and before the fix exactly 1 orphan. It fails closed — a value the parser cannot classify is
reported as UNKNOWN and reds the build rather than being dropped quietly.

The self-test mutates the **live** stylesheet back to its pre-fix shape rather than asserting
against a hand-written fixture, and asserts the mutation actually applied before trusting the
result: a regex that stopped matching would otherwise turn the self-test green by doing nothing.

**Review found three defects in the gate's own parser, and the first was fail-open** — in the check
whose entire purpose is to catch fail-open checks. Each was reproduced against the old code before
being believed:

1. The property name was matched by substring, so the CUSTOM PROPERTY `--grid-template-areas: "pins"`
   **defined** a phantom `pins` area and the orphan went unreported. A declaration that changes
   nothing in a browser could silence the check.
2. Declaration text inside a string was read as a declaration, so `content: "grid-area: ghost;"`
   invented an orphan that is not there.
3. `/*` and `*/` inside strings were treated as real comment delimiters, so one `content: "/*"`
   could blank every declaration after it.

All three are gone: the three regexes are replaced by a single-pass scanner that tracks comment and
string state and only reports a property when the text before the colon is a bare identifier inside
a block — which also keeps `@media (max-width: 900px)` and `a:hover` out. `--grid-template-areas` is
now rejected by exact match rather than by substring.

**The scanner's first draft found nothing at all**, and said so cleanly: its identifier pattern was
written `--?`, which *requires* a leading hyphen, so it matched only custom properties and rejected
`grid-area` itself. Every answer it gave was clean because it had looked at nothing — caught by
running the three reproductions rather than by the suite.

Four mutations were then run against the finished gate: revert the CSS; make `verdict()` always
report no orphans; restore the substring property match; and remove string tracking from the
scanner's main loop. **The fourth initially survived** — all three regressions above put their
string in a declaration *value*, which a different code path handles, so the prelude branch was
never exercised and deleting it looked harmless. It is not: `[title="/*"]` in a selector opens a
comment that never closes and discards the rest of the stylesheet. That case is now a test, and all
four mutations red the tests they should.

What the gate does **not** do is stated in its docstring rather than left to be assumed: it does not
know which grid an element belongs to, so an area defined on some *other* grid would satisfy it.
Closing that needs a DOM. It is a lower bound that cannot raise a false alarm, and it catches the
shape that actually occurred. The out-of-scope axis — named grid *lines* — is empty in this tree,
and a test re-measures that on every run so the scope claim cannot quietly go stale.

### dependabot's Python updates were unmergeable by construction, and nobody had said so

`services/api/requirements.lock` has **19 commits and 0 by dependabot**. The npm lock has **17 of
503**. That gap is not neglect and it is not a policy anyone chose — the lane was closed.

`requirements.in` is compiled into the lock by `pip-compile --generate-hashes`, which dependabot
cannot run. So it bumps the `.in`, `lockfile.yml` recompiles, finds the committed lock stale, and
**fails**. Every pip PR it has ever opened was red before a human looked at it. The workflow already
did the hard part — it compiles in `python:3.12-slim`, the prod base image, so the resolution matches
production — but carried `permissions: contents: read`, so all it could do was publish an artifact for
someone to download and commit by hand. Nobody did that 19 times.

It now commits the recompiled lock back on `dependabot/pip/**` branches. **Scoped there
deliberately:** on a human's branch a stale lock is a mistake worth being told about, and silently
fixing it would hide the `requirements.in` edit that caused it.

**The failure branch is the part that needed care.** Dependabot-triggered runs get a restricted
`GITHUB_TOKEN`, and whether it carries `contents: write` is a repository setting this file cannot
assert. A naive write-back would commit locally, fail to push, leave a clean working tree — and the
staleness gate below it would then **pass**, letting a PR merge carrying a stale lock. That is
strictly worse than the red build it replaces, so a refused push fails the job explicitly and names
the setting to check.

**Two review findings on this step were both real, and one of them made a comment here false.**

*Security.* `contents: write` cannot be scoped below the job, and `actions/checkout` persists the
token into `.git/config` by default — while this very job installs `build-essential` so that
`pip-compile` can **build source distributions** to hash them, which executes `setup.py` / PEP 517
hooks from the dependency being locked. That is third-party code, and raising the permission put it
alongside a write-capable credential. Checkout now sets `persist-credentials: false`, and the token
is attached to the remote inside the push step — *after* the compile is done. So the exposure is
closed by ordering rather than by a two-job split, which would have required reordering the Verify
gate (it must not run before the write-back on a dependabot branch, or it fails on the very
staleness the step exists to fix) — a behaviour change nothing here can test.

*And the workflow's own comment claimed a mechanism that does not exist.* It said the write-back
push "triggers one more run. That run finds the lock current, commits nothing, and stops." **GitHub
raises no events for pushes made with `GITHUB_TOKEN`** — the anti-recursion rule, nothing to do with
this workflow's path filter. The good half is that the write-back cannot loop. The bad half, now
stated in the file instead of contradicted by it: **the commit it pushes carries no CI or security
check runs of its own**, and `ci.yml` has no `workflow_dispatch` trigger, so it cannot even be
dispatched at it. A maintainer must re-trigger checks before merging, and closing that properly
needs a GitHub App or PAT whose pushes do raise events — a repository secret, not a change to this
file. *The claim was plausible, specific, and wrong, and it was load-bearing for how safe the step
looked.*

*This was going to be a new workflow.* The premise-check found the machinery already existed and the
whole task was one permission and one step — the fourth time in this stretch that a plan survived
until somebody read the code it assumed.

### the CHANGELOG had 34 `## Unreleased` headings, so the word meant nothing

Each change had been landing as its own `## Unreleased — title`, a peer of every real version, so the
file read as 34 pending releases. They are now one `## Unreleased` with the titles at `###` beneath
it, in the same order. **No text was edited, added or dropped** — asserted rather than eyeballed: the
bodies are byte-identical after normalising heading markers, 27,508 lines either side.

### the @thatopen/ui bump was closed rather than merged

`scripts/check-fragments-version.mjs` pins a KNOWN_GOOD trio and the bump tripped the coupling guard
**by design** — that guard exists because a green build does not prove the viewer still renders a
model, so moving the pin needs a human with a browser. 3.4.10 → 3.4.11 does not earn that. Closed on
the maintainer's call; dependabot re-proposes the group when a change worth the verification appears.
**Nothing was defective and nothing was worked around** — this is the guard's intended outcome for a
low-value bump, which is worth recording because a closed dependency PR usually is not.

### a test run the way its own docstring says could build a schema in your database

`services/api/src/aec_api/db.py` reads `DATABASE_URL` **once, at import**, and its own first line
documents that variable as how you point this service at production Postgres. 44 tests declared
theirs with `os.environ.setdefault`, which looks like a declaration and is not one: it yields to
whatever the shell is carrying.

Under `run_tests.py` that never showed, because the runner injects `DATABASE_URL` per test. But every
one of those files says in its docstring *"Run: cd services/api && PYTHONPATH=src ./.venv/bin/python
test_x.py"* — and run that way with the variable exported, **`test_view_config.py` created 173 tables
in the ambient database, wrote rows, and exited 0.** Measured, not reasoned about. The passing exit
is the whole problem: nothing announces it, and the tables turn up later as a mystery.

Every test that can build a schema now decides its own database, and
`services/api/test_db_url_isolation.py` holds it there: **27 schema-creating tests, all declaring; 0
inheriting the shell; 645 that create no schema and are not required to.** `loadtest.py`,
`mcp_server.py` and `seed_scale.py` keep `setdefault` deliberately — aiming a load test or the seeder
at a real database is what they are for.

**The population was re-derived four times and was wrong three of them, each by a different
mechanism**, which is the part worth keeping since the fix itself is one line per file:

| derivation | said | wrong because |
|---|---|---|
| grep for `setdefault` | 48 | one had an earlier assignment shadowing it |
| ...minus the 3 tools | 44 to convert | right answer, wrong QUESTION |
| `create_all` with no declaration | +1 file | the risk is schema-creation, not `setdefault` — a grep for one cannot see the other |
| "any `aec_api` import before the assignment" | +3 defects | **none was a defect** |

That last one is the sharpest. `ast.walk` reaches inside function bodies, where an import does not run
until called — and `aec_api.deal_memory` imports the database module only inside a function, so it
builds no engine at import time. The analyser called three safe files defects. *Over-reporting is the
safe direction and it is still wrong: a gate that cries wolf gets edited to be quiet, and the edit is
where the real rule dies.* Reachability is now computed over module-level statements only, with a
self-test for that exact shape.

The gate is keyed on the **risk**, not the syntax the sweep started from: *a test that can create a
schema must decide its own `DATABASE_URL`, by assignment, before anything reaching `aec_api.db` is
imported.* And `run_tests.py`'s cleanup docstring — which credited this property to declarations that
44 files were not making — now says which check actually holds it.

Also: **UX-3 is closed.** All five of its items ship, and the roadmap says so at the top of the line
rather than only in the body, because a five-item line is scanned, not parsed. The lane table had it
open and pointing at the wrong directory; lanes are assigned by directory, so a citation that
resolves is not the same as one that is right.

### the Draft form shows you the thing you are about to place, at its actual size

Type 8.0 where you meant 0.8 and the desk you place is eight metres wide. Nothing said so until it
was in the model. The Draft panel now draws a **scaled section of the element above the fields**,
rebuilt on every keystroke, so the mistake is visible before you click. A W24x76 draws deeper than a
W8x31 (the nominal depth is read out of the section name); a 0.2 m covering draws ten times a 0.02 m
one; a family draws at the width, depth and height its form is carrying.

**The frame does not rescale to fit what you typed, and that is the whole mechanism.** A view that
auto-fitted would draw an 8 m desk and a 0.8 m desk identically — a preview that always looks right,
which is worth nothing, and is the UI form of a check that always passes. So the frame's height in
metres is computed once from the element's own DEFAULTS, and the shape is drawn to true scale inside
it. Ten times the default runs off the top of the frame and the caption says so.

**A shape can also miss the frame downwards, and the "too big" check could not see it.** `extrusion`
is the one element with a base offset, and it is the one value allowed to be negative — 0 is a
legitimate offset, so it bypasses the guard that substitutes a default for a non-positive number.
Type -10 and the rectangle was drawn entirely below the viewBox while the panel reported a fit,
because the upper bound was clamped at 0.01 before the comparison and the clamp hid it. The lower
bound is now measured, and it gets its **own sentence** — "base is below the frame" rather than
"larger than this element usually is", because a base offset of -2 m is not large, it is pointing the
wrong way, and a false explanation from the one control whose job is to tell the truth about what you
typed is worse than no warning at all.

The band is derived from the defaults' bounding box rather than tabulated, so a new **supported**
element — one `previewFor` draws, not every catalog entry — gets a sensible frame with nothing to
remember to update anywhere.

**What has no preview is a list with reasons, not a silence.** The 13 `mep:` terminals bake their
dimensions into the recipe closure and expose no params, so the form has nothing to get wrong; the 19
`content:` items are sized by `place_content` from the server's own catalog. Previewing either would
mean keeping a second copy of those numbers in the browser, and a preview drawn from a second copy
can disagree with what is actually placed.

*The element population was hand-counted as 17 and is 34* — `draftCatalog.ts` builds the `cov:` and
`mep:` entries from generator functions, which a grep for the literal element shape does not find.
`draftPreview.test.ts` derives the population from `DRAFT_ELEMENTS` instead and failed on its first
run naming `cov:ceiling`. The derived test caught a population error in the same session the feature
was written.

Three mutations were run against it: making the preview ignore the typed values (5 checks fail),
letting the frame rescale to fit them (4 fail), and dropping one `NO_PREVIEW` reason (3 fail). The
assertions are about ratio, not appearance — doubling the metres must double the drawn height —
because `expect(preview).toBeTruthy()` would pass against a function that never reads the form.

### two publishes could take the same model version number, and a signed certificate points at one of them

`versions.snapshot()` allocates `version = last.version + 1` after reading the maximum, over an index
on `project_id` alone. Two publishes to one project — two uploads, a retried convert — both read 7
and both insert 8. Nothing refused it.

**The consequence is not that the diff picks arbitrarily.** `versions.review` reads
`(project_id, version).first()` and sets `review_status` on whatever comes back, so approving
"version 8" approves one row and leaves its twin a draft — against a rule whose whole purpose is
*issue drawings only from approved versions*. And `turnover.py` stamps `record_model_version`, a bare
integer, into the `data` of a signed AIA G704 substantial-completion certificate. With two rows
carrying that number, **which snapshot the certificate attests to is decided by `.first()`**.

Fixed with `uq_model_versions_project_version` plus a bounded retry in the allocator.
`auth.get_or_create_by_key` does not fit here and the reason is worth stating: that helper folds a
loser onto a row identified by a key the caller already holds, and this caller cannot know its key
until it has read the maximum. The two publishes are **different snapshots** and both belong in the
history, so the loser recomputes and takes the next number rather than adopting the winner's row.

**The dedupe renumbers and deliberately does not re-sequence.** That signed integer is why:
re-sequencing a project's versions by `created_at` would make the numbering match the chronology, and
would silently change what an already-signed certificate points at. A migration must not move the
target of a signature. So every number stays on the row that has it and only the later members of a
duplicate set move past the maximum, each carrying a note saying where it came from. The honest cost,
stated rather than hidden: a renumbered row's new number sits after versions created later than it,
so for that project numbering no longer matches chronology. `created_at` still does.

This closes the last three of the six ambiguous `.first()` sites, and unlike the first three it *was*
the concurrency defect the axis was written to look for.

**Three of this entry's own checks measured less than they claimed**, and each was found by running a
mutation rather than by reading. The competing insert that was supposed to force a collision fired
before the allocator's read instead of after it, so deleting the retry entirely left the test green.
The fixture index used the wrong shape, so every snapshot in the file was of an empty model and the
delta assertions compared nothing to nothing — surfaced only because one check demanded a specific
number and got `+0/-0`. And the retry, once actually exercised, turned out to reassign the `note`
parameter, pinning the first attempt's `+1/-0` onto a row computed against a different baseline.
*A check that asserts a value catches what a check that asserts "it ran" does not.*

### a BCF re-import duplicated everything, and one snapshot read crossed projects

**Re-importing a `.bcfzip` made a second copy of every topic instead of updating it.**
`bcf_io.import_bcfzip` blind-inserted `Topic(guid=te.get("Guid"))` with no lookup at all, and threw
each `<Comment Guid>` away entirely. So the ordinary weekly loop — export the coordination issues,
open them in a coordination tool, import the updated file back — grew the list instead of moving it
forward, and did it again every week.

The damage did not stay here. Export then wrote two `<Topic>` elements carrying one GUID, which is
not valid BCF, so the duplication left this deployment and became the next tool's problem. That is
the round-trip guarantee in `CLAUDE.md` — *pins/RFIs/punchlist follow the BCF model so they
round-trip with other BIM tools* — failing in the direction that is hardest to notice, because
nothing here ever showed an error.

A topic is now identified by `(project_id, guid)` and a comment by `(topic_id, guid)`. Both are
backed by unique indexes in `b6e1c4d09a37`, because a find-or-create with no constraint under it is
the same defect this week's other three migrations were about: the savepoint has nothing to catch
until the constraint exists.

`comments.guid` is new — a comment's identity in the *file*, separate from our primary key. It is
backfilled `guid := id`, which is exactly what the exporter has been writing as `<Comment Guid>` all
along, so **files exported before this change still match their comments on re-import**. Without the
backfill the fix would only have worked for files exported afterwards.

**The dedupe re-parents rather than deletes**, which departs from the three sibling migrations. An
enum option or an element verification carries nothing; a topic carries comments, viewpoints and
attachments by foreign key, plus audit entries, record comments and drawing markups through a plain
`topic_id` string with no constraint behind it. Deleting a duplicate topic would take a real
conversation with it and leave those three soft references pointing at a row that no longer exists.
So every child moves onto the earliest topic — the id every other record already points at — and only
then is the empty row removed. `services/api/test_bcf_reimport_dedupe.py` seeds that mess and
upgrades through it, because a dedupe runs **once, on a production database, against rows nobody here
has ever seen**, and if it is wrong the evidence is the data it destroyed.

The import route now answers `{"imported": N, "updated": M}`. `imported` keeps its name and now means
*new* topics; the old shape counted every topic in the file as an import while quietly creating a
second copy of each one.

**Separately, a viewpoint snapshot could be fetched from another project.**
`bcf_viewpoint_snapshot` validated the *topic* against the project and then read the viewpoint with
`filter(Viewpoint.guid == vguid)` over the whole table, so a viewer on their own project, passing a
viewpoint GUID belonging to someone else's, got that project's snapshot PNG with a 200. The GUID is
not a secret — a `.bcfzip` carries GUIDs chosen by whoever authored it, and those files move between
firms. Every sibling read in that router already scoped by the topic; this was the lone outlier. Now
scoped by `Viewpoint.topic_id == t.id`.

Found while reading the six ambiguous `.first()` sites the previous entry named rather than exempted,
of which `Viewpoint(guid)` was one. *The ambiguity question — can this return two rows? — and the
authorisation question — can this return someone else's row? — turn out to be the same reading of the
same line.*

### removing a member from a project reported success and did not remove them

`project_members` has carried two SEPARATE non-unique indexes since the schema baseline — one on
`project_id`, one on `user`, nothing spanning the pair — and `rbac.grant` is a read-decide-insert on
exactly that pair. Two concurrent grants for one person (an admin double-clicking "Add member", a
SCIM sync racing a manual add) both read "not a member" and both INSERT.

**`remove_member` deletes `.first()` — one row.** With a duplicate present the route returns 200, the
person disappears from the member list, and they still have the project. `rbac.role_for` reads
`.first()` too, and `require_role` calls it on every protected route, so the effective permission was
whichever row the database happened to return.

Fixed the same way as this morning's three, because at this size the fix is the same: a unique index
(`a3c7d9e4f218`) plus `auth.get_or_create_by_key`. The dedupe keeps the **highest** role rather than
the earliest row, and that differs from the sibling migrations deliberately — these rows are
permissions, and the two failure directions are not symmetric. Keeping the least-privileged row can
demote a project's only admin, which nothing in the app can undo from the inside; keeping the most
privileged can leave someone with more access than intended, which is visible in the member list and
one click to correct. `party_role` and `company` are carried forward off the rows being removed.

**The read-side gate that found it shipped with two fail-OPEN holes of its own, both caught in
review.** `test_unique_read_guard` collected a query's filtered columns with `ast.walk`, which unions
an OR's branches — `where(or_(a == 1, b == 2))` looked like a conjunction on `(a, b)` and could
borrow a unique key it does not satisfy. And it treated any call in the selector as an aggregate, so
`db.query(func.lower(X))` was exempted from the gate entirely. Both are the same mistake: answering a
question about MEANING with a test of SHAPE, in the fail-closed direction's exact opposite. Neither
could have shown up in a report — they produced BACKED and AGGREGATE, which is what a healthy tree
looks like. Fixed by pinning columns only through AND-shaped equality and by naming the aggregate
functions explicitly; fixtures now assert the verdicts, and each was run against the pre-fix
analyser first to confirm it came back safe there.

That fix then had a third hole of the same kind, found by the same review: AND-shaped `==` still
accepted `X.a == X.b`, an equality between two mapped columns, which correlates them rather than
pinning either — so a pair of self-comparisons assembled a whole composite key out of predicates
that restrict nothing. A column now counts only when its comparator contains no mapped attribute.
**A narrowed rule is not a sound rule**, and the second draft of a fail-closed check earns no more
trust than the first.

Two race tests also had their `DATABASE_URL` changed from `setdefault` to an assignment. Under
`run_tests.py` either is safe, but these files document how to run them directly, and `setdefault`
then hands them whatever DSN the shell carries — a developer's dev database, into a test that creates
tables and deletes rows. The assignment form is also the one `run_tests.py`'s sweeper can read.

**`test_seeding_sweep` could not have caught this, and its docstring already said so.** It reports a
conditional branch that inserts a mapped model; `grant` puts the insert at function scope after an
early `return`, which that gate names as its own blind spot. A named limit is still a limit — writing
it down did not stop a live instance from sitting inside it on the authorisation table. It was found
from the read side instead, by measuring the `.first()` population the new read-guard names as its
edge: 35 sites, 11 ambiguous, five of them this one table.

Verified: the duplicate reproduced against the pre-fix schema and revocation shown to fail; the fixed
schema refuses the second row; `grant` run twice updates rather than inserting; a lost race folds into
the winner's row; the migration's dedupe exercised against a seeded dirty database, keeping the admin
row and carrying `party_role` forward off a losing one; `alembic check` reports no drift.

### the reads that demand one row, asked whether anything guarantees it

The other half of this morning's seeding work. That fixed the WRITERS — conditional inserts with
nothing holding the world still. `services/api/test_unique_read_guard.py` walks the READERS:
`scalar_one_or_none()` and `one_or_none()` do not prefer a single row, they **raise** on two, so a
read filtered on columns the schema does not constrain is a 500 that arms itself the first time a
duplicate appears and never disarms. That is exactly how `element_verifications` became permanently
unreadable for an element, and this gate would have found it from the query side without anyone
looking at the inserts.

**No live defect.** 5 unique-demanding reads: 3 backed by a unique constraint, 1 an aggregate that
returns one row by construction, 1 exempt. The exempt one is `cloud_identities.cloud_sub`, read with
`one_or_none()` over an index that is **not** unique. Traced serially and under concurrency: the only
creator runs in the branch where that same query just proved no row holds the sub, and it keys on
`username` — a primary key — through `auth.get_or_create_by_pk`, so no duplicate is reachable. It is
recorded as an exemption rather than fixed with a unique index because making it unique is a product
decision, not a cleanup: it would forbid two local accounts deliberately linked to one cloud identity,
and nothing here establishes that nobody wants that.

The gate **fails closed** — a call site it cannot resolve is reported as UNKNOWN and reds the build,
rather than being skipped, because both of `test_seeding_sweep`'s blind spots were a predicate
deciding what to look at. **Its own first draft repeated that bug one layer up.** The self-test
asserted the analyser still *reported* an unresolvable read, and a mutation routing every unresolvable
read to "safe" passed anyway: reporting a site and classifying it are two different questions, and the
test asked only the first. The verdict is now a separate function so it can be mutated directly. Four
mutations run — dropping the real unique index, deleting the exemption, the fail-open reclassification,
and a newly added unguarded read — all four caught.

Uniqueness is asked of SQLAlchemy's metadata, never of the source text: `UniqueConstraint` and
`Index(..., unique=True)` are both in use deliberately, and a grep for the former would have called
`uq_element_verifications_project_guid` unprotected.

### the palette rows have a shape now, and it is not the shape the roadmap asked for

UX-3's last unshipped item was "thumbnails". Every Draft-palette row now carries a line-art glyph
for its IFC class, so a ~90-row list is scannable by shape rather than only by reading. **That is
part of the item, not the item**, and the roadmap entry says so instead of ticking the word: a
thumbnail renders what you are about to place, so a 30 m wall would look different from a 3 m one
and a W24x76 from a W8x31. A glyph is keyed on the class, so it cannot show either. What remains is a preview built
from the parametric geometry the recipe would author, which is a different job from an icon table.

The gate derives its population from the three catalogs that can put a row in that list — the TS
`DRAFT_ELEMENTS`, `content.py` and `families.py` — rather than listing the classes, so an element
added with an unmapped class reds the build. Every assertion runs through `hasExplicitGlyph` and
never through truthiness, because `draftGlyph()` always returns *something*: a test that cannot tell
the fallback from a real entry would report full coverage over a table with one row in it. Four
mutations were run — a deleted entry, an entry no catalog can reach, two classes drawn identically,
and a new element arriving with an unmapped class.

**Two things turned up that were not the feature.** The row built itself with `innerHTML` around a
server-supplied label and is now built with `createElementNS` + `textContent`. That is a *latent*
hardening and calling it more would be wrong: `/families/catalog` and `/content/catalog` both serve
static catalogs, so nothing attacker-controlled reaches that row today — but `import_types_from_ifc`
copies `IfcTypeProduct.Name` verbatim out of an uploaded IFC, and this palette exists to grow with
server-supplied content. And the first draft rendered the glyph's name as an `<svg><title>`, which
counts toward the enclosing row's `textContent`; every row silently read "wallWall IfcWall". Nothing
about the drawing was wrong, and only an existing test that matched on row text caught it.

**A third thing, found in review and worth more than the icons.** The empty state keyed on
`familiesLoaded` alone — but families and content settle independently, on purpose. So searching for
a content item before `/content/catalog` answered announced *"Nothing matches …"*: a definite claim
the code was not entitled to make, and the same wrong-answer-not-slow-answer shape as the
discipline-chip bug one layer up. Both catalogs are now tracked, and until both settle the panel
reports waiting; the Enter path does the same rather than erroring. A failed fetch counts as settled
— the answer is then final, if incomplete.

**And the search box was answering a question it had not been asked.** It ANDed the query with the
active discipline chip, so typing "column" while Architectural was selected returned *"No elements
for this discipline yet."* — the palette denying that a column exists. That is a wrong answer, not a
slow one, and nothing in the panel hinted that the chip was still filtering. A query now spans every
discipline and each off-chip hit says which one it came from; with the box empty the chip scopes the
list exactly as before, which is asserted so the chips cannot quietly become decoration. Verified by
reinstating the old filter and watching the two behavioural assertions go red.

**Enter in that box now arms the top match**, so filtering 90 rows down to one no longer ends with
reaching for the mouse: type "wal", press Enter, click in the model. It routes through the existing
`armByKey` the keyboard shortcuts already use rather than reimplementing the arming path, and it
reads the list the panel last DREW rather than recomputing one, so the key cannot act on a different
list from the one on screen. A filter matching nothing arms nothing and says so. Three mutations:
removing the handler, firing it on every key, and arming `listed[0]` without the empty guard.

### the gate shipped that morning was blind to a read done through a helper

`test_seeding_sweep` landed a few hours ago reporting **0 unguarded** seeding sites. It was not
looking at all of them. To decide whether a conditional insert was a get-or-create, it required the
model's name to appear in a lookup call **in the same function** — and `modules.add_enum_option`
reads the existing options through a helper, `list_enum_options(db, project_id)`, so the name
`EnumOption` never appears there and the site was skipped without a trace.

Behind it was a third instance of the class the gate exists for. `add_enum_option`'s docstring
promises it *"is idempotent against the JSON options + existing customs"*; `enum_options` carried
three **non-unique** indexes. Two people adding the same custom option at once both read "not
present" and both inserted — and `list_enum_options` **appends**, so the value then appeared twice
in the dropdown and stayed there. Milder than its two siblings, and fixed the same way, because at
this size the fix costs the same either way: a unique index (`e7b3f4a9c218`, de-duplicating first
and keeping the **earliest** row so the dropdown's order does not move) plus
`auth.get_or_create_by_key`.

**The precondition is now gone rather than repaired.** Every mapped model is a candidate and the
only shape detected is the conditional insert, which is syntactic. *"Did this function read the
model first"* is semantic — helpers, relationship access, raw SQL — and an AST answering it will
always answer some cases wrongly, silently, in the direction of reporting less. The cost is four
NEWLY exempt sites that genuinely are not get-or-create (a Topic per clash, per failing CI check),
taking `EXEMPT` from two entries to six. That is the better trade: **an exemption is a sentence someone wrote and can
argue with; the precondition dropped sites with no record that it had.**

The gate now also states what it still cannot see — an insert guarded by an early `return` or by a
`try/except` rather than a branch — because the next blind spot will look exactly like this one did:
a clean report.

### a field engineer could put an element permanently beyond verifying, by tapping twice

Two people marking the same element installed in the same second — or one person on a flaky site
connection whose phone retried — wrote **two rows** for that element. `element_verifications` is
read with `scalar_one_or_none()`, so from that moment on *every* request touching it raised: setting
its status, uploading a photo, the install-coverage rollup. The element was permanently unverifiable
and nothing short of deleting a row by hand brought it back.

The route's own docstring said it *"upserts by (project, guid)"*. The table had three **non-unique**
indexes on those columns. `saved_views` carried the same mismatch — *"Owned by project + module +
user + name"*, nothing enforcing it — where the failure is quieter and arguably nastier: `.first()`
raises nothing, so a lost race silently **forks the saved report in two** and the author edits one
copy while everyone runs the other.

Fixed in both halves, which do not work apart: `UNIQUE` constraints (migration `d5f2a81c6b47`,
de-duplicating first and carrying a photo or note forward from the row it removes) and
`auth.get_or_create_by_key`, which inserts inside a SAVEPOINT so losing the race folds into the
winner's row instead of writing a second one — and leaves the session usable, so the audit entry the
caller staged still commits.

Both are declared as a unique **index**, on the model and in the migration alike, and they have to
match: declaring a `UniqueConstraint` against an index in the database makes `alembic check` report
drift on every run forever. The first version did exactly that and CI's Postgres job caught it —
SQLite does not distinguish the two, so no local check could have. Switching the migration to add a
constraint then failed the other way, because SQLite cannot `ALTER TABLE ADD CONSTRAINT` at all and
the batch copy-and-move rebuild it would need puts `saved_view_seen`'s foreign key into `saved_views`
at risk. An index is the one form that enforces identically on both engines and rebuilds nothing.

### The sweep that missed them was bounded by the fix it had to hand

This is the same defect the 2026-08-25 sign-in-door work fixed, and those four sites were **all**
keyed by a PRIMARY key. That is not a coincidence, it is the selection: `get_or_create_by_pk` was
the only shape available, so the sites it could not express stayed unconverted **and unmentioned**.
`cost_db.import_custom_vintage` had even written down what was missing — *"this wants
`auth.get_or_create_by_pk`'s idiom with a query instead of a primary key"* — and nothing acted on it
for ten days, because a note in a comment is not a check.

**And the primary-key sites were the mild ones.** There the database refuses the loser's INSERT: one
500, self-clearing, because the retry finds the winner's row. Where the key is only an index nothing
refuses anything, so the race does not fail — **it succeeds twice**, and the damage is permanent.
The severity ran opposite to the order they were found in.

`services/api/test_seeding_sweep.py` replaces the prose with a derivation: it walks both service
source trees for read-decide-insert on a mapped model and requires each site to be guarded or carry
a stated reason. Its own first draft found **one** of the four known races and pronounced the tree
clean — the sign-in doors write `u = User(...)` and `db.add(u)` as two statements and it only looked
inside one. So the gate now runs itself against the pre-fix SAML door and requires a hit before it
is allowed to report anything: a completeness verdict from an unvalidated detector is confident and
unfounded.

### wall joins had a route, a client method, and no way for anyone to use it

Walls are authored to their **centrelines**, so an L or T meeting leaves the corner open or the stub
running through the other wall — right as a diagram, wrong as geometry, and it is what a quantity
takeoff and a clash run both read. `GET /model/wall-joins` detected them and the `resolve_wall_joins`
recipe butt-joins them. **Neither was on screen.** `api.wallJoins` existed and sat on the
uncalled-method ratchet in `apps/web/src/api/clientCallers.test.ts` with no caller anywhere in the
app. *A route and a client method are two thirds of a feature, and counting either one reports it as
shipped.*

Both halves now ship as one QA tool — **📐 Wall joins (open corners / stubs)**: scan at a tolerance,
list every L/T join (clicking a row selects both walls by GlobalId), butt-join them all, then
**re-scan to confirm**. The count the user is owed is measured *after* the edit rather than inferred
from the request having succeeded. GUID-stable and idempotent, so pins, RFIs and clashes survive.

### The roadmap's "diagnosis ships, repair does not" list was right about one of four

It was assembled from routes and docstrings. Checked against the **screen**, it is wrong in both
directions:

| recipe | diagnosis on screen | repair on screen | the claim |
|---|---|---|---|
| `purge_orphan_psets` | yes | **yes** | wrong — the repair ships |
| `purge_empty_groups` | yes | **yes** | wrong — the repair ships |
| `resolve_wall_joins` | **no** | no | wrong — the diagnosis is dark too |
| `set_spec_link` | yes | no | correct |

**The two purges were never a gap.** A per-row *Purge* button in "Model cleanup (maintenance)" has
shipped all along. It POSTs `row["recipe"]` — a name the **server** sent, out of `ifcpatch_lib.scan` —
so the string is a literal only inside the engine file `services/api/test_recipe_reach.py` excludes as
"the definition and its dispatch table". *That exclusion is right for a dispatch table and wrong for a
capability advertisement, and both live in that one file.*

The gate now reads `ifcpatch_lib.RECIPES` as a third reach source, **checked against what `scan()`
returns rather than against the dict** — the client dispatches on the response, and asserting the dict
against itself proves nothing. `scan()` iterates that dict instead of naming the recipes twice, so the
advertisement cannot drift from the capability. `UNREACHED` **12 → 9**; the published maturity claim in
`docs/authoring-matrix.md` said 12, and three of them were reachable.

*This is the third shape of one false positive, after comments and docstrings. What repeats is not the
syntax — it is that "reachable" was decided by grepping for the name, and **a dispatch by value has no
name to grep**.*

### And a gap in the engine's own test

`services/api/test_wall_joins.py` exercised the route only on the **already-resolved** model, asserting
`counts == {"L": 0, "T": 0}` — which a route returning a hard-coded empty result passes. *An empty
answer reads identically whether nothing was wrong or nothing was measured*, and the non-empty answer
is the whole reason the tool exists. The positive case is now asserted, and mutation-checked by
stubbing the route to return empty.

### The repair now runs at the tolerance of the list on screen

Found in review, and it is the same defect one layer inside the fix for it. The butt-join re-read the
tolerance input **at the moment it was pressed** rather than using the value the visible list was
measured at: scan at 0.05, see three joins, nudge the input to 0.5, press the button — and the server
resolved at 0.5, trimming walls that were never displayed. *The list is the user's consent, and it is
specific to the number it was measured at.*

The accepted scan's tolerance is now stored with it and used for the repair; editing the input
invalidates the list rather than silently re-scoping what the button will do; and a slow scan whose
answer lands after a newer one has started is discarded instead of overwriting it.
`apps/web/src/viewer/tools/repairPanel.test.ts` drives the panel through the DOM it builds and pins
all three.

**And the first draft of that test proved less than it claimed** — caught in the same review. It
disabled the button, clicked it, and concluded from an empty repair log that the press-time guard had
refused. It had not: *a disabled button's `.click()` does not fire its handler at all*, so the
assertion passed on the affordance alone and would have passed with the guard deleted. The two
properties are now asserted separately — ① editing the tolerance disables the control, ② the handler
itself refuses when forced to run — and the mutation the original could not catch now fails on
*"the handler itself must refuse a list the user never saw: expected [ { tol: 0.5 } ] to deeply
equal []"*. *A test can state the right rule and exercise none of it, which is this entry's own
subject one layer further in.*

### a failed reload threw away the only correct geometry on screen

`deltaCommit.consolidate()` republishes the model, reloads it, and then clears the delta store. Its own
docstring explains the ordering in detail:

> *The deltas are cleared only AFTER the new base has loaded. Clearing first would blink the elements
> off screen, and on a failed publish would leave the user with neither the delta nor the rebuild —
> **the one state in which the deltas are the only correct geometry they have.***

**It guarded the publish and not the reload.** `st !== "done"` returns early, and a thrown request is
caught — but `reloadModel()` returning `false` fell straight through to `store.clear()` and a
`"geometry rebuilt"` success. That produces exactly the end state the paragraph forbids: the base did
not load **and** the deltas are gone. On a failed reload the deltas are now kept and the message says
so.

**What "kept" means, corrected after review.** `reloadModel` disposes every model *before* it loads, so
by the time it returns `false` the delta geometry is gone from the scene whatever this function does.
The guard preserves the **record** — the rail keeps reporting unbuilt edits and *Rebuild* stays
available to retry — not the pixels, and the message now points at that action instead of saying
"deltas kept", which read as a promise the viewport was intact. *The guard was right and its wording
described a stronger outcome than it delivers* — a much milder instance of the same class as the
`"geometry rebuilt"` toast it replaced. Making the disposal itself atomic would recover the geometry
too; that belongs to `loadProjectModel` and is deliberately not in this change.

`commit()` deliberately does the **opposite** on its reconvert path, and the asymmetry is not an
inconsistency: that path republishes and reconverts, so the pending edits are already in the new base
— leaving them in the store would strand the rail on "N edits not yet rebuilt" forever. What the two
share is only the messaging rule: read the boolean, and never claim a rebuild the user cannot see.

**The tests had the same gap, in the same shape.** `deltaCommit.test.ts` covered two of the three
failure modes — publish returns a non-`done` state, publish throws — and not the third, publish
succeeds and the reload fails. Both existing tests pass whether or not the reload result is read,
because neither reaches the reload. *A failure mode with no test is not the same as a failure mode that
cannot happen, and here the missing test and the missing guard were the same absence.* The third case
is now covered, and reverting the guard fails it on the exact symptom (deltas cleared, count 0 where it
must be 1).

**`commit()` forty lines above was already correct** — `const shown = await d.reloadModel()`, and a
notify that says *"— shown"* only when it did. So this is one module disagreeing with itself, which is
why keeping the deltas is a correction rather than a new policy.

### A correction to what this repo said about the class

PR #452's commit message and review thread claimed *"a failed reload is the one outcome a user cannot
detect unaided"*. **That was wrong.** `loadProjectModel` already sets an explicit user-visible status on
three of its four `return false` paths — *"no published model yet"*, *"published model file is empty"*,
*"could not read geometry — file is not a Fragments model"*. The fourth is a `!projectId` guard that
cannot fire from those handlers.

The defect is real but different: **two contradictory signals**, a status line saying the geometry could
not be read beside a success toast saying the edit is done. *I verified that callers discard the boolean
and then inferred that the user learns nothing — a check aimed one layer above where the behaviour
lives, which is the same failure the two entries below are about.* Corrected on the #452 thread, since a
reviewer had recorded a repo learning partly on that claim; the learning's advice stands, the
justification did not.

### the reachability gate counted a docstring as a caller

`test_recipe_reach.py` strips `#`, `//` and `/* */` before deciding whether anything invokes a recipe,
on the stated principle that **"a mention in a comment is not a call"**. That principle is right. Its
implementation covered one of the two ways this tree writes prose: **a Python docstring is a string
literal, not a comment**, so it survived stripping and counted as a caller.

**Six recipes were reported as reachable on prose alone**, and every one was a route *describing what
you could POST* rather than anything invoking it:

| Recipe | Its only "caller" |
|---|---|
| `batch_tag`, `place_type` | `authoring.py` — *"Apply an authoring recipe (set_pset \| batch_tag \| place_type)"*, echoed into the **generated** `schema.d.ts` |
| `purge_orphan_psets`, `purge_empty_groups` | `authoring_docs.py` — a **dry-run** report whose docstring says *"Run a recipe via `POST /edit`"* |
| `resolve_wall_joins` | `analysis.py` — *"Resolution is the `resolve_wall_joins` edit recipe"* |
| `set_spec_link` | `authoring_analysis.py` — *"links with the `set_spec_link` recipe"* |

`UNREACHED` goes **6 → 12**. Nothing was un-wired; the count was wrong.

**The gate that named this class committed it.** DARK-RECIPES was written because a naive reachability
check counts its own documentation as usage — and then under-counted by six for exactly that reason,
one layer down. *Stating the correct rule is not the same as implementing its full extent, and nobody
asked whether "comment" and "prose" were the same set.* The `authoring_docs.py` case is the sharpest:
a route that reports what a cleanup **would** remove, naming the recipe that applies it, and that
naming was the only thing making the recipe look reachable. **A dry run is the opposite of a caller.**

Docstrings are now blanked with `ast` rather than a regex — a triple-quoted string is not a regular
language, and this file's whole subject is checks that look right and measure the wrong thing. An
unparseable file is returned unchanged, because under-stripping leaves a recipe looking *reachable*,
which is the safe direction for a check that asserts a gap.

**`apps/web/src/api/schema.d.ts` joins `CATALOGS`.** It is generated from the OpenAPI schema, so its
`@description` lines are the route docstrings a second time — counting it is the
registry-read-back-to-itself false positive DARK-RECIPES already fixed once, in a second location.

**Two mutations, in opposite directions, because one alone proves half of it.** Adding an `UNREACHED`
recipe's name to a route docstring must NOT make it reachable (it does not); adding the same name as
real code MUST (it does, and the recipe drops off the list). *A stripper that blanked too much would
pass the first check and quietly report the whole registry as dark.*

**Four of the six are a product gap of the shape this sprint keeps finding: the diagnosis ships and
the repair does not.** All four, because the first draft said "four" and named three:

| Recipe | The diagnosis that ships without it |
|---|---|
| `purge_orphan_psets`, `purge_empty_groups` | `GET /model/maintenance` reports how many entities each cleanup **would** remove, and offers no way to remove them |
| `resolve_wall_joins` | `analysis.py` detects L/T wall joins and names a resolution nothing can invoke |
| `set_spec_link` | `GET /spec-links` rolls up linked spec sections **plus the unlinked count**, and says *"Stamp links with the `set_spec_link` recipe"* |

Recorded, not wired — where those controls belong is a product decision.

*A reviewer found the missing fourth. `apps/web/src/api/mep.ts` carries a paragraph about precisely
this failure — "count the members you looked at, then phrase the result as the whole population … the
fix is to DERIVE THE COMPLEMENT, not to be more careful" — and it recurred here, in the entry about a
gate that miscounted. **Stating a cardinal and then enumerating is the tell**: the number and the list
are two separate claims, and only the list had been checked.*

### you could put a window in a wall but not a skylight in a roof

`add_roof_window` cuts a full-depth `IfcOpeningElement` through a host `IfcRoof` and fills it with an
`IfcWindow` of PredefinedType `SKYLIGHT`. It has worked since the R17 DORMER slice, it is covered by
`services/api/test_roof_window.py` down to the void/fill relations and GUID stability across a
re-open — and no user could invoke it. The viewer has had *"Add door to selected wall"* and *"Add
window to selected wall"* the whole time.

**Two independent descriptions each said a shipped tool had a missing twin, and neither was a check.**
The coverage matrix entry read *"the roof counterpart of the wired `add_door`/`add_window`"*; the
engine function's own docstring says *"the flat-roof counterpart of the wall-hosted `add_opening`"*.
Prose noticing an asymmetry is not the same as anything failing because of it.

It is now **☀ Skylight in selected roof** on the envelope section, beside the curtain wall — select
the roof, click where it goes, give width × length. `UNREACHED` goes 7 → 6.

**One behavioural difference had to be handled rather than copied.** `add_door` and `add_window`
centre themselves on the host when no position is given; `add_roof_window` indexes `p["position"]`
with no default, so the wall tools' "click optional" pattern would have produced a server error on a
button press instead of a skylight. The tool requires the point and says what to do about it.

**It went into `envelopeSection.ts`, not `app.ts`.** `services/api/test_file_sizes.py` pins
`apps/web/src/viewer/app.ts` at 2,508 lines and a decomposition ratchet only ratchets one way, so a
new tool there would have been paid for by unwinding an extraction. `app.ts` changes by two
identifiers on two existing lines and stays at exactly 2,508.

**A new gate came out of the wiring, and it generalises past this change.**
`apps/web/src/viewer/tools/sectionButtonsWired.test.ts` asserts that every member of every `*Buttons`
interface a section module exports is both destructured **and passed to an `append`** in `app.ts`.
`envelopeSection.ts`'s own comment says its interface is *"named so re-ordering cannot silently
re-map them"* — that guards the order, and nothing guarded the last step. **A button that is built,
returned, destructured and never appended is invisible with every typecheck green**, which
`envelopeSection.ts`'s docstring records the annotation group shipping once already: *"the same
silent-inert failure `qaSection.ts` shipped"*. `tsc` is satisfied by the destructure and a unit test
is satisfied by calling the handler; only the DOM tree knows. Derived from the interfaces rather than
a list — the failure mode is somebody adding a button and forgetting the second half — and it carries
a control asserting the derivation still finds all three interfaces, because a regex that stops
matching passes every assertion vacuously.

### MEP runs could only be joined two elements at a time, and a system's discipline could never be corrected

Two of the ten recipes the entry below named as reachable from nothing are real capabilities, and both
are now on the MEP systems panel.

**Auto-connect.** `auto_connect_mep` welds every unconnected MEP pair whose connection points coincide
within a tolerance, in one pass — nearest pairs first, each element joining at most as many pairs as it
has free ports, so a second run changes nothing. Until now the only way to connect anything was
`connectMep`: pick one element, pick another, connect. That is fine for a joint and hopeless for a
model, and the panel it sits on has been reporting *"**N** floating element(s)"* the whole time with no
way to act on the number. The new button sits beside that count and reports what it welded — including
`0`, which is a real answer (everything already joined, or nothing within tolerance) and is worded as
one rather than as a bare "done".

**Retype a system.** `set_system_predefined` stamps a named `IfcDistributionSystem`'s discipline.
Authoring already sets it — but only on the system's **first** assignment, and `_assign_to_system`'s own
docstring says *"first author wins; retag via `set_system_predefined`"*. That retag path existed in the
engine and in no product surface, so a system that arrived untyped from an import, or was created before
its discipline was decided, stayed untyped permanently — while the panel displayed the discipline, the
by-discipline rollup counted it, and the fire-protection checks keyed off it. Each system row now
carries a retype action.

**The third was never a gap, and that is the finding.** `add_sprinkler` is not missing a caller for want
of wiring: `add_fire_equipment(kind="sprinkler")` resolves through the same `add_mep_terminal` to the
same `IfcFireSuppressionTerminal`/`SPRINKLER` at the same size on the same *Fire Protection* system with
`discipline="fire"`, and has been on the viewer's 🧯 button since MEP-FP. Wiring it would have added a
second control authoring a byte-identical element.

*A reachability sweep answers "does anything call this?", which is one question short of "can a user do
this?" — the same shape of gap the entry below was written to close, one layer further in.* So
`SUPERSEDED` now sits beside `UNREACHED` in `authoring_matrix.py`, the matrix carries a fourth `reach`
value, and the published table and the in-app coverage panel report the two classes separately: a
duplicate counted among the gaps understates coverage and invites work that would ship a redundant
control. `UNREACHED` goes 10 → 7.

**The supersession is asserted against what the recipes author, not against how they read.**
`test_recipe_reach.py` runs both on a fixture model and compares (IFC class, PredefinedType, system
name, system PredefinedType) — every attribute that distinguishes one MEP terminal from another; without
the system and discipline it would pass on two elements landing on different systems, which is most of
what these recipes are for. Change `_FIRE_EQUIPMENT["sprinkler"]` and the gate names the divergence and
says the recipe is a real capability again. The `UNREACHED`/`SUPERSEDED` split is checked for
disjointness and for jointly covering the derived uncalled set, so neither can quietly absorb the other.

**A gate had to be narrowed to say the thing it meant.** `docsPublished.test.ts` rejects any public doc
whose opening contains "superseded" — a proxy for *"this document declares itself a working note"*. The
generated matrix now labels a set of **recipes** superseded, which is a claim about them and not about
the file, and the same latent false positive was already sitting in `docs/internal/security-roadmap.md`
("this one is **not** a superseded snapshot" — a negation read as a confession), unfired only because it
is internal. The rule now ignores lines naming a backticked code identifier: a status banner announces
the document's own condition and cites nothing else. That is a heuristic and is labelled as one — so the
narrowing carries a **positive control** that re-runs the predicate over the archived notes the
un-narrowed rule catches and fails if any is no longer recognised. *An empty result means "nothing
leaked" and "the predicate stopped working" equally, and a narrowing is exactly when the second becomes
likely.* (Written first over the whole archive, which reported 6 missed — all 6 of which had never
matched: that assertion was testing the archive's filing, not the predicate.)

### the coverage matrix counted ten capabilities no user could invoke

`edit.RECIPES` holds **96** authoring recipes, and `authoring_matrix.py` publishes them as the
authoring-coverage matrix. Its docstring calls that *"an honest, single-source answer to 'what can
this tool actually author?' … derived live from the registry (never hand-maintained, so it can't
drift). Users read it to judge maturity; contributors read it to pick work."*

**Being derived from the engine is not the same as being true about the product.** The published
output said every recipe was *"dispatchable from the CAD command line, the AI command bar, the node
canvas, or the tool panels"*. The CAD line and the AI planner both dispatch from
`nlauthor.RECIPE_SPECS` — a **curated** subset naming **12** of the 96 — and **10 recipes have no
caller on any surface at all**: not the web client, not a router, not MCP, not the planner. All ten
are implemented and tested. The matrix could not drift from the engine and was overcounting the
product by ten.

**The committed doc was separately stale.** `docs/authoring-matrix.md` opens *"Generated from
`edit.RECIPES` … do not hand-edit; re-run the generator after adding a recipe"* — and said **91
recipes**, listing 91 rows, against a registry of 96. Nothing checked it. *"Generated" is a claim
about a process, and a process nobody verifies is a wish.*

**Three false-positive classes had to be eliminated, and each made the number look better than it
was.** The first pass reported 18 candidates and then cleared all 18 — because `authoring_matrix.py`
names every recipe, so the check was reading the registry back to itself; **catalogs are
registration, not reachability**. Excluding catalogs gave 7. Then a mutation that swapped a recipe
out of its catalog entry *failed to fail*, because the entry's own explanatory comment still named
it: **a mention in a comment is not a call**. Stripping comments took the true figure to **10** —
larger than either earlier answer. `apps/web/src/viewer/tools/accessorNotCollapsed.test.ts` already
states that rule; this is its third instance.

Three of the ten were already known. SCALE-SEAM (93) recorded `add_sprinkler`, `auto_connect_mep`
and `set_system_predefined` in a doc comment in `apps/web/src/api/mep.ts`: *"referenced NOWHERE in
`apps/web/src`. Backend recipes with no web exposure at all. Recorded, not fixed."* That note was
correct and had no way to stay correct. It is now a check.

**One is wired rather than listed.** `extrude_profile` — *"E3 — sketch-to-BIM … the massing move of
sketching a shape and pulling it up"* — is the namesake gesture of this product and needed no new UI:
a polygon plus a height is what the draft panel already collects. It joins `DRAFT_ELEMENTS` as a
poly-point element, which makes it click- **and** drag-placeable in the same edit, for the reason the
entry below gives. The other ten stay listed deliberately: several are plausibly internal, and
inventing ten buttons would be worse than reporting ten honest states.

`services/api/test_recipe_reach.py` derives the unreachable set from the tree and fails when
`authoring_matrix.UNREACHED` disagrees, so a recipe added without a caller is visible instead of
silently inflating a maturity claim; it also pins the two false sentences verbatim as negatives.
`services/api/test_authoring_matrix.py` now byte-compares the committed doc against the generator.
Mutation-checked: unwiring `extrude_profile` puts it straight back on the derived list, restoring the
old sentence fails by name, and a one-number edit to the doc fails the comparison.

### a tree, a crane and a desk could not be placed where you were pointing

**And the entry below contains a claim that was wrong, corrected here.** It said thumbnails and
drag-to-place were "genuinely unshipped". Drag-to-place **ships** — RAIL-DRAG makes every Draw-rail
row `draggable` (`apps/web/src/viewer/draft/draftPanel.ts`), `apps/web/src/viewer/railDrag.ts`
handles the protected-mode payload rule, and `apps/web/src/viewer/app.ts` carries the
`dragover`/`drop` pair that arms the dropped key and places it where it landed. Thumbnails remain
genuinely unshipped.

*The error is worth more than the correction.* The premise-check looked at **the library palette**,
found a modal with a coordinate prompt, and concluded about **the app**. The library cannot be
dragged from — `.result-overlay` is `position: fixed; inset: 0` with a scrim, so there is no drop
target to reach — but the **Draw rail** could be dragged from all along. That is the same "checked
the surface whose name matched the noun" mistake `docs/roadmap.md`'s own ⑥ note records having made,
one entry earlier, in the paragraph written to stop it happening again.

**What the corrected measurement found is a real gap, and it is closed here.** The 19 CONTENT-1 items
— FF&E, Landscape, Site Logistics — were absent from the draft catalog entirely. Every built-in
element and every family has been click- **and** drag-placeable from the Draw rail since RAIL-DRAG;
content appeared only in the Library modal, whose sole placement affordance is a prompt asking for
*"Location E, N (metres)"*. They were the only placeable things in the product reachable by neither
affordance.

`contentToDraftElement` mirrors `familyToDraftElement`: a 1-point `place_content` element, keyed
`content:<key>`, bucketed onto the discipline chip that lists it (FF&E → Architectural, Landscape
and Site Logistics → Site). **One entry closes both affordances at once** rather than adding a second
placement path, because `allElements()` feeds the rows, the search, the discipline chips *and*
`armByKey` — which is the function the viewport's `drop` handler calls. Content therefore also
inherits what the Library prompt never had: `validatePlacement` refusing an off-model point by name
while keeping the tool armed, the amber optimistic ghost, the incremental preview, point undo/redo,
snapping, Esc-to-cancel — and the active-level injection that landed in the entry below.

**No parameter form, asserted rather than assumed.** `place_content` takes `{category, point}` and
sizes the item from its own catalog entry, so unlike a family there are no dims to override; a form
here would render inputs the recipe discards. And `build()` sends the catalog **key** as `category`
— the catalog calls that string `key` and the recipe calls it `category`, and sending the display
label instead 400s with *"unknown content category"*, so the exact payload is pinned by test.

Mutation-checked: loading content but leaving it out of `allElements()` — the registered-but-unreachable
shape — fails three tests including both the arm and drag paths; sending the label instead of the key
fails two; and dropping the unknown-bucket fallback fails the test that exists because an item mapped
to no discipline would vanish from every chip and read as a catalog that shrank.

**A row label names its bucket — "Tree (Landscape)", "Hoist (Site Logistics)" — and that is not
decoration.** Measured before shipping: **8 of the 19 content keys already exist as families** (bed,
chair, desk, planter, shrub, sofa, table, tree), and the row's meta badge strips both `Ifc` and
`Type`, so a family's `IfcFurnitureType` and a content item's `IfcFurniture` both render as
"Furniture". Without the bucket the Draw list would show two rows reading exactly **Desk** that
author different recipes — one a sized family type, one a phased site-content item. The suffix goes
on all nineteen rather than only the colliding eight, because a label whose shape depends on what
else happens to be in the catalog changes under the user the day a family is added.

**An existing gate caught a real defect in this change**: `docStranded.test.ts` failed because the
new flattener had been inserted *between* `contentToDraftElement`'s doc comment and its signature,
leaving that comment documenting the wrong function. That is precisely the residue DOC-STRAND exists
to find, found on its author rather than months later.

### everything placed from the library landed on the ground floor

**Found while premise-checking UX-3's five-item line, and worse than anything on it.**
`edit_core._first_storey(model, None)` returns the **lowest** storey by elevation, and
`edit.place_type` assigns the occurrence to that storey and, when a position is given, sets its Z to
that storey's elevation. So a placement that omits `storey` does not land somewhere neutral — it
lands on the ground floor.
Measured on a three-storey model: `('Level 3', (7, 5, 8.0))` with the storey, `('Level 1', (5, 5,
0.0))` without it.

**Two of the three authoring paths had always handled this.** Drawing in 3D injects the level —
`finishDraft()` in `apps/web/src/viewer/app.ts`: *"author onto the active level"*. The AI planner
injects it server-side, in `services/api/src/aec_api/nl_ai.py` `_fill_context`, for the LLM and
keyword baselines alike. **The library palette sent none**, so a column placed while working on
Level 7 arrived on Level 1 — as did every content item, every imported mesh, and every family from
"⊕ Place selected family".

**The capability was present at every layer beneath the caller.** `POST …/families/place` has always
accepted a `storey`; the `place_content` recipe has always read `p.get("storey")`; `importContent`'s
options type already *declared* a `storey` that nothing ever passed. Two client methods wrapped one
recipe and disagreed — `addFamily` carried the level and `placeFamily` dropped it. Four call sites,
closed by threading an `activeStorey` accessor through the same seam `lastPoint` already crosses, and
read **at click time**: the user changes level with the palette open, and a value captured at
panel-build time would place onto whichever level was current when the ribbon was last rebuilt.

**Why nothing caught it.** `services/api/test_content.py` builds its fixture with
`generate_blank_ifc(..., storeys=1)` and always passes a storey explicitly. On a one-storey model the
lowest storey and the correct one are the **same entity**, so the defect was invisible by
construction of the fixture rather than by any gap in its assertions. *A fixture with one of
something cannot test which one was chosen.* `services/api/test_level_placement.py` builds three, and
asserts a **middle** storey separately, so "found Level 2" cannot be confused with "ran off the end
of the list" — and that an unknown level name degrades rather than raises, because the UI sends a
name and levels are renameable.

**The caller half is `apps/web/src/viewer/tools/levelPlacement.test.ts`**, and it derives its
population from the client's own signatures rather than a hand list, so a placement method added
tomorrow is covered the day it is written. It counts **arguments**, not the word "storey": a correct
call that passes the level through a lambda parameter contains no such word, and a wrong one may
mention it in a comment. **Its first draft passed a mutation it should have failed** — `importContent`
carries the storey *inside* an options object, and matching "storey" anywhere in a parameter derived
it as positional, after which every call satisfied the arity check. Anchoring on the parameter's own
name fixed it. A green run would never have shown that; the mutation did.

Also recorded in `docs/roadmap.md`: two of UX-3's five items already ship (pick-host→auto-build,
appendable IFC libraries), thumbnails and drag-to-place do not, and the door/window path's missing
storey is a **clean negative** — `add_opening` declares a `storey` it never reads, because an opening
takes its position from the host wall.

### the permitting chain could not name the authority it was applying to

**The entry above closed half of one sentence.** Its roadmap paragraph said a transmittal's recipient
*"cannot be the agency an `entitlement` names, since that field is free text too"* — and then gave the
transmittal its `company` reference and left the agency exactly as it found it, which is the half the
entitlement workflow the item is named after actually needs.

**Four registers named one concept in prose**: `entitlement.agency`, `permit.authority`,
`review_cycle.agency` and `inspection.agency`. `company.type` has offered an **`Authority`** option the
whole time, so the directory was already modelling the concept and nothing pointed at it — the same
shape as `to_company`, one layer earlier in the chain.

The cost is not cosmetic. An authority typed three ways is three authorities, so *whose court did it
sit in* — the question `approval_cycles.py` exists to answer — could be answered for a single round and
never for a **jurisdiction**. And `permit` and `entitlement` were **islands**: the two ends of the
approval process could not point at anything at all, which is most of what separates a register from a
spreadsheet.

**Five references close it.** Four `*_company` → `company`, plus `review_cycle.reviewer_contact` →
`contact`, the person half, which copies the `inspection.inspector`/`inspector_contact` pairing already
used for the person on the other side of the same counter. Each sits **beside** its text field as the
MOD-SWEEP additive pattern requires rather than converting it, so existing records keep the name
somebody typed. Reference fields **173 → 178**, islands **46 → 44**, both ratchets tightened. No engine
changed: `REVERSE_REFS` is derived from `reference_fields()` at registry load, so the links flow into
`related_records`, the Referenced by panel and the rollups by themselves.

**A pinned assertion turned out to pin a fact rather than a rule.** `services/api/test_modules.py`
asserted `most_referenced[0] == "cost_code"`; four `company` references made it `company` (25 vs 23),
which is the module graph telling the truth, not a regression. The identity pin is replaced by what it
stood for, and the replacement cannot be invalidated by adding a reference again: the ranking is really
ordered, every entry's `in_degree` agrees with the edge list it was computed from, and cost and company
— what it costs and who it is with — are both asserted to rank in the top three.

**Two gates, both mutation-checked against `review_cycle`.** `services/api/test_module_fields.py`
names the four registers and asserts each can point at a company; `services/api/test_modules.py` drives
a real approval chain through the API and asserts all four gather on one authority record via
`…/related`, because a field that exists still proves nothing about whether the chain resolves. The
mutation target is deliberate: `review_cycle` keeps its other references, so the islands ceiling cannot
fire first and shadow the named gate — which is exactly how the previous entry's first check passed for
the wrong reason.

The remaining **22** party-named text fields are recorded in `docs/roadmap.md` as a derived population
with the company-vs-contact split written out, because that split is the part a script cannot do:
`owner` is a person on a `risk` and an organisation on a lease.

**A workflow gate can now be met by EITHER half of an additive pair — and the change above needed it.**
Review caught that `entitlement.submit` declares `requires: ["agency"]`, so the moment
`agency_company` arrived carrying help text telling the user to pick a company **instead of** typing
the agency name, a linked-only entitlement could never be submitted. *The change that added the
control created the trap.*

Sweeping all 139 modules found a **second instance already on main**, unrelated to this work:
`compliance_evidence.sign_off` requires `responsible`, which has had `responsible_contact` beside it.
So this is the additive pattern's general collision with the workflow gate rather than one bad
manifest — MOD-SWEEP's whole premise is that the reference arrives beside the text and the text is
retired later, and a gate naming only the text half blocks the migration it exists to enable.

A `requires` entry may now name alternatives as `"agency|agency_company"`, satisfied when **any** of
them is filled. The gate is loosened, not removed: a record with neither is still refused, and the
typed text alone still passes, which every pre-existing record depends on. The refusal message reads
*"requires: Agency / Jurisdiction or Agency / Jurisdiction (linked)"*.

**The rule lives in two languages, and that is the hazard.** The server enforces it in
`services/api/src/aec_api/modules.py`; the register disables the button in
`apps/web/src/portal/register/register.ts`. If only one had learned about `|`, the UI would grey out
a transition the server accepts — the same defect in mirror. The UI half is extracted to
`apps/web/src/portal/register/requiresGate.ts` and tested, and its test reaches across to assert the
**server** splits on `|` too, so the two cannot drift apart silently. `module_schema.py` validates
every alternative names a real field, because a typo in a gate makes a transition quietly unreachable.

The class rule is **derived, not a list of the two known cases**: `test_module_fields.py` section 7
walks every transition in all 139 modules and fails if a `requires` entry names the text half of an
additive pair without offering its reference. A pair added next year is covered the day it is added.

### a transmittal could not name its recipient, and could not carry a drawing at all

**R22-ENTITLEMENT's remaining item was the outbound package, and the blocker the entry named was the
wrong one.** It said assembling a package to send was impossible because `transmittal.items` is a
textarea. Re-measured before building: `submittal` has carried a `transmittal` **reference** all
along, so submittals resolved into a package the whole time — which is precisely what the same
entry's ④ note had already verified against `…/related`. *The entry contradicted itself in the
paragraph written to stop it contradicting itself.*

`items` was never the blocker. It was a second, unresolvable copy of a fact the reference already
owned, and it is now labelled as the note it is: **the contents are the records whose own Transmittal
field names this one**, because those resolve, appear under Referenced by, and can be counted.

**What was actually missing, measured across all 139 registers.** A transmittal carries drawings,
sets and documents at least as often as submittals, and **none of those three could name one**.
`document` and `drawing_set` had no reference field of *any* kind — islands that could not take part
in a chain at all. And `to_company` was plain text while `company` is a register, so a transmittal
could not name the party it was addressed to.

Four references close it: `drawing.transmittal`, `drawing_set.transmittal`, `document.transmittal`
and `transmittal.to_company_ref`. Reference fields went 169 → **173**, islands 49 → **46**.

**No engine changed, and that is the part worth knowing.** `REVERSE_REFS` is derived from
`reference_fields()` at registry load, so a new reference flows into `related_records`, the Referenced
by panel and the rollups by itself. The old paragraph's one correct instinct was that this is a schema
question rather than a workflow one.

**`to_company_ref` sits BESIDE the text, not instead of it.** The MOD-SWEEP established that pattern
for 74 fields naming a register — add the reference, backfill, retire the text later — and
`test_module_fields.py` ratchets it: the pair must be adjacent and share a fieldset. Converting in
place would have been the obvious move and the wrong one; existing transmittals keep the name
somebody typed.

**Two gates, and they catch different things.** `test_module_fields.py` names the four registers a
package carries, with a reason each, and asserts every one can point at a transmittal — the set is
named rather than derived because "what a transmittal carries" is a judgement about the business.
`test_modules.py` then asserts a real transmittal resolves all four kinds *and* its company
recipient, because a field that exists proves nothing about whether a package resolves.
Mutation-checked: removing `drawing.transmittal` fails the schema gate by name and the behavioural one
with the three kinds it did resolve; removing `document`'s or the recipient link trips the island
ceiling first, which is why the named checks were verified against a module that keeps its other
references.

*A test bug worth recording: the first draft created the submittal with a `subject` field it does not
have, the POST 4xx'd, and the assertion reported a missing submittal — which reads exactly like the
product defect it was not.* The check now asserts the POST succeeded before asserting what it means.

⚠️ **`drawing_issuance` overlaps this and was deliberately left alone.** It models the same event —
free-text `recipients`, a purpose, a sheet count — and is still an island. Whether it should link to
`transmittal`, be fed by it, or be retired is a modelling decision, not a gap to close in passing.

### the scheduled package now reaches the people it was assembled for

**R24-REPORTS-BY-MOMENT's last remainder, in its own words: *"Delivery (email on a date) is still
open; this is the assemble half."*** A routine assembled the owner's monthly package and left it in
the job tray. The reason to schedule it is that nobody has to remember it, so that was most of a
feature. A routine now carries `deliver_to` and a finished scheduled run mails its artifact.

**The blocker was one layer below the prose again.** `POST …/jobs/{id}/deliver` and `mailer.py` both
shipped — but **every line of the delivery lived inside the route function**: recipient
normalisation, the 25-recipient and 15 MB caps, the size-before-read, the message build, the
per-recipient status map, the audit. A worker has no request and no `Depends`, and an
`HTTPException` raised from a background thread turns a delivery problem into a 500 nobody sees. The
reusable half is now `artifact_delivery.py`; the route keeps only what is about HTTP — the "is this
artifact ready" refusals, which are answers to a question only an outside caller asks. Refusals are
raised as `DeliveryRefused` carrying the status the route already used, so `test_artifact_deliver.py`
— which drives the real route — is what proves the extraction changed nothing.

**Three rules.**

* **Delivery never changes a job's state.** The artifact was produced; that is what the job was for.
  A refused address or an SMTP outage is recorded under `result["delivery"]` and the job stays
  `done`. Marking it `error` would make the next sweep treat a package that exists as one that
  failed, and re-assembling a report because an email bounced is the wrong repair.
* **Only jobs carrying a `routine_id` deliver.** That keeps `deliver_to` from becoming an
  undocumented side-channel on `POST /projects/{pid}/jobs`, whose `params` are caller-supplied. An
  editor who synthesises both gains nothing they lack — the deliver route is open to the same role
  and the audit records the same actor either way.
* **It runs inside the heartbeat, before the state flips.** `_Heartbeat` only refreshes rows still
  `running`, so delivering after `state = "done"` would let the claim go stale during a conversation
  that can take minutes, and the reaper would re-queue a job that had already sent.

**The guarantee is at-least-once, stated rather than discovered.** A crash between the last
`send_email` and the commit re-mails on recovery. Exactly-once needs a sent-marker committed before
the send, which trades a duplicate package for a silently un-sent one — the worse failure for a
deliverable somebody is waiting on.

**The default is off.** An empty `deliver_to` is no delivery, not an empty send, and it is asserted.

**Tested by running the real worker on the real job the sweep enqueued**, with only
`mailer.send_email` swapped for a recorder — the same lesson the previous entry was written from,
applied one layer further out: a test that asserted `deliver_to` reached `params` would pass just as
happily if nothing ever mailed it. Thirteen checks, mutation-verified three ways — removing the
delivery call fails five, removing the `routine_id` guard fails the side-channel check alone, and
letting a delivery failure propagate fails the three that say the job stays `done`.

**It also corrects a claim that had reached four files.** *"There is no scheduler of any kind in this
tree"* was recorded as false in `docs/roadmap.md` earlier the same day, and was still stated as fact
in a comment in `routers/jobs.py`, in the docstring of `test_artifact_deliver.py`, and in a released
changelog entry. Only the *library* half was ever true — no APScheduler, croniter or cron in
`requirements.in` — while `R22-ROUTINES` had hand-rolled the capability under a different heading.
*Searching for a dependency and concluding there was no capability is what let every copy read true
against the same grep.* The released entry keeps its wording with a dated correction beneath it,
because a shipped changelog is a record rather than a place to rewrite history.

### a report package can now be scheduled, and the blocker was in the browser

**Closes the gap the entry below named as the honest remaining work.** "The owner's monthly package,
every month" is the plainest thing anyone wants from a scheduler sitting on a 56-report catalog, and
it was the one thing this scheduler could not do.

**The premise-check moved the whole design.** The entry below diagnosed this as routines not carrying
their job's parameters — true, and not the reason it had stayed open. `routines_run.run_due` built
one params dict for every kind, which is a dict merge to fix. The real obstacle was that **the seven
report moments lived only in `apps/web/src/ui/reportMoments.ts`**: authored in the browser, resolved
in the browser, turned into `{moment_id, reports[]}` and handed to the job. `reports.py` contained no
notion of a moment at all — grepped, not assumed. So nothing server-side could turn *"the owner's
monthly package"* into a report list, and the plumbing was never the part that was missing.

**Python owns the moments now.** `services/api/src/aec_api/report_moments.py` holds the table;
`routines_run.job_params` expands a routine's `moment` into the reports it names; `report_package`
joins the routine picklist alongside a `moment` select. A scheduled package and one assembled by
clicking are now the same job, with the same params and the same artifact name.

**Two refusals and one note, because a schedule fails quietly.**

* A package routine that names **no** moment is refused at the sweep, listed with the moments it
  could have named. Enqueueing it anyway would turn a configuration mistake into a monthly failed job
  somebody has to diagnose — *the same defect one layer down* that kept `report_package` off the
  picklist in the first place.
* An **unknown** moment is refused identically. A typo is not a package.
* A moment set on a kind with no use for one still **runs**, and the sweep says it ignored the
  setting. That is what you are left with after changing a routine's kind and not clearing the field:
  a mistake, not a failure. Silently ignoring it is the "package quietly one row shorter" fault this
  feature exists to prevent; refusing to run an otherwise-correct routine is worse.

**The refusal text belongs to the server, and the UI was restating it.** The AI Assist sweep rendered
every refusal as *"names unknown kind X"* — true while that was the only way to be refused, and a lie
the moment `bad_params` joined it: a package missing its moment would have been reported as naming an
unregistered job. It now renders the server's own `reason`, which names the fault and lists the valid
choices. *A copy of a string is still a copy, and this one drifted the same day the rule behind it
changed.*

**AND IT FOUND THAT THE SWEEP HAS NEVER PASSED `project_id`, which made the entry below inert too.**
A handler is called as `fn(db, j.params)` and **never sees the Job row**, so `Job.project_id` is
invisible to it. Every registered kind reads `params.get("project_id")`, and two read
`params.get("actor")` as an identity claim recorded against the coordination issues they create.
`routers/jobs.py` writes both into `params` *last*, after the caller's, so neither can be spoofed from
a request body — deliberately, and documented there. **`routines_run` wrote neither.**

So a scheduled job queued cleanly, ran, and died with `report_package needs a project_id`. The entry
below says the picklist "now offers the ten registered kinds that actually run" — **that was wrong,
and it is corrected here**: those ten stopped being *refused at enqueue* and would have *failed at
run*. Fixing the picklist and leaving this is precisely the *"same defect one layer down"* that fix
was written to avoid.

**It was invisible because every test asserted the ENQUEUE and none asserted the RUN.** The Job row
was right — right kind, right reports, right moment — and could not execute. `test_routines_run.py`
now runs the real handler on the real params the sweep produced: half a second, one 11-report,
21 KB PDF. Mutation-checked — removing `project_id` and `actor` fails five checks, the first with the
exact error above.

*Found by CodeRabbit on this PR, on `report_package` alone; the ten other kinds were the same defect
and are the reason this is a correction rather than a note.*

**Two copies of one table, chosen and priced rather than overlooked.** `reportMoments.test.ts` reads
`report_moments.py` off disk and asserts ids, order, labels, occasions and report lists are
identical — the same technique that file already uses to check the catalog against `reports.py`, for
the same reason. Order is part of the assertion because it is assembly order for the PDF. The
single-source alternative — delete the literal, fetch the moments from the API — is a Report Center
change rather than a scheduler one, and it is recorded in `report_moments.py` as the open option.

**Gated in both languages, and mutation-checked in both.** `test_routines.py` asserts set equality
both ways between the register's moment options and the server's table — a moment offered but unknown
is a routine that can only be refused, and a moment known but not offered is a package nobody can
schedule, which is the quieter half. It also asserts every report a moment names is one the catalog
serves, and that no moment exceeds the 16-report cap `_report_package` enforces. Mutations verified:
renaming a report id, reordering the moments and deleting one each fail the web tripwire; neutering
`job_params` fails eight of the thirteen new backend checks.

*The exemption in the entry below is gone because the gap it described was closed, not because the
argument stopped applying.* An exemption named in a gate is a promissory note; this one was paid.

### every routine kind a user could pick was unrunnable

**Fixes a fully-built feature that could never run once.** `modules/routine/module.json` offered five
`kind` options — `progress_report`, `schedule_risk_scan`, `cost_variance_scan`, `provenance_check`,
`custom` — and `jobs.KINDS` registers **none of them**. Verified by executing against the live
registry, not by reading: the intersection was **empty**.

`routines_run` refuses an unregistered kind with `unknown_kind`, so **every routine anyone created
through the Routines module was refused at sweep time** — on a module shipping a full workflow
(draft/active/paused/retired, activate, pause, retire), a persisted register carrying each routine's
own `last_run`, cadence, and a sweep endpoint. All of it correct; all of it unreachable.

The picklist now offers the ten registered kinds that run from the project alone: `model_ci`, `ids_validate`,
`clash_detect`, `clash_federated`, `escalation_scan`, `cobie_export`, `model_export`,
`compiled_set_pdf`, `labor_estimate`, `energy_analyze`.

**Which ten was derived, not chosen.** The sweep enqueues `{routine_id, window_start}`, so a kind is
schedulable only if every other parameter has a default. All twelve handlers were read — not
sampled — and each of these ten takes its non-project params as `params.get(…) or <default>`.

⚠️ *Corrected by the entry above: that reading established what each handler DEFAULTS and missed what
they all REQUIRE — `params["project_id"]`, which the sweep did not pass. "Runs from the project alone"
was the right test applied to the wrong half, so these ten went from refused-at-enqueue to
failed-at-run rather than to working. Read for what a function needs, not only for what it defaults.*

**Two kinds are exempt, by name.** `echo` is the queue's smoke-test kind. `report_package` **is**
registered — it is R24-REPORTS-BY-MOMENT's assemble half — but requires a `reports: [id, …]` list the
sweep cannot supply. *(Superseded within the same unreleased window by the entry above: routines now
carry a `moment`, `report_package` is offered, and `echo` is the only remaining exemption. Left
standing because it is why the next change happened.)* Offering it would move the failure from `unknown_kind` at enqueue to *"no reports
in the package"* at run: **the same defect one layer down.**

*That also re-scopes R24's "scheduling still open".* A complete scheduler already ships; what is
missing is a way for a routine to carry its job's parameters. That is a routine-record change, not a
scheduler change, and it is the honest remaining work.

**The gate lives in `test_routines.py` because that file already names this blind spot.** Its header
says a suite that only asserts refusals cannot tell a careful feature from a no-op, and pairs every
"must not fire" with a "must fire". It asserted that an *unknown* kind is refused; nothing asserted
that the kinds a user can actually *choose* were not all unknown. **A refusal test passes just as
happily when everything is refused.** The new check asserts the set relationship — every option
registered, every registered kind offered or exempt by name — plus a non-empty floor so it cannot
pass vacuously. Mutation-checked: reinstating a dead option fails, and silently dropping an offered
kind fails.

*Existing routine records naming an old kind are left alone rather than rewritten.* They are already
refused, so nothing regresses, and silently changing what a user configured would be a worse fault
than the one being fixed.

### the app.ts figure was wrong in four places, and the gate that was supposed to stop that reached one of them

**Corrects `docs/roadmap.md`, and widens `services/api/test_claude_md_gates.py` to the class rather
than the instance.**

The R39-DECOMP-VIEWER entry carried **three different figures for one file**: a header saying
`app.ts` is "5,160 → **3,311**, a 36% cut", a shipped block saying "5,160 → **2,944**, a 43% cut",
and the ratchet pinning **2,508**. A fourth sat elsewhere in the file — "5,064 → 3,444 → and thirteen
slices since". The header also claimed "seven slices shipped" directly above a list naming eleven.

**The two baselines were both real, and neither was labelled.** `CLAUDE.md` measures from 5,064 —
the file before the first extraction commit of 2026-08-06 — while the roadmap measured from 5,160, a
**same-day peak** partway through it: the file grew before it shrank. Nothing on the page could tell
a reader the two were counted from different points. The baseline is now stated, matches `CLAUDE.md`,
and the current figure is the ratchet's own count.

**The gate is the real subject here.** The previous release added a check binding `CLAUDE.md`'s
narrative `app.ts` figure to the `test_file_sizes.py` pin, on the reasoning that *prose is a copy of
a gated value and a copy is what drifts*. That reasoning was right and the implementation was too
narrow: it gated **one copy of a number that lives in four places**, and the other three were already
wrong when it shipped. *Gating the instance you happened to be looking at is not gating the class.*
The check now scans every doc that carries the baseline-anchored form.

**It immediately earned that.** Having corrected the two figures I found by reading, the widened
check failed on a **third** I had missed entirely.

**And mutation testing found a defect in the widened check itself.** Its first draft used a summed
floor — "at least 2 figures across the docs" — and reported "3 figures across 2 docs" while **all
three came from the roadmap**: `CLAUDE.md` words it "5,064 lines to", so the arrow pattern never
matched it and its contribution was zero. A mutation that reformatted only the roadmap took the
count to 0 and exposed it. That is precisely the per-doc vacuity failure this same file's citation
ratchet was built to prevent, repeated one screen further down. The floor is now **per-doc**, and
`CLAUDE.md` is covered by name rather than by assumption.

### SCALE-SEAM (104): coverage maps

Extracts `spineTraceability` and `scopeRegister` from `client.ts` (**572 → 554**) into
`apps/web/src/api/coverageMaps.ts` — *how completely is this project's chain of records linked, and
exactly what is missing.*

**This is the affirmative half of a boundary (103) drew by exclusion.** `acceptanceGates.ts` took the
four methods that collapse the project to one accept/refuse verdict, and named `spineTraceability` as
the closest miss *precisely because* it maps completeness rather than deciding. Both members here
report proportion-complete across several link types — `specs_packaged_pct`, `packages_costed_pct`,
`sheets_specced_pct`, `spec_to_budget_pct`; `pct_quantified`, `pct_allocated`, `pct_scheduled` — plus
the individual records lacking the link: `specs_without_bid_package`, `bid_packages_without_cost_code`,
`sheets_without_spec`; `gap_items` with per-item `gaps[]` and `status: "complete" | "gap"`. **Neither
carries a verdict field.** Same test as (103), run for inclusion this time.

**Deriving the population required resolving named return types, and that is the lesson.** A scan of
method bodies for coverage vocabulary returned `scopeRegister`, `citedQuery` and `progressActuals` —
and **missed `spineTraceability`, the strongest member**, because its return is the named type
`SpineTraceability` and its body contains none of those words. That is the exact **mirror** of the
mistake (103) recorded, where a body scan *over*-counted by matching the doc comment of the next
method. *A textual scan of a typed language reads neither the comments nor the types correctly — it
finds candidates, it never counts them.*

**Exclusions.** `citedQuery` carries `coverage`, `uncited_claims` and `fully_cited`, but its product
is an *answer* whose sourcing those annotate — the caller renders a cited answer, not a worklist.
`masterBuilderBrief` is **the closest call in this slice**, closer than `spineTraceability` was to the
gates: it has `readiness_pct`, `ready_steps` and `gap_steps`. It stays because its product is a
narrative brief with a `reframe_prompt` and a `disclaimer`, where the percentages head a document
rather than being it — recorded rather than asserted, since a later reader may decide otherwise.
`progressActuals`'s `pct_complete` is physical progress against a planned quantity, banded
`ahead`/`on_track`/`behind`: variance over time, not completeness of linkage.

**A correction to a follow-up proposed in (103).** That PR said three consecutive slices leaving an
orphaned type import in `client.ts` was "a pattern that wants a gate rather than vigilance". **It
already has one.** `tsc` reports the orphan as `TS6196`, and it caught every instance — `EnergyResult`
(101), `PrequalScores` (102), `DiligenceReadiness` (103) and now `SpineTraceability` (104). None ever
reached a commit. Proposing a gate for a class the toolchain already gates is how a checklist grows
without getting safer; the follow-up is withdrawn.

### SCALE-SEAM (103): acceptance gates

Extracts `permitReadiness`, `diligenceReadiness`, `handoverAcceptance` and `validate` from
`client.ts` (**589 → 572**) into `apps/web/src/api/acceptanceGates.ts` — *will an outside party
accept this project, and what is blocking it.*

**Neither the route nor the audience produces this grouping.** The four routes are
`/permit/readiness`, `/diligence/readiness`, `/handover/acceptance` and `/validate` — four different
prefixes, so a prefix grouping takes one each and the set never forms; the shared leaf word
"readiness" reaches only two of the four. The deciding parties are an AHJ, an investor, an owner and
an IDS checker — four different audiences, so grouping by reader fails too. What forms it is the
**shape of the return**: each collapses the whole project to a single accept/refuse verdict
(`verdict` / `go` / `accepted` / `status: "pass" | "fail"`) and then enumerates what withholds it.

(102) was carried by a prefix that actively *disagreed* with the seam; this one by a vocabulary that
says nothing at all — **four names sharing no words can still be one question**. That is the inverse
of the error (85), (89) and `annotate.ts` each recorded, where a shared mechanism looked like a
shared question.

**The two exclusions did the work.** `spineTraceability` is the closest miss — same domain,
adjacent in the file, equally project-scoped — and returns `coverage`/`gaps`/`chain` with **no
verdict field at all**: it maps completeness for a human rather than deciding acceptance.
`editPrecheck` *does* return a verdict, but judges a **pending action** ("may I run this recipe with
these params"), is remedied by changing the parameters you are about to submit, and sits beside
`addCurtainWall` as the precheck for `editIfc`.

**One false positive is worth recording.** A scan for verdict-shaped returns also flagged
`collabSnapshot` — but the match came from the doc comment introducing `permitReadiness`, the *next*
method. A method-body splitter that runs to the next header swallows the comment belonging to that
header, so the population silently inherits its neighbour's vocabulary; a count of six looked
entirely checked. Only reading each candidate caught it.

Also files `handoverAcceptance`, which an earlier slice had parked under an explicit "UNFILED" note
asking for it to be placed *by what it answers rather than by what it sits next to*. That note is
**narrowed to two entries, not deleted** — the other two are still genuinely unfiled, and a note
that silently loses entries is how earlier slices lost methods.

### review fixes, and a gate for the number that keeps drifting

**Four review findings on the same pull request, and the second one was self-referential.** The PR
corrected `CLAUDE.md`'s stale `apps/web/src/viewer/app.ts` line count from "3,444" to **2,570** —
and then, in the same PR, R39-DECOMP-VIEWER ⑰ took the file to **2,508**. The paragraph diagnosing
*numbers that decay toward the conclusion they support* decayed toward its own conclusion before it
merged, and a review bot found it rather than the author.

* **`services/api/test_claude_md_gates.py` now checks that number against the ratchet.** The
  existing gate asks whether a cited FILE exists; this asks whether a cited NUMBER is still true.
  It is cheap only because the value is not really `CLAUDE.md`'s to hold — `test_file_sizes.py`
  already pins the same file at an exact size, so the prose is a **copy of a gated value, and a copy
  is what drifts**. Mutation-checked both ways: a wrong figure fails, and a *reworded sentence* fails
  too rather than passing on two `None`s, which is the vacuous-green failure that file's own header
  calls worse than no gate at all.
* **R38-SYNC-2D3D is CLOSED, with its children named.** The entry said three of four children were
  open and named none of them. Re-derived by grepping the tree rather than reading the file that was
  already wrong: `R38-SYNC-SELECT`, `R38-SYNC-VIEW`, `R38-PLAN-TRANSFORM` and `R38-PLAN-IDENTITY`,
  and `docs/roadmap-completed.md` carries a ✅ for **each**. The 2026-08-10 un-archive was
  mechanically right — a lane row pointed at nothing — and inherited the restored text's open count
  as though the restore had verified it. Nothing had; R38-PLAN-IDENTITY was marked ✅ *that same
  day*, in the archive the entry was being pulled out of. **Un-archiving restores an entry's text,
  not its truth.**
* **Naming those children made them items, and the gates said so.** Adding four bold item codes to
  `docs/roadmap.md` put three new orphans in `apps/web/src/shell/roadmapLanes.test.ts` and a stale
  open-vs-implemented pair in `apps/web/src/shell/roadmapStale.test.ts`. The fourth escaped only
  because its line happened to contain a ✅ in prose. All four now carry an explicit ✅ marker —
  *passing by accident and passing by construction look identical until something moves.*
* Completed the verbless counterparty-risk entry below, and gave the bare `wc -l` in `CLAUDE.md`'s
  re-measure command its argument — an instruction to verify that hangs on stdin is one nobody runs
  twice.

### SCALE-SEAM (102): counterparty risk

**Extracts** `prequalScores`, `coiExpiry` and `lienExposure` out of `client.ts` (**603 → 589**) into
`apps/web/src/api/counterpartyRisk.ts` — *which trade partner is a risk on this job, and why.*

**The witness is that the seam disagrees with the route prefix.** Two sit under `/prequal/`, one
under `/payapp/lien-exposure`, so grouping by prefix would have **split** the set — while all three
return per-counterparty rows carrying a verdict about that counterparty: `risk_band` + `flags`,
days-to-expiry, `exposure` + `vendors_at_risk`. That is the affirmative form of a rule this file has
only ever recorded negatively — (85) rejected "they are all multipart uploads", (89) "they are all
module records", `annotate.ts` "they all call `editIfc`" after measuring 24 recipes across nine
categories. A shared mechanism is not a question; here the mechanism argues *against* the grouping
and the shape of the returns argues for it, so the evidence is not something a name could produce.

`benchmarkResponseRates` sits immediately above them and **stayed**: it returns RFI/submittal
turnaround and names no counterparty at all — it measures how responsive the *process* is. Adjacency
is not a relationship.

Found on the way out: an orphaned `PrequalScores` type import, the same residue slice (101) left
with `EnergyResult`.

### Roadmap truth pass + R39-DECOMP-VIEWER ⑰

**Two stale claims corrected, both found by testing the entry against the tree rather than reading it.**

* **R38-SYNC-2D3D's stated defect is fixed end to end.** The entry said the pipeline *"discards
  element identity at bake time"* and that *"nothing in a plan can name what it draws"*.
  `_bake_uncached` returns `(guid, ifc_class, mesh)` — its own docstring credits R38-PLAN-IDENTITY —
  `cut_baked_guided` emits `(guid, class, polyline)` and has a **production** caller in the plan
  renderer, the SVG carries `data-guid`, and `apps/web/src/viewer/planPane.ts` selects on it. The
  entry described `cut_baked` and `cut_baked_classed` accurately and drew the wrong conclusion,
  because it never looked for a third function. What actually remains is that it claims three open
  children and names none of them.
* **`CLAUDE.md`'s viewer numbers were both stale** — "twenty-eight commits" and "3,444 lines" are
  now **67** and **2,570**. Unlike the Node and Python drifts that file already records, this one
  moved in the direction that *strengthens* its argument, which is the hardest kind to notice: a
  number that decays toward the conclusion it supports never looks wrong.

**R39-DECOMP-VIEWER ⑰ — field verification out of `app.ts` (2,571 → 2,508).**
`apps/web/src/viewer/tools/verifySection.ts`.

`app.ts` is not a class, so REL-4's "grep the `this.` refs before naming the slice" rule has no
`this.` to grep — the file is **one 2,445-line function** and everything in it is a closure. The
equivalent measurement is how many *sibling closures* a candidate captures, and over all fourteen
candidates of 25+ lines **exactly one captured zero**: `renderVerify`. `buildToolsPanel` captures 14,
`handleKey` 12, `selectByGuids` 6 — every other move would have been the callback bag REL-4 warns
about. Four of the five free variables already travelled on the typed `ViewerCtx`, so the deps object
is that context narrowed, not one invented to make the move possible.

**The narrative-chain gate refused the first ratchet entry, correctly.** The previous entry ended at
2,571 and the file measured 2,570 when this slice began — one line had left with no slice recording
it, the drift the roadmap cell already documents from another lane touching the same file. The entry
now runs 2,571 → 2,508 and says which line is the stray, rather than starting at a number nobody can
reproduce.

### Portfolio resourcing

`GET /portfolio/resourcing` (`resource_portfolio.py`) sums weekly **concurrent** resource demand per
trade across projects. `?cap=` flags weeks where one trade is over-committed across the book and
names the competing projects. Rendered on Portfolio, with ⇄ marking the trades on more than one
project — the only ones that can be double-booked.

**A trade on three jobs in the same week looks comfortable on every one of them.** That is what a
per-project histogram cannot show, and it is the whole reason for the endpoint.
`test_resource_portfolio.py` proves it rather than asserting it: two projects at 6 units each are
each under a cap of 8, verified by calling their own `/schedule/resource-loading?cap=8` and getting
nothing back, while the book reports 12 over the same cap.

**"By department" turned out to be the wrong shape.** `resource_assignment.trade` is labelled
"Trade / discipline", and no `department` field exists anywhere in the backend. A department axis is
a product decision, not a filter over data we hold — raised in the roadmap rather than invented.

**Fidelity is reported, not blended.** A project with no assignments falls back to activity
`crew_size` — a crew count, not a resourced plan — so every row carries its `source` and `fidelity`
gives the split.

The two `over_allocation` shapes are **not** interchangeable and both docstrings say so: this one
caps per trade across the book; `resource_loading`'s caps one project's total weekly units.

Found on the way in: the field named `resourced` made `test_route_reachability` report
`/schedule/eot/sourced` as called, because that gate matches route leaves as substrings and
`resourced` contains `sourced`. Renamed to `assigned`; the second instance of that collision is
recorded in the gate's own notes.

### Cross-project Gantt

The Programme card (`/projects/{pid}/schedule/portfolio`) now draws a bar per project on a shared
span: start, finish, duration, which project drives the programme finish, and which are named by an
external link. `apps/web/src/portal/panels/programmeGantt.ts` holds the geometry as a pure function;
the panel only paints what it returns.

**It needed no new engine, and that is the finding.** The roadmap recorded a cross-project Gantt as
missing because `schedule_viz.py` is per-project. But R46's `schedule_portfolio.py` already computes
`project_starts` and `project_finishes` in its single merged pass, and the route already returned
them — `apps/web/src/api/schedule.ts` **named only three scalars**. `HttpCore.json<T>` returns
`res.json()` under an unchecked cast, so the dates were in the parsed response all along; nothing
declared them, so no call site could reach them and none did. Same class as R37-TESTED-UNWIRED one
layer further out: not a route without a caller, but a payload without a reader.

Bars come from the **merged** pass, never each project's standalone CPM. A project can look
comfortable alone and be critical to the programme; its own run would show the comfortable answer.
`services/api/test_programme_gantt.py` asserts the FS link actually pushes fit-out past enabling's
finish — removing the link fails it with exactly that explanation, so the claim is load-bearing
rather than decorative.

**A project with only one dated end gets no bar**, and is listed with the reason. Substituting the
programme's own start or finish for the missing end would draw a bar that looks measured and is not
— the same rule the risk heat map applies to an unmeasured cell.

Writing the test also found that an external link must name activities by **record id**: `wbs` and
`ref` are aliases resolved only for a project's own predecessor tokens, so a link written in WBS
terms is refused as "no such activity". Recorded next to the link that uses it.

### Portfolio risk heat map

`GET /portfolio/risk` (`risk_portfolio.py`) grids `risk_board` across the book: projects down, the
five risk engines across (Monte-Carlo schedule risk · predictive alerts · EVM · pre-flight gate ·
overdue coordination), intensity `3·high + 2·medium + 1·low`. Rendered on Portfolio beside the
executive roll-up, with a "worst first" line and click-through to the project.

`/portfolio/executive` and `/portfolio/construction` roll up *performance*; neither could say which
risk **engine** is hot on which project. Cells come from `risk_board.board` unchanged — same engines,
same Monte-Carlo seed — so a cell and the project's own risk panel cannot disagree. That costs a full
board per project, so the sweep is bounded by `limit` (default 25, clamped 1–100) and reports
`truncated` rather than quietly scanning a prefix.

**An empty cell is not a safe cell.** A grid of counts renders `0` for two different facts: *this
engine looked and found nothing*, and *this engine could not run*. `board` is fail-open per lane and
already separates them, so every cell carries a `state`; an unmeasured cell carries **no counts at
all** rather than zeros, and the UI draws it as a dash. `coverage` reports the split at portfolio
level. A clear signal nobody has a basis for is worse than no heat map.

**`risk_board.LANES` is new, and gated against a real board run.** `board` reports coverage under
lane keys (`schedule_risk`) while its items carry source strings (`schedule-risk`); nothing connected
the two, and a roll-up must join on both. `test_risk_portfolio.py` asserts every lane key `board`
emits appears in the table and every `source` its items carry is a value — so a lane added to `board`
alone fails rather than rendering as a column that never lights up.

Both claims mutation-checked: emitting zeros for an error cell, and dropping a lane from `LANES`,
each fail with the shape named.

### SCALE-SEAM (101): design-phase predicted performance

Six methods out of `client.ts` (**642 → 603**). Five to a new
`apps/web/src/api/designPerformance.ts` — `energy`, `energyModel`, `energyExportUrl`,
`carbonComplianceReport`, `projectCarbon` — and `benchmarkCosts` to `cost.ts`.

**The seam was drawn by earlier slices, not this one, which is the whole witness.**
`operations.ts`'s own header records why the carbon half did not go there: *"`projectCarbon` is
EMBODIED carbon — a design-phase estimate. The GHG figures in `esgSummary` come from metered utility
data. Same molecule, opposite ends of the asset life."* `models.ts` records the parallel call for
`/energy`, and `operations.ts` does hold `/energy/actual`. Prediction versus measurement, committed
to twice independently — these five are the prediction side.

Deliberately **not** named `environmental.ts`: that names the topic both halves share, and would
re-blur the seam `operations.ts` drew.

**A planned `benchmarks.ts` was abandoned on evidence.** `cost.ts` already held `unitRates`
(`/benchmarks/unit-rates`) and `schedule.ts` holds `benchmarksPullPlanning`
(`/benchmarks/pull-planning`), so the repo already distributes that prefix by what each method
answers; grouping the remaining three by route would have contradicted two live placements.
`benchmarkResponseRates` and `spaceUtilBenchmarks` stayed — no mixin owns their question, and
inventing a home on a guess is what produced this file's UNFILED banner.

The DOC-STRAND gate caught the extraction stranding `unitRates`' doc comment above the inserted
block; reunited rather than deleted.

### only committed capital owns anything (cap table + waterfall)

`capital.cap_table` summed `commitment` across every investor whatever their workflow state. A
`prospect` carrying a $10M interest and $0 contributed took 50% of a $10M cap table and halved a real
LP from 60% to 30% — and the number did not stop at display: `distwaterfall` allocates off these rows,
so the prospect drew **$1,818,181.82 of a $2M distribution** while the committed LP got $181,818.18.

**The obvious filter is wrong on its own.** `investor` declares `initial: prospect` and every record
is stamped with it at creation, so on a project where nobody ran the `commit` transition every
investor is a prospect and filtering empties the cap table. `workflow_in_use` separates the readings:
a default state is not a signal. Until some investor moves off the initial state everyone counts;
after that, `prospect` genuinely means "not committed". Prospect rows stay visible at 0% with their
money reported as `pipeline_commitment`, and no longer sort above real owners.

The decision rides on each row as `counts_toward_ownership` so the seven consumers cannot disagree.
Mutation-checking found `test_distwaterfall` passed even with the waterfall ignoring the flag — its
fixture has no prospect — so `test_cap_table_state.py` covers that case through the real API.

### R24-REPORTS-BY-MOMENT: a finished pack can be sent, not only downloaded

`POST /projects/{pid}/jobs/{job_id}/deliver` emails any finished job's artifact to named
recipients, surfaced as **Send** beside **Download** in the job tray.

**The roadmap named the wrong blocker, one layer too high.** It said this "still wants a delivery
surface and SMTP" — both of which already shipped: `mailer.py` sends real mail, and the notification
digest is a working assemble-then-send surface. What was actually missing was smaller and more
specific: **the mailer could not carry a file**. `build_message` gained attachments, and the order
matters — `add_alternative` must run before `add_attachment` or Python refuses outright, which the
test asserts rather than assumes.

Refusals mirror the download route exactly (404 wrong project, 409 while queued/running, 404 with no
artifact), so a caller does not learn two answers to "is this artifact ready", plus two of its own:
an empty recipient list is 422 rather than a silent success, and over 15 MB is 413 rather than a
per-recipient error from a server that would have bounced it. A deployment with no SMTP configured
returns 200 with every recipient `disabled`, so the UI reads `smtp_configured` before claiming a
send. The delivery is audited — a file leaving the system is what an audit log is for.

**Not shipped, deliberately: the SCHEDULED half.** There is no scheduler of any kind in this tree,
so choosing in-process versus external cron is a deployment decision, not a wiring task.

> ⚠️ **Corrected 2026-09-05.** The sentence above is false and is left standing because a released
> entry is a record of what shipped, not a place to rewrite history. `R22-ROUTINES` had already
> hand-rolled a scheduler under a different heading, and scheduled report packages ship in a later
> release. Only the *library* claim was ever true — no APScheduler, croniter or cron in
> `requirements.in` — and what remains a deployment decision is narrower than this says: what invokes
> the sweep on a cadence. This claim reached four files; searching for a dependency and concluding
> there was no capability is what let each copy read true.

## v0.3.1143 (2026-09-01) — SCALE-SEAM ㉝, Last-Planner onto schedule.ts

Six methods out of `client.ts` into the existing `apps/web/src/api/schedule.ts` mixin
(`2,486 → 2,440`). No extra wrapper on `ApiClient`. Also deleted a stranded "Developer cost
budget" comment that had been sitting on the class close with no method under it.

What they answer together: *did this week keep its commitments?* Pull board, printable board,
PPC/TMR metrics, pull-planning benchmark, lean PPC, live board stream.

`MARKS` widened to ㉞ on the way out. Pin lowered with the file. This bump sits on the
`test_release_current` bound (10 ahead of tag `v0.3.1133`).

Follow-on on the same version (no bump — the bound is already tight): **SCALE-SEAM ㉞ ㉟ ㊱**.
Eleven methods out of `client.ts` (`2,440 → 2,323`) into existing mixins, still no extra
`withX()` on `ApiClient`.

- ㉞ *does this frame stand?* — five methods onto `apps/web/src/api/model.ts` (analytical
  summary, gravity solve, OpenSees Tcl, Code_Aster mesh, ASCE 7 lateral). `subsetIfcUrl`,
  collab, carbon compliance, and permit readiness stayed. Two stranded comments on `model.ts`
  deleted.
- ㉟ *what does this model still need, and can we ask it?* — three methods onto
  `apps/web/src/api/topics.ts` (readiness, promote-to-BCF, NL-QA). Not a contiguous run.
- ㊱ *what resources are on site when?* — three methods onto `apps/web/src/api/schedule.ts`
  (get/put logistics, date state). The model graph stayed.

`MARKS` widened to ㊲ on the way out. Pin lowered with the file.

Second follow-on on the same version: **SCALE-SEAM ㊲ ㊳ ㊴**. Twelve methods out of
`client.ts` (`2,323 → 2,258`) into existing mixins.

- ㊲ *what is related to this element?* — three methods onto `apps/web/src/api/model.ts`
  (graph stats, neighbors, doc-graph). QUERY-DSL subset export stayed.
- ㊳ *run this parameterized authoring chain?* — five methods onto
  `apps/web/src/api/authoring.ts` (`editGraph` plus list/save/expand/run macros). Layers stayed.
- ㊴ *what non-destructive property composition is in force?* — four methods onto
  `apps/web/src/api/model.ts` (get/put/resolve/bake layers). Pins stayed.

`MARKS` widened to ㊵ on the way out. Pin lowered with the file.

Third follow-on on the same version: **SCALE-SEAM ㊵ ㊶ ㊷**, plus a harden of leftover `//`
banners. Eight methods out of `client.ts` into existing mixins.

- ㊵ *where do we set out in the field?* — four methods onto `apps/web/src/api/model.ts`
  (points, CSV, DXF, as-installed verify). Pins stayed.
- ㊶ *what axial load per column?* — two methods onto `apps/web/src/api/model.ts`
  (defaults, gravity takedown). Verified progress stayed.
- ㊷ *which envelope ranks, and how do we author the winner?* — two methods onto
  `apps/web/src/api/authoring.ts` (optioneer + recipe chain). Selections stayed.

Deleted the leftover `AUTH-VS` comment on `modelAssets` and the municipal-permit banner on
`scheduleOptioneer`. `apps/web/src/api/docComments.test.ts` now fails a `//` line that sits
on the next method's JSDoc and shares no word with it.

`MARKS` widened to ㊸ on the way out. Pin 2,258 → 2,194.

Fourth follow-on on the same version: **SCALE-SEAM ㊸ ㊹ ㊺**. Eight methods out of
`client.ts` (`2,194 → 2,127`) into existing mixins.

- ㊸ *what layered view preset is in force?* — three methods onto `apps/web/src/api/model.ts`.
- ㊹ *what did the owner pick, and does it trigger a change order?* — two methods onto
  `apps/web/src/api/contracts.ts`. Share tokens stayed.
- ㊺ *is claimed progress the installed one?* — three methods onto
  `apps/web/src/api/schedule.ts` (verified, rollup, capture-diff). Not a contiguous run.

`MARKS` widened to ㊻ on the way out. Pin 2,194 → 2,127.

Fifth follow-on on the same version: **SCALE-SEAM ㊻ ㊼ ㊽**. Eight methods out of
`client.ts` (`2,127 → 2,065`) into existing mixins.

- ㊻ *is this element installed as designed?* — three methods onto `apps/web/src/api/model.ts`.
  Photo upload stayed (PHOTO-PIN is parked). `askModel` stayed.
- ㊼ *what is this asset earning today?* — two methods onto `apps/web/src/api/proforma.ts`.
- ㊽ *which permits exist near this site?* — three methods onto
  `apps/web/src/api/entitlements.ts`. `permitReadiness` stayed.

`MARKS` widened to ㊾ on the way out. Pin 2,127 → 2,065.

Sixth follow-on on the same version: **SCALE-SEAM ㊾ ㊿ ❶**. Six methods out of
`client.ts` (`2,065 → 2,035`) into existing mixins. The CJK enclosed-number block
ends at ㊿; **❶ is 51**.

- ㊾ *what can we print from this project?* — two methods onto `apps/web/src/api/documents.ts`.
  Licence stayed.
- ㊿ *what extra work is unbilled against a change event?* — two methods onto
  `apps/web/src/api/cost.ts`. Submittals stayed.
- ❶ *what labor was certified this week?* — two methods onto `apps/web/src/api/cost.ts`.
  `preflight` stayed.

`MARKS` widened to ❷ on the way out. Pin 2,065 → 2,035.

Seventh follow-on on the same version: **SCALE-SEAM ❷ ❸ ❹**. Six methods out of
`client.ts` (`2,035 → 2,000`) into existing mixins.

- ❷ *what does a cited question return?* — two methods onto `apps/web/src/api/ai.ts`.
  Photo upload and `preflight` stayed.
- ❸ *are required submittals turning around?* — three methods onto
  `apps/web/src/api/procurement.ts`. Not a contiguous run.
- ❹ *what is the CO pipeline worth?* — one method onto `apps/web/src/api/contracts.ts`.
  Action tracker stayed.

`MARKS` widened to ❺ on the way out. Pin 2,035 → 2,000.

Eighth follow-on on the same version: **SCALE-SEAM ❺ ❻ ❼**. Four methods out of
`client.ts` (`2,000 → 1,966`) into existing mixins.

- ❺ *are meeting actions closing?* — one method onto `apps/web/src/api/routines.ts`.
- ❻ *what RFIs are still open?* — one method onto `apps/web/src/api/topics.ts`.
- ❼ *what can we legally build on this site?* — two methods onto
  `apps/web/src/api/entitlements.ts`. Quality stayed.

`MARKS` widened to ❽ on the way out. Pin 2,000 → 1,966.

Ninth follow-on on the same version: **SCALE-SEAM ❽ ❾ ❿**. Five methods out of
`client.ts` (`1,966 → 1,916`) into existing mixins.

- ❽ *can we cover the bid?* — three methods onto `apps/web/src/api/procurement.ts`.
- ❾ *is the installed work passing inspection?* — one method onto `apps/web/src/api/topics.ts`.
- ❿ *is turnover actually closing?* — one method onto `apps/web/src/api/documents.ts`.
  Safety stayed.

`MARKS` widened to ⓫ on the way out. Pin 1,966 → 1,916.

Tenth follow-on on the same version: **SCALE-SEAM ⓫ ⓬ ⓭**. Five methods out of
`client.ts` (`1,916 → 1,867`) into existing mixins.

- ⓫ *is the job on track across domains?* — one method onto `apps/web/src/api/evm.ts`.
- ⓬ *what happened on site this week?* — two methods onto `apps/web/src/api/schedule.ts`.
- ⓭ *can we bring this scan in?* — two methods onto `apps/web/src/api/model.ts`.
  Admin audit stayed.

`MARKS` widened to ⓮ on the way out. Pin 1,916 → 1,867.

Eleventh follow-on on the same version: **SCALE-SEAM ⓮ ⓯ ⓰**. Nine methods out of
`client.ts` (`1,867 → 1,814`) into existing mixins.

- ⓮ *who is on this project?* — four methods onto `apps/web/src/api/auth.ts`.
- ⓯ *what did the system just do, and what broke?* — four methods onto
  `apps/web/src/api/auth.ts`. ⑦ left these behind because they are not `/auth` routes;
  this slice groups by ANSWER (ops observability), not by the leftover admin banner.
- ⓰ *who is looking at the model right now?* — one method onto `apps/web/src/api/sync.ts`.
  Project CRUD stayed.

`MARKS` widened to ⓱ on the way out. Pin 1,867 → 1,814.

Twelfth follow-on on the same version: **SCALE-SEAM ⓱ ⓲ ⓳**. Thirteen methods out of
`client.ts` (`1,814 → 1,740`) into existing mixins.

- ⓱ *what needs my attention?* — four methods onto `apps/web/src/api/routines.ts`.
- ⓲ *what's overdue, and who gets told?* — five methods onto
  `apps/web/src/api/routines.ts`. Clash imports stayed.
- ⓳ *what changed between publishes?* — four methods onto `apps/web/src/api/model.ts`.
  Review gate was not contiguous with the version list.

`MARKS` widened to ⓴ on the way out. Pin 1,814 → 1,740.

Thirteenth follow-on on the same version: **SCALE-SEAM ⓴ ⓵ ⓶**. Eleven methods out of
`client.ts` (`1,740 → 1,663`) into existing mixins. Also dropped an unused `LiveStream`
type import that mobile `tsc` (clean cache) rejected after the stream method moved.

- ⓴ *can we bring this clash report in?* — two methods onto `apps/web/src/api/clash.ts`.
- ⓵ *what's running in the background?* — four methods onto `apps/web/src/api/routines.ts`.
- ⓶ *which projects can I open?* — five methods onto `apps/web/src/api/auth.ts`.
  `meta` stayed.

`MARKS` widened to ⓷ on the way out. Pin 1,740 → 1,663.

Fourteenth follow-on on the same version: **SCALE-SEAM ⓷ ⓸ ⓹**. Eleven methods out of
`client.ts` (`1,663 → 1,584`) into existing mixins.

- ⓷ *is this deployment entitled and wired?* — six methods onto `apps/web/src/api/auth.ts`.
- ⓸ *what's on and around this site?* — four methods onto `apps/web/src/api/entitlements.ts`.
- ⓹ *where are the field marks?* — `pins` onto `apps/web/src/api/topics.ts`.
  ⑳ left pins behind because they are not `/topics` routes.

`MARKS` widened to ⓺ on the way out. Pin 1,663 → 1,584.

Fifteenth follow-on on the same version: **SCALE-SEAM ⓺ ⓻ ⓼**. Eleven methods out of
`client.ts` (`1,584 → 1,512`) into existing mixins. TypeRow / TypeDetail / GroupRow /
AssemblyRow moved to `apps/web/src/api/types.ts` with the family/group methods.

- ⓺ *can this package go out?* — `preflight` onto `apps/web/src/api/documents.ts`.
- ⓻ *what families can I place?* — five methods onto `apps/web/src/api/authoring.ts`.
- ⓼ *how are these elements grouped?* — five methods onto `apps/web/src/api/authoring.ts`.
  Detailing stayed.

`MARKS` widened to ⓽ on the way out. Pin 1,584 → 1,512.

Sixteenth follow-on on the same version: **SCALE-SEAM ⓽**. Five public methods — plus the
private helper three of them share — out of `client.ts`
(`1,512 → 1,462`) into three existing mixins — and the slice is one cluster, not three,
because **one banner was covering three different questions**.

The `// --- AI drafting (RFI / submittal summary / scope of work) ---` section held six
methods. Only four of them draft anything:

- ⓽ *draft this document for me from a file or some text?* — `aiDraftRfi`,
  `draftSubmittalSummary`, `draftScope` and their shared multipart helper `draftPost` onto
  `apps/web/src/api/ai.ts`. All three are `/projects/{pid}/draft/{kind}` doors.
- *what sheets are in this PDF, and make the records?* — `extractSheets` onto
  `apps/web/src/api/drawingSheets.ts`. It is `/extract/sheets`, not `/draft/`, and with
  `create: true` it creates DRAWING records — a drawings question wearing an AI label.
- *how do these bids compare, in detail?* — `bidLevelingDetail` onto
  `apps/web/src/api/procurement.ts`, whose own header has claimed "bid levelling" since ⑥
  while this method sat in `client.ts` under a banner about RFIs. It is the detail view of
  the levelling `procurementLevel` and `procurementLevelQuotes` already answer.

**This is the failure `procurement.ts`'s header recorded at ⑥, met again**: *"the
`// --- section ---` comments label where a run starts and the file then carries on into
other domains, so they have not delimited anything for a long time."* A split by route
prefix or by banner would have moved all six to `ai.ts`; only asking what each method
ANSWERS separates them.

`BidLevelingDetail` dropped from `client.ts`'s type imports and added to `procurement.ts`.
Pin 1,512 → 1,462. `MARKS` unchanged — ⓽ is the last glyph in the vocabulary, so the next
slice needs the range widened before it can be numbered.

Seventeenth follow-on on the same version: **SCALE-SEAM ⓾**. Four methods out of `client.ts`
(`1,462 → 1,436`) onto `apps/web/src/api/ai.ts` — two AI-facing questions:

- *can I generate a concept image from this project, and store the result?* — the three
  feature-flagged `/concept-render` doors (status, request, ingest).
- *is this project's data ready for AI to work on?* — `aiReadiness`, the single-source /
  completeness / governance / model-integrity scorecard.

**`aiReadiness` had been declined twice, and the two refusals disagreed with each other.**
`ai.ts` passed on it at ㉑ because *"it is `/ai-readiness`"* — a ROUTE reason, under the rule
that file was split by at the time. `documents.ts` passed on it at ㉛ on semantic grounds:
*"it is an AI scorecard, not a CDE question."* That second sentence is a characterisation of
where it belongs, and it is what moved it. Both headers now say so; `documents.ts`'s note no
longer claims the method is in `client.ts`, because it is not.

Same lesson as ⓽ one file over: a split by route prefix leaves things misfiled, and the
misfiling survives precisely because the route reason reads like a decision.

`MARKS` widened to **⓾** (U+24FE) — the last glyph of the double-circled range ⓵–⓾. Pin
1,462 → 1,436.

Eighteenth follow-on on the same version: **SCALE-SEAM (81)** — the first slice with **no mark**.
The ⓵–⓾ glyph range is exhausted and there is no natural successor, so the numbering stops here
rather than starting a fourth visual scheme. Nothing depended on it: the mark is optional in
`roadmapLanes.test.ts`'s item regex, and the roadmap item and lane cell already carry none.

Eight methods out of `client.ts` (`1,436 → 1,374`) into three existing mixins:

- *is this project ready for substantial completion, and certify it?* — `turnoverReadiness`,
  `turnoverStatus`, `turnoverCertify`, `g704Url` onto `apps/web/src/api/documents.ts`, beside
  `closeoutSummary`, which ❿ brought in under *is turnover actually closing?* `ModuleRecord`
  moved with them into that file's type imports and out of `client.ts`'s.
- *what IFC class should these generic elements be?* — `ifcClassify` onto
  `apps/web/src/api/model.ts`.
- *what is the market doing to my costs?* — `marketSnapshot`, `marketContext`, `marketEscalate`
  onto `apps/web/src/api/cost.ts`. `marketSnapshot` is global (`/market/snapshot`, no project id);
  the other two apply that snapshot to one project.

**Third banner in three slices that over-claimed.** `ifcClassify` sat under
`// --- turnover: substantial completion (G704) + record model ---`, separated from `g704Url` by a
blank line, with nothing to do with substantial completion — a model question filed at whatever
banner happened to be nearest. ⓽ found the same thing in "AI drafting" (three questions), ⓾ found
it in two headers that had declined one method for contradicting reasons.

The two remaining banners are the largest instance yet and are what the next slices are for:
`// --- Responsibility matrix (RACI / DACI) ---` carries **13** methods including `standardsCheck`
and `mcpTools`, and `// --- CX-1 commissioning loop ---` carries **49**, among them `rebarBbs` and
`rebarCheckCage`. Neither is what its banner says.

Pin 1,436 → 1,374.

Nineteenth follow-on on the same version: **SCALE-SEAM (82)**. Six methods out of `client.ts`
(`1,374 → 1,339`), and the banner that held them was the worst yet: `// --- Responsibility matrix
(RACI / DACI) ---` covered **thirteen** methods and described **four**.

- *how good is this model, measured against a standard?* — `standardsCheck`, `bimKpiScorecard`,
  `openbimQuality`, `lodAssessment`, `envelopeAudit` onto `apps/web/src/api/model.ts`.
  `lodAssessment` joins `lodCensus` and `lodHandoverReadiness`, already there.
- *how well does this project follow its own naming rules?* — `namingAudit` onto
  `apps/web/src/api/documents.ts`.

**`namingAudit` was on its way to `model.ts`** — "audit" reads like model quality — **until the
return shapes were compared.** It reports compliance for `containers` and `sheets`;
`documents.ts`'s `namingConventions` states the pattern for `container` and `sheet`. Same two
subjects: one says what the rule is, the other how well it is followed. Splitting that pair would
have been the mistake, and only reading both return types found it.

**The banner is now split rather than left over-claiming.** The RACI header names its four
`/responsibility` methods, and the three that are not RACI — `mcpTools` (`/mcp/tools`, global),
`handoverAcceptance`, `inspectVim` (`/convert/vim/inspect`) — sit under an explicit *UNFILED*
header that names them and says each needs a home decided by what it answers. Naming them is the
point: an over-claiming banner is how the previous three slices each lost a method.

Pin 1,374 → 1,339.

Twentieth follow-on on the same version: **SCALE-SEAM (83)** — the banner that ran to the end of
the file. `// --- CX-1 commissioning loop ---` covered **49 methods**, of which **three** were
commissioning. Nine methods out of `client.ts` (`1,339 → 1,292`) into three existing mixins:

- *is commissioning closing, and in detail?* — `cxSeed`, `cxMatrix`, `cxDossier` onto
  `apps/web/src/api/documents.ts`, beside `closeoutSummary`, which ❿ brought in and which already
  returns a `commissioning` **rollup** (`cx_count` / `passed` / `failed` / `conditional`). These
  three are the detail behind that number — the same rollup-and-detail pair as `procurementLevel`
  and `bidLevelingDetail` at ⓽.
- *does this model pass its checks?* — `ciRun`, `ciLatest`, `rulesRun`, `rulesGeometryRun` and
  `rebarCheckCage` onto `apps/web/src/api/model.ts`, beside `envelopeAudit` and `standardsCheck`.
  `ModelCiReport` moved with them into that file's type imports and out of `client.ts`'s.
- *what does this model cost, by storey and discipline?* — `qtoByFloor` onto
  `apps/web/src/api/estimate.ts`, beside `estimateFromModel`.

**Two placements were decided by return shape, against what the route said.** `qtoByFloor` reads
as a quantity method and its route is `/qto/by-floor` — but every line carries `rate` and `amount`
and the payload has a `grand_total`. It is priced takeoff, so it went to estimating, not to the
model reads. And `rebarCheckCage` came to `model.ts` while **its two `/rebar/` siblings did not**:
`rebarBbs` and `rebarBbsCsvUrl` share a route prefix and a `REBAR-RULES` doc tag with it, and
answer a different question — a bar bending schedule is a quantity, an ACI cage check is the same
question `envelopeAudit` asks. Route-and-tag kinship is exactly the reason ⓽ nearly filed
`bidLevelingDetail` in `ai.ts`.

**The banner was replaced, not narrowed.** With the three `/cx/*` methods gone it named *nothing*
— the worst state a label can be left in, one step past the over-claiming that cost ⓽, ⓾, (81) and
(82) a method each. In its place is an `UNFILED` map of the 40 that remain, grouped by what each
cluster answers: reinforcement quantities, development budget and draws, portfolio, saved views,
material palette, site and test fit, four unrelated singles, and five that are genuinely
client-level (`enumOptions`, `searchAll`, `attachmentUrl`, `templates`, `rvtBridgeStatus`) and
should **stay**. Those five are the first methods in this whole sequence marked as *not* to be
extracted — a decomposition that never says "this one is already home" will eventually move
something that should not move.

Pin 1,339 → 1,292.

Twenty-first follow-on on the same version: **SCALE-SEAM (84)** — the cluster that split three
ways, and **the slice that found (83) had corrected a right number to a wrong one**.

Twelve methods out of `client.ts` (`1,292 → 1,212`), plus the `DevBudget*` interfaces from
`client.ts` into `apps/web/src/api/types.ts`, where a mixin can import them:

- *what is this development costing, and how is it funded?* — `devBudget`, `saveDevBudget`,
  `devBudgetCostLines`, `sourcesUses`, `gmpReconciliation`, `syncGmpToHard`, `constructionDraws`,
  `loanDraws`, `loanDrawRequestPdf` onto `apps/web/src/api/proforma.ts`, beside `drawPackage` and
  `twoSidedBudget`.
- *are we priced right, and does cost tie back to the model?* — `pricingReconcile`,
  `costTraceability` onto `apps/web/src/api/cost.ts`.
- *what has each subcontract billed?* — `subcontractorBilling` onto
  `apps/web/src/api/accounting.ts`, beside `contractorStatements` and `wip`.

**The types decided the hardest placement.** `gmpReconciliation` and `syncGmpToHard` look like
`cost.ts` work — ㉚ put the GMP/pay-app stack there, and both routes are GMP-flavoured. But
`cost.ts`'s `gmpBudget` is the **GC's own** GMP (contract value, categories, EAC/ETC), while these
two are the **developer** comparing their hard cost against it, and both return `DevBudgetLine` /
`DevBudgetSummary`. Filing them in `cost.ts` would have forced the `DevBudget` type family into
two mixins. *A split that duplicates a type family across mixins is almost always the wrong seam*
— a sharper rule than "group by what they answer", because it is mechanical.

### (83) reported 44 where the answer was 49, and 49 was already written down

The `// --- CX-1 commissioning loop ---` banner really held **49** methods. (83) counted them with

    /^  ([a-zA-Z_]\w*)\(/

which does not match `async` methods, so five were invisible — `importRvt`, `loanDrawRequestPdf`,
`raisePlan`, `takeoffDxf`, `uploadSourceIfc`. The roadmap had said 49. **(83) "corrected" the
correct number to an incorrect one** and shipped 44 into this changelog, the roadmap and its own
merge commit — in a slice whose subject was counts that disagree with the lists beside them.

The failure is not carelessness with a number. **A regex that silently drops a syntactic variant
returns a smaller number, not an error, and a smaller number looks exactly like a right one.**
That is the same shape as the inverted count #396 pinned, the two totals #399 fixed, and a `&&`
chained off `head` that printed "TYPECHECK CLEAN" over a failing `tsc`. Four instances in one day,
every one of them a check whose output did not measure what it claimed.

So the map is no longer proofread — it is **derived**, by `apps/web/src/api/unfiledMap.test.ts`:
the declared count must equal the methods actually below the banner, every such method must be
named, and no name may survive after its method has moved. Its method regex matches `async`. Which
tokens count as method names is itself derived — a word qualifies only if some file in `api/`
declares a method by it — because a hand-kept word list would either miss `property` and
`templates` (no capital letter) or swallow prose like "check" and "stay". All three assertions were
mutation-checked: a wrong count, a dropped name, and a name left behind after its method moved.

**The gate found two more things immediately.** The map had never listed `takeoffDxf`, `raisePlan`,
`uploadSourceIfc` or `importRvt` — all `async`, all invisible to (83)'s query — and they form a
cluster the map had no line for at all: *how do I get a file into this project?* They are four
multipart uploads, and `rvtBridgeStatus` is the bridge `importRvt` drives, so **(83)'s claim that
`rvtBridgeStatus` was a client-level "stayer" was wrong** — it was only ever plausible because the
four uploads beside it could not be seen. Four stayers remain: `enumOptions`, `searchAll`,
`attachmentUrl`, `templates`.

Pin 1,292 → 1,212. Twenty-eight methods left under the banner, and that number is now checked.

Twenty-second follow-on on the same version: **SCALE-SEAM (85)** — *mechanism is not a question*,
and **the new gate had the old bug**.

Five methods out of `client.ts` (`1,212 → 1,173`), into three existing mixins:

- *how does this project get its source model?* — `uploadSourceIfc`, `importRvt` and
  `rvtBridgeStatus` onto `apps/web/src/api/model.ts`. The first two both return `source_ifc` and
  both set it; the third is the precondition for the second, reporting whether the paid Autodesk
  bridge is enabled and what it costs.
- *turn this 2D plan into authored walls?* — `raisePlan` onto `apps/web/src/api/authoring.ts`.
- *what quantities are on this drawing?* — `takeoffDxf` onto `apps/web/src/api/estimate.ts`,
  beside `takeoff2d`.

**(84) had grouped all five as *how do I get a file into this project?*, and that was wrong for a
new reason.** They are all multipart uploads — but "multipart upload" is a HOW, not a question.
Grouping by mechanism is the same error as grouping by route prefix, one level further from the
domain. Read for what each answers and they split four ways: a quantity takeoff, a model write, two
that set the source model, and a feature-availability check.

**`rvtBridgeStatus` did not go to `entitlements.ts`, and the near-miss is worth recording.** The
name fits perfectly — a paid feature, enabled or not, with a cost warning. But that mixin is the
**land-use** entitlements route group (`/projects/{pid}/entitlements/…`): planning approvals,
review cycles, permit conditions. Same word, different domain. Filing on it would have been the
route-prefix mistake wearing a vocabulary disguise.

### The gate written to prevent the count bug had the count bug

`unfiledMap.test.ts`, added one slice earlier, derives which words in the map are method names by
scanning `api/` for method declarations. Its pattern required **exactly two spaces** of indent.
But five files indent by four — `authoring.ts` alone has **37 methods** — so roughly 47 names were
missing from that vocabulary, and a map entry naming any of them could never be reported stale.

*That is the `async` bug again, in the test written to stop it.* Both are a pattern whose scope
silently excludes part of its population, and both return a smaller set rather than an error. The
fix is not a wider regex alone: it now also **asserts that every file declaring a mixin contributes
at least one name**, so a whole file's convention cannot drop out silently again. Mutation-checked
by having the map name `editIfc`, a four-space method — previously invisible, now caught.

The gate also earned its keep the ordinary way: mid-slice it failed with *"the banner says 28
methods but 23 follow it"* and *"the map names these, but they are no longer under the banner"*,
naming all five moved methods. First time it caught live drift rather than a deliberate mutation.

`constructionPortfolio` and `materialPalette` got the doc comments they had never had. The first is
global (`/portfolio/construction`, no project id) and carries no investment figure — which is what
separates it from `executivePortfolio`, and why the portfolio trio still under the banner is
flagged there as likely to split rather than move as one.

Pin 1,212 → 1,173. Twenty-three methods left under the banner.

Twenty-third follow-on on the same version: **SCALE-SEAM (86)** — *a shared word is not a shared
domain*, for the third slice running.

Six methods out of `client.ts` (`1,173 → 1,131`), into three existing mixins:

- *is every job on track?* — `executivePortfolio`, `constructionPortfolio` onto
  `apps/web/src/api/evm.ts`, beside `projectHealth`.
- *which projects should we prioritise?* — `portfolioPrioritization` onto
  `apps/web/src/api/proforma.ts`, beside `portfolio`, `portfolioCompare` and `pipelineFunnel`.
- *save a selection rule and run it* — `smartViews`, `smartViewsSave`, `smartViewRun` onto
  `apps/web/src/api/elements.ts`, beside `colorBy` and `colorFacets`. `SmartView` moved with them
  out of `client.ts`'s type imports.

**The portfolio trio split 2/1, and only the shapes said so.** All three are `/portfolio/*` global
rollups, so any route-based cut moves them together. But `evm.ts` recorded at ⓫ that `projectHealth`
answers *"is the job on track across domains?"* for one project — and `executivePortfolio` is that
same question over the whole portfolio, `constructionPortfolio` the same one domain narrower. Those
two REPORT. `portfolioPrioritization` ranks projects by a weighted composite of return, budget,
schedule and risk and names a best and worst: it DECIDES, which is a pipeline question, not a status
one.

⓫ also recorded that *"safety sat below and did not come"*, and `constructionPortfolio` does carry
`recordables`. It came anyway — it is a cross-project execution rollup that happens to include a
safety count, not the safety module. Naming the tension in the header is the point; a slice that
quietly contradicts an earlier one's stated reason is how the next reader stops trusting either.

### The third homonym in three slices

`smartViews` nearly went to `modules.ts`, and the reason is worth recording because the name
matched **exactly**: that mixin already owns a saved-views family — `SavedViewDef`, at
`/projects/{pid}/modules/{key}/views`. Comparing the two types separated them in one line. A
`SavedViewDef` is `{q, state, sort}` — a data-grid filter over a register. A `SmartView` is
`{selector, mode: isolate|color|hide, color}`, and `smartViewRun` returns matched **GUIDs**. Same
word, unrelated things.

That is three in three slices: `rvtBridgeStatus` versus the LAND-USE `entitlements.ts` at (85),
"they are all multipart uploads" as a question at (85), and now "view". **A name is evidence about
vocabulary, not about domain** — and in a codebase spanning development finance, construction
operations and 3D geometry, the same word reliably means three things.

Pin 1,173 → 1,131. Seventeen methods left under the banner, and the count is checked.

Twenty-fourth follow-on on the same version: **SCALE-SEAM (87)** — *the map described the tail, not
the file*.

Thirteen methods out of `client.ts` (`1,131 → 1,015`), into eight existing mixins:

- *what does the model look like?* — `materialPalette`, `saveMaterialPalette`, `applyMaterialPalette`
  onto `apps/web/src/api/elements.ts`, beside `colorBy`.
- *does a scheme fit the site?* — `testFitCompare`, `testFitOptimize` onto
  `apps/web/src/api/entitlements.ts`, beside `feasibility` and `feasibilityCompare`.
- *what is the asset's record?* — `property`, `saveProperty` onto `apps/web/src/api/proforma.ts`.
- *what does it cost to build?* — `rebarBbs`, `rebarBbsCsvUrl` onto `apps/web/src/api/estimate.ts`.
- *what is expiring?* — `complianceExpiring` onto `apps/web/src/api/modules.ts`.
- *how did the bids compare?* — `bidLeveling` onto `apps/web/src/api/procurement.ts`.
- *is the job safe?* — `safetyMetrics` onto `apps/web/src/api/schedule.ts`.
- *how is the programme performing?* — `pxSummary` onto `apps/web/src/api/evm.ts`.

`OptScheme`, `DepthPoint`, `MaterialEntry`, `MaterialPaletteResult` and `EgressResult` moved to
`apps/web/src/api/types.ts` with them.

### The finding: the map covered the tail of the file, not the file

Deriving the whole population instead of trusting the banner: **130 methods in `client.ts`, 4 below
the banner, 126 above it.** Those 126 — `disciplineTree`, `classify`, `specManual`, `editUndo`,
`energyModel`, `rentRollScrub`, `esgSummary` and the rest — were never inside the CX-1 banner, so no
map has ever covered them. The UNFILED map described the TAIL of this file, and every completeness
statement made against it was scoped to a list the same slices had authored.

So the banner is renamed UNFILED → **STAYING** and reduced to what it actually decides: four
global/cross-cutting methods (`enumOptions`, `searchAll`, `attachmentUrl`, `templates`) recorded as
DECIDED. It no longer implies anything about the file above it, and it says so in the text.

### Two corrections to my own earlier slices

`evm.ts` at ⓽ split a rollup from its detail; `pxSummary` is the programme-level rollup that belonged
on the same side of that cut and did not move with it. And `modules.ts` carried a doc comment
orphaned from `complianceExpiring` — the comment had been swept into the mixin in an earlier slice
while the method it documented stayed behind. Reunited here.

### The predicate that was replaced twice

`test_roadmap_status.py`'s SCALE-SEAM gate was `client.ts > 1200` — a threshold proxy that decayed
and went red at (85). It was replaced with a check for the banner string, and **that replacement was
also a proxy**: it would have declared SCALE-SEAM DONE with 126 methods outstanding, and it was
described as a fix in a commit message, a PR body and to the user before that was noticed. It now
counts methods not on the declared keep-list — the thing the claim is about — and was
mutation-checked four ways: baseline 126 → OPEN, banner renamed → still OPEN, keep-list deleted → 130
(fails safe), simulated completion → 0 → DONE. *A proxy can be replaced by another proxy and read as
a fix.*

### The ratchet now checks its own history chain

`test_file_sizes.py` records each slice as `(before -> after)` in the narrative beside the pin, and at
(86) CodeRabbit caught `(1173 -> 1132)` sitting beside a pin of `1131`. The chain is now asserted:
consecutive pairs must link, and an unrecorded SHRINK fails (growth does not — files legitimately
grow between slices). It took four tries to get right, and all four failures were found by running
it, not by reading it: `\d+` skipped underscore-separated numbers; requiring a closing paren skipped
an entry and invented a false break; strict equality flagged legitimate growth; and the finished
checks **printed FAIL but exited 0**, because they had been appended below the `if FAILED:` block.
`apps/web/src/viewer/app.ts` carries a named exemption — its 2,571/2,570 gap is documented in the
file as deliberate slack, and calling it a defect (as a draft of this entry did) would have meant
falsifying a slice's measurement to satisfy a gate.

Pin 1,131 → 1,015. Four methods left under the banner, 126 above it and now counted.

Twenty-fifth follow-on on the same version: **RUFF-SCOPE** — *the lint was real; the scope was the
fiction*.

`ci.yml` ran `cd services/api && ruff check src/ ../data/src/`. That is two source trees. The
repository tracks **1,338 `.py` files**; those two trees hold 612. **The other 726 were never linted
at all** — the entire backend test suite (672), every alembic revision (27), the repo scripts, the
pyRevit bridge, the Blender bridge, the plugin example and the Claude hooks. The step exited 0 and
printed *"All checks passed!"* on every push, which is exactly what made it invisible.

The command is now `cd services/api && ruff check ../..` — one path, the whole repository, no list of
directories to fall out of date. The `cd` is load-bearing: `services/api/ruff.toml` is the only ruff
config in the tree, and ruff resolves it *and its `extend-exclude` paths* from the working directory.
Running from the root with `--config services/api/ruff.toml` finds the config but resolves the
excludes against the wrong root, which silently un-excludes all five vendored trees — measured at 161
findings in code we copy verbatim and must not edit.

**230 findings, now zero.** 166 auto-fixed (import ordering, unused imports, f-strings), 40 more with
`--unsafe-fixes` reviewed hunk by hunk, and the last six hand-written. The substantive ones: **five
`assert False`** (B011), one of them guarding path-traversal rejection in `test_security.py`. Nothing
here runs `python -O`, so those were **latent, not live** — but they are precisely what ruff exists to
catch, and it had never been asked.

### Widening the scope broke something, and only reading the diff caught it

`--fix` over the new scope stripped `# -*- coding: utf-8 -*-` from four files under
`integrations/pyrevit/` — three of which contain non-ASCII source. That tree runs **inside Revit on
pyRevit's IronPython 2.7 engine** (`massing_api.py` says so in its first docstring line and proves it
by try/excepting `urllib.request` against `urllib2`). Python 2 defaults to ASCII source encoding, so
removing that line is `SyntaxError: Non-ASCII character` **at import** — the Revit bridge would not
load, and no CI here runs IronPython to notice.

`target-version` is a single global setting and cannot be narrowed per directory, so `ruff.toml` now
carries a `per-file-ignores` entry disabling `UP` for that tree, with the reason written next to it.
`F`, `E9`, `B` and `C4` stay on there — all four are 2.7-compatible findings worth catching.
**Scope and rule set are different questions, and widening one can break the other.**

### The gate reads the workflow rather than restating it

`services/api/test_ruff_scope.py` asserts every tracked `.py` is either in ruff's file set or under
one of five explicitly named vendored prefixes. It gets that file set by **parsing the `ruff check`
line out of `ci.yml`** and running `--show-files` on it — because a scope gate that measures a command
nobody runs is the same bug one level up. Narrow the CI command and the gate goes red; it cannot drift
from CI, because it reads CI. Each vendored prefix must also still match a tracked file, so a renamed
tree cannot quietly take a carve-out with it.

Mutation-checked: CI narrowed back to `src/ ../data/src/` → exit 1 naming 726 unlinted files; a vendor
prefix renamed → exit 1 naming the stale entry. Restored → exit 0. *Read the exit code directly, not
through a pipe.*

#### The first version of that gate was bypassable, and CodeRabbit found it

It used `re.search` over `ci.yml` — which returns the **first** match. Add a harmless earlier line
(`ruff check ../.. --show-files`), narrow the real one below it, and the gate measures the decoy and
passes while the enforcing lint is back to two directories. I had asked for review on exactly this
question and the answer was yes.

The extraction now parses **every** workflow with PyYAML, collects **every** `run:` step mentioning
`ruff check`, and requires **exactly one** — two is ambiguous, and ambiguity resolved by picking one
is how the bypass worked. A step that cannot fail the build is rejected outright: `--exit-zero`,
`--show-files`, `--statistics`, `--show-settings`, a trailing `|| true`, or `continue-on-error` on
either the step or its job. Five mutations, all red, restored green: decoy-then-narrow · `--exit-zero`
· `|| true` · `continue-on-error` · narrowed single invocation.

*A gate derived from a config is only as good as its derivation. "Parses the workflow" sounded like a
guarantee and was a substring search.*

#### And the same hole exists one directory over, in `test_declared_imports.py`

That gate walks `services/api/src` and `services/data/src` only — so an import in a gate sitting in
`services/api/` itself, which is where all ~30 of them live, is invisible to it. Demonstrated rather
than argued: `test_ruff_scope.py` added `import yaml`; pyyaml was declared in neither
`requirements.in` nor `requirements-dev.txt`, reached the lock only `# via` fastapi/uvicorn/pyHanko/
bandit/starlette/markdown-it-py, and the gate stayed green. pyyaml is now declared explicitly in
`requirements-dev.txt` as a point fix; **the class is open** and recorded in `docs/roadmap.md`.

`requirements-dev.txt`'s `ruff>=0.16.3` comment also said the floor had been validated "against the
exact scope ci.yml lints, `src/ ../data/src/`". That scope is now the whole tree — so the validation
behind that pin covered less than half of what a future bump touches. Corrected in place, pointing at
the gate rather than restating a number.

Twenty-sixth follow-on on the same version: **SCALE-SEAM (88)** — *the first slice out of the 126 that
were never in any map*.

Nine methods out of `client.ts` (`1,015 → 953`) into a new `apps/web/src/api/operations.ts`.

What they answer together: **the building is built and running.** Three halves of one question — is it
being MAINTAINED (`cmmsGeneratePm`, `cmmsKpis`: PM work orders, compliance, MTTR), what is it
CONSUMING (`energyActual`, `energyBenchmarkStatus`, `esgSummary`: metered EUI, GHG from actuals, water,
POE actual-vs-design), and what CONDITION is it in (`fcaIndex`, `fcaPortfolio`, `reserveStudy`: FCI,
deferred-maintenance backlog, and whether the reserve fund clears the replacement schedule).
`twinReadiness` asks whether the asset data is good enough to operate from at all, which is the
precondition for the other three.

**Checked against the backend rather than assumed:** all nine are served by
`services/api/src/aec_api/routers/operations.py`, whose own docstring names the same cluster. That is
corroboration from a source this extraction did not write — the opposite of the self-authored list
(87) was about.

### Three did not come, and the words say otherwise on every one

**`lifecycle` / `lifecycleSeed` are not asset lifecycle.** Their banner reads *"design lifecycle
(RIBA/AIA phases + itemized soft costs)"* and the payload is `design_fee_pct`, `deliverables`,
`iso_status`, `soft_costs` — design stage gates and what the design costs, years before anything
operates. **Fourth shared-word trap in this sequence**, after entitlements (land-use vs licence), view
(grid filter vs 3D selection) and now carbon.

**`projectCarbon` is EMBODIED carbon** — what building it emits, a design-phase estimate. The GHG in
`esgSummary` comes from metered utility data. Same molecule, opposite ends of the asset's life.

**`camReconciliation` shared `reserveStudy`'s banner AND its backend router, and still stayed.** It
reconciles budget against actual operating expense, then allocates the recoverable pool **across
tenants** by share and returns `balance_due` per suite: a lease-revenue answer, not a building-condition
one. It waits for a rent-roll slice with `rentRollScrub`, `netEffectiveRent` and `normalizeT12`. Moving
it along to empty a banner would have been the route-and-neighbour reasoning this sequence keeps
rejecting — and the banner it was left under is **rewritten** rather than left naming a method that has
gone.

### The banner (87) wrote cited a method this slice moved

The STAYING banner listed `esgSummary` among its examples of work still above the line. (88) moved it —
so a banner offering evidence of what is *unfinished* was naming something finished, nine days'
equivalent of drift in about two hours. Corrected to 117, re-pointed at `camReconciliation`, and it now
says to **re-derive the number and the names from the file rather than read them there**, with the count
itself asserted by `services/api/test_roadmap_status.py`.

*The instance is small and the class is the one this whole sequence is about: every example list in a
comment is a claim with a shelf life.*

Pin 1,015 → 953. **117 above the banner, and still no map for them** — this was one cluster read out of
the file, not a plan for the rest.

Twenty-seventh follow-on on the same version: **DECLARED-SCOPE** — *the same hole, one directory
over, and it was hiding a real one*.

`test_declared_imports.py` exists because `httpx` was declared in no requirements file and reached the
lock only `# via anthropic`, so an SDK bump would have deleted a package two shipped modules import.
It walked `services/api/src` and `services/data/src` — **and every one of the ~30 gate files lives in
`services/api/` itself, outside that walk.** RUFF-SCOPE's defect exactly, in the checker written to
catch this class: *the check was real, its reach was the fiction.*

**Widening it found one true instance immediately.** `test_saml.py` does `from lxml import etree` at
module scope. `lxml` is declared in neither requirements file and arrives in the lock only `# via`
pyHanko / signxml / python-docx. signxml's own pin is `lxml<7,>=5.2.1`, so a signxml release that
changed XML libraries would remove a package this suite imports directly — and nothing would go red
until the SAML tests hit an ImportError. Undeclared for as long as `test_saml.py` has existed. Now in
`requirements-dev.txt`, with the provenance written next to it.

### Two scopes, because a dev pin does not ship

A gate may import from `requirements.in` **or** `requirements-dev.txt`; a shipped module may import
only from `requirements.in`, because that is what compiles into the runtime image. A runtime import
backed solely by a dev pin passes CI and `ImportError`s in production. Proven rather than asserted: a
module-scope `import yaml` added to `src/aec_api/__init__.py` **fails** (`yaml` is a dev-only pin),
while the same import in `test_ruff_scope.py` passes.

### The widening's own first output was five false positives

`run_tests`, `mcp_server`, `vendor_drift`, `massing_api`, `massing_export` all reported as *"not
installed"*. None is a package: they are sibling `.py` files, plus the pyRevit bridge library that
`test_revit_bridge.py` puts on `sys.path`. The first-party set was derived from `src/` package
**directories**, which cannot see a module that is a bare file. Now enumerated from the importable
directories — scoped to those, deliberately, since a repository-wide basename sweep would forgive a
real third-party import that happened to share a name with one of our files, and forgiving is the
failure this test exists to prevent.

*A widened scope's first run is data, not a verdict.* Five of the six findings were the gate's fault;
the sixth had been true for months.

Mutation-checked: lxml undeclared → exit 1 · gate dirs pointed at an empty path → exit 1 on the
vacuity guard · a dev-only import in a shipped module → exit 1. Restored → exit 0.

### And the split had reintroduced its own defect — CodeRabbit found it

The first version put **every** direct `.py` under `services/api` in the DEV scope. Two of those files
**ship**: `desktop_entry.py` is the executable in `desktop.spec` and `sidecar.spec`, and
`seed_demo.py` is `COPY`ed into the runtime image by `Dockerfile` and run by `docker-compose.yml`'s
seed profile. A dev-only import in either would have passed this gate and failed in the packaged
artifact — **exactly the failure the two-scope split exists to prevent**, reintroduced by assuming
"directly under `services/api`" means "test".

Fixed by DERIVING the shipped set from the packaging manifests themselves — the specs, both
Dockerfiles and the compose file — rather than naming the two files. Naming them would fix today and
leave the next packaged entry point to land in the loose bucket silently, which is the same
"a hand-list goes stale" argument as `FIRST_PARTY` and `LOCAL_MODULES`. An independent sweep of every
direct `.py` against those manifests returns exactly those two, so the derivation and the finding
agree.

A vacuity guard comes with it: if the manifests ever stop naming any direct `.py`, the gate fails
rather than quietly moving every entry point into the looser scope.

Mutation-checked: a dev-only import in `desktop_entry.py` → **exit 1 as `[shipped]`** (it passed as
`[gate]` before the fix) · the same import in a genuine test file → **exit 0** · `PACKAGING` pointed
at files naming no `.py` → **exit 1** on the vacuity guard.

*Three scope defects in one day — the linter's, this gate's, and then this gate's own fix — and the
third was introduced while correcting the second. **Widening a scope is itself a scoping decision,
and it deserves the same suspicion as the one it replaces.***

Twenty-eighth follow-on on the same version: **SCALE-SEAM (89)** — *two clusters, and a banner that
named two of its four*.

Eight methods out of `client.ts` (`953 → 906`) into two new mixins.

**`apps/web/src/api/resilience.ts` — what could the environment do to this project?** One question
asked of three things: the SITE (`resilienceFlood` — SFHA, design flood elevation, which assets sit
below it), the CIVIL DESIGN (`resilienceStormwater` — runoff coefficient, peak CFS, detention volume),
and the PROGRAMME (`resilienceWeather` — weather-sensitive activities by trade, open site risks, delay
days). `resilienceClimateRisk` is the composite over all three.

*The tension is named rather than smoothed over*, and then the reason for resolving it was narrowed
after checking the source. `resilienceWeather` reads activities with trade, start, finish and percent
complete — `schedule.ts` vocabulary, and a subject-matter split would send it there.

**The first draft of that argument claimed a dependency the backend does not support.**
`resilience.climate_risk()` does score `high_severity_open`, `open_risk_count` and
`weather_delay_days` alongside the flood and runoff figures — but it reaches them through
`_weather_exposure()`, commented in the source as *"site-risk + delay only — skips the
schedule_activity scan"*. The composite never reads `weather_sensitive_activities`. So the rollup
binds the half of that method which is **not** schedule-shaped, and the schedule-shaped half has no
claim from it: a shared input, not a call dependency, and weaker than "separating an input from its
rollup" implies.

The placement stands on a **boundary rule** instead: `schedule.ts` holds programme-state queries, it
is not the home of every query that happens to read a `schedule_activity` record. That reason was
CodeRabbit's, arrived at independently while confirming the narrowing. *An argument that reads well
is not the same as one that holds, and a header is where the difference gets inherited.*

**`apps/web/src/api/responsibility.ts` — who is accountable for what?** The backend agrees exactly:
`aec_api/routers/responsibility.py` holds those four routes **and nothing else**. A 1:1 router
correspondence is the strongest corroboration available for a grouping, and it was checked rather
than assumed.

*It did NOT go to `modules.ts`, and the router's own docstring is why it nearly did:* "Rows themselves
are ordinary `responsibility` module records, so create/edit/delete of individual cells goes through
the generic /modules CRUD." Same storage, and that CRUD lives in `modules.ts`. **Storage is a HOW.**
A caller reaching for `modules.ts` wants records of a module type; a caller reaching for these wants
to know who is Accountable for a task. "They are all module records" is (85)'s "they are all multipart
uploads" one layer down.

Four methods is a small file, and that is fine — `risk.ts`, `dealMemory.ts` and `assetRights.ts` hold
two each. Sizing a mixin to feel substantial is not a reason to file a method where it does not answer.

### The banner over-claimed, for the sixth time in this sequence

`// --- climate & water resilience (flood + stormwater) ---` sat above **four** methods and named
**two**. Weather and the climate-risk composite were filed at whatever header was nearest — the same
defect as ⓽'s "AI drafting" running on into sheet extraction, (81)'s `ifcClassify` under a G704
turnover header, and (82)'s RACI banner covering thirteen methods while describing four.

`ResponsibilityMatrix` left `client.ts`'s type imports with the methods; it had no other reader.

Pin 953 → 906. **109 above the banner, and still no map.** The banner's seven example names were
checked against the file this time and none had moved — *that check is the point, not the result.*

Twenty-ninth follow-on on the same version: **SCALE-SEAM (90)** — *the gate caught what my own check
was built to miss*.

Eight methods out of `client.ts` (`906 → 866`) into a new `apps/web/src/api/clientPortal.ts`.

**What they answer: how does someone with no account see this project, and answer back?** The owner's
half mints, lists and revokes share tokens and reads what came back; the recipient's half is the
token-authenticated public surface — the no-login page and digest URLs, and posting a comment or an
approve/acknowledge/decline. **The token is the seam**: minted on one side, IS the credential on the
other, and revoking it closes both. Splitting owner-side from recipient-side would put a capability
and its only means of exercise in different files.

`aec_api/routers/client_portal.py` groups the same set — 8 of its 9 routes, checked. The ninth,
`GET /shared/{token}/model.frag`, has no client method **by design**: the server-rendered share page
fetches it, not this SPA.

### The extraction script had a real bug, and a test found it rather than I did

Its brace counter only terminated when `j > i`, so a **one-line method** consumed one line too many
and swallowed the *next* method's doc comment. `sharedPageUrl` and `sharedDigestUrl` are one-liners:
the first draft dragged `spaceUtilBenchmarks`'s SPACE-UTIL doc out of `client.ts` and duplicated
`sharedPageUrl`'s. `apps/web/src/api/docComments.test.ts` went red, the extraction was reverted, the
counter fixed to terminate on the method line itself, and the slice redone.

Two things about that are worth keeping:

**I wrote an orphan check of my own and it passed.** It treated a following comment as an acceptable
neighbour — which is *precisely the case that defines the defect*. The real gate asserts that a line
ending `*/` is not followed by a line starting `/**`, and that is the whole difference between the two.
*A check you write while looking at the code you just wrote inherits its blind spot.*

**Seven of these eight carry `/** */` docs**, which the walk-back did not handle either until this
slice; (88) and (89) survived only because the methods they moved used `//` banners. That was luck,
not care, and the tool is fixed for both now.

### Found on the way, deliberately not fixed here

That ninth route serves geometry only to a token minted with `show_model` — an opt-in the backend
treats as strictly independent of `show_payments` (*"granting one never implies the other"*).
**`createShareToken` never sends it**, and the row type `shareTokens` returns has no `show_model`
field. Every token this product mints has it false, so `/shared/{token}/model.frag` always 404s and
the public 3D viewer is dark from the UI's side. Left alone because an extraction slice's claim is
that no behaviour changed, and adding a parameter falsifies it; recorded in the mixin header at the
method, where the next reader of that code will find it.

Pin 906 → 867. **101 above the banner, still no map.**

### And RUFF-SCOPE left residue in two documents that tell contributors what to run

Review flagged that this PR's body ignored `.github/pull_request_template.md`. It does — and reading
that template found something worse than a formatting miss. **Two of its checklist lines were wrong,
and one was wrong because of my own merged work:**

- *"Backend: `cd services/api && python -m ruff check src/ ../data/src/` clean"* — the narrow scope
  RUFF-SCOPE replaced on 2026-09-03. The template was still telling every contributor to run the
  command that linted 612 of 1,338 files while printing "All checks passed!".
- *"Web: … clean (Node 20)"* — both manifests declare `"engines": {"node": ">=24"}` and `ci.yml` pins
  `node-version: "24"`.

`CONTRIBUTING.md` carried the same ruff command under the heading *"Run the gates locally — CI runs
the same"*, which my own change had made false. Both corrected.

**A checklist that names a command CI no longer runs is worse than no checklist, because it gets
followed.** So the template is now in `test_claude_md_gates.py`'s scanned set — it is a checklist of
checks, which is that gate's own stated trigger for inclusion. Mutation-checked: a renamed citation
→ exit 1; its citations stripped → exit 1 on the per-doc ratchet.

`CONTRIBUTING.md` is deliberately **not** added: its commands live in bash fences rather than
backticks, so it contributes zero citations, and a doc that matches nothing passes vacuously — the
failure that file's own header calls worse than no gate at all.

*Fixing a scope leaves residue in every document that described the old one, and the ruff line had
been stale in two of them for a day without anything noticing.*

Thirtieth follow-on on the same version: **SCALE-SEAM (91)** — *three corroborations that agreed, and
a forecast that was tested instead of executed*.

Thirteen methods out of `client.ts` (`867 → 746`) into a new `apps/web/src/api/creDeal.ts`, lifted as
one contiguous run. No behaviour change: a mixin, so every call site resolves unchanged.

**What they answer: should we transact on this income property, and on what terms?** Verify the
seller's numbers (`normalizeT12` — the tie-out is a gate, not a report; `rentRollScrub` — a check
without its inputs reports not-run, never a pass; `netEffectiveRent`; `tieredComps` — a band reports
the weakest tier it rests on; `competitiveSupply`), decide (`holdSell`, `decisionGate`), and set the
terms (`clausePlaybook` + `reviewContractClauses`, `loanCovenants`, `dealAuthority`, plus the two
save halves). Diligence, decision, terms — one transaction.

### Three signals, derived independently, and they agreed

1. **The source marks them itself.** Ten `CRE-` codes sit in these doc comments — `CRE-HOLDSELL`,
   `CRE-CLAUSE` (twice), `CRE-COVENANT`, `CRE-AUTHORITY`, `CRE-SUPPLY`, `CRE-DECISION-GATE`,
   `CRE-COMP-TIER`, `CRE-T12`, `CRE-RRSCRUB`, `CRE-NER`. Grepped across the whole of `apps/web/src`:
   those eleven occurrences are the **only** ones in the web tree, and every one was in `client.ts`.
2. **A 1:1 router match.** Every route these thirteen call — eleven distinct paths, since the
   playbook and the authority table each have a read and a write half on one path — is served by
   `services/api/src/aec_api/routers/realestate.py` and by no other router; its ten `(R20)`
   docstrings name the same ten codes. Checked by pairing each `@router.` line with the `def`
   beneath it, not by reading the file top to bottom.
3. **One question runs through all thirteen.**

*A marker alone would not have been enough.* This sequence has been trapped four times by a shared
word — entitlements, view, carbon, lifecycle — so `CRE-` counts as **one vote of three**, and the
router match is what carries the weight.

### A fourth corroboration, found by accident and recorded as such

The backend suite names this family too, and it partitions the same thirteen: `test_cre_deal_desk`
(comps/tiered, rent-roll/scrub, t12/normalize), `test_cre_governance` (deal-room/authority,
decision-gate, loan/covenants, supply/competitive), `test_cre_tier3` (contracts/playbook,
contracts/review, hold-sell) and `test_net_effective` (rent-roll/net-effective) — all eleven paths,
and no `test_cre_*` file **asserts on** a route outside the set. *Caveats, because this arrived late
and is the kind of evidence it is tempting to round up:* `test_cre_tier3` reaches three routes
outside it — `POST /proforma/scenarios`, `POST /proforma/scenarios/{sid}/review` and
`GET /projects/{pid}/reports/ic_memo.pdf` — and `test_net_effective` sets up through `/rent-roll`
and `/modules/lease`. A test may use a neighbour as a fixture without that neighbour joining the
cluster, but the count has to be right: **the first draft named one of those three and truncated its
path**, which review of #408 caught. The claim is true of asserted routes, not of fixtures — weaker
than the first draft, and the one the evidence supports.

It was noticed only because those two test names scrolled past in the suite output **after the slice
was committed**. Test-file names are a grouping somebody else authored, which is precisely the kind
of source (87) argued to prefer — *and it was not on the list of places this slice thought to look.*
Recorded as a fourth signal rather than folded into the three, so the derivation stays honest about
when each piece arrived.

### The boundary that decides `rent-roll`

`apps/web/src/api/proforma.ts` already holds `GET /projects/{pid}/rent-roll`, and two of these sit
directly beneath it on `/rent-roll/scrub` and `/rent-roll/net-effective`. A route-prefix split takes
all three; the boundary is what they answer, and **the backend states it**. The plain rent roll
carries no `CRE-` code and no `(R20)`, and its own docstring calls it the operating rent roll "from
the `lease` module (**the hold phase**)" — while these two POST a body of figures somebody else
supplied and report whether they survive scrutiny. *What are we earning* and *is their number true*
are different questions that happen to share a prefix.

### A forecast from (88) was checked, and it did not hold

(88) left `camReconciliation` in `client.ts` with a note saying it "goes with `rentRollScrub`,
`netEffectiveRent` and `normalizeT12`, still below, **when a rent-roll slice takes them**". This is
that slice. It took all three and **left `camReconciliation` where it was**, because every signal
points the other way: no `CRE-` code, no `(R20)`, and `/projects/{pid}/cam/reconciliation` is served
by `operations.py`, not `realestate.py`. Reading it settles it — a CAM true-up bills a **completed
operating year** to sitting tenants, which is running the asset, not buying it.

**A placement forecast written by one slice is a hypothesis for the next slice to test, not an
instruction to carry out.** Phrased as a plan — *"it goes with X when Y"* — it reads as settled and
invites the next reader to execute it without re-deriving anything, which is how a guess becomes a
fact in a file nobody re-checks. The note at that method now records what was measured, and the
roadmap entry that repeated the forecast is corrected too.

### The banner cited a departed method for the second time

`rentRollScrub` was in the STAYING banner's example list until this slice moved it — the same defect
(88) caught with `esgSummary`: a banner offering, as evidence of unfinished work, a method that has
left. (89) audited those seven names and found none had moved, *which is why they survived to be
wrong now — a list that passes one audit is not thereby safe for the next slice.* The roadmap's own
`client.ts is 953 lines` was three slices stale for the same reason and is corrected to 746.

### The review also found the no-behaviour-change claim resting on a gate with 37 of slack

This entry said `apps/web/src/api/surface.test.ts` proves every call site still resolves. For these
thirteen it did not. That file spot-checks a name list none of them was on, plus a floor of **751**
on the total client surface — and the surface **measures 788**. Losing one of the thirteen leaves
787 and passes; losing the whole mixin leaves 775 and passes. *That is exactly the slack
`surface.test.ts`'s own comment at the 696 floor predicted would accumulate as endpoints are added,
and it is the first time it has actually misled a reader* — a review of #408 stated the opposite,
that "losing any one reduces the count below 751", which is off by 37.

All thirteen are now named in that spot-check, on the same reasoning the file already gives for
naming the twenty auth methods. Mutation-checked both ways: renaming `holdSell` fails with
*"holdSell() vanished — a call site is now broken"*; restoring it passes. **A floor that new work
keeps clearing stops being a ratchet without ever going red** — so the fix is to name the group, not
to raise the floor.

Pin 867 → 746. **88 above the banner, still no map.**

Thirty-first follow-on on the same version: **SCALE-SEAM (92)** — *the marker that bounds a set, and
the one that does not*.

Four methods out of `client.ts` (`746 → 733`) into a new `apps/web/src/api/annotate.ts`:
`addAnnotation`, `addDimension`, `addRevisionCloud`, `addTag`. **What they answer: put a note, a
dimension, a cloud or a tag ON the model** — all four author real `IfcAnnotation` entities at world
`[E,N]` through `editIfc`.

### The set is bounded by two sources somebody else authored

1. **`services/api/src/aec_api/authoring_matrix.py`** — the curated recipe→category map behind the
   public authoring-coverage endpoint, maintained for a different purpose than this extraction. Its
   `annotate` category holds **exactly these four** of the map's 99 recipes across 15 categories. A
   complete category: nothing left behind, nothing pulled in.
2. **`services/api/test_annotation.py`** exercises all four annotation recipes, and no other recipe
   as its *subject* — it calls `add_wall` and `add_column` once each as fixtures, to give `add_tag` a
   host element to label.

*The qualification in (2) was missing from the first draft, which said "and no others" — and it is the
**second consecutive slice** to make that error: (91) claimed no `test_cre_*` file reached outside its
set while `test_cre_tier3` reached three routes as fixtures. Both times the claim counted what a test
**targets** and ignored what it **sets up**. A "nothing else" claim about a test has to say whether it
means assertions or every call the file makes; those are different sets, and the smaller one is the
one you notice.*

A third corroboration: `apps/web/src/viewer/tools/annotationSection.ts`, the UI these serve, makes
exactly four `api.*` calls and they are these four.

### The `UX-2` marker does NOT bound the set, and the distinction is the point

(91) had a marker that did: `CRE-` occurred only in `client.ts`, so it drew the boundary itself.
`UX-2` is a different animal — 12 occurrences across three files (`client.ts`, `viewer/app.ts`,
`viewer/tools/annotationSection.ts`). It marks a **feature workstream** spanning UI and client, so it
corroborates *purpose* and is silent on *membership*. **Two markers, two strengths.** Treating every
prefix as a set boundary is how a cluster acquires the wrong members, and (91)'s success with `CRE-`
is exactly what would make that mistake feel justified here.

### Not `markup.ts`, and not `authoring.ts`

`markup.ts` is **2D sheet markup** — a pin at a sheet's `(x, y)` carrying a note, stored as a markup
record, promotable to an RFI. These author **model content** that travels with the IFC. *A comment
layer over a drawing and drawing content authored into the model are different questions sharing the
word "annotation".*

`authoring.ts` is the harder call: it **defines** `editIfc`, holds seven recipes, and its header
claims "the endpoints that WRITE to the model rather than read from it" — which would take all 24
recipes still in `client.ts`. **A description broad enough to take everything is not a seam.** Its
demonstrated practice is far narrower than its sentence: it declined detailing at ⓼, property-override
layers at ㊳ (*"those compose properties, they do not write recipes"*), and groups at ⓻. `mep.ts` had
already settled the principle — its methods *"use `editIfc` (`/edit`) and stay"* — and the matrix
proves it, splitting those 24 recipes across **nine** categories. `editIfc` cannot be the seam.

### A technical finding that probably explains the whole backlog

**This is the first mixin to call `editIfc` without declaring it, and that is unlikely to be a
coincidence.** (`authoring.ts` calls it seven times, but it *defines* it, so it never needed a base
type that promises it — which is why eleven slices could pass these recipes without hitting this.)
`editIfc` is declared on the `Authoring` mixin rather than on `HttpCore`, so a mixin typed
`Ctor<HttpCore>` cannot see it: the extraction does not compile, and nothing says why. It is the same
shape `authoring.ts` records blocking the SSE methods — *"a mixin cannot see a sibling's private
member"*. That is a plausible reason all 24 recipes were still sitting in `client.ts` after eleven
slices went past them.

`annotate.ts` declares the requirement in its type (`NeedsEditIfc`) and must be composed outside
`withAuthoring`. Mutation-checked: composing it *inside* fails with `TS2345` naming `editIfc`, rather
than failing at runtime with `undefined is not a function`. Moving `editIfc` down into `HttpCore`
would unblock the other 20 recipes; that changes a file every mixin depends on and is left for
whichever slice takes the next recipe cluster.

> **(93) tested that last sentence and it does not hold.** `httpCore.ts` says it owns "the base URL,
> the bearer token, and the low-level fetch helpers", keeping "transport concerns separate from the
> endpoint surface" — and all eight of its methods are transport. `editIfc` is a *domain* endpoint.
> Moving it there contradicts that file's stated purpose and the layering SCALE-SEAM exists to build.
> The answer is the `NeedsEditIfc` pattern, now shared from `types.ts`. *Written as a plan one slice
> after (91) recorded that a placement forecast is a hypothesis to test — and phrasing it as a plan
> is precisely what makes it read as settled.*

All four are named in `surface.test.ts`, which (91) established is necessary rather than optional.

Pin 746 → 733. **84 above the banner, still no map.**

Thirty-second follow-on on the same version: **SCALE-SEAM (93)** — *finishing ⑲, and a note that
recorded a symptom without diagnosing it*.

Two methods out of `client.ts` (`733 → 731`) into the existing `apps/web/src/api/mep.ts`:
`connectMep` and `addMepFitting`. No new mixin.

### ⑲ already claimed them, and could not take them

`mep.ts` has said since SCALE-SEAM ⑲ that *"`connectMep` / `addMepFitting` call `editIfc` (`/edit`)
and stay."* That reads as a placement decision. It was a **compiler error**: `editIfc` is declared on
the `Authoring` mixin rather than on `HttpCore`, so a mixin typed `Ctor<HttpCore>` cannot see it and
the extraction does not compile. (92) diagnosed that; (93) applies it, and `mep.ts` now declares
`NeedsEditIfc` and composes outside `withAuthoring`.

**A method left behind for a reason nobody wrote down stays behind indefinitely.** ⑲ recorded what
happened and not why, so eleven slices read it as settled and moved on.

### One contract, not two copies

`NeedsEditIfc` moves from `annotate.ts` into `types.ts`, shared by both mixins. Two hand-copied
signatures are exactly the drift the #409 review had to check by hand — a copy subtly *wider* than
the real `editIfc` typechecks at the mixin and still breaks at a call site. One definition cannot
drift from itself. Mutation-checked: composing `withMep` inside `withAuthoring` fails with `TS2345`.

### The evidence is weaker than (92)'s, and says so

This is **not** a complete `authoring_matrix.py` category — `create-mep` has 11 members and
`edit-mep` 3, of which these are one each. The boundary is *"MEP recipe exposed as a typed client
method"*, which is exactly these two. **Twelve** MEP recipes remain in the matrix (11 `create-mep`
+ 3 `edit-mep`, less these two): **nine** are driven from viewer code through the generic recipe path
in `apps/web/src/viewer/draft/draftCatalog.ts` and `apps/web/src/viewer/tools/mepSection.ts`, and
**three — `add_sprinkler`, `auto_connect_mep`, `set_system_predefined` — are referenced nowhere in
`apps/web/src` at all.** Recorded, not fixed: wiring a capability is not an extraction slice's business.

> **This said "the other nine" until review, and that is the third consecutive slice with one
> defect wearing a third disguise.** Nine was the number I had *enumerated* (the viewer-driven ones);
> twelve is the number that *remain*. (91) claimed no `test_cre_*` file reached outside its set while
> three reached out as fixtures. (92) claimed `test_annotation.py` exercised four recipes "and no
> others" while two more were tag-host fixtures. Each time: **count the members you looked at, then
> phrase the result as the whole population.** A reviewer found all three.
>
> The fix is not resolving to be more careful. It is to **derive the complement** — `set(all) -
> set(moved)` — and only then describe what is in it. Every one of these would have been caught by
> computing the remainder instead of listing the examples. `test_mep_systems.py` covers both **among** other MEP recipes —
it corroborates the family and does not bound the set — and `test_guards.py` is cross-cutting.
*Spelled out because the "no others" overstatement was made in each of the two preceding slices.*

*`addMepFitting` is callerless and stays on `apps/web/src/api/clientCallers.test.ts`'s allowlist:
moving a method does not change its called-ness. It is still named in `surface.test.ts`, because that
list is about the surface rather than the call sites — a method with no screen behind it can still
vanish in an extraction, and the count would not notice.*

Pin 733 → 731. **82 above the banner, still no map.**

Thirty-third follow-on on the same version: **SCALE-SEAM (94)** — *the two methods ㊻ could not see,
and a complete category that is not one question*.

Two methods out of `client.ts` (`731 → 727`) into the existing `apps/web/src/api/model.ts`:
`verifyAsbuilt` and `recordAsbuiltDimension`. No new mixin.

### ㊻ stated this question and left two of its members behind

`model.ts` has said since SCALE-SEAM ㊻ that it holds *"field-install verification — **is this
element installed as designed?**"* — coverage, status write, deviation log. `verifyAsbuilt` stamps
`Massing_AsBuilt` (the LOD-500 reliability layer) and `recordAsbuiltDimension` records a
field-verified dimension with its variance against design. Both answer exactly that question, and
**neither is named in ㊻'s header.**

**Why it missed them: ㊻ split on the `/verification/*` route prefix, and these two go through
`editIfc`, so they carry no route to be found by.** A route-prefix split cannot see a recipe-based
sibling of the same question. They were also unmovable at the time, for the reason (92) diagnosed —
`editIfc` lives on the `Authoring` mixin, so a mixin typed `Ctor<HttpCore>` does not compile. That
makes **three** slices now found to have left work behind for that one cause, after ⑲'s MEP pair.

### The matrix argued for a third method, and it was declined

`authoring_matrix.py`'s `lifecycle` category is exactly these two plus `set_phase` — a **complete
category**, which is the signal that decided (92)'s annotate slice. `setPhase` stays anyway:

- it answers a different question — tag a construction phase (new / existing / demolish /
  temporary), which is element state in the build sequence, not install-versus-design; and
- **its read half `phasing()` is still in `client.ts`.** Taking a writer and leaving its reader is
  the split (87) had to undo.

*A complete category is one vote, not a verdict — and "lifecycle" is a word (88) already caught
misleading once, in a different way.*

### Two checks that failed honestly

**The first composition-order check was worthless, and reading its output is the only reason I know
that.** It rebalanced parentheses wrongly and went red with `TS1005` syntax errors — proving nothing
about composition order while looking exactly like a passing mutation test. Redone as an isolated
probe applying `withModel` to bare `HttpCore`, which fails `TS2345` naming `NeedsEditIfc`.

**And the ratchet caught the banner.** The first draft added 9 lines of prose to `client.ts` while
the extraction removed 8, netting **+1** — an extraction slice that grows the file has failed its
purpose. The note is now three lines and the reasoning lives once, in `model.ts`'s header, instead
of twice.

### Review of #411 found the overstatement I had asked it to look for

I scoped the claim carefully in the PR description — *"two known missed members, not necessarily all
members"* — and then wrote **"finishes that question"** in `model.ts` and **"completing its
verification question"** in `surface.test.ts`. The reviewer caught the contradiction.

**Hedging in the review request while the artifact overstates is not scoping.** It puts the caveat
where a reviewer sees it and the overstatement where every later reader will, which is worse than a
plain overstatement because it looks like discipline. Fourth instance of one defect across four
slices, and the first where the correct wording existed and simply did not reach the code.

Both now say *two members of ㊻'s question that it did not name*, which is what the evidence supports.

### The composition-order constraint is now a test rather than a claim

`apps/web/src/api/compositionOrder.test.ts` asserts, with `@ts-expect-error`, that `withAnnotate`,
`withMep` and `withModel` all reject a bare `HttpCore` base — the `NeedsEditIfc` requirement stated
positively and checked by `npm run typecheck`, naming the mixin when it breaks.

The review is what forced it: I had reported the constraint as "mutation-checked", but the check was
a scratch file I deleted, so neither the reviewer nor anyone after me could verify it. **A
verification that leaves no artifact is a claim, not a check.** Mutation-checked in turn — relaxing
`withMep` to `Ctor<any>` fails with `TS2578: Unused '@ts-expect-error' directive` naming the line.

*Also corrected: the reviewer described `phasing()`/`setPhase()` as a direct read/write pair in
`modelStatePanels.ts`. `phasing()` is read there and the panel colours by `Massing_Phasing.Status`,
but `setPhase` is that panel's **unwired** writer, on `clientCallers.test.ts`'s UNCALLED allowlist.
Reader and unwired writer on one panel — still the reason not to separate them, stated accurately.*

Pin 731 → 727. **80 above the banner, still no map.**

Fortieth follow-on on the same version: **R22-ENTITLEMENT ⑤** — *an agency review comment becomes an
RFI somebody owns*.

**The gap.** `RecordComment` had **no outward link of any kind**. An agency's comment on an
`entitlement` or `permit` was a text blob at the end of a thread: readable, and impossible to assign,
track or close. ④ had already made comments survive a revision — that is the *inbound* half of
"round-tripping"; this is the outbound half the ring entry still listed as remaining.

`POST /projects/{pid}/modules/{key}/{rid}/comments/{cid}/promote` mints a Topic carrying the comment
text, the source record's ref and its `element_guids`, and writes a back-link on the comment.

### The back-link is the idempotency

A second promote **409s** instead of minting a duplicate RFI — the failure mode a promote button
produces on every double-click. `services/api/test_comment_promote.py` holds it, and both
load-bearing assertions were **mutation-checked**: removing the 409 guard makes one comment mint two
RFIs, and the failure output shows both `comment.promote` activity entries side by side; removing the
back-link write drops `topic_id` from the comment.

Follows `promote_markup` (`POST …/drawings/markup/{mid}/promote`) rather than inventing a second
idiom — same shape: mint, carry provenance, link back, 409, audit.

### Reachable, not merely built

The control renders beside the comment in `apps/web/src/portal/register/recordComments.ts` and is
replaced by "→ RFI raised" once promoted, because a button whose only remaining outcome is a 409 is
worse than no button.

Adding it turned `register.ts`'s extraction ratchet red, and **the remedy is the one that file
states: extraction, never headroom.** The comment thread + composer + the new control came out to
`portal/register/recordComments.ts` (`2,516 → 2,505`, pin lowered with it). The block is a genuine
leaf — it touches the record's comments, the API and a reload callback and nothing else on the class
— and the directory already holds three leaves extracted the same way.

### What the premise-check found, and it is why this slice exists

The entry's "Remaining:" line named **two** things and **contradicted itself on one**: it listed
submittal packages flatly while the ④ note above it said the inbound half had already shipped.
Measured 2026-09-04 — the inbound *view* is real (`…/related` returns `incoming`), but assembling a
package to send is not, because `modules/transmittal/module.json` types **`items` as a textarea and
`to_company` as plain text**. A package's contents are prose no machine can resolve back to the
records it names, and its recipient cannot be the agency an `entitlement` names, since that is free
text too. *That is a schema question — reference fields — not a workflow one, which is why reading
the workflow surface kept reporting it done.* The roadmap now says that instead of the flat line.

Also corrected: the roadmap's argument against picking SCALE-SEAM quoted `client.ts` at **2,837
lines**. It is **642** — the number was copied forward through every slice since, which is the exact
drift the rows beside it document twice.

Thirty-ninth follow-on on the same version: **SCALE-SEAM (100)** — *the element-connection pair, and
a destination named at the strength the evidence supports*.

Two methods out of `client.ts` (`648 → 642`) into the existing `apps/web/src/api/model.ts`:
`elementConnections` and `connectElements`. No new mixin. **What they answer: what is physically
joined to what, and record a joint.**

### The backend names its own writer

The `/element-connections` route docstring reads: *"Author edges with the `connect_elements` recipe
(`POST /edit` with `{guid_a, guid_b}`)."* Reader and writer, one relationship type
(`IfcRelConnectsElements`), both marked B5. That is the (96) shape and it is what carries the pair.

### The destination argument is weaker, and is labelled as such

`model.ts` owns `modelGraphStats` — whose `by_rel` counts the IFC relationship graph **by relation**,
and `IfcRelConnectsElements` is one of those relations — plus `graphNeighbors`, which walks it. So
this pair is one relation of a graph the file already reads, plus its authoring verb.

**That is a specialisation, not an identity.** `modelGraphStats`/`graphNeighbors` are generic
traversal over every `IfcRel*`; these two are one relation with a verb attached. Recorded as the best
available home rather than a derived one — *the pairing is evidenced, the placement is a judgement,
and collapsing the two would be the overstatement this sequence keeps catching.*

### Two candidates rejected on checkable grounds

**`connections.ts` is the trap.** It is *data-source* connections — SQL, ACC, Procore — and shares
nothing with this but the English word. (97) found two version stacks behind one word; this is the
same collision in a **destination** rather than a source, and it is the file a name-based search
would have landed on first.

**`elements.ts`** holds element *attributes* and views — properties, 5D, colouring, QA, costs. A
relationship between two elements is not an attribute of either.

`addBasePlate` and `addShearTab` did **not** come despite sharing `services/data/src/aec_data/connections.py`
with these: a backend module is a HOW, the grouping (89) had to reject, and those two author
*physical* assemblies (plates, bolts) rather than `IfcRelConnectsElements` edges.

### Found while deriving

`add_connection_assembly` (B5, `IfcRelConnectsWithRealizingElements`) has **no client method
anywhere** in `apps/web/src` — a backend recipe with no web exposure, the same class (93) recorded
for three MEP recipes. Noted, not fixed.

`client.ts` is 60 methods above the STAYING banner and 4 below.

Thirty-eighth follow-on on the same version: **SCALE-SEAM (99)** — *the content half of a shelf the
destination's own first line already claimed*.

Three methods out of `client.ts` (`665 → 648`) into the existing `apps/web/src/api/authoring.ts`:
`contentCatalog`, `placeContent`, `importContent`. No new mixin. **What they answer: what pre-made
content can I place, and place it.**

### A role-for-role parallel, read off the signatures

The family shelf was already in `authoring.ts`. The content shelf is the same three roles, with
matching shapes and arities:

| role | family | content |
|---|---|---|
| catalog reader | `familyCatalog()` → `{count, categories: Record<…>}` | `contentCatalog()` → `{count, note, groups: Record<…>}` |
| placer | `placeFamily(pid, family, position)` | `placeContent(pid, category, point, name)` |
| multipart importer | `async importFamilies(pid, file, …)` | `async importContent(pid, file, opts)` |

**A parallel between two method *triples* is structural.** "Both are shelves" would have been a
shared word — the grouping (88) and (89) each had to reject — so the argument is deliberately the
signatures, not the noun.

### The destination's header was wrong until this commit

`authoring.ts` line 1 has read *"the family/content shelf"* while the file held **zero** content
methods; the only other occurrences of the word were an HTTP header and a sentence about IFC *type*
content. The docstring described an intended scope as though it were a fact.

That is the same class as every drift the project instructions warn about, at the smallest possible
scale: **prose asserting an arrangement that nothing checked.** It is recorded as corroboration that
was *false* rather than as evidence — the parallel above is what carries the slice, and a header
that agreed with me would have been worth nothing if I had not checked whether it was true.

`client.ts` is 62 methods above the STAYING banner and 4 below.

Thirty-seventh follow-on on the same version: **SCALE-SEAM (98)** — *detailing carriers, and a
field map that is total over one module but not over the codebase*.

Five methods out of `client.ts` (`687 → 665`) into a new `apps/web/src/api/detailing.ts`:
`elementDetailing`, `classify`, `applyDetailingRules`, `validateDetailing`, `attachDocument`.
**What they answer: what informational carriers are attached to this element, write them, and which
are missing.**

### A 1:1 and total field-to-writer map

The reader's response has exactly two carrier arrays, and `services/data/src/aec_data/detailing.py`
holds exactly two writers, one per array:

| response field | writer | IFC relationship |
|---|---|---|
| `classifications[]` | `classify` | `IfcRelAssociatesClassification` |
| `documents[]` | `attachDocument` | `IfcRelAssociatesDocument` |

`element_detailing` walks `HasAssociations` and branches on precisely those two relationship types —
nothing else contributes a field — so the map comes from the reader's own body rather than from
matching names. The other two methods are those same two writes under automation:
`applyDetailingRules` runs the condition-to-content rule set and writes both carrier kinds, and
`validateDetailing` reports elements a rule applies to that lack the required code.

### Total over the module, not over the codebase

`attachOmDocument` — moved to `model.ts` in (96) — is a purpose-tagged wrapper of the **same**
`detailing.attach_document`, so it also writes `IfcRelAssociatesDocument` and its output lands in
`documents[]`. So *"these are all the writers of this reader's fields"* is **false**. The claim the
evidence supports is narrower and is the one made: the map is 1:1 and total **over `detailing.py`**.
*That overlap was named when `attachOmDocument` moved, which is why it was available to qualify this
slice instead of being discovered by a reviewer.*

### Adjacency agreed with the answer, and is not evidence for it

These five were **contiguous** in `client.ts` (119–145). Unlike (95), where non-contiguity was the
whole argument for grouping by what methods answer, a positional split would have found this set
too. That is worth stating precisely *because* it looks like support: a grouping that happens to
coincide with adjacency is not thereby better evidenced.

Also recorded: **`api.classify()` has no call site.** `viewer/tools/detailingSection.ts` drives the
recipe through the generic `authorAndReload("classify", …)` path, bypassing the typed method.
`api/clientCallers.test.ts` counts it as reached because it matches bare string literals as well as
calls — a looseness that file's own docstring declares deliberate, preferring a higher ceiling to a
false unreachability report. Noted so the next reader of `detailing.ts` does not assume the method
is live.

The new mixin needs `editIfc`, so it declares `NeedsEditIfc` and composes outside `withAuthoring`;
`api/compositionOrder.test.ts` gains a fourth line asserting that. **That assertion was
mutation-checked**: relaxing the constraint to `Ctor<any>` produces `TS2578: Unused '@ts-expect-error'
directive` on exactly the new line, so it fails for the reason claimed rather than merely passing.

`client.ts` is 65 methods above the STAYING banner and 4 below. *The extraction removed 27 lines and
the banner plus import added 5 back — caught by the ratchet, not by me, which is the same way (94)
found its own banner growth.*

Thirty-sixth follow-on on the same version: **SCALE-SEAM (97)** — *the undo stack, and a
destination that looked right and was not*.

Three methods out of `client.ts` (`698 → 687`) into the existing `apps/web/src/api/authoring.ts`:
`editHistory`, `editUndo`, `editRedo`. No new mixin. **What they answer: what has been done to this
model, and can I take it back.**

### `editIfc` is the push they pop

They belong with `editIfc` — already in that mixin — because `authoring.py` records the pre-edit
version on every `/edit` call *"so this edit can be undone"*, `_restore_version` pops that stack,
and `edit_history.state()` reads its depths. One stack; the operation that fills it was already
here.

The types agree: both writers return `{ restored, state: { can_undo, can_redo } }`, and `state` is
`editHistory`'s own return type minus the depths — **the writers hand back the reader's answer.**
That is a type-level relation, not a shared `/edit/` prefix. The prefix is real, but a route prefix
is exactly what ㊻ was caught grouping on, so it corroborates and does not decide.

### A hypothesis tested and withdrawn

*"Undo restores the prior model version"* makes `model.ts` the obvious home — it owns
`modelVersions`, `versionDiff`, `versionCostDelta`. **It is the wrong home.** Those read
`/projects/{pid}/versions` out of `bim.py`; undo pops a *different* stack, the `edit_history`
sidecar, which `recipe_log.py` describes as a list of file paths with *"No recipe, no parameters,
no actor"*. Two stacks, one word.

This is the second time a plausible destination has had to be withdrawn after checking it — (93)
withdrew (92)'s forecast about moving `editIfc` into `HttpCore`. **A likely-looking home is a
hypothesis to check against the backend, not an instruction to carry out.**

### The bound is weaker than (96)'s, and is stated that way

`app.ts`'s S4 block wires `refreshUndo` (calling only `editHistory`) and `doUndoRedo` (calling only
`editUndo`/`editRedo`), so the union is exactly these three. But unlike (96)'s `openAsBuiltPanel`,
that unit is a block delimited by reading rather than a closure the braces define — so it is
recorded as corroboration, not as a boundary. *Not every set has a witness as strong as the last
one's, and inflating a block into a closure would be the same defect this sequence keeps finding.*

`client.ts` is 70 methods above the STAYING banner and 4 below. Pin lowered with the file; the three
names added to `surface.test.ts` — all three have live call sites, so a drop breaks the undo/redo
buttons rather than only the count.

Thirty-fifth follow-on on the same version: **SCALE-SEAM (96)** — *the as-built question's
aggregate reader, and the first witness in this sequence that actually bounds a set*.

Three methods out of `client.ts` (`711 → 698`) into the existing `apps/web/src/api/model.ts`:
`lod500`, `setManufacturerInfo` and `attachOmDocument`, rejoining `verifyAsbuilt` and
`recordAsbuiltDimension` which (94) moved. No new mixin. **What they answer: is this element
installed as designed, and is it documented for turnover.**

### Two bounding witnesses, and they agree

`openAsBuiltPanel` in `apps/web/src/viewer/tools/modelStatePanels.ts` calls exactly five API
methods — read off that function's brace closure rather than grepped for, so it is the closure of
a scope and not a sample. Two of the five were already in `model.ts`.

Independently, the reader's own response type names its writer set field by field:
`verified`/`by_method` ← `verify_asbuilt`; `with_dimensions`/`dimensions_out_of_tolerance` ←
`record_asbuilt_dimension`; `with_manufacturer`/`with_serial` ← `set_manufacturer_info`;
`with_om_docs`/`om_documents` ← `attach_om_document`. The backend route says it in prose:
*"Stamp elements with the `verify_asbuilt` recipe."*

**A reader whose response type enumerates its writers is a DERIVED population.** Eight slices in,
that is the first grouping witness here that bounds a set rather than sampling one.

### What corroborates is not what bounds

`services/api/test_lod500.py` reaches exactly three recipes — `attach_om_document`,
`set_manufacturer_info`, `verify_asbuilt` — and **omits `record_asbuilt_dimension`**, which is
unambiguously in this family. So it agrees with the answer without being able to establish it. A
witness that misses a known member cannot bound anything, however exactly its members match.
*Three slices claimed "and no others" off a test file and were wrong all three times; the fix is
not to read the test harder, it is to ask which question the test can answer.*

### What is NOT claimed

`attachDocument` stays in `client.ts`, takes a `purpose` parameter, and `asbuilt_summary` counts
**any** purpose-tagged document reference. So *"every writer of `with_om_docs` moves here"* is
**false**. The field map above is of the recipes each field was designed around, not of everything
that can set it. The claim that survives is the bounded one: the five methods `openAsBuiltPanel`
calls.

### Two sources disagree, and lose for the same reason

`attach_om_document` is implemented as a purpose-tagged wrapper of `detailing.attach_document`, and
`authoring_matrix.py` files it and `set_manufacturer_info` under `data`. The first is a shared
HELPER, the second a STORAGE bucket — the two groupings (89) and (90) each had to reject. The
matrix is now the losing vote twice running after being right three times; *a corroborating source
that keeps winning is the one that stops getting checked.*

`client.ts` is 73 methods above the STAYING banner and 4 below. Pin lowered with the file; the
three names added to `surface.test.ts`, whose floor carries enough slack that the count alone would
not notice a loss.

Thirty-fourth follow-on on the same version: **SCALE-SEAM (95)** — *element state, and a matrix
disagreement worth stating rather than eliding*.

Four methods out of `client.ts` (`727 → 711`) into the existing `apps/web/src/api/model.ts`: the
`lodSummary`/`setLod` and `phasing`/`setPhase` pairs. No new mixin. **What they answer: what state
are the model's elements in, and set it.**

### The shape is the argument

Both readers return `{ total, <x>ed, prop, counts: Record<…> }` — same three fields, differing only
in the second field's name and the key union. Both writers are `(pid, guids, <enum>, publish) →
editIfc`. Both readers are consumed by `apps/web/src/viewer/tools/modelStatePanels.ts`. Both writers
are unwired and sit **adjacent** on `clientCallers.test.ts`'s UNCALLED allowlist.

**And `lodSummary` was a sibling separated from its own family.** `model.ts` already held
`/model/lod/census`, `/lod/handover-readiness` and `/lod/assessment`, while the base distribution
`/projects/{pid}/lod` stayed behind in `client.ts`.

### `authoring_matrix.py` disagrees, and why it loses

The matrix files `set_lod` under `data` and `set_phase` under `lifecycle`. That is a real
disagreement with this grouping and is recorded rather than elided. It loses because **the matrix
categorises by the IFC output each recipe writes** — an LOD stage tag against
`Massing_Phasing.Status`. Different property sets, same question.

*That is (89)'s "storage is a HOW" trap: "they write different psets" has the same shape as "they are
all module records", and neither is a question.* The matrix has been a good witness three slices
running; this is the first time it has been the losing vote, which is the reason to say so plainly
rather than quietly not mentioning it.

### It meets (94)'s objection rather than overriding it

(94) declined `setPhase` because taking the writer would have stranded `phasing()` in `client.ts` —
the reader/writer split (87) had to undo. Both halves move together here, so nothing is separated.

*Not contiguous: the pairs sat at 271–279 and 293–301 with `ensureContexts` and `queryElements`
between them. (88) recorded that as the strongest case for grouping by what methods answer, since no
prefix or positional split would ever find them together.*

Pin 727 → 711. **76 above the banner, still no map.**













## v0.3.1142 (2026-09-01) — SCALE-SEAM ㉜, appraisal and listings onto proforma.ts

Nine methods out of `client.ts` into the existing `apps/web/src/api/proforma.ts` mixin
(`2,531 → 2,486`). No extra wrapper on `ApiClient`.

What they answer together: *what is this asset worth, and how does it list?*
Appraisal, listing autofill / share / RESO, comparable import, MLS syndication.
`reports` / `reportUrl` stayed in `client.ts`.

`MARKS` widened to ㉝ on the way out. Pin lowered with the file.

## v0.3.1141 (2026-09-01) — SCALE-SEAM ㉛, ISO 19650 CDE onto documents.ts

Six methods out of `client.ts` into the existing `apps/web/src/api/documents.ts` mixin
(`2,580 → 2,531`). No extra wrapper on `ApiClient`.

What they answer together: *is the information container and its requirement flow in order?*
BEP, CDE status, info-requirements register / cascade / delivery plan, exchange acceptance.
`aiReadiness` stayed in `client.ts`.

`MARKS` widened to ㉜ on the way out. Pin lowered with the file.

## v0.3.1140 (2026-09-01) — SCALE-SEAM ㉚, GMP and the pay-app stack

Eight methods out of `client.ts` into the existing `apps/web/src/api/cost.ts` mixin
(`2,641 → 2,580`). No extra wrapper on `ApiClient`.

What they answer together: *what does the GC job cost, and how is the GMP billed?*
`costSummary`, `gmpBudget`, baseline / variance / cashflow, SOV-from-budget, G702 PDF, pay-app
invoice. `pxSummary` and `costTraceability` stayed in `client.ts`.

`MARKS` widened to ㉛ on the way out. Pin lowered with the file.

## v0.3.1139 (2026-09-01) — SCALE-SEAM ㉙, the investor capital stack

Nine methods out of `client.ts` into the existing `apps/web/src/api/finance.ts` mixin
(`2,696 → 2,641`). No extra wrapper on `ApiClient`.

What they answer together: *what do the investors own and get paid?* Cap table, waterfall,
capital call, distribution, investor statements, securities package / syndication. `k1Pack` was
already on that mixin. Rent-roll and lease management stayed in `client.ts` — adjacency is not a
relationship.

`MARKS` widened to ㉚ on the way out. Pin lowered with the file.

## v0.3.1138 (2026-09-01) — four more downloads a user can actually open

**Band 2 reach, fourth pass.** Mixins only (drawingSheets, models, modules):

- Drawings rail — door/window/room schedules as CSV
- Exports — nearby permits as GeoJSON (first city in the catalog) and the printable RFI log
- Model Analysis — cut vs projection graphic state for the first saved view template

Uncalled by the leaf rule: **31 → 27**.

## v0.3.1137 (2026-09-01) — twelve more engines a user can actually open

**Band 2 reach, third pass.** Mixins only (cost, elements, estimate, codecheck, ai, documents,
drawingSet, authoring — still no extra wrapper on `ApiClient`):

- Budget — resolved cost vintage, installed vintages, live GUID-keyed 5D table, GAEB X83 download
- Benchmarks — actual unit rates (cost ÷ installed quantity) beside the cost-code distribution
- Model Analysis — local code amendments and the stored space rule pack
- AI Assist — named agent packs and per-run history (write packs named as write)
- Documents — filed model revision list + file-current-model into `12_Model/IFC`
- Exports — compiled drawing-set PDF and shareable project-package PDF

Uncalled by the leaf rule: **43 → 31**. Shared-leaf `admissibility` and `eot/sourced` stay frozen
on purpose. `cv-progress/ingest-batch` remains the leftover under the genuine-unreached heading.

## v0.3.1136 (2026-09-01) — fifteen more engines a user can actually open

**Band 2 reach, second pass.** The freeze list still held working routes with no product caller.
Each gained a typed method on the existing domain mixin (codecheck, finance, model, models,
authoring — still no extra wrapper on `ApiClient`) and a card or download on the panel that
already owns the question:

- Standards — LOD 500 handover work list, triangle census, golden thread, spec links,
  export round-trip, schema diagnostic, authoring coverage matrix
- Equipment — FF&E bill of materials, starter spec-check properties, budget-suggestion
  lines, mint product-data submittals
- Operations / turnover — quality evidence vs closeout (uninspected counts against ready)
- Investors — K-1 preparation pack (capital movement only; named as not a tax document)
- Exports — IFC5 JSON (`.ifcx`) and WGS84 footprint GeoJSON

Uncalled by the leaf rule: **58 → 43**.

## v0.3.1135 (2026-09-01) — twelve built engines a user can actually open

**Band 2 reach.** These routes were live, tested, and frozen as deliberately unreachable because
nothing in the web app called them. Each gained a typed method on the existing domain mixin
(accounting, documents, elements, proforma, mep, cost, procurement, entitlements — not a new
wrapper on `ApiClient`) and a caller on the panel that already owns the question:

- Ledger — construction chart of accounts beside the trial balance
- Standards — naming conventions next to the naming audit
- Discipline Spine — model composition by NCS discipline
- Portfolio — acquisition funnel (`GET /pipeline/funnel`): derived win rates, weighted value
  with coverage, closed cycle time beside open age
- Budget — Uses vs capital plan (`GET /budget/two-sided`) and lien waiver JSON + PDF
- Analytics — whether RFQ dispatch is configured
- Design — approval conditions checked against the model (unevaluable stays not-checkable)
- MEP systems overlay — pressure loss, tray fill, thermal loads

`cv-progress/ingest-batch` is the one leftover in that freeze heading. Uncalled by the leaf
rule: **71 → 58**.

## v0.3.1134 (2026-09-01) — seven sourced clearances actually run

**SOFT-CLASH-RULES.** The geometry check the QA rail runs used one clearance — door approach at
0.9 m, `severity: high` — while `soft_clash.CLEARANCE_RULES` already held seven sourced classes
(NEC 110.26 working space, coil-pull, valve reach, pump service, VAV access). `rule_for` had no
production caller. The starter set is now derived from that table. Doors stay high. The other six
enter at **medium** so existing projects do not light up high the day they start being evaluated.
`fill_clearance_check` is what consults the table: omit `distance_m` on a stated class and it is
filled from the basis; omit it on an unknown class and the route 422s rather than inventing 0.9 m.
The engine itself no longer has that fallback.

Clash rail gained **Sourced clearance rules** (`GET /clash/clearance-rules`) and **Discipline-pair
matrix** (`POST /clash/matrix`). The clash client methods moved to `apps/web/src/api/clash.ts`
because `client.ts` is at its extraction pin.

## v0.3.1133 (2026-09-01) — the debug hook shipped the renderer, and energy export had no click

Two leftovers from looking at what a user can actually reach.

**The preview-eval hook was a production API.** `window.__viewer` assigned the Fragments
loader, THREE, `openFile` and the renderer on every session, including shipped builds. The
Cost/Deal rooms and drawings only need `selectByGuid` / `selectByGuids`. Those two stay;
everything else is DEV-only. `__takeoff` — a click driver with no product caller — no longer
attaches in production at all. Gated in `apps/web/src/viewer/debugHook.ts` and asserted both
ways (prod keys only; DEV keeps the live-verification surface).

**`energyExportUrl` had no caller.** Both `/energy/export.{gbxml,idf}` writers were live, tested,
and frozen as deliberately unreachable because a client method that accepts a format is not a
click that passes one. Exports now has those two buttons; the routes moved from
`KNOWN_UNCALLED` into `CALLED_VIA_TEMPLATED_EXT` with the call-site text as evidence. The
simplified `/exports/model.gbxml` button is unchanged — different engine, still labelled as
building-level.

Uncalled by the leaf rule: **73 → 71**. `test_groups` now picks the array by its source
GlobalId rather than "any array". The live-audit compare fixture dropped the deleted classic
shell as a run label.

## v0.3.1132 (2026-08-31) — eight routes frozen as callerless while the UI called them

`ROUTE-INTERP`. `test_route_reachability` flags a route when its **last static segment** appears
nowhere in the web source. The file's header already knew literal matching is unsound against a
client that builds URLs from template literals — that is *why* the rule is the last segment. **It
assumes the last segment is written out.** Eight routes are built with that segment templated too, so
their leaf appears nowhere, and every one was frozen in `KNOWN_UNCALLED` as deliberately callerless:

| route | built at | value passed at |
|---|---|---|
| `/exports/{cobie,qto,schedule,spaces}.xlsx` | `viewer/tools/exportsSection.ts:57` | the four-entry list on line 54 |
| `/schedule/{gantt,lob}.svg` | `api/schedule.ts:193-4` | `portal/panels/schedule.ts:731` |
| `/model/export.{jsonld,parquet}` | `api/model.ts:185` | `portal/panels/standards.ts:488-489` |

The list's own contract is that *"a frozen route that gains a caller must leave"*. These never lacked
one — eight entries in the allowlist that records deliberate decisions were false, and four of them
sat under a heading reading *"a user reaches these by clicking a link the server builds, so no client
caller is expected"*, which is what made them look considered.

## Two mechanisms, because one shape is decidable and the other is not

* **Templated stem** (`exports/${file}.xlsx`) is a **pattern**: the parent segment and the extension
  must still match literally. Six routes are accepted. Dropping the parent anchor *would* vouch for
  six more that nothing calls — measured as a mutation, not shipped behaviour.
* **Templated extension** (`model/export.${fmt}`) is a **two-entry named list with its call site
  recorded**, because as a pattern it is wrong in both directions: it vouches for six `export.*`
  routes of which only two are called. The other four are frozen correctly, and each says the same
  thing — **a signature that accepts a value is not a call site that passes one**:

  | route | why it stays frozen |
  |---|---|
  | `/model/export.ifcx` | `modelExportUrl` is typed `"csv" \| "jsonld" \| "parquet"` |
  | `/drawings/sheet.dxf` | `sheetPath` accepts `"dxf"`; its only caller `openSheet` is `("svg" \| "pdf")` |
  | `/energy/export.{gbxml,idf}` | **`energyExportUrl` has no caller at all** — an unwired client method |

That last row is a new finding this release does not fix: both formats the energy exporter offers are
unreachable, and the client method that would reach them is called by nothing.

## The leniency is pinned, because it moves the number the *rewarded* way

Every previous correction here made the gate stricter. This one makes it more permissive, and the
file's own generated-types comment says that is the direction nobody investigates. So the change is
not trusted to be small — it is measured against the pre-change rule and every route it vouches for
is named, **attributed to its mechanism** (six by pattern, two by list; swapping them keeps the total
right and fails the attribution), and the named list gets the mirror of `KNOWN_UNCALLED`'s rot check:
an allowlist asserting *"this IS called"* outlives its caller exactly the way these eight outlived
nothing. Five mutations, all failing, all restored.

**This is not the matcher-sharpening this file has rejected twice.** That proposal went the other
way — `/leaf` instead of substring, measured at 81 → 124 frozen, 43 newly unreachable. Opposite
change to the same rule; the earlier decision does not speak to this one.

Uncalled by the rule: **81 → 73** — the strict baseline is 81 and the two leniencies remove eight.

## v0.3.1131 (2026-08-31) — nine comments describing something else, and the reason nobody widened the gate

`DOC-STRAND`. A doc comment immediately followed by another doc comment has lost its own
declaration. It does not disappear — it attaches itself to the *next* declaration down and is read as
documenting that. `apps/web/src/api/docComments.test.ts` has caught this inside `apps/web/src/api`
since v0.3.1075. **Everywhere else in `apps/web/src` it was unchecked, and the roadmap's standing
"~25 orphaned comments, not yet fixed or gated" had been a candidate count for a month.**

Measured: **ten**, not ~25 — the `api/` cleanup had been the bulk of it. **Nine were real.**

**The gate stayed narrow for a reason that did not survive being checked.** Its own docstring
argued widening "would need a rule that can tell a header and a narrative from a leftover, and that
rule does not exist yet", naming two shapes:

* **A module header written below the import block is real — and needs no exemption, because it is
  structural.** Nothing but imports stands above it. That is computable, it exempts exactly one site
  (`apps/web/src/portal/panels/budget.ts`), and it cannot exempt a block with a declaration above it.
* **The "narrative above the thing it motivates" was not a shape at all.** `apps/web/src/main.ts`
  had no stranded comment. And the `apps/web/src/viewer/app.ts` RAIL-SPLIT block that reads as
  deliberate prose documents `distributeToolGroups` — declared **42 lines further down**, past
  `railGroup` and past `railGroup`'s own comment. It was residue, classified as intentional by
  reading it rather than by looking for its owner.

*A gate's scope is part of its claim, and so is the reason given for not widening it.*

**All nine were moves, not deletes** — the opposite of what the `api/` cleanup found, where most
orphans described features with no method left in the file. Not chance: `client.ts` was the file the
methods were moving *out of*, so its residue was abandoned; these are feature modules that only had
things inserted into them, so the owner is still a few dozen lines away. In **every one of the nine
cases that owner carried no comment of its own**, so nine silently undocumented functions
(`auditRooms`, `showMarkupGrid`, two different `renderBudget`s, `RegisterFilter`, `composeExhibit`,
`refreshDealMemory`, `installClickEcho`, `distributeToolGroups`) got their documentation back and
nothing was deleted.

Gated tree-wide by `apps/web/src/tooling/docStranded.test.ts` (336 files, 4 mutations). The *pairing*
half — does this comment share a word with the method below it? — stays inside `api/` on its own
merits: outside it, a comment legitimately describes a paragraph of behaviour rather than one method.
**Two rules that shipped together do not have to keep the same scope**, and assuming they did is what
kept this half narrow after its stated blocker had stopped being true.

## v0.3.1130 (2026-08-31) — a release you could sign and nobody could check

`ASSET-VERIFY`. `asset_rights.py` shipped both halves of a signed release manifest and only sealing
was reachable: `verify_release`, `verify_signature`, `verify_content_hash`, `verify_manifest_hash`,
`public_key_b64` and `generate_seed` had **zero** production callers, against one each for
`sign_manifest` and `build_manifest`. A manifest exists so that *someone else* can confirm a release
is authentic and unaltered; sealing alone produces a file nobody can check, including us.

Three things were missing and none was a big build:

* **`POST /asset-rights/verify`** takes the `asset_rights.json` out of a `.mass` and reports findings
  separately — `content_hash_ok`, `manifest_hash_ok`, `signed`, `signature_ok`, `trusted_key` —
  because *"the content was altered"* and *"it carries no signature"* call for different responses.
* **`GET /asset-rights/status` now serves `public_key`.** Its docstring said *"never the key
  itself"*, which read as a rule against publishing **any** key. `public_key_b64`'s own docstring
  says the public half is *"safe to publish; this is what verifiers need"*, and that same key is
  embedded in every signed manifest we emit — withholding it protected nothing and left a recipient
  trusting the document's own copy, which is the copy an attacker would have replaced.
* **`python -m aec_api.asset_rights --generate`** mints a signing seed. Without it the *signed* path
  was unreachable from a clean deployment except by generating an Ed25519 key out of band. It is a
  command and deliberately **not** a route: minting a private key is an operator action at the
  machine, and no request-authorisation gate is worth trusting more than shell access to the host.

**The design error, caught by writing the test rather than by reading the code.** The plan was to
default `public_key` to this deployment's key "so `trusted_key` means something". Backwards: a
release signed by anyone else would then be checked against *our* key, fail, and be reported as
`signature_ok: false` — a valid third-party release described as a bad signature. The key is the
caller's to supply. Omitted, the signature is checked against the key inside the document, which
proves internal consistency and nothing about authorship — precisely what `trusted_key: false` says.

**A client method was written and then deleted.** `verifyRelease()` had nothing in the UI calling it,
so it would have been an unwired client method added to make a reachability gate go green — the exact
defect this release removes, introduced while removing it. The party who verifies a release is
whoever received the file, with their own tooling.

**The reachability gate cannot see the new route in either direction, and that is now recorded rather
than worked around.** The leaf `verify` occurs in 25 unrelated web files, so the substring rule reads
it as called; for the same reason it cannot be frozen as uncalled. Asserted in
`services/api/test_route_reachability.py` beside its other documented blind spot, with the measured
alternatives for whoever takes the matcher on: `/leaf` flags 43 further routes, a word-boundary match
flags 5.

**Review found a crash bigger than the feature, and most of it pre-dated this release.**
`signing_available()` asked only whether the environment variable was **non-empty** — a claim, not a
fact — and every consumer trusted it. `bundle.py` signs a release when it is true, so a variable
holding anything that is not a 32-byte seed took down the **whole `.mass` export** with a
`RuntimeError` out of `_private_key`. Publishing the public key on `/asset-rights/status` inherited
the same fault and turned it into an **unhandled error on the one route a client calls to decide
whether to offer sealing at all** — that half was a regression this release introduced.

It now decodes the seed and constructs the key, so a misconfigured deployment reports
`signing: false` — hashed, tamper-evident, unsigned — a state the contract already has words for,
instead of failing downstream where the cause is invisible. The CLI distinguishes *unset* from *set
but unusable*, because telling an operator their key is missing when they can see it in the
environment sends them to re-set the same typo.

**The full suite caught a security defect the targeted runs did not: the new route was reachable
unauthenticated.** It shipped with `Depends(current_user)`, which **identifies** and does not
**authorise** — with RBAC on and no credential that dependency returns the literal string
`"anonymous"`. `SEC-GLOBAL-AUTHZ` exists because three `/jurisdiction/packs` routes shipped exactly
that way once, measured at 200/201/200 with no credentials. Now `require_identified`, asserted both
by that gate and by a check in this feature's own test, so a future edit fails the test that owns the
route.

A second gate fired in the same run: `/asset-rights` was frozen as **read-only**, and a prefix
gaining its first mutating route is the silent opt-out `test_protected_prefix_coverage` guards. It is
now recorded in `KNOWN_UNCOVERED_MUTATING` **deliberately**, on the grounds its own `/metrics` note
gives — the middleware net is for routes with no gate of their own, and this one has one. It is kept
out of `_PROTECTED_PREFIXES` on purpose: that would make `GET /asset-rights/status` refuse anonymous
callers, and the public key it serves is the one thing a third party needs to check a release we
issued. *Two gates, two different questions, and neither was answerable from the route in isolation.*

**And a limit of `trusted_key` that cannot be fixed, so it is documented and pinned instead.** The
same manifest and the same cryptographic evidence report `trusted_key: false` honestly, and `true` if
the caller echoes the document's own `verification.public_key` back. Comparing the supplied key
against the embedded one would *not* fix it — for a genuine release those are the same key. The API
has no trust anchor to check a caller's key against; trusting a key is the part a verifier does out
of band. The route says so, and a test asserts the flip so it is not mistaken for a bug later.

New gate `services/api/test_asset_verify.py` — 20 checks and four mutations. One of those mutations
found a hole in the test itself: removing the `signing_available()` guard from `--public-key` makes
the command *crash* rather than refuse, and an exit-code assertion cannot tell those apart. What the
guard buys is an operator being told what to set, so that is what is asserted now.

## v0.3.1129 (2026-08-31) — a citation had to name its source, but never to have a real one

`CITE-RECORD`. The entry said three of four citation builders were wired and the record one was not,
and called it extra-small wiring. Measuring the premise found something worse than the gap.

**`is_citation` checked that the identifying field was PRESENT, never that it had the right SHAPE:**

| citation | before | after |
|---|---|---|
| `cite_ifc("3Rb$mtGnf8kQm0Xy1_ZzAB")` — a real GlobalId | 0.733 | 0.733 |
| `cite_ifc("the north wall")` — a display name | **0.733** | **0.000** |
| `cite_record("budget", 7)` | 0.667 | 0.667 |
| `{"source_type": "record", "record_ref": "banana"}` | **0.667** | **0.000** |

A display name where a GlobalId belongs scored **the contract's highest confidence tier**, equal to
the real thing. That is this project's first non-negotiable — *reference a model element by GlobalId,
never a transient id* — being credited without being met, in the one place whose whole job is to say
whether a claim is backed. It is also the dead end `R31-CITE-HIGHLIGHT` fixed for documents,
*"display names render fine and cannot be opened"*, never applied to elements or records.

The rule was not new: `module_schema.IFC_GUID_RE` already existed and is now **imported, not copied** —
a rule with two copies is a rule with two places to drift. `rule` and `doc` stay presence-only, since
a rule id and a document id have no canonical shape, and **a positive control asserts they still
pass**: without it, tightening every kind would look identical to tightening the two that have a
format. Mutation-checked in both directions — reverting to presence-only fails, dropping the record
shape fails, and over-tightening onto `rule`/`doc` fails.

Scoped to **reads**, so stored citations are re-scored. That follows R37, which made this same
function strict and did re-score stored data; it is deliberately *not* the write-time scoping
`module_schema` uses for its own GUID rule.

**`owner_of` was consolidated, and it was hiding dead code.** `folder_template.owner_of` had zero
callers while `docmanager` reimplemented it at three sites. The three were not identical: `move`
carried a different rule — keep the file's existing owner when the destination is off-taxonomy.
Preserving it passed every test, and the mutation check showed why: **deleting the fallback broke
nothing**, because `move` raises on an invalid destination two lines earlier. The branch was
unreachable in the original too. *An unreachable branch and a well-guarded one look identical from
the call site; only the mutation tells them apart.* New gate: `services/api/test_folder_owner.py`.

**Review found a crash in the same function, older than this change.** `is_citation` looked its kind
up with `_IDENTIFIES.get(c.get("source_type"))` — a dict lookup. A `source_type` that is a list, dict
or set is **unhashable**, so instead of returning False like every other malformed shape it raised
`TypeError: unhashable type`, and one bad entry took out the whole `provenance_confidence` call.
`Assumptions.sources` is typed `dict[str, list[dict]]`, so a client can post exactly that. *A
validator that crashes on the input it exists to reject is not rejecting it.* Guarded on
`isinstance(kind, str)`, asserted over list/dict/set/int/None/object with a positive control that
well-formed citations still score, and mutation-checked. Pre-dates the shape rule; fixed here because
it is the same function and the same family.

**Two test files minted fake GlobalIds, and only the FULL suite found the second one.** Both
`test_cited_answer` and `test_persona_answer` passed `"g1"`-style placeholders to `cite_ifc`; under
the new rule those stop being citations, so every claim reads as uncited. The first was obvious. The
second was not: `persona_answer` builds no citations itself, the failure surfaced three modules away
as *"3 claim(s) carry no citation"*, and **the affected-suites heuristic did not reach it** — the
targeted runs were all green. *A change to a shared contract has no affected-suite shortlist; the
population is everything that calls it.* Both fixtures now build real 22-character ids from readable
labels, so they exercise the shape rather than dodge it.

**The record builder is still unwired, and that is now recorded as a decision rather than a task.**
`ask()` never reads a module record, nothing server-side populates `Assumptions.sources`, and the web
only types the citation shape. Giving `cite_record` a producer means building record-aware QA — a
feature, and the user's call. *"One of four missing from a set of four is a gap, not a design"* was a
reasonable inference and it was wrong.

## v0.3.1128 (2026-08-31) — the sweep that found nothing, recorded so nobody runs it again

Documentation only; no engine changed. v0.3.1127 corrected a roadmap claim that a release had
already ended, and the obvious next inference was *"if one was stale, sweep them all"*. That was
checked rather than assumed. **It is not a class.**

**Population:** the 21 `⚠` markers in `docs/roadmap.md`, of which exactly **five** assert
present-tense runtime behaviour that can be executed and falsified. The rest are SHIPPED rows,
sweep-run headers, prior corrections and the 18-findings table; one more (`takt.py`'s name) is a
semantics decision with nothing to falsify.

**Four of five accurate.** The EOT surface is dark as described; `/schedule/risk` really does serve
the same engine as `/schedule/montecarlo` (`schedule_risk_mc.for_project`); the three PPC
implementations really were unified in v0.3.974 and are held by `services/api/test_ppc_divergence.py`;
`/schedule/compare` really does return `finish_move_working_days` and `calendar_vs_working_gap_days`.
The one false claim was the one already fixed.

**Why the negative result is worth a release.** Every defect class this repository has found by
sweeping — the refusal-state readers, `PORTAL-STATUS`, the status/workflow drift — showed *several*
instances on the first probe. This one showed one and four counter-examples. *A sample of one is a
finding, not a pattern.* Recording it stops the next reader inferring a class from the v0.3.1127
entry and spending days confirming that well-maintained entries are well maintained.

**The gap is stated rather than papered over.** Only the falsifiable five were swept. A roadmap
sentence that misdescribes something unexecutable — an intent, a plan, a reason — cannot be caught
this way, and no gate proposed here would catch it. The 103 test-file citations in the roadmap were
considered as a population and rejected: filtering mechanically cannot separate a citation
*describing what a test asserts* from one offered as *corroboration of a live defect*. That needs
reading, not grep.

## v0.3.1127 (2026-08-31) — the roadmap described a defect that a release had already ended

Documentation only; no engine changed. Two roadmap entries said `eot.py` **"names four AACE methods
and performs none of them. All four return an identical number on the same input."** Both are
corrected, because the claim was false — and false on the day it was written.

Measured through `eot.analyse`, one job, baseline finish 2026-01-31, two excusable events totalling
20 days:

| actual finish | `impacted_as_planned` | `as_planned_vs_as_built` | `time_impact` | `windows` |
|---|---|---|---|---|
| 2026-02-10 (slip 10) | **20.0** | **10.0** *(capped)* | *refuses* | *refuses* |
| 2026-03-12 (slip 40) | 20.0 | 20.0 *(cap idle)* | *refuses* | *refuses* |

Three distinct outcomes where the as-built cap binds, two where it does not, and the two series
methods never return a number at all — they refuse with `method_needs_schedule_updates`. "All four
return an identical number" is therefore untrue on every input, not merely on some.

**The fix predated the claim by four days.** `v0.3.971` shipped 2026-08-16 under the title *"four
delay methods, one number, and a label that said otherwise"*; the roadmap paragraph was dated
*"measured 2026-08-20"*. A measurement date is what stops a reader re-checking a sentence, so an
inherited date made this harder to catch, not easier.

**The citation contradicted the claim it supported.** The paragraph cited
`services/api/test_schedule_windows.py` as its pin. That test asserts `windows` and `time_impact`
return `None` — *"which is now the REASON they refuse"*. The gate had been green on the **corrected**
behaviour the entire time. *A citation is evidence that a file exists, not that it says what the
sentence claims* — `test_claude_md_gates.py` checks the former and cannot check the latter.

No new gate. The behaviour is already pinned twice (`test_schedule_windows.py`, `test_eot_methods.py`)
and both were green throughout; what failed was prose that the existing gates already contradicted.
A string-matching guard on one sentence would rot the same way the sentence did.

**What survives is the genuine open decision, unchanged:** whether `/schedule/eot` should delegate to
`schedule_windows` and `schedule_modelled` — which perform three of the four for real — or keep its
own number and cite theirs. An EOT figure ends up in arbitration, so that remains a domain call.

## v0.3.1126 (2026-08-31) — the rejection flag fired on the sub who was still biddable

The tail of `PORTAL-STATUS`. `prequalification.score_record` raised its "marked rejected" flag from
`data["status"]`, the typed field, while v0.3.1124 had moved `in_pool` to `workflow_state`, the field
the reject transition sets. The two then answered to different fields, and came out **inverted**.

Measured through `/prequal/scores`, on two subs driven through the real transitions:

| sub | workflow | `in_pool` | flag before | flag after |
|---|---|---|---|---|
| rejected by the **transition** | `rejected` | `false` | **none** | `rejected` |
| merely submitted, `"Rejected"` **typed in the blob** | `submitted` | `true` | **"marked rejected"** | `status field says rejected, but the workflow says submitted` |

So the flag fired on the sub who was **still in the bidding pool** and stayed silent on the one the
team had actually refused — the worst of both readings, and worse than either field alone.

**The typed value is neither believed nor dropped.** `modules.transition()` never writes `data`, so
the two fields drift on their own with nothing to reconcile them; a person typing "Rejected" while
the workflow says otherwise is a real disagreement, and naming it is more use than picking a side.
`PREQUAL_NOT_IN_POOL` moves above `score_record`, which is now its first reader — *the flag and the
pool must not answer to different fields.*

Both changes mutation-checked: reverting the flag to the blob, and collapsing the disagreement into
a plain rejection, each fail a specific assertion. A positive control asserts a clean record raises
neither, so the pair cannot pass by flagging everything.

### The first cut fixed the field and left the normalisation — found in review

`score_record` canonicalised `workflow_state`; `score_project` compared the raw stored value. The two
then agreed on **which field** to read and disagreed on **how to read it**, which reproduced the same
defect one line away. Measured through `/prequal/scores` with `workflow_state` stored as `"Rejected"`:
the flag read `rejected` while `in_pool` stayed **true** and the sub kept its place in `pool_count`
and `high_risk`. Transitions write canonical states, but a bundle import preserves whatever it is
given, so the non-canonical case is reachable rather than theoretical.

Both now go through one `state_key()` helper — *a rule split across two call sites is a rule with two
places to drift, and this one drifted inside the release that exists to stop exactly that.* Asserted
over `rejected` / `Rejected` / `"  REJECTED  "`, with a positive control that a non-refusal state
survives canonicalisation without becoming one, so the test cannot pass if the helper always
returns `"rejected"`.

## v0.3.1125 (2026-08-31) — the owner's page said nothing had been paid, and it never could

**`PORTAL-STATUS`.** The client-facing payment schedule showed `data["status"]` — a select a person
fills in — instead of `workflow_state`, the field the transitions actually set.

Measured through `/shared/{token}/digest` on three owner invoices driven through the **real**
transitions:

| | before | after |
|---|---|---|
| `billed` | 650,000 | 650,000 |
| **`paid`** | **0.00** | **350,000** |
| `outstanding` | 650,000 | 300,000 |
| INV-001 — `submit` → `mark_paid` | shown to the owner as **`draft`** | `Paid` |
| INV-002 — same, plus the select's own `"Paid"` typed in | `Paid`, **not counted** | `Paid`, counted |
| INV-003 — submitted | `draft` | `Submitted` |

**`paid` was structurally unreachable.** The comparison was `status == "paid"`, lowercase, against a
select whose every option is capitalised (`Draft / Submitted / Approved / Rejected / Paid`), with no
normalisation anywhere on the write path. The only value that could ever have matched is a lowercase
string written straight into the blob — which nothing in the product does. **The one thing that did
was the test**, which seeded `"status": "paid"` through the API and so proved the arithmetic on data
no UI can produce. *A check that supplies its own subject in a form the product cannot emit is not a
check.*

**The root cause is structural, not a typo.** `modules.transition()` writes `workflow_state`,
`modified_at` and `party_owner` and **never touches `data`** — so the blob and the workflow are
independent fields that drift apart the moment anybody uses the workflow, and nothing reconciles
them. `owner_invoice` declares the same five-state vocabulary **twice**: once as its workflow, once
as a hand-typed select.

**Two readers, one rule.** `_payments_html`'s green "paid" colour carried the identical lowercase
comparison, so it never once fired. Both now key off `invoice_status_key()`, and the response
carries `status_key` (what everything compares on) beside `status` (what the owner reads), so the
page and its totals cannot disagree about one invoice.

### What the sweep did NOT change, and why that is the finding

17 modules declare both a workflow and a hand-typed `status` field, and a `get("status")` grep
returns ~25 hits. **Two of them were the defect** — both in `client_portal.py`. The rule that
separated them:

- **The workflow can express the same thing → the blob is a shadow; read the state.**
  `owner_invoice`, `permit`, `prequalification`, `value_engineering`, `weekly_plan`.
- **The workflow lacks the concept → the blob is the authority; reading it is CORRECT.**
  `bid_submission`'s workflow is only `[open, closed]`, so award lives solely in its select;
  `project_budget.py` reading `d["status"] == "Awarded"` is right, and its capitalisation matches.

Most of the remaining hits were never module data at all: computed RAG dicts in `precon` and the
construction report builder, a *project* field in `supply_pipeline`, a snapshot in `assistant`, and
an **external** open-data permit payload in `routers/opendata.py`, correctly translated at the
boundary. `procurement_gate` builds its status *from* `workflow_state` and reads its own dict.

**REFUSAL-READERS' population was derived too NARROWLY and missed five real reads; this one is too
WIDE and flags twenty-three non-defects. Same species of error, opposite directions — so neither a
match nor a miss is evidence, and only reading settles it.**

### A colour assertion scoped to its own row

Review flagged the HTML colour check as vacuous, reasoning that an earlier approved decision already
renders `#1a7f37` on that page. **Measured: that claim is false here** — forcing the payment row to
`color = "#9a6700"` fails the assertion, so the colour was on the page only because of the invoice.
The *fragility* behind the claim is real though: a page-wide substring check stays honest only while
nothing else on the page uses that colour, and goes vacuous the moment something does, with nothing
to announce it. The assertion now scopes to the INV-001 row and adds its converse — the unpaid row
must NOT carry the paid colour.

### A lane cell that outlived its item, and the gate that let it

Review flagged a stale item code in the Lane C table. The framing — that it violates a validation
rule — is wrong: every gate was green. **The observation is right, and the reason it was green is
the more useful half.** `PORTAL-STATUS` was added to that row in v0.3.1124 and marked ✅ here, and
the gate that exists to catch exactly this (*"names no code that has neither an open entry nor a
note saying it is done"*) tested the whole cell against `/SHIPPED|CLOSED|.../`. The cell read
`PORTAL-STATUS *(split out of the now-closed REFUSAL-READERS)*` — so it matched **"now-closed"**,
a fact about a DIFFERENT item, and exempted the entry from its own check.

*A note about somebody else is not evidence about you.* The rule now strips any parenthetical naming
another code before testing, with a fixture carrying a positive control — the raw cell must still
match the `done` regex, or the fixture would not reproduce the bug it describes. Verified by
restoring the stale row: the gate names it.

### A guard that no route-level test could see

`invoice_status_key` casefolds, and mutation-testing showed **no assertion through the route could
tell `.strip().lower()` from nothing** — workflow states are already lowercase, and the blob
fallback is only reachable on a legacy row with a NULL state. That is the untestable-guard shape
v0.3.1124 deleted. Here the branch is worth keeping, so it is asserted **directly** against the pure
function instead of left as decoration: `invoice_status_key({}, {"status": "Paid"}) == "paid"`.

## v0.3.1124 (2026-08-31) — the last five refusal readers, and a metric that was never alive

**`REFUSAL-READERS` closes: the five remaining instances, plus the behavioural gate for the class.**
Every number below was measured through its real route before and after, never reasoned about.

| endpoint | measured before | after |
|---|---|---|
| `/rfi/register` | `cost_impacted_count` and `schedule_impacted_count` both **1**, sourced entirely from a VOIDED RFI | `0` / `0` |
| `/prequal/scores` | `high_risk: 1` on a project whose only high-risk sub had been **rejected** | `high_risk: 0`, `pool_count: 1` |
| `/entitlements/conditions` | `total_open: 5`, three of them the terms of a **denied** variance | `total_open: 2` |
| `/entitlements/condition-checks` | the denied variance's conditions model-checked into `total_not_checkable: 5` | `2`, refusals named |
| `/specs/submittal-log` | `required_total: 5` / `missing_total: 5`, three demanded by a **void** spec section | `2` / `2` |
| `/spine/traceability` | `specs_packaged_pct: 50.0`, the void section named as a broken chain link | `100.0`, gap list empty |

**The prequalification case is the sharpest.** `score_record` *already noticed* the rejection — but
through `data["status"]`, a free-text field a person types, while ignoring `workflow_state`, the
field the reject **transition** actually sets. It raised a "marked rejected" flag, then scored and
counted the record anyway. The state was not missing; it was read from the wrong field and acted on
in no way that changed a number.

**The feasibility-style shape recurs at the consumer, too.** A denied entitlement keeps its
conditions listed — an appeal puts them back in play — so `/entitlements/condition-checks`, one level
up, had to honour the refusal itself or it would re-create the defect by checking the model against
terms that were never imposed and reporting the misses as compliance findings.

### A metric that could never have computed

`rfi.register`'s turnaround read `updated_at`; a module row's timestamp column is **`modified_at`**.
`avg_response_days` was therefore permanently `None` — a **dead** metric, not a slow one — and any
refusal filter over it would have been vacuous. `quality.py`'s `avg_days_to_close` carried the same
typo and is fixed with it. (`ncr` declares no refusal state, so that one is only the dead-metric
fix.) The gate asserts an answered RFI now produces a real number, so it cannot quietly die again.

### What was already right, and is now asserted

Three numbers the sweep's own derivation had wrongly listed as broken: `open_count`, `overdue_count`
and `ball_in_court` already honoured `void` (it is in `CLOSED_STATES` and has its own court). They
are now asserted so a future "fix" cannot double-count them. *A derived population names candidates,
not defects — reading each one is what separates the two, and three of five sub-numbers named here
were the wrong ones.*

### The redundant guard mutation testing caught

The first draft of the entitlement fix filtered refused records **twice** — once in `assess`, once
again in `for_project`'s sums. Mutation-testing the second filter showed **no assertion could tell
its presence from its absence**, because `assess` had already zeroed the record. It is gone. *A
guard whose removal nothing detects is not defence in depth; it is a second place to rot.*

### A fifth count that did not move with its filter — found in review

`submittal_log.logged_total` is summed **submittal-side** (`sum(logged_by_section.values())`), not
over the rows, so filtering the rows left it behind: a submittal logged against a **withdrawn**
section still counted as logged while that section's `required` did not.

This is the corollary this very release writes into the roadmap — *when you filter a computation,
every count derived from that set must move with it* — **failing on the release that states it**,
and the reason is worth naming. The other four counts (`required_total`, `missing_total`, `by_type`,
`by_division`) accumulate inside the row loop, so filtering the loop moved them for free.
`logged_total` is derived from a **different collection**, and a filter applied to one collection
does nothing to a total derived from another. *Look for the counts that are built somewhere else.*

**The suggested patch was not taken as written.** Accumulating `logged` per enforced row would also
have dropped **orphan** submittals — logged against a section number that matches no spec row at
all. Those are still submittals somebody logged; dropping them silently trades one wrong number for
another. The exclusion is by section key and only for keys no enforced row also claims, so a
withdrawn row and a reissued row sharing a section number cannot take the live one's logged
submittals down with it.

### The size ratchet did its job, and the pin came down

18 lines of new response fields went into `apps/web/src/api/client.ts`, a file under an extraction
ratchet at 2,752 — and the build went red at 2,769. That is the ratchet working exactly as its own
comment describes: *an extraction without a ratchet is a rearrangement.* The four refusal-aware
response shapes moved to `apps/web/src/api/types.ts` as named interfaces — which is what that file
exists for, as its header says — taking the client to **2,731**, twenty lines below where `main` had
it. The pin moves **down** 21, never up.

*The failure was invisible locally for a self-inflicted reason worth recording: the size gate was
run BEFORE the client edits, and the full-suite command was piped through `tail -20`, which
discarded the inline `FAIL` line and reported the pipeline's exit status instead of the runner's.
A check run before the change it should judge is not a check.*

### Gate

`services/api/test_refusal_readers.py` is the class's behavioural gate: per record type, drive the
real route, transition into refusal, assert the consuming number does not move — each with a
**positive control** proving the subject drove that number while live, and a **reconciliation**
assertion tying the filtered population plus the excluded list back to the total the same response
reports. It also asserts every refusal rule in the class is a named constant rather than an inline
literal, and that `spine.traceability` uses `specs.SPEC_SECTION_WITHDRAWN` rather than its own copy.
All seven fixes were mutation-checked independently.

## v0.3.1123 (2026-08-30) — a scheme the team refused could still win the comparison

**Four `REFUSAL-READERS` instances, all of the form "a refused thing ranks first".** Unlike v0.3.1122
these move no money directly; they move what the product *recommends*, which is worse in one respect:
a wrong number gets questioned, a wrong recommendation gets built.

| endpoint | measured before | after |
|---|---|---|
| `/design/options/compare` | a REJECTED option named **best-in-class on all four** of its populated metrics | the live scheme leads |
| `/design/options/carbon` | the rejected option was `lowest_total` | `Scheme D — live` |
| `/design/options/economics` | the rejected option was `best_irr`, at 30% against a live 12% | the live scheme |
| `/feasibility/compare` | a SUPERSEDED zoning scheme ranked **#1** at 240,000 GFA vs a live 80,000 | excluded and named |

**The design-option case is the sharpest.** The engine already knew: the same response reported
`rejected: 1` in `by_state` while naming that option the leader. The state was not missing, not
buried, not expensive to reach — it was one field away, counted, and ignored.

**The feasibility case is the most consequential.** The top scheme is the baseline every other
scheme's deltas are measured against, so a superseded FAR-12 envelope made a live FAR-4 scheme read
as a 160,000 SF *shortfall* against something nobody can build. Its own sibling `feasibility()`,
thirty lines below in the same file, already reads that state to prefer an approved record — one
function in the file honoured it and the other did not, the same shape as the accounting and
procurement defects. `compare` also **dropped `workflow_state` before returning**, so no caller could
have filtered even if it wanted to; every row now carries it.

**Nothing is hidden.** All four endpoints keep listing the refused item and name what left the
ranking — `not_in_contention`, `superseded_excluded` — following `compute_appraisal`'s
`excluded_comparables`. A ranking whose field silently shrank reads as a thinner set of options
rather than as a decision somebody recorded. `draft` and `proposed` are deliberately still ranked:
an unapproved scheme is a real thing to test, which is what a comparison is *for*.

These three modules already separated LISTED from RANKED — for unmeasured carbon and unpriced
economics, as their own notes say. Refusal simply was not one of the reasons.

**And the same defect, a third time, caught by review.** Excluding a refused option from the
*ranking* left the counts describing the *unfiltered* set: `option_economics` reported
`unpriced_count: 1` while **zero** options lacked an IRR — the rejected one has 30% and was simply
missing from `priced` — and `option_carbon`'s `measured` + `unavailable` no longer summed to
`count`. This is the third appearance of one shape: v0.3.1122's `billed_to_date` excluded refused
invoices while `invoice_count` did not; then this; then carbon's parts not summing. **Filter a
computation, leave a count over the unfiltered set.** Both now take their counts against the ranked
population and return `in_contention_count`, so `count` reconciles rather than leaving a reader to
infer the difference. Asserted, not just fixed: the test pins `unpriced_count` to the number of
options that actually lack a figure, and pins both responses to add up.

**A vacuous test, caught by mutation-checking rather than by review.** The first `option_carbon`
mutation **did not fire**: reverting the fix broke nothing, because the rejected option carried no
carbon figure and so could never have won that ranking. Adding one exposed a *second* vacuity — with
the rejected option excluded, nothing was measured at all, `lowest_total` went `None`, and the
assertion passed for a new wrong reason. It took a live carbon-bearing option to make the check real.
Both guards are now in the test with the reasoning inline. Every assertion carries a **positive
control** (the option leads while live) so no exclusion test can pass merely because its subject was
uncompetitive.

## v0.3.1122 (2026-08-30) — the owner rejected the invoice; five money numbers went on counting it

**A rejected owner invoice was booked as revenue.** `accounting.journal_entries` posted every
`owner_invoice` as debit 1200 / credit 4000 — Accounts Receivable and Contract Revenue — with no
regard for its workflow state. Measured through the routes with a rejected $250,000 application
beside a certified $100,000 one, the trial balance reported **accounts receivable of $350,000
against $100,000 actually owed**.

Rejecting an owner invoice is the *owner* refusing to pay it — `reject` is their transition, and
`revise` (rejected -> draft) is the GC's way back. Every consumer of the record ignored that:

| reader | what it got wrong |
|---|---|
| `accounting.journal_entries` | posted AR + Contract Revenue for a refused application |
| `/accounting/trial-balance` | AR $350,000 instead of $100,000 |
| `project_budget.billed_to_date` | "THE single 'billed' number" the loan-draws, draw-composition and investment memo all quote |
| `wip.schedule` | `billed` drives over/under-billing, which posts BACK as the WIP-ADJ revenue line — one refused invoice moving the ledger by two routes |
| `client_portal` payment schedule | billed the owner for the invoice **they** rejected — and displayed `data.status` (default "draft") rather than the workflow state, so it showed as a draft that nonetheless counted |
| `/loan-draws` | drew $350,000 and accrued interest on the balance it invented ($2,085.62 -> $595.89) |

**This is the AP fix from v0.3.1121 met in a mirror.** That release fixed `journal()` for
`sub_invoice`; this defect sat twenty lines below it, in a different function, reading a different
record type, and was untouched. *Adjacency in a file is not a relationship* — the fix and the bug
were as close as two pieces of code can be.

The rule is a **named constant**, `project_budget.OWNER_INVOICE_NOT_BILLED`, not five inline checks:
a record type with five readers is a rule with four places to rot. `sum_field` has carried an
`exclude_states` parameter — and named *"billed-to-date"* as its example — since it was written; the
call site simply never passed it.

`submitted`, `approved` and `paid` stay: the first two are live receivables, the third is history
that belongs in the books. `draft` also stays, deliberately — whether an unsent draft counts as
billed is a separate question from whether a *refused* one does, and only the second has an answer
the workflow states. Only the explicit refusal is refused.

Pinned in `test_accounting.py`, `test_portal_txn.py` and `test_wip.py`, each asserting the converse
too — a submitted application still bills, and `revise` restores a refused one, so the fix cannot
degrade into "only certified counts". All five engine changes mutation-checked independently.

**The roadmap lane gate was measuring 31 of 33 items, and it took adding an item to notice.** The
new roadmap entry for this class is called `REFUSAL-READERS`; `roadmapLanes.test.ts` passed with it
in place, and the pass was vacuous — the item regex capped a code head at six characters and
`REFUSAL-` is seven, so the bullet was never in the population. Widened to eleven and measured as
that file requires: **31 codes before, 33 after, none lost.** The second code gained is
`QUALITY-ROOM`, an entry that had been invisible to the gate for its whole life and so was never
required to be in a lane; it is a question answered and declined in place ("the register stays with
its discipline"), now marked ⛔ to say so.

Widening the item regex did not fix it. `laneRows()` held a **second hand-kept copy** of the same
six-character rule, so the code was in the population, absent from every lane, and the suite failed
naming it an orphan while the lane row plainly listed it — two copies of one rule inside the check
that exists to catch two copies of one rule.

**And "both now read a single `CODE_HEAD`" was itself a claim narrower than it sounded.** Review
found the copies do not stop at that file: there were **nine across three suites**, so
`REFUSAL-READERS` stayed invisible to `roadmapStale` and `roadmapSelfConsistent`, both of which
reported a pass on an item they could not see. All nine now carry the same rule (measured per
regex shape: 31 → 33 codes and 27 → 29, nothing lost either way).

The duplication is **gated rather than removed**: these suites are deliberately self-contained
(node + vitest only), so a shared module would be the first import between them. A new check asserts
every code-head rule across the three files is character-for-character identical, reading the file
*text* rather than the compiled regex — because the failure being prevented is a copy that was never
wired to anything, which a runtime check over imported values cannot see. A second check asserts the
rule is wide enough for the longest code the roadmap actually contains, so the limit is measured
against the file instead of being a number someone must remember to raise. Mutation-checked: one
copy reverted fails the gate and names the file.

**A second review round found the fix had made one payload disagree with itself.**
`/projects/{pid}/construction-draws` returns `actual_billed` from `billed_to_date` — which this
release taught to exclude refused applications — beside an `invoice_count` from `count_records`,
which was not taught anything. So the endpoint reported money from N invoices next to a count of
N+1: measured, `actual_billed` $1,000,000 with `invoice_count` 3. **Excluding an amount without
excluding its count is not half a fix, it is a new defect**, and `count_records` had the principle
in its own docstring — *"a count that ignores a filter the list applied reports a total the page
cannot account for, and a total is exactly the number a user trusts without checking"* — while
lacking the parameter to honour it. It now takes `exclude_states`, matching `sum_field`. Pinned as
a PAIRED assertion, because either half alone passes while the response contradicts itself.

**And the widening was described wrong in three places.** `[A-Z][A-Z0-9]{1,11}-` admits a head of
**twelve** characters, not eleven — the leading `[A-Z]` sits outside the quantifier. The regex is
fine; the prose was off by one, and so was the new gate's own second assertion, which compared the
quantifier bound against a full code length and would therefore have **rejected a 12-character code
its own regex accepts**. That is the same claim-wider-than-the-property mistake this release is
about, pointing the other way. The assertion now converts bound to admissible length explicitly;
the rule stays at twelve rather than narrowing to make the sentence true, because narrowing a limit
is what created this whole section.

**Not fixed here, and recorded instead:** the same portal reader shows `data.status` from the
free-text blob rather than `workflow_state`, so a certified application can read as a draft to the
owner and the paid/outstanding split can be wrong independently of any refusal. That is which
status the page *shows*, not which invoices it *counts* — pre-existing, client-facing, and it
changes a contract the portal tests encode, so it is its own slice under `REFUSAL-READERS` rather
than a rider on this one.

**The population in the roadmap entry was also derived wrong, and that correction is the more
useful one.** The table said 17 unfiltered sites while the classification below it summed to 19.
The reason: the derivation matched `list_records(db, "<type>"` and nothing else, but
`billed_to_date` and `wip.schedule` read the same records through `sum_field`, a SQL aggregate.
Counting the other accessors gives `sum_field` 3 and `count_records` 2 — 49 reads, not 44. So **two
of the five defects this release fixes were never in the population at all**; they were found by
reading the module, not by the sweep meant to be exhaustive. A derived population is only as
complete as its list of accessors.

## v0.3.1121 (2026-08-29) — a `.mass` you can prove is authentic, and the first tag in thirty releases

**Sealing a container is now possible, and opt-in.** A `.mass` can carry `asset_rights.json`, a signed
release manifest: it cites the container's existing deterministic digest rather than building a second
one, excludes the regenerable `model.frag` from release identity, and is signed and verified with
Ed25519. A stable `asset_id` survives an export/import round-trip, which nothing did before — import
mints a fresh project id, so provenance had nothing to bind to.

It is **chosen when the file is created**, because a manifest attests to the bytes of one particular
export and cannot be bolted on afterwards without producing a different file. A container saved
without it is byte-for-byte what this format has always produced: **no format-version bump**, and a
v2 reader ignores the field. Both directions are tested. With a key the release is signed and a third
party can verify it; without one it is hashed and tamper-evident but carries no attribution, and the
UI says which of those two you have rather than implying the stronger one.

Deliberately not done: no contract, no chain, no wallet, no new dependency. That half is a decision
rather than work, and it is written up under "Decisions, not effort" in the roadmap.

**This release also closes a thirty-version gap.** v0.3.1090 (2026-08-25) was the last tag, while main
reached v0.3.1120 — every release step was being taken except the last one, and nothing was watching
it. The CHANGELOG was current, both manifests were bumped, CI was green on every commit and the
container images published; only the tag was missing. So this build additionally carries everything
merged since 1090: the R37 reach ring (twenty functions that were built, tested and reachable by
nothing in production — four wired, three consolidated), four money-bearing fixes in the proforma,
CAM, margin and comparables engines, the anthropic 1.x SDK move, and the gates written along the way.

## v0.3.1120 (2026-08-29) — the roadmap's ⭐ was pointing at finished work

Asked what to do next, the honest first step was not to read the roadmap's ranking but to **check it**.
Four of the open markers were stale, including the one the file itself flags as most valuable.

### The sweep

| item | marked | actually |
|---|---|---|
| **R46** — Band 2's ⭐, *"the highest-value item in a band"* | open | **done.** `test_vendor_reachable`: 29/29 reachable, 0 unreached, allowlist empty. Its own closing line already read *"R46 IS COMPLETE"* |
| **R37-TRIAGE** *(M — "do FIRST")* | open | **done.** `test_dead_code_population`: 0 unreferenced, `DELIBERATELY_UNCALLED` empty. The "12 remaining candidates" are gone |
| **R37-TESTED-UNWIRED** | *"NOT yet read"* | **complete v0.3.1115–1119** — its own body says so, four lines below the header saying it isn't |
| **QTO-TRADE** | open | **done** — its body: *"ALL THREE ARE NOW WIRED — 2026-08-27"* |

Plus the sprint-proposal row naming R37-TRIAGE's twelve candidates, which is a status line too and had
gone stale the same way.

**Three of the four had one half of a single entry contradicting the other**, and R46's ⭐ meant the
file's own priority ranking sent a reader at work that was finished. This roadmap has recorded this
defect at least six times — *"two whole bands read as open and were entirely finished"*, the five
stale status lines counted in the SCALE-SEAM ring, *"a pull request is the one staleness clock in this
file with a real timestamp on it, and nothing consulted it."*

### So it is a gate now, for the items that can have one

`services/api/test_roadmap_status.py` pairs an item code with a predicate that reports whether the
work is done, and fails when the roadmap still marks it open. The predicates **run the real gates** —
the same ones a human would consult — so the check cannot drift from what they report.

`roadmapLanes.test.ts` already checked that every open item is in a lane; that is bookkeeping *between
two lists*, and neither list measures anything. This one measures. Deliberately small: two items
qualify today, because inventing a predicate for a prose item about a product decision would produce a
check that is vacuous or wrong — the failure it exists to catch. It carries a **negative control** (a
genuinely open item whose measurement must still say "open"), so a bug making every predicate return
False cannot leave it green. Mutation-tested both ways.

### And then the actual work: SCALE-SEAM ㉘

`client.ts` 2,816 → **2,752**, as `apps/web/src/api/accounting.ts` — ten methods, the double-entry
books and WIP.

**The strongest case yet for grouping by what methods ANSWER**: the group sat in **two non-contiguous
clusters ~700 lines apart**, with prequal, carbon and land screening between them. No prefix split
would have found them together, and a route split would separate `journalBatchExportUrl` from the
batch `createJournalBatch` creates. What they answer together is one question — *what do the books
say?* `costTraceability` sits immediately above the second cluster and did **not** come: it answers a
takeoff question that happens to be adjacent. *Adjacency in a file is not a relationship*, met for the
third time (㉕, ㉗, ㉘).

Two things done in the shipping release rather than the next one, both corrections to how this ring
has failed before:
* **`MARKS` widened to ㉙ on the way OUT of ㉘.** The ㉘ note records the vocabulary stopping one short
  while the bullet was headed with a slice its own next words called shipped — *"a code it cannot
  spell is a code it cannot contradict."* Widening late is how that happened.
* **The per-file pin lowered 2,837 → 2,752**, zero headroom. It had been carrying slack nobody
  recorded: v0.3.1119 took the file to 2,816 *under duress from that very check* and never lowered it.

## v0.3.1119 (2026-08-29) — the three that were left: a sold format nothing could produce

The three items v0.3.1118 deliberately left for a product decision. All three turned out to have a
defensible answer in the code, and **checking each premise changed two of them again.**

### ① `nwd` was not the only thing sold and unbuilt — `obj` was too

The finding said the `navisworks` entitlement and `nwd` export were advertised and unimplemented. It
was right about `nwd` and **wrong about `navisworks`**, and it missed a second format. Checking every
declared export for a delivery path rather than trusting the single grep that produced the finding:

| format | tier | delivered by |
|---|---|---|
| `nwd` | Enterprise | **nothing — and nothing can.** Delisted. |
| `obj` | Home | **nothing.** `viewer/referenceLoader.ts` *reads* `.obj`; import is not export. Delisted. |
| `rvt` | Commercial | **nothing.** Every RVT path is an *import*. Delisted — see below. |
| `png` | Home | the viewer's canvas capture — client-side, which is why it stays |

**`rvt` is the one I got wrong while fixing the other two, and review caught it.** `POST /convert`
converts RVT→IFC→`.frag` and its own 503 reads *"Revit (.rvt) **import** needs the Autodesk APS
bridge"*; `/bridge/rvt/status` reports on that bridge and `/projects/{pid}/import/rvt` is named for
what it does. Nothing writes an RVT. My `EXPORT_DELIVERY` mapped `rvt` to `/convert` and the gate
passed — because **the gate asked whether the path EXISTS, not whether it EXPORTS**, and `/convert`
exists. A delivery path must now end in `.{format}`, which is what an export route looks like here
(`export.gltf`, `sheet.pdf`, `sheet.dxf`); mutation-tested by restoring the exact `rvt → /convert`
mapping, which the gate now rejects. *A check whose property is weaker than its claim passes for the
same reason the bug shipped* — the third instance of that shape in this phase, and the first in a
gate I wrote to catch it.

`nwd` is not a gap to close. `routers/convert.py` already states the position for its siblings:
*".rvt/.dwg/.nwc are closed Autodesk formats with NO open-source reader"*. Writing one offline is not
possible without the paid APS/ODA SDK, and this project's own rule is that such bridges are optional
and flagged, never bare-tier features. Selling it as an Enterprise differentiator was the error.

**`navisworks`, by contrast, is real and was simply never enforced** — native Navisworks clash-report
XML import (`smart:` namespace), tabular clash reports, BCF round-trip. Exactly the `sso` defect from
one release earlier: an entitlement the Settings panel renders and no code consults. Now gated on the
native XML route. The tabular sibling stays open deliberately: it reads Solibri and any spreadsheet,
so it is not the Navisworks capability the table sells, and gating it would refuse Solibri users a
plan they do not need.

`services/api/test_export_promises.py` resolves every sold format against the **live FastAPI path
list**, not against the registry that declares it — the tautology cut from `test_r37_contract.py` a
release earlier, avoided this time by construction. Mutation-tested 3/3.

*The delisting also went red on two assertions written one release earlier* — `test_licensing.py` and
`test_r37_contract.py` both pinned `nwd` to Enterprise, because when they were written that was true.
They now assert the delisting instead, in that direction rather than deleted, so re-adding the format
has to confront the line. The vacuity floor in the 402-message loop moved 9 → 8 for the same reason:
it guards against an empty population, and the population legitimately shrank.

### ② `pdf_sanity` is a pre-ingest gate because it now runs at ingest

Its docstring called it *"a fast pre-ingest gate"* with no runtime caller anywhere — a role asserted
in prose and held by nothing, the same shape as `pid_lock.cross_process_status` in v0.3.1115. Wired
into `routers/drawings._read_pdf`, the single chokepoint `info`/`merge`/`split`/`extract`/`rotate` all
read through, which was hand-rolling `data[:4] != b"%PDF"` — a weaker second copy of a check that
already existed properly, the duplicated-derivation shape behind most of this phase's findings.

Two things follow that were not the point but matter more than it: these routes read whole uploads
into memory and hand them to pypdf with **no size cap at all** (now 50 MB), and embedded active
content — JavaScript, Launch, OpenAction, EmbeddedFile — is now reported, since pypdf carries it into
whatever the route hands back. Reported, **not refused**: plenty of legitimate CAD-exported drawings
carry an OpenAction, and refusing those would break real workflows to no security benefit.

**A merge is bounded by the SET, not only by each member** — raised in review, and it is the
multiplication a per-file cap invites: twenty files each just under 50 MB are twenty acceptances, all
held at once for pypdf. `/pdf/merge` now takes at most 50 files and 200 MB in total, refused as soon
as the running total passes so the rest are never read. (The review also said merges had *no*
aggregate limit; that part is wrong — `bodycap.MaxBodySizeMiddleware` bounds the whole request body,
counting bytes as they arrive rather than trusting `Content-Length`. What is genuinely open is the
half that middleware's own docstring names: *"it does not stop a handler materialising the body it
did receive"* — pre-existing across 36+ `await file.read()` sites and tracked as the back half of
R39-UPLOAD-CAP-APP, not this release's to close route by route.)

The `no %%EOF trailer` flag is deliberately not a refusal either, and now says so in the code —
review asked for a 422 there, and measurement declined it: `pdf_sanity` looks for `%%EOF` in the last
1024 bytes, so a PDF with 2 KB appended (an incremental update, an embedded signature) trips the flag
while **pypdf reads it and reports its pages without complaint**. Pinned as a test, so the exemption
is evidence rather than an omission.

### ③ A capability nobody can reach is indistinguishable from one that was never built

`/projects/{pid}/mep/size` had no caller in `apps/web` at all, and `client.ts::takeoff2d` never sent
`layout`. So wiring `block_cooling` into the route in v0.3.1116 made it *callable* and not
*reachable* — the product gap survived the fix meant to close it.

Now: `sheetRegions` (the producer for the `layout` the takeoff consumes — the same one-way asymmetry,
found again), `mepSize`, an opt-in "scope to sheet" control in the 2D takeoff, and a first-pass MEP
sizing calculator in the MEP tools. The takeoff reports its shortfall rather than a bare total —
`unscoped` / `ambiguous` / `unknown` are three different reasons a number would be wrong, and only
`scoped` traces may be priced. `apps/web/src/api/unreachableRoutes.test.ts` asserts the whole chain
from UI entry point to request, because a client method nothing calls is the same defect one layer up.

### Two existing gates went red, and both were right

Neither was a regression — both fire when something *becomes reachable*, and refuse to let a stale
entry sit in a list describing the past.

* `test_reachable.py` had carried **`supply_chain` in `KNOWN_UNREACHABLE` since 2026-07-27**, worded
  *"tested and imported by nothing. Whatever it checks is not being checked in the running system."*
  That is the `pdf_sanity` finding, recorded a month earlier in a different file, by a gate that had
  been saying so the whole time. Wiring it made the module reachable and the entry stale; deleted.
* `test_route_reachability.py` had `/projects/{pid}/drawings/sheet-regions` frozen as caller-less.
  It has a caller now, so its entry is gone too.

*Two independent checks noticing the same fix is the strongest evidence available that the wiring is
real rather than merely present* — neither knows about the other, and neither was edited to agree.

## v0.3.1118 (2026-08-28) — R37 CONTRACT: an empty dict scored 100% provenance coverage

The last two R37 findings, and they turned out to be one defect in two places: **a contract
documented in prose and enforced nowhere**, so the thing meant to serve as evidence could be
supplied by anyone for free.

**① `{}` was full provenance.** `cited_answer` documents four citation kinds, and the proforma's
`Assumptions.sources` block is typed `dict[str, list[dict]]` with a comment saying those dicts are
`cite_doc` / `cite_record` / `cite_rule` / `cite_ifc`. Nothing checked that they were. Measured
against the real functions before the fix:

| recorded "source" | coverage | status | confidence |
|---|---|---|---|
| `{}` | **100%** | cited | **0.6** |
| `{"foo": "bar"}` | **100%** | cited | 0.6 |
| `{"source_type": "ifc"}` — no GUID | **100%** | cited | **0.733** |
| `cite_record("rfi", 12)` — complete | 100% | cited | 0.667 |

An empty dict was full provenance coverage. Worse, **asserting the strongest source type while
naming no source out-scored a complete weaker citation**, because rank was read off a self-declared
string that nothing validated — so the highest trust signal in the system was free to anyone who
claimed a kind and supplied nothing. On a module whose stated thesis is *"an uncited assumption is
uncited, never assumed sound."*

`cited_answer.is_citation` is now the contract's own rule — a known `source_type` **and** the field
that kind uses to identify its source (`guid` / `record_ref` / `rule_id` / `document_id`). Callers
that build through the `cite_*` constructors pass by construction, so this is invisible to every
real producer and bites only dicts that were never citations. `provenance_confidence` and `build`
count recognised citations only; `assumption_provenance` reports malformed entries in
`malformed_citation_paths` rather than crediting them, on the same principle that already named
`orphaned_sources` — a caller who records a citation this contract cannot read has exactly the
problem that field exists to surface. This also removed a crash: `source_types` indexed
`cit["source_type"]` directly, so one dict without the key took down the whole answer.

*This is why `cite_record` had no producer.* It was never a missing feature — the field that is
documented to take record citations accepted anything, so nothing ever had to build one.

**② The `sso` entitlement gated nothing, and the upgrade message named no plan.**
`TIER_FEATURES` has marked `sso` Enterprise-only since the tiers were written and the Settings panel
renders that table, but no code consulted it: any workspace that configured a SAML IdP got SSO.
`saml.is_available()` is now configuration **and** entitlement, and it gates all three SAML routes
through one guard *and* `/auth/providers` — because gating only the routes would have left the
sign-in page rendering an SSO button that 402s on click. That is the symmetric-path defect this
phase has now hit five times: fixing one side of a path teaches the caller the other side is safe.

Upgrade messaging was a second, hand-kept copy of the tier matrix listing only the openBIM formats,
so every Home-tier export refusal rendered **"PNG export requires the Massing a higher plan (or
higher)"** — the most common refusal a Free workspace would ever see. `min_tier_for` /
`min_tier_for_export` derive it from `TIER_FEATURES`; a capability no tier grants now says so
instead of implying an upgrade would help. `tier_at_least`, which had no caller, is gone: these are
the derivations that needed to exist.

**And the first version of the fix repeated the bug it was fixing.** `_cites_for` filtered
`isinstance(c, dict)` while building its list and took the malformed count *after* that discard, so
`sources = {"exit.exit_cap": ["Appraisal p.12"]}` — a plain string where a citation belongs, the most
natural way to get this field wrong — reported **0 malformed** and rendered as plainly uncited: a
caller once again unable to see that what they recorded had been thrown away. Anything recorded and
unreadable now counts; only an absent or empty value is silence, because nothing was claimed. (Caught
in review on #372.)

`test_r37_contract.py` pins all of it (120 checks), and was itself mutation-tested — three
deliberate regressions, three failures. One assertion was dropped for being a tautology: looping the
export list to check each entry resolves to a tier cannot fail, because the derivation reads that
same list. The population that matters is the **rendered 402 string** for every declared format, and
that is what catches the original defect.

## v0.3.1117 (2026-08-28) — R37 CONSOLIDATE: the callers had reimplemented the accessors

Three functions came back referenced only by the test tree, and the roadmap's reading was that
deleting them was the wrong move because **the caller had reimplemented each one**. Fixing the caller
removes the duplication *and* the orphan; deleting the function keeps the duplication and loses the
better implementation.

`routers/ids.py::_specs_from` looked a use case up itself and called the **private**
`ia._specs_for` — which is both halves of what `build_from_use_case` and `eir_for_use_case` do, and
why neither had a caller. `/ids/build` and `/ids/eir` now call them. `agent_packs.catalog` inlined
`list(p["tools"])` where `tools_for` exists, so it calls that instead: one definition of what a pack
runs.

**Reading the code changed the plan twice.**

**The private reach-through had a second caller.** `codecheck.py` also called `ids_authoring._specs_for`
and passes a *group list* rather than a use case, so it cannot go through `specs_for_use_case`. *A
private helper with two external callers is not private, it is undeclared* — so it is now
`specs_for_groups`. Routing around it would have left the second caller reaching in.

**And routing `/ids/eir` through `eir_for_use_case` would have shipped two regressions**, both
because the twins had drifted while one of them had nothing calling it: it raised a bare `KeyError`
where `build_from_use_case` raises `ValueError`, so the route's existing **422 would have become a
500**; and it had no `title` parameter, so a caller-supplied title would have been **silently
discarded**. Both were fixed before the route was pointed at it, and both are pinned. *A
consolidation that adopts the surviving implementation inherits its defects too, and they are
invisible precisely because nothing calls it.*

**And review found the pair still disagreed about malformed input.** `/ids/build` has always wrapped
its build in `except Exception -> 422`; `/ids/eir` had **no catch at all**, so a malformed explicit
spec — a requirement missing `pset`, a spec that is not an object, a `requirements` that is a string —
came back **500** from one route and 422 from the other, on the identical body. Narrowing the new
`try` there to `ValueError`, which is all the use-case branch needs, would have hardened one half of
a symmetric pair and left the other reporting a server error for the caller's own bad input. Measured
on all three cases, both routes, before and after; the well-formed twin still answers 200 on both.

*Two lessons from the test rather than the code.* Its first draft asserted the reach-through was gone
with `"_specs_for" not in inspect.getsource(router)` — and **failed on the router's own new comment**,
which explains the fix by naming the private helper in prose. A substring test over a file counts
comments as code, which is the defect this R37 line keeps finding in other gates; it does not get to
live in the test that closes it. `services/api/test_r37_consolidate.py` walks the AST and asserts on
attribute accesses instead. And its catalog checks guarded every claim with
`if isinstance(cat, dict) and "packs" in cat else True`, so an unexpected shape would have passed
silently — *a defensive fallback that turns a check into a no-op is the same defect as writing
`True`*, and it is asserted against the real shape now.

## v0.3.1116 (2026-08-27) — R37's last two WIRE items, and what "wired" turned out to mean

`mep.block_cooling_load` and `takeoff_scope.scope_annotations` were the last two of R37-TESTED-UNWIRED's
four real gaps. Both are now routed, and the useful finding is how narrow the fix actually was.

**Each was the one function in its module that its own router did not call.** `routers/design.py`'s
`mep_size` is a five-branch dispatcher over `mep.py`: it called `size_duct`, `size_pipe`,
`size_cooling` and `hanger_spacing`, and `block_cooling_load` was reachable by nothing. `takeoff_2d`
called `takeoff_scope.scope` and `check_calibration`, and `scope_annotations` — R27-LAYOUT ③'s own
named deliverable — was reachable by nothing. **One of five missing from a five-branch dispatcher is
a gap, not a design.** Parity with the siblings is the bar and it is the whole bar.

**`block_cooling` is not `cooling`.** That converts a load somebody already has into tons; this
estimates the load from gross area, which is the earlier question and the one asked when no load
exists yet. The area defaults to `energy.project_gfa_sf` — the one definition of gross area here, so
deriving a second would guarantee two answers to one question — and a caller can still pass `gfa_sf`
to size a massing that is not the loaded model.

**The route refuses where the engine clamps.** `block_cooling_load` does `max(gfa, 0.0)` and
`max(sf_per_ton, 1.0)`, and both clamps turn a missing input into a confident number: an unloaded
project answers `tons: 0.0`, which reads into a plant schedule as an answer rather than as a missing
input, and `sf_per_ton=0` returns **350x** the tonnage for the same building. The engine is unchanged
— the clamps are its business and other callers may want them — so the refusal lives at the route,
where a request can still be told what is wrong with it. `services/api/test_r37_wire_routes.py`
asserts the clamps are still in place, so the fix cannot quietly become an engine edit.

**Annotations ride on the layout the traces already use.** `scope_annotations` takes
`takeoff_2d`'s existing `layout` and `px_per_point` rather than a route of its own, because it is not
a second engine: its docstring is explicit that an annotation and a traced polygon pose the identical
question — which drawing is this on — so it maps annotations onto the same region shape and calls
`scope`. A separate route would have duplicated the coordinate contract, and two places to get
`px_per_point` wrong is how two answers to one question drift apart. Both keys are omitted entirely
when their input is absent, so a takeoff with no notes gets the response it always got.

**A 500 on malformed input, found by review and fixed once rather than twice.** Every coordinate on
this route is caller-supplied, and `float("abc")` raised straight out of `takeoff_scope.scope`'s
comprehension — leaving the route as a **500**, the wrong status for bad input, and failing a whole
forty-trace takeoff over one malformed entry. **The gap was pre-existing and symmetric:** the
`regions` path did exactly the same thing, and routing annotations merely added a second way to reach
it. So it is fixed in `scope`, where both paths converge; fixing only the new half would have been
worse than leaving it, because a caller would learn that malformed input is handled and then meet a
500 on the other key.

A bad row now comes back `unknown` **with a stated reason**, which is this module's existing
vocabulary — an empty point list has answered exactly that since it was written — and one bad trace
costs that trace rather than the other thirty-nine. A wrong *type* for the whole `annotations` field
is still a 422: that is a caller who cannot be answered at all, as opposed to one bad note in a sheet
full of good ones.

**Then the same mistake in miniature: the LAYOUT was the other half of that gap.** Hardening the
traces and annotations and leaving the viewport rectangles left **seven** more 500 paths, all
caller-reachable — a `rect` that is a string, too short, missing, or containing null; a `regions`
that is a string or holds a null; a `layout` that is not an object at all. Same function, same class,
one door further in. The type-level cases are now 422 and the row-level ones are handled.

**A skipped viewport is COUNTED, and that is the load-bearing part.** Skipping one silently would be
worse than the crash: a trace over a drawing whose rectangle could not be read would report
`unscoped` — *"not on any drawing"* — when the truth is *"we could not read the drawing"*. That is a
wrong answer in the confident direction, which is the failure this module exists to prevent, so
`scope` returns `unreadable_viewports` and says in its note what it means for the traces.

**And the last crash survived because the route kept its own copy of the filter.**
`takeoff_2d`'s calibration block had `_viewports`' body inlined —
`[r for r in (layout.get("regions") or []) if r.get("kind") == "viewport"]` — so hardening the engine
did not reach it, and a string `regions` still iterated its characters there. The helper is now
public (`takeoff_scope.viewports`) and the route calls it. *Two derivations of one question meant one
of them stayed unhardened* — the same shape as the boot guard's hand-parsed dialect two releases ago,
in different clothes.

**Then the subtlest one, which nothing caught until review: NaN and infinity survive `float()`.**
They raise nothing, match no finite viewport, and came back `unscoped` — *"this trace is not on any
drawing"*. A confident wrong answer about the **drawing**, when the truth is that the coordinate is
meaningless. Now `unknown`, like every other unreadable coordinate. The same trap sits one level out:
a viewport `rect` of NaN converted cleanly, counted as *readable*, and would have reported every trace
on that drawing `unscoped` with `unreadable_viewports: 0` — the count that exists to prevent exactly
that misreading saying nothing at all. Both are `math.isfinite`-checked now.

**And a guard that was right but in the wrong place.** The `annotations` type check sat *inside*
`if layout:`, so a request with `annotations: {}` and no layout returned a normal takeoff and dropped
the field on the floor — the silent no-op the guard exists to prevent, reintroduced by where it was
put. *A malformed field is malformed whether or not a different field is present.* Both type guards
now run before the layout gate.

**And a separate gap, found while wiring these.** `/projects/{pid}/mep/size` has no caller in
`apps/web` at all — it appears only in the generated `schema.d.ts` — and `client.ts::takeoff2d` never
sends `layout`, so R27-LAYOUT ② and ③ are unreachable from the product however well they are routed.
That is not a dead function but a **built server capability with no client**, a different shape from
anything R37 measured, and it needs a UI decision rather than a wiring one. It is recorded in the
roadmap rather than fixed here. `test_route_reachability` cannot see it: the route path is referenced
by the generated schema, which satisfies a substring test over the web tree.

## v0.3.1115 (2026-08-27) — two of R37's four real gaps, and both comments were describing surfaces nobody built

R37-TESTED-UNWIRED classified 20 test-only functions last release and called five of them real gaps.
**Four are** — one of the five is corrected below. Two of the four are now wired, and in both cases
the code that *explained* why they were unreachable was itself the defect.

**`pid_lock.cross_process_status` — a boot guard arguing against a function, for a false reason.**
It reports what serialisation is actually in force for the sidecar write lock: a Postgres session
advisory lock, or nothing a second worker can see. Its docstring said it was "callable from a health
surface and from the production guard". Neither existed. `main._production_guard` derived the dialect
itself with `db_url.split("://")` under a comment explaining that it must not call this function,
because the call "opens a live session, so a transient connection blip would return `''`".

**It does not connect.** `SessionLocal()` is lazy and `db.get_bind()` returns the engine, whose dialect
is parsed from the URL string — it answers `postgresql` for a DSN pointing at an unroutable address,
now pinned by `services/api/test_pid_lock_surface.py`. So the duplicate derivation looked like dead
weight and the guard was switched to call the status.

**The next full run failed `services/api/test_perf_rate.py`, and that is the part worth keeping.** Its
own comment carried the real reason: the engine is built once, at import, so under any test runner it
is SQLite whatever a fixture's env claims — and an earlier engine-probing version of that branch had
"shipped a guard no fixture could ever satisfy". The guard reads the env var again, the comment above
it now says *why* instead of saying something false, and both directions are pinned so the next reader
who notices the duplication finds the reason rather than the fiction. They are not the same question:
the guard asks whether the database this deployment is **configured** for can serialise, the status
asks whether the engine this process is **using** can. At boot they agree. *A stated reason that is
false is worse than no comment at all* — the true constraint stands behind it unrecorded, and the only
thing that finds it is breaking what it was protecting.

The "live-truth surface on /health" was never built either, and `/health` was never going to be it:
it is dependency-free on purpose, and "in-process only" is a supported deployment shape, not a failed
probe. It went to `/metrics` as `aec_pid_lock_cross_process`, beside a new `aec_pid_lock_writers`,
**because the dangerous condition is a conjunction and neither number is the alarm alone.** That also
answers which deployments needed telling: the guard refuses on exactly this conjunction, but runs only
when the DB is non-SQLite or `AEC_ENV` says production, and is skipped entirely under
`AEC_ALLOW_OPEN=1`. A self-hosted SQLite deployment with two uvicorn workers boots clean and is
exposed. Both numbers come from one extracted `_writer_processes()`, so a refusal at boot and a scrape
at runtime cannot disagree about how many writers there are.

**`photo_cv.duplicate_of` — the abuse it exists for was unguarded on the only path where it happens.**
*One photo uploaded against thirty elements to clear a checklist.* `routers/verification.py` ran
`photo_quality` and `compare_photos` on upload and never this. The upload now compares against
`element_verifications.photo_phash`, a new nullable column (migration `f7a3c82e19d4`), rather than
re-reading every stored photo out of object storage per upload.

**Flagged, never refused** — the same judgement the route already makes about a blurred frame. Two
elements can legitimately share a frame; the server cannot tell that from checklist-clearing and a
reviewer can, and refusing would teach whoever wanted to defeat it to take one step left, leaving no
record at all. `photoVerdict` renders it second, behind only the retake prompt: both stop being cheap
the moment the person walks away.

**`compared_against` ships with every answer.** Photos predating the column are not backfilled, so a
clean result over nothing must not read as a clean result over everything. The UI renders no line at
all when no duplicate is found, for the same reason — saying nothing makes no claim, and a reassuring
"no duplicates" would make one that is false on every project with older photos.

**And one of the five was not a gap at all — `test_fit.depth_range`.** Last release's entry said the
client "has to invent the sweep this function exists to generate". `optimize` generates it whenever
`targets.sweep_depth` is set, `apps/web/src/proforma/testfitTab.ts` sets that from a checkbox, and
`routers/generate.py` routes it: reachable end to end. The measurement flagged it because
`src/aec_api/test_fit.py` is a **production** module — a *test fit* is the architectural exercise of
fitting a program onto a plate — and the population rule sorted files into "test tree" by the
`test_*.py` filename, so a production call inside it counted as a test reference. The WIRE list is
four, not five. *A population rule that looks reasonable is wrong until you read what it selected* —
and reading is not enough either: the first read produced a confident sentence about the route's
`body.depths` and never opened the engine. The gate `services/api/test_dead_code_population.py` was
never fooled; it counts same-file callers on purpose. The ad-hoc measurement reintroduced a
distinction that gate had already learned to do without.

*One fixture lesson, from the new test failing its first run:* the retake case was written against an
element whose shot a second element also held, so the duplicate it reported was correct and the
self-exclusion it was meant to test sat invisible under a legitimate match. **An exclusion can only be
tested on an item that is otherwise unique.**

## v0.3.1114 (2026-08-27) — all 20 test-only functions read, and the answer is not "20 dead"

R37-TESTED-UNWIRED said 20 public `aec_api` functions are referenced only by the test tree. All 20 are
now read, each against what its own router actually calls. **Eight are correct as they are, three want
their callers fixed rather than themselves deleted, five are real gaps, and the two most valuable
outputs are not functions at all.**

**Five that nothing can reach — `beside` again.** The sharpest is `pid_lock.cross_process_status`:
`main.py`'s boot guard explains at length why it reads the dialect from `DATABASE_URL` instead of this
function, and ends *"the live-truth surface stays `cross_process_status()` on /health"*. `/health`
returns `{"status": "ok"}` with no dependencies, deliberately. **The comment asserts a surface that was
never built**, and the fact it exists to publish — *this deployment cannot serialise sidecar writes
across workers* — is readable by nobody. Also `photo_cv.duplicate_of` (the one-photo-for-thirty-elements
abuse its docstring names is unguarded on the only path where it can happen),
`takeoff_scope.scope_annotations` (R27-LAYOUT ③'s own deliverable), `mep.block_cooling_load` (not a
duplicate of the routed `size_cooling` — that converts a known load, this estimates it from GFA), and
`test_fit.depth_range`.

**Three to consolidate rather than delete.** `routers/ids.py::_specs_from` duplicates
`build_from_use_case`'s body **and reaches for the private `ia._specs_for`** to do it; `catalog()`
inlines `list(p["tools"])` rather than calling `tools_for`. Calling the public wrapper removes a
private reach-through *and* the orphan; deleting would remove only the orphan.

**Two contract findings worth more than the functions.** `licensing.tier_at_least` has no caller and a
grep for any tier gate finds only `current_tier()`, read for display — **entitlement tiers are computed
and shown and enforced nowhere.** And `cited_answer.cite_record` is one of four citation kinds of which
only `cite_ifc` is ever produced, while `routers/proforma_schemas.py` documents all four as the value
type.

### What shipped: the exemption was the wrong instrument

`services/api/test_energy_star_bridge.py`. Yesterday's release exempted `sync_property` in the
dead-code gate as a refusal stub. Reading its family showed the exemption was wrong:
`parcels_bridge.fetch_parcels` and `payments_bridge.send_payment` are the same design and **each
already had a test exercising the refusal** — `sync_property`'s only reference in the whole tree was
the exemption entry naming it.

**An exemption is what you write when there is nothing to assert.** There was something. The stub now
has the test its siblings had, in both postures — unconfigured, and flagged-on-but-unwired, which is
the dangerous one because a deployment that has set the env vars is exactly the one that would believe
a number it got back. The load-bearing assertion is not "it raises" but that **no posture returns a
score**: a fabricated 1–100 would be read as EPA's and never questioned.

`DELIBERATELY_UNCALLED` is empty again, and the gate is held by a test rather than an exemption —
mutation-checked by removing the new file and watching `sync_property` come back.

*The first draft of the roadmap entry proposed exempting all three stubs together, on the reasoning
that the other two were invisible for the same reason. They were not; checking took one grep. It is
recorded because the wrong version was one sentence from shipping, and it would have frozen a missing
test as a deliberate decision — which is exactly how an exemption reads to everyone afterwards.*

## v0.3.1113 (2026-08-27) — a dead-code gate that counted prose, and the gap it still cannot see

**Two changes and one correction, and the correction is the useful part.**

`test_dead_code_population.py` counted every non-docstring string literal as a reference, deliberately:
registries dispatch on strings, and that rule is why `register_recipe` survived a sweep. But it makes
no distinction between a dispatch key and an English sentence, so any function whose name is a common
word is reached by prose. The gate had already recorded this once — `evm.quadrant`, *"a limitation,
stated rather than hidden"* — and left it needing a human.

It needed a rule: **a key is a token, a sentence has spaces.** A string literal now counts only when
the whole literal is identifier-shaped — `add_wall`, `cost_per_sf`, `drawings.markups.rekey_storeys`
match; a payload note reading *"…is shown beside it rather than folded into it"* does not.

Measured before and after, because this file's own history is four corrections to a population rule:
**0 unreferenced → 1**, and the one is `sync_property`, which R37-TRIAGE already documents as
genuinely uncalled and masked by its own `NotImplementedError` string. It moves from invisible to
**explicitly exempted, with the reason and a rot-check in both directions**. An exemption anybody can
read beats a mask nobody can see; from the outside they are identical — a green run over a function
nothing calls.

**Writing that exemption list immediately broke the gate, which is the sharpest part.** Adding
`"sync_property"` as a dict key made `sync_property` referenced — the key is identifier-shaped by
construction, so it survives the very filter it was added because of. The ratchet went back to zero
and the entry documenting it read as stale. **An exemption list that satisfies the check it exempts
from is the gate measuring itself**, the same shape as the `specPane` string that made
`canvasMode.test.ts` too weak in v0.3.1111. The gate no longer reads its own file: it names symbols to
talk about them, and it is not a caller.

### The correction: this is NOT why `beside` was missed

Yesterday's find — `deal_memory.beside()`, built and wired to nothing — scored **60 references** here,
and it would be neat to say the prose rule is why. It is not, and checking rather than asserting is
the whole discipline: **under the tightened rule `beside` still has two references, one of them
`test_deal_memory.py`, which has imported it since the engine shipped in PR #180.**

The test tree counts as callers **by design** — that is the 35 → 13 correction in this gate's own
header, and it is right for the question the gate asks. But it means *"tested, and wired to nothing"*
is invisible to it by construction, and no string rule reaches that.

So the gap was measured instead of narrated: **20 public functions in `aec_api` are referenced only by
the test tree**, `beside` having been the 21st. That is the third instance of one shape after
`read_p6xml_all` and the spec manual's MasterFormat default, and all three were found by hand. Three
hand-finds is a population, not a coincidence.

It is recorded as **R37-TESTED-UNWIRED** rather than ratcheted, because the number is not the
deliverable: several of the 20 are legitimately test-only surface — `sbom`, `pdf_sanity` and
`is_dual_licensed` exist for the supply-chain *gates*, which are tests by design. R37-TRIAGE's record
is the warning: reading its 12 candidates found **eight live**, and the two deleted without reading
had to be put back.

### Review round on the above, and the sharpest finding was already a test

**`test_route_authz.py` failed on the new route, and it was right about something a correct hand-check
would still have got wrong.** The first version authorised with
`if pid not in (member_project_ids(db, user) or {pid})`. `member_project_ids` returns **None** for "no
restriction" and an **empty set** for "a member of nothing" — and `or {pid}` collapses the second into
the first, so a signed-in user belonging to no project was authorised for any project id they typed.

The route now uses `Depends(require_role("viewer"))`, like every other `/projects/{pid}` route in that
file. The gate walks those routes and requires the *tagged* dependency, so a bespoke membership check
is invisible to it **whether or not the check is correct** — it is not looking for authorization, it
is looking for the one authorization anybody audits. Running it before pushing would have taken four
seconds; the full backend suite takes twenty-two minutes, and skipping the suite meant skipping this.

Three more, all real:

* **`hard_cost` accepted NaN and Infinity.** `not x` is False for NaN and every comparison with NaN is
  False, so both halves of `not hard_cost or hard_cost <= 0` let it through; it then divided into the
  response and left as `null` under orjson — *a comparison with a missing number in it, which reads as
  "no history" rather than as bad input.* Now `math.isfinite`, with all five cases pinned.
* **The $/SF strip was painted once by `renderBudget()`**, so editing "Hard cost $" left a comparison
  for the PREVIOUS hard cost beside the new number. It rides the same debounce as the solve now, and
  a late reply for a superseded cost is dropped rather than allowed to win by arriving last. Three
  regression tests, one of which fails on the `cost_lines[1]` shortcut the sum replaced.
* **The test inherited `DATABASE_URL`.** `setdefault` keeps `run_tests.py` in control of the per-test
  database, which is right — but it also inherits whatever a developer exported, and this file calls
  `create_all` and commits fixtures. It now refuses to start against anything that is not a local
  sqlite path, rather than quietly creating test schema in a real database.

## v0.3.1112 (2026-08-27) — the firm's own closed projects, beside the number being underwritten

**R35-DEAL-MEMORY's engine shipped with the item and the function it exists for had no caller
anywhere.** `deal_memory.comps` has been routed since the start. `deal_memory.beside()` — the last
function in that module, whose own docstring calls it *"the shape the underwriting screen wants"* —
was never routed, never in the client, on no screen. Nothing failed, because `test_reachable` asks
whether a MODULE is reachable and `deal_memory` is: the portfolio route imports it. *A module can be
reachable and its whole reason for existing still be unreachable* — `read_p6xml_all` was the same
shape one ring over.

`GET /projects/{pid}/deal-memory/beside` is the route, and the proforma's cost budget is the screen:

```text
🏛 Your own history: this deal's hard cost is $250/SF ($500,000 ÷ 2,000 SF) — inside the range
   your 6 closed project(s) landed in ($225–$275, median $250). A comparison, not a verdict.
```

**It offers one of the engine's three metrics, and the other two are decisions rather than an
unfinished job.** `cost_per_sf` is a unit conversion: a hard cost and a GFA turn into it.
`cost_variance_pct` is not — the nearest thing a proforma enters is a contingency, and *"your
contingency should cover this firm's historical overrun"* is a claim the product would be making in
an underwriting, which is the same call `/schedule/eot` is still waiting on. `schedule_variance_days`
beside an entered `construction_months` would be a category error in matching units, which is the
dangerous kind: both are numbers of time and the screen would look right.

`no_gfa` is its own status rather than folded into `insufficient_history` — load a model versus close
more projects are different remedies, and answering the first with the second sends somebody hunting
for history they already have. `services/api/test_deal_memory_beside.py` holds all of it, including
the anti-vacuity check that the deal on screen is excluded from its own comp set.

**The "by vintage" half was nearly left out, and two gates arguing is what caught it.**
`clientCallers.test.ts` rejected `portfolioDealMemory` — no screen, so a typed method would exist
only to satisfy a gate. Then `test_route_reachability` failed the other way: the new route put the
substring `deal-memory` into the web source, and that rule matches a leaf against the whole blob, so
its frozen entry for `/portfolio/deal-memory` read as *"quietly became called"* while nothing called
it. **A substring test cannot tell which route a string belongs to.**

Neither gate was wrong and neither could be satisfied by wording. Re-reading the item settled it — it
asks for realised outcomes *"(… cost/SF by vintage)"*, and `comps` returns `vintage` per project. The
comp list was in the item all along; wiring only the summary was the half-build. A "which projects?"
disclosure now shows them, newest first, with the excluded count beside them so a partial comp set
cannot read as a whole history. Sharpening the needle instead was measured and rejected: a
two-segment needle is already rejected in that file with numbers, and **328 of 941 routes share a
leaf**, so "a shared leaf decides nothing" would take a third of the surface out of the gate's reach.

Also in this release, and the same shape one level up: **the roadmap and its own gate were blind in
the same place, so they agreed.** The SCALE-SEAM bullet was headed `㉗` while its own next words said
㉗ shipped in v0.3.1086, and the Lane I cell called ㉗ "the only open slice". `MARKS` in
`apps/web/src/shell/roadmapLanes.test.ts` stopped at ㉗, and marks are an optional group on both
sides of that check — so a numeral it cannot spell does not fail to parse, it drops, and item and
lane row degrade to the same bare code. Measured both ways: a mismatch *inside* the vocabulary fails
correctly; one *outside* it passed 13 of 13. `MARKS` now spells ㉘ (29 item codes before, 29 after —
nothing moved, which is the point), and forgetting to widen it next time fails a test instead of
quietly narrowing what is enforced.

## v0.3.1111 (2026-08-27) — the viewer could not run offline, and nothing on screen said so

**A non-negotiable was being broken by a transitive import, and it was found by opening the app in a
browser rather than by reading code.** R36-VIEWER-SUBAPP has carried "not verified live" since slice
4 — `createViewerApp` needs a WebGL context and a Fragments worker, so the tab strip, the spec pane
and the keynote column had never been seen rendered. A headless Chromium settles it: **WebGL 2.0 is
available, all three tabs render, and refusing Sheets with no project open both says why and leaves
the Model tab selected.** The unit tests were right about every one of those.

They could not have caught what the same run found in the first second:

```text
pageerror: Failed to fetch dynamically imported module: .../viewer/app.ts
REQFAIL https://cdn.jsdelivr.net/npm/opentype.js@1.3.4/+esm :: ERR_CERT_AUTHORITY_INVALID
```

`three/examples/jsm/loaders/TTFLoader.js` opens with a **static import of a CDN URL**. Rolldown
cannot bundle a URL specifier, so it emitted it verbatim — as **line 1 of `three-*.js`**, the chunk
every 3D module depends on, reached because `@thatopen/components-front` imports `TTFLoader` for a
`DrawingEditor` font loader this app never constructs. A static import is loaded whether or not it is
used.

The consequence is not a missing font. With no route to jsdelivr the chunk never evaluates, the
viewer's dynamic import rejects, and **nothing renders and nothing reports it** — which is precisely
the failure mode an air-gapped deployment has, and the fourth non-negotiable in `CLAUDE.md` says the
viewer must run fully offline.

`apps/web/src/shims/TTFLoader.ts` is a local stand-in keeping the module's shape and refusing at the
point of use, aliased in `vite.config.ts`. A stub rather than a vendored font parser because
`LengthMeasurement`, `AreaMeasurement` and `AngleMeasurement` are the only things this app imports
from `components-front` and none of them loads a font — so vendoring opentype.js would add a
dependency to make a path work that nothing enters.

**`apps/web/scripts/check-offline.mjs` is the gate, and it greps the OUTPUT.** `vite.config.ts`
already carries the reason in as many words for the vendor split next to it: a config that stops
taking effect still builds, still emits the right filenames, and is wrong. An alias is the same
shape — bump the dependency, rename the upstream file, and it quietly matches nothing. Measured both
ways: with the alias, 85 bundled JS files and zero network imports; with it removed, the jsdelivr
line is back and the check fails on it. It runs in CI after the build, and refuses to pass on a
directory holding fewer than ten JS files, because "0 remote imports" reads identically whether the
bundle is clean or absent.

Also fixed, and the same defect class as the rest of this week: the comment introducing the canvas
mode switch said `specs` **is deliberately NOT registered** — three lines above the registration of
`specs`. True when written in v0.3.918, false from v0.3.920, and it stood for 190 versions because
nothing reads a comment. The test beside it proves the tab is real and could not see the prose
denying it; `canvasMode.test.ts` now fails on a comment that says a registered mode is not
registered.

## v0.3.1110 (2026-08-26) — the pre-GUID markups can be moved, and nothing has to guess a level

The residual limitation recorded in v0.3.1106 is now resolved. Storey markups saved before that release
are keyed `plan:<storeyName>`; the new key is read alongside the old one so nothing disappeared, but
a markup still sitting under a name **still orphans when its level is renamed**.

`POST /projects/{pid}/drawings/markups/rekey-storeys` moves them. It is a route rather than an
alembic migration for a reason that is not preference: rekeying needs a `name → GlobalId` map and
only the project's source IFC holds one. A migration has the database and not the model.

Three things it refuses to guess, each reported by name:

* **`dry_run` defaults to TRUE.** The mapping depends on a model that may have been re-uploaded since
  the markups were made, so the caller sees exactly what would move before anything does.
* **A duplicated storey name is skipped**, not resolved. Two levels called "Level 1" mean the name
  does not identify a GlobalId — and picking either is the same guess, in the other direction, that
  this whole line of work exists to stop making.
* **A vanished storey is skipped.** Nothing to map it to.

A key that is *already* a GlobalId is reported under `already_keyed_by_guid` rather than lumped in
with the unmappable, because a clean second run that reads as a partial failure is a report
misdescribing itself. That also makes the operation idempotent, which is asserted rather than
assumed: `test_markup_rekey.py` runs it twice and checks nothing moves the second time.

**It shipped unreachable, and `test_route_reachability.py` caught it.** The route had no client
caller, which that gate states plainly: *"a route the product cannot call is a feature nobody can
use."* The gate offers an allowlist entry as the alternative, and taking it would have been the wrong
answer here — a one-time backfill that only an operator with `curl` can run is exactly the shape the
gate exists to stop. So it has a real caller: **⟲ Fix legacy keys** in the ☰ Markups grid, which is
where markups across sheets are already listed. It dry-runs, shows what would move and what it
refused to guess, and applies only on confirm — the two-call shape the route was designed for.

*This is the mirror of the defect that motivated the reachability gates in the first place: seven of
eleven things built across v0.3.701–710 shipped with no route at all. Here the route existed and
nothing could reach it.*

## v0.3.1109 (2026-08-26) — a shared saved view now alerts every reader, each from their own visit

R22-REPORT-BUILDER item 4 shipped `SavedView.scope` and stopped deliberately short of alerting anyone
but the author. Its note said why, and was right: `saved_views.last_seen_at` was ONE column on ONE
row, so a shared view in a second person's 🔔 feed would have computed *their* "new since" from **the
author's** last visit — the confidently-wrong-number shape item 3 had just removed one layer down.
It also meant the one person the feed showed a view to was the only person allowed to mark it seen.

`SavedViewSeen` is the per-viewer timestamp that item named: one row per (view, viewer), unique on
the pair, because two rows would make "when did I last look at this" ambiguous and the feed would
answer with whichever the query returned first.

**The migration moves the data and then drops the old column.** Every non-null `last_seen_at` becomes
a row for that view's owner, so nobody's feed resets — an author who last looked on Tuesday still
counts from Tuesday. The column is then removed rather than left in place unread: a populated,
authoritative-looking column that nothing reads is how a later change "fixes" something by reading it
again. The downgrade restores owners exactly; other viewers' visits have nowhere to go in the old
shape, which is precisely the limitation being removed.

The load-bearing assertions are not "a shared view appears in Bob's feed" — a scope filter alone
satisfies that. They are that **Bob's count is Bob's**: Alice marking the view seen leaves Bob's alert
untouched, and vice versa. Mutation-checked — ignoring *whose* visit it was fails both.

`test_view_sharing.py` had pinned the old behaviour on purpose, so the gap stayed visible. That pin is
released **and the release is recorded** rather than the assertion quietly flipped: a pin removed
without a note reads, later, as a leak somebody stopped checking for. What it still asserts is what is
still true — sharing reaches the reader, and does not reach their edit rights or another project.

## v0.3.1108 (2026-08-26) — a section keynote now names the spec section that governs it

R36-VIEWER-SUBAPP's last remaining item, unblocked by v0.3.1107. A keynote said what an assembly
**is** — `200mm MASONRY WALL`, composed from the element's class, material and measured thickness.
The spec section says what **governs** it. Nothing joined the two, so a reader holding a section had
to know the mapping by heart.

    before:   200mm MASONRY WALL
    after:    04 22 00  200mm MASONRY WALL

**What made it reachable was an identity that was already there and being discarded.**
`section_drawing_svg` cut with `cut_baked_classed`, which keeps the IFC class and throws the GlobalId
away — so the frame that builds keynotes had nothing to look a classification up by.
`cut_baked_guided` has carried `(guid, class, polyline)` since R38-PLAN-IDENTITY; the section path now
uses it. That also fixes an accounting gap in passing: the guided cut **logs** meshes that fail to
section, where the classed variant dropped them silently — *"a plan missing a wall renders perfectly;
nothing about it says a wall is missing."*

**The interesting half is when a keynote may NOT cite.** The group is formed by
`(class, material, rounded thickness)`, deliberately, so a wall cut at eight storeys is one keynote
rather than eight. **That partition is not the spec partition**: an interior partition and a
fire-rated shaft wall of the same build-up are identical to the grouping key and specified apart. So
a group cites a section only when **every** member agrees, and an unclassified member counts as a
disagreement — *"I do not know about this one"* cannot license a claim about it. A keynote printing a
section that governs only some of the elements its leader points at is a false statement on a
construction document, and worse than no citation, because a drawing is read as authored.

`element_codes(model, system=None)` is the guid → code map, keyed by GlobalId like every other
identity in this project. It resolves types too: a classification on an `IfcWallType` covers its
occurrences, and a direct classification on an occurrence wins as the more specific statement. The
system-resolution walk is factored into `_rel_system` so `classification_systems`, `project_manual`
and `element_codes` cannot drift into three answers to "which system is this in".

`test_keynote_spec.py` covers both halves, and its **fixture was the thing that had to be fixed
twice**. The first draft used two walls meeting at a corner: they look equivalent to two parallel
ones and are not — a plane of constant y crosses only one, so every group had a single member and the
disagreement case asserted nothing while reporting a pass. The guard now counts the ELEMENTS the cut
caught rather than the labels it drew. Mutation-checked: replacing unanimity with the largest
member's code prints `04 22 00` on a group where only one of the two walls carries it.

## v0.3.1107 (2026-08-26) — the spec manual answered nothing, for every model this project ships

R36-VIEWER-SUBAPP's last remaining item is the **keynote → spec section** link. The premise-check
before starting it found the surface that link would point at is empty.

`specmanual.project_manual(model, system="MasterFormat")` had a default, and its only caller —
`routers/authoring_docs.spec_manual` — passed nothing. So every project got MasterFormat. Measured
across the repository's own corpus:

    58 tracked .ifc files:  57 Uniclass · 1 OmniClass · 0 MasterFormat

**Not one model this project ships declares MasterFormat**, so the spec manual returned zero sections
for all of them — and reported no error, because an empty manual is exactly what an *unclassified*
model returns. The two states were indistinguishable.

**Why nothing caught it.** `test_specmanual.py` passes and always did: it builds a synthetic model and
classifies it *with MasterFormat*, so the fixture supplies precisely the system the code demands. That
is the one-directional gate again — **a check whose population is filtered by the very thing it is
checking for cannot observe that thing being wrong.** It is a good test of the grouping logic and was
never a test of the default.

`project_manual` now resolves the system from the model: an explicit argument wins, else MasterFormat
or OmniClass when present (their codes are the numeric ones `MF_DIVISIONS` describes), else the
most-used system the model actually carries. A model with no classifications keeps the old default and
the old empty answer, which is the true one there.

Three things travel with it, because a non-empty answer that misdescribes itself would be worse than
the empty one:

* **the `note` named MasterFormat unconditionally** — a Uniclass manual described itself as a
  MasterFormat manual. It now names what it read, as does `manual_text`'s "no classified elements" line;
* **division roll-up assumed CSI numbers.** `MF_DIVISIONS.get("Pr")` misses, so every Uniclass section
  filed under a division title that asserts something the code never said. Uniclass codes now group by
  their table (`Pr` → Products, `Ss` → Systems, …) — the twelve table names, not a code dictionary;
* **`available_systems` is published**, so a UI can offer the choice rather than infer it, and
  `SpecManual.system` is documented as the thing to read before treating `division` as CSI.

Both routes take an optional `?system=`, and an explicit system is still obeyed when it yields zero —
asserted, because "auto-detect" that silently substitutes a system that works would replace a visible
wrong answer with an invisible one.

`test_spec_system.py` measures the corpus claim rather than quoting it, so if a MasterFormat-classified
sample is ever added the guard says so instead of letting the case go vacuous. Mutation-checked:
restoring the old default fails five of its assertions.

**The keynote → spec link is not built here.** It is the roadmap's named next item and this was its
prerequisite; building it first would have pointed drawings at an empty book.

## v0.3.1106 (2026-08-26) — markups were keyed on a name the user can change

R36-VIEWER-SUBAPP's sprint row asks for a premise-check before starting. This is the third row in a
row whose premise-check found the row wrong, and the first where what it found was a live defect
rather than a stale sentence.

**Slice 6 shipped keyed on the storey NAME.** Both surfaces — the Drawings room and the viewer's plan
pane — stored sheet markups under `plan:<storeyName>`. Rename a level and every pin on it orphans
silently: the plan renders, nothing is marked, and it reads as *"there was never anything here."*

What makes it worth writing down is how thoroughly the correct answer was already present:

* **the roadmap entry specified it** — *"keying on the storey NAME would look natural and is wrong…
  the key is the storey's GlobalId"*, three paragraphs above the shipped code;
* **the first non-negotiable says it** — reference by IFC GlobalId, never a transient id;
* **the payload always carried it** — `storey_elevations` returns `{name, elevation, guid}` from
  `s.GlobalId`, through `drawingStoreys` and `modelGrid` alike;
* **the client type had been widened to expose it for this exact fix**, with a comment arguing
  against declaring it optional because *"that is precisely where a `?? level.name` fallback gets
  written, reintroducing the rename orphan this field exists to prevent."*

Four statements of the right answer, and the code did the other thing. **A specification written in
the same entry as the work is not a check on the work — only a test is.** So the fallback that
comment predicted is now a test that fails when it is written.

**The key is `plan:<storeyGuid>`.** `modelGrid` already served `levels[].guid`; the level `<select>`
now carries it, and it reaches `PlanPane` as an accessor rather than a value, for the reason
`drawingsSection.ts` documents — a value freezes at panel-build time, before any level exists.

**Nothing already stored disappears.** The pre-GUID key is read alongside the new one and merged.
Switching the key without that would have "fixed" the bug by hiding every markup already saved, which
is the same data loss arriving through the front door. Nothing is written to the legacy key and
nothing is rewritten.

**Residual limitation, stated rather than buried:** a markup created before this release is still
name-keyed and still orphans if its level is renamed. Rekeying it needs a name→GlobalId map that only
the source IFC holds, so it is a backfill rather than a code change. Every new markup is immune.

The test stub was part of the defect's cover. It ignored the key and served the same rows for every
id — modelling an API that does not exist, since `sheet_id` is a column — so the legacy read appeared
to double every pin. Fixed by making the stub key-aware rather than by adding a dedupe to the layer,
which would have hidden the unrealistic fixture behind correct-looking code. Both halves are
mutation-checked: reverting the key fails six tests, and re-adding `?? activeStorey()` fails the one
written for it.

## v0.3.1105 (2026-08-26) — a saved view that cannot be replayed is worse than one that was refused

Review follow-up on R22-REPORT-BUILDER. `validate_view_config`'s docstring promised that **a view is
validated exactly as the query it replays would be — otherwise a view could be saved that the
aggregate route then refuses.** The code kept that promise for field *names* only. `aggregate`
enforces two further rules, and the validator asked neither:

* a non-`count` aggregate needs an `agg_field`;
* `sum`/`avg` need a **numeric** one — it refuses rather than returning the confident `0` SQLite
  gives for summed text.

So three configs saved at 200 and then 400'd when the report was run, measured before the fix:

    {"group_by": "target", "agg": "sum"}                        -> SAVED OK, 400 on replay
    {"group_by": "target", "agg": "sum", "agg_field": "target"} -> SAVED OK, 400 on replay
    {"group_by": "target", "agg": "avg", "agg_field": "target"} -> SAVED OK, 400 on replay

The refusal now happens while the user is still looking at the form. Both rules are re-asked of the
**same resolved field definition** `aggregate` uses rather than re-derived from the name — a second
answer to "is this field numeric" is how two sources of truth start disagreeing, which is the rule
this module's own header states.

`test_view_config.py` covers it, and covers the inverse: `rfi` declares no numeric field, so the
acceptance half could not be expressed there and **refusals alone would be satisfied by a validator
that refuses every aggregate**. The numeric case resolves against whichever module declares a numeric
field, guarded by an assertion that one was found. Mutation-checked — with the new block neutered,
the three refusal cases fail and the three acceptance cases still pass.

Also: the archived R22 entry described item 2 as open ("**Single-module only** … not expressible")
after it shipped in v0.3.1103 — the one item of five that never got its landed line. Corrected, and
the correction records the part that is easy to misread: **`SavedView.module` is still one string.**
The base register is singular by design and the second module arrives as a declared-reference `join`,
which is what keeps the edge coming from the schema instead of from the request.

## v0.3.1104 (2026-08-26) — one answer to "what reports do I have here?"

R22-REPORT-BUILDER item 5, **and the item said the decision itself was the deliverable**: unify
`reports.REPORTS` with the saved-view layer, *or* decide deliberately that they stay separate.

**They stay separate implementations behind one surface.** They are not the same kind of thing:

* a **built-in report is code** — Earned Value, the WIP schedule, a tri-approach appraisal, 56 of
  them. These compute things no query builder expresses. Folding them into saved views means either a
  query language that can do EVM (it cannot) or 56 rows of config that secretly dispatch to Python,
  which is a registry with extra steps;
* a **saved view is data** — a user's query, authored without an engineering ticket, which is the
  entire point of R22-REPORT-BUILDER.

The entry's actual worry was *"a second way to make a report, sitting beside the one users already
have"* — and re-reading it against the code, the duplication was never in the implementations. It was
in the **surface**: `GET /reports` was global, knew nothing about saved views, and rendered in its own
panel, so one question got two unrelated answers from two places.

`GET /projects/{pid}/reports/catalog` is the one answer. `kind` is explicit rather than inferred,
because the two differ in what a caller may *do* with them — a built-in renders to PDF at a fixed
path, a saved view is replayed against its module — and a UI that guesses that from the shape of an
id will guess wrong. The saved half obeys the same scope rules as the register's own view list, which
`test_report_catalog.py` asserts against a second user rather than trusting the shared clause.

## v0.3.1103 (2026-08-26) — a report can span two modules, along an edge the schema declares

R22-REPORT-BUILDER item 2 — *"'RFIs against change orders by trade' is not expressible, and that is
most of what a report is."*

`aggregate` takes a `join`, and **the join comes from the schema, never from the request.**
`reference_fields` already lists the edges a module declares, and a reference field stores the
target's id in `data.<field>` — the shape `related_records` has always read. `_join_target` resolves
a requested join against that list and refuses anything else, for two different reasons:

* `_json_text` interpolates the name into a JSON path, so an arbitrary one is an **injection site** —
  the one `_resolve_field` exists to close, one level further out;
* an arbitrary *module* would let a report join two tables no schema says are related, producing a
  number nobody can trace back to the data. That is worse than an error, because it looks like an
  answer.

`group_by` and `agg_field` may then name a field on the joined side as `<module>.<field>`, resolved
against *that* module's declared fields. A saved view carrying `join` is validated exactly as the
query it replays would be — otherwise a view could be saved that the aggregate route then refuses.

### The join is LEFT, and that is a correctness choice rather than a default

A base record with no related record still counts, under a `None` group. An inner join drops it
silently: "RFIs by change-order trade" that omits every RFI *without* a change order answers a
narrower question than the one asked, while looking complete. Mutation-verified — switching to an
inner join turns the fixture's **4 of 4 into 3 of 4**, and the assertion names the missing one.

The test picks its two modules **by resolution rather than by name**, walking the live registry for a
real declared edge (it finds `action_item.responsible_contact → contact`). A fixture naming two
modules by hand would keep passing after the schema connecting them changed.

## v0.3.1102 (2026-08-26) — a saved view can be a project report, and sharing it leaks nothing

R22-REPORT-BUILDER item 4. `SavedView.user` was both the owner **and** the audience, which is what
made the builder — in the entry's own words — *"a personal filter"*.

`scope` separates the two questions that were conflated: **ownership** (`project + module + user +
name`) decides who may write or delete a view; **scope** (`private` | `project`) decides who may read
and run it. Existing rows become `private`, which is exactly what they already were.

### The three ways sharing leaks, each asserted

**Across projects** — every clause is bounded by `pid` and the read route already requires `viewer`
on that project, so a shared view shows nobody a row they could not already list.

**Into edit rights** — visible is not writable. A second user saving under the same name gets their
own row, which is why ownership stays *part* of the key rather than being replaced by it.

**Into the alert feed, where it would produce a wrong number** — and this one is a deliberate
*non*-feature. `last_seen_at` is one column on one row, so a shared view has a single "last opened"
timestamp; showing it in a second person's feed would compute their "new since" from **the author's**
last visit. That is exactly the confidently-wrong-number shape v0.3.1101 removed one layer down, and
re-introducing it while adding sharing would trade one defect for another. Per-viewer alerts need a
per-viewer timestamp — a table this item does not add — so `view_alerts` stays keyed to the owner and
`test_view_sharing.py` pins that, making the gap visible rather than assumed.

### A tautology, caught in the test written to pin the limit

The first draft of that assertion read `all(a["name"] != "Open structural" or True for ...)`. **`X or
True` cannot fail.** Worse, the fixture had Bob owning his own row of that name, so a name-based
check could not have distinguished a leak from his own view even had the clause been real. It now
asserts on **ownership** — every entry in a feed is a view that user owns — with an anti-vacuity
guard that the feed is non-empty first. Mutation-verified: widening `view_alerts` to include
project-scoped rows now fails, naming the foreign view.

## v0.3.1101 (2026-08-26) — the alert feed counted rows the view itself would not show

R22-REPORT-BUILDER item 3. `SavedView.config` was `mapped_column(JSON, default=dict)` and the write
route stored whatever a client POSTed. "filter/sort/column config" was true only in the docstring.

**That was two defects, one cause.**

### The schema

`validate_view_config` resolves every field name through `_resolve_field` and every operator through
`FILTER_OPS` — **the same two the list route uses.** `_json_text` interpolates a field name into a
JSON path, so an unvalidated name is an injection site rather than a typo, and a second validator
would be a second answer to "what is a field". That rule is already written in `aggregate`'s
docstring; this is the third caller to follow it. `MAX_FILTERS` moved from the router to the engine
for the same reason — a view that could store 50 filters would have been refused only when someone
replayed it as a URL.

**Unknown keys are refused, not ignored**, which is what gives the schema a migration path: the key
set is the contract, and changing it becomes a visible act.

### The miscount the schema exposed

`count_records` has taken `filters` since MOD-FILTER, and its docstring names this caller — *"a count
that ignores a filter the list applied reports a total the page cannot account for, and a total is
exactly the number a user trusts without checking."* **`view_alerts` never passed it.** The parameter
was built for saved-view alerts, and the saved-view alert path was the one place it went unused.

Measured on two RFIs differing by one declared field, with a view saved as
`{"filters": [["discipline","eq","Structural"]]}` — which the write route accepted, because nothing
validated a config:

    alert feed total = 2        the view itself shows = 1

The shipped web register only ever saved `{q, state, sort}`, so **no browser produced this** — but the
API accepted filters from any other client, and the new schema positively *invites* them. Fixing the
count is what makes storing them safe: the two had to land together, because either alone makes the
other worse.

### And a dead guard, caught by the test on its first run

The "uncountable" branch — report `total: null` and a reason rather than a wrong number — was
**unreachable**. `view_filters` was tolerant by shape, so an unreadable config returned `[]`, the
`except` never fired, and a legacy row was counted as unfiltered: the same wrong number, by the
guard meant to prevent it. `view_filters` now raises on a config it cannot read, and `view_alerts`
catches that *and* the `HTTPException` from a field the module no longer declares. Both mean the same
thing to a reader: this number cannot be computed, so it must not be guessed.

## v0.3.1100 (2026-08-25) — the re-pin the last release said was the right answer

v0.3.1098 patched two CRITICAL `libgnutls30` CVEs by name and recorded the fix as a treadmill in the
same commit: *"every future CRITICAL in the base will red this gate until the shared digest is
re-pinned to a newer `node:24-slim`. Re-pinning is the right answer and accumulating `--only-upgrade`
lines is not."* This is that re-pin, two releases later rather than left as a note.

    was  sha256:2cf067cfed83d5ea958367df9f966191a942351a2df77d6f0193e162b5febfc0
    now  sha256:a9f5f7c91a432850b2a8a7797adf5eadb6c733ceed61167806cee7ea7fbc29df

All three Dockerfiles move together, which is not diligence but arithmetic: `check-fragments-version.mjs`
B1c (v0.3.1097) asserts they share one base, tag **and** digest, so a partial re-pin fails the build.

### What is verified, and what is deliberately not

The `--only-upgrade libgnutls30` line is **removed**, and whether the new base already carries
`3.7.9-2+deb12u7` **could not be checked before pushing.** Stated plainly because the alternative is
implying a confidence that does not exist: there is no Docker daemon in the agent container, and the
proxy denies image *blob* fetches (`production.cloudfront.docker.com`, 403 at CONNECT), so the layers
cannot be read either.

What manifests *do* confirm: the digest resolves, and it still covers `linux/amd64` — the platform
every Docker build here targets. The new index drops `armv7` and `s390x`, which nothing in this
repository builds for, and that narrowing is itself consistent with a newer Node build.

So the removal was a **hypothesis with Trivy as its adjudicator**, not a guess dressed as a fix. It
was pushed as one and **CI has since ruled: confirmed.**

    massing-converter:pr (debian 12.15)   debian   0   -
    Legend:  '0': Clean (no security findings detected)   '-': Not scanned

The `debian` row reads **0**, not `-` — the OS scan ran (Trivy, 10.7 s, outcome success) and found
nothing, so this is a clean scan rather than an absent one. **And the mechanism is legible in that
line: `debian 12.15`, where the base this replaces was `debian 12.13`.** Two Debian point releases
forward is what carries the patched `libgnutls30`; the `--only-upgrade` line was doing by hand what a
current base does by construction.

**And the scan can answer it at all only because of v0.3.1098.** Before that release this image was in
no build matrix, so re-pinning its base would have been unfalsifiable — the change would have shipped
to ghcr with nothing able to contradict it. A gate's first value is catching the defect; its second is
making the *next* change testable.

## v0.3.1099 (2026-08-25) — the source that gates the build was, for the second time, the source nobody linted

Following v0.3.1098's question — *what else is not covered?* — to the linter.

### The gap

`apps/web/eslint.config.js` lints `scripts/**/*.mjs` **relative to its own base path**, so it reaches
`apps/web/scripts/` and *structurally cannot* reach the repository-root `scripts/`. A flat config
cannot lint above its own directory; pointing it there fails with *"was not found by the project
service"*. So the root `scripts/` was covered by nothing — and it holds
`scripts/check-fragments-version.mjs`, the program CI runs to gate the fragments/web-ifc pin and, as
of v0.3.1097, the shared Node base image.

**That is verbatim PR #219's finding of 2026-08-06, one directory up and _nineteen days_ later:** *"the
only web source nobody linted was the source that gates the build."* Its note is the part that
matters — the directory was ignored *"rather than a decision anyone made about linting build
scripts."* An accident of configuration reads, from outside, exactly like a choice.

*(This entry first said "eleven weeks later", which was simply wrong — 2026-08-06 to 2026-08-25 is
**19 days**. Caught in review. The correction sharpens the point rather than softening it: the same
structural defect recurred inside three weeks, in a repository that had just written the lesson down.
A recurrence at eleven weeks is drift; a recurrence at nineteen days is a pattern the prose could not
prevent — which is the argument for the check.)*

### Enumerating the population found three more, in the same service as yesterday's

Every tracked `.mjs`/`.js` outside `apps/web` is four files: one in `scripts/`, and
`services/converter/src/{cli,ifcToFrag,rvtToIfc}.mjs` — **the IFC→Fragments conversion named in the
first non-negotiable at the top of CLAUDE.md**, read by no linter.

Which makes the converter the least-covered corner of this repository in two independent ways found
hours apart: **its image was built by no CI job (v0.3.1098) and its source was read by no linter.**
Neither caused the other. Both are the same absence, and the second was found only because fixing the
first prompted the question.

The first lint of that source found one issue — `no-useless-escape` on
`objectName.replace(/[^\w.\-]/g, "_")`, the sanitiser for a filename sent to Autodesk APS. **It is
cosmetic**: `\-` and `-` are identical inside a character class, verified across 8,192 code points
with zero behavioural differences before touching it. Reported as what it is rather than dressed up —
the value here is that a linter now reads these files at all, not that this one found a bug.

### The check, and how its own first draft failed

A recurring gap does not want a third careful config; it wants **a check that fails**.
`apps/web/src/shell/lintCoverage.test.ts` asserts every tracked JavaScript file resolves an ESLint
config carrying at least one rule.

**Its first draft ran `eslint . --format json` and treated every path in the output as covered — and
it passed its own mutation.** Removing `services/converter/src/**` from the root config, reproducing
the exact defect the file was written for, left those three files linted by nothing and the test
still went green: ESLint emits a zero-message result for a file it merely *walked past* without
matching any `files` entry, so *"appears in the output"* and *"had rules applied to it"* are
different questions, and the draft asked the easier one.

**A measurement whose population quietly includes the failure case — reproduced inside the test
written to catch that exact shape.** The fix asks ESLint's own config resolution
(`calculateConfigForFile`) for a rule count, which a file ESLint declined to lint cannot satisfy. The
mutation run is the only thing that told the two drafts apart; their PASS lines were identical.

Mutation-verified three ways: dropping the converter globs now names all three files, deleting the
root config fails, and narrowing the population to one tree trips the span guard.

### The check's first CI run failed, on the config that was added with it

`eslint.config.mjs` is tracked JavaScript, and no config linted it — which would have made the root
ESLint config **the one file in the repository exempt from the rule it exists to enforce.** It now
appears in its own `files` list.

**The local run had missed it for a reason worth generalising.** The population is `git ls-files`, so
it contains *tracked* files, and `eslint.config.mjs` had been written but not yet `git add`ed when the
suite was run. CI checks out a tree where everything is tracked, so it saw immediately what the local
run structurally could not. The test was right; the local run was under-populated.

**A `git ls-files` gate cannot see the change being made until it is staged**, so a green from one
before `git add` is weaker than it looks. That applies to most of the gates in this repository —
`test_claude_md_gates`, `roadmapLanes.test.ts`, `test_file_sizes` and this one all derive their
population the same way.

### Also

`npm run lint` at the repo root, wired into CI immediately before the existing web lint — the step
that lints the program the step above it runs. And `apps/web/public/coi-serviceworker.js` (Guido
Zuidhof, MIT) joins the excluded list beside `src/vendor/`: third-party source vendored verbatim is
not ours to restyle. **That entry exists because the check found the file on its first execution.**

## v0.3.1098 (2026-08-25) — the one Dockerfile no job has ever built, and the hardening that never ran

Following the v0.3.1097 Node-base fix to its cause. **`services/converter/Dockerfile` is built by
nothing** — not on a pull request, not on a push to `main`, not on any event — and it has not been
buildable at all since v0.3.936.

### The image cannot be built

v0.3.936 is titled *"drop root in the converter image"*. It added:

    RUN addgroup -S app && adduser -S -G app app && chown -R app:app /app
    USER app

That is BusyBox/Alpine syntax. This image is `node:24-slim`, which is Debian, and Debian's
`adduser` is a Perl script whose short options are Getopt::Long abbreviations. Run on the Debian
family:

    $ addgroup -S app
    Option s is ambiguous (shell, stderrmsglevel, stdoutmsglevel, system)
    $ adduser -S -G app app
    Option s is ambiguous (...)   Option g is ambiguous (gecos, gid, group)

Both exit non-zero, so the `RUN` fails and the build stops there. **The hardening that commit
describes has never run anywhere, because the image it hardens has never been produced.** The file
was never Alpine-based — checked back to the initial commit — so this was wrong on the day it
landed. Now `useradd -m -u 10001 appuser`, the same idiom and the same uid as
`services/api/Dockerfile`, which is Debian too and does build.

### Why nothing said so, and it is the same shape again

`ci.yml`'s container matrices listed `api` and `web`. `docker-scope`'s path filter is
`(^|/)Dockerfile$|...`, which **does** match `services/converter/Dockerfile`. So editing that file
*triggers* the container jobs, and those jobs then build the two images it did not change:

    apps/web/Dockerfile              filter-matches=True   in-matrix=True
    services/api/Dockerfile          filter-matches=True   in-matrix=True
    services/converter/Dockerfile    filter-matches=True   in-matrix=False

`test_container_pr_gate.py` exists to keep the filter and the matrix in sync and asked one
direction: *does the filter match every Dockerfile in the matrix?* That catches a Dockerfile that
**moved**. It cannot catch one that **exists and was never added**, because such a file is in
neither list being compared — outside the population entirely. Its own rule 1 anticipated *"a third
image added to the publish matrix"*: a third image entering the **matrix**, not a third Dockerfile
entering the **repository**.

**This is the fifth instance of one shape in this release range**, and they are worth reading
together rather than as five coincidences — a check whose population was defined so that the failure
it exists for could not appear in it:

| gate | the population it chose | what that excluded |
|---|---|---|
| `test_lock_satisfies_requirements` (2026-08-01) | `requirements.in` | the floors in `services/data` |
| `test_lock_satisfies_requirements` (2026-08-07) | pin ≥ floor | a floor that is too **low** |
| `docsCurrent.test.ts` (v0.3.1096) | README rows present in the manifest | a row for a **removed** package |
| `check-fragments-version.mjs` (v0.3.1097) | the two version ARGs | the `FROM` line above them |
| `test_container_pr_gate.py` (here) | Dockerfiles in the matrix | a Dockerfile **not** in the matrix |

Four of the five filtered their input by the very thing they were checking it against.

### The fix

`converter` is in both matrices, so the image is built on every PR that touches a Dockerfile and
built, scanned and published on `main`. Rule 3 gains its converse, derived from `git ls-files` so a
hardcoded list cannot rot: **every Dockerfile the filter triggers on must be one the matrix
actually builds.** Anti-vacuity guarded on the `git ls-files` result.

Mutation-verified two ways. Reverting the matrices to their previous state — the live defect — fails
the new assertion **and nothing else in the file**, which is the claim about invisibility stated as
a test result. Adding `converter` to the publish matrix only fails rule 1 instead.

### What the first build revealed — a CRITICAL CVE, shipped by the base image

**CI built this image for the first time in this pull request, and that first build immediately
earned its keep.** The `useradd` fix was correct — the build ran to completion — and then the Trivy
gate, also running against this image for the first time, failed it:

    tar (package.json)  CVE-2026-59873  CRITICAL  fixed  installed 6.2.1  fixed in 7.5.19
    node-tar: Denial of Service via crafted gzip bomb

**Nothing this Dockerfile installs is `tar`.** A clean `npm install` of `@thatopen/fragments@3.4.7`
and `web-ifc@0.0.77` resolves seven packages, none of them tar — verified by running it. The
vulnerable copy is `/usr/local/lib/node_modules/npm/node_modules/tar`, **vendored inside npm**, which
`node:24-slim` ships.

The reason the other two images are clean is structural, and it is the same reason they were never
caught by this: **the converter is the only single-stage image in the repository.** Its base *is* its
runtime, so the whole toolchain publishes with it. `services/api/Dockerfile` takes exactly two things
out of its node stage — `/usr/local/bin/node` and `/conv/node_modules` — and `apps/web/Dockerfile`
ships nginx with only `dist`. Neither has ever shipped npm.

So npm, corepack and the npm cache are removed in the same layer that uses them. The runtime keeps
the `node` binary and the resolved `node_modules`, which is all the ENTRYPOINT invokes — the same end
state the other two reach by being multi-stage, and a smaller attack surface besides, which is what
v0.3.936 was reaching for when it added the non-root user it could not build.

### ...and then two more, in the base OS

With npm gone, the node-package scan came back clean and the **OS** scan failed instead:

    libgnutls30  CVE-2026-33845  CRITICAL  fixed  3.7.9-2+deb12u6 -> 3.7.9-2+deb12u7
    libgnutls30  CVE-2026-42010  CRITICAL  fixed  3.7.9-2+deb12u6 -> 3.7.9-2+deb12u7

Same root cause as the npm one, one layer down. **Pinning a base image by digest (SEC F4) buys
reproducibility and costs currency**: the apt packages inside a pinned image are as old as the day
it was built and keep accruing CVEs while the digest stays perfectly honest. The other two images
never had to reckon with that, because their Debian layers stay in a build stage and are never
published. This one publishes its base, so it inherits the base's CVEs.

Upgraded by name rather than by a blanket `apt-get upgrade`: the scanner names the package and the
fixed version, so the change stays bounded and reviewable, where a blanket upgrade would move an
unbounded set of packages in an image nobody can build locally.

**Recorded as a treadmill, because that is what it is.** Every future CRITICAL in the base will red
this gate until the shared digest is re-pinned to a newer `node:24-slim`. Re-pinning is the right
answer and accumulating `--only-upgrade` lines is not; the digest is shared by all three Dockerfiles
and asserted by `scripts/check-fragments-version.mjs` B1c, so it is one coordinated change when it
comes.

### What this says about the gate

Three CRITICAL, fixable CVEs — one vendored inside npm, two in the base OS — were sitting in an
image that `main` publishes to ghcr. **Nobody triaged them and decided they were acceptable. No scan
had ever been pointed at that image.** A finding cannot be dismissed, or accepted, or even seen, by a
check that never runs; and the check never ran because the file was in the trigger's population and
not in the matrix's. That is the whole argument for the assertion this release adds, stated in CVEs
rather than in principle.

## v0.3.1097 (2026-08-25) — a floor that is too low satisfies every check written to catch a floor that is too high

The dependency half of the full branch/PR review. **272 of 340 pull requests merged; 68 closed
without merging.** Sixty-two of those 68 are Dependabot proposals superseded by later, higher bumps
that did land, and four are deliberate declines (the `@thatopen` group, per the version-coupling pin
CLAUDE.md calls the #1 risk here; Python 3.14; TypeScript 7; Node 26). Two feature pull requests
(#210/#211, #260) were traced into `main` by content — #260's `git ls-files` claim resolver and its
`!services/api/src/aec_api/main.py` carve-out are both present, so nothing was left stranded.

**Six of the remaining closed pull requests left something behind, and it is the same defect six
times.**

### Five of twelve shared packages had drifted apart

`services/api/requirements.in` and `services/data/requirements.txt` both declare floors, and both
are read by `test_lock_satisfies_requirements`. Twelve packages appear in both. Five disagreed:

    defusedxml     requirements.in >=0.7.1     services/data >=0.7       (lock 0.7.1)
    ifcopenshell   requirements.in >=0.8.0     services/data >=0.8.5     (lock 0.8.5)
    manifold3d     requirements.in >=3.5.2     services/data >=2.0       (lock 3.5.2)
    rdflib         requirements.in >=7.1       services/data >=7.6.0     (lock 7.6.0)
    reportlab      requirements.in >=5.0.0     services/data >=4.0       (lock 5.0.0)

**They disagree in both directions**, which is what makes this drift rather than a decision: nobody
deliberately requires `ifcopenshell 0.8.0` in one file and `0.8.5` in the file beside it. Two of the
five carry a stated security reason in the very file that then declares the weaker floor —
`defusedxml` is commented "XXE / billion-laughs hardening" in one and "XXE-safe parser for untrusted
P6 (PMXML) schedule uploads" in the other, and only one of those lines actually delivers 0.7.1.

### Why nothing was broken, and why that is the problem

The lock pins at or above the higher floor in all five cases, and the lock is the only thing
installed. **The runtime was right, so the declaration could stay wrong indefinitely.** It becomes
real the moment the lock is recompiled: pip resolves against these files, so with `defusedxml>=0.7`
written down a fresh resolution may pick 0.7 while every check stays green.

It also explains six pull requests closed rather than merged (#37, #38, #40, #89, #90, #92). Each
raised a floor in `services/data/requirements.txt`; each was correct that the lock already carried
the version; and closing them left the *declaration* behind. **"Already covered by the lock" is a
true answer to the wrong question** — a floor is not a report of what is installed, it is the
constraint the next resolution is bound by.

`test_lock_satisfies_requirements` could not have caught it. Its existing check asks whether the pin
is *at least* the floor, so **a floor that is too low satisfies it for free**. Its docstring already
records two incidents, both in the opposite direction, both from the half of its claim it had left
unstated. It now also asserts that two files declaring the same package declare the same thing — a
deliberately narrow claim with one unambiguous right answer and no resolver required. Anti-vacuity
guarded (a rename that stopped the two files sharing packages would otherwise pass over an empty
set, reporting "all 0 shared packages agree" — demonstrated live in the mutation run) and
mutation-verified both ways.

### The Node base image, one line above the ARGs that were already gated

`scripts/check-fragments-version.mjs` gates the fragments/web-ifc ARGs across
`services/api/Dockerfile` and `services/converter/Dockerfile`. The `FROM node:` line sits directly
above those ARGs and was gated by nothing.

Dependabot raised both converter images to `node:25-slim` together (#117, #116; both merged
2026-07-31). Four days later the api one went back to `24-slim` in an unrelated release, with a
comment giving the reason — 25 is an EOL major with no security patches, both manifests declare
`engines.node >= 24`, CI runs 24. **That comment said "one Node runtime across the product", and it
was false as it was written**: `services/converter/Dockerfile` was still on 25-slim, and stayed
there for 25 days while Dependabot re-proposed the bump (#227, closed).

A reason applied to some of the files it argues about is the "one rule, some of the doors" shape
this repository keeps finding — the SSO domain allowlist (PR #339) and the three unguarded sign-in
doors (v0.3.1093) are the same sentence. **A decision recorded in a comment protects the file the
comment is in.** All three Dockerfiles now share one base, and B1c asserts tag *and* digest, because
`node:24-slim` is a moving tag and two files naming it without the same digest can still build two
different images. Mutation-verified three ways: a different major, a different digest under the same
tag, and a Dockerfile that stops naming a Node base at all.

### A limit recorded rather than fixed

The repo-root `scripts/` directory — which holds `check-fragments-version.mjs`, a gate CI runs — is
**not linted**. `apps/web/eslint.config.js` covers `scripts/**/*.mjs` relative to its own base path,
so it reaches `apps/web/scripts/` and structurally cannot reach the root one. That is PR #219's finding
("the only web source nobody linted was the source that gates the build") one directory up, and
fixing it needs a root ESLint config rather than a glob edit, so it is named here instead of widened
into this change.

## v0.3.1096 (2026-08-25) — a version table that filtered out the only row that could be stale

Two review findings on the v0.3.1091–1095 pull request, both real, both the same shape: **a check
whose population was defined so that the failure it exists for could not appear in it.**

### The README table check could not see a removed dependency

`docsCurrent.test.ts` asserts `apps/web/README.md`'s pinned-version table against
`apps/web/package.json` — the gate added at v0.3.1091 after six of that table's ten rows turned out
to be wrong. It parsed the rows, then dropped every row naming a package the manifest does not
install, with the comment *"not this check's business"*.

**That filter is derived from the thing being checked, so it defines the failure out of the
population.** Delete a dependency from `package.json` and leave its README row behind, and the row
describing a package nobody installs is silently excluded from the comparison — the stalest row the
table can hold is the one row the check refuses to look at. Nothing is wrong today (all ten rows
resolve), so this was latent, not live.

Every row is now accounted for: named-and-installed, or named-and-not-installed and **reported**.
Mutation-verified — adding a row for an uninstalled package fails the suite and names it; removing
the row passes again.

**This is the third recorded instance of the one-directional gate in this repository**, and worth
naming as a class rather than as three coincidences. `test_env_documented` is bidirectional
deliberately. `test_lock_satisfies_requirements` carries two incidents in its own docstring, both
from the half of its claim it left unstated. A check that filters its input by the source of truth
has stopped asking its own question.

### The roadmap said the next action was work the same release had finished

§Band 1 read *"The last sweep that filled it was 2026-08-01"* and *"the honest next action for this
band is to run one"* — four lines above the three sweep records from **2026-08-25** that this very
release range added. A reader picking up Band 1 would have been sent to run a sweep that had just
run. The sprint table said it twice: row 1 still ranked *"a correctness sweep — refill Band 1"*
first, on the premise *"the last sweep was 2026-08-01, ~270 releases ago"*.

Both re-derived. The sprint row is **struck through rather than deleted**, because that table's own
preamble says its *predictions* are the part worth checking — and this one was right: its
premise-check ("pick the axis before starting") is what made two of the three axes produce a defect.

**A staleness clock that nobody winds when the work happens is the A29-GUIDE-UNDERLAY defect** —
*"(in flight, PR #199)"*, which read as current for 214 releases after the feature shipped. v0.3.1091
archived that entry and then left a date next to it that had gone false in the same commit.

## v0.3.1095 (2026-08-25) — a distribution statement whose parts did not add up to its own total

**The money sweep**, the third and last of the axes Band 1 names. It found a live defect, in the
JV waterfall.

### The defect

`run_waterfall` emits a row per period: `distributable`, and the `lp` / `gp` shares it was split
into. Each was rounded on its own:

    "distributable": round(cash, 2), "lp": round(lp_take, 2), "gp": round(gp_take, 2)

Three independent roundings of what is arithmetically one identity — every tier allocates out of
`cash`, so `lp_take + gp_take == cash` before rounding. Rounding the parts separately breaks it.
**Measured over 399 distribution periods on awkward fractions: 52 of them, 13%, had
`lp + gp != distributable`**, a penny out in both directions:

    distributable 1051.33   lp 1051.10 + gp 0.24 = 1051.34   (+0.01)
    distributable 1053.67   lp 1052.97 + gp 0.69 = 1053.66   (-0.01)

**A partner reading a distribution statement whose parts do not add up to its own total has found an
error in the document.** Being a penny is not a defence — the same class as the retainage convention
`test_money_spine` pins, whose docstring says *"a pay application out by a penny is rejected, which
makes this a document defect rather than a rounding curiosity"*. This is real money to real
partners, and it is what a promote gets argued from.

The capital-call branch had the identical shape and got the identical fix.

### `money.allocate` existed for exactly this, with no caller here

`test_money_wire` already describes the helper: *"the parts sum to the whole, and the leftover cents
are distributed by a defensible rule rather than dumped on whoever sorts last."* The waterfall never
called it. Also `q2` on the total rather than `round()`: `allocate` takes its total half-up and
`round()` is half-even, so a bare `round(cash, 2)` could disagree with its own parts by a cent at
precisely the `.xx5` boundary the fix is about — two conventions inside one statement, which is the
defect `test_money_spine` was written about.

### Why this axis needed a different kind of sweep, and what that says

The authz and concurrency sweeps each had a population you could enumerate and read — 43 routes,
36 get-or-create sites. **This one does not.** `round(x, 2)` appears **732 times** under
`services/api/src`, and converting them would be the mistake R39-UPLOAD-CAP-APP's entry names:
*a count is not a work list*. Most are display figures where half-even versus half-up changes
nothing anyone can act on.

So it was swept **by a property instead of by a population**: *where money is SPLIT, do the parts
still add up?* That has a yes/no answer, needs no reading of 732 sites, and is exactly the boundary
where a rounding difference stops being cosmetic and becomes a wrong document. `accounting.py` was
checked against the same question first and is sound — each journal entry debits and credits the
same figure, so there is no asymmetry to drift.

**The three sweeps did not want the same method, and assuming they would was the thing to avoid.**

### The gate, and both mutations

`services/api/test_waterfall_cents.py` asserts the identity over a sweep of deliberately awkward
fractions rather than pinning frozen figures — a fixed expected-value table would freeze today's
arithmetic and say nothing about the identity, and a sweep of round numbers cannot produce the
defect at all.

Mutation-checked two ways, and the second is the one that matters: reverting to independent rounding
fails with **52 of 598** periods off by a cent; and satisfying the sum by **collapsing the split**
(handing the LP everything) is caught by a separate assertion that the GP still receives a real
promote. A gate that only checked "the parts add up" would have applauded a waterfall that pays the
GP nothing.

## v0.3.1094 (2026-08-25) — a ratchet went red about the wrong thing, loudly enough to expose the right one

**v0.3.1093 turned `test_mutating_get` red, and the interesting part is not the red.** Moving
`db.add` out of the OAuth callback into `auth.get_or_create_sso_user` changed the route's recorded
ops from `('add','commit')` to `('commit',)`, and that ratchet exists to notice exactly such a
change. Fixing it needed one line. Asking *why* the shape could change at all found a hole that had
been open since the massing.cloud door shipped.

### The scan only ever read the route's own body

`test_mutating_get` guards the CSRF property: the session cookie is `samesite=lax` with no CSRF
middleware anywhere, and Lax **sends the cookie on a top-level GET** — so a mutating GET is
triggerable by a link in an email, and the whole defence is a property of the route table.

Its AST walk covered the route function and nothing else. **Any write moved one call away left its
remit** — and one already had:

    GET /auth/cloud/callback   ->  _link_account()  ->  db.add(User(...)), db.commit()

The route body touches the session **not at all**, so a GET that creates a user was invisible to the
gate from the day that door shipped. The assertion *"no GET route touches the DB session without a
written reason"* was passing over it, which is worse than not having the assertion: it reads as
coverage.

The scan now follows **same-module** helper calls, depth-limited and cycle-safe. Cross-module calls
remain invisible, stated as a limit rather than solved — widening it means resolving imports, and a
scanner that guessed which `foo()` it is would be worse than one whose blind spot is written down.

### Four unreviewed GETs, now reviewed

Following helpers took the population from 5 to 9. The four new ones are all `cloud.py`, and each
was read rather than baselined on assumption:

- **`/auth/cloud/callback`** creates a user and writes the link. Safe for the same reason the OAuth
  callback is: it must be a GET because the broker chooses the method, and the authority is the
  broker's one-time code plus the PKCE state, not our cookie. A forged link carries neither.
- **the three `/cloud/library/*` reads** commit only because `_fresh_access_token` rotates the
  **caller's own** massing.cloud token at expiry and must store the rotated pair — refresh tokens
  rotate on use, so dropping the new one strands the link. Nothing an attacker supplies is written.
  The residual is stated instead of waved away: a cross-site GET can force a rotation, whose worst
  case is the victim's own link needing a re-sign-in. A nuisance, not an escalation, and making
  these POSTs would stop the library being browsable.

### Mutation-checked both ways

A new GET whose only write sits one call away — the precise blind spot — is now caught. And
reverting the scan to body-only makes all four `cloud.py` entries go **dead**, which the
"BASELINE carries no dead entries" check flags: the two halves corroborate each other, so the new
entries cannot be quietly kept by a scanner that stopped finding them.

**The lesson is about ratchets, not about GETs.** This one could only ever fire on a route it could
already see. It fired about a cosmetic change to a route it *could* see, and following that question
one step led to the route it could not. **A gate that goes red for a boring reason is still worth
reading properly** — the boring reason was bookkeeping, and the answer underneath it was a hole.

## v0.3.1093 (2026-08-25) — three sign-in doors, one seeding race, and a test that took three drafts to mean anything

**The concurrency sweep**, the second of the three axes Band 1 names. Unlike the authz sweep one
release ago, this one found a live defect.

### The defect

OAuth, SAML and the massing.cloud broker each auto-provision a local account on first sign-in, and
all three did it the same unguarded way:

    u = db.get(User, email)
    if u is None:
        u = User(username=email, ...)
        db.add(u)

`User.username` is the **primary key**. Two concurrent *first* sign-ins for one person — two tabs,
two devices, a retried callback — both read `None`, both INSERT the same key, and the loser's
`commit()` raises `IntegrityError`. **The person who did nothing wrong gets a 500 on a legitimate
login.** A retry then succeeds, because the winner's row exists by then, which is exactly what makes
this easy to dismiss as a blip instead of finding.

**Seeding is the one moment no row-level mechanism can protect, because there is no row yet** — the
sentence `modules._next_ref` already carries about its ref counter. This is the third instance of
that pattern in this codebase, after `_next_ref` and `rbac.consume_stepup`, and the fix is theirs:
INSERT inside a SAVEPOINT so the refusal stays local, then re-read and use the winner's row.

**One helper, not three copies** — `auth.get_or_create_sso_user`. The defect this repository keeps
finding in these three doors is *one rule applied at some of them*: `AEC_OAUTH_ALLOWED_DOMAINS` held
on four doors and was bypassed by the fifth (PR #339), and this race was present at all three. A
fourth sign-in path should have to call the helper rather than re-derive it.

### How the sweep found it

`test_race_conditions` names the shape its two defects share — *"read state, decide, write, with
nothing holding the world still in between"*. Scanning for that shape across `services/api/src`
(a lookup, an if-absent branch, an INSERT inside it, no savepoint) returned **36 candidates**; only
**3** savepoints exist in the whole tree. The three sign-in doors were the ones where a primary key
turns the loser's refusal into a 500 on a user-facing action.

### The test took three drafts, and the first two were worthless

**Draft 1 passed against the broken code.** It committed the competing row *before* calling the
helper, so the helper's own lookup already saw the winner and never reached the INSERT. Twenty-one
green assertions, proving nothing — the same trap `test_stepup_race` records about *its*
predecessor, in a new costume.

**Draft 2 deadlocked.** Committing the competing row from a second connection while the loser's
transaction is open is not a race on SQLite, it is `OperationalError: database is locked` — the
constraint `test_race_conditions` states in its own docstring and which this file had to rediscover.

**Draft 3 reproduces the STATE a lost race leaves, not the concurrency that causes it**, which is
what `test_race_conditions` settled on for the same reason. The winner's row is committed first, and
the loser's session is made to read as though it had looked before that commit — its first
`Session.get` for that username returns `None` **once**, and an assertion checks that exactly one
answer was faked. Everything after is real: a real INSERT, a real primary key, a real
`IntegrityError`, a real savepoint rollback.

**Only the mutation run separated draft 3 from drafts 1 and 2.** Reverted to the unguarded shape it
now fails with `UNIQUE constraint failed: users.username` **and** `PendingRollbackError` on the
following commit — the second one meaning the `auth.sso_login` audit row is silently lost. That is
the failure `rbac.consume_stepup`'s docstring calls the nastier of the two: *a security control
quietly erasing its own evidence while still reporting the correct outcome.* It is asserted
separately here for exactly that reason.

**A test that cannot fail is not evidence, however many PASS lines it prints.**

## v0.3.1092 (2026-08-25) — the id in the path is not the project's, it is the resource's

**Sprint 1 of the re-cut roadmap: an authorisation sweep.** Axis picked before starting, as that
sprint row's own premise-check demands — two of the three subsystems added since the last sweep
(2026-08-01) are auth-adjacent.

**No live hole was found. The gate is the finding.**

### The blind spot every existing authz gate names about itself

Four gates guard this surface, and each closed one way a project id arrives by a route other than
the path — `test_global_authz` (global mutating routes), `test_global_mutating_authz` (that they
actually refuse anonymity), `test_body_pid_authz` (a `pid` in the request BODY), and
`test_protected_prefix_coverage` (a new top-level prefix outside `_PROTECTED_PREFIXES`). All four
docstrings contain some form of the same sentence: *a route with no `{pid}` in the PATH is outside
`test_route_authz`'s remit entirely.*

**The one nobody had closed is that the id in the path is not the project's — it is the
resource's.** `GET /attachments/{aid}/download` names an attachment, which names a project.
`PUT /proforma/scenarios/{sid}` names a scenario, which names a project. There is no `{pid}` for
`require_role` to read, so the dependency cannot be applied and the walker never looks.

### What the sweep measured

Enumerated from the live app: **43 routes** have a path parameter, no `{pid}`, and no role gate.
**All 43 are correctly protected today** — this release fixes no defect and should not be read as
though it did:

| how | count |
|---|---|
| a real admin/platform-admin/SCIM dependency | 20 |
| authorised **inside the handler body** | 11 |
| `require_identified` — identity, by a recorded decision | 4 |
| deliberately public (OAuth redirects, `/shared/{token}` capability URLs) | 8 |

Each of the 11 and each of the 8 was read rather than inferred. `/families/{key}/types` looked like
the odd one out and is not: it serves the shared family catalog, which is global content with no
project data in it.

### Why 11 correct routes are still a finding

They are correct **only because of hand-written call-site checks that no gate can see** — and this
exact class has failed here twice in three weeks. `_scenario_for`'s own docstring records the first:
`_can_read` "was called by **2 of the 8** `{sid}` routes… The other six — share, update, clone,
review, forecast, draw-package — **fetched by id and acted, with no ownership check at all**."
`/proforma` is in `_PROTECTED_PREFIXES`, so anonymous callers were refused and every route *looked*
guarded; what was missing was authorisation, not authentication. The second is the massing.cloud
sign-in door (PR #339), where a domain allowlist held on four doors and was bypassed by the fifth.

That docstring also says the helper exists "so that a ninth route cannot be added without answering
the question." **That is a convention, and a convention is what has just failed twice.**

`services/api/test_resource_id_authz.py` freezes the four buckets and pins each in-handler route to
the specific helper it calls — not to "some check", because the failure it catches is a refactor
dropping the call while the route keeps working for the person testing it, who is a member of the
project. Both directions, like `test_env_documented`: a new route in this shape fails until someone
says which bucket it is in, **and** a listed route that no longer exists fails too, so the lists
cannot rot into a place where things are parked and forgotten.

Mutation-checked three ways, each red then green again: dropping `_scenario_for` from `clone`,
adding an unguarded `/proforma/zzfake/{zid}`, and leaving a deleted route in the declared list.

**It names its own limit.** It cannot tell `_can_read` from `_can_write` — a read helper where a
write helper was needed would pass. `_can_write`'s docstring is about exactly that confusion
("Read permission is not write permission, and reusing one guard for both is the quiet way to grant
the second while auditing only the first"), so the distinction is real and stays with review. A gate
claiming to settle it would be worse than one that names the gap.

**Band 1 stays empty, and the sweep is what makes that mean something** — it was last defensible on
2026-08-01 and is defensible again on the authz axis as of today. **Concurrency and money were the
other two candidate axes and remain unswept.**

## v0.3.1091 (2026-08-25) — a status glyph is a note to a reader; only the move is a change to the file

A full-repo reconciliation. Nothing here is a new capability: it is the record catching up with the
code, plus four gates so the same drift fails a build next time instead of being found by reading.

### The roadmap was carrying 600-odd lines of finished work

**Twenty-one shipped entries moved to `docs/roadmap-completed.md`.** Twenty were already marked ✅,
and **18 of the 21** were named in lane-table cells — the table an agent reads to choose what to pick
up. The phrase *"pending archive"* appears **17** times in the roadmap they came from: **14 in those
lane cells**, 3 in the item bullets. `roadmap.md` held **30** open items in **3,715** lines; it holds
**28** in **3,084**.

**Nothing could have caught them**, and that is the finding rather than the count.
`roadmapLanes.test.ts` deliberately skips ✅ lines when it builds the open population, so a shipped
item that stays put is invisible to the only check that reads the file. **A status glyph is a note
to a reader; only the move is a change to the file.**

**The twenty-first was not marked at all.** A29-GUIDE-UNDERLAY ③ read *"(in flight, PR #199)"* for
**214 releases**. PR #199 merged 2026-08-06 and the feature shipped in v0.3.875. A pull request is
the one staleness clock in that file with a real timestamp attached, and nothing consulted it. It is
worse than a stale ✅: *"in flight"* reads as **someone else has this**, so it actively deterred the
reader who would have found it done.

**R43-MASSINGBILL-CORE was being counted twice** — a second bullet opening with the same code, for
the kit review the live entry rests on. `itemCodes()` collects into a `Set`, so the duplicate
collapsed and the total came out right for the wrong reason. v0.3.1073 shipped as *"two entries for
one item, again"*; this was the third time, surviving because the check that would see it
de-duplicates before it counts.

### The CHANGELOG had four orphan headers

A `## vX.Y.Z` line sitting directly on top of another, with one body between the two — the v0.3.1019
nineteen-branch integration renumbered colliding releases by splicing new headers **above** the old
ones instead of replacing them.

**`docs/roadmap.md` already carried that exact lesson** — *"replace between the section markers,
never splice at a matched string"* — written after scripted edits produced three duplicate NOW
sections. It was written about `roadmap.md`, and it did not travel. **A lesson recorded as prose
about one file does not protect the file next to it.**

`services/api/test_changelog_current.py` now checks the changelog's *structure*: no orphan headers,
headers newest-first, no entry duplicated, and version reuse pinned by a **down-only ratchet** to the
one genuine historical collision — two commits really did both ship as v0.3.1019, so renumbering one
would invent a release that never existed. All four mutation-verified.

### Three toolchain floors had moved under notes phrased as advice

- **RT-NODE-LANE was gated on a user action the user had already taken.** It read *"CI is on Node 22;
  the local Node is still 20.3.1 (user action), then unpin eslint off 9.39.5, then Vite 6→7 (defer
  Vite 8)"*. Measured: CI pins **Node 24** in all five workflows that set a version, both manifests
  require `>=24`, eslint is **10.8.1**, and Vite is **8.2.1** — the version it said to defer. **An
  entry blocked on an external event has no mechanism to notice the event happening**; every other
  kind of staleness eventually trips something, but not being worked on is a gated item's expected
  state.
- **Python's floor is `>=3.12`, not "prefer 3.11+ if available".** `requirements.lock` pins
  `numpy==2.5.2`, and numpy dropped <3.12 at 2.5.0 — so on 3.11 the install does not degrade, it
  fails: `No matching distribution found`. Found by building the venv, which is the only way this
  kind of claim can be checked.
- **`apps/web/README.md`'s pinned-version table was wrong in six of ten rows.** It is the table
  CLAUDE.md calls the project's #1 risk — the components ↔ fragments ↔ three coupling. Its `vite`
  row was wrong three times in one cell: it named 6.4.3, declared the repo pinned to v6, and
  justified that with *"this machine has 20.3.1"*. The table was last **edited** at v0.3.1048, in a
  commit about colouring plans by discipline — *edited while stale, not merely left alone.* **A
  stale row that carries its own reasoning is worse than a stale number**, because the reasoning is
  what stops the next reader checking. `docsCurrent.test.ts` now asserts every row against
  `package.json`.

### Two build warnings, one of them the shape of a silent no-op

- **`advancedChunks` → `codeSplitting`.** Rolldown deprecated the name; the build printed it on
  every run and still split correctly. That is the same trap the config's own comment describes one
  rename later — *"a vendor split that silently stops splitting is the worst kind of build
  regression"*. Verified the way that comment demands, by grepping the **output**: chunk hashes and
  `WebGLRenderer` counts (41 in `three-*.js`, 0 in `thatopen-*.js`) are byte-identical across the
  change.
- **`vendorAlias` imported without a file extension** in `vite.config.ts` / `vitest.config.ts`,
  which Vite's native config loader warns on.

### The public status page had three sections titled "Recently shipped"

`docs/status.html` — the page the landing page links as *"What's shipped"* — carried three of them,
oldest first: v0.3.298–306, v0.3.911–929, v0.3.988–1018. **The same splice-instead-of-replace defect
as the CHANGELOG, on the public site.** One current wave (v0.3.1019–1089) now leads; the rest are
retitled as dated earlier waves and ordered newest-first.

One card also **contradicted the roadmap**: it said the viewer sub-app work *"closed the rail arc"*,
while R36-VIEWER-SUBAPP is open as *"the remaining half of the rail arc"*. The page now says what
shipped and names what has not.

### And the archive pass broke a gate, which is the best thing that happened here

Rewriting Band 1 **deleted** its summary bullet instead of moving it, and `test_env_documented` went
red: the phrase *"`properties.py` rejects over `AEC_PROPS_MAX_MB` before parsing"* inside that bullet
was the **only** mention of the flag anywhere the gate reads. So `AEC_PROPS_MAX_MB` had never really
been documented — **a planning entry had been standing in for operator documentation and the gate
could not tell the difference.** It is now in `.env.example` beside the other caps, and the deleted
bullet is preserved in the archive. That gate shipped one release ago, in v0.3.1089, and caught a
real regression on its first contact with unrelated work.

### Walking the branches found an unmerged security fix

40 remote branches, **38 fully merged**. Of the two that are not:

- **`fix/cloud-domain-allowlist` is a real, open gap on `main`** (commit `de935a26`, pushed today at
  06:34; **PR [#339](https://github.com/ibuilder/massing/pull/339)** — opened partway through this
  audit, which is why the branch first showed up here with nothing pointing at it). `AEC_OAUTH_ALLOWED_DOMAINS` is enforced in exactly one place — `routers/auth.py`,
  the direct-IdP callback — and `routers/cloud.py`, the massing.cloud SSO door, has no check.
  Confirmed by grepping `main`, not by trusting the branch's description. An operator who restricted
  sign-in to their own domain has it enforced on four doors and bypassed by the fifth. **Not merged
  in this release on purpose** — an authentication change belongs in its own release, not inside a
  documentation reconciliation. It is recorded under Outstanding USER actions with the evidence.
- **`lock/cve-floors-2026-08-09` reads as an open CVE hole and is not one.** It is superseded: `main`
  already carries `pypdf>=6.15.0`, `cryptography>=50.0.0` and the transitive-floors block, with the
  lock resolving to exactly those. Checked before reporting, because a branch named for three CVEs
  is the kind of thing that raises a false alarm on sight.

### Also

The roadmap status block was **311 releases stale** and had itself recorded that its predecessor was
thirty-eight stale — twice in a row is not bad luck. Re-derived: backend **628/628** suites, vitest
**2,007** tests across 196 files, `test_reachable` **358/364**, **28** open items. **CodeQL is
recorded as NOT MEASURED rather than carried forward as 0** — no alerts-API tool was available in
this session, and `docs/roadmap-directions.md` §7 is explicit that a green *run* is not zero alerts.
Band 1 is empty for the first time and says so in those terms: it measures when someone last swept,
not that nothing is wrong. The next three sprints are re-cut, each row now carrying the premise to
check first — the one row of the previous cut that was correctly sized was the one that demanded it.
## v0.3.1090 (2026-08-25) — sign in through massing.cloud, and open your cloud library

massing.cloud becomes the **identity broker**. The user signs in once on the site — picking
Microsoft, Google, Procore, Autodesk or a password *there* — and this deployment holds **no provider
secret at all**. If their plan is anything but Free, their massing.cloud project vault becomes
browsable and openable in the app.

OAuth2 authorization code + **PKCE (S256)** against the already-registered public client
`massing-desktop`. The redirect URI is our own `/auth/cloud/callback`, which for a desktop or
self-hosted install is already a loopback address. Off by default; the routes 404 until
`MASSING_CLOUD_SSO_ENABLED=1`.

**The toolbar account control becomes an identity chip** — the massing.cloud (WordPress) avatar,
display name and an admin badge — falling back to a generated initials disc for password and
direct-IdP accounts, which have no avatar and never will. Absence is a rendering branch, never an
error.

**Administration stops being a place you go.** The four admin-only dropdown entries (users, audit
log, errors, data connections) are now the *Administration section* of one **Profile & settings**
panel, shown only when the account carries the capability. A non-admin and an admin see the same
panel; the admin's has one section more. That is the whole reorganisation — admin settings live in
your profile — without deleting a capability the product still needs.

### Three decisions a reader should be able to question

**The code exchange runs server-side, not in the browser.** The cloud refresh token is good for 30
days and has no business in `localStorage`; doing it here also means massing.cloud never has to
CORS-allow this origin. PKCE needs no client secret, so nothing about being a public client is bent.

**The PKCE verifier is derived, never stored.** The cookie carries an opaque flow id; the verifier is
`HMAC(signing key, flow id)`, recomputed at callback time. Nothing the browser holds is secret
material. An earlier version sealed the verifier into the cookie — signed but not encrypted — which
CodeQL flagged; the rule's own concern was a false positive (SHA-256 inside HMAC is the correct
primitive and a slow KDF would be *wrong*), but it pointed at a real question the rule does not ask,
so the design changed rather than the alert being argued away.

**The two tier vocabularies must not be crossed, and this nearly shipped as a bug.**
`licensing.TIER_ORDER` is `free|home|commercial|enterprise` — what the site sends. `tiers.TIERS` is
`free|pro|enterprise`, the seam on `User.tier`. Running a cloud tier through `tiers.normalize` maps
**`commercial` → `free`**, telling a paying customer they have no library.

### Roles: built, and inert until the site publishes them

`userinfo` returns `{sub, name, email, avatar_url, tier, providers}` and **no role key** — verified
against the plugin source, not the docs. So `administrator`/`editor` ⇒ app admin is implemented,
two-way and fail-closed, and **does nothing today**. Worth stating plainly, because it makes the
feature's most visible behaviour a no-op: someone testing "does my cloud admin role grant admin
here?" will see nothing happen and reasonably conclude it is broken. The four-line
`massing_sso_userinfo` filter that activates it is in `docs/internal/massing-cloud-sso.md`.

### Four admin lockouts, one missing fact

Nothing recorded whether an account's admin role came from the cloud or predated it, while three
comments asserted the distinction. Because `userinfo` publishes no roles, `is_admin` is *always*
False and the bootstrap admin's username *is* their email — so each of these was a guaranteed lockout
in the default configuration, not an edge case:

1. a first link demoted a pre-existing local admin;
2. a first-link-only guard merely **delayed** that to the second sign-in — a fix that postpones the
   write rather than preventing the state, and the test asserted the delayed demotion as correct;
3. `/auth/cloud/refresh` demoted them on an explicit Refresh;
4. `/auth/cloud/disconnect` demoted them on the way out.

`CloudIdentity.local_admin_at_link` snapshots the provenance at first link, before any sync write.
Role sync may now promote freely and demote **only an elevation it granted**; disconnect reads the
flag before deleting the row, since afterwards there is nothing left to ask. All four sites are
mutation-checked — including removing the *promotion*, without which "never demotes" would pass on a
build with role sync switched off entirely, which is exactly how the second defect hid.

**Intended consequence:** for a cloud-linked account that was not already an admin, the site is
authoritative — promoting it locally under Manage users is undone at the next sign-in.
`MASSING_CLOUD_ROLE_SYNC=0` opts out.

### A restriction that held on four doors and not the fifth

`AEC_OAUTH_ALLOWED_DOMAINS` was enforced on the four direct-IdP callbacks and **not** on the
massing.cloud path — so an operator who restricted sign-in to their own domain had it hold on four
doors and silently bypassed on the fifth, which is worse than no control because they believe it
holds. The cloud callback was written from the direct-IdP one and carried `AEC_OAUTH_NO_AUTOPROVISION`
across but not the five inline lines above it; the flag reads `AEC_OAUTH_*` as though scoped to those
providers, when what it governs is *who may sign in*. Now `oauth.domain_allowed`, shared by both, so
a sixth sign-in path cannot miss it. Found by reading v0.3.1089 — the release that made the control
discoverable is the one that made its gap visible.

### Not included, deliberately

Saving back to the cloud (docs/31 §3 is an open joint decision and there is no `.mass` container
writer, so a save button would record a pointer to nothing); opening `.mass` (refused explicitly
rather than handed to the IFC loader); and the `massing://open` deep links.

**Not verified:** the real broker handshake. Every test stubs it at the module seam, so the first
live sign-in against production is untested.

## v0.3.1089 (2026-08-25) — two sign-in restrictions existed in code and in no document

83 `AEC_*`/`MASSING_*` environment flags are read under `services/`. **32 appeared nowhere** — not in
`.env.example`, not in `docs/`, not in `README.md`, not in `docker-compose.yml`. Two of them decide
who may sign in:

    AEC_OAUTH_ALLOWED_DOMAINS    unset ⇒ any domain the IdP will authenticate may sign in
    AEC_OAUTH_NO_AUTOPROVISION   unset ⇒ an unknown identity mints a local account

Neither has a restrictive default, so a deployment with OAuth enabled and these unset is open *by
configuration* — and an operator who cannot discover them cannot close it. **A hardening control that
exists in code and in no document is a control nobody can use.** Timely rather than theoretical: SSO
landed one release ago.

The same argument, less sharply, for `AEC_GRID_KGCO2E_PER_KWH`: its default is a US-average grid
factor (~0.386 kgCO2e/kWh), so carbon figures are wrong for any other region — and reported
confidently anyway. Also now documented: the untrusted-code limits (`AEC_IFC_CODE_CPU_SECONDS`,
`AEC_IFC_CODE_MEMORY_MB`, `AEC_SANDBOX_STARTUP_SECONDS`, `AEC_PLUGIN_TIMEOUT_S`, `AEC_MAX_UNZIP_MB`),
`AEC_LOCAL_MODE` (which disables access control and belongs to the desktop build, not a served
deployment), error-log retention, and the three external endpoints an air-gapped install needs to
point elsewhere.

**It is a gate, not an edit, because a list of names is exactly what rots here.** `clearCache.ts`'s
`KEEP_KEYS` named six keys the app never wrote and shipped a button that deleted the session it
promised to keep — four releases ago. So `services/api/test_env_documented.py` checks **both**
directions: a flag the code reads must be documented or declared internal, and **a name in the
internal list must actually be read**.

That second check rejected three of its own author's entries on its first run — `AEC_PIDFILE` and
`AEC_ENVFILE` are set and read entirely inside a test, and `AEC_PLUGIN_CHILD` is *written* by
`plugin_registry._child_env` and read by nobody. The gate caught its own list rotting before it
shipped, which is the whole argument for checking the direction that feels redundant.

Mutation-checked by undocumenting `AEC_OAUTH_ALLOWED_DOMAINS`: it fails and names the file that reads
it. An anti-vacuity check requires documented flags to outnumber internal ones two to one, so the
exemption cannot quietly swallow the population — 67 documented, 18 internal.

## v0.3.1088 (2026-08-25) — a register can finally be grouped, which is what makes it a report

**R22-REPORT-BUILDER item 1**, which its own entry calls "the substantive one" of four. Until now the
only `group_by` anywhere in the module path was hardcoded to `workflow_state` (two call sites in
`modules_query.py`), so "cost by discipline", "RFIs by month" or "hours by trade" had no expression
at all and the answer was an export into a spreadsheet.

    GET /projects/{pid}/modules/{key}/aggregate
        ?group_by=<field>&agg=count|sum|avg|min|max&agg_field=<field>

It takes the **same** `?f.<field>[.<op>]=` filters the list route takes, through the same
`_parse_filters` — so a report and the register it came from cannot disagree about which rows they
describe.

**Field names are validated by `_resolve_field`, the one the filters and sort already use.** Not a
new check beside it: `_json_text` interpolates a field name into a SQLite JSON path, so an
unvalidated name is an injection site rather than a typo, and a second validator would be a second
answer to "what is a field" — which is how two sources of truth start disagreeing.

**`sum` and `avg` are refused on a non-numeric declared field.** This is the load-bearing behaviour,
and the reason was verified rather than assumed: with the guard removed, SQLite returns `0.0` per
group for a sum over text. Not an error — a confident number, which a reader takes as *this project
has none*. The refusal names the declared type so the caller can act on it, and it is
mutation-checked. Its twin asserts that a sum over a real numeric field still returns the right
number, because "it refuses" is otherwise satisfied by an implementation that refuses everything.

**The group cap is announced, not silently applied.** A `group_by` over a free-text field with
thousands of distinct values is a denial of service dressed as a report; a silently truncated one is
worse, because a short list reads as the whole answer. The query asks for one past the cap so
"there were more" is observed rather than inferred, and the response carries `truncated` and
`max_groups`.

The test's fixture is derived from the registry rather than naming a module, so a renamed module
fails as a stale fixture rather than as broken aggregation — and it found the create-vs-patch
asymmetry on the way through: `create_record` takes `{"data": {…}}` while PATCH takes the field map
flat, and getting it wrong reports as "missing required field(s)".

## v0.3.1087 (2026-08-24) — the Project Pulse rail has never been styled

`pulse.ts` shipped in v0.3.749 and **no stylesheet has ever contained the string `pulse`**. The rail
is not dead code — `portal.ts:renderPulse` builds it and mounts it on the dashboard — so for ~330
releases it rendered as bare HTML: no card, no rule, no colour. `pulse.test.ts` was thorough and green
throughout, because it tests what `buildPulse` *computes*, and the computation was always right.

**The part that matters is the tone.** `pulseCardEl` writes `pulse-card pulse-tone-${tone}`, where
tone is `good | watch | risk` derived across five domains: a blocking model issue, cost variance,
negative float, overdue work, a failing reserve. With no rule for those classes **a risk card was
pixel-identical to a healthy one** — which is the entire thing an at-a-glance rail is for. The app
computed the distinction correctly and threw it away at the last step.

Colour comes from the status tokens per R26-COLOUR-DISCIPLINE, never `--accent`: accent means "you can
act on this" and a pulse card says "this is how it is". The tone rides the left rule and the dot, once
— five cards with full-bleed status backgrounds would be a wall of colour with no emphasis left to
spend. The risk *sentence* is deliberately not tone-coloured: it appears on watch and risk cards
alike, so colouring it would say "this is bad" about a line that often says "this is what to watch".

**A class collision came out with it.** `pulse-${tone}` produced `pulse-risk` for the risk tone —
which was *also* the class on the risk sentence inside the card, so one selector matched both a card
and a paragraph within it. Nothing depended on the ambiguity only because nothing was styled; the
moment a rule existed it would have painted both. Renamed to `pulse-tone-*`.

`pulseStyled.test.ts` asserts every class the component emits has a rule, that the three tones resolve
to three *different* status tokens (all three sharing one would be the same bug with extra steps),
that the block uses no `--accent`, and that the tone class collides with nothing else the card emits.
Mutation-tested both ways: giving watch the good token, and deleting one rule.

**How it was found, and the discriminator that made it a finding rather than a list.** A scan for
classes assigned in TS with no CSS rule returns 62 — mostly selector hooks on components that style
inline, which is not a defect. `pulse.ts` was the only file with unstyled classes **and zero inline
styling**. That single condition separated the real one from the noise.

Verified in a real browser against the live stylesheet: the three tones compute to `rgb(51,209,122)`,
`rgb(255,212,121)` and `rgb(226,85,74)` — `--status-good`, `--status-warn`, `--status-crit`. *The
markup was injected rather than driven from the live rail, because this demo project's `projectPulse`
returns nothing to build cards from; the emitted-class half is what `pulseStyled.test.ts` covers.*

## v0.3.1086 (2026-08-24) — SCALE-SEAM ㉗: the PDF tools, and the plumbing that stayed

Nine methods out of `client.ts` into `api/pdfTools.ts` (2,883 → 2,837): merge, split, rotate, extract,
the stamp library, stamping, the PAdES-signed seal, and the licences that back it.

Grouped by what they **do**, following ㉖ rather than the route prefix. The run spans `/pdf/*`,
`/stamps/library` and `/licenses/mine`; splitting on the prefix would put `stampLibrary` in one file
and the `pdfStamp` that consumes it in another, and separate `myLicenses` from the seal dialog that is
its only reason to exist.

**`_pdfPost` did not move.** It is `protected` on `HttpCore`, which every mixin extends, so it is
already where shared transport belongs — the seam is the feature, not the plumbing.

The doc-comment gate earned its keep on the way through: `myLicenses`'s comment spelled it "licences"
while the code, the type and the route all say `licenses`, so it shared no word with its method. Fixed
by matching the code, not by widening the exemption set — that set is frozen and may only shrink.

## v0.3.1085 (2026-08-24) — "Clear cached data" kept nothing, and said it kept everything

Found by sweeping for more instances of yesterday's favourites defect — state that is read but cannot
be written. This is the same class and worse: a live button in Settings, a promise printed beside it,
and a green test file vouching for the wrong thing.

**`KEEP_KEYS` matched no key this app writes.** It named `aec_token`, `aec_user`, `shell-spine`,
`aec_persona`, `aec_ws`, plus the prefixes `prefs:` and `aec_pref_`. The session key is **`aec-token`**
— a hyphen, not an underscore — and the other six strings appear nowhere in this repository outside
`clearCache.ts` and its test. `aec_user` matched exactly and has never been written by any commit.

So `isKeeper` returned false for every key that can exist. Pressing the button signed the user out,
wiped their settings, persona, workspace and every portal preference, and deleted `aec-field-queue` —
**unsynced field captures, with photos** — then reported *"Kept your sign-in and preferences (0
settings)"*, a count that states the bug, beneath a note reading "Your sign-in and preferences are
kept", and told them to reload. Which lands on the sign-in screen.

**The test was green because its fixtures were invented.** It asserted `isKeeper("aec_token")`,
`isKeeper("shell-spine")`, `isKeeper("prefs:rfi:columns")`, `isKeeper("aec_pref_density")` — every one
a key with no writer — and its "cached payloads do NOT survive" cases (`cache:modules`,
`aec_demo_snapshot`, `rooms:proj-1`) were equally fictional. It asserted the constant back to itself
over a namespace that did not exist: thorough, readable, and about nothing.

### What changed

**The direction of the default, which is the actual fix.** An allowlist destroys any key nobody
thought about, or that got renamed. A denylist keeps it. Drift is inevitable; what a design chooses is
what drift costs. `CACHE_KEY_PREFIXES` is empty today, and that is the honest answer rather than an
oversight — every key this app writes is a user choice or pending work, and the caches this button
exists for live in the Cache API, IndexedDB and the service worker.

**The upload queue survives.** `aec-offline` holds real `File`/`Blob` objects captured offline and not
yet sent; deleting it is losing work, not evicting a copy. It is skipped and reported as kept.

**`clearCacheKeys.test.ts` enumerates every localStorage key in `src/`** and checks both directions: a
key that exists must be classified, and a declared prefix must match something that exists. The second
is what would have caught the original list the day it rotted. Mutation-tested by reintroducing the
defect: a `shell-spine` prefix is flagged as matching nothing, and an `aec_`/`portal-` prefix is
flagged for the eight real keys it would delete.

Writing that scan produced the same failure one level down, twice — and both are why it now refuses to
skip rather than skipping quietly. It could not resolve `keyFor(pid)` (the call regex stops at the
paren, so the identifier came out as `keyForpid`), and it could not resolve
`const RECENT_KEY = ` + "`lib-recent:${pid}`" + ` — **a real key my own manual enumeration of this app
had missed entirely.** An unread key is an unclassified key, so an unresolved argument now fails the
build instead of being passed over.

The Settings note is narrower than it was, because the behaviour is: it no longer claims to clear
"offline data".

## v0.3.1084 (2026-08-24) — favourites could be read for two months and set by nobody

Found while measuring `portal.ts` for the next REL-4 extraction. The cluster I was about to extract
turned out to be unreachable, and what it had taken down with it is the release.

**The module catalog has not rendered since 2026-06-24.** `catalogEl` appears exactly three times in
`portal.ts`: its declaration, and two lines inside `refreshCatalog`, which opens
`if (!this.catalogEl) return;`. Nothing else assigns it. `git log -S catalogEl` names commit
`9a61f4cc`, which deleted the two mount lines **deliberately** — "the persistent nav rail (N1) owning
module navigation" made the dashboard catalog redundant — and left ninety-one lines of implementation
behind, plus a persona-change listener calling the resulting no-op.

**The dead lines are not the problem.** `toggleFav` had exactly one call site in the whole app: the
`☆` button inside that catalog. `readFavs` has three live readers — `buildNav`'s "★ Favorites" group,
and `pinnedItems` in `shell/pinnedRail.ts`. So favourites could be **read** and never **written**, and
`pinnedItems` could only ever return `mode: "recent"`. The pinned rail's entire "pinned" mode was
unreachable — on a component carrying a careful docstring about why it never mixes pins with recents
(*"two identical-looking rows mean different things — 'I chose this' and 'I happened to be here'"*),
protecting a distinction that could not arise.

**So the fix is not the tempting one.** Deleting ninety-one dead lines would have dropped a size
ratchet, kept every test green, and quietly finished killing a feature two other surfaces are built
around. `readFavs` having three readers is the evidence that favourites are wanted; only the *setter*
was lost. `moduleButton` — the one place every rail row is built — now carries the pin, and the
catalog went in the same release so the star does not exist twice.

The row is two sibling buttons rather than a star nested in the open button, because a `<button>`
inside a `<button>` is invalid and the inner one is unfocusable. The deleted catalog had already
worked that out and said so in a comment; the shape and its `.mod-fav` styling, which outlived it in
`style.css`, are inherited on purpose.

**`SECTIONS_BY_PERSONA` went too, and had been orphaned for longer than the catalog.** Its comment
said "buildNav falls back to open-all when none match the active workspace" — but `buildNav` stopped
grouping modules by section in v0.3.767, when the room spine made a second taxonomy in one rail a
defect rather than a feature. A constant's docstring is a claim about the rest of the tree, and
nothing checks it.

**No reachability or uncalled-symbol gate would have caught this, and none should be trusted to:**
every method in that catalog had a caller — *each other*. `renderModuleCatalog` was called by
`refreshCatalog`, which was called by a live event listener. The cycle looked wired from every angle
except whether a person could reach it. `portal/favourites.test.ts` builds the real rail, clicks the
real control and reads the preference back; it was mutation-tested against a star that only re-styles
itself, and four of its six checks go red.

Verified in a real browser against the live API, not only in happy-dom: pin writes
`portal-favs: ["pull_plan_task"]`, both that row's star and the one in the new ★ Favorites group flip
to "Unpin", and unpin returns the preference to `[]` and removes the group. Layout checked
numerically — the star's right edge sits at or before the open button's left edge, so the two never
overlap. *The trusted-input path was NOT exercised: this session's browser pane does not composite,
so synthetic clicks do not reach the page. That is a tooling limit; the handler is a plain `onclick`
and does not consult `isTrusted`.*

`portal.ts` 1,400 → 1,353.

## v0.3.1083 (2026-08-24) — the budget that was waiting for a moment, not a beacon

**R24-PERF-BUDGET is complete.** All three stated budgets are now measured. `panel_load` had had its
beacon since v0.3.1063 and stayed `measurable: False` for fourteen releases, because the blocker was
never the beacon — `ui/modal.ts` builds an empty shell and each caller fills it afterwards, so timing
that chokepoint records DOM construction and files it as a panel load.

**Measured from the click, not from the shell.** That is what makes it correct for the several
dialogs whose *caller* fetches before the shell exists — `conceptBudgetView`,
`estimateConfidenceView`, `composeExhibit`, `openReportCenter` all await, then open a shell that
builds synchronously. A timer starting at `modalShell` would have missed the user's entire wait and
reported the DOM work in its place. A click seeds at most one panel, so a modal opened by a timer
thirty seconds later cannot invent a thirty-second load.

**Wiring alone would have replaced one honest gap with a dishonest number.** A p95 over whichever
panels somebody remembered to wire is a figure whose population nobody can state — the objection
`perfBeacon.ts` already makes against instrumenting click handlers one at a time. So
`apps/web/src/ui/panelReady.test.ts` enumerates every `modalShell` call site and requires each to
either report or be declared synchronous with a reason; the budget itself carries a `population`
field, because it is the only one of the three with a subset. 18 of 29 report.

**The classification is human, and it had to be — it was wrong twice by inference.** `qr.ts` was
assumed instant from its file name and awaits `QRCode.toCanvas`; three register dialogs were assumed
instant because their own bodies contain no `await`, and their callers fetch. Both caught by reading,
neither by a rule. One site is *excluded* rather than synchronous: `openProjectBundle` sits behind a
native file chooser, so its interval would time the human browsing for a file rather than the app —
and a handful of those would move the p95 further than any real regression.

Two checks changed shape rather than being deleted. The route test used `panel_load` as its example
of a declared-but-unmeasurable budget; that property still matters and now runs against an injected
one, because a property with no current instance is still a property. And the flip got its twin — the
budget that just became measurable must actually be *accepted* by `/metrics/client`, or a
`measurable: True` the route still rejected would report `no_observations` for ever while every flag
in the table said it was wired.

**The gate itself had to be fixed, and the way it broke is worth keeping.** It first asked whether
the `modalShell(` line mentioned `ready` — the destructure. Mid-release a botched edit removed two
`ready()` *calls* while leaving those destructures in place: two panels silently stopped reporting
and the gate stayed green. A gate that reads the declaration and not the use is satisfied by dead
wiring, which is the same shape as a beacon that is installed and never fires. It now requires a call
in the enclosing function, and that was mutation-tested by deleting one.

And its file list had a hole for the same kind of reason: `ui/modal.ts` *defines* `modalShell`, so
the instinct is to skip it — but it also **calls** it twice, for `confirmModal` and `promptModal`.
Excluded, those two sat outside a population the file claims to enumerate. The definition is now
skipped by line rather than the file by name, and the population is 31.

One incidental find while flipping the flag: `_EDGE_BUDGETS` — the tuple naming which budgets sit on
a histogram bucket edge — had **no reader at all**, and the test that should have used it hardcoded
the same two numbers instead. A dead constant sitting beside a comment explaining why it matters is
the shape a rule takes just before it stops being true. The check now derives from it, and asserts it
still names every client budget.

Along the way the click and panel budgets were put on one shared sender (rolling cap, implausible
drop, non-throwing reporter). Copying those three rules would not have crashed anything; it would
have let the two budgets quietly disagree about what counts as a measurement.

## v0.3.1082 (2026-08-24) — the leaf that was a leaf, and the one that only looked like one

**REL-4.** `renderDeveloperHome` out of `portal.ts` into `portal/homes/developerHome.ts`
(1,473 → 1,400 lines). Seventy-nine lines is a small slice, and small was the correct answer rather
than a disappointing one.

The `this.` references of every candidate were grepped **before** naming the slice:

| method | lines | touches on the class |
|---|---|---|
| `renderDeveloperHome` | 79 | `host`, `mods` — a leaf |
| `renderDesignHome` | 94 | + `activeKey`, `buildNav`, and five sibling renderers |
| `renderPxBand` | 54 | + `activeKey`, `buildNav`, `renderBudget`, `renderScheduleViews` |
| `renderPortfolio` | 116 | + `bar`, `root`, `panelCtx`, `renderHome` |

The two persona homes sit next to each other, are named alike, take the same four arguments and are
called on adjacent lines — and only one is a leaf. Taking `renderDesignHome` too would have meant
inventing a callback bag for seven siblings: coupling added in the name of removing it. That is three
times this cycle that adjacency was not a relationship, and the first time it was measured before the
slice was chosen instead of during it.

**A size ratchet for `portal.ts` ships with it, at 1,400.** The file had none, so it lived under a
global ceiling it is nowhere near — the extraction would have bought nothing any check could see, and
the next dozen additions could have put the lines back while the work still read as done. *An
extraction without a ratchet is a rearrangement.* Mutation-verified: at 1,399 the build fails.

`portal/homes/` needed an owning lane (A, matching `portal.ts`; B owns `portal/panels/`). The
unowned-files gate caught that on the first run, which is what it is for.

## v0.3.1081 (2026-08-24) — third-party plugin code stops running in the API process

**SEC-PLUGIN-LOADER.** `plugin_registry` used to `exec_module` a plugin's entry in this interpreter
and then call its `register(api)`. Every check around that line — the manifest, the `api_version`
major, the rollback of a plugin that raises — happens *before* it and constrains nothing the code
then does. Import-time plugin code had the API's DB session, filesystem, network and environment.

It now runs in a child process. `plugin_host.py` has two modes: `discover` imports the entry and
records what it declares against a recording API, and `run` executes one recipe against an IFC on
disk. `plugin_registry` no longer contains `exec_module` at all — it shells out and registers
*proxies*, so a plugin's callable is only ever held in a child.

**`run` is there because sandboxing only registration would have been half a boundary that read like
a whole one.** The item asked for "registration in a separate process", but a plugin's recipe is
`fn(model, params)` — an arbitrary callable invoked later, from the API process, on every use.
Isolating the import while leaving the work in-process contains the smaller half and leaves the
larger one open, under a heading that says the problem is solved.

**The load-bearing assertion is process identity**, and everything else is decoration without it. A
probe plugin records `os.getpid()` at import and again inside its recipe; both must differ from the
API's pid *and from each other*. A version that quietly ran in-process would satisfy every other
check in the file — the timeouts, the stripped environment, the refusals.

Three things this cost, all of them found by checks rather than by reading:

* **A silent lost edit.** The proxy reopens what the child wrote and hands back `(model, changed)`,
  which `edit` only rebinds for recipes in `REPLACING_RECIPES` — a frozen set the plugin path could
  not join. Without that registration the driver writes the *pre-edit* model and reports a healthy
  change count: no error, a green run, the edit gone. The pre-existing plugin fixture only counted
  storeys, so nothing would have shown it; the new suite asserts against the **written file**.
* **A gate that agreed with itself.** The first encoding check asserted that a non-ASCII recipe
  result survived the pipe. It passes with the encoding pin deleted, because `json.dumps` escapes
  non-ASCII by default and the protocol is ASCII whatever the codepage is. What is actually raw on
  the pipe is the *diagnostic* path — the stderr tail reported when the child prints no JSON at all,
  which is the path you are on precisely when something has already gone wrong.
* **A gate that discriminated only under an invocation nobody uses.** The replacement check was real
  when run bare and vacuous under `run_tests.py`, which sets `PYTHONUTF8=1` and puts the parent in
  UTF-8 mode regardless of what the child is asked for. It now runs its own probe with that variable
  removed, and was mutation-tested under the suite's own invocation rather than a convenient one.

**The deferral in the entry was overridden deliberately, not overlooked.** It said to build this when
plugins are *distributed* and not before, and that reasoning still holds: no path exists from an
unprivileged caller to plugin execution, so this retires no live vulnerability. It buys the
marketplace prerequisite in advance instead of it being discovered as a blocker later.

**SCALE-SEAM ㉖** — the code-compliance group out of `client.ts` (8 methods, 2,961 → 2,883) as
`api/codecheck.ts`. First slice grouped by what the methods *answer* rather than by route prefix: it
spans `/projects/{pid}/codecheck`, `/codes/adoptions` and `/codes/ebc/pathways`, and splitting on the
prefix would have put `ebcClassify` and `ebcPathways` — two halves of one screen — in two files. Two
RFI methods sat inside the run and stayed; adjacency in a file is not a relationship.

## v0.3.1080 (2026-08-24) — the same scan over the rest of the tree, and why it stays out of it

Having found 23 stranded doc comments in `api/`, the obvious next move was to run the scan repo-wide
and widen the gate. **The scan was worth running; widening the gate was not**, and the reason is the
useful part.

Eight more hits across `apps/web/src`. **Only one was safe to act on.** The other seven are two shapes
that do not occur in `api/` and that the rule cannot tell from residue:

- **A module header placed after the imports.** `portal/panels/budget.ts` has one. A blanket cleanup —
  the exact thing the `api/` result invited — would have deleted the file's own documentation.
- **A context block above the declaration it motivates.** `viewer/app.ts` and `main.ts` both carry a
  RAIL-SPLIT narrative (with its live measurement: *182 buttons and 11 inputs under 7 headings*) above
  the code that acts on it. That is deliberate prose, not leftover.

In `api/` neither shape occurs: headers sit at line 1 above the imports, and the methods are a flat
list with one comment each. **A gate's scope is part of its claim**, so the scope is now argued in the
test rather than assumed — widening it needs a rule that can tell a header and a narrative from a
leftover, and that rule does not exist yet.

### Fixed

The one safe case: `portal.ts` was holding the comment for `panelCtx()`, which had none of its own.
Moved, same shape as `riskBoard` in v0.3.1078.

### Not done, and why

`client.ts` extraction stops here for now. The largest contiguous route group left is **four methods**
— about 1% of the file — where the last four slices took six, six, five and five. The stated goal is
met (**5,064 → 2,961 lines**); one 4-method slice per release cycle is churn rather than progress.

## v0.3.1079 (2026-08-24) — SCALE-SEAM ㉕: specialty, and a type that nearly moved with it

`/projects/{pid}/specialty` out of `client.ts` into `apps/web/src/api/specialty.ts` — five methods and
five types, **3,019 → 2,961 lines**, ratchet lowered with it.

**Two neighbouring types deliberately stayed.** `MaterialEntry` and `MaterialPaletteResult` sat
interleaved among the specialty types, and `portal/panels/materials.ts` imports `MaterialEntry` from
`api/client` — moving it would have been a breaking change dressed as tidying. *Adjacency in a file is
not a relationship.*

**And one type nearly moved without its consumer.** I checked that the specialty types were unused
outside `client.ts` with a grep I had truncated using `head -4`, and `SpecialtySummary`'s single
outside reference — in `proforma/proforma.ts` — was on the line after the cut. The typecheck caught it;
my check did not. **A population derived from a truncated list is not a population**, and the failure
is invisible because the truncated output looks exactly like a complete one. The import now points at
the new home, and the near-miss is recorded in the module header where the next mover will read it.

### Note for ㉖

`MARKS` in `apps/web/src/shell/roadmapLanes.test.ts` stops at ㉕. The next slice cannot be written into
the roadmap until that vocabulary is widened — the lane gate would stop seeing the item, which is
precisely the blindness v0.3.1074 fixed.

## v0.3.1078 (2026-08-24) — 23 comments about declarations that are not there

The cleanup v0.3.1077 booked, done with the gate that belongs beside it rather than ahead of it.

### Fixed

**Twenty-three doc comments were stranded** — sitting directly above *another* doc comment, their own
declaration long gone, left behind by the SCALE-SEAM extractions. A stranded comment does not sit
harmlessly in the file: it attaches itself visually to whatever follows. `TOPIC-BOARD` sat above
`modelConstraints`, `RISK-BOARD` above `devBudget`, the R26 room spine above a `StripStatus` union.
**A comment about a declaration that is not there is not documentation — it is a false statement
positioned where the next reader will trust it.**

Each was checked against the declaration below it before being touched; none was a section header.
Two had a verifiable owner and were **moved** rather than deleted:

- `setToken`'s comment had been separated from it when the `authToken` getter was inserted between
  them — it is back on `setToken`;
- `riskBoard` had no comment of its own, and `client.ts` was holding the one that describes it.

The remaining 21 described features with no method here to own them and were removed. The prose is in
git history if any of those features later needs documenting where it actually lives.

**One of the 23 was mine.** In v0.3.1075 I gave `schedule4d` a correct comment by *prepending* one and
left the wrong `MASSING-OPT` comment stranded above it, instead of replacing it. Fixing a wrong
docstring by adding a right one leaves two, and the wrong one is still the first thing read.

### Added

`docComments.test.ts` gains a second check: no doc comment may sit directly above another. Mutation
checked — stranding one fails both this and the neighbour check, naming file, line and text.

## v0.3.1077 (2026-08-24) — SCALE-SEAM ㉔, and the same extraction caught leaving comments behind

### Changed

- **`/ids` and `/projects/{pid}/ids` out of `client.ts`** into `apps/web/src/api/ids.ts` — six methods,
  one contiguous run, **3,066 → 3,026 lines**, ratchet lowered with it. The group was chosen by
  measuring the longest same-prefix run left in the file rather than by picking a domain that sounded
  tidy. Two of the six are not `json()` calls (a browser download and a multipart PUT); they move with
  the group because **the seam is the route, not the transport** — splitting on transport would put
  two halves of one feature in two files.

### Found — this extraction has been leaving doc comments behind, in two distinct shapes

When a method moves, its comment stays with the file and attaches itself to whatever follows.

- **Eleven methods documented as a neighbour's job** — fixed in v0.3.1075 and now gated.
- **~25 orphaned comments**: a doc comment immediately followed by another doc comment, its own
  declaration gone. Three sampled and all genuine, each traceable to this split — `httpCore.ts` still
  documents `setToken` (moved to `api/auth.ts`), `model.ts` still documents TOPIC-BOARD (moved to
  `api/topics.ts` in ⑳), `authoring.ts` still documents an IFCPATCH-LIB dry-run scan.

**Recorded, not fixed.** The 25 is a *candidate* count and my last detector of this kind had two false
positives out of thirteen, so each needs reading before it is touched — and a gate that fails on 25
sites belongs with the cleanup, not ahead of it. Booked in the SCALE-SEAM entry with the measurement
so the next slice starts from a number rather than a suspicion.

## v0.3.1076 (2026-08-24) — SCALE-SEAM ㉓: the EVM group

`/projects/{pid}/evm` out of `client.ts` and into `apps/web/src/api/evm.ts` — six methods in one
contiguous run, the tightest group left in the file. **3,120 → 3,066 lines**, ratchet lowered with it.

`EvmEarnedSchedule` moved with them: two of these methods are its only readers anywhere in the
codebase, so leaving it behind would have kept a type in `client.ts` whose consumers had all gone.

A mixin, so every call site resolves unchanged — `api/surface.test.ts` is what proves that rather than
a reading of the diff.

*This is the extraction whose measuring step turned up v0.3.1075's defect: `evm()` was documented as
`resourceLoading()`'s job, and ten other methods carried a neighbour's comment left behind by earlier
slices of this same split. The extraction that caused it is the one that found it.*

## v0.3.1075 (2026-08-24) — thirteen methods documented as something else

### Fixed — the API client's doc comments described the wrong methods

Found while measuring which route group to extract next: **`evm()` was documented as "Cost-loaded
resource histogram"**, which is `resourceLoading()`. Pulling that thread found a rotation — SCALE-SEAM
moved route groups out of `client.ts` one at a time, and each moved method kept its former
*neighbour's* comment:

    proformaLive   carried importXer's       ("Import a Primavera P6 export…")
    importXer      carried modulesGraph's    ("The module-relations graph…")
    scheduleCpm    carried proformaLive's    ("PROFORMA-LIVE: takeoff-priced cost…")
    evm            carried resourceLoading's ("Cost-loaded resource histogram…")
    permitCities   carried a schedule alert's ("Predictive schedule alerts…")

**Eleven methods were documented as something they are not**, every one reading as authoritative:
`carbonComplianceReport` claimed to run a Monte Carlo over the CPM network, `modelQueryViews` claimed
to inspect a VIM file, `devBudget` claimed to do CPM analysis. **A wrong docstring is worse than
none** — it is what a caller trusts instead of reading the route, and these are the methods every
screen calls. Each now describes what its method actually does.

### Added — a gate, with its own false positives named rather than hidden

`docComments.test.ts` asserts that a comment shares at least one substantial word with the method it
sits above. Crude on purpose: anything cleverer would need to understand prose, and this only has to
catch a comment belonging to a *different* method, which shares nothing with this one by
construction. Mutation-checked by reinstating one wrong comment — it fails naming file, line, method
and the offending text.

**My own detector had two false positives and I did not gate over them.** `addCurtainWall` ("author an
IfcCurtainWall") and `queryElements` ("the IfcOpenShell selector DSL") are correctly documented; the
shared noun is inside a compound identifier the rule cannot see through. Both are frozen in a
two-entry set that may only shrink — a new entry means someone is adding a comment the check cannot
read, which is worth a moment even when the comment is fine. Fixing a "defect" my own scan reported
without reading each one would have replaced two correct comments with worse ones.

### Fixed

- **`PERF-THREADS ③` was shipped in v0.3.1074 and its entry was never marked.** The reverse lane check
  added in that same release caught the stale lane cell on the very next change — closing an item now
  costs both edits or the build says so, which is why it was added.

## v0.3.1074 (2026-08-24) — forty concurrent parses, and a gate measuring 27 of 32

### Added — PERF-THREADS ③: concurrent IFC parses are capped

**The entry this closes corrects its own premise, and that is why the fix is shaped this way.** The
claim was "unbounded threads → resource exhaustion". Starlette/anyio's pool is **40, not unbounded**.
The real risk is what those threads each hold: an IFC parse materialises a whole model, hundreds of MB
for a large one, so forty concurrent parses is an out-of-memory kill rather than a slow response.

So the cap is small and **specific to model work** — not a change to the general thread pool, where
every other off-loop route is cheap and should stay unthrottled. It sits at the **resource**, inside
the loader's uncached parse, so all 31 model-touching call sites are covered without editing any of
them. Configurable via `AEC_IFC_PARSE_SLOTS` (default 3), and **per process**, so the deployed bound
is that times `UVICORN_WORKERS` — the same multiplication `PERF-WORKERS ①` is about, stated rather
than left to be discovered.

`test_ifc_parse_gate.py` asserts the properties that are easy to get wrong, each mutation-checked:
peak **observed** concurrency never exceeds the cap (removing the semaphore takes it from 3 to 12);
the cap is actually *reached*, so this is not a cap of one that serialises every model read; and a
failing parse does not leak its slot — four deliberate failures, then the gate still admits the full
cap. The truncated-file screen runs **outside** the gate, so refusing a bad upload costs a read rather
than queueing behind three real parses.

### Fixed — the lane gate was blind to five items and to a whole direction

`roadmapLanes.test.ts` is the check that every open roadmap item belongs to exactly one lane. It had
three faults, found by pulling one thread:

- **Its item regex allowed ONE leading marker.** `- ◧ ⭐ **SCALE-SEAM ㉒ …**` carries two, so the line
  parsed as nothing and that item was invisible: never counted, never required to be in a lane.
  **A parser that silently skips a line it cannot read destroys the evidence that it is skipping.**
- **It required two characters after a code's dash.** `REL-4`, `REL-7`, `UX-3` and `SITE-1` have one.
  `parkedCodes()` carried the identical flaw, so `REL-7` was listed as parked *and* reported
  unassigned — two regexes over one vocabulary, wrong the same way.
- **It never checked the direction the roadmap says it checks.** The prose above the table promises a
  failure "if the table names a code that no longer exists". Only the converse was implemented.

Between them the gate was reporting completeness over **27 of 32** open items. Both widenings were
**measured before applying** — one bullet gained from the marker fix, four from the length fix —
because a regex change to a population check *is* a population change.

The new reverse check then found **eight stale lane cells** on its first run, including Lane I naming
`SCALE-SEAM ⑬`–`⑳`, eight slice numbers whose extractions had all shipped, while the open slice is
`㉒`. Each was verified against its entry and annotated with what actually happened; `UX-3` and
`SITE-1` were assigned to Lane E by where their code lives. An entry deliberately noting a shipped
item stays legal — that is a cell doing its job; what fails is an unannotated code that reads as
available work and is not.

## v0.3.1073 (2026-08-24) — two entries for one item, again

Docs and one test floor. No runtime change.

### Fixed

- **`R41-UPLOAD-WARK` and `R39-UPLOAD-CAP-APP ①` still read as open after v0.3.1069 closed them.**
  Each has **two** entries — a summary bullet and a ring entry — and that release updated only one.
  This is the same failure v0.3.1065 recorded for `R38-SYNC-VIEW ③`, committed by the person who had
  just written it down: *a summary cell drifts from the entry it summarises, and the item marker is
  the authority*. Knowing the shape did not stop me repeating it, because I closed the item where I
  was working rather than searching for every place that names it. **Grep the code before closing it,
  not just the section you are in.**
- The lane floor drops 29 → 27 to match.

## v0.3.1072 (2026-08-24) — a default that only fails on Linux

### Fixed — main was red on v0.3.1069 and v0.3.1070, both from this

- **`test_resumable_upload` did not set `IFC_DIR`.** It defaults to **`/app/ifc`** — a container path
  — and that file's consumer test registers a model, which writes an IFC under it. On Windows the
  default resolves to a drive-root path that happens to be writable, so the suite passed locally
  **623/623** and the Linux runner failed with
  `PermissionError: [Errno 13] Permission denied: '/app'`.

  This is the second passes-locally-fails-in-CI defect in two days and the same shape as the first:
  **an environment-dependent default that the local platform happens to satisfy.** A green local run
  says nothing about a path whose default is only wrong on the other operating system.

  Not gated. The obvious rule — "a test that sets `STORAGE_DIR` must set `IFC_DIR`" — was measured
  before being written: **397 test files set `STORAGE_DIR` and most do not need `IFC_DIR`**, because
  they never touch an IFC path. A gate there would be several hundred false positives, so the fix is
  the one test plus a note at the setting saying why it is required rather than tidy.

## v0.3.1071 (2026-08-24) — mark up the drawing where you are looking at it

R36-VIEWER-SUBAPP slice 6. Marking up a sheet was only possible in the Drawings room, because the
markup layer was private state on that room's class. It is now a layer, and the viewer's plan pane
mounts it too.

**Both surfaces key it `plan:<storey>` — the same key** — so a pin dropped in either appears in the
other with no syncing and no second store. The identity does the work.

### Three steps, not one

The roadmap called this "an INTEGRATION, not a build". It was a build, and the order mattered:

1. **Characterise.** `drawings.test.ts` — 13 tests over a 493-line class **nothing had ever mounted**.
   Refactoring untested code is how a room quietly loses a feature while every suite stays green. The
   tests pin what the class *does*, including the parts that look like defects, because a
   characterization test that fixes behaviour on the way past stops being a record of what was there.
2. **Extract.** `markupLayer.ts`, with those same tests proving the behaviour did not move.
   `drawings.ts` 493 → 451 lines.
3. **Mount.** `PlanPane` grew a pin layer as a sibling of the SVG host, so re-rendering the drawing
   can no longer wipe the markup — which is exactly what `body.innerHTML = svg` did to anything else
   living in there.

### The import-cycle guard caught the design error

Putting the layer under `drawings/` and importing it from `viewer/planPane` closed
`markupLayer → ui/sheetGuid → viewer/planPane → markupLayer`. **The fix was not a re-route.** The
layer now takes an `onReveal` dependency: *how you reveal an element is a property of the surface, not
of the markup.* The Drawings room selects in the 3D viewer and lights the plan; the plan pane already
has a pick handler and its own highlighter. A layer that reached for either directly could only be
mounted where that one was correct — the coupling the extraction exists to remove.
`guidFromMarkupData` moved with it (a pure data reader that was living among DOM helpers) and
`ui/sheetGuid` re-exports it.

### Wiring within the ratchet

`app.ts` is pinned at its exact size, so the one dependency it had to pass was appended to an existing
line rather than added as a new one — zero net growth.

## v0.3.1070 (2026-08-24) — a rotated model has the same storeys and the same origin

R41-MODEL-ALIGN's remaining half. The existing alignment report says the discipline models *disagree*;
it cannot say *why*, because a building that arrived rotated has the same storey scheme and the same
georeferenced origin as one that did not. This measures the rotation.

### Added

- **`aec_data/align.py`** — a yaw-only oriented bounding box fitted to a model's footprint, and the
  rule that decides whether to propose it.
  - **The acceptance threshold is the feature.** A *true* minimum-area rectangle is not what a drafter
    means by aligned: measured on a real building, the smallest rectangle sat **37° off the building's
    own walls to buy 14% of area** — arithmetically optimal and visibly broken, because the walls are
    what a person sees. A fit is proposed only when the oriented box is **≥20% tighter** than the
    axis-aligned one, which buys a *wall-parallel* answer by refusing the margin where the two
    disagree.
  - **Yaw only, deliberately.** Roll and pitch on a building are almost always a unit or axis-convention
    error, and a fit that could express them would explain a Z-up/Y-up mix-up as a 90° pitch — hiding
    the actual problem behind a plausible correction.
  - A refused fit still returns its numbers. "No" without the margin is a verdict nobody can calibrate.
- **`drawings.plan_points`** — the same geom-iterator walk `world_bounds` does, keeping the points
  instead of collapsing them to a min/max. `world_bounds` cannot serve this at all: an axis-aligned box
  is exactly what a rotated building's *bounds* cannot be told apart from.
- **`GET /projects/{pid}/models/{mid}/alignment-fit`** and
  **`apps/web/src/viewer/tools/alignmentPanel.ts`**, which now answers both questions in one place.

### Changed

- **The alignment check moved out of `qaSection.ts`** (1,348 → 1,335 lines, ratchet lowered with it).
  Adding the fit inline pushed the file 17 lines over its pin and the gate refused — so the panel was
  extracted and came back as three lines. The friction working exactly as intended, for the second time
  this session.
- The extracted panel builds issue text with `textContent` rather than `innerHTML`. The original used
  `innerHTML` with a **model name that comes from an uploaded IFC**, which is not ours to trust; a test
  now asserts a name containing markup creates no element.

### Verified against the entry's own measurement

`test_model_align.py` reproduces the numbers R41 recorded rather than numbers that merely look
plausible: a 54 × 78 m building at 37° gives a **90.1 × 94.8 m** axis-aligned box, **2.03×** the true
area. It also pins both refusals — an already-square model, and the marginal case.

### Fixed while building

- **A minimum-points floor of 8 would have refused the commonest shape in the product.** Probing a real
  generated model showed a simple extruded massing block has **exactly four** unique plan vertices, so
  the fit would have returned `None` for it — silently. The floor is 4: what matters is whether the
  points enclose an area, not whether there are "enough" of them.

**No Alembic revision was needed** — a fit is a proposal and the IFC is opened read-only. *Storing* an
alignment would need one, since `ProjectModel` has no transform column; that is the follow-up.

## v0.3.1069 (2026-08-24) — resuming is the same request as starting

R41-UPLOAD-WARK's resumable handshake, its consumer, and the fix for the CI failure v0.3.1063 caused.

### Fixed — main was red, and it was mine

- **`test_perf_budget` failed in CI with `no such table: jobs`.** That file deletes its own SQLite
  database at the end, and v0.3.1063 appended a new section **after** the cleanup — so a second
  `TestClient` started an app against a just-deleted database, SQLite recreated the file empty, and
  the daemon job-reaper thread that startup leaves polling found no table. It passed locally 621/621
  and failed in CI because whether the reaper's timer fires inside that window is pure timing.
  The section now runs before the cleanup, and the worker is stopped explicitly rather than left to
  lose a race. **Anything that starts the app must run before the file is removed.**

### Added — content-addressed resumable upload

An IFC revision is large and mostly identical to the one before it, so a model that changed in one
storey cost a full transfer, and a connection that dropped at 90% cost all of it again.

- **`resumable.py`** — the arithmetic and the identity, pure and testable without a network. The chunk
  **count** is bounded rather than the size, so the handshake manifest stays roughly constant however
  large the file gets; a fixed part size would make a 4 GiB upload declare hundreds of hashes on
  *every* resume.
- **`routers/uploads.py`** — handshake → chunk → complete. The upload id is
  `sha256(salt + size + chunk hashes)`, so **resuming and starting are the same request**: a client
  that lost its connection re-handshakes and gets a shorter `need` list. There is no resume endpoint
  and no server session to expire. Deduplication falls out of the same fact.
  - **The salt is the project id, deliberately.** Platform-wide content addressing would let one
    project discover whether another holds a given file by handshaking for it and reading `need: []`
    — a cross-tenant existence oracle, even though no bytes are returned.
  - Chunks are verified **on arrival** against the promised hash, so a refusal names the chunk index
    and one chunk can be retried. Hashing the assembled object instead would detect the same
    corruption only after the whole transfer, and could not say which chunk was wrong.
  - The **assembled** size is checked against the bytes actually written, never the declared size.
- **`POST /projects/{pid}/models/from-upload`** — the consumer, so this is a feature rather than an
  endpoint nobody can reach. **The key is checked against the calling project's prefix, and that check
  is the whole security of the route**: an editor on their own project could otherwise name another
  project's object and have its contents registered as their model. A role check answers "may you
  write here", not "is the thing you named yours".
- **`storage.get_chunks`** — the ranged-read counterpart to `put_stream`. Ranged reads existed while
  writes were all-or-nothing, so a route copying a stored object had only `get()`, which materialises
  it — the exact shape this work exists to remove.

### Changed

- **`addProjectModel` picks the transport by file size**; no screen has to know what a chunk is. A
  caller forced to choose would be a caller that can quietly choose wrong — sending a 300 MB IFC down
  a path that cannot resume. The first version put that branch in `qaSection.ts` and the size ratchet
  refused it, which was the better design telling me so.

### Fixed — three found while building, not by a failing test

- **Deduplication did not actually fall out.** `complete` deletes the parts, so a handshake that only
  looked for *chunks* answered "I need all of them" for a file already stored — the exact case the
  entry was written for. It now keys off the assembled object, and `complete` is idempotent.
- **A fabricated byte offset** in the chunk-mismatch error, computed from data that route does not
  have; it would have been wrong for every chunk but the first. A made-up number in an error reads
  like evidence.
- **`chunk_span` was dead on arrival** — written for that offset, orphaned when the offset was
  removed. The dead-code gate caught it.

## v0.3.1068 (2026-08-24) — a bare `WALL` now asks for its points

The one idea worth taking from the `@massing/embed` facade before discarding it. Everything else in
that package is **our own code** — `pixelGovernor` is symbol-for-symbol identical to ours (shipped
v0.3.678), `shadowFrustum` is ours, `section` and `walk` are ours under other filenames — because the
extraction ran this-repo → those-packages. There was no upstream improvement to pull back. There was
one genuinely new shape.

### Added

- **An interactive prompt loop for the CAD command line** (`apps/web/src/viewer/promptLoop.ts`).
  CADCMD (v0.3.430) parses a whole line — `WALL 0,0 5,0 3` — and typing a bare `WALL` was an error
  message telling you the usage and making you retype the verb. Now it arms the command and asks:
  *Specify start point* → *Specify end point* → *Height <3>*, taking a typed coordinate **or a click
  in the viewport** for each.
  - **A pure reducer.** `step(state, event) → state`, so the entire interactive CAD flow is unit
    tested with nothing mocked — no DOM, no viewport, no kernel, no clock. The usual implementation
    is mutable state spread across viewport handlers, which cannot be tested without a renderer and
    therefore never is.
  - **It collects TOKENS, not typed values**, and hands back an ordinary command line. So the
    prompted path and the typed path converge on one parser: every coordinate form (`x,y`, `d<a`,
    `@dx,dy`, `@d<a`), every default and every validation message is shared **by construction**. A
    test asserts a clicked wall produces the identical recipe to a typed one.
  - **A typo does not disarm the command.** It is reported inline and the collected points survive —
    losing three placed points to one mistyped number is the most annoying failure a CAD tool has.
  - Snapping stays **outside** the reducer, so it can be frame-immediate and the reducer stays
    deterministic: the same event sequence always yields the same state.
- **`apps/web/src/viewer/cadBar.ts`** — the command line extracted out of `app.ts` and given the
  interactive mode, with 15 tests covering the wiring rather than the reducer. A mistake in that
  extraction would have left every reducer test green while the command line did nothing.

### Changed

- **`app.ts` 2,885 → 2,865 lines**, and the per-file ratchet drops with it. The 39-line inline block
  became a 10-line mount call. The ratchet is *why* the interactive mode went into a new module
  rather than on top of the god-file — the friction working as intended.

### Fixed — two behaviour bugs the tests caught before shipping

- **A finished-but-uncommitted command ignored Escape.** `cancel` was handled after the
  all-arguments-consumed guard, so the only way out of a completed command was to commit it.
- **Completing the required arguments applied immediately**, which made every optional argument
  unreachable: a wall committed at the default height while the user was still typing one, with no
  error and no value. The rule is now *Enter advances; Enter applies only when nothing is left to
  ask* — and the first version of the reducer had the matching flaw, freezing at `ready` and silently
  dropping the next token.

## v0.3.1067 (2026-08-24) — the viewer facade, evaluated from the tarball and declined

Docs only. No runtime change. Records a decision the user delegated: *"review it and pull it in if
it's great and beneficial… let me know what you decide against."*

### Decided against — `@massing/embed` 0.2.0

**The reason is architectural, not polish.** The facade's load path is **IFC text into a browser-side
tessellator**: `open(source: string | Uint8Array)` sniffs bytes, and the required `Tessellator` is
`(ifcText: string) => {meshes, guids}`. Its own seam entry says so — *"load a model into the kernel
from IFC text"*. **Nothing in the package knows about pre-converted Fragments** (the whole tarball
was grepped; the single "fragment" hit is a generic word in a section-box note).

Two of this repo's non-negotiables say the opposite: pre-convert IFC to Fragments **on the server**,
never parse full IFC in the browser at runtime, and geometry streams as `.frag`. Adoption therefore
means either breaking them, or keeping our own load path outside the facade — at which point it is
not the whole surface, both copies live, and that is the fork *their own plan* calls "the only risk
that can end the project".

**Its `ready: true` measures the wrong half.** `seamCoverage()` from the shipped ledger reports 20/20
movable, 4 boundaries, 24 entries, and *"apps/web/src/viewer can be deleted"*. But the test behind it
asserts every `covered` entry is reachable **through the facade's type** — which proves each *claim
is backed*, not that the *claims cover the ground*. Its 24 entries dissect this viewer as it stood
around 2026-08-06; the viewer is **129 TS files / 16,408 non-test lines / 53 test files** today, and
the list names none of the plan/sheets/specs canvas modes, collaborative peer cursors, dimensional
locks, viewer load timings, reference point clouds, GIS context, or the model-bounds allowlist.

**The family is inert.** All 12 packages were published on 2026-08-08 in two bursts and none has been
modified in the 15 days since. Adopting a dependency that is not moving, to replace code that changed
today, inverts the divergence risk it exists to solve.

**In its favour, and recorded so the decision can be revisited fairly:** it is MIT, genuinely well
engineered, and unusually honest — it states outright what it does *not* wrap and why, and the seam
ledger's design (a checklist that fails the build rather than ageing in a document) is a good idea
worth borrowing. **What would change the answer:** a Fragments-shaped load path — `open()` accepting
pre-converted fragment bytes, or a `KernelProvider` that streams them — plus a seam list derived from
this tree rather than from their plan.

### Fixed

- **`CLAUDE.md`'s numbers for this were wrong and are corrected in place.** It said "25 published
  packages" and a "seam ledger reporting 27 of 27 movable capabilities covered". Measured: the
  dependency closure is **12 packages**, and the ledger reports **20 of 20 movable, 24 entries
  total**. The file's own rule — *verify, don't recall* — applied to itself.

## v0.3.1066 (2026-08-24) — what is actually left, measured rather than listed

Docs only. No runtime or test change.

### Fixed

- **`R39-UPLOAD-CAP-APP ①` is complete; the ◧ on its bullet belongs to `R41-UPLOAD-WARK` alone.**
  Front half shipped v0.3.876, and the entire back-half work list — the three category (a) store
  sites — converted in v0.3.941–942. Re-verified against the tree: `routers/documents.py` and
  `routers/modules.py` ×2 pass `storage.upload_chunks(...)`, and the two `await file.read()` calls
  still in `modules.py` are the Excel/CSV sheet readers, which this entry itself files under (b) as a
  different item with a different risk profile. Category (c) is explicitly not worth a code change.
- **`R41-UPLOAD-WARK`'s resumable handshake is confirmed unbuilt** — the primitives (`put_stream`,
  `upload_chunks`, `stream_to_path`, `file_chunks`) all exist, but the only "resumable" in
  `storage.py` refers to range-request *downloads*. This one is real, open work.

### Changed

- **`R36-VIEWER-SUBAPP` slice 6 re-checked: still open, and "an INTEGRATION, not a build"
  understates it.** The five markup client methods and their callers are all present, exactly as the
  original measurement said. But every caller lives inside the `DrawingsRoom` class in
  `apps/web/src/drawings/drawings.ts`, where the markup layer is class state coupled to that room's
  DOM — `markupOn`, the `markup[]` array, `buildToolbar()`, `openPdfMarkup()`, a `.dwg-viewport`
  selector — not a mountable module. Making it reachable from the Sheets canvas means **extracting
  the layer first**. The measurement that produced the original framing counted *methods with
  callers*, which is the right check for "does this exist" and says nothing about whether it can be
  mounted elsewhere. **Reachability and reusability are different properties, and a caller census
  only measures the first.**

## v0.3.1065 (2026-08-24) — a feature that shipped, and a cell that said it had not

Docs and one test floor. No runtime change.

### Fixed

- **`R38-SOLVER-LOCKS ③` closed — the decided scope is built end to end.** Its entry still said
  *"the route has no client caller, so the whole feature is server-only today"*, which was the
  premise the whole item rested on. Verified in the tree: `apps/web/src/api/authoring.ts` exposes
  `solveConstraints`; `apps/web/src/viewer/dimLocks.ts` maps solved variables onto the guid-keyed
  recipes in `services/data/src/aec_data/edit.py` and **refuses a variable with no recipe by name**
  rather than dropping it silently; `apps/web/src/viewer/tools/authoringSection.ts` drives
  solve → plan → apply → publish → reload and reports over-constraint, conflicts and remaining
  degrees of freedom *whether or not anything is applicable*; and
  `apps/web/src/viewer/dimLocks.test.ts` covers it with 12 tests. Across-element locks remain a
  separate later item by the user's own recorded decision — not an unfinished part of this one.
- **The lane table said `R38-SYNC-VIEW ③` had "only cursor sync left".** Its own entry has carried a
  ✅ since the cursor PR landed. **Two places described one item and only one of them was updated**,
  which is the same failure the lane row itself already carries a correction about: a summary cell
  drifts from the entry it summarises, and the entry is the authority.

### Note

That makes **eight** items this session found further along than the roadmap recorded. The reliable
tell is not the entry's age or its tone — it is whether anyone re-ran the check it names. Every
closure above was made against the tree: the module, the call site, the test file.

## v0.3.1064 (2026-08-24) — the roadmap was behind the code, in seven places

Docs and one test floor. No runtime change.

### Fixed

- **`R23-BATCH-OVERLAYS` closed.** Every clause in it was already resolved — the FOV/FAR work built,
  the measured `gridOverlay` texture leak fixed, the instancing clause closed *unbuilt* with its
  measurement, `MeshStandardMaterial` needing no work, `ifclite-geom` declined on licence — and the
  item was still carried as partial. Closed against the **tree**, not the entry's own prose:
  `apps/web/src/viewer/cameraProfile.ts` exists, `apps/web/src/viewer/draft/gridOverlay.ts` caches
  bubble textures by tag with ownership moved to `dispose()`, and
  `apps/web/src/viewer/draft/gridOverlay.test.ts` now exists — the file that had no tests at all
  because `getContext("2d")!` was unassertable under happy-dom, which was the same root cause as the
  leak it was hiding.
- **`R41-MODEL-ALIGN` was filed in the wrong lane for the half that remains.** The defect half was
  Lane E and shipped in v0.3.1062. What is left — the yaw-only oriented bounding box with its ≥20%
  area-saving acceptance rule — lives in `services/data/src/aec_data/` (**Lane D**), needs a route in
  Lane G, and needs an Alembic revision, because `ProjectModel` has no transform column to hold an
  alignment. **Lanes are assigned by directory**, so an agent picking this up under a Lane E label
  would write straight into another lane's files while several sessions ship to `main` at once. It is
  also visibly bigger than its stated M.

### Note

Seven items examined over this session were further along than the roadmap said, including
`R39-VIEWER-OBS ②`, which had shipped **in full** on 2026-08-07 and stayed listed as open for a
fortnight. The sharpest case was `R41-MODEL-ALIGN`, whose own bracketed *"PREMISE-CHECKED
2026-08-06: HOLDS"* note had itself gone stale: **a verification stamp ages exactly like the claim it
blesses, and is more dangerous, because it tells the next reader not to re-check.**

## v0.3.1063 (2026-08-24) — the budget nobody could measure, and the one that still cannot be

R24-PERF-BUDGET stated three performance budgets and measured one. `perf_budget.py` kept the other
two declared as `unmeasured` **with a written reason** rather than asserting a server number in their
place, because *"a budget file that lists three budgets and quietly checks one is how a green suite
comes to imply more than it tested."* That sentence is the only reason this was closable at all: the
gap stayed legible for as long as it went unclosed.

### Added

- **A client beacon — `apps/web/src/ui/perfBeacon.ts` — and `click_echo` now has a real number.**
  One capture-phase click listener installed at the app entry sees every click in the app. That is
  the design decision worth stating: instrumenting call sites would have measured whichever handlers
  someone remembered to wire, and **a p95 over a remembered subset is a figure whose population
  nobody can state.**
  - **Two animation frames, not one.** A `requestAnimationFrame` callback runs *before* the browser
    paints, so measuring there reports the time to schedule the answer rather than to show it —
    consistently short, consistently wrong, and wrong in the flattering direction. The callback
    scheduled from inside that frame runs after the paint.
  - **Untrusted events are ignored.** A dispatched click answers instantly because no human was
    waiting on it; counting them would pull the percentile down with intervals no user experienced.
  - A rolling per-minute cap so a stuck UI cannot bury a genuinely slow p95 under thousands of fast
    synthetic ones, and intervals the clock cannot justify (a tab suspend, a clock change) are
    dropped rather than reported as slow clicks.
- **`POST /metrics/client`** as the sink, with `metrics.observe_client` / `client_quantile` /
  `client_count` alongside the existing request histogram — a **separate** histogram family, because
  folding paint intervals into the request histogram would corrupt `request_p95`, the one budget that
  was honest all along. Both client budgets land exactly on existing bucket edges (0.1 s, 1 s), so the
  reading is not an interpolation.
  - Refuses an anonymous caller: shifting a percentile an operator makes decisions from is not a data
    breach, it is a way to make the instrument lie, which is harder to notice.
  - Matches the budget name against `BUDGETS` rather than using it as a key — an unvalidated name
    would let a browser create unbounded histogram series in a long-lived process.
  - **Drops** implausible durations instead of clamping them. Clamping a hostile 9,999 s to 10 s
    files it in the slowest real bucket and quietly moves the p95; dropping leaves the percentile
    describing only intervals a browser could have produced.

### Changed

- **Beacon traffic is kept OUT of the latency histogram `request_p95` is read from** — found by
  reviewing this change's own diff, not by a failing test. The beacon posts on every click: tiny,
  fast, same-datacentre writes, up to two a second per open tab. Folding them into the histogram
  would have pulled the server p95 **down**, so `request_p95` would pass more easily the more the
  browser reported — **the instrument flattering the thing it measures, in the direction nobody
  checks, with the bias growing as adoption grows.** They stay in `http_requests_total` so an
  operator can still see the volume; the goal is to keep telemetry out of a budget written about
  user-facing latency, not to hide it. Asserted with a control (an ordinary request must still reach
  the histogram, or the check passes on a histogram that stopped recording anything) and
  mutation-checked by removing the exclusion — 51 observations became 76.
- **The sink takes `require_identified`, not `Depends(current_user)`.** The first draft took
  `current_user` and hand-rolled the anonymous check in the handler body. That works and is invisible
  to the static walker in `test_global_authz`, which would have recorded a new platform-global
  mutating route carrying no authorising dependency — *"a dependency that looks like a gate and is
  not"*, the exact shape this repo has shipped twice and written a gate about. The gate would have
  caught it; the point is that the gate's own docstring described the mistake before it was made.
, so a slow client fails it. It
  previously described one budget while reading like a verdict on the product.
- The client budget is judged by the **same** arithmetic as the server one, asserted directly. The
  two budgets nobody could measure are the two most likely to be handed a gentler rule on the way in,
  and a budget with its own softer arithmetic is a budget reporting on itself.
- A measurable budget whose beacon reported nothing comes back `no_observations` and is **not**
  within budget. A budget that vanishes from the report when its beacon breaks is the same
  "green implies more than was tested" failure arriving later and harder to spot.

### Not done, deliberately

- **`panel_load` stays `measurable: False`, and its REASON changed rather than vanished.** The
  blocker was never really the beacon — it was a *moment*. This app has no single point at which a
  panel becomes usable: `apps/web/src/ui/modal.ts` builds an empty shell and each of its ~20 callers
  fills it afterwards, so timing that chokepoint would record a few hundred microseconds of shell
  construction and file it as a panel load. **A budget reported green against a measurement of the
  wrong thing is worse than one openly unmeasured** — it is the exact failure this module exists to
  prevent, wearing the module's own badge. Flipping it would have been the easy half of the item and
  the dishonest one. `why_unmeasured` now names the missing moment instead of the missing beacon, so
  the next reader is not sent to build something that already exists; what remains is per-site work.
- The `STATUS_UNMEASURED` path is kept and still tested — against a temporary declaration, since no
  real budget exercises it now. An unexercised branch is one nobody notices deleting, and the next
  budget stated before it can be measured needs the slot.

## v0.3.1062 (2026-08-24) — the sixth site of a defect whose own fix enumerated five

### Fixed

- **Zoom-to-model framed a 2 km ground plane instead of the building, with presentation mode on.**
  `fitToModels` in `apps/web/src/viewer/app.ts` walked the whole scene expanding a `Box3` over every
  `isMesh || isPoints`, which swallowed the `2000 × 2000` shadow-catcher `world.ts` adds in that one
  render mode. The fit then received a **~1.4 km bounding sphere against a ~65 m building — the model
  drew at roughly 5% of the view.** It now measures the model population via `modelBox3`.

  **This is the sixth site of a defect whose own fix documented five.** `modelBounds.ts` exists
  because a scene walk kept swallowing that plane; its docstring names the first three, then records
  `measureSection.ts` and `envTools.ts` as "the fourth and fifth". R41-MODEL-ALIGN had *also* written
  the instruction that would have found this one — *"check whether the AABB-versus-OBB gap already
  affects our section box, zoom-to-model and any bounding-box UI"* — and the pass that acted on it
  fixed the section box and the storey grid and left zoom-to-model. **A checklist naming three things
  was followed for two, and the miss was invisible because the two fixes were real.** N−1 correct
  sites prove nothing about the Nth, and that holds for the pass that fixes them as much as for the
  code being fixed.

  Why it hid: it misbehaves only with presentation mode on, silently, in the permissive direction —
  nothing errors, the camera just sits too far back.

### Changed

- **`apps/web/src/viewer/modelBounds.test.ts` now gates `app.ts` too**, alongside the two files it
  already covered, and adds the camera fit as a *consequence* assertion in the style of its
  neighbours: the bounding-sphere **radius** the fit receives, not the box, because a correct box
  handed to a fit that takes the wrong sphere still frames the wrong thing. **Mutation-checked** by
  restoring the scene walk and confirming the gate fails by filename.
- **A twin test pins reference overlays inside the fit.** `modelBox3`'s population is loaded
  fragments models, while the walk it replaced included `isPoints` deliberately — survey scans and
  reference geometry. So the fit passes `referenceModels` explicitly. Without the twin, a "fix" that
  simply dropped them would trade a 2 km fit for one that silently ignores a survey scan and every
  other assertion would still pass.

### Docs

- **R39-VIEWER-OBS ② closed — it shipped on 2026-08-07 in #249 and sat listed as open for a
  fortnight.** Verified end to end before closing rather than read: the load journey is instrumented
  (fetch → parse → first frame, one row per load), posted to our own API, and
  `GET /projects/{pid}/model/load-timings` answers p50/p95 per size band with `ok_rate` beside every
  percentile so a stalling band cannot show a good p95 drawn from its survivors. The optional
  `timings` dependency **is** pinned — dropping it fails `clientCallers.test.ts` by name
  (`+ "reportViewerLoad"`), confirmed by applying that mutation and watching it go red.
- R41-MODEL-ALIGN records the defect half as done and leaves the OBB feature at its stated size.

## v0.3.1061 (2026-08-24) — main went red on a frozen route that had quietly gained a caller

### Fixed

- **`/projects/preview-bundle` was frozen in `test_route_reachability.py`'s `KNOWN_UNCALLED` and
  v0.3.1060 gave it a caller.** PR #336's `.mass` preview calls it from
  `apps/web/src/api/library.ts`, so the allowlist entry became a false claim — "no client calls this"
  when one now does. The gate caught it on the merge and **CI went red on exactly this and nothing
  else.** The entry is deleted rather than updated: this ratchet only ever comes down.

  My pre-merge review missed it. I checked the things a new job kind can get wrong — mutating flags,
  privilege classification, tray labels — and did not think to ask whether any *route* in the frozen
  allowlist had gained a caller. Adding a client call to a previously-uncalled endpoint is exactly
  what a feature like `.mass` preview does, so that question belonged on the list.

### Measured, and it corrects v0.3.1059

- **The suite's true peak disk use is 17.4 GB** (start 158,232 MB, min 140,462 MB, over a 1238 s run
  at 15 workers). v0.3.1059 said the within-run peak was "somewhere else and I have not found it";
  it is real, it is the suite, and it is larger than the ~12 GB I had estimated against a nearly-full
  drive.

  The reason it can be measured now is that **~143 GB of unrelated space was freed on this machine
  while the work was in progress** (used went 919 GB → 776 GB). So the earlier conclusion "this
  machine cannot fit the suite" was *correct* — 17.4 GB does not fit in 11 GB — but the storage sweep
  was never going to fix it, and an earlier draft implied it might. Both halves are now known: the
  sweep removed a real 1.42 GB/run accumulation, and the 17.4 GB transient is the suite's own working
  set.

- **`test_modules` failed locally with `database is locked` and passes alone** (exit 0). CI did not
  fail on it. Local SQLite lock contention under 15 parallel workers, not a defect — recorded so the
  next reader does not chase it.

## v0.3.1060 (2026-08-21) — the analyses become Runs: clash, IDS, cost and energy go through the queue

Merged from PR #336 (`cursor/reach-and-feel-92e9`), reviewed and version-stamped on merge — this
repository ships version-numbered releases, so an `Unreleased` heading would leave the work with no
version. Claude Code owns R26-V-TIMING, R24-PERSONA-SHAPE,
R24-IDENTITY, PHOTO-PIN, CMMS-OPS; this change set does not touch them.

### Added

- **R24-RUNS-INBOX routing.** Clash (struct + federated), IDS, cost, and envelope energy enqueue as
  job kinds (`clash_detect` with optional BCF topics, `clash_federated`, `ids_validate`,
  `labor_estimate`, `energy_analyze`) and the Tools screens poll via `apps/web/src/api/waitForJob.ts`.
- Timeout is a `JobStillRunning` outcome (info toast → job tray), not an invented failure. Covered by
  `services/api/test_inbox_jobs.py`. A second clash run with `create_topics` skips Topics that already
  name the same pair. Shrinking an array past a moved member is a refusal, not a successful publish.
- **R38-SYNC-VIEW cursor.** `apps/web/src/viewer/planTransform.ts` reads the six `data-plan-*`
  attributes PLAN-TRANSFORM already writes; the plan pane paints a 3D-ground cursor from them.
- **R38-ARRAY-LIVE UI.** Groups panel **Re-edit** calls `set_array_params`; `list_groups` returns the
  persisted `Pset_MassingArray` definition so the button has something to edit.
- **R21-4D-CLASH install-before-support.** `GET /projects/{pid}/clash/sequence` still reports space
  contention, and now also checks directed IFC pairs from `aec_data.support_graph` against activity
  `element_guids`. A supported element that starts before its support finishes is a finding; unstated
  `IfcRelConnectsElements` joins and bounding boxes are not a load path. Analyze panel **Sequence
  clash**. `IfcRelConnectsStructuralMember` is read from its real attributes (the previous reader
  looked for RelatingElement and collected nothing).
- **R28-BUNDLE preview.** Open Project reads `POST /projects/preview-bundle` first and shows excluded
  tables (users, audit log, settings, connections) before import. ⌘K save is labelled `.mass`.

Merged from PR #336 (`cursor/reach-and-feel-92e9`), reviewed and version-stamped on merge — this
repository ships version-numbered releases, so an `Unreleased` heading would leave the work with no
version. Claude Code owns R26-V-TIMING, R24-PERSONA-SHAPE,
R24-IDENTITY, PHOTO-PIN, CMMS-OPS; this change set does not touch them.

### Added

- **R24-RUNS-INBOX routing.** Clash (struct + federated), IDS, cost, and envelope energy enqueue as
  job kinds (`clash_detect` with optional BCF topics, `clash_federated`, `ids_validate`,
  `labor_estimate`, `energy_analyze`) and the Tools screens poll via `apps/web/src/api/waitForJob.ts`.
- Timeout is a `JobStillRunning` outcome (info toast → job tray), not an invented failure. Covered by
  `services/api/test_inbox_jobs.py`. A second clash run with `create_topics` skips Topics that already
  name the same pair. Shrinking an array past a moved member is a refusal, not a successful publish.
- **R38-SYNC-VIEW cursor.** `apps/web/src/viewer/planTransform.ts` reads the six `data-plan-*`
  attributes PLAN-TRANSFORM already writes; the plan pane paints a 3D-ground cursor from them.
- **R38-ARRAY-LIVE UI.** Groups panel **Re-edit** calls `set_array_params`; `list_groups` returns the
  persisted `Pset_MassingArray` definition so the button has something to edit.

## v0.3.1059 (2026-08-21) — the per-test sweep covered the database and not the storage beside it

### Fixed

- **A full suite run filled the disk and reported `database or disk is full` across 71 unrelated
  suites.** `_run_one` has swept each test's SQLite database as that test finishes since
  R41-TEST-RESIDUE — its own comment says *"removing each as it finishes keeps the peak at roughly
  one test's worth."* The per-test **object-storage dir beside it was never added to that line.** It
  was cleared only at the START of the next run of the same test, so it accumulated across the whole
  run and then across runs: **93 directories and 1.42 GB** were sitting there when a run finally
  exhausted the disk mid-suite.

  The fix is one `shutil.rmtree` under the guard that was already there, so both halves obey the same
  rule — a FAILED test keeps its storage, because the sidecar state is as much the evidence as the
  rows are, and `KEEP_TEST_DB=1` keeps both.

  **Measured before and after.** Before: free space fell 544 MB per 20 seconds. After: 383 tests
  completed with live `_storage_*` directories holding at **0** and free space flat at 13.1 GB.

- **The first explanation written into this file was wrong, and is retracted in place.** *"Lower
  TEST_JOBS — the peak scales with the worker count"* is the obvious reading and it is false: 8
  workers consumed ~11.6 GB, **3 workers consumed ~12.5 GB**. The footprint is cumulative over tests
  completed, not concurrent over workers, so fewer workers only reach the same total more slowly.
  Both measurements are recorded next to the retraction, because the plausible explanation would have
  sent the next person to tune a knob that does nothing.

### Added

- **A disk-full run now says it ran out of disk.** The runner scans captured output for
  `database or disk is full` / `no space left on device` / `disk i/o error` and prints which suites
  hit it plus free space before and after — instead of leaving tracebacks that name everything except
  the cause. Two runs here were diagnosed as contention, then as a code regression, before anyone
  read far enough down a traceback to find the real message.

- **Directories the runner does not own are reported, never deleted.** A test that sets its own
  `STORAGE_DIR`/`IFC_DIR` owns that name, so the runner prints the count and size and leaves it
  alone — *"the sweep must never propose something it does not own"* is the rule the database half
  already follows.

- **`test_sweep_guard.py` grew the storage half (18 assertions).** The load-bearing one records why
  the sweep derives its names instead of globbing:

      PASS  the naive glob DOES hit tracked source -- which is why the sweep derives instead
            test_ifc_cache.py, test_ifc_path_containment.py, test_storage_key_parity.py

  `glob("test_storage_*")` and `glob("test_ifc_*")` match three **tracked source files** in that
  directory. Every manual cleanup during this work ran `git ls-files` on each candidate and deleted
  directories only; that caution is now a test rather than a habit. A further assertion pins the
  symmetry that was missing — both the database and the storage sweep must sit under the same
  pass-and-`KEEP_TEST_DB` guard, so neither can drift away from the other again.

### Known, not fixed — and separated from this change on purpose

`test_edit_undo` fails intermittently. It passes standalone, and twice consecutively under the
runner's exact invocation (18.7s, 16.9s); it failed once inside a 6-way concurrent run. It also
failed in a run at `095f6277`, **before any of these runner changes existed**, so it is pre-existing
and not caused by the sweep. The cause is not identified and is not guessed at here.

### What this does NOT fix, stated plainly

**The within-run disk consumption is not explained and not fixed by this change.** The sweep removes
*accumulation between runs* — that is measured and real. It does not touch the transient peak. A run
started with **20.9 GB free** still drove the disk down to **1.9 GB**, i.e. ~19 GB consumed, with
live `_storage_*` directories sitting at 0 the whole time and only ~1.3 GB findable on disk under
`services/api` afterwards. The space returns within a minute or two of the workers exiting.

So the peak is transient, it is somewhere other than the per-test storage dirs, and I have not found
it. An earlier draft of this entry implied the sweep addressed the disk problem; it addresses one of
two problems and the larger one is still open. The disk-full detector added here at least makes the
condition announce itself instead of scattering unrelated tracebacks.

CI is unaffected — it runs on a clean runner with far more headroom.

## v0.3.1058 (2026-08-21) — the exemption matched the package, not the advisory

### Fixed

- **`scripts/audit_npm_gate.py` suppressed every advisory on a package as soon as ONE of them was
  exempt** — shipped in v0.3.1056, found the same night by reviewing my own diff.
  `next((k for k in keys if k in EXEMPT), None)` matches if *any* key hits, so the whole row went to
  `exempted`. The key was per-advisory; the matching was not.

  **This fails in the normal case, not an exotic one.** An exemption exists precisely because that
  advisory has no acceptable fix — so it persists, and the next advisory to land on the package
  arrives *beside* it rather than replacing it. `brace-expansion` already carries two advisories at
  once. Measured on a synthetic report: a fresh **CRITICAL** with an in-range fix came back as
  `blocking = []` while the row printed as exempt. A blocking CI gate that silently stops blocking is
  the exact defect this file was written to fix, reproduced one layer in.

  `classify()` now classifies each advisory on a package independently, blocks on the remainder, and
  only reports a row as exempt when **every** advisory on it is covered by a live entry. The blocking
  line names just the advisories that block — a work list rather than a row to re-derive — and says
  how many siblings are still exempt, so a reader can tell which half moved. A row with mixed live
  and lapsed exemptions blocks on the lapsed one. Where the whole row is covered it quotes the
  **soonest** expiry, since that is the date it stops being settled.

- **The test that was supposed to pin this never exercised the failing case.** It passed `via=OTHER`,
  which *replaces* the exempt advisory rather than adding to it — so it only covered the shape where
  the old advisory had vanished, which already worked, and stayed green against the defect.
  It now uses the additive shape `via=[*ADV, *OTHER]` and asserts four things: the new advisory
  blocks, the blocking line names only it, the line says the rest of the row is still exempt, and a
  lapsed sibling drags the row into blocking. Mutation-checked by restoring the old `next(...)`
  matching: all four go red, and the first one reports *"the old exemption silently covered a finding
  nobody looked at"*.

  *A test can assert a property by name and not test it.* The name was right, the fixture was the
  easy shape, and nothing in the suite could tell the difference.

## v0.3.1057 (2026-08-21) — a job kind that needs to know who you are, and the identity it would have believed

### Fixed

- **A latent identity hole, closed in the commit that would have made it live.** `routers/jobs.py`
  built a job's params as `{**caller_body, "project_id": pid}` — every key the caller sent merged
  straight through. Harmless for exactly as long as no handler read an identity out of it, which was
  true: nothing read `params["actor"]`. This release adds the first kind that does, and
  `clash_intel.coordinate` records the actor **and their party role** against every coordination
  issue it creates, reopens and resolves. So the route now writes `project_id` and `actor` *after*
  the caller's params, and `services/api/test_clash_federated_job.py` enqueues with
  `params={"actor": "someone-else"}` and asserts the stored job carries the authenticated user.
  Mutation-checked by restoring the old merge order: the job comes back with `actor='someone-else'`.
  **A latent hole becomes a live one the moment something reads the field, so the read and the fix
  belong in one change** — shipping the handler first and the ordering later would have been a real
  vulnerability for the length of that gap.

### Added

- **`clash_federated` as a job kind** (R24-RUNS-INBOX). `clash_detect` was already queued, but it is
  the *single-model narrow phase*; the run the coordination screen performs is the **federated** one,
  and it had no kind at all. Registered `mutating=True`, because `coordinate()` writes records and
  must take the project lock like any other write — with the twin asserted, so a set containing
  everything cannot pass for a set containing this.
- **Both halves of the job are tested, and the second one nearly was not.** The first version of
  `test_clash_federated_job.py` asserted only the refusal path — and a test that asserts only what
  must *not* happen passes on a handler that does nothing at all: deleting the entire body of
  `_clash_federated` and leaving the `raise` would have been green. The twin registers two discipline
  models and asserts the job succeeds over both, finds cross-model clashes and groups them into
  tracked issues. Measured on the fixture: **64 clashes into 12 coordination issues.**
- **Fewer than two discipline models FAILS the job**, with the remedy in the message, rather than
  returning an empty result. "No clashes" and "there was nothing to compare" are the two answers a
  coordination report must never merge. Asserted by running a real worker and reading the row, not by
  calling the handler.
- **An existing gate caught the half I had not thought about.**
  `test_dispatcher_privilege_coverage.py` refuses to let a job kind be *registered but classified
  nowhere*, and refuses a MUTATING kind that is "neither elevated nor acknowledged". Both fired on
  `clash_federated` in the full run. The classification entry it demands is not a checkbox — it is a
  written reason, and writing this one out is what confirms the queue is not a side door around a
  stricter endpoint: the direct route `POST /projects/{pid}/clash/federated` is `editor`, and so is
  enqueuing. That parity is now *asserted* rather than asserted-about, by reading `require_role` out
  of `routers/analysis.py` and comparing it through `ROLE_ORDER`, so raising the route without
  raising the queue goes red.
- **`services/api/test_job_kind_labels.py` — the Python job registry and the web tray's label map are
  two hand-maintained lists of one thing, in two languages, and nothing compared them.** The tray
  falls back to rendering the raw kind, which is right for a plugin and wrong for us: a kind we ship
  without a label degrades in silence. Both directions fail — an unlabelled kind, and a label naming
  a kind nothing can produce any more (the more insidious one, since it reads as a live feature). It
  caught `clash_federated` before the label was added, which is how I know it works.

### Still open on R24-RUNS-INBOX

The four **screens** still call their analyses synchronously behind a modal, so the inbox stays empty
until they are switched to enqueue-and-poll. The kind is reachable today through
`POST /projects/{pid}/jobs`, which the web client already wraps as `enqueueJob` — what is missing is
the call site, not the capability. Named here rather than implied, because "the job kind exists" and
"a user can produce a Run" are different claims and only the first has shipped.

## v0.3.1056 (2026-08-21) — the npm half of the supply-chain scan could not fail, and every advisory was in the half it skipped

### Fixed

- **Three HIGH advisories that had been sitting in a green CI job.** `brace-expansion` carries two
  (GHSA-mh99-v99m-4gvg, GHSA-rgw5-rvv9-x895) and is present in three copies; `nanoid` carries one.
  All fixed by an in-range bump — four packages, a 17-line lockfile diff from
  `npm audit fix --package-lock-only`. They were not hard. They were invisible.
  *(npm's own summary counts two "vulnerabilities" because it counts affected PACKAGES, not
  advisories. Both numbers appear below; they are counting different things.)*
- **The step that hid them was neutered three independent ways, and any one alone was enough.**
  `scripts/audit_lock_gate.py` exists because the pip-audit step carried `continue-on-error: true`
  and a trailing `|| true`, found a HIGH, and reported success. The npm step **fifty lines below it
  in the same file** had both of those — plus `--omit=dev`, over a tree in which *every* advisory is
  dev-only. Measured before writing anything:

      npm audit --omit=dev   ->  "found 0 vulnerabilities", exit 0
      npm audit              ->  5 advisories, 2 of them HIGH

  Fixing one half of a lesson and leaving its twin in the other language is the shape here; the
  lesson had been written down, and it had been written down in one language.
- **The roadmap sentence that vouched for it.** R37's §4 said "`pip_audit`/`npm audit` ran
  2026-08-01 … do not re-open this as if unknown". The npm half of that was true and useless — it
  ran, over a population that excluded every finding. Corrected in place, because a true sentence
  ("it ran") can carry a false one ("so it is covered").

- **CLAUDE.md's viewer-extraction blocker was false when it was written.** It says the MassingViewer
  packages "are not on npm yet. Until they are, this repository keeps its own viewer and nothing here
  should change on account of the extraction." Queried against the npm registry: **20 of the 25
  package names are published, all MIT, all dated 2026-08-08** — including the "@massing/embed"
  facade at 0.2.0, whose eleven declared dependencies are every one of them published. That section
  is dated **2026-08-15**, a week later. A standing instruction can be stale on the day it is
  written, and this one named its blocker so confidently that no reader would think to check.

  **Only the factual claim is corrected; the decision it was gating is untouched and still yours.**
  Adopting the facade is a multi-release architectural commitment with two deliberate breaking
  changes (async viewport creation, add/remove replacing `showModel`) and thirty-odd commits of
  divergence to reconcile — not something to start off the back of a registry query. The standing
  advice below it ("keep shipping viewer work") was never contingent on the npm question and is
  unchanged.

### Added

- **`scripts/audit_npm_gate.py` — a blocking npm-advisory gate**, mirroring its Python sibling's
  asymmetry: block on advisories with a published fix, report the rest, so the no-fix case needs no
  allowlist entry and the exemption list stays near-empty by construction. Two deliberate
  differences. It audits the **whole tree including dev**, because this is what builds and signs the
  desktop and mobile artifacts and a build tool that can be made to hang is a supply-chain problem
  even though no byte of it reaches a browser. And npm's **semver-major** fixes block rather than
  being waved through — npm's proposed "fix" here is a *downgrade* of `@capacitor/cli` off the 8.5.x
  line, and a rule that excused those would excuse a genuine major fix too.
- **Exemptions keyed `package:GHSA-id`, not by package.** A new advisory on an already-exempt package
  produces a key nobody exempted and blocks — asserted directly, because the coarse spelling would
  have let the next finding through under an old decision. There are **three entries for one
  finding** — npm reports each hop of a dependency chain as its own row, so `uuid`, `xcode` and
  `@capacitor/cli` each need exempting or the same advisory blocks three times. The entry that
  carries the analysis is the `uuid` one, and it carries a reading rather than a rationale: the `uuid` advisory is a missing bounds check in **v3/v5/v6 when a buffer
  is passed**, and the only consumer here calls `uuid.v4()` with no arguments, at one line of
  "node_modules/xcode/lib/pbxProject.js" and nowhere else. Checked by opening the file.
- **A blocking half for the MCP tool-poisoning self-audit too** — found by sweeping every workflow
  for the same shape rather than stopping at the one that was reported. `security.yml` ran
  `mcp_tool_audit` with `continue-on-error: true` *and* `|| true`, into a job summary, and nothing
  anywhere asserted the result. `test_invisible_unicode.py` already tested the **detector**; that
  proves the detector works, not that what we ship is clean. It now asserts our own catalog — 18
  tools, 0 findings — with the vacuity twin (`tools_scanned > 0`, because "0 findings over 0 tools"
  is the pass this repo keeps re-learning about). Mutation-checked both ways: a planted finding and
  an empty catalog each go red, each on the right assertion. This one matters more than most,
  because tool poisoning hides in precisely the characters a human reviewer cannot see — code review
  is not a control against an invisible character.
- **`services/api/test_npm_advisories.py`** — the offline half: the classification rules driven with
  synthetic reports (including the twin that an empty report blocks nothing, so a gate that refuses
  everything cannot pass), dated-and-unexpired exemptions, a cyclic `via` chain terminating, a broken
  audit run failing loudly instead of reading as clean, and the workflow step carrying neither escape
  hatch nor `--omit=dev`.

## v0.3.1055 (2026-08-21) — the spatial tree is a tree, and a container build can be seen before it lands

### Added

- **`GET /projects/{pid}/spatial-tree` and `POST /projects/{pid}/elements/properties`**
  (R43-VIEWER-CONFORMANCE) — the two endpoints the 2026-08-13 conformance run found absent. The
  tree is the file's real `IfcRelAggregates` chain (Project ▸ Site ▸ Building ▸ Storey ▸ Space),
  every node carrying its **GlobalId**, built at index time rather than grouped from the `storey`
  name string. The name-grouped version is five lines and looks identical until the model has two
  buildings that each have a "Level 2" — the ordinary case on any campus — at which point it merges
  them with no symptom: right count, right elements, wrong building.
- **"By spatial structure" in the model browser** — the first grouping in it keyed on a GlobalId
  rather than a label, and the mode is offered **only when the server actually sent a tree**. An
  option that silently fell back to storey names would be the original defect wearing the fix's
  label, which is worse than not offering it because the label now vouches for it.
- **A PR container build** (R39-CONTAINER-PR). `containers` is gated `push` + `refs/heads/main`, so
  it reported `skipping` on every pull request and *structurally could not* exercise a change to
  itself; both Dockerfiles and two Docker-action bumps merged all-green without one green having run
  a container build. `containers-pr` builds both images with `push: false`, no registry login and no
  `packages: write`. Its gate, `services/api/test_container_pr_gate.py`, turns on the assertion that
  the **two matrices stay equal** — a third image added to the publish job alone would restore the
  hole for that image and every other assertion would still pass.

### Changed

- **Storey elevations ship with the unit they are IN, unconverted** — and that was checked against a
  real file rather than reasoned about. `samples/school_str.ifc` returns `-2499.99`, `0`, `3800`,
  `7599.99`, `11399.99`: **millimetres**, while the consumer's interface documents `elevation` as
  "metres above project zero". Converting on the assumption of metres would have placed a four-storey
  school's roof 11.4 **kilometres** up, from a number that looks entirely reasonable in the payload.
  The value passes through with `elevationUnit` beside it instead. Same run confirmed the join the
  whole feature rests on: **1,551 of 1,551 elements carry a `storey_guid` and all 1,551 resolve to a
  node of the tree** — the synthetic fixture has one element and could not have shown that.
- **The element index is `index_schema: 2`** and carries `storey_guid` and `predefined_type` per
  element. An index written before it is **refused (422, with the remedy in the sentence)** by
  `/spatial-tree` rather than answered with a null: a v1 index and a model with genuinely no
  `IfcProject` are the same absence and different answers, and only one is fixed by re-publishing.
- **The tree checks the payload's SHAPE rather than its truthiness** — caught before shipping, and it
  would have broken the public Pages demo specifically. `apps/web/src/demo/demoApi.ts` degrades an
  *uncaptured* GET to `[]` instead of throwing, so the demo build would have handed `[]` to the new
  code; `[]` is truthy, and the walk then read `.children` off an array. Reproduced by mutation
  (`TypeError: node.children is not iterable`), fixed, and pinned in `apps/web/src/tree/tree.test.ts`.
  The build with no backend to blame is the one where a fixture layer's fallback becomes a crash.
- **Lane E claims `apps/web/src/tree/`**, and the unowned-file ratchet is re-seated **48 → 39**.
  The roadmap warns that guessing an owner for a directory is how the register overlap was made, so
  the question asked was *who imports it*: `tree/tree.ts` has exactly one importer in the whole tree
  and it is Lane E's. No second lane reaches it, so there was no boundary to negotiate. The ceiling
  goes to the **measured** number rather than down by the size of the directory — 48 was carrying
  slack nobody had spent, and unspent slack lets the next few files in for free.
- **`test_bake_shared` no longer fails on Windows.** `st_mode & 0o777` is meaningless on NTFS, so
  the 0700 assertion was *unsatisfiable* there and had been red on every local run. It is now
  SKIPPED with the reason printed — not softened to a pass, because a green line for a check that
  never ran is the failure this repo keeps writing tests about. ubuntu CI still holds the claim.

### Fixed

- **The conformance report was wrong twice, and re-deriving it before building found both.**
  `elements/properties` is a **POST**, not the GET recorded: the run probed with GET, hit
  `/elements/{guid}` with `guid="properties"`, correctly concluded the route was absent, and carried
  the wrong method into the conclusion. A GET-shaped endpoint would have passed every check in that
  file and been unreachable from the consumer forever. And the population was **nine calls, not
  seven** — `snapCandidates` and `drawing` are called by the same adapter and appear in no row, so
  "1 of 7" was measured against a denominator nobody derived. Neither of those two is fixed here.
- **R39-NGINX-INHERIT ② was already shipped** (v0.3.1028) and its roadmap entry never said so —
  written and fixed the same morning, which is the most convincing kind of stale entry because
  nothing about its age suggests re-reading it. Verified rather than assumed: 13/13 green, and the
  gate already derives the scoped locations exactly as the entry asks.

## v0.3.1054 (2026-08-20) — ruff `>=0.16.3`, validated by running it

### Changed

- **ruff floor `>=0.6` → `>=0.16.3`** (#331). Held back from the v0.3.1053 batch on purpose: a
  linter floor is not a normal dependency bump — a new major flags code that has been fine for a
  year — and **`requirements-dev.txt` is covered by no lock**, so no gate would have caught a
  regression. The dev venv was already on 0.15.20; only the floor was stale.
- **Validated by running it, not by reading a changelog.** 0.16.3 installed to a temp directory
  (never the shared venv, which other sessions use) and pointed at the exact scope `ci.yml` lints —
  `src/ ../data/src/` from `services/api`. **Both 0.15.20 and 0.16.3 report "All checks passed."**
  The reasoning is recorded beside the pin, because the next person to see this floor move will want
  to know whether anyone actually looked.

## v0.3.1053 (2026-08-20) — four dependency floors, one lock recompile

### Changed

- **orjson `>=3.12.0`** (#334), **boto3 `>=1.43.73`** (#332), **redis `>=8.1.0`** (#327) and
  **opentelemetry-instrumentation-fastapi `>=0.65b0`** (#330), with `requirements.lock` recompiled in
  `python:3.12-slim`. Resolved: **orjson 3.11.9 → 3.12.0, redis 8.0.1 → 8.1.0, and nothing else** —
  boto3 and opentelemetry were already satisfied by the existing pins, so raising those floors moved
  no package at all.
- **Batched deliberately.** Each raises a floor above what the lock pins, and
  `test_lock_satisfies_requirements` compares the two — merging them one at a time would have
  reddened `main` three times before the fourth fixed it. Verified in both directions: the gate
  passes on the new lock and **fails on the old one**.

### Note

- **ruff (#331) is deliberately not in this batch.** It targets `requirements-dev.txt`, which no lock
  covers, and `>=0.6 → >=0.16.3` is a major jump on the linter CI itself runs — a new ruff can flag
  code that has been fine for a year. That needs its own change with the lint output actually read,
  not a floor bump waved through.

## v0.3.1052 (2026-08-20) — main went red on the size ratchet; SCALE-SEAM ㉒

### Fixed

- **v0.3.1051 reddened `main`.** `riskDigest` took `client.ts` to 3,132 against a 3,125 ratchet, and
  the release that added it ran vitest, lint, build and the route gate — **but not
  `test_file_sizes`**. That ratchet *had* been run earlier in the same session, before a different
  edit. **A check run before the change it is meant to cover is not a check of that change**, and
  reusing an earlier green is how a verified-looking release ships a red one.
- **SCALE-SEAM ㉒ — `riskDigest` and `riskBoard` move to `api/risk.ts`.** The ratchet's own comment
  says the friction should buy a cluster out of the file rather than buy the pin a higher number,
  so the pin came **down**: 3,125 → **3,120**, below where the session started.

## v0.3.1051 (2026-08-20) — the risk card now shows what its narrative rests on

### Changed

- **The dashboard risk card calls `/risk-digest` instead of `/ai/risk-summary`.** Both return the
  same headline and ranked risks; the digest also returns the **drivers** — SPI, percent complete,
  EAC, variance-at-completion, open RFIs / submittals / change orders, incidents and the top alerts.
  The card now prints them: *"Computed from: SPI 0.94 · 62% complete · VAC −$180,400 · 7 open RFIs"*.
- **An owner/PM report is exactly where that matters.** The prose is the claim; the drivers are the
  evidence. A risk narrative a reader cannot check against anything is the same as no narrative —
  the same principle as make-ready's cited blockers and the plan that names its cut height.
- `/risk-digest` shipped with no client caller and was invisible until v0.3.1049 stopped the
  generated OpenAPI types vouching for routes nothing calls.

### Note

- `riskSummary` is now recorded as uncalled **with a reason and an expiry**, not deleted:
  `/ai/risk-summary` is the smaller, cheaper, prose-only call and a reasonable thing for an embedded
  caller to want. It has no caller *here*, which is what that list is for.

## v0.3.1050 (2026-08-20) — the pay period could not be closed from the product

### Fixed

- **`POST /cost/advance-period` had no client caller**, and `cost.advance_period` is the **only**
  code anywhere that rolls an SOV line's `completed_this` into `completed_prev`. So the
  pay-application cycle could not advance: every AIA application re-billed the same "completed this
  period" amounts as the last one, because nothing closed the period. Not a missing view — a missing
  **step in a workflow the product claims to run**, on the money path.
- A **✓ Close pay period** control now sits in the owner-billing row beside the G702/G703 and invoice
  buttons. It confirms first, and the confirmation states the **consequence** — every line rolls and
  resets, no undo in the app — rather than asking "are you sure".
- It reports the count the server actually advanced. **"0 lines" is a real answer** (nothing was
  billed this period) and is worded so it does not read as a failure.

### Changed

- The client method went into `api/cost.ts`, the seam that owns `/cost/*`, rather than `client.ts`.
  The extraction ratchet caught the difference — `client.ts` would have gone 3,125 → 3,136 — and the
  right home was already there.

## v0.3.1049 (2026-08-20) — the generated types were vouching for 29 routes

### Fixed

- **`test_route_reachability` counted `api/schema.d.ts` and `api/openapiTypes.ts` as client code.**
  Both are emitted **from** the OpenAPI spec, so every route in the API appears in them by
  construction — a route's presence there restates the server's own route table and says nothing
  about anything calling it. Excluding them took the uncalled count **56 → 85**: **29 routes were
  vouched for by a generated file.**
- **The file already had the principle and applied it to one input.** `demo/` is excluded because
  `demoData.json` is a captured snapshot keyed by request path, *"so including it would make every
  crawled route look 'called' by its own recording."* Generated types are the same argument; this is
  that sentence finishing.
- The 29 are frozen **grouped by why**, because "frozen" without a reason is how an allowlist becomes
  a fiction: external callers and browser redirects (OAuth callback, e-sign webhook, SCIM discovery,
  public listing/statement), signed-URL handoffs, server-built download links — and **nine genuinely
  unreached capabilities** that are the reason the exclusion was worth making, including
  `/cost/advance-period`, `/budget/two-sided`, `/accounting/chart-of-accounts` and `/risk-digest`.
- Mutation-verified: bypassing the exclusion makes all 29 read as called, and the rot check catches
  it.

## v0.3.1048 (2026-08-20) — plans can be coloured by discipline; the flag existed and nothing sent it

### Added

- **DISC-poché is reachable.** `plan.svg` has accepted `by_discipline` since it shipped — it strokes
  each element's linework in its discipline colour and adds a legend — and **`planParams()` never
  sent it**, so every plan in the product came back monochrome. Built, routed, unreachable: the same
  shape as the six routes v0.3.1044 surfaced, one parameter down.
- A `◑` toggle on the plan pane turns it on. **Off by default**, deliberately: a monochrome plan is
  the drafting convention, and colour here is an analysis overlay rather than the sheet you would
  issue.
- The parameter is **absent rather than `false`** when off — the route reads them the same way, and
  the shorter URL is the one that makes sense when a user copies it out of the pop-out button.
  Asserted on the encoded query, because what reaches the route is the only thing the route can be
  wrong about.

## v0.3.1047 (2026-08-20) — the split-pane canvas layout is gone

### Removed

- **`planPane.dock("side")`** — the original 38% strip beside the model. R36-VIEWER-SUBAPP ④
  replaced it at v0.3.918 with a mode switch that makes the plan the *whole* canvas, on the grounds
  that a plan occupying a third of the screen is a **slice** of the model rather than a peer of it.
  Nothing outside the tests had called it since, and `specPane.dock` already declared
  `"full" | "hidden"` — this signature was the odd one out.
- **A second, unreachable way to arrange the canvas is exactly what a mode switch exists to
  prevent.** Leaving it live invites it back by accident, which this repo's own record shows
  happening more than once. Its test now asserts the invariant that replaced it: an open plan is the
  whole canvas, never a slice.

## v0.3.1046 (2026-08-20) — conditions of approval reach the screen; SCALE-SEAM ㉑

### Added

- **`GET /entitlements/conditions` has a client caller and a surface.** R22-ENTITLEMENT ② shipped
  the engine and route with neither — an approval's conditions split into tracked items, tagged by
  topic, with quantities extracted beside the sentence they came from. It renders in the Design
  room beside the review-cycles card.
- **Two distinctions the card refuses to flatten**, because both are the point:
  - **`unparsed` is shown separately from `open`.** A condition nobody could read is not a condition
    anybody has assessed; folding it into "open" would make the register look complete while the
    unreadable ones sit unexamined. Nothing is ever rendered as satisfied — discharge is a human act.
  - **An approved entitlement with an empty conditions field reads "unrecorded", not "clean".**
    Approvals almost always carry conditions, so a blank field far more often means nobody typed
    them. Printing "0 conditions" there would be a confident wrong answer about compliance.

### Changed

- **SCALE-SEAM ㉑ — `/entitlements` leaves `client.ts` for `api/entitlements.ts`.** Forced, not
  chosen: adding the method put the file at 3,136 against a 3,129 ratchet, and that pin's comment
  says the friction should buy a cluster out of the file rather than buy the pin a higher number.
  **3,129 → 3,125 — the file came down while gaining a method.**

## v0.3.1045 (2026-08-20) — Make-ready reaches the screen: "can next week's work actually start?"

### Added

- **`GET /schedule/make-ready` has a client caller and a surface**, having shipped as a tested
  engine and route with neither. READY-AGENT checks every activity starting inside a window against
  its preconditions — incomplete predecessors by ref and % complete, open submittals by ref and
  state — and returns a ready/blocked verdict. It sits beside the Lookahead card in the Schedule
  room, because the two answer adjacent questions: **the lookahead says what is coming; make-ready
  says whether it can start, and what is in the way.**
- **Every blocker prints its evidence**, never a bare flag — *"FDN-12 is 40% complete"*, *"open:
  SUB-003 (in_review)"*. A readiness verdict the superintendent cannot check is the same as no
  verdict. Blocked activities sort first: the list exists to be acted on.

### Note

- **Premise-checked against the adjacent surfaces before building**, after the previous item was
  built and reverted for duplicating something that already shipped. `scheduleLookahead` lists the
  window grouped by week; the pull-plan board's `made_ready` is a manual trade commitment. Neither
  computes preconditions from predecessors and submittal state, which is the whole of this.
- Found by v0.3.1044's fix to `test_route_reachability` — the gate that had been counting a route
  named in a doc comment as a route called. The first thing it surfaced was wired the same day.

## v0.3.1044 (2026-08-20) — the reachability gate counted a route NAMED in a comment as a route CALLED

### Fixed

- **`test_route_reachability` matched against the raw web source**, comments included, so a route
  whose name appeared in a doc comment read as reachable. **Six were hidden this way** —
  `/cost/datasets`, `/pipeline/funnel`, `/drawings/sheet.dxf`, `/entitlements/conditions`,
  `/schedule/eot/sourced`, `/schedule/make-ready`. `sheet.dxf`'s only appearance in the entire client
  is inside `/** … the query parameters `sheet.svg` / `sheet.pdf` / `sheet.dxf` declare. */`.
  **The gate's central assertion could be satisfied by writing the route's name in a sentence** —
  which is the failure it exists to prevent, one level up.
- **The stripper is deliberately conservative, and the greedy version was measured and rejected.**
  A plain `/\*.*?\*/` corrupts this source: there are **3,500** `/*` occurrences inside quoted glob
  strings (`"src/**/*.ts"`), each opening a false comment that runs to the next `*/` and eats real
  call sites between. Over-stripping is not the safe direction — it invents unreachable routes, i.e.
  work for someone. Block comments are removed only where they *start a line*; trailing `// …` is
  left alone, because removing it needs string-awareness and a naive pass truncates `https://`
  inside a literal. The gate's own regression check ("the siblings that motivated this gate are
  STILL reachable") confirms nothing real was stripped.
- **The allowlist could rot indefinitely.** "A frozen route is now called" was a bare `print` — the
  run stayed green. Its sibling `test_reachable.py` states the principle this file lacked: *"a
  KNOWN_UNREACHABLE that becomes reachable ALSO fails — so the list cannot quietly rot into a
  fiction."* It is now a real check. Both directions mutation-verified.

### Note

- The five newly-visible routes are **frozen, not wired** — the list's own contract is that it
  records "this was looked at", never "this is safe". Two deserve attention:
  `/entitlements/conditions` is R22-ENTITLEMENT's own surface, and `/schedule/make-ready` is the
  Last Planner constraint list.

## v0.3.1043 (2026-08-20) — R39-DECOMP-VIEWER ⑬: federation leaves app.ts

### Changed

- **`viewer/app.ts` 3,032 → 2,944** — the "Data · Models (federation)" group (federated-model list
  and the 3D version compare that overlays two published versions) moves to
  `viewer/tools/federationSection.ts`. `app.ts` is now **5,160 → 2,944 across thirteen slices, a 43%
  cut**; the ratchet in `test_file_sizes.py` went down with it, never reset.

### Note

- **⑫ said "the renderer-free seam ends at ⑫", and that was true of the group it described and too
  broad as written.** The annotation group really is renderer-coupled — it mutates the live scene and
  *writes* to `let` captures. The federation group is not: measured **zero** `viewer.world` / `THREE`
  / `screenToGround` touches across 95 lines, reaching 3D only through `layerMgr`, a live object
  slices ⑨–⑫ already hand over whole. Measuring each candidate group rather than trusting the summary
  sentence is what found it.
- **`layerMgr` is imported as `LayerManager`, not guessed.** ⑩ recorded the one dep whose type was
  guessed — `{ rebuild(): void }` — which compiled until a call site reached `isolateGuids`.
- The module was written **imported by nothing** first, so `tsc` enumerated its nine dependencies in
  one pass. That caught a collision a hand list would not: the block holds a local `let d` (the
  version diff) which the deps parameter `d` shadowed, so `d.api` silently read the undefined local.
  The local is now `diff`.

## v0.3.1042 (2026-08-20) — a resubmittal now shows the review that asked for it

### Fixed

- **R22-ENTITLEMENT ④, comment round-tripping.** `revise()` writes a **new record with a new id**,
  and comments live in `record_comments` keyed by `record_id` — so the reviewer who returned
  SUB-001 *"Revise & Resubmit — anchor spacing does not match detail 5/A-501"* opened SUB-001.1 and
  saw **an empty comment list**. The one thing needed to judge whether the resubmittal addressed
  anything was the thing the revision dropped. Measured before the fix: 2 comments on the source,
  **0** on the revision.
- **Not a submittal problem — fifteen modules are `revisable`**, so a reissued RFI lost the
  discussion that caused the reissue in exactly the same way. The fix is in `get_record`, so every
  one of them gains it.
- The thread now walks the `data.revises` chain (bounded, cycle-guarded — that JSON is
  caller-writable) and reads oldest-first across revisions.

### Note

- **Inherited comments are labelled, never merged flat.** A comment written against rev 0 is
  evidence about rev 0; presenting it as though it were written about the revision in hand would be
  a confident wrong answer — worse than the omission, because it reads as current. `inherited: true`
  and `on_ref` say which revision each came from, and a comment made *on* the current revision
  carries neither. A record with no revision history is byte-identical to before.

## v0.3.1041 (2026-08-20) — a module can be reachable and its whole reason for existing still be unreachable

### Fixed

- **A PMXML export with baselines imported the first project and dropped the rest in silence.**
  P6 XML carries baselines as additional `<Project>` elements — the reason the format is worth
  having, since XER cannot carry them at all. `schedule_import` called `read_p6xml`, which returns
  **one** project. `read_p6xml_all`, whose own docstring says it *"is the entry point that makes
  P6 XML worth having"*, had **zero callers**. Measured on a two-project document: `activities: 2`,
  and no mention of the baseline anywhere in the report.
- `report.projects` now lists every project found; importing one and not the others is logged as a
  `PMXML_MULTI_PROJECT` **error** — data was dropped, which is not a coercion — naming what was left
  out. `project_id` on `POST /projects/{pid}/schedule/import-xer` loads a chosen project, so a
  baseline is loadable at all. A single-project export is unchanged and raises nothing.

### Note

- **`test_vendor_reachable` was green throughout, and correctly so.** `p6xml` *is* imported, so it
  counts among 29/29 reachable. Import-reachability is a real property and it is not usefulness:
  the module was reached, and the one function that justifies the module was not. R46's own framing
  said this — *"faithfulness and usefulness are different claims about a vendor drop"* — and the same
  split applies one level down, to functions inside a module a gate already calls reached.

## v0.3.1040 (2026-08-20) — trimesh 5, and the section coverage that makes the bump checkable

### Changed

- **trimesh `>=4.12.2` → `>=5.0.0`** (#281), with `requirements.lock` recompiled in
  `python:3.12-slim`: `trimesh` 4.12.2 → 5.0.0 and **nothing else moved**.
- `services/data/requirements.txt` had recorded the condition for lifting its deliberate hold —
  *"regenerating the lock AND validating trimesh 5 against the paths below"* — because trimesh
  drives mesh booleans (with manifold3d) and 2D section cuts. Both halves are here.

### Added

- **`test_section_geometry_kinds.py`** — the validation half. `test_sections` asserts an
  auto-centred cut draws geometry: one cut, one model, one wall. That catches a *total* failure of
  `mesh.section` and nothing weaker. The dangerous regression is **partial** — still fine for
  extruded boxes, broken for a swept profile or an inner loop — and it prints as a sheet that
  composes perfectly with part of the building missing.
  Five shape kinds (wall, slab, round column, annulus, swept L) are now cut and checked for the
  **size the shape actually is**, not merely for presence; the annulus must keep **both** loops,
  since losing the inner one silently draws a solid pipe; a clear plane must still return `None`
  rather than an empty-but-truthy section, which is what R43-PLAN-EMPTY-AT-CUT relies on to tell
  "the cut missed" from "the storey is empty"; and all five go through the real plan-drawing path.

### Note

- Dependabot raised this same floor once before (#229) and every check went green, because nothing
  then compared that file against the lock — the image kept shipping 4.12.2 while the line claimed
  5.0.0 was required. `test_lock_satisfies_requirements` reads it now, which is why #281 could not
  merge as it stood.

## v0.3.1039 (2026-08-20) — `/precon` leaves client.ts

SCALE-SEAM ㉒. Six preconstruction methods (estimate continuity, snapshot, decisions,
assumptions, VE, alignment) moved to `apps/web/src/api/precon.ts`. One contiguous run.
`client.ts` 3,170 → 3,128.

## v0.3.1038 (2026-08-20) — `/ai` leaves client.ts

SCALE-SEAM ㉑. Six AI methods (risk summary, ask, RFI triage/draft, estimate,
author) moved to `apps/web/src/api/ai.ts`. Five regions. `aiReadiness`
(`/ai-readiness`) stays. Increment class widened ①–㉕.
`client.ts` 3,205 → 3,170.
## v0.3.1036 (2026-08-20) — boto3 and numpy floors raised, and the lock recompiled to match

### Changed

- **boto3 `>=1.34` → `>=1.43.68`** (#288) and **numpy `>=2.5.1` → `>=2.5.2`** (#277), with
  `requirements.lock` recompiled in `python:3.12-slim` — the prod base image — via `lockfile.yml`.
  Resolved: `boto3`/`botocore` 1.43.46 → 1.43.75, `numpy` 2.5.1 → 2.5.2, **and nothing else moved**,
  which is the point of compiling without `--upgrade`.
- **Neither PR could merge as it stood.** Both raise a floor *above* what the lock pins, and
  `test_lock_satisfies_requirements` checks the lock against `requirements.in` **and**
  `services/data/requirements.txt`. Verified rather than assumed: run against the old lock the gate
  exits 1. A floor raise and a lock recompile are one change, not two.
- **numpy was raised in `requirements.in` too**, not only where Dependabot proposed it.
  `pip-compile`'s sole input is `requirements.in`, so a floor raised only in the data service cannot
  move the resolution — the lock would have stayed at 2.5.1 and the gate would still have failed.

## v0.3.1035 (2026-08-20) — honest empty canvas, Place ticks, element cards

The upgrade audit's remaining code slice, not another library.

- **Empty canvas.** A 404 / empty / unreadable `.frag` still fails open, and now names why in the
  status bar (`apps/web/src/viewer/loadProjectModel.ts`) instead of leaving the last success sitting
  there. Gated by `apps/web/src/viewer/loadProjectModel.test.ts`.
- **Place pipeline.** "⊕ Place selected family" reports publish states the same way Republish already
  did (`apps/web/src/viewer/tools/authoringSection.ts`).
- **UX-DUP-DESTINATIONS.** Analyse rail labels are Model checks / Read the model / ISO 19650
  scorecard. Bars and Design tiles read the catalog.
- **R24-ELEMENT-CARD ②.** RFI, estimate, owner invoice (pay app) and asset/COBie rows mount the
  existing card. `register.ts` dropped 33 lines onto `apps/web/src/portal/register/elementTies.ts`
  to stay under its pin. Seeding the asset register now keeps `element_guids`.

- **The three named Analyse destinations did NOT land as rail siblings.** This branch split
  `Analyse` into `Model checks` / `Read the model` / `ISO 19650 scorecard` on the rail;
  v0.3.994 finished the same UX-DUP-DESTINATIONS item the other way — one `Analyse` home with
  the three reachable inside it — and that is the newer decision, with a test asserting it.
  The naming half was already on main; only the placement was superseded. The branch's test
  is kept, retargeted from the rail stage to `ALL_DESTS`, so the guard against synonym labels
  survives without contradicting the newer layout.

## v0.3.1034 (2026-08-20) — `/topics` leaves client.ts

SCALE-SEAM ⑳. Seven BCF methods (create, viewpoints, board, timeline, comments)
moved to `apps/web/src/api/topics.ts`. Three regions. `pins()` stays (`/pins`).
`client.ts` 3,243 → 3,205.

## v0.3.1033 (2026-08-20) — the level list says which cut height to use

### Added

- **`GET /projects/{pid}/drawings/storeys` carries a `cut_height` per level.** Every plan in the
  product was requested at a flat `cut_height=1.2` regardless of storey — right for a normal floor,
  and the reason a roof datum printed blank. The level list is where a caller picks what to draw, so
  it is where the answer belongs. Additive: `name` / `elevation` / `guid` are unchanged, and
  `cut_default_spans` / `cut_best_spans` ride alongside so the suggestion can be judged rather than
  trusted.
- The suggestion is **a value to pass back, never an override applied behind the caller's back** —
  the titleblock prints the elevation it cut at, and a silently different plane would make that
  printed number a lie.

### Fixed

- **The first version of this maximised element count, which is the wrong objective.** On
  `basichouse.ifc` "Floor 0" it proposed **0.400 m** to raise the count from 84 to 106 — more
  linework, cut below every door and window, which is not a floor plan. A plan cuts near 1.2 m
  because that is where openings are; the convention earns its default. The override now fires on
  exactly the condition the sheet's banner fires on (`ratio < 0.5` with `best >= 4`), so a level
  offered a different height is precisely a level that would otherwise have been warned about —
  one rule, not two that can drift apart. A storey with almost nothing at *any* height keeps the
  default and its honest "NO GEOMETRY" banner rather than being handed a fake better plane.

## v0.3.1032 (2026-08-20) — a ratchet measured on a branch describes a tree that never shipped

### Fixed

- **Main was red on the extraction ratchet**: `client.ts=3305 > 3304`. Each of the five seam
  branches (#316–#320) measured `client.ts` on a tree containing only *its own* extraction, so
  every ceiling was correct on its branch and none described the merged result — which carries six
  mixin imports, not one. Corrected to 3,305.
- **This is not a raised bound.** The file went **3,683 → 3,305** across the chain, and the gate
  still fails on any growth from here — mutation-checked by appending one line. The lesson is
  narrower and worth keeping: *a ratchet value computed on a feature branch is a measurement of a
  tree that never shipped*, and in a stacked chain every one of them is stale by construction.

## v0.3.1031 (2026-08-20) — pdf.js pinned exactly; the flag that was doing nothing removed

### Fixed

- **`pdfjs-dist` pinned to exactly `6.2.108`**, the release that fixes CVE-2026-16633 (JavaScript
  embedded in a PDF executing in the hosting origin). A range would let a future install float off
  the patched version, and the pin is the only thing standing between this app and that CVE.

### Changed

- **Removed `enableScripting: false`, and the test that vouched for it.** The incoming change added
  that option at every `getDocument` call site. It is a pdf.js **viewer** option, not a
  `getDocument` one: it appears nowhere in `pdfjs-dist`'s `DocumentInitParameters`, the vendored
  fork read it nowhere, and it did not typecheck against the real types — the compiler is how it
  surfaced. It was a security control consumed by no code, with a green test reporting "PDF
  scripting is disabled". **A gate vouching for a no-op is worse than no gate**, because it answers
  the question and the next auditor moves on.
- `pdfjsScripting.test.ts` now asserts the two things that are actually true: the version spec is an
  exact pin at or above 6.2.108, and nothing in `src/` imports pdf.js's viewer or
  `PDFScriptingManager` — which is *why* document JavaScript has nowhere to run. Both
  mutation-checked: floating the pin to `^6.2.108` fails, and adding a `pdfjs-dist/web/` import
  fails.
- Lane D (`Geometry & drawings`) now owns `apps/web/src/drawings/`, which no lane claimed; the new
  test file pushed the unowned-file ratchet from 48 to 49 and the fix it asks for is a lane row,
  not a higher number.

## v0.3.1030 (2026-08-19) — CC0 is permitted, and the written rule catches up

The operator confirmed adding **CC0-1.0** to the permitted licence list.

The Python classifier already accepted it, from 2026-08-10: `test_licence_allowlist.py` pins
`CC0-1.0` / `CC0 1.0 Universal` as permitted, next to Boost `BSL-1.0` and explicitly not `BUSL`.
The families shelf already shipped CC0 content. What had not followed was the *written*
non-negotiable (`docs/roadmap-directions.md` still said "MIT / BSD / Apache only") and the
roadmap decision bullet that still asked for a call.

This release closes that bullet, names CC0 (and ISC) in the directions, classifies a CC0
LICENSE *title* in the npm gate so it is not an unclassified text, and records the same in
the vendorable-core note.

**Not a new dependency. Not a licence we did not already ship.** The defect was three
statements about one fact, two of them stale.

- The permit-list comment in `licencePolicy.mjs` read "Forbidden outright: MIT / BSD /
  Apache / ISC / CC0" — the allowed licences under the banned heading, the exact inverse of
  the rule enforced beside it. Introduced by this same widening edit; corrected here.

## v0.3.1029 (2026-08-20) — an opening in the first half of any wall was "outside its host"

### Fixed

- **The opening-extent bound was wrong at both ends.** `add_wall` places a wall at the midpoint of
  start→end and sweeps a *centred* profile, so a valid opening sits in `[-length/2, +length/2]`.
  The check compared against `[0, length]`: every opening in the first half of any wall was
  reported as outside its host, and a genuinely-overhanging opening on the far side was missed by
  a full half-length. It hid because omitting `position` centres an opening at local x = 0, which
  passes either way — only explicitly-placed openings expose it. The refusal message now names the
  centre-relative offset and the valid range, so it says which frame it is talking about.
- **Element lookup by GlobalId is a hash lookup, not a scan.** `by_guid` replaces
  `next(e for e in model.by_type("IfcElement") if e.GlobalId == guid)`. Every bulk record recipe —
  `set_phase`, `verify_asbuilt`, `set_element_pset`, `classify`, `set_lod`, `attach_document` and
  the rest — loops a guid list calling it once per guid, so stamping N elements in a model of N
  was O(N²). Measured on a 1,153-product model: **27.6 s → 2.4 s, 11.5×**, with an identical IFC
  class histogram and property-set signature multiset. The `IfcElement` narrowing is kept on
  purpose — a stamp aimed at an element must not land on a storey, a space, or the project.

### Changed

- Family shelf refreshed to massing-families v0.1.5 *(#290, folded in — #291 contains it)*.
- `test_element_lookup` registered in `run_tests.py`; the manifest guard had refused the PR
  precisely because a test file on disk that the runner never calls is not a test.

## v0.3.1028 (2026-08-20) — the other five headers the same trap was eating

### Fixed

- Preserve cross-origin isolation headers for module workers in Nginx deployments so IFC geometry
  loading does not stall. *(#311, john-rogers — the first outside contribution.)*
- **And the rest of what that trap was eating.** nginx inherits `add_header` from the enclosing
  scope only while the current scope declares none, so a location with its own `Cache-Control`
  silently drops **all seven** server-level security headers. Three locations do this —
  `~* \.mjs$`, `/assets/` and `/wasm/` — which meant `X-Content-Type-Options: nosniff` was absent
  from every hashed bundle, every WASM binary and every module worker the app serves. #311 fixed
  the two headers that caused the reported stall on one of the three; the full set now appears in
  all three.

### Changed

- **`nginx.test.ts` derives the population instead of counting scopes.** The incoming test encoded
  the partial state as the specification — `Cross-Origin-*` required in three scopes, everything
  else in two — which passes forever with `nosniff` still missing. It now finds every location
  block that declares an `add_header` and requires the whole set in each, so a *fourth* such
  location fails the day it is added rather than the day someone re-audits. Mutation-checked:
  deleting `nosniff` from `/wasm/` alone fails with a message naming that location.



## v0.3.1027 (2026-08-20) — a sanitiser narrower than its input type

### Fixed

- **`js/incomplete-sanitization` (HIGH)**, the one CodeQL alert the merged chain introduced.
  `charts.test.ts` escaped a status colour for a regex with `[.#]` — wrong in both directions:
  `#` is not a metacharacter and never needed escaping, while `(`, `|`, `*` and `\` were absent.
  Correct for today's `#rrggbb` inputs, and the day a token becomes `rgb(1,2,3)` those parens
  compile as a **group**, so the "declared once" count silently stops meaning what it says.
  Not exploitable — test-only, constant input — and fixed anyway, because a sanitiser narrower
  than its input *type* is a latent wrong answer rather than a style nit.

## v0.3.1026 (2026-08-20) — a plan that grazes the storey now says so

### Fixed

- **Blank floor plans printed as finished drawings.** `samples/basichouse.ifc` storey "Floor 1"
  cuts at 3.600 m, passes through **2** of the 16 elements standing on that storey, and composed a
  full sheet around them — titleblock, general notes, graphic scale, north arrow, "CUT PLANE
  3.60 m AFF" — with no building on it and nothing said. The v0.3.913 guard asked `if not polys`,
  a test for *exactly* zero, and the failure mode is *nearly* zero: two loops are truthy.
  `cut_plane_quality` now measures the chosen plane against the best one available on the storey,
  so a fraction decides rather than a boolean, and the sheet names the height that would work
  ("at 2.500 m it would pass through 6 — set the cut height to 0.100 m").
  Still **not** a silent re-cut: the titleblock prints the cut elevation, so moving the plane
  quietly would make that printed number a lie. The counts are also published as
  `data-plan-cut-spans` / `-best` / `-best-z`, measured once and shared, so the data and the
  banner cannot drift apart.
- `test_plan_cut_quality.py` verifies the suggested height *actually improves the drawing* rather
  than merely being printed, and that a healthy plan is left alone.

### Changed

- **SCALE-SEAM ⑭** — the five drawing-markup methods leave `client.ts` for `api/markup.ts` as
  `withMarkup`. Forced rather than chosen: teaching `addDrawingMarkup` to carry the GlobalId put
  the file at 3,606 against a 3,602 ratchet, which is that pin working as its own comment says it
  should — the friction buys a cluster out of the file instead of buying the pin a higher number.
  3,606 → 3,579.

## v0.3.1024 (2026-08-20) — `/mep` leaves client.ts

SCALE-SEAM ⑲. Seven MEP methods (summary, connectivity, sizing, sprinkler, fittings,
class rollup, model-extract) moved to `apps/web/src/api/mep.ts`. Four regions.
`connectMep` / `addMepFitting` stay on `editIfc`. `client.ts` 3,304 → 3,243.

## v0.3.1023 (2026-08-20) — `/documents` leaves client.ts

SCALE-SEAM ⑱. Nine document-control methods (tree, folder, health, upload/move/delete,
download) moved to `apps/web/src/api/documents.ts`. One contiguous run.
`client.ts` 3,353 → 3,304.

## v0.3.1022 (2026-08-20) — `/models` leaves client.ts

SCALE-SEAM ⑰. Nine health/QA/georef/federation methods moved to
`apps/web/src/api/models.ts` (`withModels`; `model.ts` remains `/model`).
Four regions. `client.ts` 3,412 → 3,353.

## v0.3.1021 (2026-08-20) — `/elements` leaves client.ts

SCALE-SEAM ⑯. Eleven inspector/list/colour/QA/citation/cost methods moved to
`apps/web/src/api/elements.ts`. Five regions. `elements5dMap` (`/5d/heatmap`) and
the job tray stay. `client.ts` 3,482 → 3,412.

## v0.3.1020 (2026-08-20) — `/drawings` leaves client.ts

SCALE-SEAM ⑮. Eleven sheet methods (revise, schedules, storeys, sync-status, markup + stream)
moved to `apps/web/src/api/drawingSheets.ts`. Six regions. `client.ts` 3,538 → 3,482.

## v0.3.1019 (2026-08-20) — `/drawing-set` leaves client.ts

SCALE-SEAM ⑭. Eleven drawing-set methods (register, issue, issuance matrix, transmittals)
moved to `apps/web/src/api/drawingSet.ts`. They sat in three runs with `/preflight` and
`/pdf` between them. `client.ts` 3,602 → 3,538.

## v0.3.1019 (2026-08-20) — the four checks that stood between 19 branches and main

Integration pass over the v0.3.988–1018 stack. Every item here is a gate that was correctly
red; none of them were silenced.

### Fixed

- **`report_package` was a job kind classified nowhere.** `register_kind` added it without an
  entry in `_KIND_MIN_ROLE` or `EDITOR_OK_KINDS`, which is the privilege-side-door shape the
  dispatcher gate exists to catch. Classified as editor-sufficient with its reason: the queue
  requires `editor` while `GET /projects/{pid}/reports/{report}.pdf` serves the same content at
  `viewer`, so the queue is stricter than the front door, and it parks an artifact rather than
  writing project state.
- **`addDrawingMarkup` lost its only caller.** `postSheetPin` had re-issued the POST by hand to
  add `data.guid`. The client method now carries the guid and `postSheetPin` delegates, so the
  endpoint and its body are constructed in one place. Its test drives the real client and still
  asserts the encoded body, so the claim now spans seam → client → wire.
- **The web build was broken before it began.** `vite.config.ts` resolved `three/package.json`,
  which `three` does not list in its exports map — copied from `vitest.config.ts`, where the same
  line works only because `pdfjs-dist` happens to expose its manifest. The hoisted `node_modules`
  is now derived from the package entry path, which does not ask a dependency to publish its
  manifest. CI never reached this: the test step failed first.
- **A negative test with an expiry date.** `test_engine_routes` used `page=A0` as its unknown
  page size; this release widened `_PAGES` to nine ARCH/ISO sizes and A0 became valid, so the
  request reached the model open and returned 409. The invalid value is now derived from `_PAGES`.
- **`docs/status.html` was 90 releases behind**, and the gate measuring that could no longer
  measure: its `/v0\.3\.(\d{3})/` read `v0.3.1018` as **101**, smaller than the 928 already on the
  page. Past v0.3.999 it reported a lag no amount of refreshing could close. Both it and the
  CHANGELOG gate now read `\d{3,}`, and the page carries the v0.3.988–1018 wave.
## v0.3.1018 (2026-08-20) — `/sync` leaves client.ts

SCALE-SEAM ⑬. Seven Procore pull/push + auto-sync-schedule methods moved to
`apps/web/src/api/sync.ts` as `withSync` (`withSchedule` is already CPM).
`client.ts` 3,629 → 3,602.

## v0.3.1017 (2026-08-20) — a worktree build uses the pinned Vite

BUILD-WORKTREE-CHUNKS closed. `npm run build` / `dev` go through `run-vite.mjs`, which
execs the nested Vite 8 pin (found in the main clone via `git-common-dir` when the
checkout is a worktree). Bare `vite` was resolving the workspace-root Vite 6 and
folding three.js into the shell at exit 0. `vite.config.ts` now allows that hoisted
`node_modules` the same way the vitest config already did.

## v0.3.1016 (2026-08-20) — `/connections` leaves client.ts

SCALE-SEAM ⑫. Eleven `/connections` methods moved to `apps/web/src/api/connections.ts`.
`client.ts` 3,672 → 3,629. The increment marker vocabulary in `roadmapLanes.test.ts` now
runs ①–⑳ so the twelfth does not silently parse as the bare series name.

## v0.3.1015 (2026-08-20) — assemble the package, don't click it one by one

R24-REPORTS-BY-MOMENT ②. Each package has **Assemble**: a `report_package` job builds the
named reports into one PDF and parks it in the job tray. Unknown ids fail the job rather than
quietly shortening the pack. Email-on-a-date is still open (needs a recipient and SMTP).

## v0.3.1014 (2026-08-20) — markup the plan you are looking at

R38-SHEET-MARKUP ③ closed. Every generated sheet (plan / elevation / section) has
**🖊 PDF markup**. Composed sheets still use `sheet.pdf`; the others wrap the live SVG
in pdf-lib (`apps/web/src/ui/svgPdf.ts`) so the takeoff tools open on the room's own
drawings.

## v0.3.1013 (2026-08-20) — a pin on a wall raises an RFI on that wall

R38-SHEET-MARKUP ③ ②. Promoting a drawing pin copies `data.guid` onto
`Topic.element_guids`, so the RFI is the same GlobalId the sheet and the 3D view
already share. A pin on empty paper still raises a coordinate-only RFI.

## v0.3.1012 (2026-08-20) — a pin on a wall is that wall

R38-SHEET-MARKUP ③ ①. Generated-sheet markup in the Drawings room now reads `data-guid` from the
SVG (same hit-twins as the plan pane). A pin dropped on linework stores the GlobalId and
reselects it in 3D. Empty paper is still a coordinate pin. PDF markup on generated
plans/elevations (not only composed `sheet.pdf`) is still open.

## v0.3.1011 (2026-08-20) — box one symbol on the sheet, get the rest

R23-SYMBOL-COUNT ②. Takeoff **⌘ Match** boxes one instance on the pdf.js-rendered page;
`countOnRgba` in `apps/web/src/ui/symbolCount.ts` downsamples, NCC-matches, and places
existing count marks. A too-small or too-large box is a sentence, never a guessed quantity.

## v0.3.1010 (2026-08-19) — count a symbol by matching it, not guessing

R23-SYMBOL-COUNT ①. Normalised cross-correlation plus non-maximum suppression in
`apps/web/src/ui/symbolCount.ts`. Zero new dependencies. The takeoff-worker wiring is still open.

## v0.3.1009 (2026-08-19) — this week's Gantt, not a month of bars

UX-GANTT. The Schedule room already had a month-scale SVG. It now opens with a Mon–Sun week:
day columns, inline %, crew size when present, and trade colour from `SERIES_PALETTE` (not
traffic lights). Empty is a sentence. The server Gantt is still below.

## v0.3.1008 (2026-08-19) — field mode hides the seven rooms

R24-FIELD-MODE ④. With field mode on, `#workspaces` (the room tablist) is `display:none`, so
it is also out of the tab order. Capture stays the landing (③); Office restores the spine.
Replacing the portal home itself is still Lane A.

## v0.3.1007 (2026-08-19) — Tab to the room's job, then land

R39-A11Y-JOURNEYS ②. Each of the seven rooms has one keyboard primary: Design is its tab; the
other six put `[data-room-primary]` on the landing (Open RFIs / budget lines / activities / the
next Deal gate / the first work-queue row / Open work orders). Tests Tab to it, operate it, and
assert focus did not fall on `document.body`.

## v0.3.1006 (2026-08-19) — field mode lands on capture when a project is open

R24-FIELD-MODE ③. If field mode is on and a project is selected, the capture sheet opens
(on load and when you flip the Field toggle). No project → no sheet (that would only toast).
The seven-room spine is unchanged; this is not a second portal home.

## v0.3.1005 (2026-08-19) — a citation boxes the passage, not a new browser tab

R31-CITE-HIGHLIGHT. Opening a source used `window.open` on a blob URL, so `citeLocate` had no
page to draw on. The citation now opens the in-app takeoff viewer; `PdfDocument.textItems` is
the `PageWords` supplier. A scan or empty text layer is a sentence, never a guessed box.

## v0.3.1004 (2026-08-19) — the field FAB no longer sits on the queue

R24-FIELD-MODE ②. Slice ①'s 56 px rules lost to the FAB's inline `52×52` / `bottom:18px`, so the
sync strip was under the camera button. Field-mode CSS now wins; the FAB sits above the strip.
The strip announces queue changes (`aria-live="polite"`). Capture-first home is still open.

## v0.3.1003 (2026-08-19) — one mono face, including paste-from-spreadsheet

R24-MONO-DATA. The last hand-rolled `ui-monospace` stack was the register paste textarea, left
when the renderer still lived in a Lane A file. It now reads `var(--mono)`. The ratchet
allowance is 0.

## v0.3.1002 (2026-08-19) — a series is not a traffic light

R24-CHARTS-GRAMMAR ③ closes the item. `chartColor` is a seven-slot categorical ramp that does not
include passing-green, warn-gold, failing-red, or `--accent`. Signed charts and the CPI–SPI
quadrant still use those status hues. A mix donut that means on-track / at-risk must pass the
hues in.

## v0.3.1001 (2026-08-19) — field mode: 56 px, the queue, and a mic that can be missing

R24-FIELD-MODE ①. A stored mode (`aec-field-mode`, `?field=1`), not a breakpoint: 56 px targets
and outdoor contrast on the capture FAB / sheet / strip only. The offline queue is always
visible in field mode (empty and offline are sentences). Dictation on the note when the
browser has SpeechRecognition; no engine means no mic, never a dead button. Capture-first
home is still open. Register density is a separate control.

## v0.3.1000 (2026-08-19) — the element card opens wherever a register names a GUID

R24-ELEMENT-CARD ② reach. Opening an RFI, estimate, SOV (G703 / pay-app line), or asset-register
(COBie Component) record that is tied to model elements now mounts the same lifecycle card as the
viewer and the cost-trace lookup. There is no `pay_app` module and no COBie worksheet UI — those
two named surfaces are SOV and the asset register. A failed lifecycle is the identity line, never
a six-blank strip. The register file shrank (`tiedElements.ts`); the pin is 2,516.

## v0.3.999 (2026-08-19) — Cost, Planning, and Operate open on three answers

R36-ROOM-BRIEFS for the remaining portal homes. Cost (`__budget__`) opens vs GMP, unpriced
exposure, and buyout. Planning (`__benchmarks__`) opens on the RFI clock, the submittal clock,
and own-history cost medians. Operate (`__operations__`) opens on overdue work orders, PM
compliance, and FCI. No GMP / no history / `pm_compliance_pct: null` / no FCA elements are
sentences, never 0%. Shared card chrome is `roomBriefChrome.ts`. Design stays the viewer
(`ROOM_HOME.design` is null).

## v0.3.998 (2026-08-19) — Deal opens on the developer's three answers

The Deal room (`__portfolio__`) used to open on the book-wide table. It now opens with returns vs
the underwriting band, open diligence, and the next developer protocol gate (`dealBrief.ts`). A
failed engine is a reason, never 0.0% IRR or "0 flagged". Schedule (995) and Work remain the
other landed briefs; Cost / Planning / Operate / Design are still open on R36.

## v0.3.997 (2026-08-19) — CAM statement PDF is a POST

Downloading a tenant CAM statement used to be a cookie-bearing GET that `Session.commit()`'d an
audit row. SameSite=Lax sends the session cookie on a top-level GET. The route is POST; the
Finance UI fetches the blob and saves it. OAuth callback remains the only GET+commit.

## v0.3.996 (2026-08-19) — Field / Comfortable / Compact on registers

Density is three named row heights (56 / 36 / 28 px), cycled from the portal home, and applied to
`.portal-table` so the 8-hour register is not stuck at dashboard-only compact. Numeric cells use
tabular figures. Catalog star and module buttons show a focus ring outside the control
(`outline-offset: 2px`), so keyboard focus is visible.

## v0.3.995 (2026-08-19) — Schedule opens on the superintendent's three answers

The Schedule room used to open on import/export, then a wall of tools. It now opens with today's
lookahead, blockers, and yesterday's variance (`scheduleBrief.ts`), then the rest of the board.
The three engines already existed. A failed fetch is a reason, never a plausible zero. Work remains
the template; Deal and the other rooms are still open on R36-ROOM-BRIEFS.

## v0.3.994 (2026-08-19) — one Analyse home, three named tasks

Design's rail no longer lists Model Health, Model Analysis and BIM KPIs as siblings. One **Analyse**
destination opens a home that names the question each already-built panel answers. The three dests
still render (readiness hops unchanged). Not a fourth scorecard.

## v0.3.993 (2026-08-19) — pick the sheet paper; 24×18 is ARCH C

The Drawings rail has a paper picker. Catalog is US ARCH C/D/B/A plus ISO A0–A4. **24×18 in is
ARCH C**, not an ISO A size (A2 is 16.5×23.4). ARCH D is the usual full-size US construction set
(36×24); half-size of D is ARCH B (18×12); the next step down is ARCH A (12×9), often called
quarter-size of D. Default is ARCH C. 11×17 is not in the list — it is a copier size, not half of
24×36. An unknown `page` is refused (422), never substituted. `compose()` with no `page` is still
A3 so existing API links do not change paper.

## v0.3.992 (2026-08-19) — Issue sheet prints as ISO A1

The Drawings rail's Issue / Sheet PDF buttons labelled the sheet A-101 and the hover said ARCH-D,
while the request omitted `page` so `compose()` silently used **A3**. The paper-space editor already
defaulted to A1. The rail now sends `page=A1`. ARCH-D (24×36 in) is a different standard and stays
a product call, not a silent default. `compose()` with no `page` is still A3.

## v0.3.991 (2026-08-19) — Pulse is one GET, pills follow the persona, a 500 is not a blank

Home Pulse no longer fans seven client GETs and maps the wrong field names (`score` vs
`overall_score`, a `variance_pct` the cost summary never returned). `GET /projects/{id}/pulse`
returns `PulseInput` from `project_pulse.py`; each engine still fail-opens on its own. The
route does **not** POST a renovation programme with an invented body.

Persona-weighted pill **order** is now the server `keys` list (engineer on Design: design →
regulatory → place). A brief that 500s shows "Readiness unavailable" instead of a blank
strip that reads as "nothing is next".

## v0.3.990 (2026-08-19) — Starlette 1.6.0, the FileResponse Range floor

`requirements.lock` pinned Starlette 1.3.1. 1.5.1/1.6.0 fix Range handling on `FileResponse` (we
stream source IFC that way) and add `max_body_size` on routes. FastAPI 0.141.1 already allowed
`starlette>=0.46.0`; the floor is now explicit in `requirements.in`. No other lock moves. Compiled
on Python 3.12.

## v0.3.989 (2026-08-19) — the home strip's scope is a server fact, not a client filter

The 8-step protocol still runs in Python. The home strip was still deciding *which* steps a
superintendent or a designer sees. That map now lives next to `_PROTOCOL` in
`master_builder_scope.py`, is applied on `GET /projects/{id}/master-builder/brief?workspace=&persona=`,
and is lockstep-tested against `readinessStrip.ts` so the two layers cannot fork. The overall
readiness percent stays on all eight steps; only the pills are scoped. Empty intersect still
falls back to the workspace set.

Bake-share directories are mode 0700 when the operator turns sharing on. GET handlers that
`Session.commit()` are a ratchet (`test_get_commits.py`): OAuth callback stays GET; the CAM
PDF download is named as the leftover. Handoff for the next session:
`docs/internal/runway-claude-2026-08-19.md`.

## v0.3.988 (2026-08-19) — the readiness brief is on every home, and bake-share stores JSON

Two leftovers from the upgrade audit, neither of which is a library swap.

**The Master Builder 8-step brief was the product's own "what do I do next" surface, and it lived
on one destination in Design.** A GC superintendent, a developer, or anyone who opened the workspace
home never saw it. v0.3.988 mounts a compact strip on every portal home (construction / design /
developer all pass through `renderHome`) and scopes the pills to that workspace, then to persona —
intersected so a superintendent browsing Design still sees Design's questions rather than an empty
strip. "Close this gap" hops to the first non-ready scoped step; "Full brief" still opens
`__masterbuilder__`. Fail-open: a brief that cannot load leaves the host empty, same rule as Pulse.
The strip sits above Pulse so the next action is above the risk numbers.

Does not replace the eight-card panel. Does not invent a second protocol. The API is still
`/projects/{id}/master-builder/brief`.

**When bake-share is on, values are JSONDisk, not pickle.** `diskcache` 5.6.3 still has no published
fix for CVE-2025-69872; the shared cache is still **off unless `AEC_BAKE_SHARE_DIR` is set**. The
geometry payload was already nested lists of arrays, so pickle was never load-bearing here.
`JSONDisk` is in the package we already pin. A row that cannot be JSON-encoded is refused rather than
pickled. `mapped-diskcache` was not added. Default deployments still never construct a Cache.
## v0.3.986 (2026-08-18) — a comment that explains a pin gets believed because it is specific

Three review findings, all of them claims that had drifted from what they described.

**A stale comment contradicted the pin it justified — and the comment was the wrong one.**
`requirements-dev.txt` pinned `DracoPy==2.0.0` under a comment reading *"2.0.0 publishes Windows
wheels ONLY"* and *"1.7.0 is the newest with manylinux wheels"*, while `test_gltf_compress.py` told
readers to install 1.7.0 and the dev venv had 1.7.0. Three sources, two stories, and nothing
comparing them.

Checked against PyPI rather than reasoned about: **2.0.0 publishes 16 manylinux wheels**, alongside
16 Windows and 15 macOS. Both comment claims are false. They were presumably true when written —
2.0.0 shipped Windows-first — and nothing re-read them after. **The pin was right and the prose was
stale, which is the reverse of the natural assumption**: a comment that explains a pin gets trusted
precisely because it is specific.

The hazard was real in the other direction too. If the comment *had* been right, Linux CI would have
had no wheel, `draco_available()` would return false, and `test_gltf_compress.py` would print SKIP
while the job stayed green — the exact silent-pass the comment was written to prevent.

**Fixed so it cannot drift again:** the test's message now *reads* the pin via `_pinned_draco()`
instead of restating it, and asserts no literal `DracoPy==x.y.z` creeps back into that file.
Mutation-checked by restoring the old literal, which fails by name.

**And a gate that flagged its own documentation was removed rather than worked around.** The first
version also asserted the comment named only the pinned version — and immediately failed on the
*corrected* comment, which cites 1.7.0 while recording what the stale claim used to say. A regex
cannot separate "the version to use" from "the version this comment is about", so that check's only
remedy is rewording the history until it goes quiet, which destroys the record. It is gone, with the
reasoning left in place.

**A release note claimed a gate covered something it does not.** The v0.3.985 entry said all four
floor bumps went to versions the lock already pins, citing
`test_lock_satisfies_requirements.py`. True for the three in `requirements.in`; **false for bandit**,
which lives in `requirements-dev.txt` — outside that gate's sources — and is not in the lock at all.
The one bump in an unchecked file was the one presented as checked. Nothing is broken (1.9.4 exists),
but a future dev-tool bump naming a yanked version would pass every local gate and fail CI at
`pip install -r requirements-dev.txt`. Corrected in place.

**And the v0.3.984 entry backticked `requirements.txt`** — the file whose non-existence the v0.3.985
entry reports as its headline finding, in the same document. `test_claude_md_gates.py` does not cover
CHANGELOG.md, so nothing failed. Diagnosing an error and leaving its live instance one screen away is
its own lesson.

## v0.3.985 (2026-08-18) — four declared floors made honest, three refused

**Four Python floor bumps applied** (dependabot #289 manifold3d, #286 fastapi, #282 shapely, #284
bandit).

**Three of them are verified; the fourth is not, and this entry originally said otherwise.** The
`requirements.in` bumps — manifold3d, fastapi, shapely — each raise a `>=` floor to a version
`requirements.lock` already pins, so nothing about what installs changes and
`test_lock_satisfies_requirements.py` confirms it: 50 floors against 110 pins.

**bandit is the exception.** It lives in `requirements-dev.txt`, which is **not** in that gate's
sources (`requirements.in` + `services/data/requirements.txt`), and bandit is not in the lock at
all — dev tools are installed unpinned by `ci.yml` and again, unconstrained, by `security.yml`. So
the one bump in an unchecked file was the one this entry presented as checked. 1.9.4 does exist and
is installed in the dev venv, so nothing is broken; the claim was the defect, not the change.

That matters beyond the wording: a future dev-tool bump naming a **yanked** version would pass every
local gate and then fail CI at `pip install -r requirements-dev.txt`. The floor is also inert where
bandit actually runs, since `security.yml` installs it without a constraint.

**The other three are refused, and the reason is worth keeping.** #277 numpy (lock pins 2.5.1),
#281 trimesh (4.12.2, and a major), #288 boto3 (1.43.46) all raise the floor **above** the lock.
Merging them would red main on that same gate — mutation-tested here by simulating #281, which fails
with the exact package, both versions and the line number. And the deeper point: **CI installs from
`services/api/requirements.lock` with `--require-hashes`, not from the sources.** So even if the gate
did not exist, merging them would produce a green CI run that tested the *old* versions. A floor
bump is a claim about what is required; only a lock regeneration changes what is *used*.

**Two things the mapping turned up, both from checking rather than assuming:**

- `services/api/requirements.txt` **does not exist**. The source is `requirements.in`, compiled to
  `requirements.lock`; a first pass looking for the `.txt` found nothing and would have concluded the
  packages were undeclared.
- **`shapely` is declared in two different files** — `services/api/requirements.in` at `>=2.0` and
  `services/data/requirements.txt` at `>=2.1.2`. Reading the wrong one makes #282 look already
  applied. The edit is line-anchored and asserts it matched exactly one line, so a floor like
  `>=2.0` cannot silently match inside `>=2.0.1`.

## v0.3.984 (2026-08-18) — the dependabot bumps were incomplete, and the lock is what CI installs

**Five npm dev-dependency upgrades, applied together and verified as one state:** eslint 10.8.0 →
10.8.1, globals 17.7 → 17.11, happy-dom 20.8.9 → 20.11.2, typescript-eslint 8.65 → 8.67, vite
8.1.5 → 8.2.1 (dependabot #278, #280, #283, #285, #287). They were applied in one commit rather than
merged one by one because all five rewrite `package-lock.json` and would have conflicted pairwise.

**Dependabot could not see the whole picture, and merging its PRs as-is would have changed less than
they claimed.** The **root** workspace declares `vite`, `eslint` and `happy-dom` too. Dependabot
only opened PRs against `apps/web`, so:

- **`eslint` would have stayed on the root's 10.8.0** — hoisted, so the apps/web bump was a *no-op
  for linting*, which is the tool the bump exists to update;
- **`vite` would have been installed twice** — the root's exact `8.1.5` against web's exact `8.2.1`,
  forcing a nested second copy. This repo already has a memory about a worktree silently building
  with a different Vite; this is the same hazard from the other direction.

Both roots are now aligned and all five resolve to **single hoisted copies** at the intended
versions, confirmed by reading `node_modules` rather than by trusting the manifest.

**There is also an `overrides` block pinning eslint repo-wide, which dependabot never touches.** The
first edit here landed on *it* instead of the devDependency — the same key exists in both sections
and a count-limited replace takes whichever comes first in the file. npm rejected it immediately
(`EOVERRIDE: Override for eslint@10.8.0 conflicts with direct dependency`), which is the good case:
a loud failure rather than a silent half-upgrade. Both entries now read 10.8.1 and are asserted equal.

**`toolchainDocs.test.ts` then caught the third thing:** `docs/engineering/web-standards.md` still
said "eslint 10.8.0". That is a governed doc whose versions are asserted against the manifest, and
its own comment records that both versions there were wrong for weeks once before. Updated.

**The seven Python PRs are a different problem, and none of them are merged here.** CI installs from
`services/api/requirements.lock` with `--require-hashes`, **not** from the sources it is compiled
from. (This entry said "requirements.txt" in backticks; there is no such file — the input is
`services/api/requirements.in`. Corrected in v0.3.986, which found the live instance of the very
error the v0.3.985 entry below diagnoses.) Those PRs
only raise `>=` floors, so:

- **#289 manifold3d, #286 fastapi, #282 shapely, #284 bandit** — the lock already pins versions that
  satisfy the new floors. Safe, and purely a matter of making `requirements.txt` honest.
- **#277 numpy, #281 trimesh, #288 boto3** — these raise the floor **above** what the lock pins
  (2.5.1, 4.12.2, 1.43.46). `test_lock_satisfies_requirements.py` already guards exactly this; it was
  mutation-tested by simulating #281 and fails with the precise message. Merging them without
  regenerating the lock would red main — **and CI would still install the old versions, so a green
  run would prove nothing about trimesh 5.** They need a lock regeneration, which is its own change.

Web: typecheck + lint clean, 1651/1651, build ✓. Backend 608/608.

## v0.3.983 (2026-08-17) — a deleted symbol in backticks still reads as a live one

Docs only. An end-of-session sweep over v0.3.978–982 found one real gap and one wrong number, both
in the R37-TRIAGE entry.

**The three functions deleted in v0.3.980 were still listed in plain backticks.** The same entry
already strikes through `verify_stepup_token` with its deletion version — the convention existed, it
just was not applied to the newer deletions. This repo's standing rule is that **backticks are
reserved for things that exist**, because a backticked name reads as a live citation whether or not
anything backs it; that rule was written for *file paths* and the gate enforces it for those, but it
holds for symbols too and nothing enforces it there. `discipline_names`, `quadrant` and
`scorecard_inputs` are now struck through with the rest.

**And the sentence summarising what was left said "eight" when the answer is nine.** Counted rather
than recalled: twelve candidates, three deleted, **nine unstruck — of which eight have a real
caller.** The ninth is `sync_property`, and it is worth naming instead of rounding away: it has no
caller at all. It is a deliberate refusal stub that raises `NotImplementedError` and names *itself*
as the place to implement the credentialed ENERGY STAR exchange, kept because deleting it would
remove the documented extension point from a module whose entire contract is "never fabricate a
score". The dead-code gate counts it as referenced only because that error string contains its name
— a limitation of the rule, now stated in the entry rather than left to be rediscovered.

An unattached number drifts, and this one had drifted within a day of being written.

## v0.3.982 (2026-08-17) — where the renderer-free seam actually stops

**R39-DECOMP-VIEWER ⑫ — envelope & free-form geometry.** Curtain wall, sloped wall top, and the raw
verts/faces mesh escape hatch → `viewer/tools/envelopeSection.ts`, 75 lines. `app.ts` 3,096 →
**3,032** — 5,160 → 3,032 across the ring, a **41% cut**.

**I corrected a claim of my own in the roadmap, and the correction is the release.** One release
earlier I wrote that the two remaining groups were renderer-free and "both extractable on the same
recipe". That was written without checking, and half of it was false.

**The annotation group is not renderer-free.** It adds and removes objects on the live
`viewer.world.scene.three`, raycasts through `screenToGround`, and — decisively — **assigns** to
`annotGuide` and `guideWired`, which are `let` in `app.ts`. Reading a mutable capture through an
accessor is cheap. *Writing* one across a seam needs a setter pair, and the module would still need a
WebGL context to test, which is the precise untestability this whole decomposition exists to escape.
So the renderer-free seam **ends at ⑫**. What is left needs a different technique — move the scene
state into the module and let it own its objects — and that is a design change, not a lift, so it
belongs in its own roadmap item rather than being forced through as slice ⑬.

**The check cost nothing, which is the point.** The module was written, left in the project imported
by nothing, and typechecked. `tsc` listed `viewer`, `screenToGround`, `annotGuide`, `guideWired` and
four more in one pass — before a line of `app.ts` had been touched and with nothing to revert. The
same procedure then confirmed the envelope group *is* clean: six missing names, three of them plain
imports.

**Two smaller things worth writing down:**

- **⑫ is two non-contiguous ranges.** The sandboxed IFC-code runner sits between the curtain wall and
  the slope/mesh pair, and it stays in `app.ts` — a code sandbox is a different concern with a
  different risk profile, and folding it in for one tidy cut would trade cohesion for convenience.
  Extraction boundaries follow meaning, not line numbers.
- **Comments move with the code they describe.** The first cut took its ranges by line number and
  dragged in the "Advanced toggle" and "sandboxed ifcopenshell" comments while leaving the slope
  tool's own comment behind — a module documenting features it did not contain. Same defect as the
  docstrings that got three functions deleted in v0.3.980, and caught the same way: by reading what
  the output actually said.

**Remaining:** ~640 lines in `buildToolsPanel`. The annotation group (~120) is the renderer-coupled
part above; the rest is the content/family library and the rail assembly itself, which is wiring —
the thing this file is *for*.

## v0.3.981 (2026-08-17) — the accessor rule meets the capture it was written for

**R39-DECOMP-VIEWER ⑨ — fabrication detail leaves `app.ts`.** 65 lines to
`viewer/tools/fabricationSection.ts`: base plate, shear tab, rebar cage, the ACI 318 cage check and
the bar bending schedule. `app.ts` 3,311 → **3,255** — 5,160 → 3,255 across nine slices, a 37% cut.

**This is the slice the accessor rule was written for.** Slice ⑦ threaded `activeStorey`; this one
threads **`selectedGuid`**, the capture the decomposition plan named first and the one with the worst
failure mode. Every tool in the group is selection-gated, so collapsing the accessor would not break
them loudly — it would make all five **permanently inert behind a polite "select an element first"**,
which is precisely the bug `qaSection.ts` shipped once, under a docstring explaining why it could not
happen. Eight reads of `d.selectedGuid()`, no local binding, and `accessorNotCollapsed.test.ts`
mutation-checked against the new file.

**`tsc` rejected three things, and each rejection was correct** — which is the argument for a recipe
whose gate is the compiler rather than a suite that never imports the file:

- a dep signature narrowing `authorAndReload` to `Promise<void>`, which would have dropped the
  `{applied, refused}` verdict and let a future caller read a **refused** edit as a successful one;
- calling the accessor twice where narrowing was needed (`if (d.selectedGuid()) … d.selectedGuid()`)
  — two calls genuinely can differ, so the compiler is asking the right question;
- returning an **array**: under `noUncheckedIndexedAccess` a destructured element is
  `T | undefined`, and these are appended straight into the rail. A named interface is the only shape
  that carries non-optional types across the seam, and names survive re-ordering where indices do not.

**R39-DECOMP-VIEWER ⑩ — MEP, fire protection and life safety.** 169 more lines to
`viewer/tools/mepSection.ts`: MEP fitting, fire-protection equipment, fire-alarm device, telecom
device, vertical riser, and the `IfcDistributionSystem` browser. `app.ts` 3,255 → **3,096** — 5,160
→ 3,096 across ten slices, a **40% cut**.

**This slice threads `lastPoint`, the last of the two named mutable captures**, and the most volatile
state on any of these seams: `selectedGuid` changes when you pick an element, `lastPoint` is
rewritten on *every click in the 3D view*, and five of the six tools place geometry at it. Each
handler reads it once, at click time, into a local — which is the point-of-use read the rule asks
for, not the build-time collapse it forbids. The distinction is the *when*, not the presence of a
local, and the gate is mutation-checked against the new file.

**It also exposed the recipe's own weak point, which is worth more than the slice.** The
free-variable list was hand-written and found **12 of 17** captures — `askText`, `layerMgr`,
`loadProjectModel`, `reloadModelPins` and `waitForPublish` were all missed. Worse: the one dep whose
*type* was guessed (`layerMgr` as `{ rebuild(): void }`) compiled fine until a call site reached for
`isolateGuids`. **Guessing a dep's type is the same error as guessing its name.**

The fix is procedural, and it is now how these slices get done: write the module first, run `tsc`
against it *unwired*, and thread exactly what the compiler reports missing. A compiler is a complete
enumerator; a hand-written list never is. Checking before the splice also keeps every error
attributable to the new file instead of mixed into `app.ts`.

`tsc` additionally rejected narrowing `loadProjectModel` to `Promise<void>` — the real return is
`Promise<boolean>`, and that boolean is whether the re-tessellation *succeeded*. Same defect class as
the `authorAndReload` narrowing caught in ⑨: a dep type that quietly drops a verdict lets a caller
read failure as success.

## v0.3.980 (2026-08-17) — a rule corrected twice had not finished being wrong

**R37-TRIAGE step 4: all 12 dead-code candidates read.** The entry already recorded this population
being corrected twice — **877 → 35 → 13**, without moving a single threshold, every reduction a fix
to *what counts as a caller*. The implication nobody drew is that a rule corrected twice has not
finished being wrong.

It had not. Reading the 12 found **eight live symbols**, missed for three distinct reasons:

- **aliased imports** — `search_filter`, `project_with_source` and `input_fields` all arrive as
  `from .x import f as _f` and are then called as `_f(...)`. Deleting them breaks module search and
  three authoring routers.
- **Python files that are not `.py`** — `excluded_import_names` is imported by name, unaliased, by
  `desktop.spec` *and* `sidecar.spec`. The scanner never opened them, because its glob was `*.py`.
  **A population derived over the wrong file set is not a conservative estimate, it is a confident
  wrong answer**, and this one sat one careless deletion away from breaking both PyInstaller builds
  with nothing in the suite going red.
- **methods reached through an instance** — `register_recipe` is the documented third-party plugin
  API, called as `api.register_recipe(...)` by `plugins/example-wall-brand/plugin.py`.

**And the list was short by two.** A corrected rule surfaced `get_meta` and `validate_dir`, which
were never candidates — so 13 was neither an upper nor a lower bound on anything.

**Three deleted, each for saying something false about itself rather than merely for being uncalled:**
`evm.quadrant` (a second implementation of the CPI–SPI points `evm.ts` already derives, under a
docstring claiming the dashboard uses it) · `cde.scorecard_inputs` (a wrapper "so the KPI engine has
one import", which `bim_kpi.py` bypasses by calling the two functions it wraps) ·
`classification.discipline_names`.

**Two more were deleted and put back, and that is the sharpest lesson in this release.**
`module_schema.validate_dir` is called by `test_module_config.py`; `model_index.get_meta` is imported
and called in `routers/standards.py`. The new gate reported both dead **because its comment-stripper
was wrong** — it applied the TypeScript block-comment pattern `/\*.*?\*/` to `.py` files, and
`test_module_config.py` contains `modules/*/module.json`, which holds a literal `/*` and a literal
`*/`. The "comment" swallowed the imports. **Over-stripping is not the safe direction**: a false death
in a dead-code gate is an instruction to delete working code. Stripping is now per-language.

The two were caught by different things, which matters. `validate_dir` was caught by the full suite.
`get_meta` was caught only by re-grepping every deleted name **without a `head` limit** — the first
check had one, `.venv` noise filled the first ten lines, and the real caller was pushed off the end.
A truncated search is a search that can report absence it never established.

**The rule is now `services/api/test_dead_code_population.py`, a ratchet at zero** — a new
unreachable public function fails at the commit that adds it. Two admissions belong with it:

- **It had to be corrected four times itself**, and the last three each survived the fix for the one
  before. (1) `ast.walk` counted nested closures as public API and discarded same-file callers —
  **69** flagged against the roadmap's 12. (2) Reference matching counted **prose**: it passed with
  zero unreferenced while `evm.quadrant` was "reached" only by *"CPI–SPI quadrant"* in a TypeScript
  comment, so the gate could not go red at all. (3) The TypeScript block-comment regex ran on `.py`.
  (4) `"""…"""` pairing shifted and swallowed code to end-of-file. Python is parsed with `ast` now,
  regex stripping is `.ts`-only, and each fix is mutation-checked.
- **It still cannot see `quadrant`**, whose name collides with a UI label inside a string literal,
  and string literals have to count because registries dispatch on them. That one needed a human.
  The limit is written in the file rather than hidden behind an exemption.

## v0.3.979 (2026-08-17) — the filename was the whole defect

**`LICENSE-NOTES.md` → `THIRD-PARTY-NOTICES.md`.** GitHub's licence classifier globs `LICENSE*`,
`LICENCE*` and `COPYING*` at the repository root and tries to identify every hit. A *notes* file
sitting beside the real licence is therefore not a neighbouring document — it is a **second licence
declaration that fails identification**, and the sidebar degrades from "MIT" to
**"MIT, Unknown licenses found"**.

That string is not cosmetic. Directory listings and awesome-lists assert a licence and link back
here, so the repository has to agree with them, and "Unknown licenses found" is exactly the claim
that makes a reviewer hesitate. **Nothing in the file's contents was ever wrong — the filename was
the entire defect**, which is also why no gate about doc *substance* could have caught it: every
existing check asked whether the document said enough, and none asked what its name made GitHub
believe.

**So there is now a gate, and it checks the shape rather than the one name that failed.**
`test_doc_substance.py` asserts that exactly one root file matches the licence glob. A well-meant
`LICENSE-THIRD-PARTY.md` or `LICENSES.md` fails it too. Mutation-checked by restoring the old
filename, which turns the check red with the reason.

Four live references followed the rename (README, `docs/deploy.md`, and the two gates that name the
file by string — `docsPublished.test.ts` and `test_doc_substance.py`). Three historical mentions in
`roadmap-completed.md` and the internal archive were left in place but demoted from backticks to
plain quotes, per this repo's own rule that **backticks are reserved for files that exist**: those
records describe what was true then, and a backticked dead name reads as a live citation.

## v0.3.978 (2026-08-17) — whose court did the permit sit in

**R22-ENTITLEMENT ③.** A permit that took seven months prompts exactly one question, and it is never
"how long". It is *whose court did it sit in.* An agency that held three review rounds for 40 days
and an applicant who took 55 days to answer them produce **identical elapsed time**, a completely
different conversation, and a different remedy.

Until now this system could not tell those two apart. Both registers for approval already existed —
`entitlement` (application type, agency, hearing date, public process) and `permit`
(applied → under_review → issued) — and `approval_conditions.py` / `condition_checks.py` already carry
conditions of approval into the model as constraints. What neither register modelled is **rounds**.
`permit` has a single `under_review` state, so a third round is indistinguishable from a first and the
only recoverable duration is `applied_date → issued_date`: one number for a process that is a
back-and-forth.

**New: the `review_cycle` register and `approval_cycles.py`.** Each round carries submitted,
comments-received and response-sent dates, so the elapsed time splits into the leg the agency held and
the leg the applicant held. `agency_share_pct` is the number an argument actually quotes.
`GET /projects/{pid}/entitlements/review-cycles` serves it, optionally filtered to one application.

**The refusals are the design, and each one is mutation-checked:**

- **An open round is unmeasurable, not zero days.** A round sitting with the agency has no
  comments-received date, and scoring that absence as 0 would report a submission held for ninety days
  as instantaneous — the most flattering possible lie about the party you are about to argue with.
  Open rounds are counted and *named* (`rounds_open`, `open_detail`, `held_by`), never scored. Same
  rule v0.3.974 settled for PPC, for the same reason.
- **A share of an unknown total is not a share** — `agency_share_pct` is `None`, never 0, when either
  side has no closed leg.
- **Days are calendar days, and the axis is stated on the response.** A statutory review period does
  not pause for a weekend, and an applicant who sat on comments over a holiday still sat on them. This
  is the opposite choice from `schedule_compare`, which counts working days because a *construction*
  duration is worked. Mixing the two silently is how `eot.py` produced four identical numbers.
- **Rounds out of order are reported, not sorted away.** Round 3 dated before round 2 means a mis-keyed
  date or rounds that are not what they look like, and quietly sorting destroys the only evidence.

**The test's load-bearing case is a pair of applications with the same total elapsed time** (60 days,
2026-01-01 → 2026-03-02) and opposite causes: 54/6 against 9/51. If those ever collapse into one
number the module has stopped answering the only question it exists for. Measuring the applicant leg
from submission instead of from comments-received fails three named checks; scoring an open leg as 0
fails the share check; sorting the rounds fails the out-of-order check.

One real defect was caught by writing the refusal test before believing the engine: the undated-rounds
count was returned under a mismatched key, so `rounds_undated` stayed 0 while a stray field appeared
beside it. Asserting the *count* rather than just the status is what saw it.

**The route has a client caller, because a gate insisted.** `test_route_reachability` failed the
moment the route landed: *"a route the product cannot call is a feature nobody can use."* It offers
two ways out — wire it, or freeze it with a reason — and wiring it was clearly right, so the split now
renders in **Diligence & Entitlements**, beside the go/no-go banner that counts applications by state
without saying who was holding them. A refusal renders *as* a refusal there; "0 days with the agency"
would be a confident wrong answer about the party the reader is preparing to argue with.

---

**R39-DECOMP-VIEWER ⑦ — the drawings group leaves `app.ts`.** 142 lines to
`viewer/tools/drawingsSection.ts`: 3,444 → **3,311**, and the whole `sheetSpecs` import left with
them. Slices ①–⑥ had already emptied the `builders` map (5,160 → 3,444); this is the first group
lifted out of the ~1,100 lines still sitting directly in `buildToolsPanel` above it.

**It is the slice that finally exercised the accessor rule.** `exportsSection.ts` said outright that
it "touches neither" mutable capture and that its deps type was shaped so the next one could. This is
that one: `activeStorey` and `activeStoreyZ` are `let`, reassigned by the level selector. Passing
either by value compiles clean and freezes the level at panel-build time — which is *before any level
exists* — so every plan, DXF and sheet would quietly render the whole building instead of the level on
screen. As accessors, `tsc` then rejected `if (d.activeStorey()) q.set(…, d.activeStorey())`: two
calls cannot narrow where one `let` did, which is the compiler asking the right question, since two
calls genuinely can differ.

**Moving the code broke a gate, and that is the part worth keeping.** `sheetSpecs.test.ts` asserted
against `app.ts` that `placeBtn` is built *and* appended — written because that button nearly shipped
constructed-and-unreachable. It failed with its own message: *"the rail moved and this gate is now
blind."* An extraction is exactly the event that invalidates a gate's address. Re-pointing it at the
new file alone would have left it **weaker** than before, because the seam adds a link that can fail
silently — build the button, forget to `return` it. It now follows all three hops (built → returned →
appended), each mutation-checked.

**Two ratchets moved down, neither raised.** `app.ts` 3,444 → 3,311. And `client.ts` failed the
extraction ratchet when the new API method pushed it to 3,706 — the pin working as designed. Its own
history records the same event at ⑫, when a response type went to `types.ts`; this did that twice,
moving both the new `ReviewCycles` type **and** the `DiligenceReadiness` one beside it, so 3,685 →
**3,683**. The pin bought a second DTO out of the file rather than merely admitting the first.

**Docs:** the register count went 138 → 139 in six places across four files. The doc gate flagged one
of them.

## v0.3.977 (2026-08-17) — the roadmap gets its own hygiene, and a gate that can see a duplicate

Docs and one test. No product code changed.

**Thirteen completed entries archived** — `roadmap.md` goes 3,616 → 3,051 lines, and
`roadmap-completed.md` takes 565. `RATCHET-SET` was **deliberately left in the live roadmap**: its own
text argues that why a scalar ceiling was the wrong instrument is worth reading before anyone reaches
for another one, and that argument is only useful where people are still choosing instruments.

**Four shipped codes were still sitting in lane cells** — `BOE-MAPPING-DEDUP`, `R43-PLAN-DRIFT`,
`R24-CMDK-VERBS`, `R41-BUNDLER-SPLIT`. Same shape as the `R22-AGENT-PACKS` finding a release earlier:
finished work making a lane look busier than it is. Archiving without clearing these would have failed
`roadmapLanes.test.ts` on its other direction — the table naming a code that no longer exists.

**Two items each had two bullets**, and the gate could not see either. `roadmapLanes.test.ts` asserts
MEMBERSHIP — every code is in a lane, every lane names a real code — and both assertions are satisfied
by the first occurrence and never look for a second. `R31-CITE-HIGHLIGHT` and `R22-PIPELINE` had been
double-counted in every total for months while the file stayed green.

Neither duplicate was an accident: both secondary entries *say* they are cross-references (*"the live
entry is the Band 2 one"*, *"folded in rather than deleted"*, because both halves found real and
independent blockers). So nothing was deleted — the secondaries became bold cross-references instead
of `- **CODE**` bullets, and the count became honest.

**A uniqueness assertion now exists**, with a twin that plants a duplicate pair so the scan cannot pass
vacuously. Mutation-checked: it names the offending code and its count.

*And the first sweep for duplicates found only one of the two*, because it grepped for the code
somebody had already noticed. Counting every bullet found the other — the same
enumerate-the-population lesson this roadmap keeps re-learning about itself, committed while auditing
it for exactly that.

**A next-three-sprints block** was added to the NOW section, labelled a proposal rather than a
decision, because five consecutive releases were each one item chosen in the moment. That worked and
is not a sequence anybody else could pick up. The reasoning is written out so disagreeing with it is
cheap.

**Verification, stated precisely:** the full web suite (1,650 tests), all five roadmap/doc gates, and
the backend gates that read these files. **The full backend suite was not re-run** — no Python source
changed in this release, and the previous commit's 606/606 covers that tree.

## v0.3.976 (2026-08-17) — one PPC rule for answers too: the leg fills itself, and it was one engine

v0.3.975 gave the ANSWERS leg somewhere to live. It stayed empty on every real project, because the
only thing that produces a cited answer never filed one — `admissible` was reachable in principle and
unreachable in practice, which is a quieter version of the same defect.

**It was ONE engine, not three.** The roadmap said `decision_gate`, `persona_answer` and `rfi_qa`
answer. Reading them says otherwise: `decision_gate.evaluate` *consumes* a cited answer as evidence,
`persona_answer.shape` *re-renders* one for a reader. Only `rfi_qa` calls `cited_answer.build`.
**Wiring all three would have filed one answer three times under three engine names — and a provenance
report is a count, so that is worse than not filing at all.**

`provenance_report.record_answer` files; `rfi_qa.ask` calls it with the `db` and `pid` it already
holds, so no signature changed. **Filing never raises and never blocks answering:** a question
answered correctly and unfiled beats one that filed and returned nothing, so failures ride on the
response as `recorded: false` with a *composed* reason — `str(exc)` on a response path is the v0.3.962
defect. An answer with **no** citations is still filed, because that is precisely what the report
exists to name; dropping it would improve every provenance report by hiding the answers most worth
looking at.

**The round trip is the assertion.** `test_answers_leg_roundtrip.py` asks and then counts it in the
report, because both halves have their own tests and neither can see the seam between them. It also
asserts the population in both directions — exactly one module builds a cited answer, exactly one
calls `record_answer`. If that ever names two, the leg double-counts and every report reads better
than the project is.

**Two seam defects it caught, both invisible to either side alone.** `create_record` reads its field
map out of `body["data"]`; passing it flat inserts a record with every field empty and does not raise
(mutation-checked, 2 named FAILs). And `cited_answer` emits `guid` for an IFC citation and `rule_id`
for a rule where the register declares `document_id` — a module `table` field keeps the columns it
knows and **drops the rest**, so an unmapped key stores a citation with nothing to open.

**And one in the test itself, worth recording because it nearly shipped.** It set `AEC_DB_URL` where
the real variable is `DATABASE_URL`, so it wrote to the shared `./aec.db` while claiming isolation.
Every assertion passed. A UNIQUE-constraint collision on the *second* run is what gave it away — a
first green run proves nothing about isolation.

## v0.3.975 (2026-08-16) — the answers leg gets somewhere to live, and `admissible` becomes reachable

`R22-PROVENANCE`'s last leg. `provenance_report` reported ANSWERS as `not_captured` — not *"you have
not filled this in"* but *"this system has nowhere to put it"*: `cited_answer` was an in-flight
contract consumed by decision_gate / persona_answer / rfi_qa and discarded with the response. **No
project could satisfy that leg, so a project-scoped verdict could never read `admissible`** however
well-cited the deal was. A verdict with no reachable passing branch is not a strict check, it is a
check that has stopped being one.

**`answer_record` is the store the old note asked for by name.** A register in Project Governance
beside Assumptions and the Decision Log, holding the question, the answer, what it was about, the
engine that produced it, and a **table of citations** with source type, document, sheet, page and
revision. `from_project` gathers the leg through `provenance_report.answer_rows`; the verdict is no
longer forced down and now fails on the legs' own evidence.

**Three gates turned this build, and none of them was the schema.**

The register first went into a section that does not exist — `Quality & Compliance`. `test_module_rooms`
caught it as *"every module in it is unreachable from the spine"*. Moved to `Quality` it hit the
**8-module section cap**, whose message is *"split it on the seam — what JOB differs, not the count"*.
Quality verifies physical work; Project Governance records what was concluded and on what basis, which
is this register's job. Then `test_module_fields`' island ratchet refused a register with no reference
at all — correctly, because a cited answer that cannot be walked back to the document it cites is the
exact thing this exists to prevent. It gained `source_document` and `source_rfi` rather than a raised
ceiling.

**Two seams asserted rather than assumed.** The register-to-leg mapping (`answer` → `text`, the
citations table → `citations`) is the same shape as the `ESTIMATE_TO_BOE` defect: unmapped it does not
raise — every answer simply looks uncited, and the report states with confidence that nothing in the
project is cited. Mutation-checked, 2 named FAILs. And `not_captured` is now unreachable from a project
report, so it is asserted where it still can be reached — with the register absent — because a status
nothing can produce is dead code no test would miss.

The Alembic revision needed a column the copied template predated (`schema_version`, added to every
`mod_*` table in `e2c6f31b9a44`): the neighbour you copy carries its own age, and `alembic check` is
what says so.

*Not done, and named rather than implied:* `decision_gate`, `persona_answer` and `rfi_qa` do not yet
auto-record what they answer. The register is written through the generic register surface; wiring
those three is the next slice.

**Also from the R22 premise-check:** `R22-AGENT-PACKS` moved from Lane C to Lane A. Its packs, audit
trail and attribution fix are all shipped and its own text already said the remainder — the governance
console — is shell work. A code sitting in a lane that cannot finish it makes the lane look busier
than it is.

## v0.3.974 (2026-08-16) — one PPC rule, and an engine that could not read its own register

`R45-SCHED-DEDUPE ②`'s last overlap. **Your call, taken: the vendored engine's rule wins.** One rule
everywhere — met or not met with no partial credit; an **unanswered commitment makes the period
unmeasurable**, so PPC is `null` rather than a number; and nothing promised is `null` too, because a
team that made no commitments has not broken any.

Still **three functions, because there are two registers and a route** — `lean.ppc` scores
`weekly_plan`, `pull_plan.metrics` scores `pull_plan_task`, `schedule_lastplanner` scores the same
records through `massingplan.core.lastplanner`. Collapsing them would merge two registers holding
different work. What had to agree was the rule, and `test_ppc_divergence.py` now asserts the
agreement — with a **closed** week as the twin, because three engines that always answered `null`
would look consolidated and be broken.

**The consolidation turned up two defects nobody was looking for.**

**The engine could not read its own register.** `schedule_lastplanner` grouped commitments on a field
called `week`. `pull_plan_task/module.json` declares **`planned_week`** — `week` is `weekly_plan`'s
field, a *different register*. So `GET /schedule/reliability` answered *"none of the N pull-plan tasks
carry a week"* on **every real project**: routed, reachable, tested, and structurally unable to read
the records it exists for. Its only test passed on a hand-written fixture supplying `week`.

*A fixture cannot catch this by construction.* It is written from the same wrong belief as the reader,
so it agrees with the reader and disagrees with the database. `test_ppc_field_conformance.py` asserts
the engine's field names against the register's own `module.json` — a reader neither of them wrote.
Mutation-checked: 4 named FAILs, and the gate reproduces the exact pre-fix refusal message.

**`pull_plan.metrics` disagreed with itself.** The trend line divided by every commitment including
the unanswered ones; the headline divided by the assessed only. On one week with 1 done, 1 missed and
3 still open, that is **20% in the chart and 50% in the tile — same week, same panel**. The existing
test could not see it: its fixture had no unanswered commitment, so both forms happened to agree.

Also: `lean.ppc` no longer reports `0.0` and a rating of *"needs work"* for a project with no
commitments, and no longer defaults a missing variance reason to the string `"Unspecified"` — which
sorted beside real reasons as though somebody had entered it, in the list a team is asked to act on.
And the web PPC-trend chart stopped plotting `?? 0` for a null week: drawing "not measurable yet" as a
zero bar is the confusion the null exists to remove, and worse in a chart, because a reader sees a
collapse rather than a gap. Unmeasurable weeks are dropped and counted underneath instead.

**`GET /schedule/risk` keeps serving as a deprecated alias** — your call, taken, and the roadmap
question is closed rather than left open.

**The R45 ring is complete.** Of its four "overlaps", three were never overlaps at all — `takt` was
line-of-balance wearing the takt name, `progress` measures the schedule where `progress_rollup`
measures the building, and PPC needed one rule rather than one function. Only `risk` was two
implementations of one thing. The table had been built from names.

## v0.3.973 (2026-08-16) — 877 dead functions, then 35, then 13, and one of them was replayable

`R37-TRIAGE` said the dead-code list *"should be re-derived, not triaged"*. Re-derived — and the
derivation is worth more than the list.

| population rule | candidates |
|---|---|
| public functions in `aec_api` never referenced by name | **877** of 1,993 |
| …excluding decorated functions (FastAPI handlers are reached by decorator, never by name) | **35** |
| …counting string literals as references, across `services/api`, `services/data` and the test tree | **13** |

**877 to 13 without changing a single threshold.** Every reduction corrected *what counts as a
caller*. The first number — "44% of this package is dead" — is what the obvious query returns, and it
would have been confidently wrong by a factor of 67.

**One of the 13 justified the exercise on its own.** `auth.verify_stepup_token` ran identical
signature, expiry, action and password-fingerprint checks to `verify_stepup_claims` and returned
**only the subject** — so a caller reaching for it could not spend the `jti`, and the step-up
assertion stayed **replayable**. A step-up attests *"a human confirmed THIS act"*; `rbac.consume_stepup`
spends the jti against `stepup_spent` precisely so a captured token cannot seal a stack of documents.
Nothing called the weak one, which is the reason to delete it rather than a reason to leave it: two
verifiers where one silently drops replay protection is a footgun whether or not anyone has picked it
up yet.

`services/api/test_stepup_single_verifier.py` asserts the **property** — every step-up verifier
returns something a caller can spend — not the absence of a name. A grep for a deleted name passes
forever and reads as coverage. It also re-asserts what must not have been lost with it: a step-up for
one act does not satisfy another, a changed password invalidates an outstanding assertion, a tampered
signature is refused, and garbage returns `None` rather than raising.

**Three roadmap items closed on measurement, not on re-reading.** `R41-CLASH-TRIAGE` (grouping,
dedup, grazing filter and consequence ranking all built; the 18:1 scale test is in the manifest and
passes), `R45-VENDOR-REACH ③` (29 of 29 vendored modules reachable, allowlist empty, asserted in both
directions) and `R45-SCHED-REACH ①` (all five adapters routed — `resources` is adapted inside
`schedule_levelling.py`, which is why a filename check would have called it unfinished). All three
were done and none carried the ✅, which costs every later reader a premise-check.

## v0.3.972 (2026-08-16) — two Monte Carlos, and the one that counted Saturdays is gone

`R45-SCHED-DEDUPE ②` asks for one decision per overlap: *diff the two behaviours, keep the deeper
engine, keep our rendering, delete the loser, and write a test asserting there is exactly one
implementation.* This is the `risk` decision. `aec_api/schedule_risk.py` and its test are deleted;
`schedule_risk_mc.py` over the vendored engine is the only simulator left.

**`GET /schedule/risk` still serves, as a deprecated alias, and that is a correction.** This release
first deleted the path along with the engine. The roadmap had recorded retiring it as *"a user-facing
removal and therefore your call"* — a decision a previous session escalated and nobody answered. The
engine was this item's to delete; the path was not. It now returns exactly what
`/schedule/montecarlo` returns, with a `deprecated` note naming the successor, so nothing 404s while
the removal stays undecided. The response *shape* did change — dates rather than day counts — which
is unavoidable, since the old shape was the wrong answer's shape. `scheduleRisk` survives as a
one-line client alias and is recorded in `KNOWN_UNCALLED` as deliberately callerless.

*An item that authorises a deletion does not authorise every deletion it touches.*

**Two measured defects, not one, and the second is the worse.**

* **It added calendar days.** On five 20-day activities in series from 2026-03-02 — a hundred working
  days — the deleted engine put the deterministic finish on **2026-06-10**. The surviving one, running
  the same `Task`/`Link` network on the same work calendars the CPM uses, puts it on **2026-07-17**.
  Thirty-seven days apart, in the same portal, under two labels that both said "schedule risk".
* **Its predecessor index was built from `ref` and `wbs` only, never the record `id`.** `schedule_cpm`
  resolves both. So a schedule whose logic was written with record ids chained correctly in the CPM
  and simulated as **fully parallel** in the risk run — no error, no warning, a P80 four months early
  on a job with four months of chain in it.

**Deleting the loser is not a licence to drop what it was carrying**, which is where a dedupe usually
loses something quietly. Three things moved across rather than out:

* `project_ppc` — the team's Last Planner reliability, now looked up in **one** place. It existed
  twice, in the route and in the MCP tool, which is how two callers of one forecast come to calibrate
  differently and nobody notices.
* the `risk_calibrate` block — the spread measured from **this project's finished work**, reported
  beside the forecast so its provenance can be argued with.
* `buffer_p80_days`, which `risk_board` raises as a finding — now counted in **working** days on the
  schedule's own calendar. The old buffer counted Saturdays and read high on a job that was fine, so
  its severity thresholds were re-derived rather than carried over.

The route, the MCP tool and the risk board now assemble through one `for_project`. The schedule panel
reports dates rather than day counts, and shows **duration sensitivity** beside criticality —
criticality says how often an activity sat on the path, sensitivity says whether its duration actually
moves the finish, and either alone misleads about where to spend attention.

`test_schedule_risk_single.py` asserts one implementation *and* both defects, because the argument for
a deletion is the thing most likely to be doubted later — and because a test that only greps for a
filename would pass against a re-import under another name. Its population scan named the wrong file
on the first run (matching "montecarlo" caught `risk_board.py`, which merely links to the route); the
twin that plants a second simulator is what keeps that honest.

## v0.3.971 (2026-08-16) — four delay methods, one number, and a label that said otherwise

*Cut in the same release as v0.3.972 and carries no separate tag: the first full suite over this
work came back red on four unrelated suites (a known parallel flake — all four pass solo), so
rather than pay a second 36-minute verification the next item was folded in and both were
verified together. The in-code references to v0.3.971 name this entry, not a tag.*

`eot.py` refuses to emit an extension of time without naming its analysis method, on the correct
argument that *"the same facts give different answers under different methods"*. It then validated
`method` against the closed set, echoed it back in three fields — and **never read it again**. Every
branch computed the same additive sum, so `as_planned_vs_as_built` and `windows` returned identical
figures on identical facts.

A required field that changes nothing is worse than no field. It tells the reader the number came
from a windows analysis when it came from adding up event durations, and this is the number the
entry itself says ends up in arbitration.

**`test_eot.py` was the evidence rather than the guard.** It reached for `time_impact` and `windows`
at random for its arithmetic assertions — which is only possible while the choice cannot matter. Its
checks now name `impacted_as_planned`; the behaviour under that method is unchanged.

**Two methods are now computed differently and two are refused.**

* `impacted_as_planned` sums each event's impact beyond available float, bounded by nothing — which
  is the published criticism of AACE MIP 3.6 and is now reported on the response as
  `over_claimed_days` rather than left to be read about.
* `as_planned_vs_as_built` caps that at the movement of the completion date. It needs `actual_finish`
  and **refuses without it** instead of quietly answering the additive question under this method's
  name. Slip that no event explains is `unattributed_slip_days` and is granted to nobody.
* `windows` and `time_impact` need a dated **series** of schedules, which one baseline finish and one
  CPM snapshot are not. They return `method_needs_schedule_updates`; windows names
  `GET /projects/{pid}/schedule/windows`, which performs it against the captured baseline library.
  Time-impact names nothing, because nothing performs it yet — pointing at a route that does
  something else is how this defect started.

Measured: on a 10-day critical employer-risk event against a job that finished 4 days late, additive
grants 10 and as-planned-vs-as-built grants 4. **The twin matters more than the finding**: on a job
where nothing was recovered the two agree exactly, so the difference is the cap and not different
arithmetic — without it, a version returning different garbage per method would have passed.
Mutation-checked (2 named FAILs, and the four numbers collapse back to one).

The assertion in `test_schedule_windows.py` that pinned the old behaviour said that if it ever failed
because the numbers diverged, *that was the fix landing and it should be replaced rather than
relaxed*. This is that replacement.

## v0.3.970 (2026-08-15) — the PO hop was blocked on a register that already exists under another name

`R41-COMMERCIAL-DRIFT`'s last hop read: *"`purchase_order` still does not exist and
`procurement_package` carries `est_cost`/`award_amount` with **zero reference fields** — an island
nothing can walk into or out of."*

**`commitment` is that register.** It is titled *"Commitments (POs)"*, carries `po_date`, `amount`,
`vendor`, `retainage_pct` and `cost_code` — and **already references `subcontract`**. So the hop
needed no schema change, exactly like the three before it. The blocker was the name.

That is the third time in this ring a capability was filed as missing because it was called something
else: `takt.py` was a line-of-balance engine wearing the takt name, `bid_leveling.py` was filed as
absent while shipped and routed, and now the PO register. **A grep for a name proves a string absent,
never a capability** — the check that works is reading what the registers actually hold.

`contract_to_po` joins the walk. Two design calls, both asserted rather than described:

**Every PO against a subcontract is summed**, not just the largest. A subcontract is routinely bought
out across several commitments, and comparing the contract to the biggest one would report the rest
as money that vanished.

**Change orders are excluded from this hop**, unlike `contract_to_invoiced`. A CO raises the contract
sum and is normally followed by its own PO; comparing the CO-inclusive sum against POs raised before
it would report every mid-job change as an under-commitment until the paperwork caught up — a timing
artefact, not drift. The test asserts the two hops start from different figures (105,000 vs 113,000)
rather than trusting the comment.

A project with no commitments gets `incomparable`, never a zero-dollar drift: a subcontract nobody
has raised a PO against has not drifted by $0, it is unmeasured. And the new argument is optional, so
every existing three-argument caller keeps the walk it had — asserted by **comparing the two calls**
rather than by predicting either, after the first version of that twin guessed wrong about its own
fixture.

*One test-hygiene fix in passing:* the suite asserted `hops_compared + hops_incomparable == 6`, a
literal that had no way to notice a third hop was added. It is now derived from the rows — every hop
must land in exactly one bucket, which survives a fourth.

## v0.3.969 (2026-08-15) — two rounding conventions inside one G702, and a penny between them

`R43-MASSINGBILL-CORE` recommended adopting `massingbill/core/money.py` to fix a float money path in
`payapp.py`. **That premise was already stale** — v0.3.927 replaced it with exact `Decimal` quantized
HALF-UP, under the title *"money is Decimal end to end"*.

It was right about `payapp.py` and wrong about the tree. Checking the other five G702 sites the item
itself names found **three that still computed retainage as `round(amount * pct / 100, 2)` on binary
floats** — `cost.py` twice and `routers/cost.py` once. `round()` is ROUND_HALF_EVEN; an invoice
rounds half away from zero. Measured on the real code:

| completed | rate | `cost.py` | `payapp` |
|---|---|---|---|
| 2.50 | 5% | **0.12** | **0.13** |
| 12.50 | 1% | **0.12** | **0.13** |
| 162.50 | 1% | **1.62** | **1.63** |

**Four of six sampled cases differed by a penny**, and the same pay application could show either
number depending on which path produced it. A pay app out by a penny is rejected, so this is the
document failing rather than a rounding curiosity. It is `correct-twice-missed-once` exactly: N−1
fixed sites prove nothing about the Nth, and the release note said the tree was done.

`aec_api/money.py` — which has carried `q2`, `to_cents` and a penny-accurate `allocate` since
v0.3.191 — gains `retainage()` and `rate()`, and the three float sites now call them. Additive: no
existing helper changed, and `payapp.py` was left alone because it was already correct and touching a
shipped billing path without a defect to fix is risk for nothing.

**Neither "massingbill/core/money.py" nor a new module was adopted, and that is the finding.** The
correct implementation already existed here; what was missing was that three sites had never been
pointed at it. `test_money_spine.py` pins the divergence that existed, the convergence now, and the
fact that `payapp`'s own quantize helpers still agree with `money`'s — a duality tolerable only while
it agrees, so the agreement is asserted rather than assumed.

Also pinned: an explicit **0%** retainage rate stays 0% (a truthiness test made it 5%, withholding
$1,000 on a $20,000 line the owner had agreed to hold nothing on), while a *missing* rate still gets
the contract default.

*Two process notes, both mine.* The first draft of the test asserted `abs(old - new) == 0.01` and
failed, because `1.63 - 1.62` is `0.010000000000000009` — comparing float differences with `==`, in a
test about float money. And I wrote this fix as a **new** `money.py`, destroying the existing one;
`test_money` and `test_money_wire` failed in 0.3 seconds with `no attribute 'q2'`, which is the only
reason it was caught. Second time in one session that a "new" module overwrote a tracked file. The
restore was clean and the shipped change is the additive one.

## v0.3.968 (2026-08-15) — the third sync in two days, and it changed the three shipped yesterday

`massingplan` re-synced `a740241c` → **`ccadd04b`**. MIT, read from the LICENSE file; copy verbatim,
no local deviations. Four modules changed and **three of them are ones this repository wired hours
earlier** — `compression`, `modelled` and `portfolio` — after an upstream review. The fourth is
`xmlsafe`, whose commit message is *"Stop lexing XML by hand, and fix a character set that was wrong
both ways"*: that module is on the XER, MSPDI and PMXML upload paths, so it is the half that mattered
most, and it reached us transitively again with no adapter change.

**Nothing on our side needed changing.** The R46 adapters, the delay-analysis suites, the XXE and
PMXML tests, the reachability ratchet and the per-project portfolio authz check all pass unaltered
against the new engine. That is the useful result: three adapters written against code that was
revised underneath them, and the seams held.

Worth recording because it is the point of the whole R45/R46 arc — this is the **third** massingplan
sync in two days, and each time `test_massingplan_vendor` (is the copy faithful?) and
`test_vendor_reachable` (can the application call it?) have answered different questions. The first
sync grew the engine behind a green digest. The second refilled an allowlist that had just been
emptied. This one revised three modules a day after they were wired, and the only reason that is a
non-event is that both gates run on every push.

## v0.3.967 (2026-08-15) — R46 complete: 29 of 29, and an acceleration figure that overstates

The last three vendored modules are wired. **Every module the `a740241c` sync brought is now
reachable**, and `test_vendor_reachable`'s allowlist is empty again — this time at 29 of 29.

**`POST /schedule/compress` — and the number `/schedule/optimize` cannot get right.** That route is a
rule-based advisory, honest about it in its own docstring: it never re-schedules, and reports
`duration × 0.25` for each long critical activity. A fraction of the activity's own length cannot see
the path *behind* the activity, and shortening a driving activity by five days when it is only three
days ahead of the next path buys three. The other two are spent and gone.

Measured on a four-activity network with a near-parallel path: **the advisory says 5 days, the finish
moves 3.** The error grows with the number of near-parallel paths, and it is largest exactly where the
schedule is tightest and the decision is most expensive. This re-schedules after every single day, so
`days_saved` is the project-finish movement, and the plan is cheapest-useful-day-first — an algorithm
picking its whole shopping list from the *original* critical path keeps spending on an activity that
stopped driving three days ago.

`cost_per_day` and `max_days` are **required per activity**. `max_days` is a fact about the work — a
pour cures in the time it cures — and a default of "as far as you like" produces a plan that finishes
on any date somebody asks for. A plan reaching eight of ten days is returned as eight.

**`POST /schedule/weather`** — the allowance a programme already carries, modelled as non-working days
instead of padded into durations, where a five-day pour becomes seven and nobody can afterwards say
which two days were weather. That matters when the weather arrives: a contractor claiming an extension
has to show the allowance was exceeded, and an allowance buried in durations cannot be shown at all.
**No allowance is invented** — a request with none is refused, because a default is a number nobody
agreed inserted into a programme somebody signs. The days are listed, not just counted. And the
without-allowance run strips **only** the weather days: removing every calendar exception would delete
Christmas and report a fortnight of it as weather recovered.

**`POST /schedule/portfolio`** — several projects in one pass over one merged network. Scheduling them
in sequence propagates a delay only in whichever order somebody listed them; merging first is the only
way the direction of the arrow decides it. A cross-project cycle — one that neither schedule has alone
— is found and refused, which is among the things scheduling them together is for.

**It reads other projects' data, so it is gated on every one of them.** `test_route_authz` proves each
`/projects/{pid}` route enforces membership on its own `{pid}`; that is all it can see, and this route
takes more ids in its body. The dependency is re-run per project, and
`services/api/test_portfolio_authz.py` exercises it through the real app: **403 for a project the
caller is not a member of, 200 when they are.** The twin matters — without it, a route that refused
everything would pass.

## v0.3.966 (2026-08-15) — a PMXML import that imported nothing, and the SPI that reads 1.0 on a late job

**A Primavera PMXML export used to import zero activities.** The branch warned
*"PMXML is parsed by the legacy reader, which does not carry relationships"* and returned
`activities: 0`, with a note telling the planner to re-export as XER. So the one Primavera format
that **can** carry baselines and global calendars — the thing XER structurally cannot do, and the
gap behind our own baseline-schema work — was the one that imported as nothing.

`p6xml.read_p6xml` returns the same `ExchangeSchedule` the XER reader does, so it drops straight into
the existing path: activities, relationships, durations, calendars. The upload gets the same defused
pre-parse as MSPDI, and for the same reason — this path takes a file from a user, so it **rejects** a
document using XML entity or DTD features rather than sanitising one. That is not redundant with
`xmlsafe` in the vendored reader: one is a property of the parser, the other of this upload path.

Worth recording because it nearly shipped wrong: the first fixture used
`<PredecessorActivityId>A1010</...>` and produced **zero relationships while passing every other
assertion**. Real PMXML links activities by numeric `ObjectId` and carries the planner's code
alongside. The fixture was written from what the format "should" look like; the corrected one was
written from the reader. A fixture that parses cleanly and yields nothing is the exact shape of the
defect this release closes.

**`GET /schedule/earned` — Earned Schedule.** `evm.py`'s own docstring defers it: *"the time-based
Earned Schedule extension come in later phases"*. This is that phase, and `evm.py` is untouched.

Classic `SPI = EV / PV` is a cost ratio used as a time signal, and it has a terminal defect: EV
converges on PV at completion whatever the dates did, so **SPI returns to exactly 1.0 on a project
that finished late**. It does not degrade — it arrives at "perfectly on schedule" for a job everyone
watched run over. Measured on a schedule that finished **24 working days** past its baseline,
`SPI(t) = ES / AT` reads **0.556**. The twin matters as much: a project that ran to plan reads 1.034,
so an index that was simply always pessimistic would have failed here.

**It is the one baseline method that works on a pre-v0.3.961 snapshot.** `compare`, `windows` and
`impacted` all need frozen logic and refuse the older ones; Earned Schedule needs only dates, which
every baseline ever captured carries. Refusing them would have been a refusal the data does not
require.

Activities with no baseline entry are excluded from both sides and **counted** — progress on work the
plan never contained inflates the index for doing unplanned things, and the count says how much was
set aside. `performance_index` is `null` when no time has passed, never 1.0.

**26 of 29 vendored modules now reachable.** Three left: `compression`, `weather`, `portfolio`.

## v0.3.965 (2026-08-15) — four delay methods that were one number, and two of them now real

**`eot.py` offers four AACE delay-analysis methods, refuses to produce a number without one, and
performs none of them.** Measured, not argued — one input, a 10-day weather event and a 6-day change
against a baseline and an actual finish:

| declared method | `eot_days` |
|---|---|
| `as_planned_vs_as_built` — *"the weakest"* | **16.0** |
| `impacted_as_planned` | **16.0** |
| `time_impact` — *"preferred by most protocols"* | **16.0** |
| `windows` — *"most defensible, most data-hungry"* | **16.0** |

One number, four labels. The method is recorded and then not used — the arithmetic is
events-minus-float in every branch, and nothing re-schedules a network, which is what three of those
four methods *are*. A user who picks the most defensible method gets the answer the weakest one
gives, and the label travels into a claim as though it had been earned. Pinned in
`services/api/test_schedule_windows.py` so it cannot close unnoticed — or widen.

**`GET /schedule/windows`** — contemporaneous windows analysis (AACE 29R-03 MIP 3.3), performed. The
series comes from the captured baseline library: up to twelve dated snapshots, each carrying the
logic to be re-scheduled since v0.3.961. That capability was added for `compare`; this is the second
thing it bought and the more valuable one. The answer is *which period lost the time*, which
as-planned-vs-as-built structurally cannot give. Windows sum to the total slip exactly, and a window
that pulled time back is reported as a **negative** rather than dropped — a claim that counts only
the slips overstates itself, and the sum would not hold.

A pre-v0.3.961 baseline is **excluded and named**. Re-scheduling one produces a fully-parallel plan,
which here would not merely be wrong but wrong *inside one window*, moving time into a period it did
not happen in. Likewise a snapshot with a logic loop: named, skipped, and the rest of the series
still analysed.

**`POST /schedule/impacted` and `POST /schedule/collapsed`** — impacted as-planned (MIP 3.6, additive)
and collapsed as-built (MIP 3.9, subtractive), the two that **alter** the network. Impacted runs
against the captured baseline and refuses if there is none: impacting a progressed schedule is a
different method with a different name.

**Concurrency is now measured rather than named.** `eot.analyse` declines to apportion it, correctly,
because it has no network to measure it on. With one it is arithmetic: two overlapping delays of 8
and 6 days move the finish 8, not 14, and the 6 is the entitlement nobody gets twice. The independent
case reports zero — without that twin, a number that was always positive would look like a finding on
every project.

**Collapsed as-built is refused on our data, and the refusal is the finding.** The method removes
activities that are already in the as-built network; ours are detected from the field record by
`notice_clock` and are not in `schedule_activity` as tasks. Inserting them and then removing them is
impacted as-planned wearing the subtractive method's name, and a report that did that could not say
what it had done. The refusal names which events are missing, and the method runs correctly when the
precondition really is met.

`days_source: "caller"` is on every result. Nothing in the field record says what a delay cost —
`notice_clock` deliberately returns no `days` field — so the most contested input on the page is
typed, and the response says so. `responsibility` is carried through untouched.

**The reachability ratchet's vacuity twin failed, and it was the twin that was wrong.** It dropped the
alphabetically-first entry point and required the closure to shrink; wiring `windows`, which imports
`compare`, meant dropping `compare` as a *direct* entry point no longer shrank anything. It was
measuring which name sorts first, not the property it meant. Now asserted two ways that depend on no
particular name: no entry points must reach nothing, and any single one must reach strictly less than
all of them.

## v0.3.964 (2026-08-15) — the vendor re-sync that proved its own gate

`massingplan` re-synced `d1e4bf16` → **`a740241c`**: eight new modules, 2,986 lines, a rewritten
MSPDI writer and an injection audit across every writer. MIT, read from the LICENSE file. Copy
verbatim, no local deviations.

**R45 finished yesterday with all 21 modules reachable and the allowlist empty for the first time.
This sync refilled it, and `test_massingplan_vendor` stayed green throughout** — the digest matched,
`core` still imports nothing but the standard library, nobody forked a file. It was
`test_vendor_reachable` that failed the build. Faithfulness and usefulness are different claims
about a vendor drop, and only the second one notices that the engine grew and the application did
not. The second gate justified itself on the very next sync rather than in the argument for it.

**The security fix was already live.** `xmlsafe.py` — parse-bomb and XML-entity hardening — reaches
us transitively through `mspdi` and `xer`, so it took effect the moment the files landed. It is not
on the unreached list and needs no adapter. The XER/MSPDI import paths are the ones users point at
untrusted files, so this is the half of the sync that mattered most and it needed nothing.

The `mspdi` rewrite (1,265 lines differ) and the `xer` injection audit landed with **no adapter
change and no test movement** — verified by running the schedule suites, not inferred from the diff
being large.

Seven modules now have no path from the API, recorded as **R46** with what each answers. None
duplicates anything we have, so unlike R45 there is no de-duplication decision hiding in the list:
`windows` (contemporaneous windows analysis — where the eighty days went, window by window, which is
the question a claim asks and `compare` cannot), `modelled` (impacted as-planned / collapsed
as-built, which *alter* the network where `windows` only observes it), `p6xml` (PMXML carries
baselines and global calendars; **XER cannot**), `earned` (Earned Schedule — how far along in time,
where SPI degenerates to 1.0 in the last third), `compression` (what finishing three weeks earlier
would take, and cost), `weather`, and `portfolio`.

## v0.3.963 (2026-08-14) — a select read as a truthy object, and a scanner that read its own comment

**`bool("No")` is `True`.** `bid_leveling` read `bond_provided` as `bool(d.get("bond_provided"))`,
and that field is a select whose options are the strings `"No"` and `"Yes"`. So a bidder who
explicitly answered **No** reported as bonded, while one who left the field blank reported as not
bonded — the two cases inverted precisely where it matters, because an explicit No is the answer
somebody typed on purpose. A bid bond is what lets a bidder enter the contract at all.

`addenda_acknowledged` is captured by the `bid_submission` register and was read by **nothing**. A
bidder who acknowledged no addenda has not bid the current documents. Both are now
`non_responsive` — reported as their own list ahead of the grid, and carried on the recommendation,
because responsiveness is decided before price and neither has anything to do with being cheap. A
table sorted by number puts exactly these bidders at the top.

### The reachability scanner read a comment as a call site, then ate a real one

`clientCallers.test.ts` counts a client method as reached if the app calls it *or* names it as a
string literal. A comment saying a module is *"not `procurementLevel`"* therefore registered as
something calling `procurementLevel` — **a source-grep gate reading its own documentation**, a shape
this repo has hit before. The fix belongs in the scanner: a comment that must avoid naming its
neighbour to keep a test green is a comment the next person rewrites back.

The first fix was three regexes and was **worse than the bug**. The `/*` inside the string
`photoIn.accept = "image/*"` opened a phantom block comment that swallowed the next hundred lines,
deleting a real `api.uploadVerificationPhoto(...)` call. A false positive traded for a false
negative — strictly worse, since an uncounted caller reads as dead code somebody may then delete. It
was caught only because this ratchet fails in **both** directions; a one-way "did anything become
unreachable" check would have accepted it silently. It is now a small scanner that tracks string
state, with a twin asserting comments are stripped *and* that real calls, dispatch-by-name and `//`
inside a URL all survive.

Stripping comments then uncovered a genuinely dark method: **`job(pid, jobId)` has no caller at
all**, and read as reached only because `shell/spine.ts` contains the sentence "`label` and `job`
mirror `rooms.ROOMS`". Recorded with its condition rather than wired, since the caller belongs in
`main.ts`.

## v0.3.962 (2026-08-14) — the same defect, three times, now a gate

CodeQL flagged `py/stack-trace-exposure` on v0.3.961 within the hour: `_unavailable(str(exc))` in the
new compare adapter. **That is the identical defect fixed in v0.3.956** — written again, in a module
authored after the fix, by someone who had read it.

Fixed structurally rather than carefully. The refusal reason is now composed as **data**
(`schedule_baselines.logic_gap()` returns the sentence) instead of being recovered from an exception,
so there is no shape in which exception text can reach that response.

Grepping the same file then found a **third** instance — `str(e)[:120]` on the CV-progress apply
path, shipped for several releases and never flagged, because **CodeQL's alert list is diff-scoped**:
it reports what a push changed, not what a file contains. Now logged server-side with a stable
sentence returned.

Three occurrences of one defect is not a lapse of attention, so it is now
`services/api/test_no_exception_relay.py`: an AST gate over all 444 `aec_api` modules that fails when
an `except … as e:` handler **returns** a value built from `e`'s text.

It distinguishes carefully, because a checker that cries wolf gets switched off:

* `str(exc)`, `f"{exc}"`, `exc.args`, `exc.detail` — **flagged**, that is the library's words.
* `list(exc.cycle)` — allowed. A structured field our own engine chose to expose is the recommended
  alternative, not the defect. Flagging it would have hit every honest refusal path in R45.
* `type(exc).__name__` — allowed. The class is "ValueError", never the path it was raised about, and
  flagging it pushes people back toward `str(exc)`.

Twenty pre-existing relays remain, **recorded with a reason each rather than suppressed**, and the
reasons were verified rather than assumed: every route in `routers/connections.py` carries
`Depends(require_admin_user)`, read from the source, so those are an administrator being shown the
error from a connection string that administrator just typed — a different risk class from an
anonymous caller receiving a driver's trace, and deleting the text would make "test this connection"
useless at its only job. `calc_fields` relays `SyntaxError.msg` from parsing the user's own formula.

The list ratchets in **both** directions: a new relay that is not recorded fails, and a recorded
entry that no longer relays fails too, so it cannot decay into a graveyard of names that were fixed
long ago. The gate is mutation-checked — restoring the v0.3.961 defect fails it by name.

## v0.3.961 (2026-08-14) — delay attribution, and the blocker that was one field

`GET /projects/{pid}/schedule/compare` — the live schedule diffed against a named baseline, with the
finish move **apportioned** across duration growth, added logic, lag, constraints, progress and
levelling. Not variance: `/schedule/variance` answers "did this activity's dates move"; this
re-schedules the baseline through the CPM engine and answers *why the finish moved*. The
contributions sum to the move exactly, because a delay analysis whose parts do not sum to the whole is
an opinion with numbers attached.

`compare` was the last of the 21 vendored modules and the one the roadmap recorded as **blocked on a
decision**: a captured baseline held two dates and a budget, so there was no network to re-schedule,
and adding one "changes what every existing stored baseline means". That is what a **schema version**
exists to avoid. Baselines now freeze durations, predecessors, calendar and constraints under
`schema: 2`; a v1 baseline keeps meaning exactly what it meant, and variance against it is untouched.

**A v1 baseline is refused for attribution, and the refusal is the load-bearing part.** A v1 snapshot
and a v2 snapshot of a schedule that genuinely has no relationships are indistinguishable from the
data. Rebuilt as a network, a v1 one comes back as 1-day tasks with no predecessors — a fully-parallel
plan finishing on day one — which diffs into a large, confidently-attributed delay caused by logic
nobody removed. The test forces one through and measures it: **53 days against a true 14**, named
activities and all. So it refuses, with a sentence saying to capture a new baseline.

Progress is deliberately **not** frozen into a baseline. A baseline that already knows how the job
went under-reports every later slip by exactly the progress recorded the day it was captured.

**A finding in the vendored engine, surfaced rather than patched:** its per-activity contributions are
in *working* days while its finish-move total is in *calendar* days. The sum invariant still holds —
but only because an `UNEXPLAINED` bucket absorbs the difference, and "unexplained" reads to a planner
as a cause nobody has found yet. On a ten-working-day growth it is four days of weekend, every time.
The response now carries `finish_move_working_days` and `calendar_vs_working_gap_days`, and the panel
says so in words. Not fixed in `massingplan/core/` — that is a re-synced vendor drop.

**All 21 vendored modules are now reachable**, and the allowlist that tracked them is empty for the
first time. Its vacuity twin was rewritten in the same change: the old one could never fail once the
list emptied, and a check whose failing branch is unreachable is not a check. It now asserts the
closure is *derived* — drop one entry point, and a real closure comes back strictly smaller.

## v0.3.960 (2026-08-14) — Last Planner reliability, and three PPCs that disagree

`GET /projects/{pid}/schedule/reliability` — PPC by week with the variance reasons, plus a client
method and a Schedule-panel card. **20 of 21 vendored modules now reachable.**

The R45 table called `lastplanner` an overlap with `pull_plan.py`. Reading all of them found a **third**
implementation — `lean.ppc` — and the three do not agree. On one week with 1 done, 1 missed and 3 still
unanswered:

| | denominator | reads |
|---|---|---|
| `lean.ppc` | every record | **20%** |
| `pull_plan.metrics` | assessed only | **50%** |
| `core/lastplanner` | frozen at commit | **unmeasurable** (`null`) |

`lean.ppc` reads artificially low mid-week — on Wednesday every team looks like it is failing.
`pull_plan.metrics` reads artificially high — one commitment answered out of twenty, and it was done,
reports 100%. **The one the portal renders is the flattering one.** These are not rounding differences;
they are different questions wearing the same label on the same dashboard.

Two further `lean.ppc` defects, now pinned: it reports **`0.0` and a rating of "needs work" for a
project with no commitments at all** — a team that made no promises is not a team that broke them — and
it **defaults** a missing variance reason to the string `"Unspecified"`, quietly filling the learning
loop with a value nobody entered.

The vendored engine's rules, and why each exists: the denominator is frozen when the week is committed
(re-planning after seeing how it went makes PPC a measure of nothing); partial completion is not
partial credit; an unassessed commitment makes the week **unmeasurable, not perfect**; a missed
commitment must carry a reason, never defaulted; and only make-ready work can be committed. It also
declines to report a lifetime average — the trend is the signal, and one number across six months hides
the month it collapsed.

**Nothing was consolidated.** Changing what PPC means on a shipped dashboard is a domain decision with
contractual weight — a GC reports PPC to an owner — so all three still ship and
`test_ppc_divergence.py` pins the disagreement so it cannot widen unnoticed.

One hardening on the way: the engine refuses a commitment with no crew, and the first draft let that
exception escape and take out the whole report. A single malformed record now counts as
`unusable_tasks` and is excluded, rather than 500-ing the PPC page — surfaced rather than dropped,
because a silently discarded commitment is a denominator quietly shrinking.

## v0.3.959 (2026-08-14) — Monte Carlo on the real network, and two engines 38 days apart

`GET /projects/{pid}/schedule/montecarlo` — schedule risk simulated over the same `Task`/`Link`
network the CPM uses, with a client method and a card in the Schedule panel.

This is the ring's **one true overlap**: `aec_api/schedule_risk.py` also runs a Monte Carlo. So it
followed the rule the ring settled on — *keep what is ours and distinctive, take their engine*. Ours
calibrates the pessimistic tail from the team's Last Planner PPC, and the vendored engine exposes
`default_estimates(tasks, optimistic_factor, pessimistic_factor)`, which is exactly the seam that
calibration belongs in. Our input, their arithmetic.

**And the swap exposed a live wrong number.** `schedule_risk._network` is FS-only, lag-free and
calendar-free — checked rather than assumed, the module contains zero occurrences of "calendar" — and
it converts a duration to a date with `start + timedelta(days=round(days))`: *calendar* days. The CPM
beside it reports *working*-day dates. On the test fixture, a five-link chain of 20-day activities:

```
ours     P80  2026-06-22   (calendar days)
vendored P80  2026-07-30   (working days on a real calendar)
                38 days apart
```

Ours is the optimistic one. A P80 that counts Saturdays is not conservative, it is a different
question's answer — and both currently render in the same portal. Retiring `/schedule/risk` is a
user-facing removal and is filed as a decision rather than done unasked.

Two things the vendored engine reports that ours cannot: **`confidence_in_deterministic`** — on that
fixture the programme date had a **9% chance** — and **`duration_sensitivity`** per activity, the
correlation between an activity's sampled duration and the finish. Criticality says how *often* an
activity sat on the critical path; sensitivity says whether its duration actually *moves* the date.

### The fixtures were measuring a schedule nobody described

Chasing why every percentile came back identical turned up something worse than the bug:
`schedule_engine._duration_days` reads `data["duration"]`, and **four of this ring's test fixtures said
`duration_days`** — a key nothing reads, so every activity fell through to a 1-day default. The tell
was in plain sight and I had not chased it: `test_schedule_health` reported *"CPLI of 1.000 on a 3-day
critical path"* for activities of 5, 10 and 15 days.

Nothing failed, because those assertions are about structure. `test_schedule_locations` and
`test_schedule_takt` were unaffected — their adapters read the record directly and accept both keys —
so the genuinely weakened pair were `health` and `progress`, now fixed and each carrying a guard that
asserts the durations arrived: the health suite now requires a **30-day** critical path, and progress
requires the 3-day slip that only a real 5-day task can produce.

19 of 21 vendored modules reachable; 2 remain.

## v0.3.958 (2026-08-14) — R45: schedule progress against a baseline, and a fifth misclassification

`GET /projects/{pid}/schedule/progress-report` — BEI, finish variance and slippage of the schedule
against a captured baseline, with a client method and a card in the Schedule panel.

**The R45 table called this an overlap with `progress_rollup.py`. It is not one, and the difference
matters on a dashboard.** `progress_rollup` measures the **building**: percent complete from as-built
element presence, keyed by GlobalId, by class / discipline / level, by count and by value.
`core/progress.py` measures the **schedule**: how activities stand against their baseline dates. A
tower can be 60% erected and four weeks late. They share the word "progress" and nothing else — the
fifth entry in that table classified by name rather than capability, and the first caught *before*
being acted on, by reading both modules.

It also proves the `compare` blocker is specific, not general: **progress needs only dates**, which
`schedule_baselines._snapshot` stores, so it ships. `compare` needs predecessors, which the snapshot
does not have, so it stays blocked.

Two engine judgements preserved deliberately, both of the kind that get "simplified" into a wrong
answer:

- **BEI is `null` when nothing was due — never `1.0`.** An empty ratio is no information; reporting it
  as 1.0 puts a green tile on the dashboard of a project that has not started.
- **`behind` is broader than DCMA check 11.** An activity that was due to start and never did counts
  as behind, though check 11 only looks at finishes. It is the more urgent problem.

A project with **no baseline is refused**, not measured against its own current dates — that would
report every activity perfectly on programme.

**One defect caught by running it rather than by types:** the first draft returned
`report.worst_slippage` under a key named `worst_slippage_days`. That property returns an
`ActivityProgress` dataclass, not a number, so the route would have serialised a whole object or 500'd
— invisible to a typecheck, since the adapter returns `dict[str, Any]`. The test now asserts the whole
result survives `json.dumps`, and the value ships as both the days and the activity that set them.

18 of 21 vendored modules reachable; 3 remain.

## v0.3.957 (2026-08-14) — ruff, which I never ran locally

The API gate had been red since v0.3.952 and it was never a test. **`ruff check` — three `I001`
import-order errors**, all mine, all from inserting `import logging` with a blank line after it and
splitting the stdlib import group in two.

I ran the web lint before every push in this run and never once ran ruff, so five releases went out
with a lint failure I could have caught in four seconds. The command CI uses is in the
security-monitoring skill and in `ci.yml`:

```
cd services/api && python -m ruff check src/ ../data/src/
```

`--fix` resolved all three; the only changes are import blocks, verified by reading the diff — nothing
semantic moved. All four adapter suites, `test_reachable`, `test_route_reachability`,
`test_vendor_reachable` and `test_route_order` re-run green afterwards.

CodeQL is back to **0 open alerts** after v0.3.956, and the web job has been green since v0.3.955, so
this should be the last red on the run.

## v0.3.956 (2026-08-14) — CodeQL: the engine's own message was being relayed to callers

Two new `py/stack-trace-exposure` alerts (medium) appeared after v0.3.952–953, both mine:
`schedule_locations.flowline` and `schedule_takt.takt` returned `_unavailable(str(exc), …)` when the
vendored engine raised, so an engine-authored message reached the HTTP response.

The messages happen to be curated domain text today (*"duplicate location id 'L1'"*), which is the
argument for dismissing it — and it is a bad argument, because it is a claim about every message the
vendored engine will ever raise, in a tree that re-syncs from upstream. **CodeQL is right and the fix
is three lines**: the engine's text goes to `logging.warning`, the caller gets a stable domain
sentence. The repo has 34 documented dismissals of a different rule where direct proof was available;
there is none here, so this is fixed rather than dismissed.

Both adapters' refusal paths — the ones users actually hit, like "only one location" or "no crew caps"
— are unchanged, because those messages are written here and never came from an exception.

## v0.3.955 (2026-08-14) — the four R45 methods reach a screen, after three more gates said they had not

v0.3.952–954 shipped four scheduling engines behind four routes and I called that done. Three separate
gates disagreed, in sequence, each seeing one hop further out than the last:

| Gate | Question | Verdict |
|---|---|---|
| `test_vendor_reachable` | is the vendored **module** reached? | fired twice |
| `test_reachable` | is the module behind a **route**? | caught `schedule_health` |
| `test_route_reachability` | does a **client method** call the route? | caught `flowline`, `takt-train` |
| `clientCallers.test.ts` | does a **screen** call the client method? | caught all four |

Each layer only sees its own hop, and from the inside a module behind no route, a route no client
calls, and a client method no screen calls are all indistinguishable from a shipped feature. That is
why there are four gates and not one.

So this adds the missing halves: four typed client methods in `api/schedule.ts`, and
`portal/panels/scheduleMethods.ts` — a card each for DCMA quality, flowline, takt train and levelling,
mounted in the Schedule panel. Each runs **behind a button rather than on render**: three of them walk
the whole activity set, and a panel that fires four full-schedule computations every time it opens is
a panel people learn to avoid.

**The rendering rule is shared by all four: read `available` before reading any number.** Every one of
these engines can be asked something it cannot answer — no locations, a logic loop, no crew caps — and
every one returns `available: false` with a reason. Rendering the zero instead is how "we could not
measure" becomes "this is terrible" on somebody's screen.

Two of the four — `/schedule/health` and `/schedule/level` — passed `test_route_reachability` only
because the words "health" and "level" appear elsewhere in the web source. That is the gate's own
documented blind spot, and they were as uncalled as the two it caught, so all four got client callers
rather than the two that were flagged.

## v0.3.954 (2026-08-14) — R45: resource levelling, and `compare` turns out to be blocked on our own snapshot

`POST /projects/{pid}/schedule/level` — deterministic resource levelling by serial schedule generation.

It overlaps `resource_loading.level()` without replacing it, because they answer different questions.
Ours shifts non-critical work **inside its CPM float** to shave a peak and gives up when float runs
out. The vendored engine places every activity at the earliest instant its resources are genuinely
free, so it resolves conflicts the smoother can only report — and tells you what that cost.

**Determinism is the feature, not a nice property.** The problem is NP-hard, so this is a constructive
heuristic rather than an optimiser: it gives up optimality and buys *the same input always producing
the same answer*, which a planner can follow by hand. The priority key ends in the activity id
precisely so set and dict iteration order cannot leak into placement — an optimiser whose answer
changes between runs cannot be reviewed, approved, or defended in a claim.

**The horizon has no safe default and is therefore explicit.** On the test fixture — three parallel
carpentry tasks at 4 crews against a cap of 8 — `within_float` moves nothing and reports **5
unresolved**; `extend_finish` resolves them and moves the finish **7 days**. A job with liquidated
damages wants the first; one that has already blown its float wants the truth of the second. Reporting
"0 unresolved" for the first would be claiming a fix that never happened.

An **uncapped** trade is left unconstrained rather than capped at a guess, and a cap naming a trade
nobody works is refused rather than silently ignored.

### `compare` is blocked, and the blocker is ours

Wiring it was next; it cannot be. `compare()` diffs two *computed schedules* and needs both
**networks** — attributing a finish move means knowing which logic drove it. Our baseline snapshot
freezes `ref`, `name`, `start`, `finish` and `budget` per record id: **no predecessors, no durations.**
A network cannot be rebuilt from that.

That also explains our own `compute_variance` being date-only — not a weaker choice, just everything
the snapshot supports. Unblocking means capturing logic in the snapshot, which changes what every
stored baseline means, so it is filed as a decision rather than done unasked.

17 of 21 vendored modules now reachable — `levelling` pulled `resources` in with it. 4 remain.

## v0.3.953 (2026-08-14) — R45-SCHED-DEDUPE ②: takt was never implemented, only named

`GET /projects/{pid}/schedule/takt-train`. The R45 table filed `takt` as *"two implementations, same
`plan()`"* — pick the better one. Reading both says they are **two different methods**, and the
vendored docstring draws the line: line of balance lets every trade run at its own pace and shifts the
lines apart until nobody trespasses; **takt does the opposite** — every wagon occupies exactly one zone
for exactly one takt, and the crew sizes move so the durations do not.

`aec_api/takt.py` gives each trade its own rate (`Structure 5, Envelope 5, MEP 6, Interiors 8,
Finishes 6`). Trades running at *different* rates is the definition of line of balance. **So our "takt"
module is a line-of-balance engine wearing the wrong name, and real takt was missing entirely** — which
matters now that `locations.py` ships as `/schedule/flowline` and genuinely is line of balance.

What real takt gives: `(W + Z - 1)` takts for `W` wagons through `Z` zones, **always**, readable before
any of the work is estimated. That predictability is the product — a site where every trade hands over
Friday is one where the next can be told to arrive Monday and believed.

What it costs, reported rather than absorbed: **idle capacity**. A wagon with 3.2 crew-days inside a
5-day takt needs one crew and uses 64% of it. `utilisation` is per wagon per zone and unrounded,
because rounding up or averaging produces a plan that looks efficient and is not. Omitting `takt_days`
returns the shortest feasible rhythm *and the wagon that sets it* — shortening any other trade changes
nothing, so naming the constraint is the actionable half.

Work content is `duration × crew_size`, not duration: a 4-day task with one carpenter and a 4-day task
with six are the same duration and very different work, and takt is precisely the method that holds
durations fixed while crews move.

**Nothing was renamed or removed.** `takt.py` backs a shipped, user-facing panel; which of the three
naming options to take is a decision filed in the roadmap, not a cleanup to perform unasked.

15 of 21 vendored modules now reachable; 6 remain.

## v0.3.952 (2026-08-14) — R45-SCHED-REACH ①: the flowline, and the wrong answer it gave first

`GET /projects/{pid}/schedule/flowline` serves location-based (linear) scheduling — line of balance.
This was the **one** vendored module with no counterpart anywhere in the codebase, and the count only
got there after three wrong tables; see the previous entry.

CPM answers *"when can this activity start"*. It cannot answer *"where is each crew, and does anyone
get in anyone else's way"*, and the thing it **structurally** cannot express is **crew continuity**: a
forward pass gives every activity its earliest start, which is exactly what fragments a gang into
work-a-floor-then-wait. A subcontractor cannot price that. `continuity_cost_days` reports, per trade,
what keeping that crew whole costs in days — the number that decides whether the view is worth using.

It needs no new data: `schedule_activity` already carries `trade` (the crew that flows) and `location`
(the place it flows through).

**The defect worth recording is one I shipped into the first draft and caught by running it.** The
engine takes tasks in *handover* order. The adapter sorted them **alphabetically**, so Drywall preceded
Framing — and it produced a complete flowline: a duration, nine segments, per-trade continuity costs.
Nothing errored. The numbers were simply about a building nobody is going to build, and they were
wrong in a way no schema or type check could see: `{Framing: 4, Paint: 2}` where the truth is
`{Paint: 6}`.

Handover order is now derived from **when each trade actually starts** in the existing schedule. When
the records carry no dates to derive it from, the call is **refused** with that reason rather than
falling back to alphabetical, because a confident wrong flowline is worse than none. An explicit
`trade_order` overrides both — the sequence is a planner's call.

Locations sort naturally, so `Level 10` comes after `Level 2` rather than between `Level 1` and it —
the classic way a forty-storey flowline reads as a logic error when it is really a sort bug.

**The v0.3.949 ratchet fired for the second time**, again in the direction most allowlists never check:
wiring `locations` made `test_vendor_reachable` fail until the name left `UNREACHED`. 14 of 21 vendored
modules now reachable; 7 remain (2,793 lines), all of them overlaps rather than gaps.

## v0.3.951 (2026-08-14) — the DCMA assessment gets a route, because v0.3.950 shipped it without one

`GET /projects/{pid}/schedule/health` now serves the fourteen checks. It mirrors the existing
`/schedule/cpm` route exactly — same record source, same `require_role("viewer")` on a
`/projects/{pid}` path, so it lands inside the 735 routes `test_route_authz` already gates.

**This is a fix, and the way it was found is the point.** v0.3.950 added `schedule_health.py` with a
passing test suite and no route. I noticed, said so, and called it deliberate scope — *"reachable from
Python but not over the API."* The repo's own `test_reachable.py` disagreed and turned the API gate
red:

> These modules cannot be reached from any route, MCP tool or entry point. **A tested module behind no
> route looks exactly like a shipped feature from the outside.**

That gate exists because across v0.3.701–710, seven of eleven things built shipped with no route —
fully tested, CI-green, impossible to call. So while building a reachability ratchet for the vendored
engine, I created exactly the defect it describes one level up, and the older gate caught the newer
one. The fix is the route, not an exemption.

## v0.3.950 (2026-08-14) — R45-SCHED-REACH ①: DCMA 14-point, reachable at last

`massingplan/core/health.py` has implemented the Defense Contract Management Agency's fourteen
schedule-quality checks since the `d1e4bf16` sync — 634 lines of the closest thing the industry has to
a shared definition of *"is this schedule trustworthy?"* — and **nothing in this application could
call it.** Checked first, not assumed: no DCMA implementation existed anywhere outside the vendored
tree, so this is pure gain rather than a second implementation.

`aec_api/schedule_health.py` is the adapter, and it is thin on purpose. The dependency runs one way:
we convert our records into engine types, never the reverse, because `massingplan.core` is stdlib-only
*by contract*. That contract is the same one whose other half — hardening untrusted XML at the
application layer — was quietly deleted in the very sync that shipped this module. It only works if
both sides keep it.

**Most of the adapter is deciding what a score is allowed to claim.** Three states, and neither of the
first two is a grade of F:

- **No activities** → unavailable. An unplanned project is not a failing one, and returning `F` for
  one produces a number that reads as a finding.
- **A cyclic network** → unavailable, with the cycle. No dates were computed, so every check would be
  scoring absent data; grading it would be grading a crash.
- **Assessed** → the engine's report verbatim.

`grade` and `score` come back `None` in the first two, never `"F"` and `0` — a zero meaning "we did
not measure" is indistinguishable from a zero meaning "this is terrible", and only one of those should
ruin somebody's afternoon.

The engine's own honesty rule is asserted rather than trusted: skipped checks are excluded from the
denominator, so a clean schedule scores **100 over 10 runnable checks, not 71 over 14**. The four
skipped (9, 10, 11, 14) need baselines, actuals or resources; those arguments stay optional, because
passing empty stand-ins to make the checks "run" would convert an honest gap into a passed check.

The test carries the twin that matters — a schedule with dangling logic must come back **failing**, or
every other assertion is satisfied by an adapter that returns a canned grade A. It also asserts the
optional arguments are wired rather than accepted-and-dropped, by watching checks 10 and 14 move from
*skipped* to *run*.

**The v0.3.949 ratchet earned its keep on its first real use.** Wiring `health` made
`test_vendor_reachable` fail — *"these are now reachable, delete them from UNREACHED: health"* — which
is exactly the direction most allowlists never check. 13 of 21 vendored modules now reachable; 8
(3,270 lines) remain, filed as R45.

## v0.3.949 (2026-08-14) — the vendored engine re-synced, the guard it removed restored, and the check that missed both

### The sync, and the regression it carried

`massingplan` was re-synced from pin `b703dca4` to `d1e4bf16`: two new core modules (`takt`,
`lastplanner`) and seven deepened. `test_massingplan_vendor` is green — 22 files, digest
`1904999dd527f385`, still stdlib-only, nobody forked a file.

The same change also deleted the defusedxml hardening from `aec_api/schedule_import.py`. That was
**not** a design decision. The vendored `mspdi.py` still says, unchanged at the new pin: *"core is
pure stdlib by contract so the application layer is where an untrusted upload gets hardened."*
Upstream still delegates to us; our half had been removed, so the two halves no longer met.

It was exploitable, and confirmed by a failing test rather than by reading the diff:

```
FAIL  an MSPDI upload carrying billion laughs is refused   it was ACCEPTED
```

The deletion was 33 lines removed and **0 added**, so restoring from `HEAD` lost nothing the sync had
written. `test_mspdi_xxe` is 5/5 again, including the twin proving the vendored file was not forked to
get there. The re-synced import is a genuine upgrade and is kept — the two were never in tension.

### R45-VENDOR-REACH — faithfulness and usefulness are different claims

`test_massingplan_vendor` proves the copy is **faithful**. Every one of its checks passed while the
vendored tree grew by 880 lines that nothing in the API could call. A re-sync can double the engine
and the gate stays green, because it was never making that claim.

`test_vendor_reachable.py` makes it: **12 of 21 vendored modules are reachable; 9 (3,904 lines) are
not.** The number is transitive, and that is the point — a direct-import grep reports 12 unreached,
but three of those (`cpm`, `progress_logic`, `units`) are pulled in by `schedule.py` and run on every
CPM calculation. A grep-based gate would have sent someone to "wire" code that was already
load-bearing.

The allowlist ratchets in **both** directions: a module that becomes unreachable without being
recorded fails, and a recorded module that gets wired fails until it is removed from the list. Both
are mutation-checked. A one-directional check would let the number grow silently, which is the exact
failure being fixed.

Filed as R45 in the roadmap, split deliberately: five of the nine have no counterpart in `aec_api`
and are additive; the other four already have ours beside them — `takt.plan()` is currently defined in
**both** trees — so those are de-duplication decisions, not adapters.

## v0.3.948 (2026-08-14) — R24-CHARTS-GRAMMAR ②: one tick style, one legend, one currency

The no-data rule shipped first because it was costing something. These three are the rest of the
audit's finding 15, and none of them was cosmetic once measured.

**Ticks.** Three charts hand-rolled the same `for (k = 0; k <= 4)` gridline loop, and the copies had
already diverged: `lineChart` labelled `max − (k/4)(max − min)` while `groupedBar` and `waterfall`
labelled `max − (k/4)·max`, which is a different axis whenever the minimum is not zero. Meanwhile
**`stackedBar` drew no gridlines at all** — just a zero rule — so a cash-flow chart and a budget
chart sitting in the same panel were being read against different furniture. There is now one
`yGrid`, and a source scan that fails on a local gridline loop.

**Legend.** Four hand-rolled copies of the same magic coordinates, consistent today by coincidence.
One `legendRow`. The donut keeps the one legitimate position difference — under the ring, which has
no plot to sit above — and still goes through the helper, so the swatch, size and spacing cannot
drift from the other eight.

**Currency — the one with a real defect behind it.** The count was **22 declarations across six
behaviours**, not the 18 a first grep suggested; the gate enumerated the population and the grep had
not. Ten of them wrote `` `$${Math.round(n).toLocaleString()}` ``, which renders a loss as
**`$-1,000`**, with the currency mark on the wrong side of the minus. Three sites had already
noticed and written `(n < 0 ? "−$" : "$")` locally, so the same panel set disagreed with itself about
how a loss looks, and which spelling you got depended on which file you were in.
`viewer/inspectorTabs.ts` used `Intl` currency formatting *and* mapped a non-finite value to **`$0`** —
an absent number rendering as a plausible zero, which is the failure the vitals strip and the run
diff both exist to prevent. `proforma/format.ts` **exported** a competing implementation. All 22 now
import `usd` from `ui/charts.ts`, and the gate bans re-declaring one.

**And one of the 22 was not a money formatter at all.** The stormwater card's `usd` emitted no `$`
because it formats cubic feet and square feet. Converting it would have put a currency mark on a
detention volume. That is why `qty` exists, and why the rule bans *declaring* a formatter rather than
banning the name — the name was the defect there, and a rule chasing only the name would have made
the output wrong in order to make the label right.

Charts also gain `unit: "money" | "percent" | "count"`, which says what the numbers **are** rather
than making every caller remember a formatter. An explicit `fmt` still wins.

## v0.3.947 (2026-08-14) — R24-RUNS-INBOX phase 1, and the shell budget that caught v0.3.946

### The run history, and a premise that was half wrong

The R24 audit's finding 05 is *"analyses are modals, so they have no history"*, and the roadmap
recorded the state as **"no runs concept in the web app"**. That premise was half wrong, and the wrong
half is the expensive one to assume: `models.py:Job` already stores every field a run needs — `params`
(inputs), `actor` (who), `created_at`/`finished_at` (when), `result` (the artifact) — and
`routers/jobs.py` has served them for a long time. There was never a missing table.

So the item splits, and only the cheap half ships here. **History and comparison** is pure computation
over data the server already returns: `apps/web/src/ui/runs.ts` groups runs by kind, newest first, and
diffs each against the previous *comparable* run; `apps/web/src/ui/runsInbox.ts` renders it. Reachable
from the job tray's footer and from ⌘K. **Routing clash, IDS, cost and energy through the queue** —
the change that would actually give those four analyses rows here — is four call sites and their
handlers, and it stays open.

Two decisions the module exists to get right, both mutation-checked:

- **A metric present in one run and absent in the other has a `null` delta, never zero.** Absence-as-zero
  turns a detector that simply stopped reporting `count` into a confident, precise, entirely invented
  −412 — worse than no number, because it reads as a finding.
- **A failed run is never a baseline**, though it is still listed. A run with no result is not a run
  whose every metric fell to zero, and using one as the comparison point fills the screen with `—` in
  a way that looks like the analysis broke rather than one attempt.

Because most projects have never queued anything, the empty state names *which half is missing* rather
than implying the feature is broken.

### The budget caught v0.3.946 on the public build

v0.3.946 turned the Pages deploy red: the public shell measured **320.5 KB against a 320 KB budget**.
Half a kilobyte, and the gate was right to stop it — that budget is derived, not observed. It has to
stay consistent with `DEMO_MAX_BYTES` in `services/api/test_file_sizes.py`, because the two ratchet the
same artefact from opposite ends and an inconsistent pair is unsatisfiable. Raising it to make room
would have quietly broken that relationship.

So the eager path was trimmed instead, which is what the failure message asks for. Four things that are
only ever reached by a click now load on the click: the Report Center, the run history, the element
card, and the toolbar's tool table (which loads with the viewer chunk, where it already belonged).
Public shell **322.0 → 312.0 KB**, with 8 KB of headroom; the default build is 194.0 KB against 220.

## v0.3.946 (2026-08-14) — R24-CMDK-VERBS: two of the palette's six sections could not be filled

`R24-CMDK-GROUPS` (v0.3.780) gave the command palette its sections, and `GROUP_ORDER` has named
**Do · Records · Elements · Reports · Modules · Go to** ever since. Only three of those six could ever
contain anything: `main.ts` registered workspaces, six hardcoded actions, and 130-odd modules.
**Elements and Reports were headings with no possible contents** — declared, ordered, and unreachable.

The four missing providers are now in `apps/web/src/ui/paletteProviders.ts`, all pure and all injected,
so none of them imports the viewer, the API client or the DOM:

- **Authoring verbs** do not reimplement Move/Copy/Rotate — they find the toolbar button by its `title`
  and click it. `viewer/toolbarLayout.ts` already keys the tool table on that exact string and already
  fails when an installed button is missing from it, so the palette inherits that gate: a retitled
  button cannot silently lose its palette row. A verb whose button is not installed is **omitted, not
  disabled** — before a model loads, every authoring row would otherwise look available and do nothing.
- **Elements** is a GlobalId lookup plus an IFC-class list, and deliberately not a name search. There
  is no server-side element text search, and pulling every element into the browser to filter would
  violate "never parse the model in the browser" in order to answer the question badly.
- **Reports** come from the server's own catalog as static rows, so they go through ranking and
  recency. Choosing one opens the Report Center *scrolled to and highlighting that row*, rather than
  dropping the reader at the top of a 56-row modal to re-find what they just named.
- **Ask** is the fallback, passed separately from the results so it is appended *after* the per-section
  cap. A fallback the cap can delete is not a fallback: it would vanish exactly when a query matched
  twelve things badly, which is when it is most useful.

**Fixed on the way, and found by reading rather than by testing:** the palette did
`items = items.concat(extra)` when async results arrived, appending them to an already-grouped list. A
record hit — group *Records*, which sorts second — landed *below* Modules and Go to, under a **second**
`RECORDS` heading. The grouping was a property of the first paint only, and the section the async
provider exists to fill was the one it could never reach; adding Elements and Reports would have made
it three duplicate headings instead of one. `mergeResults` re-sorts on group rank alone — `Array#sort`
is stable, so each side keeps its own ranking inside its section, and re-scoring would have discarded
the server's relevance order, which the palette cannot reconstruct.

The regression test restores the old `concat` and asserts the ordering flips, so the fix cannot be
undone by a future edit that merely looks tidier.

## v0.3.945 (2026-08-14) — R24-TERMS: a building storey is called a storey

Diagnosis #17 of the R24 audit is "three vocabularies collide". Measured before touching anything,
and the clearest instance was **a single control disagreeing with itself**: in `budget.ts` the button
read *"QTO by floor"*, its own tooltip two lines below read *"by storey"*, and its own table header
read *"Storey"*. One feature, three lines, two words for one thing.

**This is a consistency fix, not a naming decision** — which is the only reason it was safe to make
without asking. `storey` is already canonical everywhere that carries meaning: the API returns a
`storey` field per element, QUERY-DSL filters on `storey=L3`, and both rendered table headers say
Storey. Three chrome strings were the outliers. Choosing a *new* canonical term would have been the
user's call; the sibling question ROOM-NAMING was settled with them, and this one deliberately did not
follow that path because nothing needed settling.

`apps/web/src/shell/storeyVocabulary.test.ts` holds it, and **the exceptions matter more than the
rule**: only phrasings meaning "per building storey" are refused. *Gross floor area* is the standard
term and `operations.ts` uses it correctly for EUI; *floor plan* is what the drawing is called. A
blanket ban on the word would have been a worse error than the inconsistency it replaced, and would
have flagged two correct strings — so the twin asserts those stay legal.

**The test immediately found something the hand-scan missed.** After fixing the two strings I had
grepped for, it failed on a third — `"Rooms per floor"` in the viewer's add-rooms prompt. My
verification grep checked *by floor* and *each floor* but not *per floor*, which my own rule bans.
The gate was stricter than the search that produced it, which is the entire argument for writing the
rule as a test rather than fixing the instances you happen to see.

## v0.3.944 (2026-08-14) — R43-PLAN-DRIFT closed: the cadence, and why it does not fail a build

The remaining half needed a decision rather than code: **how often to ask whether upstream has
moved.** The answer is **weekly, non-blocking, into a single reused issue** — and the reasoning is
the deliverable, because each part of it is easy to get wrong in a way that looks like rigour.

**It notifies, it does not block.** Upstream moving is not a defect in this tree. A red build caused
by someone else's commit cannot be fixed by editing our code, and a red nobody can act on is the
fastest way to teach a team that red means nothing. The companion check — *did we edit the vendored
copy?* — **does** block, because that one is our defect, and it runs offline on every CI run.
`test_vendor_drift.py` asserts the exit code stays 0 even when drifted, because "make it fail the
build" is the obvious-looking hardening and it is wrong here.

**Weekly, not daily.** The pin moves a few times a month. A daily job is noise, and noise is how a
notification stops being read.

**One issue, reopened and commented — and closed again when the pin catches up.** Fifty-two issues
saying the same thing is not a signal; neither is an issue that is only ever opened, which becomes
permanent furniture.

### UNKNOWN is a first-class verdict, and that is the point

If the upstream query fails — offline, rate-limited, a renamed branch, a token without access — the
honest answer is **"could not tell"**, never "no drift". A two-valued verdict cannot express that,
so `check_drift` returns three values and the workflow renders UNKNOWN as loudly as DRIFTED.
Collapsing them is how a job that has quietly stopped working posts good news every Monday forever —
the failure this repo has met more often than any other, under a different name each time.

`test_vendor_drift.py` proves all three verdicts are reachable (a vacuity guard: every individual
assertion would still pass on a function that could only answer one thing), that a failed query
reports UNKNOWN with its reason attached, and that a short pin like the historical `155640a7` is
refused rather than truncated into an answer.

### One parse, two callers

`read_pin` / `read_digest` live in `vendor_drift.py` and `test_massingplan_vendor.py` now imports
them instead of carrying its own regex. Two independent parses of the same table could disagree about
which commit VENDOR.md names, and **neither would notice**, because each would be self-consistent.

## v0.3.943 (2026-08-13) — a vendored copy that can prove it was not edited

### R43-PLAN-DRIFT — the half that was never blocked

The item is filed as blocked on **cadence**: how often to ask whether upstream has moved. That is a
real open question and this does not answer it. It answers the other half — *has anyone edited the
copy here?* — which needs no schedule, no network and no decision, only the recipe `VENDOR.md`
already writes down.

`services/api/test_massingplan_vendor.py` executes that recipe: a content digest over
`massingplan/core/`, CRLF-normalised, compared against the value **parsed from VENDOR.md** rather
than a second copy living in the test. A hardcoded expectation would become a second source of truth,
and the first thing a re-sync would do is make the two disagree while the test stayed green against
its own stale copy. It also holds the stdlib-only contract the whole adoption rests on.

Mutation-checked three ways, each failing by name: a local edit to a vendored file, a re-sync that
did not update the digest, and a third-party import into `core` — the last caught independently by
two different checks.

**VENDOR.md earned this.** It records the recipe because the *previous* digest turned out to be
unreproducible by anything anyone could try, and its own conclusion was that *"a recorded
verification value nobody can recompute is not a verification, it is a decoration."* A recipe stated
in prose and never executed is one revision away from being decoration again.

**The first attempt to reproduce the digest failed, and the measurement was the error.** Hashing the
whole vendored directory gave a mismatch; the recipe says `core/`, and the top-level `__init__.py` is
a three-line shim of *ours* that is not upstream's. Over `core/` alone it reproduces exactly. The test
now asserts that shim stays outside the digest, because widening the recipe is the obvious wrong
correction a mismatch invites.

### The pin in the roadmap was stale — the item's own failure mode

The entry named pin `155640a7`. VENDOR.md records the tree moved to `b703dca4` on 2026-08-11 and says
so in as many words: *"was `155640a7`, 2026-08-10"*. A pin copied into prose drifted from the pin in
the tree and nothing noticed — which is precisely the class of drift this item exists to catch.

### Also

`check()` in the new gate splits its detail into `why` (printed only on failure) and `note` (only on
success). The shared helper prints one string either way, which puts the failure explanation on a
PASS line — a log contradicting its own verdict, and a reader skimming for trouble finds the
scariest sentence sitting under the word PASS.

## v0.3.942 (2026-08-13) — record attachments stream, and a bulk route nothing was checking

### R39-UPLOAD-CAP-APP — bucket (a) closed

`mod_engine.add_attachment` takes the same widening as `docmanager.upload`: **either** `data` or
`chunks`, exactly one required, with `size` from `put_stream`'s written count. Both routes now stream
— the single attachment and the bulk upload, which exists precisely because a superintendent dumps a
batch of site photos at once, so holding the whole batch in memory was the wrong shape for the one
case it was built for. The three `contracts.py` callers hold real bytes and are untouched.

### The test gap that mutation-checking found

Stubbing the write so **nothing was stored** left `test_evidence_gate` green. It asserts `count == 3`
and three attachment rows — and a row is created whether or not the bytes arrive. The bulk route had
no content assertion anywhere in the suite.

`test_attachments.py` now uploads three payloads of **different lengths** and checks each one's bytes
round-trip and each recorded `size`, so a batch that stores nothing, or stores one file three times,
fails on content and on size rather than passing a row count.

**What that test explicitly does not prove, recorded because the obvious claim is wrong.** It does
not guard the route's `lambda f=f:` late-binding capture. Removing `f=f` leaves the test green — and
correctly so: the route awaits each `run_in_threadpool` *inside* the loop, so every lambda runs before
the loop advances and the classic late-binding defect cannot occur. The binding is harmless insurance,
not load-bearing. A comment claiming otherwise would be a confident wrong answer about our own
coverage, which is the failure this release's other half is about.

### The published classification was wrong, in both directions

v0.3.940 said bucket (a) was **five** sites and named `authoring.py`'s content-shelf asset. It is
**three**. That route never stores the upload — it hands the buffer to `content.parse_mesh` and keeps
only the resulting verts and faces, so it belongs in (b). The error came from reading the two lines
*after* `await file.read()` — a filename suffix and a category lookup, which read like the preamble to
a store — instead of following `data` to its single use. **Classify an upload by where its bytes are
used, not by what surrounds the read.**

And `bim.py`'s BCF topic attachment is a fourth store site absent from the list on purpose: R41-UPLOAD-WARK
converted it in v0.3.876, so it has no `await file.read()` left to find. A population derived from
"sites that still read the whole body" correctly excludes what is already fixed — but it is therefore
not "every store site", and reading it as one undercounts the surface.

## v0.3.941 (2026-08-13) — the suite finally runs on the bundler that ships

### R41-BUNDLER-SPLIT — one Vite, and it is the one that builds the app

The app was **built** with Vite 8 / rolldown and **tested** under Vite 6 / rollup. Not merely a
narrower environment — a *different implementation*, able to agree with you about code the shipping
bundler treats differently.

**The filed cause was wrong, and that is what kept it parked.** The entry said vitest depends on
vite `^6`. It does not: vitest declares `^6.0.0 || ^7.0.0 || ^8.0.0` in both `dependencies` and
`peerDependencies`, and 4.1.10 is current. Checked against the lockfile, **no consumer requires `^6`
exclusively**. So this was never a dependency decision awaiting sign-off; the root simply resolved to
6.4.3 because that satisfied every range and nothing forced it to move.

**The dedupe alone did not work, and the failure mode is worth knowing.** An `overrides` entry looked
like the fix, and npm *registered* it — `npm ls` printed `vite@8.1.5 overridden` — while leaving the
hoisted copy at 6.4.3 and marking the tree `invalid`. Neither `npm install` nor
`npm install --package-lock-only` re-resolved it, and deleting `node_modules/vite` did not either,
because the lockfile still pinned 6.4.3 and `npm install` honours the lock. **A registered override
over an unchanged lock is a config that reports success while the tree disagrees** — believing the
config instead of `npm ls` would have left the split in place and called it closed.

What worked: declare `vite` as a root devDependency at the same exact pin `apps/web` already uses.
One line, no new package. The tree then dedupes to a single `vite@8.1.5` and
`apps/web/node_modules/vite` disappears.

**Result:** 1,576 tests pass under Vite 8 / rolldown, and faster (26.5 s vs 32.6 s). Typecheck, lint
and the production build are unchanged, and the precache output is byte-identical at 902.20 KiB — the
coverage was bought without moving what ships.

**One quiet consequence, caught rather than shipped:** the added root devDependency pushed
`package-lock.json`'s version key from line 23 to line 24. The release recipe named "line 23" in
prose. Nothing broke, because `versionConsistency.test.ts` reads
`packages["apps/web"].version` structurally — the roadmap now names the key instead of the line,
since the line number was the only part that could rot.

### R39-UPLOAD-CAP-APP — the first of the five storage sites

`docmanager.upload` now accepts **either** `data` (bytes in hand) or `chunks` (an iterable from
`storage.upload_chunks`), and the documents route passes the latter. Documents are the largest thing
an ordinary user uploads here, and `await file.read()` was copying a file Starlette had already
spooled to disk.

Two details that are not incidental:

- **Exactly one of the two is required** — passing both is ambiguous about what was stored, passing
  neither would write a zero-byte document and index it as real. Refused rather than defaulted.
- **`size` now comes from `put_stream`'s return value**, the count actually written, rather than
  `len(data)`. The index cannot record a size the stored object does not have.

The other four callers hold real bytes and still pass `data`, which is why this is a widening rather
than a signature change.

## v0.3.940 (2026-08-13) — two uploads that copied a file that was already on disk

### R39-UPLOAD-CAP-APP — the 34 sites classified, and the two nobody had counted

The roadmap's instruction was *"classify the 34 rather than convert them — a count is not a work
list"*, and that was the right instruction: every one of those sites is the identical
`await file.read()` call, which is exactly why the count read as one work item. Reading each one
together with **what it does with the bytes** splits them three ways, and only the first is work:

- **stores the bytes** — `documents.py`, `modules.py` ×2, `authoring.py`. Five, not thirty-four.
  Converting these means widening the persisting function to take chunks, which `storage.put_stream`
  already supports.
- **hands the buffer to a parser** — point clouds, BCF zips, XLSX, PDF, IFC, the converters. Streaming
  these means changing the parsers: a different item with a different risk profile.
- **structurally small or already capped** — `properties.py` rejects oversize before parsing.

**Two sites were converted here, and they are the ones a count could never have surfaced**, because
they look like parser sites and behave like storage ones: `cost.py`'s DXF takeoff and `authoring.py`'s
raise-plan both read the entire upload and then **wrote it straight back out to a temp file**, purely
to hand a *path* to a parser. Starlette had already spooled that upload to disk, so each was a
disk-to-memory-to-disk copy of a file that existed the whole time — and a survey-sized DXF is exactly
where that costs something. This is the identical conversion `convert.py`'s RVT path already carried,
so it is a precedent being followed rather than a pattern being invented. `stream_to_path` writes
`.part` then renames, so a failed upload can no longer leave a truncated `.dxf` for the parser to
open.

Both routes have real upload tests that POST through the HTTP layer, and **mutation-checking proved
those tests reach the new code** rather than passing beside it: stubbing out the write makes the
takeoff route answer 400 "Not a readable DXF". Verifying that the test can *see* the change is the
step that separates a covered line from a covered claim.

## v0.3.939 (2026-08-13) — a test that reported failure while nothing had failed

### The suite's exit code depended on the console encoding

`test_procurement.py` passed every assertion it makes and then **died printing its success line**.
The arrow in `"rebar→BuildMart"` is U+2192; Windows' default console encoding is cp1252, which has no
such character. Exit code 1, zero failed assertions, and a traceback where the OK line should be.

Through `run_tests.py` it passed, because that runner sets `PYTHONUTF8=1` for its children. Run
directly — which is how anyone debugging a single test runs it — it reported failure while nothing had
failed. **A false red is worse than an annoyance: it sends someone to debug a passing test, and what
it teaches is to distrust the runner.**

**The same bug bit from the other side on the same day.** A gate written that morning put a U+2192 in
its *failure* detail. Every assertion passed, so nothing showed — until a mutation made it fail, and
instead of naming the unpinned action it raised `UnicodeEncodeError`. Exit code 1 either way, so the
mutation appeared to work; the message identifying the culprit was destroyed. Reading the output
rather than the exit code is the only reason it was caught.

Swept 67 test files, replacing such characters **inside `print()` calls only** — located by walking
the AST, not by a blind find-and-replace, so docstrings and comments are untouched.
`services/api/test_output_encoding.py` holds the line, and is deliberately narrow for the same
reason: a rule covering docstrings would flag its own prose, which is how a gate gets switched off.
It carries the twin too — asserting cp1252 punctuation (em dashes, curly quotes) stays *allowed*, so
nobody "fixes" characters that were never the problem.

### QTO-TRADE — buyout packages from the model reach a screen

The backend half was already done and the roadmap had not noticed: `procurement.normalize_qto_line`
speaks both dialects and takes the trade from the classification spine rather than a second mapping
table. What was missing was the screen. *Buyout packages* on the budget panel now feeds
`qtoByFloor`'s `by_discipline` lines — the exact `{ifc_class, count, unit, quantity, rate, amount}`
shape that used to yield zero packages — into the engine.

**Two empty states, rendered separately on purpose.** *No priced quantities* and *lines went in and
nothing came out* are different facts about a project, and one shared empty table for both is exactly
what would have reported "this project has nothing to buy out" about a fully-priced model.

The uncalled-method gate did its job on first contact: adding the caller failed the build with
`1 method(s) in UNCALLED now HAVE a caller: buyoutPackages`, naming the method and prescribing the
fix. That is the RATCHET-SET conversion — from a scalar ceiling with no floor to a committed set —
earning its keep in real use.

## v0.3.938 (2026-08-13) — supply-chain pins, and a citation that opens the document it cites

### HIGH-7 — every third-party GitHub Action pinned to a commit SHA

A workflow step runs code from another repository with access to this one, and a tag or branch ref is
mutable: whoever controls the upstream repo can repoint it, and the next CI run executes the new
code. Thirteen third-party references across eight actions are now pinned to 40-hex commit SHAs, each
carrying a trailing comment naming the version it pins so it can still be bumped deliberately.

The worst was `dtolnay/rust-toolchain@stable` — not a tag but a **branch**, used three times, which
moves on every upstream push by design.

**Scope is stated rather than assumed.** `actions/*` and `github/codeql-action/*` stay on version
tags: they are published by GitHub itself, from the same trust root that runs the workflow, so
pinning them defends against a compromise that would already own the runner. Pinning all 33 would
triple the bump burden for no threat-model gain, and a gate whose upkeep outweighs its value gets
switched off. `services/api/test_actions_pinned.py` enforces the rule so a ninth action cannot be
added unpinned.

**The first enumeration of this was wrong, and how it was wrong is the reusable part.** A grep
reported 46 references including `actions/setup-example@v1` — a **commented-out line** in CodeQL's
starter template, naming an action that does not exist. The gate therefore parses the workflows as
YAML: a parser cannot see a comment at all. That is the fifth time a source-scanning check here has
read the prose describing it rather than the code.

Also fixed: `db-migrations.yml` used `actions/checkout@v5` while the other thirteen call sites used
`@v7`.

### R31-CITE-HIGHLIGHT — the citation is now a control

`doc_text.answer()` has emitted seven fields per citation since v0.3.877. Both panels that render
citations declared their own inline `{ page, snippet }` and dropped the other five — including
`doc_id` and `openable`, which are exactly the two the "make the citation a control" work needs.

The cost of that is the point. With those fields dropped the feature looked *blocked on a backend
change that had already shipped*: a comment in `aiassist.ts` said "there is nothing to open" and the
roadmap carried the item as blocked, while the server had been sending the answer the whole time. **A
narrow client type does not merely hide a field — it produces confident, documented, wrong claims
about what the system can do.** `citationContract.test.ts` now asserts the shared `DocCitation` type
against `doc_text.py` by set equality in both directions.

Clicking a citation fetches its source PDF and opens it. Fetched as a blob rather than linked,
because auth is a bearer header and a plain link arrives unauthenticated. Citations whose ingest was
text-only stay plain text — the server says so via `openable`, and a control that always 404s is
worse than no control.

**Not done, so nobody rediscovers it:** the in-page highlight box. `citeLocate.ts` can find a passage
but needs a `PageWords` supplier the viewer does not yet expose. Opening the document is the
reachable half.

### SCALE-SEAM ⑪ — doc QA moves out of client.ts

Adding that one method took `client.ts` from 3,703 to 3,715 and **failed the size ratchet**, which is
the ratchet working exactly as `contracts.ts` documented when it hit the same wall. The response was
not to raise the pin but to ask whether the method belonged in a domain module: the three `review*`
methods were already a cluster sharing one route prefix and one helper. They moved to `docqa.ts` with
that helper, and the pin moves **down**, 3,703 → 3,690.

One hazard worth recording from the extraction: the mixin was first written constraining on an
interface exposing the `protected` helper. A mixin constraint cannot see a protected member, so the
inferred base silently collapsed and every *other* mixin's methods vanished from `ApiClient` — which
surfaced as `editIfc` not existing, a symptom nowhere near its cause. Moving the helper into the
mixin removed the cross-mixin reach entirely.

### Verified false: Aikido MED-5 and MED-6

Both were checked against the code rather than the report. **MED-6 (SSRF)** — the one operator-settable
URL already routes through `safe_urlopen`, whose `_ValidatingRedirectHandler` re-validates *every*
redirect hop; the remaining call sites are fixed-host with the injected value landing after the first
`/`, where it cannot reach the authority. **MED-5 (file inclusion)** — `storage.py` resolves first and
tests containment afterwards, and validates keys at the interface so both backends refuse the same
set. Neither needed a change. That brings the scan to 14 findings examined, 11 misreported.

## v0.3.937 (2026-08-13) — the changelog rule becomes a test, because as prose it failed twice

This file stopped at v0.3.881 while **fifty-two releases shipped**, twenty-two of them tagged. Before
that, v0.3.808 shipped with the same lapse. Both were noticed late and reconstructed from release
commits — which in this repo carry real descriptions, so the reconstruction is honest, but it is
strictly thinner than an entry written while the reasoning was still in someone's head. The
per-release *why* was never recoverable, and inventing it afterwards would have been worse than the
gap.

`services/api/test_changelog_current.py` now asserts that the version in `apps/web/package.json` —
the number that actually ships — is named here. It fires before the release, which is the moment the
fix is cheap.

Two decisions worth stating, because both are the difference between a gate that survives and one
that gets switched off:

- **It checks the current version only**, not every historical tag. A gate demanding entries for all
  900-odd releases would fail forever on the reconstructed range and be disabled within a day. A rule
  that is technically right and operationally impossible is not a rule.
- **It accepts a grouped range** (`## v0.3.934–936`) as well as an explicit version, because this
  repo legitimately batches a day's releases into one section. And it carries a twin asserting the
  matcher *rejects* a version that was never released — without it, "the version appears somewhere in
  the file" could pass for reasons having nothing to do with the release.

The twin caught something on its first run, and the something was this entry. Its sentinel started as
a hardcoded fake version, and the paragraph above originally quoted that fake version to explain what
the twin did — so the gate matched its own release notes and failed. The sentinel is now derived from
the shipping version's own prefix, which is both a harder test (it must discriminate inside the real
namespace, not merely across an unrelated one) and one nobody can accidentally write down. **Fourth
time this repo has shipped a source-scanning check that reads the prose describing it.**

**Also in this release, and the more useful lesson:** v0.3.936 broke `main`. Seven explanatory
comments added to `apps/web/src/portal/register/register.ts` took it from 2546 to 2553 lines and
tripped the per-file size ratchet. It was fixed by trimming the comments rather than raising the
ceiling — the direction of travel on that file is down. The pre-flight missed it because
**`register.ts` is a web file whose size ratchet is enforced by a Python test in `services/api`**;
typecheck, lint and the web vitest suite were all run, and all three were structurally blind to it.
Running the suite that owns the *gate* matters more than running the suite that owns the *language*.

## v0.3.934–936 (2026-08-13) — the Aikido list, worked by reading the code rather than the report

A 32-issue security scan arrived. Twelve findings were examined; **nine were misreported**. Two real
holes were closed, and four items would have had us edit code that was already correct.

### v0.3.934 — SEC-SCENARIO-AUTHZ: the guard existed and 6 of 8 routes never called it

`_can_read` had been in `routers/proforma.py` all along, called by **two** of the eight `{sid}`
routes. Share, update, clone, review, forecast and draw-package fetched by id and acted with no
ownership check. Not an unauthenticated hole — `/proforma` is in `_PROTECTED_PREFIXES`, so the global
middleware 401s anonymous callers and every route *looked* guarded. **A generic gate hiding a missing
specific one:** authentication was enforced, authorisation was not.

Worst was `share_scenario`, which took the *grantee* in a parameter named `user` and had **no
`current_user` dependency at all** — no notion of who was calling, so any authenticated user could
share any scenario with anyone.

Added `_can_write` (deliberately *not* `_can_read`: an LP with read access must not edit, clone,
approve or pull a draw package) and `_scenario_for(sid, …, write=…)` so a ninth route cannot be added
without answering the question. Scenarios carry draw packages and forecasts — this is money-adjacent.

### v0.3.935 — verify the gitleaks binary before executing it

`security.yml` curled a release tarball and ran it, unverified, in CI with repository access. Now
checked against a SHA-256 committed in the workflow — **hardcoded rather than fetched alongside the
tarball**, because a checksums file from the same origin is signed by nothing and moves with the
artefact. A committed digest fails even when the release asset is replaced. Plus a default-deny
`permissions` block in `codeql.yml` for jobs added later.

### v0.3.936 — one real XSS, three false positives

`register.ts` built `<option>` markup from `api.permitCities()` — a server response — with `c.id` and
`c.label` raw in `innerHTML`. Escaped. The other 24 `innerHTML` sites in that file were already safe.
`services/converter/Dockerfile` drops root (a CLI entrypoint, no port to trade). `apps/web/Dockerfile`
deliberately **not** changed: it is nginx on port 80, and going unprivileged moves the published port
— a deployment decision, not a code cleanup.

False: `document.write` (zero occurrences), `location.href` into a DOM sink (zero),
`fast-xml-builder` (not a dependency), and path traversal in `bim.py` (`storage.contained_path`
already resolves *then* tests containment, and explains why that order matters).

### Also in this range

Earlier the same day: massingcapture `classify/` + `probe/` vendored (v0.3.933), the MSPDI upload
hardened at **our** layer rather than by forking a vendored file, and massingplan re-synced to
`b703dca4` (v0.3.932).

**Still open and untouched:** HIGH-7, ~40 third-party GitHub Action references not pinned to commit
SHAs. Real, mechanical, and all-or-nothing across every CI entry point.

## v0.3.882–933 — fifty-two releases reconciled from the release commits

**This section is reconstructed, and it is thinner than the ones below it on purpose.** The changelog
stopped at v0.3.881 on 2026-08-07 and fifty-two releases shipped without an entry — 22 of them tagged —
until a documentation audit on 2026-08-13 found the gap. What follows is derived from the release
commits themselves, which in this repo carry a real description rather than "bump version". It is an
accurate index of *what shipped*; it is **not** the per-release reasoning the entries below carry,
because that reasoning was never written down and inventing it now would be worse than the gap.

Two tags carry no version-named commit and are recorded here rather than silently skipped:
**v0.3.924** is `b7d0c9b6` *"the ruff step and the CodeQL alert that v0.3.923 shipped red"*, and
**v0.3.931** is `2c4f478d` *"R43-CRUD-FRAGMENTS was not executable as written — rescoped before any
code"*.

### 882–886 (2026-08-07) — answers that outran their data, and a write behind a read gate

- **883** — "AI estimating is off" is not "0 line(s)". An unavailable feature was reporting an empty
  result, which reads as *"we looked and there is nothing"*.
- **886** — four reach callers rendered a confident answer the response did not support. Same shape as
  883, found four more times.
- **884** — SEC: `attach=1` was a **write** sitting behind a viewer gate; and a module shadowing the
  stdlib `code` was renamed.
- **885** — Band 1 emptied: SEC-PLUGIN-SANDBOX closed, `qaSection.ts` pinned.
- **882** — the two new roadmap items assigned to lanes.

### 887–909 (2026-08-08) — reach writes, the LOD 2025 read, and three red mains in one day

- **887 · 898** — QTO-TRADE: the buyout engine could always do this, but the two halves spoke different
  dialects. BOE-MAPPING-DEDUP then stopped the confidence units being a comment in two files.
- **890 · 891 · 894 · 895** — R41-REACH-WRITES 1–4: retiring a shared parameter without the PUT eating
  the standard; removing a discipline model now says when it will disable clash; a saved view can be
  deleted and the confirmation names it; the model-review gate — **approve is not a thing an API key
  can do**.
- **892 · 893** — SEC: `delete_view` claimed a success it had not achieved *and* crossed project
  boundaries; the module segment of the saved-view URL meant nothing.
- **899 · 901 · 902 · 903 · 904** — the LOD Spec 2025 read and its three items: the LOD band now comes
  from the **geometry**, not from how well an element is tagged; a verification that never says how
  accurate it was is an incomplete assertion; the target matrix was authorable and uncomparable.
- **905 · 906 · 907 · 908 · 909** — the R42 incremental-commit ring, opened on a premise that was wrong
  until the code was read. `/publish` accepted `reconvert` and nothing read it. R42-SESSION-MODEL: the
  model cache existed and the authoring loop could never hit it. **R42-UNDO withdrawn — undo exists, is
  wired, and has its own suite.**
- **888 · 889 · 900** — main was red three times in one day, and *reported green once*. Causes: a ruff
  I001 on a new import, and a streaming test writing to `/app`, a path that exists only on one machine.

### 910–922 (2026-08-09) — drawings return, and the canvas becomes one surface

- **913 · 914** — R36-DRAWINGS-RETURN: three of the item's four claims were already false, and the one
  real defect was invisible to its own test. It had been wired at 2 of ~10 crossings and called
  complete; the rule now lives at the event.
- **915 · 916** — gate what **ships**, not what happens to be installed; a sheet asking for an
  axonometric no longer draws a plan; the rail's sheet buttons were sending three parameters the route
  does not accept.
- **918 · 919 · 920** — R36-VIEWER-SUBAPP: the canvas is one surface at a time; cross-mode selection
  worked *by accident* and is now asserted; Specs ships, needing no backend work at all.
- **911 · 912** — R42-COMMIT-DELTA keeps the geometry already converted and **says when the model is
  behind**; alongside three silent reads, one wrong identity, and a cache serving the next version
  under this version's name.
- **910 · 917 · 921 · 922** — `⟳ Republish` and the AI plan's Apply had never worked (the body shape
  422s); `app.ts` 3,717 → 3,384 with the ratchet going down; `@types/three` was a minor behind `three`,
  so `tsc` described a different library; UX-VIEWED — `last_viewed_at` was stored, served, typed, and
  dropped on the floor.

### 923–933 (2026-08-10 → 08-13) — siblings vendored, money made exact, plans that explain themselves

- **926** — R43-ORG-OWNERSHIP: **bootstrap registration handed platform admin to a stranger.** The
  entry's stated premise was wrong and the audit found a real hole anyway.
- **925** — R43-CSRF-GET: no route changes state on a GET, and now nothing can add one quietly.
- **927** — money is `Decimal` end to end, so a display-rounded value can no longer become a stored
  total. R41-UPLOAD-WARK's premise turned out to be already false.
- **928 · 929 · 930** — R38-PLAN-TRANSFORM: the plan publishes the transform it used. R43-PLAN-EMPTY-AT-CUT:
  a blank plan now says **why** it is blank. The storey GlobalId was being served all along.
- **923 · 932 · 933** — massingplan's CPM engine vendored and the P6 import that read no relationships
  fixed; massingplan re-synced, where **the recorded content digest verified nothing**; massingcapture
  classify+probe vendored, hardening the MSPDI upload at our layer rather than upstream's.

## v0.3.878–881 — thirteen PRs land, and a ratchet that was quietly not one

### The reach ring: 131 → 117 uncalled client methods

Thirteen PRs merged in one batch. `UNCALLED_CEILING` — the count of client methods with a live
server route and no path to them in the product — fell from **131 to 117**, with one lane still to
land. Every step was measured by re-running the gate, never derived from what the wiring touched.

The sharpest find in the batch was not a count. **The finance period lock was enforced and its
control was unreachable**: every mutation dated into a closed month refused with a 409, while the
screen to see or reopen the lock had no path in the UI. A user hit refusals with nothing explaining
why and no way to act. That is a different severity from ordinary unreachable capability — an
unreachable *feature* is one nobody can use; an unreachable *control over an enforced rule* actively
blocks people — and it is now how reach work is prioritised.

### v0.3.878 — a share token may serve model geometry, as a per-token opt-in

`R22-PUBLIC-VIEWER` was filed for weeks as missing code. It was not. The token was already
project-scoped, revocable and audited, and four routes already honoured one. What was missing was a
**decision**, and a roadmap entry had it recorded as a build.

Answered: yes, **per-token, never a default**, following the payments precedent. The flag defaults
false, so no link already in someone's inbox was widened retroactively. The token serves the
converted fragment and **never the source IFC** — "share the model" reads as either, and the wide
reading discloses every property set, classification and GlobalId in the project. Unknown token,
revoked token, missing opt-in and no-model-published all return an identical 404, so none of them is
an enumeration oracle.

### v0.3.879 — one implementation of the estimate→BoE mapping

Two client-side copies of the same cost-code mapping, where the seam already exists server-side. One
removed; the reasoning kept in the docstring rather than deleted with the code, so it does not get
re-added by someone asking a reasonable question.

It nearly did not land at all. It was authored on a branch **after** that branch had squash-merged,
so it sat on a ref no PR pointed at, while the session that wrote it correctly reported it pushed. A
`git grep` on main still showed two callers. **After a PR squash-merges, its branch is a dead ref.**

### v0.3.880 — the routine sweep echoed an exception's text onto a response

The repo's only open CodeQL alert. A caught `ValueError` had its message placed into a refusal
returned to any viewer-role caller. The message is now rebuilt from the job registry — identical
text, sourced from a server constant instead of from a traceback, so the next exception added
upstream cannot start leaking whatever it happens to say.

### v0.3.881 — the roadmap reconciled, and three findings booked

`R22-PUBLIC-VIEWER` moved to the completed archive. Three new entries, each from something that
actually happened during the batch rather than from a survey:

**QTO-TRADE.** The four procurement methods cannot be wired at all. The engine skips any quantity
line lacking an item, description or material, and both model-derived sources supply none of them —
so a buyout screen over today's inputs renders "0 packages", which reads as *this model has nothing
to buy out* rather than *this input is incompatible*. Two agents reached this independently from
different directions. It also corrects a premise the whole ring rested on: the sweep proved every
parseable client method has a live route, and reachability was allowed to follow from that. **Route
existence and input adequacy are different questions.**

**RATCHET-SET.** The uncalled ceiling asserts only `measured <= ceiling` — there is no floor, so a
*higher* literal always passes. Five PRs lowered that one line from four different bases during this
batch and two stale-high literals were caught only by hand, each of which would have loosened the
ratchet with every gate green. Merge sequencing does not fix it: it decides which number lands, not
whether it is true. Two PRs measured against one base are both right until either merges, and then
the second is wrong — it must **re-measure**, not rebase. The fix is to commit the set of uncalled
names rather than a count.

**BOE-MAPPING-DEDUP.** The second copy of that mapping, booked rather than paid under time pressure.

### Also

Thirteen merged branches deleted. They are dead refs, and one had already swallowed a real commit.

## v0.3.877 — a contract, a control character, and a gate that relied on its neighbour

### The sandbox gets the contract isolation needs

`SEC-PLUGIN-SANDBOX`'s remaining half has been filed for weeks as "Parked pending a deployment-shape
decision". That decision was already settled — the repo ships a production compose file and
`R39-WORKER-SPLIT` built the precedent for a second compose-launched process. The obstacle was never
deployment. It was this signature:

```py
execute_ifc_code(model, code)   # a live ifcopenshell.file, mutated IN PLACE
```

The caller keeps using that same object afterwards. A child process cannot share an in-memory
object, so running the snippet anywhere else means serialise → run → serialise back → reload — which
hands the caller a **new** object and breaks every one of them. That is an API contract change at the
call site, not a deployment choice, and building the isolation first would have run straight into it.

So the contract moves first and the execution stays put. `execute_ifc_bytes` is bytes-in/bytes-out
over the same sandbox. It runs in-process and **is not isolated** — that is not claimed. What it buys
is that the middle can be replaced without touching a caller.

The test for it found something worth keeping. Deleting the feature-flag check from the new function
*still* raises `PermissionError`, because the inner call checks the flag too — an equivalent mutant.
The two arrangements differ in *when*: without the outer check the input is parsed before the flag is
consulted, so unreadable bytes with the flag off fail as a parse error instead of a refusal. Once
execution moves out of process that inner check is running somewhere else, and a door that relies on
its callee's gate has none of its own.

### Storage keys: every control character, and NTFS was hiding the rest

`validate_key` rejected NUL. Reverting the new check to that rule leaks exactly one key of the
thirty-three the test now drives: ``. The other C0 characters *look* refused — by NTFS rejecting
an invalid filename, not by us. S3 has no filesystem and would have stored every one of them, so the
two backends disagreed about thirty-one keys and the local backend's accident hid it. That is the
same shape that moved `..` out of the local backend and into the shared validator in the first place.

The stronger change is deliberately not made: tightening to an `[A-Za-z0-9._-]` allowlist would reject
attachment keys, which carry user-supplied filenames — a contract change for every caller dressed as
a hardening.

Two CodeQL `py/path-injection` alerts were raised against the file the moment it changed, and are now
dismissed as false positives with the evidence attached: the barrier resolves and compares rather than
inspecting strings, 43 hostile keys are refused through both write paths, and a filesystem check
confirms nothing landed outside the root.

### Also

`R31-CITE-HIGHLIGHT`'s data-model blocker is cleared — a PDF ingest used to run the text extractor and
then throw the PDF away, so even when a real document existed nothing could open it. And `main` was red
for three commits over a single wrong quadrant character (`◨` for `◧`), which stopped a bullet being
parsed as an item and made its body fold into the entry above it.

## v0.3.876 — three limits that were not limits

Every fix in this release has the same shape: a guard that existed, ran, and returned a confident
answer about something it had never looked at.

### The upload cap asked the client how big the body was

`main.security` did reject an oversized upload with a 413 — the roadmap's claim that the cap "lives
only in nginx" was simply wrong. It decided from a header:

```py
cl = request.headers.get("content-length")
if cl and cl.isdigit() and int(cl) > _MAX_UPLOAD_BYTES:
```

Every term is a way to skip the check, and the first one is the one that mattered: **with no such
header the expression short-circuits and the body is never measured at all.** `Transfer-Encoding:
chunked` is the ordinary HTTP/1.1 way to send a body of unknown length — what `curl -T`, most
streaming clients and any generated-on-the-fly upload do — and it carries no `Content-Length` by
definition. The guard covered the polite case and nothing else. `cl.isdigit()` is the same hole in
miniature: a malformed length silently disabled it too.

The bound now counts bytes as they arrive, on the ASGI `receive` channel. That placement is the
point: it sits below `BaseHTTPMiddleware` (which hands you a request whose body is consumed
downstream), and it covers **every** route at once — the 36+ `await file.read()` sites span fifteen
routers, and any hand-listed set of them would have been stale the day it was written. The declared
length is kept as a fast path but never as the measurement, so a lying or absent header now changes
only how early a request is refused.

`storage.put_stream` is the other half: writing an object from an iterable of chunks, local via a
`.part` file renamed at the end, S3 via multipart. Both clean up on refusal, because a truncated
object at the real key is worse than no object — `exists()` reports it and `size()` returns a
plausible number. No call site has been converted yet; that work is tracked and the item stays open.

### Two rate limiters, and the boot guard covered one

`throttle.py`'s always-on per-endpoint caps kept a plain in-process dict, so on a multi-worker
deployment every one of them was silently multiplied by the worker count — including `POST
/auth/stepup` at 10/min, which is brute-force protection on a human step-up assertion. The per-IP
limiter beside it already had both a shared Redis counter and a boot guard refusing exactly this
misconfiguration.

**A boot guard naming `AEC_RATE_LIMIT_RPM` reads as "rate limiting is protected against the
multi-worker mistake".** It was not; it covered the opt-in limiter and was silent about the
always-on one. The new guard names throttle buckets explicitly, and the test asserts the two are
separate checks — if the old guard had ever covered this case, the item was never a gap.

Nothing about this became urgent because it was edited. R39-WORKER-SPLIT (v0.3.869) made a second
writer process the supported deployment, which turned a rounding error into the deployed
configuration.

The counter is the existing implementation *extracted*, not a second one written beside it — and
that fixed a real defect by construction. `throttle.py` bounded memory with a wholesale `clear()`
at ten thousand keys, so a scanner cycling through callers could wipe the limiter's state for
everyone it was legitimately throttling. The shared counter evicts the oldest keys instead.

### A record that predates a schema change

Shipped in v0.3.875 and completed here: module records now carry the field shape they were written
against, and a read reports orphaned and mistyped values instead of rendering them as empty fields.
The filed prescription — null the payload on any version difference — would have blanked every
historical record the first time anyone *added* a field, reproducing the exact bug it was meant to
fix. Severity now derives from the payload, not the version.

## v0.3.875 — eighty-four commits that were never tagged, and the reason

**This release exists because the previous two did not.** `v0.3.873` was tagged and no release was
ever created; `v0.3.874` was tagged, its notes written, its release object created — and left as a
**draft**, which renders in the tag list exactly like a published one until you read the state field.
Eighty-four commits accumulated behind that. The lesson is the one this file keeps re-learning in new
costume: *a step that half-completes looks identical to a step that completed*, and the only defence
is to assert the end state rather than the action.

### An unauthenticated read of another project's financials

`POST /test-fit/optimize` accepted a project id **in the request body** and seeded its economics from
that project's `purchase_price` and hard $/sf — with no gate of any kind. Four independent mechanisms
existed and not one could see it. `require_role` resolves its `pid` from the path or query, so a body
field is structurally unreachable to it. The route-authz walker covers `/projects/{pid}` routes only.
The RBAC middleware's prefix list does not contain `/test-fit`. And the global-authz test had the
route in its **frozen baseline**, filed under "stateless compute — no stored state" beside four
genuine calculators — it was the only one of the five that takes a database session.

That fourth point is the one worth keeping. The exemption list had not overlooked the route; it had
*examined* it and judged it safe by association with its neighbours. **A frozen baseline preserves
the reasoning of the day it was written, including the parts that were wrong.** The predicate that
isolates it is not "has no authz" — 34 routes qualify, mostly fine — but **"has no authz AND takes a
DB session"**: a route that cannot read stored data cannot leak it. The fix is a dependency, not a
body check, so the walker can see it; the no-`pid` calculator stays open, because closing it would
have broken the feature to fix the leak.

`pdfjs-dist` moved 6.0.227 → 6.2.108, closing a path by which a malicious PDF could execute
JavaScript in a shipped surface.

### The section box clipped nothing and every storey grid was 21× too large

Both tools sized themselves by walking `scene.three` and expanding a box over everything they found —
including the ground plane. On the demo tower that turned a 31.5 m clip volume into 700 m (clipping
nothing at all) and a 104.5 m storey grid into 2,200 m. The viewer already excluded that mesh in two
places; the bounds walk was the third site and did not. **N−1 correct sites prove nothing about the
Nth.** Both callers now derive from `modelBox3`, which sees loaded models and nothing else, and the
test asserts the consequence — the clip distance and the grid extent — rather than the code path. The
same shape appeared separately in the mis-click guard, defeated by the same ground plane.

### CI stopped paying for suites nobody reads

Neither `ci.yml` nor `codeql.yml` had concurrency control, so every rebase left its predecessor
running to completion and CodeQL alone reached 15 of 28 queued jobs. Queue saturation is the failure
mode that costs the most to diagnose, because a **cancelled** job reports `fail` from `gh pr checks`,
`failure` as the run conclusion, and `failure` as the job conclusion — only the failed *step name*
distinguishes infrastructure from defect. Pull requests now share a group keyed on the head ref and
supersede themselves; pushes key on the run id so main commits never cancel each other. CodeQL
additionally scopes its language matrix to what the diff touches, failing toward more. The Pages
workflow no longer redeploys the site for a roadmap edit.

### Gates that were measuring almost nothing

The licence gate — the one enforcing the MIT/BSD/Apache/ISC-only rule — **scanned one package out of
434**, and was caught by its own vacuity floor rather than by anyone reading it. It now reads the
LICENSE file itself, because a declaration cannot catch a lying declaration. A companion check asserts
that a cited path which *resolves* also *says something*. The delete ratchet gained its file half:
removed documents stay removed. Route reachability became a ratchet with its blind spot written down.

### Also in this release

`app.ts` shed five sections (project browser, analyse, authoring, exports, clash/QA), 3,953 → 3,751
lines with the builders map now empty. A29-GUIDE-UNDERLAY pins a scanned plan to a level to trace
over. R22 gained the option as one comparable record, the provenance estimate leg, agent packs that
record the identity the transport actually sent, and the PM agreement register. The demo generator
now produces a non-empty demo for every room, and stopped double-seeding 72 registers behind a
swallowed error. A preflight refuses to build under the wrong Vite, because that build *succeeds* and
ships a 19.7× eager shell. Twenty-four completed items moved to the archive and Band 1 was
re-prioritised on what was measured rather than on what the entries claimed.

## v0.3.874 — a build that succeeds and ships the wrong bundle

**`vite build` from a git worktree exits 0 and emits a 19.7× eager shell.** One commit, two checkouts:
`three-*.js` and `thatopen-*.js` vanish and the shell goes 334 KB → 6,581 KB. `searchForWorkspaceRoot`
returns the worktree root, deps fall back to CommonJS interop, and the chunking rules never match.
Package resolution is *not* the cause — both packages resolve to identical absolute paths either way.

**Three things had to line up for it to stay silent.** `bundle-budget.mjs` computed and printed the
lazy-chunk count without ever asserting it. The only objection came from the PWA precache limit — an
accident, not a check anyone wrote. And `VitePWA` is excluded when `VITE_PAGES=1`, so on the public
path even the accident is absent. `vite.config.ts` had already written the warning in its own comment:
*"verify by grepping the OUTPUT, never by reading the config and believing it."* Nobody was.

Half of it is closed here: `copy-wasm.mjs` resolves the package instead of guessing directory depth,
and `bundle-budget.mjs` now **asserts** the vendor chunks exist. Fixing `copy-wasm` alone would have
made things worse — it would have unblocked the worktree build and let it start producing the wrong
bundle. The remaining half is workspace-root scoping, filed as **BUILD-WORKTREE-CHUNKS** rather than
smuggled into a tooling PR.

**SCALE-SEAM ⑧** took `/proforma` out of `client.ts` (3,871 → 3,796) and, in the same move, gave three
endpoints their first caller: `/proforma/renovation`, `/rollover` and `/income-basis` were built,
tested and unreachable from the product. The per-file ratchet added in ⑦ is what forced this — a new
endpoint added straight to `client.ts` now fails the build, so the methods went into a domain module.

**RAIL-DRAG** ships drag-to-place. Its finding is not about dragging: during `dragover` the browser's
DataTransfer is in **protected mode**, so a handler that reads the payload concludes "not mine", never
calls `preventDefault()`, and every drop is silently refused. **happy-dom does not model this**, so a
test written against the real API passes while the feature does nothing — a test environment more
permissive than the browser, vouching for a broken build.

**Lane J added.** Three sessions in one day flagged a path belonging to no lane — `test_file_sizes.py`,
`style.css`, the build scripts — each flagging it correctly and then editing it anyway. An unowned
shared path is not neutral ground; it is a collision nobody is watching for.

## v0.3.873 — four sessions, and three of the findings were holes in the checks themselves

Integration release: SCALE-SEAM ⑦, AUTH-SNAP-OVERRIDE, the roadmap-staleness scan fix, and the
premise corrections three sessions deferred here. Merged main verified as one tree — backend 528/528,
web 1223/1223 across 109 files — because each change was green *alone*, which is not the same claim.

**SCALE-SEAM ⑦** took `/auth` out of `client.ts` (3,967 → 3,871) into `api/auth.ts`. It also found the
surface ratchet had gone slack at 698 against a live count of 699 — one method's worth of loss would
have passed silently. The floor was measured on the *unmodified* tree first, so "I raised the floor
and it passes" could not be confused with "I raised the floor to hide what I dropped".

**The size guard could not record that extraction at all**, and the reason is the release's theme.
`CEILING` was one global number asserted against every file, so it is pinned by whichever file is
worst — `viewer/app.ts`. Removing 96 lines from `client.ts` left 5,200 exactly as true as before. A
global ceiling is structurally blind to an extraction from any file that is not the current worst.
It is now a `PER_FILE` map, and the entries are asserted **present** before their sizes are checked,
because a ratchet keyed by path stops ratcheting silently the moment a path changes.

**AUTH-SNAP-OVERRIDE** shipped a one-shot object snap — and found `resolveSnap`/`segmentSnaps` had
**zero callers**, with `perpendicular` sitting in `SnapKind` all along with nothing able to produce
one. The roadmap entry described a modal snap preference that does not exist.

**`roadmapStale` was timing out, and it was not a flake.** The scan ran three times per file, ~500
Python modules each, 2127+1370+484 ms against a 5 s default. Three scans became one and whole-file
reads became 500-byte reads; only *then* was the timeout raised, with the measurement beside it.
Raising it first would have hidden the cost and moved the cliff somewhere less predictable.

**Corrections to entries that were confidently wrong**, all found by reading rather than by any gate:

  * **R35-SANDBOX-ISOLATION** is not parked on a deployment-shape decision — that is settled. It is
    blocked because `execute_ifc_code` mutates a live in-memory `ifcopenshell.file` **in place**, so
    isolation requires an API contract change at the call site, not a deployment choice. Re-estimate
    M→L. And the sandbox looks unreachable from the routers but is not: the caller resolves through
    the edit-recipe registry, which no route-reference grep can see.
  * **⑥'s "`/auth` needs care, it owns token state"** was already discharged when written — token
    state has been public on `HttpCore` since the T2 extraction.
  * The per-file ratchet's own docstring said `viewer/app.ts` was 5,064 lines. It was 5,106 by the
    time it landed. A number embedded in prose goes stale the same day; the assertion reads the file,
    the sentence does not.

## v0.3.872 — the guard forbidding two writers didn't know I had added a second way to have two

v0.3.869 moved the job worker into its own container. `_production_guard` already refused to boot a
deployment that could not serialise sidecar writes across workers — but it asked `UVICORN_WORKERS > 1`,
which is *one* route to two writer processes. `AEC_JOB_WORKER=off` is a second, independent one, so a
stack with one uvicorn worker and a dedicated worker container went straight through.

On anything but Postgres this matters: `pid_lock` falls back to a `threading.RLock`, which two
processes cannot share. A mutating job in the worker and a document upload in the API then interleave
their load→save on the same sidecar index and one entry disappears, with nothing raised.

The guard was right when written and became wrong when the product grew a new way to do the thing it
forbids — the failure mode of any check that enumerates causes instead of measuring the condition.

Both sides now close it. The boot guard counts writer processes and names which second writer it
found. `python -m aec_api.worker` refuses to start where the lock cannot span processes, because the
API's guard is production-scoped and the worker can be pointed at a database the API never saw;
`AEC_WORKER_ALLOW_UNSAFE_LOCK=1` accepts the risk explicitly and still warns. The dialect is read
from `DATABASE_URL` rather than a live session, so a connection blip cannot permanently refuse a good
deployment — the reason `main.py` already documented for the same decision.

Also corrected: the R35-PIDLOCK-XPROC roadmap entry described its problem in the present tense long
after the fix shipped, so a ✅ item read as open work.

## v0.3.871 — the roadmap contradicted itself in four places

Seven item ids were defined more than once and four of the duplicates disagreed. Since every
prioritisation decision is made from this file, that corrupted the decisions rather than just the
document.

`R36-AUTHOR-MENU` was the dangerous one: marked ✅ SHIPPED (v0.3.836–843) in one entry and sitting
*unmarked* — open work — about twenty lines below it. `R31-CITE-HIGHLIGHT` carried a ⭐ and an "S"
above a correction, inside its own entry, withdrawing exactly that estimate. `R22-PUBLIC-VIEWER` was
S in one place and M in another, which lands it in a different sprint.

`SEC-PLUGIN-SANDBOX` turned out not to be a stale duplicate at all but an **id collision**: one entry
is `sandbox.py`'s AST allowlist (shipped v0.3.864, Lane D), the other is `plugin_registry.py`
importing third-party Python into the API process (open, Lane C). Two different items wearing one
name, so "SEC-PLUGIN-SANDBOX is partially shipped" was true and false at once. The second is now
`SEC-PLUGIN-LOADER`. Splitting them exposed a fifth consequence: the lane table listed the id under
Lane C while the item's own text read "Lane **D**, not C" — with one id covering two items, the table
could not be right about both.

`roadmapStale.test.ts` now fails the build if any id is marked done in one place and open in another.
It could not see this before: it compares open items against the *code*, and nothing compared an
entry against its own twin — a gate written for this exact class of bug, missing another instance of
it, while reading as coverage. Contradiction is checked rather than duplication, because duplicates
are legitimate (`R22-PHOTO-CV` has three, all true) and banning them would need an exemption list.

Three things it deliberately cannot catch are named in the test: disagreeing sizes, a heading that
contradicts its own body, and the next id collision. Those need a reader, and saying so beats
implying the gate covers them.

## v0.3.870 — a stalled queue and an idle one no longer look the same

v0.3.869 let the job worker run in its own container. That closed a scaling ceiling and opened an
observability hole: with the worker elsewhere, nothing the API can see changes when it dies. The API
is fine — it does not run jobs. The worker container may be up and wedged. Every enqueue keeps
succeeding.

`/metrics` now exposes `aec_jobs_oldest_queued_seconds`, the age of the head of the queue. Alert on
that. The series is **absent when nothing is queued** rather than zero, because a zero would say "the
oldest job is brand new" and make the rule both silent during a stall and reassuring the rest of the
time. `aec_jobs_stats_ok` is always emitted so that "could not read the queue" never renders
identically to "nothing is queued". Depth is exported too, but it is the thing to scale on, not the
thing to page on — one job wedged for six hours never crosses a depth threshold.

## v0.3.869 — the heavy work moved out of the process answering requests

The durable job queue ran as a daemon thread **inside the API process**. Its heavy kinds are
full-model IFC parses — COBie handover export, bundle generation, generative runs — so one person
converting a large model competed for CPU and memory with every request that container was serving.
Nothing errored. The application just got slower for everyone, which reads as "the product is slow"
rather than "a job is running".

`AEC_JOB_WORKER=off` now makes the API serve requests only, and `python -m aec_api.worker` runs the
queue in its own container. `docker compose --scale worker=3` scales conversion throughput without
touching API latency. The default is `inline` — an existing single-container deployment upgrades and
changes nothing.

The two mechanisms that make this safe were already there, and a stale comment was hiding both: job
claim is a compare-and-swap that is correct across processes, and `pid_lock` became cross-process in
R35-PIDLOCK-XPROC. The docstring still said multi-worker deployments were unsupported and would need
`SELECT … FOR UPDATE SKIP LOCKED` — false, and a no-op on SQLite. It would have talked the next
reader out of the change it was sitting next to.

The new risk is silence: turning the API's worker off without running one leaves every enqueue
succeeding and nothing ever running, with no exception and no failed healthcheck. `test_worker_split.py`
holds that closed — it checks the flag through a started app in both directions, drives a real job
through the entrypoint, and fails the build if a compose file sets `off` without a service that runs
the worker.

## v0.3.853 — the decoder's complaint was going straight to the caller

CodeQL flagged `py/stack-trace-exposure` (medium) at the exact response line added in v0.3.852. The
Pillow error was interpolated into the API response, so a caller uploading an unreadable file got back

    cannot identify image file <_io.BytesIO object at 0x7fe86faefbf0>

— which discloses interpreter detail and a heap address, and tells the person holding the phone
nothing they can act on.

The detail now goes to the log; the response carries a fixed sentence naming the likeliest real cause,
an unsupported format and HEIC in particular. That is both safe and strictly more useful than the
exception was.

A regression guard comes with it, because the natural way to write this handler is the leaky way and
it will be written again: `services/api/test_verification.py` asserts the returned reasons contain no
`0x`, `BytesIO`, `Traceback`, `PIL.` or `object at`. Mutation-checked — restoring the interpolation
reds the suite.

**Not caught by review or by the suite in v0.3.852; caught by CodeQL after the push.** The alert count
went 0 → 1 on our own commit, which is the concrete argument for the standing directive to read
alerts rather than trust a green scan *run*.

## v0.3.852 — the photo gate would have thrown away every iPhone photo

Fixed main, red since v0.3.851. One suite of 525 failed: `services/api/test_verification.py` uploads
bytes carrying a JPEG magic number that are not a decodable JPEG, and the quality gate added in
v0.3.851 refused them with a 400.

**The test was right and the route was wrong, in two ways.**

It contradicted its own docstring, which argues a blurred frame must be stored anyway because a field
engineer in a dark riser may have no better shot and losing the evidence is worse than keeping a poor
frame. An unparseable frame is the same argument, and it was refused.

And it was a live production bug, not merely an inconsistency. **iPhones shoot HEIC by default; Pillow
cannot decode HEIC without `pillow-heif`**, which is not a dependency here. A gate written to protect
evidence would have rejected the most likely genuine field photo on the platform most field engineers
carry — and CI could never have caught it, because no fixture is a real phone photo.

An undecodable upload is now stored with `quality.analysed = False` and a plain-language reason. The
API cannot tell "corrupt" from "a format we have no codec for", and **between silently discarding real
evidence and keeping something unreadable, keeping is the recoverable error.**

**Process note, which is the transferable part.** The v0.3.851 push ran the new test and the
reachability gate, and not the suite covering the route it modified. A passing check is a statement
about what it ran on. Adding validation to an existing endpoint is a contract change for every caller,
and the expensive failures are the *legitimate* inputs that fall inside the new refusal set.

## v0.3.851 - R22-PHOTO-CV Tier 1: the site photos finally have a reader

`routers/verification.py` has been attaching field photos to IFC GlobalIds for months and nothing
ever read one. The gap was a CONSUMER, not a model, so this ships without a new dependency - numpy
and pillow were already in both lockfiles.

- **`photo_cv.py`** (new leaf): a quality gate that refuses a photo carrying no evidence (Laplacian
  focus + exposure clipping), a perceptual hash that catches one shot uploaded against thirty
  elements to clear a checklist, and a normalised comparison that screens the incoming photo against
  the outgoing one at upload - the only moment both exist, since `photo_key` is a single column.
- **The API states its own confidence.** `near_identical=True` is a strong claim; a high
  `change_score` is a screening signal only, because a camera move scores higher than most real
  change. Returning a bare `changed: bool` would have asserted more than the mathematics supports.
- **A test corrected the design.** The load-bearing case - an exposure shift must NOT read as change
  - failed on first run at correlation 0.98 with zero changed cells, rejected solely on hash
  distance. dHash is not exposure-invariant where highlights clip, so it can no longer veto the two
  measures that are invariant by construction. A tight bound there would have reported "changed" for
  most unchanged elements, which is how a monitoring feature gets switched off.
- **Roadmap correction.** The licence objection filed against this item was wrong: torch,
  torchvision, scikit-image and scikit-learn are BSD-3 and OpenCV is Apache-2.0. The actual trap is
  Ultralytics YOLO (AGPL), and naming the category instead of the package had blocked the item for
  days. Defect detection stays refused - no labelled data - with concrete cracks carved out, since
  public CC-BY datasets exist for that one class.

## v0.3.850 — the register renderer leaves the shell, because two lanes were sharing one file

**The lane table was green and the boundary was fiction.** `docs/roadmap.md` assigns
`apps/web/src/portal/portal.ts` to Lane A · Shell & IA and every register-shaped item to Lane B ·
UI & panels, and `roadmapLanes.test.ts` proved those paths disjoint. They were. The generic **register
renderer** — the config-driven engine behind all ~130 registers' list, filters, sortable table, inline
edit, form, record page and board — was inside `portal.ts`, so a Lane B item could not do its own work
without editing a Lane A file. Disjointness is a property of *paths*; this was a mismatch between a
path and the *work*, and no version of that check can see it.

Three items had already hit it. **`R36-EMPTY-STATE` shipped through it last release** and missed a
collision only because the Lane A session happened to be in the viewer that hour. **`R24-MONO-DATA`
gave up** on its `portal.ts` hunk and recorded why in `ui/monoData.test.ts`: "held by another
session's in-flight work". **`R24-DENSITY ②`** — *"applied to registers, not just the dashboards"* —
was aimed at the same wall.

**Moving the items to Lane A would have relabelled the collision, not removed it.**
`R36-EMPTY-STATE` genuinely edited `ui/empty.ts` *and* `portal.ts`; under Lane A it straddles the
other way. While one file holds both jobs, no assignment of the items makes them stop straddling. And
a carve-out is written `!path` — a path is a file, so "the register methods of `portal.ts`" cannot be
said at all, and the directions are explicit that a prose exclusion is not a boundary.

So the renderer became a file. `apps/web/src/portal/register/register.ts` now holds it and **Lane B
owns `portal/register/`**; `portal.ts` keeps the shell — nav rail, room spine, workspace and persona
filters, dashboards, module catalog, destination dispatch — and stays Lane A's. Its 3,501 lines became
1,413 + 2,140.

**Behaviour-preserving by construction.** The move was mechanical: the ~90 internal calls between
these pieces are untouched, and only references to *shell* state became `this.ctx.*` over the existing
`PanelContext` — the same seam `portal/panels/*` already uses, plus one addition (`hasDest`, so a
register's declared `tools[]` can ask whether a destination exists before rendering a button for it).
The shell reaches back through exactly six members. **1149/1149 web tests green, typecheck and lint
clean, no behaviour change intended or observed.**

**Two checks hold the boundary, because prose would not.**

- `portal/register/registerOwnership.test.ts` — no register internal may reappear in `portal.ts`, and
  the six doors the shell may use are enumerated with the reason for each. A seam holds only while
  crossing it is inconvenient, and `this.reg.` is not inconvenient at all. Mutation-checked both ways.
- `shell/roadmapLanes.test.ts` gained one assertion: the lane owning the portal shell is not the lane
  owning the register renderer, and neither path is unowned.

`ui/innerHtmlGuard.test.ts`'s per-file allowance was re-split with the code (14 in one file → 8 + 6
across two) rather than left at 14, since an allowance parked above a file's real count is headroom
for the next unescaped sink; its repo-wide total was already rename-proof and never moved.

**One finding recorded, deliberately not decided.** The lane check asserts lanes do not *overlap*;
nothing asserts they *cover*, and they do not — `drawings/`, `proforma/`, `studio/`, `tools/`,
`tree/`, `pins/`, `kernel/`, `account/`, `connections/` and the `portal/` root files have no lane at
all. The live case is `apps/web/src/drawings/`, where **Lane B's `R23-SYMBOL-COUNT` and
`R38-SHEET-MARKUP ③` and Lane A's `R36-DRAWINGS-RETURN` all land**. Same shape as this bug with the
extra twist that nobody owns it. It is written into the roadmap rather than settled here: guessing an
owner for a directory two lanes are already aimed at is how this one was made.

## v0.3.849 — a register with no rows now says *which* of three things is true

**Reported as "something is wrong with specs".** Specs was fine: the module rendered in full —
toolbar, filters, saved views, templates, import — around a table holding zero rows, because the
project had never had a spec section created. Every design register was in the same state. A
complete surface wrapped around nothing reads as a failure *of the surface*, and the reader had no
way to tell which of three unrelated situations they were in:

1. **nothing has been created yet** — an invitation. The next step is to create one.
2. **a filter is hiding everything** — a mistake the reader made. The next step is to clear it.
3. **the fetch failed** — an outage. The next step is to retry, or to tell somebody.

Those three send a reader to three different places, so rendering them identically was the whole
defect — not the wording of any one of them.

**The premise-check said the copy was not the item, and it was right.** The roadmap entry asked
whether the register renderer could actually *distinguish* an empty result from a filtered-to-nothing
one before any copy was written, because writing copy for a distinction the code cannot make is a UI
promise the data cannot keep. It could not, in two ways:

- **The filter test was half the filter vocabulary.** The branch asked `filter.q || filter.state` and
  knew nothing of `filter.fields` — the ⧧ Filter panel, which is the *primary* filter UI and the one
  most likely to narrow a register to nothing. So "amount ≥ 1M" produced "No change events yet" *plus*
  curated guidance about where change events come from: a confident wrong answer in the one place a
  reader has no way to check it.
- **The failed case did not exist at all.** The records fetch was the only unguarded `await` in
  `openModule` — its neighbours `listViews` and `templates` both `.catch` — so a 500 or a dropped
  connection left the "Loading …" skeleton on screen permanently and the rejection escaped through
  the `void openModule(...)` call sites. A dead screen and an empty register looked identical, which
  is the reported defect exactly.

So the plumbing was the work and the copy was the easy half. The vocabulary lives in
`apps/web/src/ui/empty.ts` beside `noProjectHtml` rather than in a new file: that function already
owns the adjacent case with ~17 adopters and already ships the `.empty-state` class, and a second
empty-state vocabulary next to it is how the icon set once ended up speaking two languages.

- **Three states, three actions, marked in the DOM.** `data-empty` carries the decided kind, so a
  check can assert *which* was chosen rather than that something rendered — three states that read
  differently but are indistinguishable to a test would repeat the defect one level up. The failure
  state renders the back link, the reason and a retry, and deliberately **not** the toolbar: a full
  set of controls around a register that was never fetched is the original defect.
- **"Clear filters" clears all three clauses** — search, state and fields together. One left behind
  would land the reader on the same screen with no sign anything had happened.
- **The failure state refuses to claim the register is empty.** A request that did not answer cannot
  say whether rows exist, so it names the cause instead of inventing the one fact it just failed to
  fetch.
- **`No rfis yet` is fixed too.** The shipped line lower-cased the whole display name, which renders
  the busiest register on a jobsite as an unreadable slug. The rule is now on the word: two or more
  consecutive capitals is an acronym and is left as authored.
- **Verified live, in the real app, for all three states and both recoveries** — a register with zero
  rows, the same register narrowed to nothing through the actual ⧧ Filter control, and a forced fetch
  failure; then clear-filters restoring the rows and retry recovering the register. Twenty new tests
  across `ui/empty.test.ts` and `portal/registerEmpty.test.ts`, the latter driving the real renderer
  rather than asserting on its source — the defect being fixed *was* an unreachable branch, and a
  source regex passes on a branch that is present and never taken. Six deliberate mutations (drop
  `filter.fields` from the count, silence the catch, collapse the noun rule, blank `data-empty`, keep
  the filter that "clear" claims to drop, and make all three copies identical) each turn the suite
  red.

## v0.3.848 — Analyse leaves Review, because a 1087-line section was never one job

The viewer rail had a **Review** item that meant two different things at once: *is the model right*
(clash, health, rules, data hygiene, queries) and *what does the model tell you* (code compliance,
egress, cost, the 4D sequence, and asking it a question in English). They arrived together because
they were built together — one `qa` tool section, 1087 lines, 42 labelled controls, **zero
sub-headings and one divider**. Nobody chose that grouping; it is where a control went when the
section was the only place to put one.

This matters beyond tidiness. RAIL-SPLIT had already routed every other tool group to the rail item
that owns its job, and it recorded, in code, why it could not do the same here: Analyse's only tool
was *Ask the model*, and the analyses it belongs beside were locked inside `qa`. **A one-button rail
item is the thin version of the empty-room failure**, so Analyse was deliberately not shipped rather
than shipped hollow. Cutting the section is what removes that reason.

- **`qa` is now `qa` + `analyse`.** Three contiguous ranges — 234 lines covering 4D, occupancy &
  egress, IBC code analysis, IEBC existing-building scope, cost estimate and Ask — moved into a
  second `section()` call in the same builder. Deliberately **not** a file move or a function
  extraction: the block is one closure over shared state, and pulling it into functions first is how
  a re-parenting pass becomes a rewrite. Because each builder declares its own local `b` and `out`,
  every moved range is the original text at the original indent, with **no identifier renamed**.
- **Analyse is a rail item with contents**, using an icon already in the vendored set — you look
  *into* the model for an answer rather than sweeping it for faults. It is listed for every persona,
  because clicking a new rail item and finding its one group folded shut under a "more" badge reads
  as an empty room.
- **The count is asserted, not assumed.** A control that silently vanishes in a cut looks exactly
  like one deliberately removed, and the next person to notice is a user who needed it. So the
  42-control inventory is frozen in a test that checks each is on the side the split intended, that
  none is in both, **and that neither half was hollowed out** — a suite proving only "Analyse has
  contents" passes just as happily if Review had been emptied wholesale.
- The status line was the one real trap: `out` is written by nearly every handler in the section, so
  a single shared one would have printed an Analyse result into the Review panel. Two locals of the
  same name, one per section — verified live, each panel's reading stays in its own panel.

## v0.3.847 — the naming collision closed, and nine PRs drained

A release that mostly *lands* work rather than adding it: the queue went from nine open PRs to zero,
main went red twice and recovered twice, and one long-standing collision was resolved down to a
single correct name.

### The rename — one `entitlement`, meaning what the industry means

Three things were called "entitlement" and only one of them meant land-use approval. `entitlements.py`
was subscription tiers; `proforma/entitlement_risk.py` scored risk. Both were squatting on a domain
term, so a reader hitting the word had to work out which of three things it was.

    entitlements.py            ->  tiers.py         (subscription tiers)
    proforma/entitlement_risk  ->  approval_risk    (approval-process risk)
    modules/entitlement        UNCHANGED            (land use — already correct)

**The register stays put on purpose.** `mod_entitlement` appears in two migrations, so its key is a
*table name*: renaming it is a data migration rewriting every stored record's module key, not a
rename. And it was the one usage that was already right.

**The new name came from the file, not from the author.** Two rounds were spent weighing `plan_tiers`
against `subscription_tiers` before reading the source: its docstring says *"the single place that
decides what a tier unlocks"*, it says "tier" fourteen times against "plan" once, and its constants
are `TIERS` and `DEFAULT_TIER`. The answer was in line one.

### Merged this cycle

`R22-AGENT-PACKS` (#187) · `R22-ENTITLEMENT ②` (#188) · `R24-PERF-BUDGET` (#189) — plus #180–#186
earlier in the arc. Three refusals worth naming, all from the same instinct:

- **#189** states three budgets and can measure one. Click-echo and panel-load are client-side, so
  they report `unmeasured` **with the reason** rather than being omitted — a budget file listing
  three and quietly checking one is how a green suite comes to imply more than it tested.
- **#188** found that slice ① was broken: strict adjacency meant "20 parking spaces" and "45 dwelling
  units" extracted nothing, so every parking condition was unreadable. Found by ②'s checks exercising
  ① against realistic text rather than the text ① was designed for.
- **#186** treats an uninterpretable condition as `unparsed`, and an `unparsed` condition **cannot be
  discharged even when a caller names it**. Signing off text nobody read is the same failure wearing
  a signature.

### Two red mains, both mine, both from the same half-finished change

The rename renamed the files and their references and shipped — leaving `docs/roadmap.md` citing
three paths that no longer existed. `test_claude_md_gates` resolves every backticked path against
`git ls-files`, so main went red.

**Then the first fix failed the same gate.** Explaining the change reintroduced a live citation of the
deleted file — ``it was `entitlements.py` until…``. CLAUDE.md reserves backticks for files that
*exist*; a dead or historical name takes plain quotes, because a backticked name reads as a live
citation whether or not anything backs it. **Writing about a removed file is exactly when that fires**,
and it fires hardest on whoever just learned it, because they have the most to say about the file.

The rule that comes out of it is worth more than the fix: **a rename is not one change, it is three —
the files, the references, and the documentation that cites them.** Only the third is invisible to
every compiler, linter and import checker.

### Verified

Backend suites green over the renamed tree; `test_claude_md_gates` passing against a **pinned** commit
tree rather than a moving ref; manifest consistent in both directions on a clean extract of
`origin/main`; 0 open CodeQL alerts throughout.

## v0.3.846 — R36-DRAWINGS-RETURN: the way out of a room with no rail

### Fixed — Drawings was a dead end

`drawings.ts` renders into its own workspace with **no back control and no route into the viewer**;
Specs behaves the same. The only exit was knowing the tabs along the top are navigation — which is
knowledge somebody has to give you, and not what a person reaches for when a screen has trapped them.
They look for a way *back*.

There is one now, and it names where it goes: **"← Back to Design"**, not a bare arrow. A control that
does not state its destination still makes you try it to find out, and the cost of guessing wrong is
landing somewhere else you have to escape from.

**It returns where you came from, not to a hard-coded home.** Arriving from Design and being sent to
the model is wrong-but-plausible — the class of behaviour that teaches people not to trust a control.
It is sticky, because a drawing set scrolls and a way out that scrolls away is not a way out.

### Added — `wsReturn.test.ts`

Four claims, all mutation-checked: the control exists, it names its destination, it goes where you
came from, and clicking it actually lands there (*existence is not arrival* — a tab that highlights
without navigating is a defect this repo has shipped before). Plus: re-entering from a different
origin updates the label, and it never offers to return to itself.

### Fixed during verification — a fixture that described a DOM I invented

The unit test passed while the live button read **"← Back to design"**, lowercase. `wsLabel` queried
`.ws-btn[data-ws=…]` — **a class that exists nowhere in the running shell**, because the tab strip has
been `[data-room]` since the room spine landed. Every lookup missed and every label fell back to the
raw key. The test did not catch it because its fixture contained `.ws-btn` elements: it was asserting
against a shell that only existed inside the test.

Both are fixed — the lookup reads `[data-room]`, and the fixture is now copied from what the app
renders, with `model` and `drawings` deliberately given no tab because they have none in the app.
**A fixture is a claim about the DOM.** This one was a claim about a DOM that did not exist, which is
the fifth way this week a passing check turned out to be about something other than what it named —
after its shape, its age, its address and its tree.

## v0.3.845 — red main: one unsorted import, and the lint I ran on the wrong revision

`import math` was added to `drawings.py` as part of making the isometric angle exact. It went in
above the existing block in the wrong position, and **main went red on `ruff I001`.**

The failure is not the import; it is the order I checked in. `drawings.py` *was* linted — and passed —
**before** that edit, while adding `axon_outlines`. The `import math` came later, in the follow-up
that introduced `ISO_ELEVATION_DEG`, and only `sheet_layout.py` was re-linted after it. A clean lint
from three edits ago was carried forward as though it still described the file.

CI runs `ruff check src/ ../data/src/` over the whole tree. Every local check here ran against a
single named file, which is narrower than the gate in exactly the way that lets a defect through:
**a check that passed is a statement about the revision it ran on, not about the file.** The habit
that fixes it is to run the gate's own command — the full-tree form is now what gets run before a
push, not a per-file one.

Nothing else changed: the axonometric suite is unaffected and still green.

## v0.3.844 — CANVAS-PEER: a 3D view becomes a drawing, not a screenshot of one

### The asymmetry this closes

R36-VIEWER-SUBAPP wants the canvas to switch between 2D and 3D in place, and the user's framing added
the requirement the roadmap item had missed: *"they need to be interchangeable and may need some
refactoring so that we can print 2d or 3d."* **Print was the part that could not be promised.**

A plan went model → `plan_svg` → sheet → PDF: vector linework derived from the geometry, placed at a
stated scale, composable beside other views. "3D" went canvas → `toDataURL` → a raster hero image.
One is a drawing; the other is a screenshot of a screen — screen resolution, no scale, no identity,
and nothing a sheet can compose. Offering the two as interchangeable modes would have been a UI
promise the data could not keep, so the data goes first.

### Added — `axon_outlines`, and 3D as a sheet viewport

An axonometric is now a viewport kind like `plan`, `section` and `elevation`: same meshes, same
`compose_viewports`, same sheet, same PDF. Two things it does that `elevation_outlines` is
structurally unable to:

- **Any view direction.** That function reads `_DIRS`, which selects two of the three world axes —
  correct for north/south/east/west, and incapable of looking down a diagonal. Vertices are rotated
  into a view basis first here, so the axis-aligned cases fall out as the special case they are.
- **It carries the GlobalId.** `elevation_outlines` drops it, which is precisely why an elevation is
  a picture rather than data. R38-PLAN-IDENTITY established that linework carrying identity is what
  lets a click in a drawing resolve to the same element the 3D view selects — the reason the mode
  switch is worth building at all, and a project non-negotiable besides.

Silhouettes sort far → near so a painter's draw hides what is behind, and an axonometric reports
**NTS** with no scale denominator, because it has no true paper scale and must not claim one.

### Fixed — the default was not actually isometric

`test_axon_view.py` asserts the thing "isometric" *means*: all three principal axes foreshorten
equally. The first implementation hard-coded `35.264°`, a truncation of `atan(1/√2)`, and the check
caught the three axes disagreeing at 6e-6. Invisible on a page, and still not an isometric. Now
computed as `ISO_ELEVATION_DEG` rather than typed.

21 checks; four mutations verified to break it — a skewed basis, a dropped GUID, a reversed depth
sort, and the rounded angle restored.

**Two of the three failures in development were the test's fault, not the code's**, and both are
recorded in it: it asserted `viewports`/`title`/`note` against a function that returns
`views`/`label`/`sub` — a shape invented rather than read, which reported "the sheet accepted 0
viewports" and looked exactly like a broken feature — and its plan fixture cut at the default 1.2 m
through 1 m test cubes, drawing nothing. Assert against the reader you did not write.

## v0.3.843 — the rail split left nine loose ends; a gate now holds the knot

A code review over the working tree found nine defects, six of them regressions from RAIL-SPLIT
itself. They share one shape: **a rail key is a shared identifier that was defined in one place and
spelled in five**, and nothing related the spellings to the definition. Renaming `tools` into seven
items could not break them, because nothing connected them to break.

### Fixed — the rail

- **Every persona lost the new rail items.** The allowlists still named the deleted `tools` key and
  none listed its seven replacements, so `applyPersona` hid View/Build/Library/Detail/Annotate/
  Export/Review for every role except `all` — exactly the panels the tool groups had just moved into.
  `all` is the one persona with no allowlist, which is why this survived testing.
- **`props` and `clash` were listed by nobody** — found by the new gate, not the review. Properties is
  how you inspect any element; both were hidden for every persona but `all`.
- **Persona switches stacked duplicate tool groups.** `buildToolsPanel` cleared only `panel-tools`;
  the panels the distribution writes into were never cleared, so each rebuild appended another full
  copy. The copies are detached from the rebuilt handlers — identical to look at, dead to click.
- **A saved ribbon tab could empty a panel permanently.** `applyPhase` inline-hid groups outside the
  active lifecycle tab, and the distribution then moved some of those hidden groups into rail panels
  that have **no ribbon at all** — nothing could ever un-hide them. Distribution now runs first, and
  anything that moves out from under the ribbon has its inline hide cleared.
- **Clash was orphaned.** Its panel was still rebuilt on every persona change with no rail item
  pointing at it — a whole coordination surface unreachable while looking healthy in the code. It is
  a rail item again, with its own Lucide glyph; burying a distinct job inside a broader one is how
  "Tools" reached 182 controls in the first place.
- **Two dead references**: the start-from-scratch flow guarded on the deleted key (permanently false,
  opened nothing), and a portal card clicked `.rail-btn[data-rail="tools"]`, matching nothing.
- **`panel-tools` and `panel-analyse` were unreachable.** The rule was "unrouted must stay VISIBLE in
  the old place, never gone" — but once no rail item opened `panel-tools`, "stays put" silently became
  "is invisible", the exact failure the rule existed to prevent. Leftovers now sweep into Build;
  `panel-analyse` (built for a rail item that never shipped) is removed.
- **The rail overflowed its own window.** Fourteen items across four clusters pushed the Collapse
  toggle over the status bar. The item list scrolls on its own now, with Collapse pinned outside it.

### Added — `railKeys.test.ts`, five claims, all mutation-checked

Persona lists name only real items; every item is listed by at least one persona; no `data-rail`
selector or `showRail()` call names a key that does not exist; and — the direction that caught the
clash orphan — **no `.rpanel` is unreachable from the rail.** String keys have no referential
integrity unless something asserts it.

### Fixed — three engine defects

- `groups.py` — a pitch change **repositioned nothing**. Only newly-added cells used the new spacing
  while existing members kept the old, producing a silently mixed-pitch array; worse, the next call
  measured against the new pitch, read every un-moved member as hand-edited, and refused shrinks to
  protect edits nobody made. Members still on their old cell now follow the array; genuinely
  hand-moved ones stay put and are reported, as always intended.
- `icdd.py` — `build_linkset`'s refusals fired **inside** the open archive, leaving a truncated
  container on disk while the caller saw an exception and assumed nothing was written. Everything
  that can refuse now refuses before the file is touched.
- `drawings.py` — the guided cut mirrored `cut_baked`'s per-mesh tolerance but not its accounting:
  bare `continue`, no counter, no log. The default plan path dropped linework in total silence where
  the function it replaced had always warned.

### Also — the roadmap reconciled, and the citation gate caught the reconciliation

Lane D's merge train landed (PRs #176/#178/#179), so the "only OPEN item" note on R38-ARRAY-LIVE was
stale. **R36-AUTHOR-MENU is marked shipped with a note that the item under-scoped the work**: it asked
for four groups and some promotions; the panel actually held 182 buttons doing ten jobs, so the More
menu is gone rather than reorganised. **R36-VIEWER-SUBAPP is now the top of that ring** — the rail
work cleared its way, and it carries a requirement the original item missed: *print is part of the
interface*, and 2D and 3D are not yet peers there.

New item **R36-EMPTY-STATE**, from the specs report — a register with no rows must say which of
*nothing created yet*, *a filter hid everything*, or *the fetch failed* is true, extending
`ui/empty.ts` rather than starting a second empty-state vocabulary beside it.

Writing that reconciliation **failed `test_claude_md_gates`**: the roadmap cited `railKeys.test.ts`,
which this release adds but which was not yet tracked, and the gate resolves citations against
`git ls-files`. Exactly the rule it exists to enforce — backticks are reserved for files that exist.
Verified against the commit's own tree before shipping rather than assuming the commit would fix it.

## v0.3.842 — the tower drive now builds the Design room it was skipping

### Added — phase 1b, because 25 of 29 design registers were empty after a full run

An audit swept every design-room register against a completed tower: **zero errored, and 25 of 29
held no records.** The room was structurally sound and functionally untested. Phases 0–4 drive
acquisition through turnover and barely author anything in design, so the registers a reviewer opens
first were the ones nothing had ever put data in.

That matters more than a coverage number. An empty register is the worst thing to hand someone: it
renders in full — toolbar, filters, saved views, templates — and looks exactly like a broken screen.
That is precisely how it was reported, and the report was right about the symptom and wrong about the
cause. **Data is what makes the difference visible.**

Phase 1b now authors what a residential tower actually carries at the end of DD: a DD drawing set with
four sheets, an issuance and a transmittal; two studied structural options and the review that picked
one; a concept render; the four-line space program the massing implies; envelope assembly and MEP
equipment; the building permit; a design standard and a finish selection; the responsibility matrix
and a stakeholder; LOD target, information requirement and information container; the design brief,
a coordination meeting, a coordination issue and a clash run; and the site's climate, flood and
drainage exposure. **32 steps, all passing.**

The drive is now **95 pass / 0 fail across six phases**, and the design room reports **29 of 29
registers populated, 0 empty, 0 erroring** — up from 4 of 29.

### Verified — the room renders, not just responds

Driving all 33 nav entries in the live Design portal: **zero errors, 26 rendering rows.** Everything
still showing zero is a register phase 1b deliberately does not author (cross-room queues and the
sustainability set), not a failure.

One reading needed correcting rather than reporting: `flood_risk` measured 24 characters and looked
broken. It is not — it renders its full FEMA-zone / base-flood-elevation / ASCE 24 flood-design-class
filter set with its record present. The 300ms settle in the sweep was simply too short for a module
with that many filters, so it was measured mid-render. **Third time this session that an alarming
number came from the instrument rather than the product**; the rule holds — raise the bar on the
instrument before believing the alarm.

### Fixed — a pre-existing lint error in the drive

`B007` (unused loop variable) in the schedule loop, present on `origin/main` before this change.

## v0.3.841 — the residential tower builds clean; Specs asks the portal instead of the DOM

### Fixed — the end-to-end tower drive was accusing the product of its own bugs

`e2e_tower.py` builds a concrete-superstructure residential tower from acquisition to turnover over
HTTP. Run against a live API it reported **56 pass / 4 fail**, and the failures read as product
defects. All four were the driver's:

- **bid leveling** crashed with `unsupported format string passed to NoneType.__format__`. Two
  mistakes in one line: it read `packages[0]` — not necessarily the package it had just bid on — and
  formatted `low` with `:,.0f` when a package with no submissions has `low: None` **by design**. The
  endpoint was right on both counts. It now picks the package by bid count and says "no priced bids"
  rather than dying.
- **RFI respond** sent a bare action. The rfi workflow declares `respond` requires `answer`, and the
  gate is checked against the STORED record — the transition endpoint takes only `action` and `note`.
  So the field is PATCHed on first, then the action fires. The driver had no way to express that
  ordering at all, which turned a correctly enforced contract into a standing failure.
- **submittal** and **inspection** omitted required selects (`type`, `inspection_type`) added to those
  modules after the driver was written.

Fixing those revealed a fifth — **NCR** requires `disposition` — which had been **invisible**, because
the inspection step failed first and the NCR step never ran. A resilient driver reports the first
fault in a chain, not the set; a clean run is the only evidence that there is nothing behind the
first failure.

Now **63 pass / 0 fail** across all five phases.

### Fixed — Specs poll-clicked the DOM to do what one method call does

`openSpecs()` retried up to forty times at 100ms, clicking `.portal-nav [data-mod="spec_section"]` and
re-reading the node's class to learn whether the click had landed. Measured live, that selector is
**ambiguous** — a register appears in its room's list *and* in `🕘 Recent` once opened — so it matched
two nodes and **fetched the register twice** on every open. Clicking also triggers `buildNav()`, which
replaces the node mid-flight; that is what made the retry loop look necessary, and it cost two wrong
fixes in v0.3.766 and a reverted release in v0.3.770.

The portal has always exposed `openModuleByKey` for exactly this. One call, awaiting the portal's own
`init()` instead of guessing at it with a timer. **One fetch, lands in ~0.6s.**

### Noted — an empty register is indistinguishable from a broken one

The report that "something is wrong with specs" was accurate about the symptom and not about the
cause: the module renders in full — toolbar, filters, saved views, templates — but every design
register in that project (`spec_section`, `design_standard`, `space_program`, `drawing`, `document`)
returns zero records. A register with no rows and no empty state reads exactly like a failure. Worth
an explicit "nothing here yet" pass; recorded rather than bundled here.

## v0.3.840 — RAIL-ICON-UNIFY: one icon set, and a gate that says so

### Changed — the rail ran two icon languages; now it runs one

Public icon-system guidance converges on the same short list: **one grid, one stroke weight, one
style**, and mixing weights is described as destroying cohesion instantly. Measured against that, the
rail failed on all three counts — it drew hand-made 16×16 glyphs while `ui/icons.ts` held a vendored
**Lucide** set on Lucide's own 24×24 grid, so the app ran two icon languages side by side.

The icons file had already written down the rule the rail was breaking: *"Path data is copied verbatim
from the upstream SVGs — never redrawn by hand, because an icon redrawn from memory is a different
icon wearing the same name."* So `RAIL_ICONS` is now `RAIL_ICON_NAME`: a **name map, not artwork**.
Six icons the rail needed (`list-tree`, `pencil-ruler`, `download`, `file-text`, `chevron-left`,
`chevron-right`) were copied verbatim into the vendored set rather than approximated.

All **14** rail buttons now render from that set — one viewBox, one stroke weight, `currentColor`
throughout. The last text character went too: the Collapse chevron was `‹`, a different weight and a
different metric sitting in a column of SVGs, and the one place the "one icon language" claim was
still false. Because these icons carry no colour of their own, the colour contract governs them
automatically; an icon is structurally incapable of introducing a second meaning for blue.

### Added — `railIcons.test.ts`, and the assertion in it that could not fail

The gate holds four things: every rail item has an icon (the defect that shipped `undefinedView` into
the rail — the old map interpolated a missing key straight into `innerHTML`, so it printed the literal
word); every name resolves in the vendored set; the map contains **no inline SVG**, because pasting
artwork back in is the easy fix that silently restores the two-language problem; and no vendored path
carries its own stroke.

That last one was **rewritten because the first version could not fail.** It read
`icon(n).getAttribute("stroke-width")` across the set and asserted a single distinct value — but
`icon()` stamps that attribute on the wrapper itself, identically, every time. It was reading back its
own constant, and mutating the source did not turn it red. The real, breakable property is a path
*inside* a vendored body declaring its own stroke, which wins over the inherited value; that is what
is asserted now, and it fails when mutated. Consistency has no error state — nothing throws when a set
stops reading as a set — which is exactly why it needs a check that can go red.

All four claims were mutation-checked.

## v0.3.839 — Detail opens expanded; one stroke weight in the rail

### Changed — a disclosure whose parent already discloses is just a second click

Detail was three levels of chrome deep: rail item **Detail** → group heading *Fabrication detail* →
toggle *🔧 Advanced fabrication tools ▾* → the tools. The toggle earned its place when these lived
inside a crowded Build section; the rail item replaced that job. It now shows its 17 tools bare and
expanded, with no inner heading — the item you clicked already named them. `railGroup` takes an empty
heading to mean exactly that: render the contents, not a wrapper repeating the label above.

### Fixed — the rail carried two stroke weights

Public icon-system guidance is unanimous that one grid, one stroke weight and one style are what make
a set read as a set, and that mixing weights "destroys cohesion instantly". RAIL-SPLIT had added
seven icons at **two** weights (1.3 and 1.4). Normalised to one.

### Recorded — the rail runs a second icon language, and that is the real standardisation debt

`ui/icons.ts` holds a vendored **Lucide** set (ISC, in `docs/ATTRIBUTIONS.md`) at Lucide's 24×24 grid,
`currentColor`, no fill — added precisely because emoji were "several visual languages at once". The
rail's own `RAIL_ICONS` are hand-drawn at 16×16, so the app runs two systems side by side. Worse, the
icons file states the rule the rail was breaking: *"Path data is copied verbatim from the upstream
SVGs — never redrawn by hand, because an icon redrawn from memory is a different icon wearing the
same name."*

Several rail items map one-to-one onto icons **already vendored** — `layers`, `eye` (View), `pencil`
(Annotate), `flag` (Issues), `palette`/`box` (Library), `scan` (Review) — and the rest need their
Lucide source copied in rather than approximated. That migration is deliberately **not** bundled
here: swapping every rail glyph in the same release that restructured the rail would make any visual
regression impossible to attribute to either change. Tracked as RAIL-ICON-UNIFY.

## v0.3.838 — the rail reads: icons first, Detail and Annotate earn their place

### Fixed — every new rail item printed the literal word "undefined"

The rail renders `<span class="rail-ic">${RAIL_ICONS[key]}</span>` straight into innerHTML, so a key
with no icon does not fall back to a blank — **it prints**. Every item RAIL-SPLIT added rendered as
`undefinedView`, `undefinedBuild`, `undefinedLibrary`, `undefinedDetail`, `undefinedExport`,
`undefinedReview`. That is the "jumbled words". Seven icons drawn to match the existing set, plus a
first-letter fallback so an unmapped key is legible-and-obviously-unfinished rather than broken.

### Fixed — three strings competing inside a 150px rail

The dimmed-tool reason was rendered as inline text, so a disabled tool showed glyph + label +
"select an element first" across a rail 150px wide. The dimming already says *not now*; the reason
is now a tooltip appended to the tool's own title. The label truncates rather than wraps, the glyph
never shrinks, and below ~132px the labels hide entirely so the rail degrades to a clean icon strip
— which is what the rail's existing expand/collapse control was already built for.

### Changed — `gridlevels` split at the source; Detail and Annotate ship with contents

One section had grown to hold five jobs behind a single heading: levels, the document set,
annotation, the content library and fabrication detail. The seams already existed as named variables
(`annotateHead/annotateWrap`, `libHead/libWrap`, `advToggle/advWrap`) — they had simply all ended up
in one `append`. Each group now goes to the rail item that owns it.

Per-panel counts after: Tools **9** · View 17 · Build **39** (was 70) · Library 42 · Detail 19 ·
Annotate 5 · Export 21 · Review 34. **Detail and Annotate were deliberately withheld one release**
until this split gave them real contents — shipping an empty rail item to look complete is the
failure the Work room had, and withholding them was the same rule applied twice.

## v0.3.837 — RAIL-SPLIT: "Tools" was never a category

### Changed — one rail item, one job. Tools drops from 182 controls to 9

Measured live right after RAIL-TOOLBOX shipped: `panel-tools` held **182 buttons and 11 inputs under
7 headings**. The toolbox contributed 28 of those — **154 were already there**, doing about ten
unrelated jobs: an element palette (~40), analysis and QA (~30), fabrication detail (~15), exports
(~12), drawings and sheets (~10), grids and levels (~10), annotation, federation, working origin, and
a row of deep-links the room tabs already provide.

So "Tools" was not a category. It was where a control went when nobody decided — the same failure
`rooms.py` records about the retired `Engineering` section, arriving in the rail instead of the
module list. A junk drawer is invisible until something has to read it as a list of jobs.

The rail is now **13 items in 4 clusters**: Navigate (Tree · Layers · **View**) · Author (**Build** ·
**Library** · Props) · Document (Drawings · **Export** · Specs) · Coordinate (**Review** · Issues).
Measured after: Tools **9**, View 17, Build 70, Library 40, Review 33, Export 12.

Three of the new items are load-bearing for what comes next rather than merely tidier. **Library** is
the element palette, and it has to be its own item to become the drag source for placing elements.
**View** is exactly the set of tools that needs a canvas, so the 2D/3D switch belongs there.
**Export** is where "print 2D or 3D" lands once the two canvases are peers.

Both moves are re-parenting passes keyed off structure that already existed — `data-tool` on each
section, `ToolGroup` on each tool — not a rewrite of 154 call sites. **A pass that only moves nodes
cannot lose one.** A group with no destination stays visible in `panel-tools` rather than vanishing.

### Not shipped, deliberately — three items that would have been empty or thin

**Detail** and **Annotate** are absent: their content is still inside the mixed `authoring` section
(annotation + content library + fabrication under one heading), and splitting a section by guessing
which button belongs where is how a tool ends up somewhere nobody looks. **Analyse** is folded into
Review because "Ask the model" was its only tool — a one-button rail item is the thin version of the
empty-room failure fixed in Work this morning. All three arrive when `authoring` and `qa` are
separated at the source. Shipping an empty rail item to look complete is the thing being avoided.

## v0.3.836 — RAIL-TOOLBOX: the rail becomes the instrument, the window becomes a canvas

### Changed — all 28 viewer tools move from a bar floating over the model into the rail

The floating toolbar showed ~5 labelled verbs and hid **23 under More**, sitting on top of the
geometry it acts on. That was defensible while the rail was navigation and the bar was the tools. It
stops being defensible once the rail is meant to *be* the design tool: a tool you cannot see is one
you do not know you have, the bar covered the model, and it makes drag-to-place impossible — half
the palette would float over the drop target.

So the window is now a pure canvas and the rail is the instrument, grouped by the questions people
actually ask of a model: **View (10) · Measure (3) · Modify (10) · Analyse (1) · Share (4)**.

Two rules the bar had to break and the rail does not. **Nothing is demoted** — the bar had a hard
cap, so promoting one verb silently pushed another into More (a defect this repo hit twice). A rail
scrolls; every tool sits in the same place, always. **Context dims rather than hides** — the 12
selection-dependent verbs stay put and go quiet with "select an element first", instead of appearing
and disappearing under the cursor.

This is a re-parenting pass, not a rewrite: every tool is still created by the module that owns its
behaviour, through the same `toolBtn` seam. A pass that only moves nodes cannot lose one.

### Fixed — a label that did not survive its owner re-rendering

Found by driving the real app, not by the tests. The first implementation injected label spans *into*
each button. The presence tool re-renders its own button to show who is viewing — which wiped the
spans and left a bare unlabelled glyph. Any module updating its button would have done the same.
These buttons belong to the modules that made them: the toolbox may re-parent and decorate them, it
may not own their contents. The label now lives in `data-label`, rendered by CSS, and survives any
`innerHTML` the owner writes. `railToolbox.test.ts` pins that case by re-rendering a button the way
presence really does.

`railWiring`-style guarantee for the toolbox: **the count out equals the count in** — 28 placed, 0
ungrouped, verified live and in the suite. `.rail-tool.on` was added to the reviewed accent list
(R26-COLOUR-DISCIPLINE) with its reasoning; the dimmed state deliberately carries no colour, because
unusable-right-now is a second axis and sharing the channel is what made the accent meaningless.

## v0.3.835 — a pipeline gate that survives an empty model and keeps identity at scale

### Added — `test_pipeline_scales.py`: the drawing chain, walked at four sizes

Most drawing tests build one small fixture and assert one engine against it. Two failure classes
slip through that shape and this repo has been bitten by both: **the zero case** (an empty model
reaches every engine eventually — a fresh project, a failed import — and `bake` returning nothing
raises where a user expects an empty drawing), and **a fixture too small to be wrong** (a check once
produced a confident 6.44% that became 0.92% at real scale).

So this walks one model per scale — empty · 1 storey · 3 storeys · 8 storeys — through bake → cut →
guided cut → plan/section/elevation SVG, and asserts at every size that **every emitted polyline's
GlobalId resolves in the model**. That last assertion is what the runtime buys: `cut_baked_guided`
returning the right *shape* with a shifted field passes a length check and fails this one.
Mutation-proven — corrupting the guid fails 3 of 4 scales, and `empty` correctly stays green because
it has no polylines to corrupt.

Two behaviours found while writing it, both recorded at the point someone would trip on them rather
than silenced: the **empty model renders through a different path** (`to_svg([], "no geometry")`,
which emits a bare `<svg>` while the populated path emits `<?xml …?><svg>` — both valid, built by
two independent writers), and **`elevation_svg` takes baked meshes** plus a required levels + title
while its siblings `plan_svg` and `section_svg` take a model. That asymmetry made a sweep script
report a false break on its first run.

## v0.3.834 — the Work room had nothing in it; now it runs the field

### Fixed — Work was an empty room, by construction

Opening **Work** showed a tab with one panel and **zero registers**, because no section in the
`section → room` table mapped to it. Not a rendering bug — a room with no contents, which reads to a
user as a broken product.

The cause was that "Work" is ambiguous, and the code took the narrower reading: *"my work"*, a
personal inbox ("Whatever is in your court right now"), while users read the tab as *"the work"* —
the field, the jobsite. Settling it the users' way also answers a defect `rooms.py` had recorded
about itself: **Schedule held 38 modules**, the most of any room, and its own note said "the
sections there are the next thing to fix".

**Safety · Daily Log · Progress · Logistics · Quality → Work** (28 registers). Schedule keeps
Sequencing, Resourcing and Project Controls. The seam is who maintains the record, and it is the
sharpest one in the product: **Schedule is the planner's room** — the CPM, the crews, the controls;
**Work is the superintendent's** — today's log, the safety programme, what got built, what arrived,
the punch. Two different people on two different cadences who had been sharing one 38-item rail.
The ball-in-your-court queue survives as Work's *home* panel, which is right: open the field room
and see your plate before the registers.

### Changed — Closeout moves to Operate, finishing an argument R30 started

`completion_certificate`, `as_built` and `lessons_learned` were filed under Schedule because that is
when construction *produces* them. R30 had already caught that exact reasoning for the handover
package — filing by producer rather than consumer is what severed the COBie chain — and then left
Closeout filed by it. An as-built is the drawing an operator works from for thirty years. Closeout
and the Turnover panel now sit in **Operate** (15 registers). Room counts: Deal 9 · Design 32 ·
Planning 25 · Schedule 7 · Cost 18 · Work 28 · Operate 15, zero unplaced.

**Budget and financials needed no change** — all 18 job-cost registers were already in Cost. Cost
(the contractor's money) and Deal (the investor's) stay separate deliberately, and the Finance
workspace is reachable from Deal's rail via Underwriting.

### Added — a gate proving every left-rail button goes somewhere

`railWiring.test.ts` asserts every destination the rail renders has a handler in the portal's
dispatch map, or is a deliberate workspace hand-off. A destination added without a handler renders a
button that silently does nothing when clicked — invisible until a user tries it. The test also
records the trap that produced a **false positive** during the hand-audit: matching a catalog record
with `[^}]*` stops at the `}` inside an emoji escape like `\u{1F4D0}`, which falsely reported
`__drawings__` as dead. Mutation-checked: injecting a handler-less destination fails it.

## v0.3.833 — A29-UNDO-LOCAL: undo the stroke, not the commit

### Added — Ctrl+Z pops the last clicked point of an in-progress draft

Undoing one mis-clicked point of a polyline used to cost the whole draft — Escape was the only
eraser — while undoing a committed element costs a republish (correctly: the server's versioned
history is the record). Now, while a draft tool is armed, **Ctrl+Z removes the last placed point**
and **Ctrl+Shift+Z restores it**, with the status line counting what remains. A new click
invalidates the redo branch — restoring a point from an abandoned timeline would splice it into the
middle of the current polyline and draw a wall nobody clicked. The history is strictly draft-scoped:
it clears on commit and on disarm, and the keystroke is consumed **only while armed**, so the rail's
committed-element undo and the browser's own Ctrl+Z keep their meanings everywhere else. The history
mutates the live `armPts` array rather than holding a copy — one array, one truth.

## v0.3.832 — A29-SPATIAL-SELECT: click depth, not just objects

### Added — re-clicking a selected element widens the selection one spatial level

Click an element: it selects. Click it again: its whole **level** selects (every element the model
contains in that storey, with the honest count in the status line — "Level 1 — 11 elements"). Again:
the **whole model**. Again: back to the element. This is the Site→Building→Level→Item walk other
tools build from a convention tree — ours reads the containment the IFC model states per element
(`ElementProps.storey`, the same single fetch the model browser uses), which is why an element the
model assigns no level **skips the level step** rather than selecting an invented "(no level)"
grab-bag that looks like a spatial fact. The cycle anchors on the *clicked* element (a widened
selection's first guid may not be the one under the mouse), and resets on any new element, deselect,
or Escape. `spatialSelect.test.ts` pins the cycle, the no-storey rule, and the count grammar.

## v0.3.831 — A29-PLACE-VALID: the draft says no before the round-trip

### Added — client-side placement refusals, pure and beside the inference maths

An invalid placement used to cost a full author-and-republish round-trip just to be told no — or
worse, to succeed: a zero-length wall authors fine and then exists as an invisible sliver; a
mis-click near the horizon falls back to the infinite ground plane and quietly authors a wall 400 m
from the building; a bowtie slab outline produces garbage geometry downstream instead of an error.
`placeValid.ts` refuses all three at commit time, from what the client already holds: degenerate
runs (< 50 mm, refused with the measured length), points landing far outside the model's plan
extent (refused with the distance; a **blank model refuses nothing** — the first wall must always
be placeable), and self-intersecting outlines (refused naming the crossing edges; concave-but-simple
shapes pass). A refusal keeps the draft armed — adjust and re-click, nothing is torn down. Every
other rule stays the server's call: validating rules the client doesn't own is how it comes to
refuse things the server would accept.

Verified by 12 unit tests over the pure module plus a clean live boot; the interactive
refusal path is exercised through `finishDraft`, whose wiring is three lines over the tested
function.

## v0.3.830 — R38-NODE-SLIDERS: the node graph becomes an instrument

### Added — every numeric parameter across the node graph, as a named slider

The visual node canvas stored each node's params as a JSON textarea — honest, but typing, not
designing. A "🎚 Sliders" rail now lists every top-level numeric parameter across the graph as a
named slider (`n1 · height`), with a scrub range and step derived from the value, and an optional
**run on release** that re-runs the whole graph when a slider is let go — live parametric feedback.
The textarea stays the single source of truth: sliders read it on open and write it on scrub (with
step-precision rounding, no float noise), so hand-edits and scrubs interleave without a second copy
of the params existing anywhere. Coordinates (`start: [0,0]`) deliberately do not slide — they are
positions, not magnitudes — and a scrub against a mid-edit, invalid textarea is a no-op rather than
a "fix" that destroys the edit. `nodeSliders.test.ts` pins all of it.

### Fixed — the roadmap lanes gate red on v0.3.829's own annotation

Marking R38-SYNC-SELECT shipped moved its code out of the Lane E row while its coded body entry
remained, which `roadmapLanes.test.ts` correctly rejects — an item that exists must be assigned or
parked. It now follows Lane D's shipped-pending-archive convention, staying coded in its lane row.

## v0.3.829 — the plan knows what it draws: 2D↔3D selection sync

### Added — R38-SYNC-SELECT: click a wall in the plan, it selects in 3D; select in 3D, its loops light in the plan

R38-PLAN-IDENTITY carried the GlobalId through the geometry bake; this release carries it the last
two hops. The plan SVG generator now emits `data-guid` + `data-class` on every cut polyline (in both
rendering modes — identity is not mode-dependent), and the docked plan pane wires it up: every drawn
line gets an invisible fat twin so ~1px linework is actually clickable, a click resolves to the same
element the 3D view selects, and a 3D selection lights **every loop** of that element in the plan —
one wall cut at a doorway is several loops, and the sync treats that as the honest shape. A selection
change never refetches the drawing; highlighting is a style pass over nodes already on screen.

### Fixed — three defects found by driving the feature live, each invisible from the code alone

- **The plan pane was unreachable since v0.3.826.** Its toggle button was created, titled, wired —
  and never appended to the rail. Tests exercised the class; nothing exercised the rail.
- **The pane's fetch failed cross-origin from day one.** It used `credentials: "include"`, which
  requires an `Access-Control-Allow-Credentials` header the API never sends; the browser hard-failed
  the request and the pane rendered "No plan for this level yet". It now sends bearer headers like
  every other client call.
- **The `storey` parameter was silently dropped by the live route.** The serving `plan.svg` route
  took `elevation` only; FastAPI discards unknown query params, so every "storey-synced" plan was
  cut at elevation 0 while the label claimed the level. The route now resolves the storey name
  (case/whitespace-insensitive) to its elevation, and an unknown name is a 404 carrying the real
  level names — never a silent cut at the wrong height. Verified live: Level 1 cuts 11 elements,
  Level 2 cuts 4.

Pane zoom is now client-side (CSS width) instead of a `scale` refetch the server ignored.
`test_plan_identity.py` grew SVG-emission and storey-resolution checks; `planPane.test.ts` pins the
hit-twin idempotence and the many-loops highlight contract.

## v0.3.828 — each room gets its own rail, and switching rooms stops being a race

### Fixed — Planning and Schedule rendered the same (or nothing) because room switching was a DOM click-simulation

Clicking the room tabs, measured live: Planning and Schedule rendered **empty** content panes, and
Cost and Work both displayed the *Schedule* room's rail. The tabs switched the host workspace and
then tried to land by clicking `[data-dest]` buttons under a 4-second retry poll — against a rail
the workspace switch was concurrently rebuilding. Three generations of comments in `goToRoom`
each documented a subtler failure of the same approach; the approach was the bug.

The portal now owns an explicit **active room** state. The tab bar dispatches one `aec:room` event;
the portal that hosts the room scopes its rail and invokes the room's home panel **directly** —
no clicks, no poll, no race. Rapid-fire clicking four tabs now deterministically lands on the last.

### Changed — the left rail is the active room's menu, not a directory of everything

The rail rendered all seven room groups in every workspace, collapsed — which reads as "every
module on every screen". It now renders **only the active room**: its panels first, then its
registers grouped by section (Planning: Bidding · Contracts · Estimating · Approvals…). The other
rooms live where they always did — the tab bar — plus an "All rooms" escape hatch at the foot of
the rail for browsing. Nothing became unreachable: tabs, ⌘K, favorites, recents and the hatch all
still reach the full catalog, and `parity.test.ts` still proves it.

`ROOM_HOST` moved from `main.ts` into `shell/spine.ts` beside the tables it inverts;
`shell/roomScope.test.ts` pins the scoping logic, including that exactly one portal claims each
room and that an unknown active room falls back to the full rail rather than an empty one.

## v0.3.827 — the geometry loader was never stalling; the canvas had no width

### Fixed — a zero-width canvas, mistaken for a loader stall for weeks

Asked directly, for the first time, why the dev preview "stalls at preparing geometry". It doesn't.
The `.frag` fetch returns 200, the worker parses, four meshes and 230 triangles get built and marked
visible — into a canvas measuring **0 × 493** inside a container measuring **830 × 572**. Nothing
renders, and from the outside that is indistinguishable from a loader that never finished.

The renderer sizes itself once, from whatever the container measured at construction. Anything that
gives the container its real width *later* — a rail expanding, a workspace becoming visible, a font
or CSS pass landing — leaves that first size in place permanently. One re-resize existed but fired
only on workspace transitions; nothing watched the container itself. A `ResizeObserver` now does,
skipping zero sizes deliberately (resizing at 0×0 bakes a NaN camera aspect — a failure this code
has already been bitten by). Verified live: canvas went from 0×493 to 1037×717, exactly the
container at this display's 1.25 device-pixel ratio.

This reaches real users, not just the dev preview: any viewer mounted before its container settles.

### Fixed — two toolbar registrations, and what the gate caught

The push/pull tool shipped in v0.3.821 was never added to `toolbarLayout`, so the bar logged
"not described by toolbarLayout" on every load; the plan pane had the same gap. Registering them
made the layout gate fail twice more, correctly: the icons I chose were not vendored, and promoting
push/pull to the primary bar pushed **Move** past the cap into More — the exact silent-demotion the
pinned-position test was written to catch. Both fixed; push/pull stays in More and on the rail.

### Changed — the verification skill contradicted itself

`verify-frontend` asserted the geometry stall in its frontmatter while its own body recorded the
stall as fixed in v0.3.703. The stale half is what got read, and it propagated into eight changelog
entries as a verification limitation. Corrected, with the diagnostic to run before anyone writes
that sentence a third time. **A caveat nobody re-tests becomes folklore.**

## v0.3.826 — the plan stops being a browser tab

### Added — R38-SYNC-VIEW: the drawing docked beside the model

"Generate plan (SVG)" has always opened a *browser tab*, so reading a plan meant leaving the model.
The plan now docks beside the 3D view and follows the level you are working in: change the active
level and it re-cuts, with scale controls and a pop-out for when a full window is genuinely wanted.

**What it deliberately does not do, and why that is stated in the tool's own tooltip: selection is
not synced.** The drawing pipeline discards element identity at bake time — it has the GlobalId in
hand and keeps only the class — so no polyline in the returned drawing can name the element it
draws. Clicking a wall in the plan therefore cannot select it in 3D, and highlighting a nearby
element by coordinate guess would be a confident lie about which wall you picked. Carrying that one
discarded value through the bake is now the roadmap's highest leverage-per-line item; selection sync
follows it.

The refetch rule is the tested part: only a change of CUT (level or scale) costs a drawing
round-trip, never a selection change — which is what makes the pane cheap enough to leave open while
modelling.

## v0.3.825 — width and length join the conversation

### Added — R38-LIVE-PARAMS slice 3: dimension chips over the new profile recipes

The Properties panel's geometry row gains W and L chips editing the selected element's rectangular
profile through the `set_profile_dims` recipe that landed server-side this afternoon — deferred
this morning precisely because chips over ONE editable parameter would have been theater; with
depth, width and length there is now a real system. The server's design decisions surface directly
as UI states: a non-rectangular profile (an I-section steel column) is *refused, not
reinterpreted* — which dimension "width" means on a fabricated member is not this UI's judgement —
and that refusal greys the chips with the reason. An empty chip edits nothing (an omitted dimension
comes back unchanged, never zeroed), and a publish flake leaves the chips editable to retry rather
than falsely unavailable. `authorAndReload` now reports its outcome (applied / refused / flake) so
callers can react to a refusal distinctly — existing callers are unaffected.

## v0.3.824 — slide it, watch it, let go

### Added — R38-LIVE-PARAMS slice 2: the depth slider with a live ghost

The Properties panel's depth field gains a slider: while dragging, an amber outline of the element
stretches from its own base to the candidate depth — the bottom face never moves, using the same
tested base-anchored transform as the push/pull ghost, so the preview agrees with what the recipe
will commit — and releasing the slider is the decision: commit through `set_extrusion_depth` on
release, no separate Apply step (the Apply button remains for the typed-number path). The range
spans collapse to triple the current depth; the slider stays disabled until the element's real
depth is known, so it can never commit a guess.

## v0.3.823 — a number for the hand that prefers numbers to handles

### Added — R38-LIVE-PARAMS, first slice: the depth field in the Properties panel

Select an element and its one server-editable geometric parameter — extrusion depth: a wall's
height, a slab's thickness, a mass's rise — appears as a field at the top of the Properties panel,
prefilled from the selection's bounding box, committing through the same `set_extrusion_depth`
recipe as the push/pull gesture. Two hands, one commit path: drag the handle or type the number,
the same GUID-stable edit lands either way. Non-extrusions are refused by the server through the
normal recipe error path. The rest of the LIVE-PARAMS item (sliders with local preview, constraint
locks as dimension chips, editable arrays, node-canvas room sliders) stays open on the roadmap.

## v0.3.822 — the stair tells you while you draw it

### Added — R38-STAIR-LIVE: the consequence, shown before the commit

While a stair or ramp run is being dragged out, the status line now says what *this* length means —
"stair 16 risers @ 0.188 · tread 0.300 ✓", or "✗ tread < 0.25 — lengthen the run" — live, against
the same limits the server reports, before any geometry is authored. The client mirror's constants
are pinned by test to the server's values and its sample cases reproduce the server test's own
numbers, because a drifted mirror showing green for a run the server calls out-of-limits would be
worse than no readout. Still a report, never a gate: the run authors exactly where it is drawn.

## v0.3.821 — the hero gesture: grab the top, pull

### Added — R38-PUSHPULL: drag a handle, the extrusion deepens

Select a wall, a column, a slab, a sketch mass — a single vertical handle appears at its top face,
and dragging it makes the element taller or thicker with a base-anchored amber ghost for feedback:
the bottom face stays exactly where the element stands and only the top follows the hand, because
that is what the commit will actually do. On release the gesture writes through
`set_extrusion_depth` — a recipe-parameter edit on IfcExtrudedAreaSolid.Depth, GUID-stable, psets
and references intact — never arbitrary mesh. Elements that are not simple extrusions are refused
by the server through the normal recipe error path, so there is no client-side allowlist to drift.

The safety rails are pure functions with their own tests: a fumbled click (sub-5 mm drag) commits
nothing, a hard downward drag clamps above zero instead of inverting the solid, and the ghost's
base-anchor invariant is pinned for every delta. Push/pull and move are mutually exclusive modes —
two gizmos on one bounding box read as noise.

Wave 1 of the Design Room ring is now fully shipped; what remains folded forward is the live
riser/tread readout while dragging a stair run.

## v0.3.820 — draw a stair where you mean it, type the length you think in

### Added — R38 Wave 1: dimension-first input, and the room's first stair

**R38-DIM-INPUT.** The typed-constraint box existed and nobody could find it: it appeared only
after the first keystroke of a grammar no screen ever advertised. It is now visible as a dimmed
hint the moment a run is in progress — *type a length — 6 · 12'6 · <30 · 6<30* — and the grammar
accepts imperial: `12'6` parses as feet-inches and the HUD echoes **3.81 m** back before the click
commits it, so the conversion is inspectable rather than trusted. Strict where it should be:
13 inches, a bare `'6`, a mid-token inch mark all refuse to parse rather than guess.

**R38-STAIR.** The room's premise-checked hole — no stair or ramp draw tool anywhere — is closed
end to end, by two sessions working one interface: server recipes for a straight-run stair and ramp
(flight and all, beside the railing recipe), and the two draw tools with SR / RP shortcuts. One
design decision worth naming: **the run is authored exactly where it was drawn.** Riser, tread and
slope compliance is *reported* (limits as arguable module constants, not buried literals), never
enforced by silently lengthening a run to somewhere the user did not put it — a stair quietly moved
to satisfy a limit no longer arrives where the drawing says it does.

Also: the parked prod-config CI item was split — the half needing no operator decision (smoke the
validator against a synthetic safe and unsafe posture) is unparked and claimed.

## v0.3.819 — a pending edit now looks pending, and a failed one says where

### Added — the Design Room ring (R38), and its first shipped slice

The Design room was inventoried tool by tool and set against what the research says makes authoring
tools feel learnable: a shape must respond in the same frame, everything must be learnable from the
cursor, parameters must stay alive after creation, and the sheet must be a working surface rather
than an export. The room is not behind on features — 14 draw tools, families with sized variants,
constraints, phasing, MEP, generated sheets, a full markup engine — it is behind on the first ten
minutes. The new roadmap ring sequences three waves against exactly that, and a premise-check en
route found a real hole: **there is no stair or ramp draw tool.** A user cannot author a two-storey
building without leaving the room; that is now a coded Wave 1 item.

### Fixed — the optimistic preview could not be told apart from the real thing

Placement drafting was already optimistic — an amber proxy the instant of placement, then an
incremental one-element preview of real geometry. But the moment that preview streamed in, the amber
marker was cleared: **real-looking geometry, indistinguishable from a committed element, for work
the server had not yet accepted.** The one rule the authoring-feel ring wrote down — *a pending edit
must look pending* — was being violated by the code built to satisfy it. The amber outline now
stays over the preview until publish completes: accurate shape, honest status.

And failure kept no trace: a failed recipe cleared every proxy and raised a toast, so the user knew
something failed but not **where**. A failed placement is information with a location. The marker
now turns red and stays until the next draft action — drawing again is the acknowledgement.

The proxy layer's state machine (pending and failed are mutually exclusive; shared materials reset
so a stale red cannot paint the next placement as pre-failed) is unit-tested headless and
mutation-checked in both directions. Honest limit, per the frontend-verification discipline: the
live draft path cannot be exercised in the dev preview (the geometry loader stall), so verification
is the state-machine tests plus typecheck and a production build — not a hand-driven placement.

### Fixed — a boot guard nobody could ever satisfy, from two correct changes colliding

The new multi-worker sidecar-lock refusal (right in itself: N workers on SQLite cannot serialise a
document-index write) asked a **live engine** for its dialect, while every sibling check in the
production guard reads the environment. Under the test runner the live engine is always SQLite, so
the "correctly configured production" fixture — Postgres URL, Redis, RBAC, real secret — was refused
anyway: a guard whose passing configuration was unreachable in-process. Worse, a transient DB blip at
boot would have read as dialect "unknown" and refused to start a perfectly configured Postgres
deployment. The guard now derives the dialect from `DATABASE_URL` — at boot the env var and the
engine name the same database, and the env var cannot blip. The live-truth surface stays on /health.
Three new cases pin the branch: declared-SQLite production with 4 workers refuses, a
driver-qualified `postgresql+psycopg://` URL counts as Postgres, one worker is always fine.

### Security — the deployment surface now says what it enforces

- **Content-Security-Policy** on the web image (`apps/web/nginx.conf`): scripts from self plus WASM
  compilation only — no inline, no eval — workers from blobs, frames from nobody else. A new gate
  (`apps/web/src/deploy/nginx.test.ts`, 12 tests) holds the two nginx header scopes identical (a
  location-level `add_header` silently drops the server-level set) and asserts the entry point has
  no inline script, so our own policy can never blank our own app.
- **Converter build stage off an EOL Node** (`services/api/Dockerfile`): node:25-slim (no security
  patches) → the same digest-pinned node:24 LTS the web image uses — one Node runtime across the
  product, matching the `engines` field both manifests already declare.
- **R39 DEPLOYMENT-TRUTH ring** added to the roadmap from an external engineering audit,
  premise-checked item by item: shared-store endpoint throttles, an app-boundary upload cap,
  keyboard journeys per room, viewer load-time observability, and the last god-file decomposition.

## v0.3.818 — the public demo never had the six numbers it promises

### Planned — ring R36: each room must be a product (from three user directives)

Audited first, planned second. **No tool is unassigned to a room** — the spine refuses to file a
destination without one and a test gates it; the real defect is that the left rail renders *every*
room's tool group with the current one merely opened, so scoping exists as disclosure rather than as
scope. **The drawings/specs dead end is real** — no back affordance, no route into the viewer; the
only way out is knowing the room tabs are the navigation. The ring: a back affordance ships first
and alone (S); the rail scopes to the current room with ⌘K as the everything-escape (M); drawings +
specs + model become one subapp with a mode switch and selection carried across modes by GlobalId
(L, sliced); the Author menu splits into Draw · Modify · Levels & Grids · Families with the proven
"More" tools promoted (M); and each room gains a per-role landing brief, one room per release, with
the Work room as the template it already is (M).

### Fixed — four endpoints the app requests on every page load were never captured

The Pages demo has no server: `demoData.json` is a captured `{ "GET <path>": <body> }` map, and it is
the entire backend a visitor talks to. When the shell asks for a path the capture lacks, nothing
breaks — the client falls back, the panel draws its empty state, and the page looks fine. That is the
failure, not an exception to it.

Measured against a live browser session, **four endpoints requested before a visitor clicks anything
had never been in the crawl**: `/vitals`, `/work-queue`, `/jobs` and `/presence`. The vitals strip is
the walkthrough's own headline claim — *"the same six numbers follow you into every room"* — and on
the public demo those six numbers were not there, and had not been for 25 releases. The work queue,
which the product calls the daily home, opened empty for everyone.

Why it went unseen is the interesting half: the dimension anybody would think to check was
**perfect**. The demo's module registry matched the repo exactly, 133 to 133, zero drift. A capture
can be exactly right about the thing you measure and blank on the thing the user sees first.

`build_demo_data.py` already carried this lesson, in a comment explaining that `/rooms` had rotted
the same way and for the same reason. A lesson written as a comment protects one endpoint;
`demoData.test.ts` now protects the set — asserting presence *and* substance, because a fixture
captured as `{}` renders exactly like a missing one. The vitals fixture must carry all six named
numbers; the work queue must actually contain work.

### Changed — the roadmap says what is left, not what was done

341 lines of finished narrative moved to `roadmap-completed.md`: the R32 filing spine, R33's clawback
fix, R34's takeoff research and the whole of Band 3, which closed five items without a single build.
They are moved **whole, not summarised** — each records *why* something closed, and several closed
because the capability already existed. That reasoning is the part worth keeping.

The three priority bands are re-seated on what is true today rather than on what was true when they
were written:

- **Band 1** now holds the two seams the race sweep found — the cross-process sidecar lock and the
  snippet sandbox — ranked first for a specific reason: **nothing in the suite fails if either
  regresses.** FIN-SUITE-BLIND, which occupied this band, is closed.
- **Band 2** ("built but unreachable") names R31-CITE-HIGHLIGHT, where both the data half and the
  locator shipped and *nothing calls them* — the citation panel still drops the `doc_id` the server
  sends. Listing our own unreachable code in the band about unreachable code is the point of having
  the band.
- **Band 3** proposes three fresh gap-checks, each phrased so the check itself is the deliverable —
  two of them asking whether fields added last week (`suggestion_clears_horizon`, `nothing_renovated`)
  are rendered anywhere, since a field nobody displays is a field nobody reads.

## v0.3.817 — a lock the backend ignores, and a job that could run twice at once

### Fixed — two concurrent creates could mint the same record number

Human refs (RFI-001, PCO-014…) were allocated by reading a counter row under `FOR UPDATE`, adding
one, and writing it back. Correct on Postgres. **SQLite treats `FOR UPDATE` as a no-op**, and SQLite
is a supported deployment backend — so two concurrent creates both read n=1, both wrote n=2, and two
different records went out into the world as RFI-002. Not theorised: the new race suite produced the
duplicate with four concurrent creates the first time it ran. A lock the backend ignores is worse
than no lock, because the code reads as protected.

The increment is now a single atomic `UPDATE … SET n = n + 1 … RETURNING n`, which both backends
serialise natively. And the one moment no row mechanism can cover — two writers seeding the counter
for a project's first-ever record — now loses gracefully: the primary key refuses the second seeder
inside a savepoint and it retries against the winner's row, where before the refusal escaped as a
500 on an ordinary "create a record" call.

### Fixed — two workers sharing a database could both run the same job

The queue claimed work by reading the oldest queued row and committing `state = "running"` — so two
processes on one database (multi-worker serving, or two dev servers on one file) could both claim
one job and execute its handler **concurrently**. The handlers-are-idempotent contract covers a
crash-recovery re-run; it says nothing about two copies interleaving live, which for a mutating job
means two writers in the same project separated only by an in-process lock that cannot see the
other worker. Claiming is now compare-and-swap — `UPDATE … WHERE state = 'queued'` has exactly one
winner across every worker combined — and a loser advances to the next queued job rather than
concluding the queue is empty.

`test_race_conditions.py` proves both properties deterministically (the losing interleavings are
constructed by hand, not hoped for from thread timing) and adds barrier-released thread rounds on
top; reverting either fix fails it. The honest limit is stated in the file: the suite's backend
serialises writers, so what is proven is the invariant and the recovery path, not a Postgres
collision.

### Added — secret scanning as a suite gate, where checks actually get seen

From the external security audit: seven credential patterns (key blocks, cloud keys, token shapes)
at zero tolerance over every tracked file — as a test in the ordinary suite, **not** a
paths-filtered workflow, because a paths filter is exactly how the lockfile gate sat red and unseen
for three releases. The two documented dev constants the production guard exists to refuse are
pinned to an allowlist of the files where they are the *subject*; every allowlist entry is asserted
individually live, and the patterns themselves are proven against synthetic positives so a
regressed regex cannot pass as a clean repo.

The audit's remaining findings are triaged in the roadmap's new R35 ring. Its top "critical" —
that the dev auth secret boots unguarded in production — was already false: the production guard
refuses any server-database or declared-production boot with a default secret, RBAC off, a trusted
identity header, or default object-store credentials, and has a test. An audit that misses an
existing control still says something useful: the control was hard to find.

### Settled — the one non-Python server component, on purpose

Everything server-side is Python except the Fragments converter, and that is a constraint, not a
preference: the Fragments serializer exists only in the JS kernel libraries, so the converter stays
an isolated Node CLI invoked as a subprocess. Recorded in the roadmap so nobody rewrites it into a
worse Python one, and revisited only when a Python Fragments writer exists upstream.

## v0.3.816 — the lockfile pinned versions its own requirements file forbade

### Fixed — production installed packages the input file said were too old

`requirements.in` is the input to pip-compile; `requirements.lock` is what CI installs
(`--require-hashes`) and what the container image installs. Nothing installs the `.in` file, so
nothing was checking that the two agreed — and they did not:

| package | `requirements.in` required | the lock pinned |
|---|---|---|
| `fastapi` | `>=0.140.7` | **0.139.0** |
| `anthropic` | `>=0.120.0` | **0.116.0** |

Dependabot raised both floors and both PRs merged; neither regenerated the lock. So the lock pinned
versions *below its own stated minimum*, and every test run and every container built from it used
the older packages while the requirements file sat in the repo saying, truthfully but
ineffectively, that they were too old. **A floor nobody enforces is a comment.** The lock is
regenerated from the prod interpreter, which changes exactly six lines.

### Fixed — the gate that would have caught it only ran where nobody was looking

`lockfile.yml` does check this properly, by recompiling in the production image. But it triggers
only on a manual dispatch or a push touching the requirements files — so it fired on the Dependabot
PRs, failed, and was merged past; and afterwards no ordinary push re-ran it. It surfaced only
because it *also* fires on tag pushes, where three consecutive releases failed a job that never
appeared in the branch's checks.

`test_lock_satisfies_requirements.py` is the always-on half. It cannot recompile — no network, no
production interpreter — but it can compare what the lock **pins** against what the input
**requires**, on every suite run, and it names the regeneration command when it fails. The
recompiling workflow stays the authority on resolution; this is the tripwire.

Parsing both sides identically turned out to be the whole difficulty: pip-compile writes extras into
the lock too (`psycopg[binary]==3.3.4`, `uvicorn[standard]==0.51.0`, `sentry-sdk[fastapi]==2.66.1`),
and a first pattern that stopped at the bracket reported all three as **missing from the lock** —
three false alarms of the most alarming kind available, on packages that were pinned correctly the
whole time.

### Added — a citation can find its passage without editing vendored code

R31-CITE-HIGHLIGHT's remaining half was recorded as blocked on a real decision: highlighting needed
an entry point from `apps/web/src/vendor/massingpdf/`, which is carried verbatim from a sibling repo,
so an edit there is lost on the next re-vendor or has to go upstream first.

The decision is not needed. The vendor's public index already exports `splitWords` and `unionBox`,
and its search plugin exports `findInWords` — a pure function from words to boxes. Only the visual
flash is private, and drawing our own is a few lines. `drawings/citeLocate.ts` therefore composes the
locator entirely from the vendor's **public** surface: no vendor edit, nothing to send upstream, and
a re-vendor cannot silently drop it.

The hard part is not the lookup. The citation's text came out of **pypdf**; the page's words come out
of **pdf.js**, and the same paragraph does not survive both readers identically — whitespace differs,
and ligatures, soft hyphens, non-breaking spaces and curly quotes survive one reader and not the
other. An exact match therefore fails on ordinary input while looking exactly like "the passage isn't
on this page". Matching degrades on purpose and reports which rung matched, so a weak hit is not
presented as a strong one; a passage occurring twice is flagged ambiguous rather than silently boxed
at its first occurrence; and when nothing matches it returns **nothing**, because boxing an arbitrary
region would be worse than a page number — the reader would trust the box.

Three defects in the first draft of that module were found by review and are fixed here, each worth
recording because each *looked* right:

- **Normalisation was applied to the query only.** The page words were searched raw, so folding a
  curly apostrophe in the query while the page still contained one guaranteed a miss on a passage
  that would otherwise have matched. The punctuation handling could subtract matches and never add
  one. Both sides are folded now, with the words keeping their original geometry so the box is real.
- **The test fixture contained none of the punctuation its own header claimed to test**, so the
  suite was structurally unable to see that. The fixture now carries curly quotes, an em dash, a
  soft hyphen and a non-breaking space — and reverting the fix fails exactly four tests.
- **The fallback ladder was built on a false premise.** The module asserted that `doc_text` wraps
  snippets in ellipses, and trimmed both ends and sampled the middle accordingly. It does not: it
  truncates with a plain prefix (`text[:500]`, then `snippet[:200]`), so damage is **tail-only** and
  the head is exactly what the document says. The ladder now trims the tail and samples the head —
  the one region truncation cannot have touched.

Also fixed: the page-words cache was keyed by page number alone, so after a second document loaded,
page N was served from the first — a box drawn confidently over the wrong file. It now keys on
document identity and exposes `clear()`.

**This module is not yet reachable.** The citation panel still renders its source as inert text and
its local type drops the `doc_id` and `span` the backend already sends, so wiring is a second seam
fix rather than a call. Stated plainly because counting an engine nothing calls as shipped capability
is this repo's most repeated mistake.

## v0.3.815 — three of seven rooms were named once and never explained

### Fixed — the product tour listed rooms it never visited

The walkthrough is the document a new user follows, and a gate already required it to name every room.
It did — in one headline line — and that was the whole of the coverage for three of them. Counted:
`planning`, `work` and `operate` appeared **once each**, in the room list, and nowhere else, while
`cost` appeared eleven times. A reader was told the room exists and never told what it is for, which
is the documentation form of a tab that highlights but does not navigate.

The click-through now visits all three with their shipped job statements — Planning takes a quantity
off the model and turns it into a number somebody has agreed to; Work is the ball-in-court queue,
a filter across every subject rather than one of them; Operate carries handover into the asset
register, the condition assessment and the reserve study.

Two gates close the hole rather than the instance. **Order:** a doc that *lists* the rooms must list
them in shipped order — count and membership were already checked, but order is what a reader follows,
and a doc can name all seven correctly in the wrong sequence. **Substance:** every room must appear in
the walkthrough somewhere beyond the enumeration, so a single line can no longer stand in for a tour.

The order gate's first draft used a proximity window and failed on writing that was correct: it read
the click-through's *route* ("Schedule → Budget … back in Design … the Cost room") as a claim about
tab order. It now matches only verb-free lists. A gate that can be satisfied by rewriting good prose
is worse than no gate — the same correction the comparative-names pattern needed one release ago.

## v0.3.814 — a reserve suggestion that did not clear its own horizon, and a gate that checked a third of the repo

### Fixed — the suggested reserve contribution was not solved, it was guessed at

A reserve study answers one question a board actually votes on: *what flat annual contribution keeps
this fund solvent?* The answer was produced by a binary search that bracketed the requirement between
zero and a generous upper bound, halved forty times, and returned the bound — **without ever checking
that the bound it started from was reachable**. Against an opening deficit it is not. A property
carrying a £500k shortfall and one £80k component got back a confident £80,001 a year, and re-running
the same study at exactly that contribution came back underfunded from year one. A suggestion that
does not clear its own horizon is worse than no suggestion; it is the number somebody funds to.

There was never anything to search for. Staying solvent through year *k* means the contribution must
cover the cumulative outflow to that year less the opening balance, spread over *k* years — so the
requirement is simply the largest of those, computed directly and exactly. The study now solves it,
then re-runs the schedule at its own answer and reports `suggestion_clears_horizon` so the claim is
verified rather than asserted. The same fixture that used to pass with any of a hundred thousand wrong
answers now pins the exact figure, and asserts that one pound less does **not** clear.

### Fixed — a component with no install date was quietly assumed brand new

An asset carrying a replacement cost and an expected life but no install date was projected as if it
had been installed this year: the most optimistic reading available. A twenty-year component
contributed nothing at all to a twenty-five-year study while still being counted as a complete
component, and `components_missing_data` stayed at zero.

It is still projected — dropping it would understate the requirement harder — but it is now named.
`components_without_install_date` counts them, the names are listed, and the note says plainly that
the earliest replacement year is an assumption rather than a record.

### Fixed — the no-comparative-names gate read markdown and called it the repo

The gate that keeps competitor product names out of public surfaces says, in its own words, that
there is no legitimate sentence in this repository containing the hard-banned ones. It was reading
README, CHANGELOG and `docs/` — about a third of the repo's sentences — and reporting OK. This is a
public repository: a docstring and a `//` comment ship exactly as far as a README does.

Seven hard-banned mentions were sitting in shipped source, and one engine docstring named a
competitor *as a competitor* while the same sentence already named the capability. All eight are
rewritten as the thing they describe. The hard ban now covers `.py`, `.ts`, `.tsx`, `.js` and `.json`
as well — vendored trees excluded by path, because those are carried verbatim and rewriting a comment
in one would turn an upstream re-sync from an overwrite into a merge — and comparative *phrasing* gets
a second down-only ratchet with its own baseline, so a doc rewrite can never pay for a new comment.

Two traps the widening exposed, both fixed rather than worked around. A false positive
("…round-trips into BIMcollab like any other issue", where nothing is being compared) was fixed in
the pattern instead of grandfathered — a baseline that carries false positives teaches the next
person to add a key instead of rewriting the line. And the vendor exclusion was asserted non-empty
over the whole list while one of its paths did not exist, so fifteen vendored files were being
scanned on the strength of a different path matching; every prefix is now asserted individually,
because an aggregate check cannot see a dead entry beside a live one.

## v0.3.813 — a value-add premium that starts before the unit turns, and the fractional gap three more defects hid in

Four commits. The proforma gains the phase it was missing, and a race test is fixed by the same
distinction it exists to document.

### Added — a value-add renovation programme, unit by unit

Buying at in-place rents and renovating over time is the mechanic three of the surveyed multifamily
models turn on, and nothing here modelled it. A unit now has the three phases it actually has: it
earns its in-place rent until work starts, **nothing** while it is being renovated, and the renovated
rent only from the month it comes back online.

**Applying the premium from day one is the single most common way a value-add deal is overstated**,
and it is invisible in the output — it produces a smooth, plausible income curve that is simply too
high, too early, across the whole hold. Skipping the vacancy makes the programme look like capex only.

The renovation pace and the per-unit downtime are **required and never defaulted**. Without them the
model either renovates everything instantly or costs only its capex, and either result is
indistinguishable from a correct one. Stating zero downtime is accepted — it is then a choice somebody
made. A unit type with no renovated rent is not renovated, and is named with its count, because
inventing a premium there would invent the investment thesis.

`POST /projects/{pid}/proforma/renovation`.

### Fixed — three renovation-schedule defects, every one invisible at whole numbers

The module above was reviewed after it landed, and three defects turned up. What they share is the
reason they survived: the original fixture used a whole-number pace and a whole-number downtime, and at
whole numbers the correct arithmetic and the broken arithmetic agree exactly. All three lived in the
fractional gap between them.

- **A renovation pace below one unit per month renovated nothing at all.** Half a unit a month rounded
  down to none, every month, for the entire hold — while still reporting a completed schedule, a full
  month-by-month table, and a premium of zero. "One unit every two months" is an ordinary pace for a
  small property. The pace now carries its remainder, so a half becomes one unit every second month.
- **A stated half-month of downtime became no downtime.** The rounding sent 0.5 to zero, deleting the
  vacancy that is the whole cost of a renovation programme, while sending 1.5 to 2 and 2.5 back to 2.
  Downtime now rounds up and never silently to nothing; an explicit zero is kept, because that is a
  choice somebody made.
- **With zero downtime a unit was counted as finished and under renovation at the same time, for the
  rest of the schedule.** It earned the renovated premium while also being charged its full vacancy
  rent, every month — on ten units, half a million of vacancy the programme never suffered. Each
  counter looked reasonable on its own; only adding them together against the unit count reveals it,
  and nothing added them. That sum is now checked.

### Fixed — three defects in the step-up race harness, two of them the shape it documents

The test that proves a single-use seal token cannot be redeemed twice had defects that would have let
it pass while proving less than it claimed. Details in the commit.

### Also in this release

The agent-harness scaffold is now ignored, so a `git add -A` cannot publish it.

## v0.3.812 — an explicit zero was read as "unset", and a check that only ever ran one way

Four correctness items, and the two findings worth reading are both about a value that looked like an
absence.

### An explicit 0% retainage had 5% withheld anyway

A schedule-of-values line can legitimately hold no retainage — stored materials, a line the owner has
released, a fully-bonded subcontractor. The engine read that explicit **0%** as "not set" and applied
the 5% default instead, withholding **$1,000 on a $20,000 line**. Nothing looked wrong: the pay
application balanced, the arithmetic was self-consistent, and the contractor was simply underpaid by a
number that reads as ordinary.

It surfaced while closing a different gap. **G702 line 7 — the retainage held in prior periods — was
asserted in no test anywhere**, which is why a 10%-retainage contract had previously been able to
report a *negative* payment due while the suite stayed green. Lines 5 through 8 are now value-checked
against a fixture built to **distinguish**: mixed per-line rates of 10%, 5% and 0%. At a single default
rate the correct calculation and the broken one agree by coincidence, so every earlier fixture passed
against both — which is what made the defect invisible rather than merely untested.

### A field that was always empty, and the check that could not see it

`GET /modules` had been serving a `relations` list to every client since the module system's first
release. No module declared it, no schema defined it, nothing populated it and nothing read it: it was
an empty array, always. Cross-module links have shipped all along as reference **fields**, which 85
modules use. It has been removed rather than wired — a field that is permanently empty teaches every
client to ignore it, which is how a real value later goes unnoticed.

The completeness check that should have caught it only ever ran one way: it asked whether everything
*declared* was *served*, and never the reverse. It now asks both, and found a second case on its first
run — one that turned out to be legitimate, and is now recorded as such with its reason. Distinguishing
"computed elsewhere" from "dead" is the whole job; from one side they look identical.

### Fixed

- **A module's evidence requirement is now stated in advance.** Some registers require a photo or
  attachment before a record can be signed off, enforced on the server. The client was sent that rule
  but never showed it, so the first a user knew of it was a rejected action. The status menu now marks
  those transitions *(needs an attachment)*.
- **A step-up authorisation is proved to survive exactly one concurrent use**, not merely one repeated
  one. The single-use guarantee was previously demonstrated only against sequential replay — which the
  design it replaced would also have passed.

## v0.3.811 — three finance answers learn to refuse, and the server starts answering spatial questions

Three pull requests and a sibling-repository import. Two themes, and they are the same theme at
different layers: **an answer should say what it is, and decline when it cannot**.

### Lease rollover is priced, and its two riskiest assumptions cannot be defaulted

`GET /projects/{pid}/proforma/rollover` prices what a property's lease expiries actually cost over the
hold — downtime, tenant improvements and leasing commission, split into the renewal and new-tenant
futures and weighted by renewal probability.

**`renewal_probability` and `downtime_months` are required and are not defaulted.** Assuming every
tenant renews, or that a vacated suite re-lets instantly, deletes the exact risk being priced — and a
deal with those defaults applied is indistinguishable in the output from one that genuinely carries
neither. Omit either and the endpoint returns `assumptions_incomplete`, naming what is missing. A
renewal probability outside 0–1 is treated as unstated rather than clamped, for the same reason: a
clamp invents a number the caller never gave.

Downtime is charged to the **new-tenant branch only** — a renewing tenant does not vacate. Charging the
gap to both branches is the most common way a rollover total is overstated, and it overstates in the
direction that reads as conservatism. Leases with no usable end date are listed by name rather than
skipped, because a silently dropped lease shrinks the exposure and flatters the deal.

### Operating income says where it came from

`GET /projects/{pid}/proforma/income-basis` derives operating income from the property's own lease
records — in-place base rent, expense recoveries and concession load kept as separate lines — instead
of accepting one blended figure for the whole asset. Pass `declared_annual` and it reports both with the
gap between them. That disagreement is the output, not an error.

An empty rent roll returns `unavailable`, never an income of zero. A property with no lease records has
**unknown** income, and zero is the one value that reads as a measurement.

### The server can now answer spatial questions, and export a triangle budget

Broad-phase clash used to build a full N×M boolean matrix over both sides: correct, and 2.5 × 10⁹
booleans on a 50k × 50k federated test, allocated before the narrow phase does any work. It now builds a
bounding-volume hierarchy above a measured size threshold and descends both trees together.

Both paths are kept, because a BVH is not free. The crossover was **measured, not assumed** — at
800 × 800 the matrix still wins; the tree pays off from roughly 1,000,000 box pairs, reaching 2.7× at
4k × 4k and 4.1× at 8k × 8k. A first draft of the threshold was four times too low and would have made
every mid-size clash slower. Both paths are asserted to return the same clash **set**, so the choice
changes cost and never answers.

glTF export gains an optional per-class triangle budget by vertex-clustering decimation, so a consumer
can ask for a model that fits rather than the model that is. It is off by default — decimation is lossy,
and coordination and takeoff want the real geometry — and it never empties a class, because losing a
whole discipline from an export is worse than a coarse one and looks like success.

### Added

- **Scene packages** — `GET /projects/{pid}/scene/manifest` and `/scene/package`. A model's semantic
  half as a portable document: GlobalId-keyed nodes, property sets, typed relationships and precomputed
  by-class / by-level indexes, with geometry carried **by reference as Fragments** rather than
  re-encoded. Deterministic: the manifest is derived from the source model's own timestamp, so an
  unchanged model produces an identical document and its content hash means something.

  This does not make the application load faster and is not offered as if it does — the web client
  already receives class and storey per element. It is for consumers that are not the web client: an
  engine importer, a Blender add-on, a CI check, a native viewer, whose only alternative today is
  parsing the IFC themselves.

### Fixed

- **The drawing-review engine carried a permission bypass.** Its markup store checked one capability per
  change, so a change bundling a status update with an edit was only ever checked against the status
  permission — letting a reviewer allowed to close an issue, but deliberately not to reword it, do both
  at once. Not reachable in this build (the application imports only the document reader, and
  client-side policy is not the authorisation boundary here), but taken now rather than inherited later
  into a planned migration. The same update fixes an import count that reported markups *attempted*
  rather than accepted — so a user without permission saw "Imported 47 markups" over an empty store —
  three OCR defects, and accessible labels that suppressed the row text they were meant to describe.
- **`GET /modules` silently dropped two declared keys**, one of them enforced elsewhere: the response
  was built from a hand-maintained allowlist, so any key added to the schema was omitted until someone
  remembered. It now serves what the schema declares, and a completeness check fails when they disagree.
- **The roadmap lane gate was searching the table it was validating**, so every lane item satisfied its
  own existence check and the gate had never once been able to fail.
- **The documentation-citation gate could not see its most precise citations** — references carrying a
  line number, symbol or anchor did not match, leaving 21 files unchecked while the gate reported a
  confident count. Its floor is now a per-document ratchet: one total let a single document's
  contribution fall to zero while the others held the number up.

## v0.3.810 — four hand-maintained lists become checks that fail, and a third route learns that identity is not authority

Twelve commits, five pull requests, three sessions. The theme is one the last two releases have been
circling and this one makes explicit: **a rule kept as a list is a rule that drifts.** Four separate
lists in this release stopped being memory and started being tests.

### Fixed — a platform-global mutating route shipped with no gate

`POST /pipeline/allocate` guarded with `Depends(current_user)`, which **identifies without
authorising**: with RBAC on and no credential it returns the literal string `"anonymous"` and the
handler proceeds. This is the **third** appearance of that exact defect — the seal routes in v0.3.807
returned a rendered Professional Engineer seal to an unauthenticated caller for the same reason, and
the firm-standards library was writable by any project admin for a related one.

`require_role` is the *wrong* fix on a global route: its signature takes `pid`, so with no `{pid}` in
the path the framework turns it into a **caller-supplied query parameter** and the caller chooses
which project's role is checked. `require_identified` is the platform-global sibling and the correct
gate.

**The prefix gate added in v0.3.808 is what caught it.** `/pipeline` was a new top-level prefix, and
the coverage check refuses to let a new prefix opt out of the RBAC middleware unclassified. That gate
existed for exactly one release before it earned itself.

### Added — choosing which projects to fund, not just ranking them

The portfolio view ranks buildings worst-first and advises funding those first. That is a greedy
heuristic, and greedy is the thing that is *nearly* right: it loses whenever one high-return project
crowds out two smaller ones that together beat it. **Ranking is not selection.**

Given candidate projects with a cost and a value, and a capital constraint, `POST /pipeline/allocate`
returns the subset with the highest total value — an exact optimum, not an ordering.

**You cannot fund 60% of a building**, so the allocation is a whole-project decision and never a
proportional one. The most likely way a capital tool produces a confidently wrong number is by
answering the easier fractional question instead: it converges, returns a plausible total, and nothing
in the result says the answer was not buildable. Every way this can fail to produce a real answer says
so instead:

* a project that cannot fit even with the entire budget is **named**, with how far over it is, rather
  than quietly excluded alongside projects that lost on merit;
* a candidate with no stated value is **refused**, not treated as worth zero — a value nobody supplied
  is the one number that must not be inferred here, because it decides what gets funded;
* if no optimum can be computed, the result says so and returns **no selection**. A ranking is never
  substituted: it is a different decision, and returning it under this endpoint's name would give it
  authority it has not earned.

The result reports what the ranking would have chosen alongside the optimum, and the value forgone
between them. **A difference of zero means these candidates have no crowding-out between them — not
that the ranking is safe in general.** Alongside the chosen set it reports what was displaced, its cost
and value, why, and the capital left unspent, so the decision can be reviewed rather than trusted.

### Changed — every room's sections, and a taxonomy nobody had counted

`Field` (14 modules), `Preconstruction` (12), `Facilities`, `Cost` and `Schedule` are retired as
section names. **53 modules re-sectioned** into groups named for the job rather than the place:
Daily Log · Progress · Logistics · Bidding · Estimating · Project Governance · Sequencing · Resourcing ·
Billing · Budget & Actuals · Change Instruments · Maintenance · Condition & Capital · Performance.
No section now exceeds 8 modules, and none repeats its room's name.

`change_event` moved to Change Management — it is the first link of the change chain and was filed
apart from the rest of it. `punchlist` and `checklist` moved to Quality, beside `deficiency` and `ncr`.

### Fixed — 11 reports were filed under sections that no longer exist

Report categories are an **independent taxonomy** from module sections, rendered in a different panel,
which is why nobody had counted them. Three of them named retired sections, and a report string still
directed users to a route that had moved. A report category must now be a live section, a room label,
or one of five explicit purpose categories — enforced by a test, and deliberately *not* forced into
agreement with sections, because grouping by audience is a legitimately different axis from where a
register lives.

### Added — reference columns, and nine fields that stopped being retyped

A line-item table row can now **link to a record in another register**. A stored value the picker
cannot resolve is preserved and marked rather than silently replaced — inside a `<select>` an
unresolvable id is not a bad label, it is **data loss**, because the next save writes the blank over
the link.

Nine plural fields became tables of links rather than free text somebody retypes: `spec_sections`
(bid packages, bulletins), `photos` (daily reports, incidents, inspections, punchlists),
`deficiencies` (commissioning), `deliveries` (daily reports), `assumptions` (project charters).

### Changed — two more standing rules became tests

- **Competitor names in public docs.** The rule allowed them for interop and forbade them for
  comparison, and nothing checked which was which; twelve comparative mentions had accumulated. Two
  names are now hard-banned, comparative *phrasing* is ratcheted **down-only**, and six legitimate
  interop mentions are asserted **present** — so the gate cannot be satisfied by deleting the
  integrations it exists to protect.
- **The gates the project's own instructions name.** The section arguing *"if a rule matters, write it
  as a test"* listed four checks by name; two were wrong — one had never existed, and one named a file
  that does not exist while the capability does, under another name. Its own list had drifted. The
  names are now asserted against the filesystem, across both standing docs rather than the one that
  happened to break.

### Fixed — the test manifest could lose a suite silently

The runner filtered its own registration list down to entries whose file existed, so a registered test
that was deleted or typo'd was **dropped without a word** and the run still reported "N/N suites
passed". **A count that shrinks silently reads exactly like a clean run.**

The manifest now enforces a 1:1 map in all three directions — no name registered twice, every
registered name has a file, every test file is registered — and reports every problem at once rather
than one per full-suite round trip.

*(The duplicate registration originally reported did not exist: the check that found it scanned every
quoted name in the file rather than the registration list, so it matched functional code. Chasing a
false positive is what surfaced the real hole, which ran the other way.)*


## v0.3.809 — the non-negotiable becomes a check that can fail, and a pay application stops going negative

Eleven commits from three concurrent sessions. The theme is not planned: four of these are a *stated
rule* or a *stated number* that nothing was actually enforcing, found by making the rule executable.

### Fixed — CURRENT PAYMENT DUE came out negative

The AIA G703 continuation sheet retained each schedule-of-values line at **that line's own**
retainage percentage; the G702 certificate applied the **global default** to the aggregate. Any
contract not on the default made lines 5 and 7 disagree. On a 10% retainage contract with $50,000
completed and nothing this period, **line 8 — CURRENT PAYMENT DUE — came out at −$2,500**, and
closeout reads line 8 for the final-payment amount.

The existing cost test contained **no assertion on line 7, line 8, or retainage at all**. It was not a
weak test of this behaviour; it was structurally unable to see it. Line 7 now deducts what was
actually *certified*, read from the prior stored application rather than recomputed.

### Added — a pay application is a claim made on a date, not a live view

The G702/G703 pair was assembled on every read, so the certificate moved whenever the SOV moved.
`POST /cost/pay-application` now **freezes** the continuation sheet and lines 1–9 into an owner-invoice
draft; editing the schedule of values afterwards cannot restate an application already submitted.
`GET /cost/g702` stays live, because "where do we stand today" is a real question — it is just not a
certificate.

### Added — MOD-GUID: the first non-negotiable, as a check that can fail

The project's own first rule is *reference model elements by IFC GlobalId, never by transient viewer
IDs*. The three fields that store one were plain text, so a viewer id, `"TBD"` and a truncated paste
were indistinguishable from a real GlobalId. **The rule existed only as prose, and prose cannot fail.**

Format is now validated on write — 22 characters over `[0-9A-Za-z_$]` — in the one layer that can tell
a GlobalId from the id the rule forbids. Two further defects came out with it:

- **Two stores held one fact.** An element claim checked the `element_guids` column *or* the `guid`
  field, so a record could be anchored to element A by its column and element B by its field, each
  consumer correct about a different element. It also read only the singular `guid`, so plural fields
  never matched at all. The column is now a superset on create *and* update, and the claim asks the
  schema which fields hold a GlobalId rather than naming one.
- The update arithmetic subtracts what the record's own fields contributed *before* and adds what they
  contribute *now* — not a blind union, which would accumulate stale anchors forever.

### Fixed — the demo shipped the first non-negotiable being broken

CI caught this, and it is a better finding than the change that exposed it. The demo seeder falls
through to prose for any text field it does not recognise by name, so the demo project every new user
opens contained:

```
field_verification.guid = "Level 2 slab 1"
material_request.guids  = "Chiller plant — closeout noted during the weekly walk…"
```

A filing accident dressed as data, in the one place chosen to represent the product. Seeded GlobalIds
are now real 22-character compressed ids, deterministic from the same hash as every other seeded value
so a re-seed stays byte-identical and a captured snapshot stays stable. **Which fields need one is
asked of the schema rather than re-listed** — the whole point of MOD-GUID is that this has one
definition.

### Added — a section carries its layer build-up, and says when the model disagrees with itself

**R21-DIM-COMPONENT.** The floor-to-floor chain answers "how high". A fabricator asks "made of what,
how thick" — and a section showing one 300 mm overall figure cannot be built from. Every assembly the
cut passes through now carries its material-layer breakdown, each band drawn in **proportion**, so a
12 mm board beside 150 mm of insulation reads as the sliver it is rather than as an equal stripe.

The load-bearing part is the **disagreement**. What the layer set *declares* and what the geometry
*measures* are two different claims. A layer set summing to 300 mm on a wall modelled at 250 mm means
the drawing and the specification disagree, and there is no basis for preferring either — so the sheet
prints `! modelled 250 (-50)` rather than reconciling them. Printing the declared total silently is how
a trade builds to a number nobody checked.

Three further refusals, each of which would otherwise produce data-shaped nothing: an element with no
layer set is **absent**, not fabricated from its overall thickness; a layer with no stated thickness
makes the total **unknown**, not a confident under-count of the layers that happen to state one; and
assemblies past the display limit are **counted on the sheet**, because a truncated list that says
nothing reads as complete.

### Added — a production line now says HOW its cost code was matched

Cost codes match by IFC class **including inherited classes**, so one code can be reached through more
than one key: some elements matching a key that names their own class, others priced through an
ancestor. Reconciliation aggregates by cost code, so those were summed into a single confident
quantity with nothing to distinguish them.

A quantity matched by inheritance is a **weaker claim** than one matched exactly — the cost map did not
name those classes, so it may be pricing element types the estimator never had in mind — and that
difference disappears the moment the quantities are added together.

Each reconciliation line now reports its match basis (`exact` / `inherited` / `mixed`) and the keys
behind it, and the affected codes are **named** at the top level rather than counted. Where the takeoff
never stated how it matched, the basis is **unstated rather than `exact`**: reading silence as the
strongest available claim is how a weak number gets quoted as a strong one.

A blended basis is a caveat on the quantity, not a refusal — the total is still correct, it simply
rests on two different strengths of claim. That is the difference from a unit mismatch, where no
correct number exists at all. (This completes the cost-map fix shipped in v0.3.808: that one made the
walls *price*; this one makes the line say the map never named their class.)

### Changed — a junk-drawer section is worse than a flat list

**R31-DESIGN-GROUPS.** The plan for this said the Design room was 32 modules in one flat list. It was
not — the rail has grouped registers by section for many releases, and reading the renderer is what
corrected the premise. What was actually broken was what the groups were **named**.

Design's largest group was `Engineering`: nine modules spanning drawings, issuances, RFIs, submittals,
selections, design reviews, envelope assemblies and MEP equipment. That is not a section, it is where a
module went when nobody decided. `Design` — as a section *inside* the Design room — carried no
information at all.

**A junk-drawer section is invisible while nothing groups by it.** The moment the rail rendered
"Engineering · 9" as a heading, it became a confident label for a filing accident, which is worse than
a flat list because it looks like somebody decided. 17 modules re-sectioned and four sections retired;
Design now reads Coordination 8 · Design Phases 4 · Drawings 4 · Model 4 · Information Management 3 ·
Resilience 3 · Specifications 3 · Sustainability 3.

### Changed — internal

- The IFC class-chain lookup behind cost-code matching is now memoised. **This is a consistency change
  and claims no speedup:** measured on a 10,001-element model the walk is 0.92% of a first takeoff and
  the cache recovers 0.5% of that, and takeoff results are themselves cached per file so even that is a
  first-call cost. An interim measurement on a 154-element model suggested 6.44% and did not survive
  scale — that model's takeoff does almost no geometry, so a fixed per-element cost looked large
  against nothing.
- `eslint` 9.39.5 → 10.8.0 (dev dependency).


## v0.3.808 — measure the model, price the model, file the model: provenance from the traced region to the controlled folder

Thirty-eight commits, batched — a single working day's output, and more than one release should carry.
Everything below landed within about nine hours of v0.3.807, which is the honest reading: not a long
silence, but a day of work that outran its release. A green suite is not a shipped thing.

### Fixed — a cost map keyed `IfcWall` priced none of the walls

`qto.takeoff` matched cost codes with `cost_map.get(el.is_a())` — an exact string match against the
**concrete** IFC class. Most authoring tools emit `IfcWallStandardCase`, so an ordinary cost map keyed
`IfcWall` matched **zero** walls. Found on a real model: 13 of 13 walls in `basichouse.ifc` went
unpriced.

The expense is in the *shape* of the wrong answer. It was not an error and not a zero-cost line — the
walls came back **uncoded**, which reads as *"no cost data is configured for this project"* rather than
*"your cost map does not match this model's classes"*. A takeoff silently missing every wall was
indistinguishable from a clean unconfigured project. Estimates were low by the entire wall scope with
nothing on screen to say so.

Matching now walks the class chain read from the ifcopenshell **schema** — not a hand-written table.
The hierarchy differs between IFC2X3 and IFC4, and a table is the hand-maintained list that stops
covering new classes the moment nobody remembers it exists. Most-specific still wins over an
ancestor, and inheritance is not a wildcard (`IfcSlab` is not priced by an `IfcWall` rule). Every row
now reports `matched_class`: the field whose absence made the original failure invisible, and which
says plainly when a line was priced through an ancestor rather than an exact key.

The defect was found by running the takeoff against a real model rather than against its own fixtures
— see the reconciliation work below, which is what put a real model through that path. Every suite
here uses purpose-built fixtures, and a fixture-shaped hole is precisely what a purpose-built fixture
cannot show you.

### Added — field-installed quantity reconciled against the model takeoff

**R22-PRODUCTION.** `GET /projects/{pid}/progress/reconciliation` compares what the field installed
against what the model contains, per cost code. Both halves already existed and had never been joined:
the takeoff produces per-cost-code model quantities, the production module records installed quantity,
and the production analysis compared an installed *rate* against a planned rate **supplied by the
caller in the request body** — so "are we ahead or behind" was answered against a number somebody
typed, not against the model.

Why it was never wired is structural rather than an oversight. The module that carries `cost_code` —
the model's join key — is read only by pricing, carbon and unit-rate consumers. The module the
production loop actually consumes has **no `cost_code` field at all**. The loop reads the module that
cannot join; the module that can join is read only by cost.

A percent-complete drives a pay application, so the engine is built as four refusals:

- **Units are two vocabularies and are never silently equated.** The model's unit names a dimension
  (`area`); the field's is a trade unit (`m²`, `SF`, `EA`). Conversion goes through an explicit table
  with the factor reported, and an unrecognised unit **refuses** rather than assuming 1.0 — SF read as
  m² is a 10.76× overstatement that prices perfectly cleanly.
- **Over-installation reports >100%** instead of clamping. A clamp hides over-installation, a bad join
  and a stale model behind one healthy-looking number.
- **An uncoded takeoff says so.** With no cost map every element has `cost_code=None`, and reconciling
  that matches nothing — which reads as "nothing to report" when it means "the model was never
  cost-coded".
- **Unmatched field codes are named, not counted.**

Every headline percentage carries `covered_pct`, because 97% complete computed across 3% of the model
is true and useless.

### Added — a measurement records how it was made

**R34-MEASURE-PROVENANCE / R34-SHEET-SCALE.** A traced 2D region is now measured at the scale it was
traced under, stamped at trace time rather than read from whatever the sheet's scale happens to be
when the total is computed. Sets that mix 1:50 and 1:100 on one sheet report the mix instead of
quietly applying one scale to both. A takeoff that cannot state its basis says so rather than
producing a confident number.

**R34-TAKEOFF-COUNT** — the platform can count, and a count is never scaled. Scaling a count is always
wrong; four doors are four doors at any scale.

### Fixed — a scale has to be a number, not something that survives `float()`

Validating the region scale with `float()` is a wider door than it looks, and it let two expensive
values through.

`float()` accepts **booleans**. A region carrying `"scale_units_per_px": true` measured at 1.0 units/px
instead of 0.01 — and because the area path squares the scale, that is a **10,000× overprice**:
quantity 10,000 and cost 1,000,000 against a correct 1.0 and 100. Worse, the row then reported
`scale_source: "region"`, asserting the region had deliberately recorded a scale when the value was a
boolean. That is precisely the claim this feature exists to refuse.

Separately, `1e300` is finite and positive, so it passed the `> 0` guard and then overflowed to
infinity once squared. FastAPI encodes infinity as `null`, so **one** malformed region silently
returned `total_cost: null` for the *whole* takeoff under an HTTP 200, with nothing naming the region
responsible. The call-level scale had the identical hole: an infinite sheet scale nulled every
quantity while still returning 200, and a non-numeric string raised a 500. Both are 422 now.

Scales are now validated by type (booleans excluded explicitly, since `isinstance(True, int)` is
true), finiteness, sign, and an upper bound of 1e6 units/px — generous by orders of magnitude for any
real drawing, and low enough that squaring cannot overflow. An unusable region scale falls back to the
call's and says `scale_source: "call"`, so a row never claims a provenance its input did not carry. A
takeoff whose scale cannot be trusted now raises rather than answering with nulls.

### Added — every headline figure reports what it was built from

**R24-TRACE-UI ②.** Nineteen pro-forma headline figures now report their basis, separating four states
that on screen looked identical: **declared** (every input came from the user), **defaulted** (every
input fell back to a default), **mixed** (some of each), and **none**.

`defaulted` and `mixed` are the ones that matter. A figure assembled entirely from defaults renders as
a confident number indistinguishable from one the user actually entered — the same failure mode as the
typo'd money field below, where a misspelled key inherited a plausible default instead of erroring.
A return that says *mixed* tells a reader which figures deserve a second look before they are relied
on. `element_link` is reported as `None` **with a stated reason** rather than omitted — "not linked to
an element" and "linking is not available at this layer" are different facts and a reader is entitled
to both.

**R31-CITE-HIGHLIGHT** (data half) ships the resolvable half of the citation: a citation now carries
enough to be located. The viewer-side highlight needs an entry point the vendored viewer kernel does
not currently expose and is tracked separately.

### Added — the model has a home in the controlled tree

**R32-MODEL-IN-TREE / R32-FILE-GENERATED.** Issuing a drawing set now files it. The model files to
`12_Model/IFC` and generated sets to `02_Drawings` under a stable set title, so a re-issue supersedes
its predecessor instead of accumulating near-duplicates. An **unfiled model is now a compliance gap**
rather than a silent absence — the state a document-control audit actually asks about.

Filing history sorts by a monotonic index sequence, not by `uploaded_at`: upload timestamps are
second-resolution here, so two files landing in the same second sorted arbitrarily and the "latest"
model was a coin flip.

### Fixed — finance

- **R33 clawback** now *solves* the amount instead of approximating it with a rate. The old
  `(pref_rate − lp_irr) × lp_contrib` multiplies a rate by capital: a one-year figure with no time
  dimension, which cannot express the money needed to move a multi-year return. On a conventional
  five-year deal at an 8% preferred return, the proxy said **41,509** where the true restitution is
  **240,776** — a **5.8× understatement** of money the GP owes back. The solver is verified by
  construction rather than by argument: adding 240,776 at the final date takes the LP's XIRR to
  exactly 0.080000. It is capped at the promote actually paid, since a clawback returns excess
  promote and cannot return more than the GP received.
- A **typo'd money field was accepted and silently priced at the default** — a misspelled key created
  no error and no zero, it inherited a plausible number.
- **R31-K1-PACK** assembles the preparation input for a K-1 and is explicit that **it is not a K-1 and
  not a tax document**. It names the six things it does not include and reports the rounding residual
  from its allocation rather than hiding it.

### Fixed — the 4D clash blocker that was never real

The install-before-support half of 4D clash was documented as blocked on "no element binding", and the
test asserted that blocker to hold it in place. The claim was **false**: `element_guids` is a column on
every module record and already reaches the analysis. The real gap is narrower — the **support
relationship** between elements is what is missing, not the binding. The gap is now measurable rather
than asserted: the result reports how many activities are actually bound today.

A documented dead end is the worst kind of coverage, because it is the one nobody re-checks.

### Security

- **G-8 — a new route prefix could opt out of the RBAC middleware unnoticed.** The protected-prefix
  list is hand-maintained and covered **8 of 67** top-level prefixes; nothing noticed when a 68th
  appeared, it simply sat outside the safety net and no test failed. This is the *root cause* of the
  authorisation holes fixed in v0.3.807 — `/pdf` (including the unauthenticated seal forgery),
  `/templates`, `/samples` and `/firm` were each also defective in their own gate, but the middleware
  would have caught all four and never got the chance.

  Coverage is now a gate rather than a note, and it fails on three things, of which only the first is
  obvious: an unclassified prefix; a **read-only prefix that has gained its first mutating route**
  (plain set membership waves this through); and a frozen entry with no referent, because a stale name
  does not merely look untidy — it **pre-authorises** whatever later claims it.
- A step-up assertion is **spent once**, not reusable for the whole of its TTL.
- A filing failure no longer narrates the exception back to the caller.

### Added — sections are annotated the way plans are

**R21-SPACE-TAG-SECT.** Room names now appear on sections, and a section is annotated by default
exactly as a plan is. The section frame is read from the view definition rather than restated:
a section on the X axis draws (Y,Z) and one on the Y axis draws (X,Z), so hardcoding a single pair
would have worked on one axis and placed every tag wrong on the other — a failure a reader would
have blamed on the geometry rather than the annotation.

### Added — modules

**MOD-FIELDATTRS.** `min`, `max`, `placeholder` and `default` complete the field vocabulary, so a
register can express the constraints it previously only documented in a label.


## v0.3.807 — a seal attests to a person: the security pass on sealing, firm standards, and the audit trail

Seven commits, batched. Four exploitable findings, each verified end to end before and after the fix,
each pinned by a mutation-verified test.

### Fixed — unauthenticated professional seal forgery
The seven `POST /pdf/*` routes guarded with `Depends(current_user)`, which **identifies without
authorising**: with RBAC on and no credential it returns the string `"anonymous"` and the handler
proceeds. `/pdf` is not in the RBAC middleware's prefix list either, so nothing else challenged them.
Reproduced: an unauthenticated request returned a PDF bearing a rendered Professional Engineer seal
with an attacker-chosen name, licence number and state, all read back out of the returned document.
A sealed drawing is what a plan reviewer accepts and an engineer is personally liable for. Sealing
also had no audit row at all.

### Fixed — a project-admin could replace the firm's standards library
`GET/PUT /firm/rules` gated `require_role("admin")` — a *project* gate on a *firm-wide* route. That
dependency's signature is `dep(pid: str, …)`, so with no `{pid}` in the path FastAPI made `pid` a
**caller-supplied query parameter** and the caller chose which project's role was checked. Measured
with an ordinary account (`role="user"`, admin only of a project it had just created):
`PUT /firm/rules?pid=<own project>` returned `200 {"saved": 1}`. Because `save_rules` replaces the
library, the same call erased the firm's real standards, after which every project's rule-check
passes against nothing. Now `rbac.require_platform_admin`, promoted out of `routers/cost.py` where
it had been written correctly but privately.

### Fixed — the seal now attests to a PERSON, not a session
Gating the route stopped anonymity; deriving the identity from a verified licence stopped
impersonation; **neither stopped automation**. A bearer token identifies a session, so any process
holding one — including an agent driving the API — could emit sealed documents in the licensee's name
and the audit row would faithfully record a human act that never happened.

Sealing now requires a fresh single-action step-up (`POST /auth/step-up`): 5-minute TTL, scoped by
`act`, bound to the password hash so a password change invalidates it, and refused as a bearer token.
The `api-key` machine identity is refused outright. The seal text is rendered from a
`professional_licenses` row belonging to the caller, recorded by a platform admin
(`verified_by`/`verified_at`) and never self-served; an expired licence refuses with `409`. The
free-text `profile` field is refused by default (`AEC_SEAL_ALLOW_PROFILE=1` re-opens it, audited as
`via: profile:legacy`).

Single-operator/desktop is unchanged by design — no accounts, no passwords, so a step-up there would
be theatre in front of an app that is unauthenticated by design.

### Fixed — anonymous unbounded writes into the audit table
`POST /esign/webhook` is anonymous by necessity (a provider holds no user credential) and correctly
carries no authority. The exposure was the row it wrote per request: caller-chosen strings of
unbounded length, unthrottled, from the internet. Now HMAC-SHA256 over the raw body when
`AEC_ESIGN_WEBHOOK_SECRET` is set, rate-limited, 64 KB cap, 200-char field caps, and every row stamped
`signature_verified`.

### Fixed — tenant JSON had no cache policy
`Cache-Control` was set nowhere outside the SSE streams, so project records, financials and audit
feeds were free for a browser disk cache or shared proxy to retain. Now `no-store`, scoped to
`application/json` so the `.frag` geometry stream and tiles stay cacheable.

### Fixed — two defects in the above, found by self-review
`"step_up": True` was a literal in the seal audit row, so every desktop seal claimed a human had
re-proved their password when nothing had checked — an audit row wrong in the operator's favour. And
the SSO branch in `/auth/step-up` sat after a check that already raised, making its explaining `409`
unreachable dead code.

### Gates
`test_seal_identity` (26 checks) and `test_global_mutating_authz` (23 checks) both run RBAC-on and
assert `rbac.RBAC_ON` directly — the previous control (`GET /admin/errors == 403`) could not tell RBAC
on from off, since a non-admin is refused either way. The generalising check: **no global route may
expose a `pid` query parameter**, asserted against the OpenAPI schema rather than as a list of
known-bad routes. `test_global_authz`'s frozen baseline drops 36 → 29, fixed rather than re-frozen.

### Migration + operator action
Alembic `b06f7bc8ba2f` adds `professional_licenses`. **With RBAC on, sealing refuses until a platform
admin records a licence per licensee** (`POST /admin/licenses`) — nothing is created automatically.
`AEC_ADMIN_EMAILS` is now load-bearing for firm standards and licence provisioning, and had never been
listed in the hardening checklist; `SECURITY.md` and `docs/PRODUCTION_CHECKLIST.md` now cover it.

## v0.3.806 — the registers stop being paper forms: filters, fieldsets, line items, and a guide that cannot drift

Six merged branches and one refactor, batched. The through-line is that a config-driven register was
still, in practice, **a single undifferentiated column of inputs with two ways to narrow it** — and
every item below removes one reason that was true.

**Per-field filters and server-side sort** on every register. Filtering was `q` + workflow state and
nothing else; on a twenty-field register you could not filter by discipline, vendor, cost code or date.
Worse, **sorting ran in the browser over whichever page had been fetched** — "sort by amount" on a
500-row register ordered 200 rows and presented the top of those as the largest values. Nothing looked
wrong; it was the wrong 200 rows. Filters compose (`eq · ne · gte · lte · contains · in · empty ·
nonempty`), are bounded at 12 per request, and are applied in SQL before the LIMIT, with the count
filtered too — a total that ignores a filter the list applied is the number a user trusts without
checking. A filter field name is never taken from the caller: unknown names 400 rather than being
ignored, because a silently dropped filter returns *more* rows than were asked for.

**`percent` reaches the form layer.** Three sites asked `number || currency` and `percent` was in none,
so 21 newly-typed percentage fields — every retainage, fee, overhead and contingency — stopped being
inline-editable, rendered as free text, and **saved as the string `"5"`**. Nothing failed loudly; the
column simply accumulated a mix of `5` and `"5"`. That is also the bug the filter cast exists to
survive, since `'9' >= 10` is true when the value was stored as text. Fixed once as
`NUMERIC_FIELD_TYPES`, not three times as ternaries.

**Line items.** A register field can hold rows, not just a value — 22 places had a list flattened into
a textarea, and `sov`/`estimate` were documents pretending to be single records. Legacy prose in those
fields is accepted and shown verbatim above the grid rather than rejected or dropped: it is the only
copy.

**Fieldsets** across 58 registers, so a form is grouped sections rather than one column.

**Reference backfill** for the 54 reference fields added beside their text twins — exact match after
normalisation only, unique matches only, never overwriting, dry-run by default, ambiguity reported
rather than resolved. The asymmetry that drives it: an empty reference is visibly empty and gets
filled; a wrong one resolves, opens a real record, and is never questioned.

**Option economics, the quality evidence chain, and vendor memory across projects** — plus a clawback
that reports `unavailable` with its reason instead of inventing a number when the IRR solve does not
converge, and a vendor scorecard that states in the payload which registers it could *not* examine.

**The authoring guide can no longer drift.** It documented 10 of the 16 field types the platform
accepts — missing the two most recent. It is now asserted against the schema **as a set in both
directions**, because the two failure modes differ: a type in the schema but not the guide cannot be
discovered, and a type in the guide but not the schema fails only after the module is written.

**SCALE-SEAM ⑥** — `/procurement` out of `client.ts`, and the surface ratchet had gone slack again.

## v0.3.805 — R31-SCHEMA-DIAG: the IFC checked against the schema, and a parser crash found on the way

**Validate the file, not just the spec.** Every existing check scores a model against *rules* — IDS
rule-compliance, LOIN completeness, hygiene (duplicate GlobalIds, orphans, unenclosed spaces), the
normative gauntlet. None answered *is this structurally a valid IFC*: an entity type not declared in
the schema, a `#12345` resolving to nothing, an ABSTRACT type instantiated directly, a `$` in a slot
the schema declares mandatory, an attribute list of the wrong length. A model can be 100%
rule-compliant and still be rejected on import elsewhere — and a viewer hides it, because the geometry
still renders. That matters now that the platform **writes** IFC rather than only reading it.

New `schema_diag` engine, served at `GET /projects/{pid}/models/schema-diag` beside `/models/qa` and
`/models/norm-valid`. Unlike every sibling it reads the file as **text and never loads a model**, so it
still reports on files no reader will accept — precisely the case a load-based diagnostic cannot speak
about. Valid entity names, abstractness, attribute counts and optionality all come from the
ifcopenshell schema, never a list in our source: a hand-maintained set of IFC class names would rot
silently. Findings carry the instance id.

**A crash, found while building it, that matters more than the feature.** ifcopenshell 0.8.5
**segfaults** — exit 139, reproduced 3/3 — on an IFC ending inside an unclosed `'` literal, which is
what a truncated upload or an interrupted write produces. A segfault is not an exception: no
`try/except` in any of `open_model`'s **133 callers** can catch it, and the process handling the
request dies. `open_model` now screens for that one input and refuses it as an ordinary error.

The screen is deliberately **narrow**. An unclosed parenthesis and a file truncated mid-instance both
fail the structural checks and ifcopenshell opens them without complaint, so refusing everything that
fails to parse would break uploads that work today — a worse bug than the crash. It is also cheap:
quote-count parity in C with a comment-aware confirm only on suspicious files, **6,451 ms → 87 ms** on
a 51 MB model. The parity filter is trusted in one direction only, because a false negative leaves us
where we already were while a false positive refuses a valid model.

It found a real violation immediately: 27 `IfcFurnitureType` instances in the shipped `basichouse.ifc`
sample pass `$` for `AssemblyPlace`, which the schema declares mandatory. Written by a mainstream
exporter; the file loads, renders, and passes IDS. Zero false positives across the other samples.

Also fixes a cap that was a lie. `MAX_BYTES` advertised 512 MB for a whole-file read that cannot
honour it; the first full-suite run raised `MemoryError` and took two unrelated suites down with it.
Now 96 MB, reference tracking bounded, and truncation **reported** — "no dangling references" and
"stopped looking for them" must not be the same output.

## v0.3.804 — SCALE-SEAM ⑤: /estimate out, and client.ts drops under 4,100

`client.ts` 4,156 → **4,008**: the 12 `/estimate` methods become `api/estimate.ts` as a `withEstimate`
mixin. Clean on the first pass — no missing imports, no shared private helper crossing the boundary, so
a much smaller job than ④. Typecheck clean, 908/908, ratchet holds at 696; mutation-checking
`estimateFromModel` fails it both ways (695 by number, and by name in the spot-check).

Running total across five extractions: **4,956 → 4,008, down 19%**, with `authoring` · `library` ·
`schedule` · `model` · `modules` · `estimate` now separate modules behind the same `ApiClient` surface.
The method is repeatable and the two structural traps are known and written down: a `private` member
must move down to `HttpCore` if a mixin needs it (③, `liveStream`), and a `private` helper that spans a
cut must become `protected` (④, `reviewPost`). ⑤ hit neither.

## v0.3.803 — SCALE-SEAM ④, a private helper that spanned the cut, and CodeFlow removed

`client.ts` 4,369 → **4,156**: the 34 `/modules` methods become `api/modules.ts` as a `withModules`
mixin — the register engine every portal screen is built on. Typecheck clean; the surface ratchet holds
at 696, and mutation-checking `moduleRecords` fails it **both ways** (695 < 696 by number, and by name
in the spot-check).

**The extraction surfaced a real coupling, and it is the `liveStream` lesson in mirror image.**
`reviewPost` is a `private` multipart helper that some `/modules` methods use *and* three
contract-review methods in `client.ts` use. Moving it into the mixin made it invisible to `ApiClient` —
a derived class cannot see a base's `private` member. It is now `protected`, with the reason written
where the next reader will hit it. ③ moved `liveStream` *down* so a mixin could reach it; ④ had to widen
`reviewPost` for the same structural reason in the opposite direction. **Any helper that spans an
extraction boundary has to be `protected`** — worth knowing before ⑤ rather than during it.

`ModuleGraph` / `ModuleGraphNode` / `ModuleGraphEdge` travelled with the methods and are re-exported
from `client.ts`, because `portal/panels/moduleGraph.ts` imports them as `from "../../api/client"`.

**CodeFlow removed by the user.** The roadmap entry now records the decision and keeps the reasoning,
because the failure mode is generic to bolt-on analysers: **0 successes across 30 `main` commits and all
10 PRs**, every one `"CodeFlow was not able to perform analysis"` — the analyser never ran. Two things
worth carrying: a permanently-red check teaches people to scroll past red, which nearly waved through
five PRs; and it **saturated the aggregate signal**, since GitHub's legacy commit-status `state` is the
OR of its contexts, so a *new* context going red would have been invisible behind it.

## v0.3.802 — SCALE-SEAM ③, and the gate I was trusting had 13 methods of slack

`client.ts` 4,637 → **4,368**: the 29 `/model` methods move to `api/model.ts` as a `withModel` mixin.
Typecheck clean, **907/907** — the same count as before, which is what "moved, not changed" looks like.

**`liveStream` moved into `HttpCore` and that was the real work.** `modelStream` calls it and it was
`private` on `ApiClient`. A mixin is a **base** of `ApiClient`, so it cannot see `ApiClient`'s private
members — exactly why `withAuthoring` recorded "the SSE methods cannot follow yet". It is now
`protected` on `HttpCore`, which also unblocks `notificationStream` / `markupStream` /
`pullPlanStream` for ④. `surface.test.ts` had predicted this ordering constraint before the first
extraction; the prediction was right and the fix was the one it named.

**The finding worth more than the refactor: `surface.test.ts` did not catch a dropped method.** Its
floor was `>= 685` against a live surface of **696** — 13 methods of slack. I deleted `modelStream`
outright as a mutation check and the file reported **6 passed**. Only `tsc` caught it, via its two real
call sites. So my earlier claim that this gate makes "moved vs changed" checkable was stronger than the
gate delivered: it caught `scheduleCpm` in ② because that name is in the 28-name spot-check, and
`modelStream` is not.

Raised to the exact count, making it a **ratchet** in the same shape as `test_global_authz`'s BASELINE:
losing any single method now fails by number, and a legitimate new endpoint fails until someone raises
the line — one deliberate edit that only ever moves up. Mutation-verified both ways (clean 696 passes;
`modelStream` removed → 695 fails).

Also caught in passing: I first set that floor to **698**, from a counter I wrote myself, while the
gate's own `surfaceOf` counts 696 — it filters getters differently. **A threshold taken from a
different reader is a threshold for a different question**, and the clean tree failing is what said so.

## v0.3.801 — the GP promote was paid at half, and a green suite could not see it

Release for #107. `proforma/waterfall.py` tested the IRR hurdle against a cash-flow series that omitted
the preferred return and return-of-capital paid **at that same date** — `lp_take` accumulates them, but
`lp_cf.append(lp_take)` runs only after the tier loop. So the first distribution period saw a
contributions-only series, XIRR was undefined, `(None or -1.0) >= hurdle` was False, and the
below-hurdle 90/10 tier absorbed cash belonging to the 80/20 residual.

```
             2,000 distribution            10,000
as shipped   GP   102.78  LP 1897.22       GP 1697.53
fixed        GP   205.57  LP 1794.43       GP 1805.57
```

Exactly half. Reproduced independently before reading the fix, and both figures conserve to the cent.
Full backend suite on the merged tree: **446/446**.

**Defect, not convention — and the deciding argument is the direction.** The error was systematically
one-sided, always favouring the LP. A convention nobody chose does not come out one-directional; that
distinguishes "we decided to measure the hurdle at period start" from "nobody noticed". It is also
falsifiable from the outputs alone, without reading the solver. Structurally,
`solve_cash_for_irr_hurdle` already appends the tier's own candidate cash at date `d`, so omitting the
pref and RoC at that same date counted half of one date's cash and not the other half.

**Why 446 green tests missed a 100% error:** the only assertion on the promote anywhere was
`assert w2["gp_distributions"] > 0.0`, and dollar conservation held either way. The split could be
wrong by any amount with everything passing. Third defect of this shape in `proforma/` — that package
range-checks where it must value-check. Also closed: `clawback=True` was exercised by **no test** (all
ten call sites passed `False`).

Found by mutation testing — `split = min(remaining, cap)` could be flipped to `max` with nothing
failing. Operator yield, since it is not uniform: `min`/`max` on a business rule is where the signal
is; `<`/`<=` on numerical code is near-pure equivalent-mutant noise (0 of 12 real on `returns.py`, all
tolerance guards, bracket clamps, or protected by an upstream filter).

## v0.3.800 — SCALE-SEAM ②, and the item was filed complete while the god-file stayed 4.8k

`client.ts` 4,844 → **4,637**: the 26 `/schedule` methods move to `api/schedule.ts` as a `withSchedule`
mixin, so `api.scheduleCpm(...)` resolves exactly as before and no call site changes. Typecheck clean,
**907/907** web tests — the same count as before the move, which is the point.

**The status defect is the more useful half.** `roadmap-completed.md` records SCALE-SEAM as **complete**,
measuring ① — the `authoring.ts` cut, 112 lines, **2%** — after which the item was closed with the file
still at 4.8k. Eleven other stale estimates found today all *understated* what existed, so somebody
eventually trips over the truth. This one overstates it, so nobody looks again. Reopened as ③+, and the
completed entry annotated rather than deleted, because how it came to be marked done is the lesson.

**And the plan it described cannot work as written.** Classifying all 669 methods by the route each calls
— the only honest basis, since the `// --- section ---` comments label the start of a run and the file
then continues with other domains — gives **219 route-groups**. The largest is 4.5% of the file; the top
six are 20%. That is ~25 releases of one group each, not one refactor. Anyone sizing it as an L is
reading the comments rather than the routes.

Two gates were needed and they catch different things. `surface.test.ts` captures the runtime method
surface, which is what distinguishes "I moved code" from "I changed behaviour" — **a typecheck cannot**,
since deleting a method and deleting its last caller both compile clean. Verified by dropping
`scheduleCpm`: the surface test fails by name, and tsc independently fails at its two real call sites.

That mutation took three attempts, which is worth recording. The first broke the file syntactically and
vitest reported **"no tests"** — not a passing gate, but it reads like one. The second deleted a
*docstring* line naming the method. Both times the gate was green for reasons unconnected to the gate.
**A mutation you have not confirmed landed tells you nothing.**

## v0.3.799 — three R22/R23 merges, and the glTF index-width bug no fixture could reach

Release for #104, #106 and #105, all merged and verified by content on `origin/main` rather than by
merge status. Full backend suite on the merged tree: **446/446, zero failures** — worth running because
"merges cleanly" and "still correct together" are different claims and three landed at once.

- **#104 `unit_rate_memory`** — what a cost code actually cost PER UNIT across your projects, from
  installed quantity rather than from a rate somebody typed.
- **#106 `option_carbon`** — embodied carbon on the design-option card, carrying the basis it rests on.
- **#105 `gltf_export`** — per-mesh index width, plus opt-in Draco (~88% smaller). Draco sits in
  `requirements-dev.txt`, lazily imported, so the hash lock and the shipped image are untouched.

**#105 shipped green with a silent-corruption bug, and the review question that found it is the
transferable part.** Every fixture in that suite was ~960 vertices, so the uint32 index fallback was
**unreachable by any test in it** — the branch existed, was correct, and was never executed. Asking what
a suite is *structurally unable* to see, rather than reading what it asserts, is what surfaced it.

The proof is the mutation. Widening the ceiling by one (`<= 65536` → `<= 65537`):

```
FAIL  a 65,537-vertex mesh uses uint32 indices — 5123
FAIL  and index 65,536 survives the round trip (a wrap would read 0) — 65535
```

Index 65,536 comes back as **65,535**: same byte length, valid glTF, no exception — one wrong triangle
in someone's model. Fixed with a synthesised >65,535-vertex mesh before the merge landed.

Also verified on this tree, by content rather than by diff (`run_tests.py` packs ~200 entries per line,
so any change renders as a whole-line `+`): **446 manifest entries, 446 `test_*.py` files, zero orphans
in either direction** — nothing named without a file (green locally, broken on a fresh clone) and
nothing present but unnamed (a test that never runs).

## v0.3.798 — every internal audit was being published to the live site

`docs/` doubles as the web root, so the Pages workflow's `cp -r docs/. _site/` published **everything**
in it. That meant eleven superseded internal audits, four unbuilt plans and a 264 KB completed-roadmap
were served on the site beside the user guide, indistinguishable from it. Not "sitting in a public
repo" — rendered as pages.

The fix is `docs/internal/` plus one `rm -rf _site/internal`, and a reader-facing structure around what
remains (`docs/README.md` as an index, `getting-started.md`, `user-guide/`, `reference/`, `history/`).
`docsPublished.test.ts` makes the fence enforceable rather than remembered: it checks the strip runs
*after* the copy (stripping first would remove nothing and still read as protection), that every
internal note is accounted for in `internal/README.md`, and that no document declaring itself a working
note sits where the copy would publish it.

**One hole found in that gate and closed before it landed.** The fence assertion used
`WORKFLOW.indexOf("rm -rf _site/internal")`, which matches the string anywhere in the file — including
inside a comment. Commenting the command out, exactly how a fence gets disabled while debugging, left
the string present and the suite green. It now matches a **live** line, and both mutations fail it:
commented out, and deleted outright. A gate that cannot tell a command from a comment about that
command is not watching the thing it names.

## v0.3.797 — R24-BASELINE: three metrics measured, three that refuse, and a mean pretending to be a p95

R24's entry says "do not start Sprint 2 without this". Sprint 2 items have been picked up twice
already, so the gate was real and ignored. `baseline.py` + `GET /admin/baseline` closes it.

**The six metrics are not one kind of thing, and that split is the finding.** Three are derivable from
`record_activity`, which already logs an actor and a timestamp for every create/update/transition:
rooms touched per user per week (module -> section -> room via `rooms.room_of`, so the metric cannot
drift from the rail), field captures per super per day, and median RFI turnaround from paired
`open` -> `answered` transitions. The other three report **`available: false` with a reason**:
time-to-first-meaningful-action and p95 *interaction* latency are client-side with no server event at
either end, and "where is X" support threads live in an inbox this product cannot see.

Refusing matters more than measuring here. A client-side measure substituted from a server-side proxy
reads exactly like the target and answers a different question — which is how a shell nobody can score
ends up shipping with a confident dashboard.

Two defects surfaced while building it:

- **`http_request_duration_seconds` was `_sum`/`_count` only.** That yields a MEAN, and a mean cannot
  answer the p95 that R24-PERF-BUDGET asserts — it hides precisely the tail a budget is about. Added a
  latency histogram with 0.1 s as a deliberate bucket edge, plus `metrics.quantile()`, which returns a
  bucket upper bound rather than interpolating a precise-looking number out of bucketed data.
- **An unanswered RFI would have counted as zero days** — reporting the fastest turnaround on the job
  for work nobody has answered. It is excluded from the numerator and surfaced as `open_unanswered`.
  Same shape as the draw that was priced at zero for staying in the denominator.

Tests are value-checked against hand arithmetic, never range-checked, and mutation-checked in both
directions. The first draft of the test file had **no per-test isolation** — every test saw the rows of
every test that ran before it alphabetically, producing n_actors=6 where 2 was expected. The engine was
right each time and the fixture was lying, which is the more dangerous of the two.

Also corrected: R23-CONSTRAINTS named `kiwisolver`, which is **not a dependency of this repo**, for a
solver `scipy` already provides and already ships.

## v0.3.796 — R30-TOOLS: a register can finally say what it can DO

Every optional key a module carried was **presentation** — icon, list_columns, pinnable, ref_prefix,
title_field, workspace. None said what the register can *do*, which is exactly why 133 registers
rendered as a table, a form and a status chip: a paper form.

The depth was never missing. `bid_leveling.py` builds a scope-adjusted comparison from
`bid_submission`; `schedule_cpm.py` runs a real forward/backward pass over `schedule_activity`;
`fca.py` computes an FCI from `fca_element`. **The seam was missing** — a user standing in the
register had no route to the tool, and `destinations.ts` declared the dependency in one direction
only, for a handful of panels. 56 modules now carry a `tools:` list naming the destinations that
operate on them.

Two things make it more than a data edit. `GET /modules` is an **allowlist** that silently drops any
key it does not name, so a `tools` key nobody forwarded would have been invisible with every file
correct — it is forwarded. And `moduleTools.test.ts` reads the JSON from disk and asserts every
`dest` resolves against `ALL_DESTS`, so a typo or a renamed panel fails the build instead of
rendering a dead button. Same shape as `roomNames.test.ts` reading `rooms.py`.

Also: `docs/module-room-audit.md` records where all 133 modules sit and why; the demo capture and
Pages guide are regenerated to match; and `.claude/launch.json` gains an `api-alt`/`web-alt` pair on
:8097/:5183 so one session can verify its own build while another holds the default ports.

Verified before landing rather than after: backend `test_module_rooms` (133 modules → exactly one
room each), `test_modules`, `test_reachable` (306/310); web typecheck clean and **76 files / 823
tests** green. The new gate was mutation-checked — an injected bogus `dest` fails it by name, and it
passes again on restore.

## v0.3.795 — R24-MONO-DATA, and three tests of mine that were making other tests fail

### The face is decided once

The audit's visual system asks for a sans for language and a **mono** for anything a machine produced
— GlobalIds, quantities, currency, dates, keys, statuses — on the argument that it is the fastest
available signal for *"this is data, not prose"*. Unlike the rest of that system (the ink canvas, the
24/192 brand grid) it costs nothing and commits to nothing, which is why this ships and those remain
a decision for the user.

The rule worth enforcing is not "use mono", it is **decide the face once**. There were three
hand-rolled `font-family: ui-monospace, monospace` declarations in `style.css` and eleven more inline
in TypeScript. Nobody disagreed about the stack; nobody owned it — which is how a type system drifts:
one component lists `Menlo` first, another omits `Consolas`, and two GlobalIds in one panel render in
different faces.

Now `--mono` plus `.mono` / `.num` / `.mono-num`, and `monoData.test.ts` is a **ratchet** like
`innerHtmlGuard`: converting a literal passes, adding one fails. The allowance is **1**, and the test
asserts the headroom is *exactly* zero — a ratchet parked above reality never fires and reads as
protection. The one remaining literal is `portal/portal.ts`, held by another session's in-flight work;
converting it would have meant editing a file two people had open.

### The part that matters more: my tests were breaking other tests

The full suite failed intermittently — 2 of 3 runs — and the honest answer took two attempts.

**My first diagnosis was wrong and I nearly shipped it as fact.** I saw `pdfVendor.test.ts` fail
locally, had a plausible story, and reported a flake. Reading the actual output showed something
else: **all the failures were timeouts, not assertion errors.** `library.test.ts` at 5 s, `pdfVendor`
at 20 s, no assertion messages at all.

The cause was mine. Three tests added today read the filesystem — `monoData` walks 100+ source files,
`emptyGuide` stats 133 module directories, `reportMoments` parses `reports.py` — and each was called
**once per assertion**, so up to five full tree walks per file. On a loaded parallel run that pushed
*sibling* tests past their budgets. **A test that makes other tests flaky is a defect in that test,
not in theirs.**

All three now memoise their reads. Measured over five consecutive full runs: `library.test.ts`
timeouts went from intermittent to **0/5**, and the suite is 823/823 on 4 of 5.

`pdfVendor.test.ts` still crosses its 20 s budget roughly 1 run in 5 — **left alone deliberately.**
Its own comment sanctions raising the budget but names the condition: *"if this ever needs raising
again, the vendored copy has grown enough to be worth a second look."* That is a request for a review
of the vendored engine, not for a bigger number, and it belongs to whoever owns that lane. Reported
rather than patched.

## v0.3.794 — the guard that would have failed a build over a dependency that exists

v0.3.793 verified `AUTHORISING` names against the source by matching `def <name>(`. That is too
narrow. A dependency built by a factory — `require_x = _make_gate(...)`, an ordinary FastAPI idiom —
has no `def`, so the guard would report a real dependency as resolving to nothing and **fail the
build over something correct**.

That direction of error is the damaging one. This file's own failure text argues against suppressing
it; a gate that cries wolf is how a team learns to reach for the suppression anyway. So the check now
accepts a `def`, an `async def`, or a module-level binding, and says why in the code.

Mutation-checked three ways rather than two: clean → exit 0, a phantom name → exit 1, a
factory-defined name → exit 0 (the case v0.3.793 would have failed). Raised by a reviewer whose
method note — that a `def`-only grep can be right for a reason narrower than the question — is the
actual finding here.

## v0.3.793 — an allowlist entry with no referent is a hole waiting for a matching name

`test_global_authz`'s `AUTHORISING` set — the list of dependencies that count as a real gate — carried
two names, `require_license` and `require_plan`, that are **not defined anywhere in `src/`**. Dead
today, since no route depends on them. The reason to remove them rather than shrug: matching is **by
name**. The day someone writes a `require_license` that checks a subscription *tier* rather than
authorisation, every route using it drops out of the ratchet silently, with nothing failing. That is
the `current_user` trap the gate itself documents, one level up — a name that reads like a gate.

The set is now **verified against the source instead of trusted**: a name in `AUTHORISING` with no
`def` under `src/` fails the build and says why. Mutation-checked both ways (exit 0 clean, exit 1
with a phantom restored), because a guard nobody has watched fail is prose.

Also merged the two open branches after checking them: the jurisdiction packs work (its HIGH — three
unauthenticated global pack routes — and all five review findings verified fixed on the branch first)
and the global-authz ratchet itself, which I mutation-checked before merging rather than after. Its
coverage was confirmed sound against the OpenAPI contract: 0 of the 51 global unprotected mutating
routes are invisible to it.

## v0.3.792 — ReDoS on IFC-authored text, and the two halves of the fix

`classify_assist` ran regexes with **unbounded quantifiers** against free text taken straight out of an
IFC file — an element's `Name` and its type's `Name`, which is to say a string somebody else authored —
with **no cap on how much of it was scanned**. The steel keyword was `\bw\d+x\d+`: two unbounded
numeric quantifiers, on attacker-supplied input.

This repo has already paid for this class once (`py/polynomial-redos`, v0.3.492), and the standing rule
has two halves because either alone leaves the door open:

* **Cap the scan.** `_MAX_SCAN = 4096`, applied in `_keyword_hit` *before* `.lower()` — lowering a
  multi-megabyte string is itself work done on a caller's behalf for no benefit — and in `_norm`
  before its `\s+` collapse. This half holds regardless of which pattern someone adds next, which is
  what makes it the more durable of the two. A classification keyword needing more than 4 kB of
  context is not a keyword.
* **Bound the quantifiers.** `\bw\d{1,4}x\d{1,4}`. A W-shape designation is `W14x90`; four digits is
  already generous.

Tests assert **both**, not just that the current input happens to be fast: a 200,000-digit hostile name
completes in well under a second, `_MAX_SCAN` is asserted to exist and be small, `_norm` is checked
against half a megabyte of whitespace, and the steel pattern is asserted to contain no `\d+` — while
still matching `W14x90` and plain `steel beam`, because a ReDoS fix that quietly stops classifying
steel has traded one defect for a worse one.

A timing assertion alone would have been the weaker test: it passes on a slow machine with a bad
pattern and fails on a fast one with a good pattern. The structural assertions are what actually pin
the fix.

Found by a review bot on PR #97, which merged four hours before anyone read its comments.

## v0.3.791 — R24-ELEMENT-CARD ②: the strip goes where the element is named (and a broken import from v0.3.790)

### First, the breakage

**v0.3.790 shipped a broken `main`.** It carried a file move — `viewer/lifecycleStrip.ts` →
`ui/lifecycleStrip.ts` — **without the two import fixes that go with it**. `viewer/app.ts` and
`viewer/propsView.ts` were left importing `./lifecycleStrip`, a path that no longer exists.

Nobody did anything wrong. The move was staged in this session's index while the message for *this*
release was being written, and another session's entirely ordinary `git commit` swept the staged
rename into its own commit. The index is shared state; that is the second half of a change getting
separated from the first. It is fixed here, and it is the concrete cost of the hazard already
recorded in `multi-agent-lanes`: **keep the gap between `git add` and `git commit` at zero.** This
release closes it in the same commit that carries the feature, which is the only reason the window
was minutes rather than hours.

### R24-ELEMENT-CARD ②

The audit's finding 06 is the one it calls the unfair advantage: a slab's GlobalId is the same key in
geometry, BCF, the cost code, the schedule activity and field verification, and **no competitor can
answer "where did this number come from" in one hop.** The engine has been able to for a while —
`GET /elements/{guid}/lifecycle` returns all six states, and `buildLifecycleStrip` has rendered them
correctly since R26-INSPECTOR.

It rendered them from **exactly one call site**: the 3D viewer's inspector. So the single most
unusual thing about this product was visible only to somebody already looking at the model — the
person who needs it least. An estimator reading a cost trace saw a GlobalId and nothing else.

**The extraction this was scoped for did not exist.** The plan was to pull the strip out of `viewer/`
so other surfaces could use it without dragging in three.js. On opening the file: `lifecycleStrip.ts`
imports **one type** and nothing else. Already portable, merely *filed* under `viewer/`. Moved to
`ui/`, two import lines updated. Another item whose estimate came from where a file sat rather than
what it contained — the fourth today.

New `ui/elementCard.ts` is the card's frame: identity line plus strip, with a loader any surface can
call. Two rules it carries:

- **A GlobalId is shortened for the eye and never for the clipboard.** `39V6N…2zq` is displayed; the
  full value stays in `title`. It is the one string on the card a user may need verbatim.
- **No lifecycle renders NO strip**, not an empty six-state skeleton. Six blank cells claim six things
  were checked and none passed — a worse statement than "nobody asked". Same rule the strip already
  applies to `unknown` vs `none`, one level up. A failed request degrades to the identity line so a
  cost trace never loses its table to one 500.

First non-viewer surface: **Cost Traceability**, which is where the thesis is already being argued.
The lifecycle loads *after* the cost answer and is not awaited into it — context must not delay the
number the user asked for.

*Verified against the live API* with a real element (`39V6NK5af1lRCOqlaCm2zq`, an `IfcColumn`): the
card renders **even when the cost lookup finds nothing**, which is the point — the estimator now sees
*why* there is no cost. Designed ✓, Checked ✓ (no findings), Priced —, and a named next action
("Add a cost rule whose selector matches"). 816 tests, typecheck, lint clean; no console errors.

## v0.3.790 — an unsolvable draw was being priced at zero

Two correctness defects in `proforma/entitlement_risk.py`, both **on `main`** since #99 merged, and both
found by a review bot whose comments nobody had read. They share one shape: **an approved draw that
failed to solve left the numerator but stayed in the denominator.**

**`expected_npv` divided by every iteration while summing only the draws it could value.** A failed
solve therefore entered the average as **zero NPV** — a number nobody computed, quietly blended with
ones somebody did — dragging the expectation toward zero by exactly the failure share, with nothing in
the payload saying so. It now divides by the population it actually valued (solved approvals +
denials) and publishes `valued_draws`, `excluded_solve_failures` and a `basis`. A draw that could not
be solved is **not a project worth nothing; it is a project we could not value.** Same rule the vitals
strip follows: state the basis, and never let an absent value pass as a zero. All-failed now returns
`available: false` rather than `0.0`.

**`probability_given_approval` divided by the draws that happened to solve, not the draws that were
approved.** That silently drops every approved-but-unsolvable draw out of the denominator and *raises*
the reported probability — the friendlier number again, reached by a different route. The denominator
is now `n_approved`, an unsolvable approved draw counts as not clearing, and the denominator is
published so a reader can check it.

The tests are **value-checked against hand arithmetic, not range-checked**, because that is precisely
why this package needed a 17-defect review before: assertions like "between 0 and 1" are satisfied by
the right answer and the wrong one equally. The new checks pin the old wrong values too — 25.0 versus
83.33 for the expectation, and a spurious `1.0` certainty for the conditional probability.

### One finding deliberately NOT actioned

The same review flagged `test_entitlement_route.py` for overriding `DATABASE_URL`/`STORAGE_DIR` and
bypassing the runner's isolation. It is *true* — and it describes **310 of the 336 test files**, not
this one. Only 26 use `setdefault`. Isolation here comes from unique per-test filenames rather than
from the runner, and the suite is green at 435/435. Singling out one file for the house style would be
churn that misleads the next reader about what the convention is. If the convention should change, it
is a repo-wide decision, not a line item in an entitlement-risk release.

## v0.3.789 — the public site was sending visitors after a sample that no longer exists

`docs/guide.html` — the GitHub Pages tutorial, the first thing a stranger follows — said at step 2:

> Click **Open ▾ → BasicHouse** (or any sample).

**`BasicHouse` was deleted at v0.3.777**, along with the two other bundled `.frag` files, when the
viewer stopped picking geometry by regex-matching the project's name. So a reader followed the
instruction, found no such entry, and concluded the app was broken — which is a worse outcome than the
step simply being absent. A wrong instruction spends the reader's trust; a missing one only spends
their time.

Rewritten to the path that exists — **Open ▾ → Project → Load sample project** — and, since the guide
was silent on both, it now explains the two things a first-time reader most needs:

* **What a sample is.** A `.mass` container holds the geometry *and* every project table, so it opens
  as a **project** rather than a bare mesh. That difference is the entire distinction between this and
  a viewer, and the old copy never mentioned it.
* **The six rooms and the vitals strip.** `index.html` described three pillars and never named the
  navigation a visitor actually lands in. It now names **Design · Planning · Cost · Schedule · Deal ·
  Work**, and the strip — **LOD · area · $/ft² · float · IRR · health** — with the rule that makes it
  worth trusting: *where a value cannot be computed it shows an em-dash and the reason, never a zero.*
  A confident wrong number is worse than an absent one, because a blank gets chased and a number gets
  cited.

`docsCurrent.test.ts` now gates the Pages site too: each deleted sample name is asserted **individually**
so a failure says which one came back, and `index.html` must name all six rooms. Mutation-checked by
putting `BasicHouse` back, which fails the gate.

This is the third staleness class found in the docs today, and they share a shape: **nothing in the
build reads prose.** The room spine could be renamed under full test coverage while the demo snapshot,
the walkthrough and the Pages tutorial each went on describing an older app. The fix is not care, it is
that every doc sentence naming a flag, a count, a room or a file is now a claim some test reads.

## v0.3.788 — the demo script did not know about two shipped features, and the log was out of order

### The walkthrough

`docs/walkthrough.md` is what somebody reads before recording a demo, so **a scene missing from it
does not get demoed.** It was otherwise current — it knew all six rooms, having been updated at
v0.3.766 — and had **zero** mentions of the **vitals strip** (shipped v0.3.773) or the **`.mass`
container**, which is what every sample in the library actually is.

That is the shape of doc rot nothing catches. A wrong sentence gets noticed; a missing one does not.
No spell-check, link-check or build finds it, and no reader misses what was never there.

Added the vitals beat — the six numbers following you between rooms, and the em-dash: *"it tells you
what it does not know; a number it cannot compute is a dash, not a nought"* — and what a sample **is**:
a portable zip holding the geometry, every project table and the blobs, so it opens as a *project*
rather than a mesh.

`docsCurrent.test.ts` now gates all three claims, including the inverse failure the demo snapshot
committed two releases ago — naming a `Model` room that was renamed `design` at v0.3.766.
Mutation-checked: renaming "vitals" to "stats" in the walkthrough fails the gate.

### The changelog was not newest-first

Noticed while writing the entry above: **v0.3.781 was sitting at the very top, above 787 through 782.**

The cause is concurrency, and it is worth naming because it will recur. Four sessions ship releases,
and each prepends its entry above *the version it branched from*. When 781 landed above 780 that was
correct. Then 782…787 each also inserted above 780's neighbourhood — every one of them correct
relative to its own predecessor, and the result collectively wrong. No single edit was a mistake.

Reordered strictly by version. The lasting fix is not vigilance: **insert above the highest version
present, not above the one you branched from** — the difference only shows up when someone else ships
between your branch and your push, which is now the normal case rather than the exception.

## v0.3.787 — R24-EMPTY-GUIDE ②: an empty register says where its rows come from

The audit's finding 14 is that blank projects were hardened for **robustness**, not **guidance**.
Running with no data is a real strength here and the app does it everywhere. The miss is what an
empty module actually said:

> **No RFIs yet**
> Use "+ New" to create the first one.

Mechanically true, and an answer to the wrong question. "+ New" is a button three inches away — the
user can see *how*. What they cannot see is **what the register is for and where its rows normally
arrive from**, and for most registers the answer is not "somebody types one". An RFI is asked against
a drawing. A submittal is driven by a spec section. A punch item is captured on a phone, in the
field, by someone not looking at this screen. That is the difference between a blank slate and a dead
end, and it is the audit's own worked example.

24 registers now carry a curated line — RFIs, submittals, spec sections, ASIs, punch items, safety
observations, daily reports, inspections, NCRs, deliveries, budget, change events, commitments, owner
invoices, cost codes, drawings, sets, as-builts, risk, assumptions, lessons learned, meetings and
action items.

**Guidance is curated, never generated, and the fallback is the old copy** — so no module gets worse.
There are 133 modules and the other 109 keep the generic line on purpose: a plausible-sounding
invented upstream is a **confident wrong answer in a place the user has no way to check it**, which
is the failure mode running through this whole ring — the doubled `get_area`, the classification
fallback that priced everything as `01 00 00` while reporting a complete takeoff, an empty chart
frame that looks exactly like a chart. A well-formed artifact standing in for a missing answer.

**The test earned itself before it was written.** `emptyGuide.test.ts` reads
`services/api/modules/*/module.json` and asserts every key is a real module. The first draft of the
table used `change_order` and `pay_app`; neither exists — they are `change_event` and `owner_invoice`.
Two errors caught in the first run, and a rename now fails the build rather than leaving guidance
pointing at a register that is gone. It also asserts the *shape*: each entry must name an upstream
and must not contain "+ New", because guidance that restates the button is the thing being replaced.

*Verified:* 793 tests, typecheck and lint clean; the app loads against the live API with the changed
module engine, six room tabs, no console errors. **Not exercised end-to-end:** the empty branch
itself — every module in the dev database has at least one record, and manufacturing an empty one
would have meant writing to another session's dev data. The branch is unit-covered; the live check
confirms the surrounding render path is intact.

## v0.3.786 — the public demo was serving a taxonomy the app cannot render

The GitHub Pages demo reads a **captured** snapshot, `apps/web/src/demo/demoData.json`. A capture is a
photograph, and this one was taken before the room spine moved twice.

Measured, not suspected. The old snapshot held **132 modules across four rooms** — `model` 38 ·
`schedule` 41 · `cost` 37 · `deal` 16. The app has **six**, and three of those four names were wrong:
`model` was renamed **`design`** at v0.3.766, and `planning` and `work` did not exist in the file at
all. So the public demo — the thing a first-time visitor sees — served **38 modules pointing at a room
id the shell cannot render**, with rooms missing entirely.

Regenerated: **133 modules** across `design` 39 · `schedule` 42 · `cost` 20 · `planning` 16 ·
`deal` 16. Five, not six, and that is correct rather than a remaining gap: **`work` owns no sections
by design** — it is the ball-in-court queue, filled from what is in your court right now, not a home
for registers. Verified against `ROOM_OF_SECTION`, which maps zero sections to it.

**The interesting part is why nothing caught this.** Every gate here measures the *app*: `rooms.py`
fails the build if a section has no room, `test_module_rooms` enforces it, `roomNames.test.ts` now ties
the Python and TypeScript label tables together. None of them read the snapshot, because the snapshot
is data, not code — so the room spine could be renamed with full test coverage while the demo quietly
kept describing the old one. A capture rots silently by construction: nothing fails when the thing it
was copied from moves.

Also folded in: five backend PRs merged after their own CI gates — **#94** R23-DIGEST, **#95**
R22-NOTICE-CLOCK, **#96** R23-PREFAB-KIT, **#97** R22-CLASSIFY-ASSIST, **#99** R22-ENTITLE-RISK. Each
arrived without version files or CHANGELOG so its branch could not fight a release commit; this is the
batch that picks them up. **#98 was deliberately not merged** — it carries a genuine CodeQL HIGH
(`py/clear-text-logging-sensitive-data`), and a security gate is not something to merge past because
the finding looks harmless.

## v0.3.785 — R24-REPORTS-BY-MOMENT: the Report Center stops being a list of nouns

The audit's finding 16, and the numbers make the case better than the finding did: **56 reports under
18 group headings, six of which hold a single report.** The groups are accurate — `Cost`, `Quality`,
`Logs`, `Preconstruction` — and accuracy was never the problem.

Nobody opens the Report Center wanting *a cost report*. They open it because the owner's monthly
package is due Friday, or the lender wants a draw supported, or the IC meets Tuesday. The catalog
answers **what kinds of report exist**; the user asked **what do I owe, to whom, by when**. That is
the same routing-versus-browsing distinction the room spine settled for modules, arriving one layer
down — a taxonomy is a fine way to *hold* 56 things and a poor way to *reach* them.

Seven packages now sit above the groups, collapsed by default: **monthly owner package · lender draw ·
investment committee · preconstruction/GMP handover · design issue/model handover · closeout &
turnover · ownership quarter.** Each carries the line that makes it a moment rather than a category —
who is asking, and when. The audit named four; the other three came out of laying the actual catalog
against occasions, and each is a recurring deliverable with reports already built for it.

**Nothing is removed.** Every report is still under its noun heading below, which remains the right
structure for browsing the surface area — the same shape as "the catalog survives behind All modules".

Three rules the table follows, each of which is a way this feature normally rots:

- **A report appears in several packages, and most do.** `verified_progress` is evidence in a lender
  draw, in a monthly package *and* at closeout. The group taxonomy can only file it once, and being
  forced to pick is what made the catalog hard to route through. A test asserts the overlap exists —
  if every report belonged to exactly one package we would have rebuilt the noun catalog with
  friendlier headings, which is the failure the audit warns about.
- **A package naming a report the server does not serve is surfaced, never dropped.** A package that
  renders four of its six rows looks complete, and the two missing are precisely the ones nobody
  notices. Same rule the spine applies to an unroomed module.
- **The drift is caught at build time.** The catalog lives in Python. `reportMoments.test.ts` reads
  `services/api/src/aec_api/reports.py` and asserts every id the packages name is still defined —
  same technique as `roomNames.test.ts`. Without it, a renamed report costs nothing at build, nothing
  at runtime, and quietly shortens a package on the Friday it is due. The parse itself is guarded, so
  a restructured `reports.py` fails loudly rather than returning an empty catalog and making every
  assertion vacuously pass.

Verified against the live API: all seven packages render with real counts (11 · 7 · 7 · 6 · 8 · 7 · 6),
zero missing ids, all collapsed, no console errors.

## v0.3.784 — `safeHref`: the sink that no gate in this repo was watching

Found by review of the v0.3.780 job tray, not by a scanner — which is the point of the entry.

The tray's Download link assigns `a.href = artifactUrl(job)`. That is a **different sink class** from
everything else in the module, and three separate defences all miss it:

- `textContent` does not apply — this is an attribute, not text.
- `escapeHtml`/`safeUrl` do not help on their own: **`javascript:alert(1)` contains nothing to
  escape**, so an escape-based defence sees a perfectly clean string.
- `innerHtmlGuard.test.ts` watches interpolation into `.innerHTML`. An `href` assignment is outside
  it entirely, so the repo-wide ratchet would never go red.

It was safe, and it was safe *by argument* rather than by construction: `artifactUrl` resolves to
`api.jobArtifactUrl(pid, id)`, which **builds** a fixed path on a fixed origin. Nothing
plugin-controlled reaches the scheme. But the invariant holding it up — *builds a URL rather than
passing one through* — is one line away from being false. Wire it to a server-supplied
`job.result.artifact_url` and it goes live, having passed every gate on the way in.

So `ui/feedback.ts` gains **`safeHref`**: the same scheme allowlist as `safeUrl`, without the HTML
escaping, for property and attribute assignment. The two now share one `schemeAllowed()` predicate
rather than a copied regex, because two copies of an allowlist is how one of them quietly stops
matching the other.

**Why it is not just `safeUrl`,** which is the plausible wrong fix: `safeUrl` HTML-escapes, correct
when interpolating into an HTML string and wrong here — it rewrites `?v=2&inline=true` into
`?v=2&amp;inline=true`, producing a broken link that still looks defended. There is now a test
asserting a legitimate query string comes back byte-for-byte, specifically to fail on that fix.

## v0.3.783 — R24-CHARTS-GRAMMAR: an empty chart now says so

The audit's finding 15 is that `ui/charts.ts` is a dependency-free SVG kit "that has not been given a
grammar" — thirteen chart functions with no shared rules for axes, legends or empty states, which
will drift apart as the surfaces multiply. This is the first rule, and it turned out to be the one
already costing something.

**Only `histogram` handled empty input.** The other twelve rendered their frame — axes, four
gridlines, a legend — with nothing plotted. Probing all of them first showed no `NaN` and no
`Infinity` reached any path, so nothing was *broken*, and that is exactly why it survived a year of
review: an empty axis frame does not look like a defect, it looks like a chart. It is
indistinguishable from one whose data failed to load, and it shows up precisely where the user cannot
tell the difference — on a project that has not got there yet.

That is the same failure `noProjectHtml` prevents one layer up, and the same rule the vitals strip
follows: an absent number renders as an em-dash with its reason, never as a plausible zero. All nine
framed charts now return one shared `noData()` state, and `histogram`'s hand-rolled copy was replaced
by it.

The enforced half is `CHART_KINDS`. `charts.test.ts` walks it and asserts each chart returns the
shared state for empty input **and** that the list matches the module's own exports — so a fourteenth
chart added without an empty state fails the build. That guard was checked by temporarily adding a
chart and confirming the test goes red, because a drift guard nobody has seen fail is a guard nobody
knows works. `progressBar` and `sparkline` are documented exclusions: neither draws a frame that
could be mistaken for data.

The old bar was "empty is safe", and every chart cleared it. Safe is not the same as honest.

## v0.3.782 — R24-KEYS: one keyboard help, and it is true

The audit asks for a **published keyboard contract** and supplies one: ⌘K · `G then M` · `J`/`K` ·
`A` · `W S C B` · ⌥click. Most of that does not exist in this app. Publishing it would have been the
easy, wrong version of this item — a contract that lies is worse than no contract, because the person
who tries `J`, gets nothing, and goes back to the mouse has also stopped believing the keys that do
work. What ships here is what the handlers actually dispatch; the audit's unbuilt keys stay in the
roadmap as open work.

What was actually wrong was smaller and worse than a missing contract: **`?` gave two different
answers.** `main.ts` showed a six-second toast of six viewer keys. `viewer/keysDyn.ts` opened a modal
of fourteen two-letter draw codes. Which one you got depended on whether the 3D bundle had finished
loading, neither mentioned ⌘K — the single most valuable key in the product and the audit's whole
first move — and neither knew the other existed. Three keyboard surfaces, no overlap, and the one
most people press first disappeared after six seconds.

Now there is one, in `ui/keys.ts`, in three sections: **Anywhere** (⌘K, `\`, `?`), **In the 3D view**
(F · M · A · S · H · Esc, with a line saying they need an open model), and **Draw tools** — which is
omitted entirely when the viewer has not loaded, rather than listing fourteen codes that would do
nothing if pressed. It stays up until dismissed.

The draw codes are **not copied** into the help screen. They stay in `keysDyn.ts` beside the handler
that dispatches them, and `keys.test.ts` asserts the two agree in **both** directions — a new tool
with no published key fails the build, and so does a published key for a tool that was removed. Two
lists encoding one fact always drift, and the drift is invisible until somebody presses the key.

The test also pins the contract to the handler itself: every key `main.ts` forwards must appear, and
nothing extra may be claimed. That assertion failed on its first run — the published label is `Esc`
and the dispatched `KeyboardEvent.key` is `escape` — which is the right failure, and it is resolved
by mapping label to event name in the test rather than renaming the UI to match an event constant.

## v0.3.781 — SEC: an imported schedule's text is not ours to trust

Two `innerHTML` interpolations in the Schedule panel took an activity's **name** and **status tag**
unescaped. Both arrive from an imported Primavera P6 (`.xer`) or MS-Project (`.xml`) export — a
third-party file, produced elsewhere, by someone else. That is the same class as the submittal title
lifted from an uploaded document in v0.3.776: not user input in the obvious sense, which is exactly
why it reads as safe.

The ratchet in `innerHtmlGuard.test.ts` moves `portal/panels/schedule.ts` from **8 to 6**. Lowering
the baseline is the half that keeps it honest — a ledger that only ever records the worst case drifts
from the code it describes and starts granting permission it was never asked for.

Found and fixed by the security-audit session; landed here so it stops sitting uncommitted in a
shared tree. Verified standalone: 29/29 across the guard and the schedule panel.

## v0.3.780 — the queue was always there; nothing had ever asked it

### R24-JOB-TRAY — heavy work you can walk away from

The design audit's fourth finding is that convert, reindex and republish are *background work with a
foreground UI*: anything that can take a minute must be leaveable, resumable and visible from
anywhere, or people sit and watch it finish.

It was never a missing engine. `routers/jobs.py` has offered enqueue / poll / list / artifact for a
long time, over a durable queue with crash recovery and seven registered kinds — and
`grep -rn "/jobs" apps/web/src` returned **nothing**. No client had ever called one of them. Every
gate in this repo measured the queue; none measured the path to it, which is the same shape as the
seven unrouted modules found on 2026-07-26 and the reason `test_reachable` exists.

So this release is wiring. `ui/jobTray.ts` holds the whole feature and the mount in `main.ts` is a
handful of lines. Four rules it carries, each of them a way a status list normally stops telling the
truth:

- **The badge counts only what is still moving** — `queued + running`, never the total. A badge that
  includes yesterday's finished exports is a number nobody can act on, the same reasoning that
  governs the room badges.
- **A failure does not scroll away.** Errors sort above running jobs and stay until dismissed. Plain
  newest-first — the obvious sort — buries the one row that needed a human beneath the three jobs
  that succeeded after it.
- **Polling stops when nothing is moving.** An idle project makes no requests at all. Five SSE
  handlers once blocked the event loop by polling inside `async def gen()`; a tray that polls a
  finished queue forever is that mistake with a nicer face.
- **There is no cancel button,** because the server has no cancel. A control that cannot do what it
  says is worse than an absent one.

One limitation, stated rather than papered over: a job enqueued by *another* user appears at the next
poke, not immediately. The SSE feed carries records, not queue transitions, and a background poll
would be inventing a guarantee the backend does not offer.

### R24-CMDK-GROUPS — the palette had a `group` field nothing read

`Command.group` has been on the interface since the palette shipped and `paint()` never looked at it.
The audit asks for results grouped by *verb / record / element / report*, "never a flat list"; the
grouping was designed, left unwired, and looked finished. Six workspaces, 130-plus modules and every
record hit arrived as one undifferentiated column.

Now sections render in the order the question is asked — **Do · Records · Elements · Reports ·
Modules · Go to** — and a command with no explicit group is placed from the `hint` its caller already
sets, so every existing call site improved without being edited. The palette also remembers the last
twenty commands you ran and ranks them up, capped deliberately below the prefix-match bonus: what you
typed must always beat what you happen to have run before.

**And the cap is per section, which is the interesting part.** Grouping alone made the palette
*worse*. `Go to` sorts last by design, and with 130-plus modules ahead of it a flat 40-row limit cut
every workspace off the list — the palette gained sections and silently lost navigation. That was
caught in a browser, not by any of the unit tests written alongside the feature, which is worth
recording: the tests asserted that the grouping was correct and could not see that the result was
unusable. `takePerGroup` is the fix and there is now a test that reproduces the defect before
asserting the repair.

### Also

- `docs/roadmap.md` R24 re-verified against the code, finding by finding — 3 closed, 6 partial,
  6 open, 1 deliberately reversed. Six items that the original transfer dropped are reinstated,
  the largest being **R24-BASELINE**: the audit's phase 0 said *instrument before you redesign* and
  none of its six metrics were carried, so the shell was replaced with no way to score the result.

## v0.3.779 — one front door, and the rooms keep their names

### `?shell=classic` is gone

The room spine became the default at v0.3.715 and the opt-out survived sixty-four releases after
that. It has earned its removal.

Two shells is two of everything: two rails to keep in step, two paths for a defect to hide in, and —
as this repo actually managed — **a render audit whose verdict depends on which shell it happened to
measure**. `liveAudit` carried a `shell` field for exactly that reason, added after a "all 7
workspaces ok, 0 problems" result measured against the classic shell was read as evidence for the
redesign it had never touched. An escape hatch nobody is escaping through is not safety, it is a
second product.

Deleted with it: the lifecycle-stage rail, the per-workspace stage-collapse memory that existed only
to serve it, the workspace-button rail, and the `shell-spine` storage key. `spine.test` now asserts
`spineEnabled` and `SPINE_FLAG` are **absent** — a revert should fail a test, not quietly restore a
second shell.

**What the two-shell period bought is kept.** Its real product was never the fallback, it was the
guarantee that *nothing became unreachable*. `parity.test` still asserts the room rail reaches every
destination the lifecycle-stage catalog lists, so `destinations.ts` stays — no longer as "the old
rail" but as the spec of what must remain reachable. `compareShells` likewise survives as
`compareRuns(before, after)`: the question was never really about shells, it was *did a pane that
used to render stop rendering*, which any UI change can cause.

One thing removed rather than kept: `summarise()`'s `shell` field. With a single configuration it is
a constant, and a constant restating the only possibility is not a disclosure. The lesson it encoded
is written where it will be read if a second shell ever returns.

### ROOM-NAMING — settled on professional terms

The prototype named the rooms Building · Budget · Timeline · Money · My to-do. We ship **Design ·
Planning · Cost · Schedule · Deal · Work**, and that is now a decision rather than a pending question.

Not formality — *these are the words the work already has*. An architect issues a **design**; a
contractor runs a **schedule** and reports **cost**; a developer works a **deal**. A plain label reads
friendlier right up until somebody has to decide whether "Money" means the budget, the commitment,
the pay application or the equity draw, at which point the friendly word is a second vocabulary
stacked on the real one. A tool for professionals that renames their own domain gets harder to use in
exactly the moments that matter.

**The part worth testing was never the taste — it was the drift.** The labels live in two tables:
`rooms.ROOMS` in Python (what `/rooms` serves) and `FALLBACK_ROOMS` in TypeScript (what renders when
that request fails). Nothing asserted they matched. With the classic shell deleted the fallback is
load-bearing, so a divergence would rename the rail on someone's screen at the precise moment the API
hiccuped. `roomNames.test.ts` reads `rooms.py` from disk and asserts the two agree label-for-label,
that the set is exactly the settled six, and that no prototype name has crept back — verified by
mutation: renaming Cost to "Money" in the Python table alone fails three of its four assertions.

Gates: web 747/747, typecheck + eslint clean. No Python behaviour changed (`rooms.py` gained the
decision record only).

## v0.3.778 — the R27 ring closes: a received sheet has regions, and a firm has standards

### R27-LAYOUT (b) — the layout layer of a sheet we did not draw

The platform treats the model as data and the drawing as a picture with some text behind it. For
sheets *we* generate that stopped being true in v0.3.702: `sheet_regions()` keeps the rectangles
`compose_viewports` already computed, so a takeoff can be scoped to a viewport without calibration.

Every sheet that arrives from a consultant still had no answer. `sheet_extract` reads the text layer
and regexes sheet numbers out of it with **no notion of where on the page anything sits**, so a note,
a takeoff and a revision could only ever attach to a page number — not to the view they govern.

`sheet_recover.recover_regions()` reads the layout layer back out, served at
`POST /projects/{pid}/drawings/received-regions`.

**Deterministic vector geometry, not a document-layout model.** The layout-analysis paper this ring
is built on reports that pre-training on general document layout actively *hurts* on construction
sheets — **0.589 against 0.727** for the same architecture randomly initialised. Construction sheets
are not documents with unusual furniture; they are a different distribution, and a model that has
learned "this is a paragraph" is confidently wrong about them. Meanwhile the regions are not inferred
at all: titleblock borders, viewport frames and table rules are literally `re` operators in the
content stream. Detection is what you need once the vectors are gone. Where they are, this says so.

**What it refuses to do.** `to_page` is `null` for every region and never identity — the page↔world
affine cannot be recovered from a sheet we did not draw, and an identity would silently report page
points as metres. A scale printed on the sheet is a *claim on paper*, not a measurement, so it comes
back as `scale_denom_proposed` for a calibration step to accept. A takeoff auto-calibrated wrong looks
finished, which is worse than one nobody calibrated. A page whose vectors are gone returns a stated
`unknown` region rather than an empty list: an empty list is a claim about the drawing, `unknown` is a
claim about us.

### Two defects the tests caught by disagreeing with the code

**Rectangles must be transformed through the CTM stack.** Reading `re` operands raw is the obvious
implementation and it is wrong on every sheet whose views are placed with `cm` — which is most of
them. The test draws a 150×120 rect inside a 2× scaled, translated graphics state and asserts it comes
back as 300×240 at the page origin it actually occupies.

**A region's kind is decided by the text it owns, not all text inside it.** Sheets nest: a revision
table sits inside the titleblock column. Reading all contained text let the innermost box's vocabulary
classify every ancestor, so the titleblock came back as a "revision table". Text is now charged to the
smallest rectangle that holds it, which is what "which region is this?" actually means.

And one about the test itself: the border check first asserted "no region covers ≥98% of the page" —
**restating the implementation's own constant**. It passed while the drawing border sat in the output
classified as a viewport, because a border inset 10pt on an A4 is only 97.6% of the page. It now
asserts against the rectangle the test drew. A test that repeats the code's threshold measures nothing.

Verified through two independent implementations of the PDF spec: the fixtures are written by
reportlab and read by pypdf. A round-trip through one library's own writer+reader pair passes just as
happily on a wrong understanding of the format — which is exactly how the 4D binding once shipped
encoding the wrong IFC relation while its own test round-tripped perfectly.

`test_reachable` confirms the module is callable rather than merely correct: across v0.3.701–710,
seven of eleven things built shipped with no route at all.


### R27-FIRM-MEMORY — standards that outlive a project

`rule_library` is scoped per project; so are `design_standards` and `standards_expert`. But a firm's
standards are precisely the thing that does *not* change per project — "every L1 door needs a fire
rating" is true on the next job too. Re-authoring it per job turns one standard into forty slightly
different ones, with no way to say which is the standard.

Firm rules now live under a reserved storage scope, reusing `rule_library`'s own blob path **and its
validator** — one persistence path, one definition of a valid rule. A rule that would be rejected on a
project is not accepted merely because it was authored at the firm level, and the save stays atomic at
both tiers.

A project layers over the firm's **by rule id, not by name**. Matching on name would make a rename
look like a new rule and silently reinstate the firm's version alongside the project's — one rule
applying twice under one id is worse than either version alone.

**The override is the point.** A job whose client standard differs from the firm's is completely
normal, so overriding is legitimate. What is not legitimate is it being invisible: every effective
rule states its `source`, and one that displaces a firm rule carries the version it replaced. The
failure mode here is not a wrong answer — the project passes its checks either way — it is a firm
discovering its standards had quietly become optional. `PUT /firm/rules` is admin-only for the same
reason: a project editor may override a standard on their own job; changing what the firm stands for
is not a per-project act.

**The scope question, answered rather than assumed.** The item asked for an "org-scoped" tier, and
this codebase has no `Organization` entity — what `test_tenant_scoping` calls a tenant is RBAC over
project membership. Rather than invent a multi-tenant model nobody asked for, *firm* means **the
deployment**: a self-hosted install is one firm's install. That limitation is written into the module
rather than papered over; if organisations arrive later, `FIRM_SCOPE` becomes an org id and the
inheritance logic does not change.

Deliberately not an AI feature — the products selling "institutional memory" reduce to clean
extraction plus safe write-back. Both already existed; what was missing was somewhere for a rule to
live that is not a project.

**This completes the R27 ring.**

Gates: backend **423/423** suites with `test_sheet_recover` (19 checks) and `test_firm_standards`
(14 checks) registered; `test_reachable` 301/305 — both new modules are callable, not merely
correct, which across v0.3.701-710 was the difference seven of eleven shipped things got wrong;
ruff clean.

## v0.3.777 — every model gets a container, and the viewer stops guessing which one

### The viewer picked geometry by matching the project's NAME

`viewer/app.ts` held a function that mapped a project name to bundled `.frag` files:

```ts
if (/school/i.test(name)) return [["/school_str.frag", …], ["/school_arq.frag", …]];
```

A user project called "Riverside School" with no published model therefore rendered **an unrelated
demo's structural frame** — presented as theirs, silently, with the panels reading from a different
model entirely. With no project at all, the same two files loaded unconditionally. Two projects can
share a word in their names and share nothing else; the only correct key is the project id.

The gate meant to prevent this already existed and passed. `library.test.ts` asserted "the three
hard-coded .frag samples are gone" — of `main.ts`, while all three lived in `viewer/app.ts`, as the
default. **A check scoped to one file measures that file, not the behaviour.** It now reads the
viewer too, and separately forbids a name-regex model picker; both assertions were mutation-checked
by reintroducing the defect and confirming they fail.

With nothing referencing them, the three `.frag` assets are deleted — **7.4 MB** off every web build
and desktop installer. `loadSample`, the function that existed only to fetch a bare `.frag` by path,
went with them: defined, re-exported on the viewer's public API, called by nobody.

When there is no project model the canvas is now empty, which is the honest answer. The status bar
already says what to do, and the sample library is the real way in.

### Opening a model produced a mesh, not a project

Opening an IFC with the backend reachable but no project selected fell through to `view only`. That
is a thing you can orbit and nothing else: no quantities, no estimate, no schedule, nothing to pin an
RFI to, and nothing kept when the tab closes. The server was reachable the whole time — the code
simply had nowhere to put the model and gave up. The same branch also sent large files down the
in-browser parser with a "this may be slow" warning, while the server-side conversion path sat one
condition away.

It now offers to create a container, uploads through the ordinary publish path, and lands you in the
finished project. **Offers** — creating a project writes a real row into the user's database, and
doing that unasked is precisely the unconsented side effect the sample picker deliberately refuses to
commit. Decline, or be offline, and view-only remains; the two now read differently, because "offline"
and "you said no" are not the same message.

`fileIO.test.ts` gates the rule, including that the confirmation *precedes* the write — a consent
check that runs after the row exists is decoration. Verified by mutation: removing the confirm fails
the ordering assertion, and disabling the branch fails the branch assertion.

### The menus say what things are

Open ▾ led with "New model from scratch" — a create action, first item of a menu named Open — and
filed samples under "Sample models" as though they were still bare meshes. Both dropdowns are now
grouped by what the thing *is*: **Project** (new · open `.mass` · sample) · **Model geometry** ·
**Site context** · **Import from Revit / CAD**. A sample is a project now, so it sits with projects.

Gates: web 715/715, typecheck + eslint clean. No Python changed since the 421/421 backend run in
v0.3.776.

## v0.3.776 — a sample worth opening, and a ratchet on unescaped HTML

The library had a house: 23 elements, seven walls, a roof. It earns its place — it was authored in
the browser by the same edit recipes a user drives, so it proves the authoring path end to end. What
it cannot do is look like a building. A first-time visitor opening a 23-element house learns that the
viewer renders, and nothing else.

`riverside_school_structural.mass` is the second container: **1551 elements** — 619 reinforcing bars,
375 beams, 299 slabs, 203 columns, 22 members, 15 element assemblies, across 5 storeys. A structural
frame with its reinforcement modelled, which is the point: the panels have something to measure.

It was packaged through **the path a user takes**, not a fixture writer — `POST /projects`, then
`POST /projects/{pid}/source-ifc?publish=true` with the real 8.4 MB IFC, publish, then
`build_samples.py`. A sample built by a private route would sooner or later demonstrate behaviour the
product does not have.

**The school is structure only, and the vitals strip says so.** There is no `IfcSpace` in the model,
so Area reads `—` ("no space areas recorded") and $/ft² follows it, because a figure over a missing
denominator is not a figure. That is the em-dash rule from v0.3.773 doing exactly its job on the most
visible model we ship. Showing `0 ft²` here would be the easier demo and the dishonest one.

Both containers are now described in `samples/README.md` with what each demonstrates, so the library
says why it has two rather than leaving the pair unexplained.

Verified from the artifact, not the build log: `GET /samples` lists two entries; the school's
manifest reads `readable: true`, `has_geometry: true`, `elements: 1551`, `format: massing.project`,
`version: 2`. `test_samples` passes — its "ships at least one .mass" assertion now names both.

### SEC — user text reaching `innerHTML` unescaped, and a ratchet so it stops coming back

An audit pass found free text interpolated into `innerHTML` without `esc()` across nine files: a
submittal title lifted from an **uploaded document**, a `trade` parameter echoed back, an upload
filename, and server error strings — a 422 detail can quote the caller's own input. Each was one
missed call from stored XSS, and in every case the surrounding lines in the *same function* already
used `textContent`. The defect was inconsistency, not ignorance, which is precisely the kind that
returns.

So the fix is a ratchet, not a sweep. Escaping every site at once cannot be done safely — most
interpolations are literals passed to helpers (`stat("Budget", n)`) and a few carry deliberate markup
(rail icons), so blanket escaping would break UI to fix nothing. `ui/innerHtmlGuard.test.ts` instead
records a per-file baseline of unescaped hot interpolations and enforces that **the number only ever
goes down**: new code cannot add one, and a file that improves without lowering its baseline fails
too — otherwise the ledger drifts from the code it describes and starts granting permission it was
never asked for.

## v0.3.775 — TRACE-UI: a coverage number you can open

The 5D chain ran one way. You could ask *"what did this element cost?"* — paste a GlobalId, get the
budget, commitment, direct-cost and sub-invoice lines behind it. You could not ask the reverse:
**"which elements make up this number?"**

The evidence was already there and being discarded. `traceability.summary()` reads `ln["guids"]` for
every cost line, uses them to decide whether the line counts as traceable — and then aggregates only
the money, dropping the GlobalIds at the cost-code level. The figure survived; what proved it did not.
**A coverage percentage you cannot open is a claim, not a trace.**

Each cost-code row now carries `element_count` (exact) and `guids` (capped at 200), and the panel
makes the row a disclosure: click it, see the elements behind that figure, click any one of them to
run the existing "what did this cost?" lookup — the same implementation, not a second answer to the
same question.

Two details that are the point rather than polish:

- **A row with no elements is not clickable.** Offering a disclosure that opens onto an empty box is
  exactly the failure the coverage number exists to warn you about.
- **A truncated list says it is truncated** — "412 elements — showing the first 200". The count is
  always exact. A capped list presented as complete is the same defect as a fabricated number, which
  is the rule the vitals strip was built on two releases ago.

Keyboard-operable (`Enter`/`Space`, `aria-expanded`) since it is a real disclosure, not a hover trick.

Verified against the engine's own aggregation: two cost lines tagged `G1,G2` and `G2,G3` on one code
yield `element_count: 3` — deduped across lines, not summed — and an untagged code yields `0` with no
disclosure offered.

Gates: web 708/708, typecheck + eslint clean; `test_traceability`, `test_cost`, `test_cost_spine`,
`test_cde`, `test_disciplines`, `test_element_facts` all pass; ruff clean.

## v0.3.774 — VITE-8: Vite 6 → 8 (Rolldown) + Vitest 3 → 4, and a vendor split that had stopped splitting

The one genuinely outstanding item from the closed PR #69. Its other runtime bumps were already on
main (Capacitor 8.4.2, postgres:17) or superseded — the PR wanted Node 22 and main runs 24 — so this
is the whole of what was worth carrying, landed fresh with the full gate rather than by rebasing 258
commits.

Vite 8 replaces esbuild + Rollup with **Rolldown** and the Oxc transformer. `build.rollupOptions`
becomes `build.rolldownOptions`. Node ≥ 22.12 required; we run 24.

### The chunking regression, which the build would not have told us about

`manualChunks`' object form was **removed** in Vite 8, and the function form is deprecated. Migrating
to the function form is what the closed PR did, and it *looks* correct — the build succeeds, and it
still emits a chunk named `three`.

That chunk was a **94 KB re-export shim**. three.js itself — 1.5 MB of it — had been folded into the
`thatopen` chunk. Measured rather than assumed:

    grep -c WebGLRenderer  thatopen-*.js → 8      three-*.js → 0     (before)
    grep -c WebGLRenderer  thatopen-*.js → 0      three-*.js → 8     (after)

Fixed by moving to Rolldown's native `advancedChunks`, which is the supported mechanism the
deprecated one defers to:

| | before | after |
|---|---|---|
| `three-*.js` | 94.8 KB (shim) | **1618.7 KB** |
| `thatopen-*.js` | 6611.3 KB | **5077.0 KB** |

1534 KB left thatopen and 1524 KB arrived in three — the numbers cross-check. **A vendor split that
silently stops splitting is the worst kind of build regression**: nothing fails, the bundle still
works, and three.js merely stops being separately cacheable so every That Open patch re-downloads it.
The only way to catch it is to grep the *output*; reading the config and believing it is exactly how
it survives.

One false lead worth recording: the first suspect was Windows path separators in the module id.
Normalising them changed the output hash not at all — the deprecated `manualChunks` simply is not
what drives Rolldown's chunking. Same content hash before and after is what proved it.

### The Vitest 4 failure

Vitest 4 could not start a single DOM test: `Cannot find package 'happy-dom'`. It was not missing —
`happy-dom` has been a declared dependency of `apps/web` for months.

**Vitest 4 hoisted to the repo root while `happy-dom` stayed in `apps/web/node_modules`.** Node
resolves upward from the *importing* package's location, so vitest at the root can never see a
sibling workspace's modules. Vitest 3 loaded the environment relative to the test file, which hid the
asymmetry completely. Fixed by declaring `happy-dom` at the root as well — a hoisting declaration,
not a new dependency.

Both failures share a shape: the thing that changed was not an API that broke loudly, but resolution
behaviour that changed quietly underneath something that had worked for a year.

### Verified

Build green in 29s. WASM (`web-ifc`, `web-ifc-mt`, `laz-perf`) copied, PWA service worker + manifest
generated, 62 `.gz`/`.br` precompress pairs, hashed entry wired into `index.html`.
Web **708/708** under Vitest 4, typecheck + eslint clean.

### Also — CI hygiene, half of which was already done

Checked before building, and two of the four items were stale: Dependabot **already** covers all
three Docker directories with `@sha256` digest pinning, and there is **no nginx image** in the repo.
The two real ones:

- **MinIO was unpinned** (`image: minio/minio`), so it resolved to `:latest` and two machines could
  silently run different object stores. Pinned.
- **Nothing verified the Tauri `Cargo.lock` stays in sync.** Main had only a manual generator
  workflow — no CI check at all. Added to `rust-ci.yml` using `cargo metadata --locked`, which
  validates the committed lock *without* upgrading transitive patches. The obvious alternative,
  `cargo generate-lockfile` + git-diff, passes by rewriting the very thing it is meant to verify.

## v0.3.773 — R26-VITALS: the prototype's fourth pillar, finally built

**LOD · area · $/ft² · float · IRR · health**, along the bottom of every room.

This is why the app did not look like the redesign prototype. Three of its four pillars had shipped —
the room spine, the Inspector, the work-queue-as-home. The fourth sat in `roadmap-completed.md` **with
no tick**: filed under completed and never built, which is the most reliable way to lose a piece of
work, because nobody goes looking in the done pile.

It replaces audit finding 13. Fit / Grid / Section / Orbit / Snap / Units were pinned to the bottom of
*every* room — *"ten permanent controls, irrelevant on four of seven tabs, occupying the most valuable
strip of the window"*. They now live in `#sb-viewport` and appear only where there is something to
orbit. Verified live: **Design → controls visible; Cost → hidden**, with the same six vitals in both.

**One endpoint, not six client fetches.** `GET /projects/{pid}/vitals` assembles the six from the
engines that already own them — `bim_kpi.scorecard`, `schedule_cpm.compute`, `adjacency.summary`, the
proforma scenario, the cost rollup. Nothing is recomputed. That is not a performance choice: the same
audit's finding 03 is that the app contradicts itself on screen — one project scored 24 for model
health in one workspace and 77 in another — and five browser requests would rebuild exactly that.

**A missing number is an em-dash with its reason, never a zero.** A zero float reads as "no slack" and
a zero IRR as "worthless"; both are claims about a project, not about absent data. Live right now on
the showcase house:

    LOD    —  (23 of 23 elements have no LOD stage)
    FLOAT  0 days                                     <- a REAL zero: no slack is a fact
    IRR    —  (no solved scenario)                    <- not 0%, which would claim "worthless"

Two defects caught by checking rather than assuming, each of which would have shipped a permanently
blank cell that looked like a working feature: `element_facts.lod_summary` does not exist (the owner
is `representations.lod_summary`), and the health cell read `score` / `overall` / `percent` — **none
of which `bim_kpi` emits**. It reads `summary.health_pct` now, pinned by a test.

### Also — the DOCUMENT cluster was empty for most personas

v0.3.772 put Drawings and Specs in the viewer rail but added them to no persona's `rail` allow-list,
so under the default persona the heading rendered over nothing. Both are now in all seven
drawings-capable personas, and **a cluster heading hides with its items** — a label promising a
section it does not deliver is worse than no label at all.

## v0.3.772 — a DOCUMENT cluster in the viewer rail: Drawings and Specs

The rail an architect works in now reads:

    NAVIGATE    Tree · Layers
    AUTHOR      Tools · Props
    DOCUMENT    Drawings · Specs      ← new
    COORDINATE  Clash · Issues

Until now, from inside the model there was **no route to the drawings it generates**, or to the
specifications that describe them, without leaving the room via the legacy workspace bar. Model,
drawings and specs are one person's work; the rail is where that becomes true on screen.

Both are `launch` entries rather than side panels, and the distinction is deliberate: a sheet set
needs the whole canvas, not a 280px column, so forcing them into an `.rpanel` for the sake of a
uniform mechanism would have been the wrong shape. A launcher also never marks itself as the rail's
active *panel* — claiming a side panel is open when none is, is the same lie that made a `goto`
destination unlandable in v0.3.770.

Specs open in the Design room's portal — `design` is one of the three portal workspaces — and the
`spec_section` register is reachable because v0.3.767 gave every rail button a `data-mod`. The
opener retries until the register is **active**, not until its button exists, since the workspace
switch rebuilds the rail underneath it. That distinction has now cost two wrong fixes and one
reverted release, so it is written into the code where it is used.

Verified live by what renders: Drawings → `ws-drawings` showing "DRAWING SET · PDF Takeoff · Paper
space"; Specs → `ws-design` with **§ Specifications** active.

## v0.3.771 — revert v0.3.770's landing hack; the rule is now a test, not a comment

Code review caught a regression I shipped an hour earlier, and it was right on every point.

v0.3.770 tried to make a `goto` destination usable as a room's landing target by having the
workspace hand-off mark itself active. **The marker is sticky and nothing clears it**, so
`goToRoom`'s "have we arrived?" check returned true for a navigation that never happened. A second
Deal click — or Deal → Design → Deal — skipped the dispatch entirely and left the user on the
Developer dashboard with the Deal tab lit. That is precisely the "tab lights up, nothing moves"
defect v0.3.766 existed to kill, reintroduced by the fix for it.

**My "verified live: Deal → Underwriting, repeatably" was wrong**, and wrong in an instructive way: I
read `.pnav-item.active` — *the same marker the retry loop keys on*. Circular. Re-measuring the
**content pane** shows it said `Budget` throughout, while the rail claimed Underwriting. I had
written the "existence is not arrival" note two hours earlier and then checked a flag instead of a
render.

CI was **fully green** on the broken commit, which is the fourth finding: the rule forbidding this
lived in a *comment* (`destinations.test.ts`: "such a destination CANNOT be a room's landing
target"), so deleting the mechanism or breaking it both passed.

Reverted, and the invariant is now executable — `spine.test.ts` asserts **no room's home carries
`goto`**, mutation-checked by re-pointing Deal at `__uw__` and confirming it fails. Verified live by
*content*: Deal renders the real Portfolio panel on first click, repeat click, and after Design.

Deal reaching Underwriting needs `__uw__` to become a real portal panel rather than a workspace hop.
Tracked as **R27-UW-PANEL** — the honest fix, not a truer-looking flag.

## v0.3.770 — Deal opens on Underwriting, and Quality stays put

**A workspace hand-off is now a navigation like any other.** Two destinations — Underwriting
(→ finance) and Drawings (→ its own full-page surface) — carry `goto`: they switch workspace instead
of rendering a portal panel. They did not mark themselves active on the way out, which cost two
things. The rail lost its active marker entirely on the jump, so nothing on screen said where you
were. And **arrival became unobservable** — the room tabs land by retrying until the target is
active, so a `goto` destination could never be a room's home.

That is why Deal had been landing on Portfolio since v0.3.766 rather than on Underwriting, which is
what "underwrite it, fund it, lease it and dispose of it" actually starts with. Setting the key
before the hand-off fixes both. Verified live: Deal → **Underwriting**, repeatably, with Cost and
Schedule unaffected.

**Quality stays in Design — because the task already reaches Work.** The question was whether
inspections belong in Work rather than Design. They already do: the live work queue carries
`INS-001 "Level 2 deck pour"`, `DEF-001` and `NCR-001` right now. Work is a **queue over every
module**, not a register home — it has zero registers by design. Moving the `inspection` register
there would split one discipline across two rooms, leaving ITP, NCR, Test Records, Deficiencies and
Compliance Evidence behind, and would duplicate what the queue already does. The register belongs
with its discipline; the task belongs in your court; those are different objects and the app already
gets it right.

## v0.3.769 — the sample library actually ships (CI had been red all day)

`test_samples` was failing **every CI run**, while passing locally on every run. The failing check
carried its own explanation:

> `the shipped library directory exists on disk` — *"samples/ is committed"*

It was not. `.gitignore` held `samples/` outright, so the directory existed only on the machine that
wrote the test. **A rationale written into a test is a claim like any other, and this one was never
checked.** The test passed locally for an incidental reason — the files happened to be sitting there
— which is the most durable way for a gate to be wrong.

The fix ships what the library actually serves. `samples.py` reads **`.mass` containers only**, so
the containers and the README are now tracked (37 KB) and the multi-hundred-megabyte source IFCs stay
ignored — two of them are 52 MB each and were never library entries to begin with. A fresh clone now
has a sample library, which is what the first-run picker has been promising since v0.3.757.

The assertion is stronger too: a directory with **no containers** would satisfy an `isdir()` check
and serve nothing, so the library must now contain at least one `.mass`. Same failure this file
exists to prevent — a check that examined nothing reporting clean.

**Worth stating plainly:** CI had been failing on every run for a day, and earlier notes in this
project described those releases as CI-verified. They were verified by the local suite, `ruff`, the
web gate and live checks — all of which were green and all of which I ran — but the CI *workflow*
itself was red, and I should have been reading its conclusion rather than the conclusions of the
seven faster workflows beside it.

## v0.3.768 — sub-rooms: a room with 39 registers gets a second level

Design owns 39 registers and Schedule 41. A flat list at that size is exactly the wall the spine was
built to replace, so a room now groups its registers one level down.

**The grouping key is the module's `section` — which is already what decides its room.** That makes
this a strict *refinement* of the table in `rooms.py`, not a second taxonomy competing with it.
Inventing a separate sub-room list would have recreated the drift this restructure just removed.
Rooms below 8 registers, or with only one section, stay flat: below that the headings cost more than
they explain, which is why Work renders unchanged.

What an architect now sees under **Design** — the "sub-rooms for all the tools an architect or
engineer needs" in one room:

    Engineering 15 · Quality 7 · Design 3 · Information Management 3 · Sustainability 3
    Resilience 3 · BIM 2 · Specifications 1 · Design Phases 1 · Programming 1

And the others: **Planning** Preconstruction 12 · Contracts 4 — **Cost** Cost 10 · Change
Management 9 · Capital 1 — **Schedule** Field 14 · Resources 10 · Closeout 7 · Safety 7 · Schedule 2
· Project Controls 1 — **Deal** Operations 10 · Acquisition 2 · Market & Sales 2 · Feasibility 1 ·
Finance 1.

Verified live: **132 registers rendered, zero duplicate keys**, and every room's sub-counts sum to
its own total.

## v0.3.767 — one rail, one taxonomy: a room holds its registers

v0.3.766 gave the rooms the right names and the right tabs. The rail underneath was still filing
things twice.

A room group listed only its **panels**. Its **registers** — the ~130 config modules — were grouped
separately by *section* further down the same rail. Two taxonomies in one column, which is the exact
failure the spine was built to end, and it was visible in the numbers: Planning owned 16 modules and
its group showed 2.

Every register now renders inside the room that owns it, read from the `room` the API already states
per module rather than re-derived here — re-deriving is how four competing rails came to exist. The
section grouping is dropped under the spine, so nothing appears twice; Favourites and Recent stay,
because a personal shortcut is not a second filing system. Panels come first, then a quiet
`Registers (n)` divider, because a panel answers a question and a register is a table you keep.

Verified live against the API's own allocation — the rail and `GET /rooms` agree exactly:

| Room | Panels | Registers | API |
|---|---|---|---|
| Design | 20 | 39 | 39 |
| Planning | 4 | 16 | 16 |
| Cost | 7 | 20 | 20 |
| Schedule | 4 | 41 | 41 |
| Deal | 11 | 16 | 16 |
| Work | 1 | 0 | 0 |

**Zero duplicate module keys** anywhere in the rail, down from a column that rendered many of them
twice. Total rail items 250 → 181.

## v0.3.766 — the rooms go somewhere, and they are named for the work

### The Cost room was decorative

Reported from use: "the cost room doesnt seem to exist". It did not. Clicking **Cost** and clicking
**Schedule** rendered **byte-identical screens** — the tab highlighted, the content did not move, and
the room's nine destinations (Budget, Cost-code Margin, Earned Value, WIP Schedule, General Ledger,
Cost Traceability, Benchmarks, Selections, Risk & Cost) sat one collapsed group away with nothing
routing to them. Three defects underneath, each invisible to every gate we own:

- **No room named where it opens.** Cost, Schedule and Work share the `construction` host workspace,
  so switching the workspace — the whole of what a tab did — left all three on the same screen.
  Rooms now declare a home (`ROOM_HOME`), and a test asserts each home belongs to the room claiming
  it, so the table cannot drift from `DEST_ROOM`.
- **A writer and a reader disagreed about a key.** `goToRoom` wrote `setRoomOpen("cost")`; the rail
  reads `readRoomOpen("construction:cost")`. The write landed in a slot nothing reads, which is
  indistinguishable from a write that worked.
- **The pinned rail clicked itself.** Rail buttons carried no `data-dest`, so the only nodes with
  that attribute were the pinned rail's own — and its "open what I pinned" handler matched itself.
  Rail destinations are now addressable (46 of them, from none), which fixes both.

Landing now retries until it **arrives** rather than waiting a fixed delay. Two guesses failed first:
120ms (too short once a room changes workspace) and then waiting for the button to exist — the rail
renders all five room groups in every workspace, so the button was present in the *outgoing* rail and
the click was discarded by the rebuild, leaving each room showing the previous one's content.
Existence was never the condition; arrival was.

Cost → Budget · Schedule → Schedule · Deal → Portfolio · Work → My Work, verified live in any order.
Deal lands on Portfolio because `__uw__` is the only destination in the app carrying `goto` — it
switches workspace instead of opening a panel, so nothing can land on it.

### Model became Design, and Planning split out of Cost

Two renames, both from use, both of which broke a gate before they broke anything else.

**Design.** "Model" named one *output* of that room, so drawings and specifications read as though
they lived somewhere else — and specifications actually did: `spec_section` was filed under
Preconstruction, and Preconstruction sat under Cost. An architect looking for the spec they are
writing had to go to the money room. Design now holds the model, the drawings, the specs and the
analysis, which is what one discipline actually does.

**Drawings had no destination at all.** Not misplaced — absent. `openDrawingsTab()` was reachable
only from the legacy workspace bar, so from the room navigation the drawing set did not exist. It is
now a Design destination alongside Documents.

**Planning.** Estimating, taking off, bidding and buying out are preconstruction work whose *outcome*
is money, which is not the same as being accounting. Filing them under Cost put a quantity surveyor
and an accounts clerk behind one tab and buried the takeoff a precon lead opens daily under a general
ledger they never open. Planning takes the Preconstruction and Contracts sections — estimates,
estimate sets, bid packages, solicitations, submissions, buyout, prequalification, value engineering,
assumptions, the decision log, the charter and the RACI. Cost keeps budget, change, billing and
accounting.

All 132 modules still resolve to exactly one room and none is unplaced:
**Design 39 · Planning 16 · Cost 20 · Schedule 41 · Deal 16 · Work 0**, verified against the running
API rather than the table that produced it.

**Known gap, measured not guessed:** a room's *modules* do not render inside its rail group. Planning
shows its 2 first-class destinations; its 16 modules are reachable but sit elsewhere in the rail. So
the room tabs are now correct and the rail is not yet — that is the next change, and it is the same
shape as the defect above: the grouping exists, the content does not route into it.

### And the tools moved to the room that owns them

Four destinations were sitting in rooms that did not describe them:

- **Risk Review** and **AI Assist** were in **Work**, whose job is *"whatever is in your court right
  now"*. Neither is — the source calls that pair "preconstruction intelligence": read an incoming
  contract for risky clauses, find scope gaps, level bids. Both moved to **Planning**. Work is now
  purely the queue, which is the only way a queue keeps meaning anything.
- **Energy** was in **Deal**. It is an engineering analysis run off the model geometry → **Design**.
- **Issue Board** was in **Schedule**. It records clashes and coordination questions raised *against
  the model* → **Design**.

### The README described a shell that stopped being optional 50 releases ago

It told readers to append `?shell=spine` "to turn it on". It has been the default since v0.3.715, so
following that instruction changed nothing and read as a broken feature. The walkthrough still had
users clicking a three-tab bar the five rooms replaced. Both corrected, and `docsCurrent.test.ts` now
**calls `spineEnabled()` and reads `ROOM_IDS`** and requires the prose to agree — it asserts nothing
of its own, so it cannot agree with itself while both drift from the product.

## v0.3.764 — the pinned rail, and the live pass that was the real gate

- **The rail renders state that already existed.** `readFavs()`/`readRecents()` have persisted since
  the portal shipped; the rail was the missing surface, not missing data — the same finding as the
  room tabs.
- **An unpinned rail shows recents, labelled RECENT.** A new user has no favourites, and an empty
  column beside a populated app reads as broken. But a recents list captioned PINNED would be worse:
  the rail would look identical before and after somebody pinned anything, teaching them that
  pinning does nothing. Never both lists at once — two identical rows meaning "I chose this" and "I
  happened to be here" is a list nobody can read.
- **Stale keys are dropped**, and that behaviour proved itself immediately: my own live probe seeded
  `rfi`/`submittal`, which are not destination keys, and the filter silently removed them. The rail
  was right and my test data was wrong.
- **The live pass closed the gap I flagged in v0.3.763.** With a model loaded and the viewer mounted:
  opening the More menu **closed** the Open menu (`openMenuClosed: true`) — the popup-pairing fix
  that previously rested on source assertions only is now verified. No watermark. No console errors.
  Five tabs, Work badge 70 matching that project's queue, "Close ACT-001 →" in the header.

## v0.3.763 — the three chrome defects from the screenshot

- **The More menu no longer scrolls sideways.** `overflow: auto` permits *both* axes, so anything
  past the 340px cap grew a horizontal scrollbar — a menu you scroll sideways to read is not a menu.
- **Hints take their own line.** `.vt-note` already asked for `flex: 1 0 100%`, but the row never had
  `flex-wrap`, so the request was silently ignored and the text ran off the edge mid-sentence. Long
  unbroken tokens now break rather than widening the panel.
- **One popup at a time.** Open/Save dismissed each other because both are `.menu-panel`; the
  viewer's `.vt-menu` was a separate system neither knew about — which is how two dropdowns ended up
  stacked over the model. Fixed with a shared `CLOSE_POPUPS` channel rather than another selector
  bolted onto another `querySelectorAll`, because two systems that cannot see each other will always
  reproduce this.
- **The That Open Company mark is off**, and the credit moved to `docs/credits.md` rather than
  vanishing. It is a deliberate, documented feature (`renderer.showLogo`, default `true`) whose own
  docs name "white-label embed, customer-branded surface" as fair reasons to disable it. MIT does not
  require the logo; it requires the notice, which travels with the source. The reasoning sits beside
  the flag — a bare `showLogo = false` reads as somebody hiding an attribution.
- **Verified live**: the room tabs, the header CTA, the Open menu. **Not verified live**: the
  popup-pairing fix needs a loaded model for the viewer toolbar to mount, so it rests on source
  assertions only. Said plainly because "fixed" and "proven fixed" are different claims.
- Three of today's tests matched **the comment explaining the fix** rather than the code. The CSS
  check now strips comments before asserting — rewording prose each time treats the symptom.

## v0.3.762 — NEXT BEST ACTION in the header

- One button, one verb, in the top bar. The room tabs say *how much* is in your court; this says
  *what to do about it*. Verified live: **"Close ACT-001 →"** beside a Work badge reading **74**,
  which matches the queue's real total.
- **One fetch feeds both** the badge and the CTA. Two requests would be two answers, and a count that
  disagrees with the action it summarises is exactly the contradiction this shell exists to remove.
- **Only offers what the caller can actually run.** `blocked_actions` are gated behind required
  fields — offering one as *the* next best action sends somebody to a form and calls it a
  recommendation.
- **Due dates compare calendar days, not instants.** An item due today at 09:00 is not overdue at
  17:00; telling somebody they are late for something due today is how a queue loses credibility.
  A missing or unparseable date is `null`, never `0` — a fabricated deadline is worse than none.
- **The server's action id is not a label.** It returns `close`, which rendered as "close ACT-001" —
  reads like a typo rather than an instruction. `verbLabel()` capitalises for display while leaving
  the id intact for anything that dispatches on it. Caught by looking at the live header, not by a
  test.
- Renders **nothing** when there is nothing to do, rather than "Nothing to do" — a claim that ages
  badly between polls and teaches people to stop reading the one place urgency lives.

## v0.3.761 — S4: the five rooms become the navigation

- **Model · Cost · Schedule · Deal · Work** replace the seven workspace buttons. Verified live: five
  tabs, zero `.ws-btn`, each carrying its room's *job* as the tooltip, no console errors.
- **The five tabs already existed.** `ROOM_IDS` has been `model/cost/schedule/deal/work` since the
  spine shipped; `GET /rooms` allocates every module to one, and `parity.test.ts` already proved none
  is unroomed. They were rendered as a **sub-rail inside three of seven workspaces** while the top bar
  showed the seven. This is a promotion of an IA that was built and buried, not a redesign — which is
  why it is ~100 lines rather than a rewrite.
- **Two rooms had no workspace of their own** — `cost` and `work` were only ever destinations inside
  the construction portal. That asymmetry is the honest reason the rooms were never top-level. They
  route via `ROOM_HOST`, and clicking **Cost** (the riskiest path) was checked live: correct
  workspace, Cost room present in the rail.
- **Only Work carries a count**, and that is the thesis: you never browse for work, work comes to
  you. A badge on every tab is a dashboard; a badge on one is a summons. Mutation-checked — giving
  every tab a count turns 3 tests red.
- The badge reads the real queue, fails open, and shows **nothing** rather than `0` when the request
  fails: "we don't know" and "nothing owed" are different claims, and conflating them is how somebody
  misses work.
- Rooms are matched by id, never by position — a reordered response would silently relabel every tab,
  and labels are what people navigate by.

## v0.3.760 — a first run never lands on an empty canvas

- With **zero projects**, startup opens the sample library. Nothing to render, price or coordinate is
  exactly the impression the library exists to prevent.
- **It opens the picker; it does not auto-import.** Importing writes a real project into the user's
  database, and doing that unasked on first load is a side effect nobody consented to — the
  difference between "here is something to look at" and "I made you something". Asserted: the startup
  path may reach `openSampleLibrary()`, never `api.openSample()`.
- **`=== 0`, not `< 2`.** Somebody opening the app with work in it wants their work, not a demo.
  Also asserted, because a later "helpful" loosening is exactly how this becomes an interruption.
- **Verified live, end to end**: the Open menu now carries one sample entry (was three), the picker
  renders "Maple Grove House — 23 elements · 34 KB" from the container's own manifest, and opening it
  produced a project with all 23 elements queryable — 7 walls, 3 slabs, a roof, 2 doors, 4 windows,
  6 openings.

## v0.3.759 — one "Load sample project", fetched not hard-coded

- **Three hard-coded `.frag` menu entries → one library-backed picker.** Those three shipped geometry
  and nothing else: you could orbit a school and see no estimate, no schedule, no RFIs. A sample now
  opens as a **project**, through the same `import_bundle` path a user's own `.mass` takes.
- **The list is fetched.** A hard-coded list is a promise that drifts from what is actually packaged;
  `GET /samples` describes each container from its own manifest, so the card cannot overstate what is
  inside. Counts shown per sample come from that manifest.
- **`api/library.ts` — a NEW domain landing as a mixin**, not two more methods on `client.ts`. The
  seam only helps if new work goes through it; otherwise extraction is a treadmill — carve 15 methods
  out one week, add 15 back the next. Asserted by a test.
- **One entry point**: the menu item and the command shortcut both call `openSampleLibrary()`, so
  they cannot disagree about what "a sample" means. The shortcut previously opened a different,
  hard-coded model.
- Sample names pass through `escapeHtml` — manifest text is file-derived, which is exactly the
  `js/xss-through-dom` path this repo has a standing rule about. Asserted.

## v0.3.758 — a real house in the sample library

- **`maple_grove_house.mass`** — 12 x 8 m, two storeys, **23 elements**: 7 walls, 3 slabs, a roof,
  2 doors, 4 windows, 6 openings, plus rooms and seeded project records. 34 KB, served by the live
  API. The library finally shows the platform rather than a mesh.
- **`build_showcase.py`** authors it entirely over HTTP, deliberately. A script reaching into the
  database would build a project the product cannot build, and a showcase that demonstrates a private
  path demonstrates nothing.
- **Publishing is asynchronous, and that is the whole story of this release.** The first draft fired
  ten edits with `publish=False` and one bare `POST /publish`; every `/edit` returned 200 and the
  model ended up with **one slab**. Each edit had raced the in-flight publish and overwritten the
  last — ten reported passes for a one-element house. `e2e_modeling.py` already had the barrier
  (publish per edit, then poll `/publish/status`); reading it first would have skipped the detour.
- Second race, same shape: `/elements` answers `404 no properties index for project` for a moment
  after publish. Querying immediately reported "0 walls", which reads exactly like authoring failed.
  The script now waits on the condition. Worth flagging as a product observation: to a client that
  404 is indistinguishable from *no such project* — "not ready" and "not there" deserve different
  answers.

## v0.3.757 — the sample library has never worked, and now does

- **`_DEFAULT_DIR` was off by one `dirname`.** From `services/api/src/aec_api/samples.py` it took four
  hops and landed on `<repo>/services/samples` — a directory that has never existed. So `GET /samples`
  returned `[]` for a library sitting in `<repo>/samples`, and **I recorded that empty list as correct
  behaviour** across two releases. Every test set `AEC_SAMPLES_DIR`, so the default the constant
  computes was never once exercised. A test that configures the thing it tests never tests the
  default — and defaults are what ship.
- **First sample packaged and served**: `riverside_house.mass`, 4 elements, geometry, real table
  counts, listed by the live API.
- **`build_samples.py` now FAILS on an unusable container** instead of printing "verified". It wrote
  one holding neither `model.frag` nor the element index and reported success, because `has_geometry`
  accepts `.frag` **or** `.ifc` and a source IFC was present — the single check that should have
  caught it passed for the wrong reason. It now asserts geometry, index and a non-zero element count,
  and on failure names the likely cause: `STORAGE_DIR`/`DATABASE_URL` not matching the API.
- Both packaging failures were **environment, not product**: the script defaulted to a different DB
  and a different blob directory than the running server. Worth stating because the symptom — an
  empty, cheerful "0 elements" — is identical to a project with no model.

## v0.3.756 — the mobile gate caught a real break on its first run

- **The Android build failed, and it was right to.** 30+ `Duplicate resources` errors: the default
  web build emits pre-compressed `.br`/`.gz` siblings for a static server, and Android's resource
  merger treats `foo.js` and `foo.js.gz` as the **same resource**. Measured: **120 siblings** on
  `npm run build`, **0** on `npm run build:mobile`, with all 67 JS assets still present.
- **The bug was mine, in the workflow — not in the build and not in Capacitor.** `vite.config.ts`
  already had `WEB_SERVED = !["desktop","mobile"].includes(mode)` and gates compression on it
  correctly. I wrote `npm run build` in `mobile.yml` instead of `npm run build:mobile`, so the mode
  was never passed. **This would have broken identically on Capacitor 7** — nothing had ever built
  the app, which is the entire reason the gate exists.
- `--mode mobile` also reads `.env.mobile`, where `VITE_API_URL` points at the hosted API. A phone
  has no local backend, so the previous command was producing a payload aimed at `localhost` as well.
- **Added an explicit assertion** that `dist` contains no `.gz`/`.br` before `cap add`. The Gradle
  failure names *resources*, not the build mode that produced them — 40 seconds of log that points
  away from the cause. The new step fails in one line, at the right place.

## v0.3.755 — the security audit branch lands

- `security/audit-2026-07` merged after **105 commits** apart, with **zero conflicts** — it adds new
  files and makes surgical edits rather than restructuring, which is why it aged well. Finished
  security work that had been protecting nobody while it sat on a branch.
- **`net.py` — a shared SSRF guard**, applied across `esign_bridge`, `license_cloud`, `re_bridge`,
  `securities_bridge` and `webhooks`. Closes **SSRF-via-redirect**: validating the URL you request
  proves nothing when a 302 sends the client somewhere else, so the redirect target is validated too.
- **`sandbox.py` hardening** — IO and DoS escapes in the IFC-code sandbox. Related standing lesson:
  a denylist cannot see methods reached through an injected object, and banning `while` does not
  bound execution.
- **SVG sanitisation** on rendered real-estate output, and the auth gate keyed to the **routed** path
  rather than the raw one.
- Verified before merging: `test_security_audit` passes (111 lines, and it is registered in
  `run_tests.py` rather than orphaned), ruff clean, and `test_license_cloud` / `test_reachable` /
  `test_route_authz` / `test_sandbox` / `test_webhooks` all pass against the merge — the surface the
  SSRF change actually touches. The full 416-suite gate runs in CI.

## v0.3.754 — the mobile gate that should have existed before Capacitor 8

- **iOS and Android are real targets, so the Android SDK job is justified.** `mobile.yml` builds the
  web bundle, runs `cap add android` + `cap sync`, and **assembles a debug APK with Gradle**. That
  last step is the assertion: everything before it can pass while Gradle still refuses to build,
  which is precisely how a Capacitor major breaks a project.
- **The platform is generated from scratch every run**, because `apps/web/android/` is gitignored.
  That is the point rather than a workaround — it proves the *committed config alone* suffices to
  produce an app. A checked-in `android/` can drift into working-by-accident.
- **The APK is size-checked, not just existence-checked.** A build can "succeed" without its payload;
  a green step is not evidence of an artifact.
- **iOS is deliberately excluded**: macOS runners cost ~10× the minutes and it cannot build without
  signing assets. Android catches the same class of breakage — plugin API changes, Gradle/AGP
  incompatibility, a missing `webDir` — at a fraction of the cost. Stated so nobody reads "Mobile ✅"
  as covering both.
- JDK 21, since Capacitor 8's Android platform fails on 17.

## v0.3.753 — four review findings, including one where I mis-stated the facts

- **v0.3.752 said the desktop/mobile build was "CI's" job. No such job exists.** A grep for
  `capacitor|gradle|android|mobile` across all nine workflows returns nothing — CI runs npm ci, lint,
  vitest, vite build and Tauri. **The Capacitor 8 major is verified nowhere.** I wrote a reassuring
  sentence and did not check whether the reassurance was true, which is worse than saying "unverified"
  because it stops anyone else looking.
- **`capacitor.config.ts` was outside every gate** — tsconfig `include` was `["src","scripts"]` and
  lint globbed `src/**/*.ts`, so the repo's only Capacitor consumer was invisible to typecheck and
  lint. That is *why* "no web source imports Capacitor" read as true. Both now cover it, and with the
  file inside typecheck the v8 `CapacitorConfig` type is confirmed compatible — the first actual
  evidence the major is safe. `vendorAlias.ts` was in the same blind spot and is now included too.
- **Version drift, reintroduced by the commit that fixed it.** The lock recorded `apps/web` at
  0.3.751 against a 0.3.752 manifest, because the lock was regenerated *before* the bump. It had
  been wrong since **0.3.655** — ~100 releases — because `npm ci` compares dependency edges, not
  version fields, and nothing else reads it. `versionConsistency.test.ts` now asserts manifest,
  `tauri.conf.json` and lock agree; mutation-checked against a planted 0.3.651.
- **`engines: ">=24"` against CI pinned to Node 22.** ci/desktop/pages/security all said 22 while the
  Dockerfile built on `node:24-slim`. With `engine-strict` unset this only ever surfaced as an
  EBADENGINE warning. All four now run 24.

## v0.3.752 — Capacitor 8, resolved by the npm CI will actually use

- `@capacitor/{android,cli,core,ios}` **7.6.8 → 8.4.2**, manifest and lock together. `npm ci
  --dry-run` resolves clean; no web source imports Capacitor, so this is mobile packaging only.
- **Resolved with a checksum-verified portable Node 24.18.0 / npm 11.16.0**, not the Node 20 on this
  machine. That mattered: the earlier attempt with the local npm 9 **exited 0, rewrote 334 lines, and
  left the lock on 7.6.8**. A lock is only trustworthy from the toolchain that will consume it.
- **The PATH hazard bit again mid-fix** — an `export PATH=…` put the portable Node first and the shell
  still resolved `node` to the laragon **v18.8.0**. Absolute paths to `node.exe` and `npm-cli.js` were
  the only reliable way to pick a runtime on this machine. One more argument for retiring the extra
  installs rather than layering another.
- **`pdfVendor` "imports through the alias" was a broken gate, not a flake.** It reliably hit 5024 ms
  against vitest's 5 s default under full-suite load — it pays the entire transform cost of a ~20k-line
  vendored library on first import. Alone it takes ~800 ms. Budget raised to 20 s with the reasoning
  recorded, since the assertion is "the alias resolves", not "a cold transform is fast".
- **Unverified here, deliberately stated:** the desktop/mobile build. A Capacitor major breaks
  packaging far more often than it breaks the web bundle, and that job runs in CI.

## v0.3.751 — off end-of-life Node, onto the LTS that lasts

- **Both Nodes this repo targeted are end-of-life.** Confirmed against `nodejs/Release/schedule.json`
  rather than recollection: **v20 died 2026-04-30**, v18 in 2025. Every container was building on an
  unsupported runtime receiving no security patches.
- **Node 24, not the 22 that PR #69 proposed.** v22 entered *maintenance* in Oct 2025 with 276 days
  left; **v24 is in active LTS to 2028-04-30 — 642 days**. The branch was written before v24 went
  LTS. Taking 22 would have meant repeating this inside a year. `@capacitor/cli` wants
  `node >=22.0.0` — a floor, not a ceiling, so 24 satisfies it.
- `engines` → `>=24`, all three Dockerfiles → `node:24-slim`, **Postgres 16 → 17**, and `nginx:alpine`
  → `1.31-alpine` (a mutable tag is not a pin).
- **The migration drift-guard was still on `postgres:16`.** CI would have verified migrations against
  a different major than production runs — and this repo has already been burned once by that
  workflow silently not proving what it claimed. Now 17 on both sides.
- Deliberately **not** in this release: `FRAGMENTS_VERSION 3.4.5 → 3.4.6` (fragments is version-coupled
  to `@thatopen/components`; that pair moves on its own so a geometry regression is not competing with
  Node, Postgres and nginx for blame) and **Capacitor 7 → 8**, which needs a regenerated lock from
  `lockfile.yml` — never resolved on a dev box.
- Verified on the local Node 20: 599 tests, lint and typecheck clean. `engine-strict` is unset, so the
  raised floor warns rather than blocks until the runtime is installed.

## v0.3.750 — Pulse is wired, and a test says so

- v0.3.748/749 built the pulse and its renderer, and **nothing imported either**. That is this
  repo's most expensive recurring defect — seven engines once shipped with no route, every gate
  measuring the engine and none measuring the path to it. `portal.ts` now calls it on the home panel,
  and a test asserts both the import and the call site so it cannot regress to an orphan.
- **Sources are fetched independently and it degrades on purpose.** A project with no proforma still
  has a schedule; one rejection must not blank the rail. Missing engine, renamed field or slow call
  costs a card, never the page — `renderPulse` is fire-and-forget and swallows its own failures,
  because a summary that can break the page it summarises is worse than no summary.
- Guards against re-entrancy: the home panel can re-render while the fetch is in flight, so the rail
  is only inserted if its root is still `isConnected` — otherwise you get an invisible rail now and a
  duplicate on the next pass.

## v0.3.749 — Pulse renders, and the renderer keeps the logic's promises

- `pulseCardEl` / `pulseRailEl`, kept **beside** the logic on purpose. "A card may say nothing" is
  only true if the renderer also declines to draw an empty line; split the two and a `null` risk
  becomes a blank row that reads as a loading state.
- `pulseRailEl([])` returns **null**, so a caller omits the column entirely rather than showing a
  panel captioned "PROJECT PULSE" with nothing under it.
- Risk strings are server-derived free text and go through `esc()` — asserted, since this repo has a
  standing `js/xss-through-dom` lesson about exactly that.
- Tone reaches the DOM as a class so colour is decided once, in the logic, not again in CSS.

## v0.3.748 — PROJECT PULSE + NEXT BEST ACTION, the two halves that never got built

- The R26 work-queue design was the best shell this repo has had, and only half of it survived: the
  ball-in-court list lives on in `workQueue.ts`, while `PROJECT PULSE` and `NEXT BEST ACTION` had
  **zero occurrences anywhere in the codebase**. The list became one destination among ~130 modules,
  reached through the catalog it was explicitly meant to replace ("you never browse for work, work
  comes to you").
- **`portal/panels/pulse.ts`** — five cards, each a number with a sentence naming what is at risk.
  The number is not the point: "Cost −0.7%" is what a chart already tells you; "3 changes unpriced
  could take that to +1.4%" is what makes somebody act. Pure function, engines in / cards out; every
  input already exists (`modelHealth`, `costSummary`/`evm`, `scheduleVariance`, `workQueue`,
  `proformaLive`) so Pulse invents no number of its own and cannot become a sixth source of truth
  that disagrees with the five panels it summarises.
- **Cards with no data are omitted, never rendered as zero.** A project with no proforma has no deal
  position; "0.0%" would be a claim nobody made.
- **It is allowed to say nothing.** `risk: null` renders as nothing rather than reassuring filler —
  a panel that is always calming gets ignored within a week, and then the week it should have been
  alarming, nobody is reading it.
- **`nextBestAction` returns ONE item, never a ranked list** — a ranked list is just another queue to
  triage, which is the problem the work queue already solves.
- Mutation-checked: deleting the overdue item *names* while keeping the count turns 2 tests red.

## v0.3.747 — the ☰ button can explain itself

- A user looked at the top-left of the app and asked what the three lines do. That question *was* the
  bug: the control's whole explanation was `aria-label="Toggle panel"` — which names no panel, never
  changes (so after collapsing, a button that will now REVEAL the panel still read "Toggle panel"),
  and carried `(\)` as its shortcut because `\` in HTML is two literal backslashes.
- Now `Hide side panel` / `Show side panel`, describing the **next action**, with `aria-expanded` and
  `aria-controls` so the button and the panel can be **asserted to agree** rather than eyeballed.
  Without a machine-readable state, "the label is right" is an opinion.

## v0.3.746 — a `.mass` now carries the element index

- **Every container exported before this held a model you could SEE and could not QUERY.** It
  packed `geometry/model.frag` and every project table, and omitted `props.json` — the element
  index. Import one and there is no model browser, no element list, no takeoff, no element-scoped
  cost or 4D, because all of those read `_INDEX`, which is a cache over that one object. Containers
  now carry `index/props.json` and restore it under the new project id.
- **Real effect, measured through the actual export**: Verification House **0 → 7 elements**,
  Maple Street House **0 → 8**. Seven is exactly what the live authoring test built.
- **Why two exhaustive inventories both missed it.** `_project_tables()` finds tables by their
  `project_id` column; `_attachment_keys()` finds blobs by their owning record. props.json is
  neither, so each rule was complete *by its own definition* and the union still had a hole. Two
  exhaustive-looking rules with a gap between them look exactly like coverage — and the manifest's
  `entries` list inventoried everything present, because an inventory can only enumerate what it was
  handed.
- The new test asserts the **capability** (can this project be queried after a round trip), not the
  file list — including that GlobalIds survive the copy unchanged, since a re-keyed GUID silently
  orphans every pin, RFI, cost line and 4D task pointing at it. A test checking "manifest lists N
  entries" would have passed throughout.
- Investigated but deliberately **not** built: a persisted `element` table. `ensure_loaded` already
  rehydrates from object storage, so props.json *is* the durable index and the dict is a cache. A
  table would have duplicated the source of truth to fix a packaging gap.

## v0.3.745 — resolve the three CodeQL alerts: one real, two false

- **`py/path-injection` in `samples.py` was mine, from yesterday's release, and it was right.** The
  docstring said the id "is never joined onto a root"; the code checked membership and then did
  `open(os.path.join(samples_dir(), sample_id))`. Safe in practice — the check means the id must
  equal a real listing entry — but the code contradicted its own stated design, and the scanner
  cannot see a guard several lines away any more than the next person to edit it can. `read()` now
  selects the path the filesystem produced. There is no longer a check that could be relaxed.
- **A shape test, mutation-checked.** Every behavioural test passed against the flawed version,
  because the membership check really did make it safe — so behaviour was the wrong thing to assert.
  `test_samples` now parses `read()` with `ast` and fails if a join reappears. Its own first draft
  read the *docstring*, which mentions `os.path.join` while explaining the history: a shape test that
  greps prose measures prose.
- **The two vendored `js/xss-through-dom` HIGHs are false positives**, dismissed with reasons.
  `img.src` is `URL.createObjectURL(file)`, which returns a `blob:` URL by construction;
  `parseFromString(xml, "application/xml")` executes nothing and `fromXfdf` returns plain data. The
  sink side was checked rather than assumed — all 24 `innerHTML` uses in the library are clears or
  static literals, none interpolate.
- Upstream `massing-pdf#10`, which I had filed calling them real, is **withdrawn and closed** with
  the analysis.

## v0.3.744 — the sample library: showcase projects, not bare meshes

- **`GET /samples` + `POST /samples/{id}/open`, backed by `samples/`.** "Load a sample" meant one of
  three `.frag` files: geometry, and nothing else. You could orbit the model and that was the whole
  demonstration — no estimate, no schedule, no RFIs, no drawings. Every number the product exists to
  produce was missing from the thing meant to show it off. A sample is now a **`.mass` container**,
  so it opens as a project.
- **Nothing new was invented.** A sample opens through `bundle.import_bundle`, the identical path a
  user's own `.mass` takes; a demo on its own private code path eventually demonstrates behaviour the
  product does not have. And the catalog describes each container **from its own manifest** rather
  than a hand-kept catalog file — a catalog beside the artifacts is a promise, the manifest is a
  measurement.
- **Ids resolve by enumeration, never by joining.** `read()` selects from the directory listing, so a
  traversal id is simply absent rather than validated-against; there is no path to escape because no
  path is built from input. Asserted at both layers, including over HTTP.
- **Branch protection on `main`**: force-push and deletion blocked, no review requirement — version
  numbered direct pushes keep working, published history cannot be rewritten.

## v0.3.743 — SCALE-SEAM ①: the client starts splitting, provably

- **`api/surface.test.ts` first, extraction second.** The split is only safe if "I moved code" can be
  told apart from "I changed behaviour", and a typecheck cannot do that — deleting a method and
  deleting its last caller both compile clean. So the runtime method surface is captured and
  asserted. Writing it first paid immediately: it caught three method names I had guessed wrong
  (`createRecord`/`updateRecord`/`topics` are really `createModuleRecord`/`updateModuleRecord`/
  `topicsBoard`) and surfaced an ordering constraint — the SSE methods call a `private` `liveStream`,
  which a sibling mixin cannot reach, so they cannot move until it drops into `HttpCore`.
- **`api/authoring.ts` — 15 methods, 113 lines, out of `client.ts`.** IFC edit recipes, the family
  shelf, the compute graph, the massing generator. A **mixin**, so `api.editIfc(...)` resolves
  exactly as before and no call site in the app changed. Chosen as the first cut precisely because it
  reaches nothing but `HttpCore`'s `json`/`url`/`authHeaders`.
- **The first floor I wrote was 620 against a real surface of 689** — it would have sat green through
  losing every method the extraction moved. Corrected to 685. A threshold far below the truth is a
  test that cannot fail, which is the defect this suite keeps finding in its own tests.

## v0.3.742 — a size budget on the files we edit most

- **`test_file_sizes` — a ratchet, not a rule.** Measures every hand-written tracked source file and
  fails over a ceiling. Generated and vendored files are exempt **by name** (`schema.d.ts`, alembic
  `versions/`, `src/vendor/`) — exempting by size is how a budget dies.
- The ceiling is set deliberately **above** today's worst file. A guard that ships red is a guard
  everyone learns to ignore; this one holds the line while SCALE-SEAM brings the number down, and
  lowering it is part of that work. Every run prints the top eight with their headroom, so a file
  approaching the limit is visible before it blocks somebody mid-sprint.
- **CLAUDE.md said `node v20.3.1 — OK`. The `node` on this machine's PATH is v18.8.0, and v18 breaks
  the web build.** It was describing the Node you get *after* fixing the PATH. Corrected, along with
  the run-the-suite-from-`services/api` rule, and a short "verify, don't recall" section: if a rule
  matters, write it as a test, because anything held only as prose drifts — including the prose in
  that file.

## v0.3.741 — drawing review starts using the new engine

Opening a PDF and moving between its pages now goes through the drawing-review engine brought in last
release. Marking up and measuring are unchanged and move across later.

Two things get better immediately. Pages are remembered rather than re-read: this screen asked for the
same page again on every redraw, and once more for every page when exporting. And the awkward business
of copying the file's bytes before handing them over — needed because the reader can take ownership of
them and leave the export with nothing — is now handled properly inside the engine instead of guarded
by hand here.

The worker that does the reading is still bundled with the application rather than fetched from the
internet, and there is now a check that fails the build if that ever changes. Offline has to keep
working on a site with no signal, which is exactly where nobody can debug it.

## v0.3.740 — the drawing-review engine is in the building

The engine behind PDF drawing review — viewing, markup, calibrated takeoff, issue pinning, revision
compare — now lives in this repository and is wired in. Nothing has changed about how takeoff works
today; this is the groundwork under it.

It treats a markup as a **record** rather than as ink: who drew it, against which sheet revision, in
which discipline, what it measures, which spec clause it cites, which object in the model it refers
to, and where it stands in review. What you see on the sheet is one view of that record. The same
record is also what gets exported, handed to another tool, or counted in a quantity.

**Nothing has been replaced yet, deliberately.** Bringing in twelve thousand lines and re-pointing
the interface at them in one move would mean that if drawing review broke, there would be no way to
tell which half did it. The existing takeoff still runs the flow; moving to the new engine is a
separate, checkable step.

It brings no new third-party code with it — everything it needs was already here — and it adds
nothing to what the browser downloads on startup.

## v0.3.739 — opening a project takes you to the project

Opening a project now puts you where your job starts. A superintendent lands in Construction, an
architect in Design, a developer in theirs — each looking at the five rooms that organise the work:
Model, Cost, Schedule, Deal, Work.

That layout has been the default for a while and has been drawing correctly the whole time. What it
lacked was a way of being found: you only arrived at it by knowing to pick one of three particular
workspaces, and nothing said so. Every role already declared where its home was; nothing was reading
it. Now it does.

And from anywhere that is not the project home — the modelling canvas, the drawing sheets — there is
a plain **← Project home** in the tab strip. It is a link, not a redirect: someone drawing a wall is
in the right place and should not be moved out of it. It disappears in the workspaces where the rooms
are already on screen, and when no project is open there is nothing to go back to, so it stays away.

An explicit choice still wins. Pick a workspace and it is remembered — unless your role cannot reach
it, in which case you land at your own home rather than on a blank screen.

## v0.3.738 — the model knows where on earth it is

A model can now say where it actually stands: coordinates, the reference system they are given in,
the height datum, and how far project north is from true north. Ask a project and it answers.

It also says **how it knows**, which matters more than it sounds. A proper survey transform and a
rough site coordinate are both "the location", and they are not interchangeable — one is good enough
to set out a building from, the other is good enough to put a pin on a map. Reading them as the same
number is how a building ends up in the wrong place on site. And a model with no location at all says
so, rather than answering with zero — which is a real spot in the Atlantic.

Writing coordinates back round-trips exactly. That is less obvious than it sounds: the format stores
an angle as degrees, minutes, seconds and millionths of a second, and for a place just west of
Greenwich the degrees and minutes are both zero — the entire "west" lives in the seconds. Reading the
direction from the degrees alone, which is the obvious way, puts the Royal Observatory on the wrong
side of its own meridian.

## v0.3.737 — a test that only worked on one operating system

The checks covering the shared geometry cache included one that deliberately points it at an
unusable location, to confirm that a cache which cannot be opened is quietly skipped rather than
stopping a drawing being made.

The location chosen for that check was rejected by Linux before the test could even begin, so on the
build servers it did not check anything — it simply stopped. On Windows, where it was written, it ran
fine. The check now uses a location that is unusable in the same way everywhere, and it fails for the
reason it was written to test.

No change to how the product behaves.

## v0.3.736 — prepared geometry can be shared between server processes

A busy server runs several copies of itself. Each kept its own prepared geometry, so opening the same
model on a second copy did the slowest work in the system all over again — and a third, and a fourth.

They can now share. Point the server at a directory and the first copy to prepare a model writes the
result where the others can find it; they read it instead of repeating the work. Nothing is shared
between different files: the identity used is the one that already distinguishes a file from a
re-published version of itself, so a changed model is never mistaken for the old one.

**Off unless a directory is chosen.** A cache that quietly starts writing gigabytes somewhere nobody
picked is not a feature, and on a single-copy install there is nothing to share anyway. When it is
enabled it can be inspected — how many models, how much disk, what limit — because a cache nobody can
measure is a cache nobody can size.

What is stored is the plain geometry, not the internal objects of the library that builds it. If that
library changes shape in a future version, a stored entry is either read back exactly as it was
written or ignored — never turned into something subtly different.

If the directory cannot be written, or an entry cannot be read back, the drawing is simply prepared
the old way. Sharing is a saving, and losing it is never a failure.

## v0.3.735 — a single drawing gets the whole machine again

Yesterday's change to share the machine between simultaneous drawings went too far in the other
direction: it divided the machine by how many drawings were *allowed* to run at once rather than how
many actually were, so one person waiting on one drawing got a fraction of the computer for no reason.
A lone drawing now uses the machine as it always did, and the sharing only kicks in when there is
something to share with.

Three other faults in the same work, none of which would have announced themselves:

A cached calculation of the model's overall size was being looked up under an old name and could never
be found, so it was recomputed from scratch every time — and, since yesterday, took a turn in the
queue to do it.

Cleaning up after a finished drawing could be handled by a background housekeeping thread rather than
the one that started it, and the bookkeeping was written against whichever thread happened to do the
cleaning. That left the original worker permanently marked as busy — quietly opting itself out of the
sharing, for good.

And on machines with two or three processors the limit still worked out to one drawing at a time,
which is the exact state the code was written to avoid.

Two of the checks covering this could not fail — one compared a value against itself, another was
skipped entirely by the test settings. Both now run and were confirmed to catch the old behaviour.

## v0.3.734 — the server shares itself out between simultaneous drawings

Preparing a model's geometry is the heaviest thing this server does, and until now each request took
as much of the machine as it could get. Two people asking for drawings at the same moment did not get
half each — they got a fight, and both waited longer than either would have alone.

The work is now shared out: a few drawings prepare at once, each with a fair portion of the machine,
and the rest queue briefly rather than piling on. A drawing that cannot get a turn still goes ahead
rather than leaving anybody waiting indefinitely; the limit exists to stop a pile-up, not to decide
whether somebody gets their sheet.

Two scans that read only part of a model — the survey-deviation check and the egress route trace —
deliberately keep reading it in a fixed order. Both stop early once they have enough, so the order
decides which parts they looked at; letting that vary would mean the same question returned a
different answer each time it was asked.

The first version of this change was reviewed before release and was wrong in a way that mattered: it
would have let only one drawing prepare at a time on any normal machine, making every other request
wait for nothing. Four further faults were found in the same pass. All five are fixed, and the checks
that now cover them were confirmed to fail against the old behaviour rather than merely passing
against the new.

## v0.3.733 — the sample project's figures are rebuilt on the corrected measurements

The demo dataset was captured on 23 July, before the measurement fix in v0.3.727, so some of the
quantities it showed were the old inflated ones. It has been recaptured.

The change is smaller and more specific than expected, which is worth saying plainly rather than
rounding up. Only the items whose quantities are worked out from the shape were ever wrong: the
ceiling and floor finishes drop from 506 m² to 252 m², which is the doubling being undone. The slabs
do not move at all, because the sample model states its own slab quantities and those were always
read directly. The project total goes from $837,344 to $823,383.

That distinction is the whole shape of the original fix: it only ever affected drawings that carry no
stated quantities. Everything else was, and stays, correct.

## v0.3.732 — groundwork for keeping the server responsive under load

Preparing a model's geometry is the heaviest thing this server does, and each pass already spreads
itself across most of the machine's cores. That is right when one person is waiting for one drawing.
It is wrong when eight requests arrive together, because each one asks for the whole machine and they
end up fighting rather than finishing.

This release adds the piece that limits how many of those passes run at the same time, along with the
tests that prove it behaves under contention — including that a nested pass cannot lock up, and that a
pass which cannot get a turn goes ahead anyway rather than leaving somebody waiting indefinitely. The
limit is there to stop a pile-up, not to decide whether a drawing gets made.

**It is not yet connected to the thirteen places that prepare geometry**, and that is deliberate. Each
of those reads its results differently, so connecting them is a change with real care required rather
than a search and replace. Connecting some but not all would be the worst outcome: it would look like
the server was protected while most of the load was still unlimited. Behaviour is unchanged in this
release; the groundwork is in place and tested.

## v0.3.731 — the geometry cache is limited by size, and desktop installers publish again

Two unrelated things, both cases of a number that was not measuring what it appeared to.

**The cache kept four models.** Four of anything is not an amount of memory: four houses are a few
megabytes and four towers are several gigabytes, and the limit said "four" either way. It now works to
a size — a gigabyte by default, adjustable — and drops the least recently used until it fits. A model
larger than the whole budget is still kept rather than thrown away the moment it is prepared, because
discarding it would mean rebuilding it for every single view; a cache that costs more than it saves is
worse than none.

**Desktop installers have not actually been published since v0.3.576.** Every release built them and
attached them to a draft, and the final step that makes the draft public was looking the release up in
a way that cannot see drafts. It failed — but only ever ran when everything before it had succeeded,
and a step that is skipped does not turn a build red. So the build reported success for months while
the installers sat unpublished. The step now refers to the release directly, and refuses loudly if it
has nothing to publish rather than passing quietly.

## v0.3.730 — the element list can tell you when it is out of date

Draw a wall and the model has it immediately. The searchable list of elements behind it — the one the
model browser and the property panels read — is a snapshot, and it is rebuilt when you publish, not on
every edit. Rebuilding means re-processing the geometry, which is far too slow to do while you work.

That was always true. What was missing is that the list had no way to mention it. A list built ten
edits ago and a list built a second ago looked exactly alike, so a browser could show a fraction of
what you had just drawn and look entirely correct doing it.

It can now be asked, and it answers with one of three things: up to date, behind the model, or **not
sure**. The third is the one that matters. A list built before this release genuinely does not know
whether it is current, and saying "up to date" in that case would be a guess presented as a fact —
which is the whole failure being fixed, in a new place.

Nothing rebuilds automatically. Reading a list should not silently start minutes of geometry work.
When it is behind, it says so, and republishing brings it level.

## v0.3.729 — an issue means the same thing wherever you raised it

Raise an RFI in the register, tie it to a wall, and it now appears on the model and on the drawing —
while still being the same record that carries the question, the answer and the workflow through to
closed.

Until now those were two different things that happened to share a name. One kind of issue could be
placed on the model and seen; the other kind could be answered and closed. Tying a register RFI to a
wall reported success and produced nothing you could look at. You could track an issue to completion
or you could see where it was, and choosing one meant giving up the other.

A pin is now simply any issue that is attached to something — however it was created. Its position
comes from the element it refers to rather than being written down beside it, so moving a wall moves
its pins with it instead of leaving them pointing at empty air.

Not every register belongs on a drawing. An RFI, a punch item, an observation are about a place you
can stand; a change order or a submittal is about the project as a whole. Only the ones that mean
"look here" are drawn.

Where a position cannot be worked out — no model loaded, or an element that will not build — the
issue is still listed and counted as unlocated rather than quietly left out, so the number you see
and the number that exists never disagree.

## v0.3.728 — the issue you raised now appears on the drawing

Pin an RFI to a wall and it shows up on the plan: a numbered balloon at the place in the building it
actually refers to, coloured by what kind of issue it is, labelled, and listed in order so the sheet
can be read against an issue log.

Until now it did not. Asking a plan for its pins was accepted and answered with a sheet that had no
pins on it — the request looked fine, the drawing looked finished, and the thing you had flagged was
simply absent. A drawing that quietly leaves out the open question is worse than one that never
offered to show it.

Two things it refuses to do. A pin that falls outside the drawn area is still drawn, pulled to the
edge and marked, rather than dropped — an issue nobody can see is an issue nobody closes. And a pin
with no usable position is not placed somewhere plausible; the sheet says how many it could not
locate, so the count you see and the count that exists always agree.

Pins are filtered to the storey being drawn, so a tall building does not print every issue in the
project onto the ground floor. Ask for a plan without pins and you get exactly what you got before.

## v0.3.727 — a roof is priced by the roof, not by both sides of it

A model-based estimate was measuring the wrong thing. Where a drawing carries no stated quantities,
the takeoff works them out from the shape — and it was taking the **whole outer skin** of each
element. For a roof that is the top, the underside and the edge all added together. For a wall it is
both faces plus the ends.

Priced by the square metre, that roughly doubled every area line. Authoring a 12 x 8 m house and
checking by hand: the roof was measured at 202 m², and it is a 96 m² roof; the four walls came to
236 m² where the face you would paint is 108. The estimate read $112,901. It should have read
$70,110. Nothing looked broken — the numbers were simply about twice what the building is.

Each element is now measured the way somebody pricing the work would measure it. Roofs, slabs,
coverings and footings by the area you could walk on. Walls, doors, windows and panels by the face
you see in elevation — one face, no edges. Ducts and pipes keep their full surface, because for
those the skin genuinely is the quantity.

This affected drawings that carry no quantities of their own, which is exactly the drawings this
application creates. Files from other tools usually state their own quantities and were always
priced from those. If you have an estimate from a model you built here, it was high; re-running it
will now be lower, and right.

## v0.3.726 — more lists appear at once; the ones that must not be cached, are not

The journal-batch register, the concept-render grid and the capital-plan table now show their last
known contents immediately and refresh behind you, each saying how old what you are looking at is.

The more consequential half of this change is the four places that were left alone. A cached list is
safe when a person reads it and can see it is a few minutes old. It is not safe when a *control*
consumes it: the reference dropdown on a form you are about to submit could offer something already
deleted, and the bid-package picker sits directly in front of sending real invitations to real
companies. One screen reads its records and then creates a new one if the list looks empty — served
a stale list, it would quietly make a duplicate. Another shows records beside a live figure in the
same card, where caching one and not the other would put a current number next to an old one with
nothing to distinguish them.

So the rule is now written down where the code is: show-and-tell is for reading. Anything that
writes, sends, or decides asks the server.

## v0.3.725 — your queued field work is yours, and stays yours

The app holds two queues of work that has not reached the server yet: photos and observations
captured in the field, and files attached while offline. Both flush automatically when a connection
comes back.

Until now neither knew who created it. On a tablet shared between trades, the next person to sign in
saw the previous person's pending captures and uploads — and flushing them filed that work under the
wrong name. Wrong attribution on a punchlist item or a safety observation is a worse outcome than
merely seeing it.

Each queued item now records who created it, and you only see your own. Someone else's pending work
is hidden from you, **not deleted** — it is still on the device, waiting for them to sign back in.
That distinction is the entire design: this is unsent work, and losing a jobsite photo that exists
nowhere else would be far worse than the problem being fixed. Clearing your own queue leaves everyone
else's untouched.

Items already queued before this update stay visible, because there is no way to know whose they are
and stranding them would be its own kind of loss. They are never re-labelled with someone else's
name, and the unlabelled set empties as those queues flush.

## v0.3.724 — signing out now clears what was cached, and no two people share a cache

Yesterday's release started keeping record lists on the device so they appear instantly. That was the
first time this product stored project data locally, and it needed one more thing that was missing:
signing out did not erase it.

On a shared machine — the tablet in a site trailer, passed between trades — the next person to sign in
could be shown the previous person's lists, labelled as merely a few minutes old, before any request
reached the server to check whether they were allowed to see them.

Two changes, and both matter. Signing out now clears the stored lists. And each cached entry is tagged
with the session that wrote it, so even if that clearing is prevented — a locked-down browser, a crash,
another tab holding the database — one person's data still cannot be read under someone else's sign-in.
The second is what makes the first safe to fail.

Clearing never blocks signing out. Stopping being signed in is the one thing that has to work even when
everything else does not.

## v0.3.723 — lists that appear at once, and admit when they are from a moment ago

Record lists now show what was there last time immediately, and refresh behind you. Opening a
register on a site connection no longer means watching a spinner decide whether today is going to be
frustrating.

**A cached list says that it is cached.** It carries how old it is, and the panel shows it — "cached
3 min ago, refreshing…" — rather than presenting yesterday's answer with the confidence of this
morning's. Serving something slightly old is fine and useful; serving it *silently* is the thing this
codebase has spent a whole cycle learning to refuse, because a number that looks current and is not
is worse than no number.

The refresh only redraws when the answer actually changed, so a list that is still correct does not
flicker. If the network is down, the stored copy is served with its true age instead of an empty
screen. If the browser will not allow local storage at all, everything works exactly as before —
caching is a convenience, and losing it is never treated as a failure.

Records were the largest thing we were re-fetching constantly: over a hundred registers, per project,
with their history. Downloaded geometry and program code were already kept properly; this closes the
half that was not.

## v0.3.722 — sign in with Autodesk, clear your cached data, and geometry that knows which file it came from

**Sign in with Autodesk.** Google, Microsoft and Procore already worked; the missing one was the
account most people in this industry already have — the identity behind Revit, ACC and BIM 360. The
button appears as soon as the credentials are configured, and signing in this way puts you in exactly
the same account and permission model as anyone who used a password.

It asks for your identity and nothing else. Reading a project out of your Autodesk account is a
separate permission with a separate consent screen, and asking for it behind a button that says "sign
in" would be asking for far more than the button admits to. The optional Revit conversion bridge is
unchanged and still authorised on its own.

**Clear cached data, from Settings.** This app deliberately holds on to downloaded geometry, engine
code and pages, because they never change once published. That is worth doing and it is exactly why
there has to be a way out — otherwise one bad download becomes "clear your browser data", which nobody
should be told to do to a working application.

It keeps your sign-in, your chosen layout and your saved preferences. Those are not cache, they are
choices, and a button that quietly destroys them is one people learn to fear — which makes it useless
at the moment they actually need it. It also reports what it removed as counts rather than a
reassurance, names anything it could not clear, and will not hang if another tab is holding data open.

**Cached geometry now knows which file it came from.** It was previously remembered by a location in
memory, which works inside one process and means nothing outside it — and needed a guard to stop that
location being reused. It is now identified by the file itself, so republishing a model can never
serve the previous revision, and the expensive part of drawing a model becomes shareable between
processes rather than being recomputed by each one.

## v0.3.721 — a rate limit that cannot quietly be a fraction of itself

**Fixed — a request limit could silently be several times what you configured.** Running more than one
worker without a shared counter means each worker counts separately, so a limit of sixty requests a
minute across four workers is really two hundred and forty. The code detected this exactly, wrote the
most severe message it has, and then started anyway.

That is worse than having no limit. A missing control is a known gap; one that announces it is broken
and runs leaves you believing you are protected. A production deployment in that state now refuses to
start and says how to fix it — point it at a shared counter, or run a single worker.

It required no new machinery: the startup check already gathered configuration problems, refused once
listing all of them, and offered an explicit override for deliberately-open internal deployments. This
joins that list, so it inherits the override and the production-only scope. A developer's machine is
untouched, and still just warns — requiring everyone to run extra infrastructure to use two workers
locally would be a rule people work around, and a rule people work around protects nothing.

**Also researched, not yet built: how this platform should cache.** The finding is that our model and
geometry caches limit how *many* things they hold rather than how much memory those things occupy —
which for building models ranging from a few megabytes to a couple of gigabytes means the configured
number cannot be planned against. Written up with recommendations, including why reserving memory up
front is the wrong shape and a ceiling that evicts is the right one.

## v0.3.720 — a spread that adds up, and nothing copyleft in the box

**Fixed — spreading a total across periods did not add up.** A budget spread over months, and a
resource histogram over weeks, both divided the total and rounded each bucket, so the periods never
quite summed to the figure they were spread from. That is the discrepancy somebody finds while
reconciling, and it has no explanation because there is nothing wrong with any individual number. Both
now use the penny-exact allocator, and the engines are asserted to call it rather than merely to have
it available.

**The GPL-licensed package we never execute is now excluded from what we ship.** It arrives as a
required component of a permissively-licensed library we genuinely need, but the half of that library
we use never loads it, which is verified by blocking it at import and confirming our validation path
still works. It stays installed so the library's requirements resolve, and is left out of both the
desktop builds and the container image.

**That exclusion is declared once and read everywhere.** The name, the reason, and what each packager
needs live in a single place; the desktop builds and the image both derive from it. Hard-coding the
remedy in each build file would have solved exactly one package and left the next one to be noticed by
nobody. The licence check now also *enforces* the list — finding a copyleft dependency and forgetting
to act on it fails the build, instead of being recorded somewhere nobody re-reads.

**Fixed — a licence classifier that was wrong about dual licensing.** A package offering "Apache or
GPL or LGPL" was being classified as copyleft, which would have had us excluding a dependency we are
entitled to use under Apache. Where a choice is offered we take the permissive option — while a
package whose only free option is copyleft is still refused, since a commercial alternative is not
permission. Correct in both directions, which the simpler rule was not.

## v0.3.719 — the licence rule is enforced by the build, and the new navigation is proven complete

**The "no GPL/AGPL" rule now fails a build instead of relying on someone remembering.** The classifier
and the audit had been sitting in the codebase with their own tests and nothing calling them — the
same shape as the money helpers fixed last release: a mechanism written to enforce something,
enforcing nothing. It is wired to the test suite now, and a dependency that arrives under a
disallowed licence fails on the change that introduces it, naming the package.

Building it produced one finding worth acting on. A GPL-licensed package ships in our dependency tree,
arriving as a required component of a permissively-licensed library we do use — which is exactly why
a check against the names in our own dependency file would have missed it, and did. **We do not need
it:** the library we depend on is itself permissively licensed, we use only its validation half, and
that half never loads the GPL component; our own handling of that file format is our own code. The
remaining step is to leave it out of the packaged builds, which is a packaging change rather than a
code one. Two guards hold the code side meanwhile.

**The redesigned navigation is proven to have lost nothing.** With the five rooms now the default, a
destination reachable in the old layout and in no room would be a feature that silently left the
product. All 46 are placed, no workspace loses anything, every workspace now reaches the entire
catalogue rather than its own slice, and no room is an empty heading. Written up in a document you can
read against your own memory of the old layout, and held by a test proven to fail when a destination
is orphaned.

Two observations came out of it, both about shape rather than loss: the room most people land in is
the thinnest, and two entries sit in a room that is arguable. Neither is worth changing on instinct —
they want real usage data, and they are recorded rather than acted on.

## v0.3.718 — the new rail no longer disappears when a request fails, and a split total adds up

**Fixed — the redesigned navigation silently reverted to the old one.** Its room layout is fetched
from the server; when that request failed, the whole rail quietly rebuilt itself in the previous
style. That was a reasonable trade while the new look was something you opted into and a handful of
people had. Once it became the default three releases ago it meant anyone with a flaky connection —
or working offline, which this product promises to support — was handed the old shell with no
explanation, and from the outside that is indistinguishable from the redesign never having shipped.

The five rooms are a fixed set both halves of the product already agree on, so only the **badges**
depend on that request. They now degrade instead of the shell: the rail renders, the counts are
absent rather than invented, and the answer records which of the two it is. A count nobody measured
would say "nothing is in your court", which is a claim, and not one that can be supported.

This was found by looking at the running application. The previous release had verified the setting
that controls the rail — including in the shipped bundle — and stopped there, which established that
the switch was flipped and never that anything appeared.

**Fixed — money split between parties did not add up, and the shortfall always landed on the same
person.** Splitting $100 three ways by rounding each share gives three lots of $33.33 and loses a
penny. The code compensated by putting the leftover on the last row, which balanced the total but
meant whoever happened to sort last absorbed every spare cent, on every capital call and every
distribution. Small, systematic, arbitrary — and exactly the kind of thing an investor finds in a
reconciliation that nobody can explain. Leftovers are now distributed by the standard method, to the
shares with the largest fractional parts.

The decimal-precise helpers that make this correct had been sitting in the codebase with their own
tests and **nothing calling them** — found by the reachability check added two releases ago, which
now refuses to let that entry linger once it is fixed.

## v0.3.717 — pins that fail to load no longer take the rest of the panel with them

Markup now runs as an isolated capability on the adopted kernel, and it was chosen for that over
tidier candidates because of a real defect: loading pins was awaited without a guard while the
project panels were being built. One unreachable request, one malformed record, and the failure
escaped pin loading and abandoned everything queued behind it — with nothing on screen to say why.
The visible result was a panel that came up half-built, which reads as a rendering bug rather than as
a network error, so the symptom pointed away from the cause.

Failure is now a reported outcome rather than an escape. You get told the pins did not load, and
everything else still runs.

**A count is carried through rather than discarded.** An overlay with no pins on it looks exactly the
same whether the project genuinely has none or the request quietly returned nothing, and only one of
those is worth anybody's attention — so the number placed is now part of the answer.

**What was deliberately not done:** the pin overlay itself is untouched. It keeps its behaviour, its
markers and its tests. The new layer owns only *when it runs and what happens when it fails*, which
is what adopting an architecture over working code is supposed to look like — the alternative,
rewriting a working feature to prove a point about structure, is how you lose the parts that were
already right.

## v0.3.716 — the known gaps in the adopted kernel are closed, upstream

Adopting the platform kernel four releases ago surfaced four defects, each recorded here at the time
as something we were carrying rather than something we had fixed. All four are now fixed **in the
kernel itself** and this build carries them, so the two local modifications this repository was
holding are gone and a future refresh is once again a plain copy.

**A takeoff rule naming certain words produced a silent wrong number.** Because quantities were
looked up on a plain object, a rule referring to a handful of reserved property names resolved to
something that was not a quantity at all, slipped past the check meant to catch unknown names, and
evaluated to a non-number that then flowed onward into the bill of quantities, the estimate and the
cashflow — surfacing far from the rule that caused it. That check exists precisely to refuse an
unknown quantity rather than treat it as zero, on the grounds that zero is a confident wrong
measurement; a non-number is worse.

**A project file written here would not open there.** The kernel's container reader still expected
the file extension this product replaced several releases ago. It now treats the current extension as
native and keeps reading the old one.

**An identifier that was weak but looked strong.** The kernel's id generator fell back to
non-cryptographic randomness on hosts lacking the modern API. It now refuses rather than quietly
returning something predictable.

**And the viewer libraries are pinned exactly**, because the two must be installed as a matching pair
and a range cannot express that — a fresh install was free to pick a combination nobody had tested.

The mechanism that made this land cleanly is worth naming: the extension mismatch had been written
down not as a comment but as a **test asserting the broken state**, designed to fail the moment
somebody fixed it. It did, on the first refresh after the upstream change — so the gap announced its
own closure instead of quietly persisting in a list nobody re-reads.

## v0.3.715 — the new look is the front door

The five-room spine — Work, Model, Schedule, Deal, Docs — is now what you get by default. It has been
built and testable behind a flag since the R26 ring, deliberately beside the old shell rather than
instead of it, because replacing a working front door on the strength of a mock is how you lose the
parts that were already right. The ring is finished and the render audit passes against the spine
specifically, so the flag has served its purpose.

**The old shell is still one click away and the choice sticks.** `?shell=classic` returns you to the
lifecycle-stage rail and remembers. A redesign nobody can back out of has to be perfect on the first
try, and this one does not have to be.

**The detail that made the flip safe.** The stored preference used to be present-or-absent, which
made "never expressed a preference" and "deliberately chose the old shell" the same state. Inverting
the default on that would have quietly dragged the one group who had already said no into the new
shell. The preference is now explicitly on or off, so the two are distinguishable — anyone who opted
out stays out, and anyone who opted in sees no change.

The companion kernel repository is now public under MIT, which is what makes the architecture
adopted in v0.3.712 inspectable rather than a black box arriving by copy.

## v0.3.714 — an architectural claim that fails a build instead of ageing into fiction

Two codebases were being built in parallel against shared assumptions, and **every assumption written
down as prose had drifted** by the time anyone read the other's code: the project-file extension, the
format identifier, the pinned pair of viewer libraries. Nothing caught any of it, because prose is not
a gate. Parallel work did not create that drift — it only made it fast.

**A check that a module nobody can call is a module nobody can call.** Across the previous ten
releases, seven things shipped fully tested, CI-green and unreachable — no route, no tool, no caller.
From the outside that is indistinguishable from a working feature, which is why it survived so long:
every gate measures whether the code works, and none measured whether a request can arrive. That
check was a note; it is now part of the test suite. It walks the import graph from every route, tool
and entry point, and anything it cannot reach must be declared along with the reason. Declaring
something is not a way to hide it — a declared gap that later becomes reachable fails too, so the
list cannot quietly become a place where work is parked and forgotten.

It found two more on its first run. **Decimal-precise currency helpers, with their own test suite and
no callers at all** — so the rounding drift they exist to prevent is still present everywhere money
is actually computed. And a set of supply-chain hardening checks that nothing invokes, meaning
whatever they verify is not being verified.

**Fixed — a weak identifier that looked exactly like a strong one.** The adopted kernel's id
generator fell back to non-cryptographic randomness on hosts lacking the modern API, returning a
predictable value shaped identically to a secure one. Reachable only on exotic platforms, but the
contract was the problem: a general-purpose id generator cannot know whether a caller will use its
output as an internal key or as a share link. It now uses cryptographic randomness, and refuses
outright rather than quietly returning something weaker. Reported upstream.

## v0.3.713 — a selection that cannot find an element now says so

The first capability to sit on the newly adopted kernel, and deliberately the identity one: every
other capability that moves out of the viewer module will cross this boundary, and a line drawn wrong
once is drawn wrong everywhere above it.

**Fixed — selecting elements silently returned fewer than you asked for.** Resolving IFC GlobalIds to
the renderer's per-session handles discarded anything it could not find. Ask to select the ten
elements a rule flagged, or the elements behind a clash, and if three of them are not in a loaded
model you were shown seven with nothing said. The natural reading of a shorter selection is that the
model changed — not that the lookup quietly failed — so the error pointed away from itself. The
resolver now reports what it could not find, and the viewer says "7 of 10 selected — 3 GlobalIds not
in any loaded model".

Two related cases are now answered rather than guessed at. The same GlobalId present in two models of
a federated project is reported as **ambiguous** instead of resolving to whichever model happened to
be searched first — federation makes that normal, and a coin toss between two real elements is worse
than saying there are two. And geometry that can be drawn but carries no GlobalId — generated content
that was never in an IFC — is named rather than dropped, which is the difference between a clear
message and a pin that never comes back.

**Why this is the identity boundary.** A GlobalId is stable across re-issue and safe to store; the
renderer's handle is valid for one load of one model in one session and is renumbered when the same
file is converted again. Storing the wrong one looks correct for the rest of the session and only
surfaces after somebody re-issues a model, as every pin, clash and cost line pointing at the wrong
element. That rule now has one place to live, with a check that a reference is stripped of its
session handle before it can be persisted.

## v0.3.712 — the platform kernel arrives, vendored, with its disagreements written down

The kernel and plugin architecture developed alongside this product is now **in the build**. Three
packages — the kernel itself, the plugin SDK and the persisted-record contracts — are vendored under
`apps/web/src/vendor/massingifc` and compile, typecheck and test as part of the app. This is
adoption, not replacement: the viewer keeps working exactly as it did, and capabilities can move out
of the 4,528-line viewer module into isolated plugins one at a time, each behind a capability token.
Nothing has moved yet.

**Vendored rather than installed, deliberately.** The kernel lives in a private repository and this
one is public, so an install would need a credential in CI — which breaks forks and contradicts the
rule that the build stays offline and deterministic. All three packages have zero runtime
dependencies, no Node built-ins and no browser globals, so copying the source costs nothing and
keeps the build hermetic. The files are unmodified apart from one recorded line, the licence travels
with them, and the upstream commit is written down so a refresh is a copy rather than a merge.

**What the tests prove, beyond "it compiled".** A vendored library nobody exercises is a fork you
have not noticed yet, so upstream's own 152 tests now run here, and a further nine assert the seams:
the kernel boots in this environment; a plugin that throws on activation is quarantined instead of
taking the host down; an element re-converted to a different runtime handle is still recognised as
the same element, because identity is the IFC GlobalId and not the handle; and a capability that is
absent is reported differently from one that is present but incompatible.

**The disagreements are assertions, not notes.** The kernel's container adapter still expects the
project-file extension this product replaced in v0.3.705, so a project written today would not be
recognised by it. Rather than leave that to be rediscovered by somebody whose file will not open, a
test pins the mismatch and fails when it is fixed — at which point the fix is to delete the test.
Three issues are open upstream: that one, caret version ranges that cannot express the pinned viewer
pair this project requires, and a takeoff-expression evaluator that resolves inherited property
names and yields a silent `NaN` where it means to refuse.

## v0.3.711 — three engines that could not be called, and one that answered about the wrong sheet

**Sprint A-2 — reachability.** Sprint A wired four engines that had shipped fully tested and with
nothing that could reach them. Auditing for the rest found three more, one of them created during
Sprint A itself. All three are now reachable.

* **Dimensional constraints solve over HTTP.** `POST /projects/{pid}/constraints/solve`. The solver
  shipped complete two weeks of releases ago with no route and no tool, so it solved nothing in the
  interim. Required locks are satisfied and frozen before a weak preference may move what is left; an
  over-constrained system names the constraints that cannot hold rather than satisfying whichever was
  reached first; an under-constrained one reports its remaining degrees of freedom instead of picking
  one of infinitely many answers; and clearances are checked, never enforced, because sliding geometry
  to satisfy a code minimum would move something somebody placed on purpose. A malformed constraint is
  refused rather than dropped — a lock nobody applied is worse than an error, since the model then
  looks constrained and is not.
* **Sheet regions are readable.** `GET /projects/{pid}/drawings/sheet-regions` reports what occupies
  which rectangle on a sheet, in page points, with the exact page↔world affine. This is the producer
  for the `layout` that the 2D takeoff was taught to accept last release — the consumer had been wired
  and the producer had not, so that route was asking for something no caller could obtain. A takeoff
  scoped to a viewport now needs no calibration step: the regions carry the numbers the sheet was
  actually drawn with, not a recovery from rendered output.
* **The toolbar renders its icons.** The icon map has been complete and tested since v0.3.708 and the
  toolbar never read it, so "all 27 verbs mapped" was true and nothing on screen had changed. Buttons
  now carry the vendored line icon (ISC-licensed, bundled, no network), inheriting the button's colour
  so hover and disabled states cannot disagree with it. A tool with no icon keeps its original glyph
  and is tagged in the DOM, because half a bar of icons beside half a bar of emoji is readable whereas
  a blank square is a tool you cannot find.

**Fixed — a sheet layout could answer about a different sheet.** The viewport-preset lookup falls back
to the default arrangement for any name it does not recognise. That is right for a library and wrong
for an endpoint: a typo would have returned a *different* layout labelled as the one requested, and
every page coordinate derived from it would have been perfectly accurate about the wrong sheet. The
route now refuses an unknown preset outright, and refuses it before opening the model so the bad
preset reports itself rather than whatever the model open happened to complain about. Page size had
the identical fallback, and mattered more because the route echoes the requested page back in its
answer — an unknown size would have returned A1 geometry stamped with the name of a page it does not
fit. Both lists are asserted against the library's own, so they cannot drift apart in silence.

## v0.3.710 — how late are we, how wrong is the plan, and can anything reach the answer

Two questions a schedule could not previously answer, and one field it was missing to answer either.

**How wrong is the plan?** Schedule risk already ran a Monte Carlo simulation and reported the spread
of likely outcomes. What it multiplied was a three-point estimate — optimistic, likely, pessimistic —
which on most jobs is one person's opinion entered three times. The percentiles were precise about an
opinion. Every finished activity on the job is a measured comparison of planned duration against
actual, so the spread now comes from **this project's own completed work, by these trades**.

An activity that has *started but not finished* is deliberately excluded. Its measured duration is
however far it has got, which is always shorter than the truth, and including it would drag every
forecast optimistic — the direction of error that gets people hurt. When there is too little history
the result falls back — trade, then project, then the supplied estimate — and **says which rung it
landed on**, because a forecast whose provenance is invisible cannot be argued with. With no history
and no estimate it refuses outright rather than returning "no change", which would read as "no risk".

**How late are we?** A schedule with no *as-of* date is a plan, not a status report: an activity with
no recorded start might be future work sitting comfortably ahead of its date, or work that should have
begun three weeks ago, and nothing could tell them apart. With a data date, that distinction becomes
trivial — and without one, **nothing is called late at all**, because assuming today would quietly
paint a job that finished two years ago entirely red.

An activity that **finished late is complete, not overdue** — its slip already happened, and putting
it on a chase list helps nobody. And a **forecast finish** now exists as a field: the date whoever is
doing the work expects to hit. That is a *claim about the future*, not a record of the past, so it is
reported separately from actual slip and never added to it.

A review of this release caught the sharpest possible version of that same principle turned on
itself: the status engine judged an activity by whether its actual dates *existed* rather than whether
they had happened yet — so a job evaluated as of January reported work finished in June as already
complete. Dates in the future are now disregarded, and the fact that they were disregarded is stated
rather than hidden.

**And both are now reachable.** Four capabilities had shipped over recent releases fully tested with
**nothing that could call them** — which from outside is indistinguishable from a working feature, and
which survived every gate, because none of them asks whether a request can actually arrive. Schedule
status, the calibrated spread, the kind-of-claim tagging and the drawing-scoped takeoff all have
routes now, each exercised through a real request rather than only in isolation.

The calibrated spread rides *alongside* the simulation rather than replacing its inputs, so you can
see how many finished activities backed it. Drawing scoping is optional, leaving the single-drawing
case untouched. Auditing for the rest found three more capabilities nobody can call, recorded for the
next release — and a standing check worth more than any of them: *what did we build that nothing
calls?*

## v0.3.709 — four ways to say a wall is fire-rated

"This wall is fire-rated" can mean the specification requires it, the model asserts it, an inspector
went and looked at it, or a rule worked it out from the wall type. Four different claims, rendered
identically — and an estimator, an inspector and a lawyer each need a different one of them.

Every fact about an element now says which kind it is: **specified**, **asserted by the model**,
**observed**, or **derived**.

The design turns on one thing: **the kind follows the source, not the fact.** A verification backed by
a stamp in the model is the model asserting something; the same verification backed by a site record
is somebody having looked. A table keyed on the name of the fact would have to pick one and would be
wrong half the time.

**The four are deliberately not ranked**, and resisting that was the harder call. It is tempting to
say an observation beats a specification — but for *what should this be*, the specification is the
authority and an observation is beside the point, while for *what is it*, the observation wins and the
specification is a wish. Which question is being asked belongs to whoever is asking it, not to the
layer underneath.

A fact whose origin is not recognised is reported as **unknown** and listed separately, never quietly
filed under one of the four: guessing "derived" invents the weakest possible claim and guessing
"observed" the strongest. "Nobody recorded this" also stays distinct from "recorded, and we cannot
tell what it is" — collapsing those loses the one worth acting on.

The payoff is a question that could not be asked before: **has anybody actually looked?** An element
that is specified, modelled, priced and scheduled but never observed is one nobody has seen — and
until now that was indistinguishable from one that had been inspected.

## v0.3.708 — one set of icons, and they borrow their colour

The interface wore coloured emoji: several visual languages at once, each at its own weight and fill,
each carrying a colour the platform did not choose. They are now one monoline set at a single stroke
weight.

**The icons carry no colour of their own.** Every one draws in the colour of the text beside it. That
is the whole point rather than a detail — the rule established earlier that each colour means exactly
one thing now governs icons automatically, and an icon is *unable* to introduce a new meaning for
blue even by accident. Tests check that no colour is hard-coded anywhere in the artwork.

**They are copied in, not depended on.** This was held up for a while as a choice between drawing a
hundred icons by hand or taking on a licensed package. It was neither: an icon set is just drawings,
so the thirty-one this app uses now live in the source. Nothing is fetched at runtime — which is what
running offline requires anyway — and the fifteen hundred we do not use are simply not here. The
licence notice travels with the copies, as that licence requires.

Every labelled button in the model toolbar now has one, and a check makes sure a new button cannot
ship without one — or with the name of an icon that does not exist, which would render nothing at
all, and nothing looks exactly like "not done yet".

## v0.3.707 — a note belongs to the drawing it is about

A general note about the floor plan and a note about the section sit centimetres apart on the same
sheet. Attached to a sheet number, they are indistinguishable, and somebody has to read them to work
out which drawing each one is talking about — which is exactly why annotations on received drawings
never reach any downstream tool.

Notes, keynotes and revision clouds now attach to the **view** they govern.

The interesting part is what was *not* built. An annotation and a traced outline ask the identical
question — which drawing is this on — so this reuses the placement engine that shipped last release
rather than growing a second one beside it. Two routines answering one question is a guarantee they
will eventually disagree, and then nobody can say which is right.

A sheet-wide stamp comes back as belonging to **no view**, and that is the correct answer rather than
a failure: a drawing-number stamp governs the sheet, not any drawing on it. Saying so plainly is the
difference between a result and a shrug.

## v0.3.706 — a measurement belongs to the drawing it was taken from

Quantity takeoff applied **one scale to a whole sheet**. That is correct for a sheet carrying a single
drawing, and quietly wrong for every other one — a floor plan at 1:100 sitting beside a detail at 1:20
means the detail gets billed at five times its size. Nothing checked that a traced outline was even on
a drawing rather than over the titleblock.

Each trace now resolves to one of three things, and **only one of them can be priced**. Inside exactly
one drawing: measured at *that* drawing's scale. Off every drawing: reported, never quietly billed —
an area measured across a legend is not an area. Crossing two drawings: reported as ambiguous, because
two different scales apply to one outline and there is no single right answer, so choosing one would
be a coin toss dressed as a measurement.

**Screen pixels are not paper points**, and the release turns on not pretending otherwise. Traces come
from a rendered image; drawing frames are measured on the page. Relating the two needs to know what
zoom the sheet was rendered at, and that belongs to the caller. Without it, this **refuses to place
anything** rather than assuming they are the same — an assumption that would drop every trace into the
corner of the page and report it with complete confidence.

And on a sheet this platform drew, the scale is not something to measure — it is something already
known. A hand calibration that disagrees with it is now **reported**, so an estimator can see they
clicked the wrong drawing. The known number is deliberately **not** substituted: the image may
genuinely have been rescaled on its way in, and replacing somebody's measurement without telling them
would bury that.

## v0.3.705 — a project is one file, and the file explains itself

The project container is now **`.mass`**. It was `.mmproj`, a name that read as *Microsoft Project*
to anyone who had not seen it before — the opposite of what it is. This container has never held a
byte of XML or any vendor format: it is a ZIP of JSON plus a standard IFC. An extension that misleads
about its own contents is a defect, so it got a name that does not.

**Nothing anyone already saved is orphaned.** Version 1 `.mmproj` files still open, and always will.
A rename that abandons existing work is not a rename.

**The container explains itself.** A plain-English README now travels *inside* the archive, because
documentation that lives in a source repository is documentation the person holding the file does not
have. Unzip a `.mass` in ten years with none of our software and you can still work out what you are
holding: where the model is, how the data is laid out, and that building elements are referenced by
IFC GlobalId throughout — so any row can be tied back to an element in any tool.

**It is honest about what it does not contain.** The manifest lists every entry with its size, and
names the tables that deliberately did *not* travel — user accounts, the audit log, application
settings, saved connections — together with the reason: those belong to an installation, not to a
project, and importing them would overwrite the destination's own. A container that drops them
silently looks complete and is not.

**And it refuses rather than guesses.** A container written by a newer build is declined outright
instead of being partially read, because a half-imported project is worse than a rejected one — the
user believes they have their data. An unrecognised format is refused too, and the message says what
was expected.

The format is documented in full, including how to read one without any of our code, and the intended
path to becoming a standards-conformant ISO 21597 container rather than one only we can open.

## v0.3.704 — opening a model and opening a project are one act

Until now, opening an IFC ended at the viewer. The model rendered, and every data panel went on
saying "No project open" — because nothing tied the two together. That split has produced real bugs
twice in as many releases, so this release closes it rather than patching another instance.

Open a model now and the app works out what that means: **join the project that already holds it**,
bringing its RFIs, costs, schedule and documents along; **propose a new project** when the server has
nothing matching; or **stay in the viewer and say why**, when there is no server to talk to at all.
Opening a model while a project is already open loads it into that project rather than starting a
rival.

Three deliberate restraints. **Nothing is created silently** — a project is a durable, shared record,
and minting one for every file somebody previews fills the register with things nobody meant to make,
so a new project is proposed and confirmed. **A weak match says it is weak**: models are matched by
file name, and two firms' `Building.ifc` are not the same building, so the prompt states exactly what
it matched on and asks you to check. And **a failed lookup is never read as "no projects exist"** —
that would offer to create a project on top of one already there; it falls back to the viewer and
explains itself.

The decision — join, create, or view — is a pure function with its own tests, kept apart from the
part that talks to the user and the server, because that is where this kind of thing goes wrong.

Also in this release: the ISO 21597 container format and the RDF library approved for it are now
recorded in the attributions file, including that the container is implemented from the published
standard and that no specification text is redistributed.

## v0.3.703 — the stall was never the geometry

The dev preview has stalled for weeks, and the workaround was written into a checklist as a known
limitation of loading models in a browser. It was none of those things.

**Five event-stream endpoints ran their database polls directly on the event loop.** An `async`
generator executes its ordinary statements on the loop, so every four or five seconds each open stream
stopped the entire server for as long as its query took — and one of those queries walks every module
a user can see. Two browser tabs were enough to leave the server blocked more than it was running, so
*every* request timed out. That reads as "the server is wedged", not as "one handler is slow", which is
why it survived so long: the symptom pointed nowhere near the cause. Measured with three streams open,
before and after: **every endpoint timing out beyond eight seconds → all of them answering in about
twenty milliseconds.**

That one fix cascaded. The app could not reach its health check, so it never learned which project was
open, so the portal showed "No project open" while the model sat rendered on screen behind it — the
split between opening a *model* and opening a *project* that made the whole app look half-connected.

**A workspace could be permanently empty because it was opened half a second too early.** Visiting the
Developer or Design tab before the project had loaded ran their setup, saw no project, painted the
placeholder — and then set a latch saying "already initialised". The project arrived moments later and
neither tab ever tried again for the rest of the session. They now latch only on a setup that actually
succeeded.

**And the audit that was supposed to catch all of this was scoring the placeholder as content.** The
"No project open" message runs to 123 characters, three times the threshold for "this pane has
something in it", so a workspace showing nothing but that message was reported as rendering fine. Every
other guard in that file defends against calling a working pane blank; this was the opposite, and it is
the worse direction — a false blank gets investigated, a false pass gets shipped. With it fixed, the
new shell now audits **7 of 7 workspaces clean**, which is the first time that claim has been true
rather than assumed.

Also in this release: the audit no longer reports "this room is missing" when no navigation was
rendered at all — an unbuilt rail is nothing to judge, not a broken rail — plus a verified triage of an
external performance report, and a scan of a construction-data toolset whose published licence for its
headline dataset does not match the licence file in the repository.

## v0.3.702 — the audit had never looked at the thing it was built to check

Four pieces, and the one worth leading with is a defect in our own evidence.

**The render audit shipped without ever pointing at the new shell.** It was written to verify the app's
redesign, and its headline result — *all seven workspaces render, no problems, nothing unmeasured* —
was produced against the **old** shell, because the file contained no reference to the new one at all.
That number was then available to be read as proof of a redesign it had never touched. An audit that
does not state its configuration produces results that migrate to the wrong claim. Every report now
carries which shell it measured; the five-room rail is judged directly, including the case of a room
that renders with nothing in it — worse than an absent room, because it looks like a place to go; and
a comparison names a **regression**, meaning a pane that renders in the old shell and not the new one.
That comparison is the actual gate on making the new look the default, so it is a pure function with
tests rather than something observed once by hand.

**The Inspector's tabs.** Selecting an element showed a six-state strip that could say a cost state was
complete while offering nowhere to go and see the number — a summary with no detail behind it is a
claim you cannot check. Properties, Cost, Schedule and Field now sit under that strip, which stays
above them because it summarises all four. Each tab states **before you click** whether it has
anything, using the strip's own three marks rather than a second symbol language meaning the same
things. A tab whose data never loaded and a tab whose data loaded and was empty are **different**, and
say so in different words: the first is not a finding, and rendering it as *nothing here* would invent
an absence nobody checked for.

**A schedule of values built from the estimate instead of typed in again.** Every other link in that
chain already existed — the estimate prices the model, the continuation sheet reads the schedule of
values, the payment application renders it — and nothing joined the first to the second, so the numbers
were re-keyed by hand at exactly the seam where somebody asks to be paid. The transformation is a
regrouping, and the whole risk of a regrouping is money going missing inside it. So unpriced scope is
excluded **and named** rather than dropped; the rounding residual is placed on the largest item and
reported, because rounding each line then adding is not the same as rounding the total once and that
penny is what gets a payment application rejected; a result with no markup says **at cost**, since
billing a lump-sum contract off unmarked-up cost under-bills it by the entire fee every month; and each
item keeps the model elements behind it, so a billed line traces back to what it pays for.

**A drawing's layout, readable at last.** Sheet composition could place a viewport, fix its paper scale
and crop to it — and none of that survived the finished PDF, so a takeoff on a sheet this platform
produced still had to be traced blind and calibrated by hand against a scale we had already computed.
The exact page-to-world transform is now kept, so measuring on our own sheets needs no calibration step.
A viewport with no geometry reports its mapping as **unknown**, never as an identity, because an
identity would quietly report page points as metres.

## v0.3.701 — a lock that holds, or names what stopped it

Dimensional constraints — keep this wall 3000 off that grid, keep these mullions evenly spaced, keep
this level chain aligned — plus the research ring behind the next stretch of work.

**No new dependency was added.** The backlog had unblocked this item by choosing a Cassowary
constraint-solver package, reasoning that its inequalities-and-strengths model fits BIM locks. That
reasoning is right about the *shape* and wrong about the *need*: numpy and scipy are already here, and
this is a linear least-squares problem with priority tiers, where `lstsq`'s **rank** is the degrees of
freedom and its **residual** is whether a tier is satisfiable — exactly the two numbers the interface
wants. The package installs fine; checking whether it was necessary first is the cheaper habit.

**Strength is a tier, not a weight.** A `required` lock is not "a very heavy preference". The first
implementation blended them into one solve, and a strong preference duly bent a hard lock: a 3000
constraint came out at 7666. Least squares has no notion of a non-negotiable row — the only way to say
it is to remove those directions from the search. Each tier is now solved exactly, then frozen into a
null-space basis that weaker tiers may move within and cannot escape. A preference yielding is the
system working; a hard lock yielding by a millimetre is what makes people stop trusting locks at all.

**Three things it refuses to do quietly.** An over-constrained system **names** the constraints that
cannot both hold, rather than satisfying whichever was reached first and leaving geometry that looks
deliberate. An under-constrained one **reports its degrees of freedom** instead of silently picking one
of infinitely many solutions — that is how a "solved" sketch drifts on the next edit. And clearances
are **checked, never enforced**: sliding geometry to satisfy a code minimum would move something a
person placed on purpose. A conflicted row is also never frozen, since that propagates one modelling
error into every weaker tier as a phantom lock.

Also in this release: proforma fixes where a loan-first funding order never actually drew on the loan
and the risk simulation flattered the riskiest deals, and a new research ring covering drawing layout,
claim provenance, the estimate-to-schedule-of-values gap, and calibrating schedule risk from a
project's own history rather than from a three-point guess.

## v0.3.700 — two estimates, diffed by GlobalId, with every dollar attributed

A code review caught this module lying, and the most useful thing about it is *how* it lied.

**It reconstructed per-element quantities by dividing a line's total evenly across its GlobalIds.**
Add one wall to an existing line and every *other* wall in it reported as a design change, while the
new wall took the average rather than its own quantity — on the most ordinary edit an estimate ever
sees. And `reconciles`, the check written specifically to make this module trustworthy, stayed
**true** the whole time, because invented numbers sum just as correctly as real ones. A
self-consistency check is not a correctness check.

`fived.estimate` now emits `by_element` with the exact figures it already had and was discarding, and
the diff consumes them. Where an input lacks it, the diff **does not fall back to apportionment** — it
diffs whole cost lines and reports `granularity: "line"`. A coarser true answer beats a finer invented
one.

"The estimate went up $340k" is not information. *Which elements* moved it, and *why*, is — and
because both estimates key on GlobalId, the diff can say. That is the whole reason this platform
refuses to identify elements any other way, and this is the payoff.

**Four causes, because they are four different questions.** `added` and `removed` are scope.
`requantified` is a design event — the same element and rate, a different quantity. `repriced` is a
commercial decision — the same element and quantity, a different rate. A number that moved because a
rate was updated and one that moved because a wall got longer should never sit in the same row;
collapsing them into "the total changed" is how an estimate review turns into an argument.

**`both` is not a leftover bucket.** When quantity *and* rate move together, apportioning the delta
across `requantified` and `repriced` produces two numbers that add up correctly and neither of which
describes what happened. It is reported as one change, with both pairs shown, so the reader can see
exactly what moved.

**The parts add back to the whole** — and that check is a floor, not a proof. The residual is stated
either way rather than asserted away. A diff whose parts do not sum to the whole is definitely wrong;
one that passes has merely not lost money, which the original version demonstrated is compatible with
being entirely fabricated.

**Five more findings from the same review, all fixed and pinned:** a *quantity* was compared against
the *money* epsilon with `repriced` as the fall-through, so a pure design change with identical rates
came back labelled commercial; the small-delta skip ran *before* classification, so a compensating
change (quantity doubled, rate halved) was asserted to be no change at all; the route 500'd on
malformed input where its sibling returns 422; duplicate keys overwrote rather than accumulated; and
`items` was capped at 500 with no truncation flag, so any UI totalling them would disagree with the
reported delta and have no way to tell why. That last one stings — "no silent caps, say what was
dropped" is a rule applied three times elsewhere in this session and then broken here.

**Two further bugs surfaced while fixing those.** A code priced at several rates merges into one line
group, and reporting `unit_cost: None` for it looked conservative while hiding the change entirely —
no rate movement, no quantity movement, real money unattributed. Putting the rate in the key made the
money reconcile but reclassified a repricing as a removal plus an addition: scope change, the one
distinction this module exists to draw. It now compares the *set* of rates, so a shift in the mix at
unchanged rates reads as a design change. And `write_work_schedule` (v0.3.696) raised part-way through
on a bad task type, leaving an `IfcWorkSchedule` with no assignment and orphan `IfcTask`s — which a
caller turning `ValueError` into a 422 would then save. Validation now runs over the whole batch
before anything is created.

Rounding noise is not a change: the epsilon is a named constant, because an unstated one turns float
jitter into a line item on a change report. Degenerate inputs are answers rather than crashes — a
first estimate is all `added`, an abandoned one all `removed`, and every cause is listed with its
meaning even at zero, so nobody has to wonder whether "removed" was absent because nothing was
removed or because the key was dropped.

## v0.3.699 — a rate carries its year, and "no rate" is not "no charge"

v0.3.697 made a quantity say where it came from. An estimate is a rate times a quantity, and a line
that can answer for one half and not the other is only half checkable — so this is the other half.

A cost rule may now set `rate_from: "vintage"` and draw its rate from the project's pinned cost
database, localized by region index and escalated to the construction midpoint. The number arrives
with a **year** attached. Each line reports `rate_source` — `quoted`, `vintage`, or `mixed` — and the
payload carries the vintage's own metadata. Two estimates differing by 40% because one priced off a
2019 vintage is a question somebody can answer; the same gap with bare numbers on both sides is not.

**A vintage rule whose class the cost database does not price gets its own state.** It is not
*unpriced* — a rule matched the element. It is not *priced* — there is no number. Calling it either
would make the estimate silently short or silently free, so it is `no_rate`, reported against the
rule that wanted it (so the fix is actionable: either the vintage needs that class, or the rule should
quote a rate), and `complete` is false while any remain.

Layering still wins. A later rule that *can* price the element clears the flag, because reporting a
gap a subsequent rule already closed sends an estimator to check something that is fine. Two things
in that filter were wrong in the first draft and fixed before shipping: it left successfully-priced
elements in `no_rate`, and it scanned the list per element, which is quadratic on a real model.

A rule that asks for a vintage needs no `unit_cost`; an unrecognised `rate_from` is refused rather
than quietly treated as quoted.

## v0.3.698 — hardening: an N+1 on the daily home page, and an uncapped mesh behind an estimate

A hand-audit over everything shipped in v0.3.688–697. Two real defects, both introduced by that work.

**The work queue did an N+1, and it was on the page people would open every morning.**
`work_queue.queue()` called `get_record()` once per item — and `get_record` is not a row read: it
pulls the activity log, the comments, every attachment, resolves reference fields to briefs and
evaluates rollups. At `MY_WORK_LIMIT` that is ~500 items × ~5 queries with their joins, to read **one
date field**. It is now one query per *module*.

The test asserts the property rather than a number. An absolute statement count would be asserting on
the size of the module registry, which is not what broke; what matters is that **cost must not scale
with item count**. Measured: 3 items → 134 statements, 12 items → 134 statements. Delta zero.

That measurement also surfaced something **not** fixed here, and the test pins it rather than letting
it pass unnoticed: `my_work` issues one query per *registered module* (~130), so the floor scales with
the catalog rather than the caller's workload. It is pre-existing, the dashboard depends on it too,
and quietly absorbing it into a "the queue is cheap now" claim would be the wrong kind of tidy.

**An uncapped geometry pass sat behind a request-serving route.** `qto.measure` meshes every element
with `create_shape`; the estimate route previously did no geometry work at all, so v0.3.697 put
minutes of meshing on a large model behind one request. It is now capped at 20,000 elements — and the
cap is **reported** (`geometry_capped`), never silent, because a quantity nobody measured for want of
budget looks exactly like one the model never carried, and only one of those is worth chasing. Every
element is still present in the payload: the cap bounds the measuring, not the reporting.

The rest of the checklist came back clean. All three new routes carry `require_role`; both new panels
escape every interpolated string; `element_facts` caps newest-first rather than hiding recent rows.

## v0.3.697 — the estimate measures the model, and says what each number rests on

`fived.estimate` took its quantities from whatever the caller passed in. Every rule, every rate and
every roll-up could be correct while the numbers described a different building — an estimate that is
internally consistent and externally wrong, which is the worst kind, because nothing in it looks off.

`qto.measure()` now returns every element's quantities keyed by GlobalId, and the estimate route
composes it. A caller can still override a quantity — an estimator legitimately does — but an
override now *replaces* the model's own number rather than being the only source of one.

**The substance is provenance.** Quantities arrive by different routes and they are not the same
claim, even when the numbers nearly agree:

- **declared** — the model's own `IfcElementQuantity`. An authoring tool asserted this wall is 12.4 m².
- **computed** — we meshed the solid and measured it here. Our approximation of the same thing.
- **override** — the caller supplied it in place of the model's.
- **unknown** — quantities arrived carrying no provenance at all.

A line is only `declared` when **every** element in it was. One measured element in fifty makes the
line `mixed`, because rounding that to "declared" would have the reader believe the model asserted a
number we partly made up — the kind of small lie an estimate cannot afford. An absent provenance
reads `unknown`, never `declared`: a caller who sends quantities without saying where they came from
has told us nothing, and answering "the model declared these" on their behalf is exactly the overclaim
the field exists to prevent. `computed_quantity_lines` and `computed_quantity_amount` state how much
of the total rests on our arithmetic rather than the model's assertion — not a fault, often the model
simply carries no Qto pset, but it is what an estimator wants to know before signing.

Provenance annotates and never moves a number. The totals are asserted identical across all four
labellings, so the label cannot quietly start doing arithmetic.

An element with no readable quantity lands in `unmeasured` rather than getting zeros. Zero is a
measurement; "we could not measure it" is not, and billing the second as the first is how an estimate
ends up confidently missing a floor.

## v0.3.696 — the 4D binding goes into the model, and the plan named the wrong relation

v0.3.684 put cost into the file: a priced element carries its price via `IfcRelAssignsToControl` →
`IfcCostItem`. This is the time half — `IfcWorkSchedule` + `IfcTask`, in `aec_data/fourd_ifc.py`.

The asymmetry it closes is the interesting part. `schedule.from_ifc` could always **read** tasks and
their outputs, but nothing in the platform could **write** them. So a schedule authored in another
tool could be consumed, while the platform's own schedule lived only in its database: unable to
travel with the file, invisible to every other tool, re-derived on each export. A read half with no
write half is not a partial feature; it is a one-way door. This also unblocks 4D clash phase 2, and
turns the Inspector's `scheduled` state from structurally unanswerable into answerable.

**The roadmap entry specified the wrong IFC relation, and the first implementation followed it.**
`IfcRelAssignsToProcess` is the task's *input* — `task.OperatesOn`, "this task operates on that
product". The link for "this task builds this element" is `IfcRelAssignsToProduct`, the task's
**output**. Both are real IFC and both round-trip cleanly through a reader written to match, so the
mistake is invisible to any test that only checks its own writer. What caught it was asserting the
new binding against this repo's **pre-existing** reader — which, like every tool that asks what a
task builds, reads outputs. A test that had only checked the round trip would have shipped a 4D
binding no other tool could see.

Three behaviours are deliberate, each with a test. An unmatched GlobalId is **reported** and its task
still written — the work is real, and dropping it makes a programme quietly shorter than the project,
discovered from a missed date rather than a report. **Half** a date range writes no dates at all,
because a duration resting on one supplied end reads as authoritative and is not. And an *absent*
task type defaults to CONSTRUCTION while an *empty* one is refused — somebody who tried to state a
type and failed should not have CONSTRUCTION written over them. That last one the code got wrong
first; the same distinction `cost_ifc` draws for `basis` is what settled it.

## v0.3.695 — the live audit, and the four ways a render audit lies

R26 began with a click-through of the app. Click-throughs do not survive: the next person redoes the
whole thing, and afterwards nobody can tell whether a pane was blank or merely unmeasured. This turns
it into an artifact you can run and re-run — `window.__liveAudit()`, dev-only, no behaviour attached.

**Live result: all 7 workspaces render, 0 problems, 0 unknown.**

What is tested here is not "does the app render". It is **does the auditor lie** — and every trap
below fails in the same direction, toward a false blank, which is the expensive direction because it
invents defects that then get "fixed".

1. **`innerText` is empty for anything not laid out.** A hidden workspace, a collapsed `<details>`, a
   pane behind `display:none` — all report no text while perfectly populated. Content is read from
   `textContent`, and a pane that is not displayed reads **`hidden`**, never `empty`.
2. **A click rebuilds the nav, detaching any node you were holding.** A reference captured before a
   click points at nothing, and clicking a detached node silently does nothing — so every workspace
   after the first would read blank. Everything re-queries by name after every interaction.
3. **The shell is not the content.** A populated rail beside an empty pane still measures as "has
   content". The content pane is measured separately, and its absence reads `unknown` — the audit does
   not know whether that pane has a different structure or is broken, and guessing is worse.
4. **A pane that is still booting is not an empty pane.** This one was found by running the auditor
   against the real app: it reported Model, Design and Developer blank, and all three were mid-boot
   and fully populated seconds later. An empty verdict is now never final on first look — the pane is
   re-examined, and one that fills reads `slow`, which is a pass.

Two bugs in the auditor itself were caught by its own tests. It first used `offsetParent` to decide
what was displayed — which is null for every `position: fixed` element, so the floating toolbar and
every modal would have been reported as invisible by the tool whose entire job is not producing false
negatives. And `offsetParent` needs a real layout engine, so the guard could not be tested at all. A
guard against the audit's worst failure mode has to be the best-tested thing in the file, not the
least; it now walks computed style up the ancestor chain, which is both correct and testable.

## v0.3.694 — the work queue: what is in your court, in the order it needs you

The **Work** room's whole job, and the last open item in R26 Sprint D. Both halves already existed —
the platform knew what was in your court (`my_work`) and what was late (`due_feed`) — but as separate
lists on separate screens, neither carrying the thing that turns a list into a queue: what you can do
about each item without leaving it. **My Work** now leads every rail's first stage.

**`undated` is not `later`.** An item nobody dated is a gap somebody should close, not a low priority.
Folding it into "later" would sort an urgent dateless RFI below a routine item due next month, and
would hide the gap that caused it — so it gets its own bucket, *above* `later`, with its reason on
screen. Absent, blank and **unparseable** dates all land there, because an unreadable date means the
same thing as a missing one, and treating it as far-future would bury the defect along with the item.

**Every action offered is one the engine will honour** — this party, from this state. Proved by
running one against the API rather than asserted, because a queue that offers a button the server
then rejects spends the user's trust before it spends their time. An action the module gates behind
required fields is shown as a link into the record instead: it needs a form, not a click, and
pretending otherwise is how a one-click button becomes a dead end.

Counts are split: "14 items" and "14 items, 3 of them waiting on somebody else" are different
statements, and only the second lets someone plan a day. The queue is built **on** `my_work` rather
than beside it, and is asserted to return exactly that feed — a second definition of "in my court" is
precisely how two screens come to disagree, which is the defect v0.3.693 exists to catch one layer up.

One mistake is recorded in the test: it originally wrote a plausible-looking `response_due` field the
RFI module does not define, so every record came back undated and the queue dutifully reported four
undated items — correct behaviour, useless test. The due-date field is now asked of the engine.

## v0.3.693 — the app can no longer disagree with itself about six numbers

The audit's most damaging class of defect was never a missing feature; it was two screens showing
different values for the same thing. A user who catches the app contradicting itself stops trusting
every other number on it, and the loss is not confined to the number that was wrong.

v0.3.686 fixed one instance. A fix is not a guarantee, so this is the gate: six identities asserted
**between the surfaces that actually render them** — open RFIs (dashboard KPI vs the RFI board),
total records (KPI vs its own per-module breakdown), budget (cost summary vs the dashboard's embedded
snapshot), my action items, the health score against the domains it is a mean of, and the module
catalog against the room allocation that files it. Confirmed to bite by perturbing the dashboard and
watching the gate fail.

Comparing an endpoint to arithmetic restated in the test would prove only that the test can add up.
It was agreement *between screens* that was the defect, so the comparison is screen-to-screen, and
where a shared constant is unavoidable (the status→score mapping) it is imported from the engine
rather than copied — a copy is exactly the drift this file exists to catch.

**Every check runs on a seeded, non-zero project.** Zero equals zero on every surface, so a gate run
against an empty project passes while proving nothing. Two mistakes on the way there are recorded in
the file rather than quietly corrected, because both are the same failure the gate is for: the health
identity originally read a `score` field the domains do not carry, so it skipped in silence and
passed having tested nothing; and one module's seed was failing without being asserted, which left
three identities comparing two views of the same absence.

Coverage is **declared**, not implied. `IDENTITIES` names exactly what is pinned. This is not a claim
that the app is globally consistent — six pairs cannot drift apart without failing the build, and
saying more than that would be the same defect one level up.

## v0.3.692 — one meaning per colour, and something that keeps it that way

The audit found the primary blue marking Open, Save, the selected tab, the selected rail item, **every
KPI number**, PDF Takeoff, Paper space and Zoom-to-cursor — all at once. When one colour means eight
things it means nothing, and a dashboard of blue numbers has no emphasis left for the one figure that
needs it.

Blue now means **you can act on this**. Green is solved, amber needs attention, red is blocking, and
everything else — including data — is plain text. Five things stopped being blue: KPI numbers, the
IFC-class badge in the properties header, form section headings, the ball-in-court party pill, and
the value at a node-graph output socket. None of them was ever a control.

The KPI case is the one worth describing, because the tempting fix is wrong in both directions.
Painting every number blue is what made dashboards unreadable; painting none of them loses the cue
that some figures are links. So `.kpi-v` is plain text and `.kpi-click .kpi-v` stays blue — same
colour, but now it asserts something true: **this figure goes somewhere.** Verified live on the
Construction dashboard: four clickable KPIs blue, two plain ones in text colour.

A rule with no enforcement is a comment, so this one has a gate. `ui/colorContract.ts` lists every
selector permitted to paint text or background with the accent, and its test asserts that list
against `style.css` **in both directions** — a new accent-coloured selector fails the build, and a
stale allowance fails it too. Writing the list by hand first was instructive: most of my guesses were
wrong, because they used the accent only on borders. Borders, outlines and shadows are exempt; there
the colour is doing exactly its job, and gating them would be noise with no signal.

## v0.3.691 — the model toolbar: 27 glyphs, always, becomes four words

The audit's most concrete finding was a floating toolbar carrying **27 unlabeled glyphs, all of them,
always**. Live in the running viewer it is now **Levels · Section · Measure · Ask** — four labeled
verbs on one 305×24 row — with the other 23 tools under **More**, grouped and described. Nothing was
removed; every button is still there and still one click away.

Two wrong fixes were available and both were declined. Deleting tools nobody could identify would
have removed things people use — they were never unusable, only unlabelled. Labelling all 27 would
have produced a wider wall, and a wall is a wall. What helps is fewer things visible at once, each of
them readable.

**A glyph without a word is a puzzle.** `⧉`, `✥`, `◧`, `⬚`, `⊞` are not guessable, and a tooltip only
helps someone who already suspects what the button does. Primary buttons now show a short verb beside
the glyph — the glyph stays, because it is what a returning user recognises — and More lists the
label *and* the description, so the long tail is scannable as text rather than as a second grid.

**The bar is contextual, but its pinned verbs never move.** Move, Copy and Edit-in-place appear when
something is selected and are meaningless otherwise. The first version of the layout table treated
"always visible" as merely a predicate returning true, which let contextual verbs push **Ask** past
the cap the moment you selected an element — a verb you learn the position of and then cannot find is
worse than one that was never on the bar. Pinned verbs now hold fixed positions and contextual ones
append after them. The test that caught this is the one that asserts it.

**A layout pass cannot lose a tool.** The buttons are still created by the modules that own their
behaviour; this only moves them between two containers. A button the layout table does not describe
still appears — under More, tagged `data-unlaid` and logged — because a tool that quietly vanishes
from a toolbar is indistinguishable from one that was deliberately removed, and the person who
notices is a user who needed it. Live, `unlaid` is zero: all 27 are accounted for.

Labelling also **surfaced a real duplicate**: two first-person walk tools, both 🚶, both installed,
sitting next to each other — one drives the camera per frame and you drag to look, the other takes a
pointer lock and exits on Esc. As two identical glyphs they read as a rendering bug. They are now
labelled *Walk (drag)* and *Walk (locked)* so the duplication is legible. Which one should survive is
a behaviour decision, not a layout one, so it is recorded in the roadmap rather than settled here by
whichever one I happened to keep.

## v0.3.690 — the Inspector: six states on one key, and three ways of not knowing

Select an element and the lifecycle strip now sits directly under the identity header —
**designed · checked · priced · scheduled · installed · verified**, left to right. Every one of those
facts was already held against the *same GlobalId*; they simply lived in six panels across different
workspaces, which is why the one genuinely unusual thing about this product was invisible.

v0.3.687 shipped the engine that decides how those states *read*. This release answers what they
**are** — and the work was almost entirely in keeping three answers apart: the platform looked and it
is yes, it looked and it is no, and **it could not look**. Each of the three states being wired had
its own way of collapsing that distinction.

**Checked.** The integrity lenses cap every offender list at 20 for payload size. Looking this
element up in that sample would report *clean* for the 21st duplicate — a check that examined a
different element, answering about this one, which is worse than declining to answer. So the rules
are re-evaluated exactly for the GUID, and an element absent from the model reads *unknown* rather
than clean. The test builds a model with 25 orphans specifically to assert that the ones past the cap
still report as findings.

**Scheduled.** An element no activity claims looks unscheduled. But where **nothing** in the project
binds tasks to elements, that is a missing capability dressed up as a finding about the building — so
the project-wide binding is checked first, and only a project that actually uses it can return a real
"no". This is the same rule as "a check that examined nothing must not report clean", applied to the
negative side, where it is easier to miss.

**Verified.** The IFC LOD-500 stamp and a field record can both assert it. The stamp wins, because
IFC is the source of truth; the record is the fallback; and `source` states which, because they are
not the same evidence even when they agree. A verification carries its accuracy either way —
millimetres from the field record convert to metres — since a tick without a tolerance is not a
measurement.

The rendering keeps the distinctions the engine draws. `unknown` is a neutral dashed state, not a
paler failure: colour the unexamined as failed and people learn to ignore the strip, at which point
it is worse than nothing because it looks like something was checked. A state that is individually
true but sits past the contiguous reach is marked as detached, so a tick can never read as progress
the element has not made. Inconsistencies are shown. The strip is fetched after the properties and
grafted in, so a slow or absent lifecycle route never delays what the user asked for — and a failure
leaves no strip at all, because an empty strip is a claim and no strip is not.

## v0.3.689 — R26 Sprint B: the five-room rail, and the catalog that could finally be checked

**Model · Cost · Schedule · Deal · Work** — the same five rooms for every role, rendered behind
`?shell=spine`. A workspace *weights* the spine: its room comes first and opens. It never removes one,
because a room that disappears in one workspace is a room the user has to relearn where to find, and
that is the failure the spine exists to end.

Building the rail turned out to be worth less than what building it forced. The 40-odd first-class
destinations lived as a literal **inside `buildNav()`** — which is why nobody had noticed that
Facility Condition appeared twice in the Developer rail alone. A catalog you can only read by
scrolling through the function that renders it is a catalog nobody audits. It now lives in
`shell/destinations.ts`, and both rails read it, so the two shells cannot drift on what exists.

That move bought the check that matters: **every destination has exactly one room**, asserted in both
directions — no destination without a room, and no room entry naming a destination that no longer
exists. Both halves were verified to actually fail when broken rather than trusted to. An unplaced
destination is now a build failure instead of something a user discovers by not finding it. Anything
that still slips through is *shown* in the rail as unplaced rather than filed somewhere plausible;
defaulting is how four competing taxonomies came to exist.

Rooms also needed a memory that stages do not. A stage defaults to open, so recording only what the
user collapsed is enough. A room defaults to **closed** unless it is the workspace's own — five rooms
holding 45 destinations, all expanded, is exactly the wall of options this replaces. That makes three
states, not two: opened, closed, and *never touched*. Collapsing them would make the rail either
forget an explicit collapse or override an explicit expansion.

Verified live in the running app: the Construction rail opens on **Schedule** with 5 entries visible
and the other 45 one click away; an explicit collapse of the workspace's own room survives a rebuild,
and so does an explicit expansion of another. A `/rooms` failure falls back to the classic rail rather
than to an empty one — confirmed against a server that genuinely lacks the route.

## v0.3.688 — the family shelf: one real duplicate merged, and 57 packs that were licensed all along

Two backlog items about the family content shelf. Checking the premise of each changed what the work
was — in one case from a merge into a merge-plus-a-refusal, and in the other from a compliance gap
into a reader bug.

**The batch-1 duplicates.** The upstream review flagged six overlapping family keys from the plumbing
batch. Reading the packs showed **only one is a genuine duplicate**: `pipe_copper_l` and
`pipe_copper_type_l` are one product under two names inside one pack, so the short form is retired in
favour of the ASTM B88 designation — the one that actually carries the wall thickness.

The other five are not duplicates. They are a **generic tier and a specific tier**: `wc_flush_valve`
is one *kind* of toilet, and the fixtures pack ships no tank-type WC, so aliasing `toilet` onto it
would assert a fixture type nobody specified. `shower_receptor` is a *part* of a shower.
`sink_kitchen` is not what "sink" means. That is a two-tier catalog working as designed — you
schedule the generic at concept and the specific at procurement — and merging it would destroy
information under the banner of removing it. So the tier relation is now **recorded** (`FAMILY_TIERS`,
`is_narrowing()`) rather than left implicit, and the next reviewer will not re-flag it.

The merge is by **alias, not deletion**. Deleting a key breaks every model that already placed one;
an alias keeps those references resolving while still reporting a single canonical family. Aliases
are asserted never to chain, so the canonical answer cannot depend on how many times it is asked. The
generated packs themselves are untouched — they are build output from the upstream generator, and an
edit here would be undone by the next release.

**The "unlicensed" packs.** The shelf reported `unlicensed` for all 57 packs, and the backlog entry
blamed a manifest that "carries no licence field". It does carry one. `manifest.json` declares
`CC0-1.0` for the library *and* on every pack row, next to `code: MIT`. Nothing was ever unlicensed —
**our reader** looked only for a singular per-pack `licence` key, so it missed both the library-level
declaration and the plural `"licenses": [...]` form the rows actually use. A shape mismatch had been
sitting in the backlog as a compliance problem, which is the more expensive kind of wrong.

The reader now understands both spellings and both levels. A list is treated as **alternatives** and
joined with SPDX `OR` rather than collapsed to its first entry, because dropping terms silently
removes a choice a redistributor is entitled to make. An empty list is still not a licence.
`licence_source` distinguishes a pack's own claim from an inherited one — "this pack says CC0" and
"the library it came from says CC0" are different assurances even when the string matches. And the
licence now travels with the content into the import audit trail, so the terms under which content
entered a model do not have to be reconstructed later from a manifest that may have moved on.

The shelf's `unlicensed` count is 0. The packs are licensed the same way as the rest of the platform:
**code MIT, content CC0-1.0**.

## v0.3.687 — R26 Sprint C: the lifecycle strip, where one model on one key becomes visible

**designed · checked · priced · scheduled · installed · verified**, read left to right, for any element.

Every one of those six facts was already held against the *same GlobalId* — the model, the QA lenses,
the 5D cost binding (v0.3.684), the schedule, the field record, the LOD-500 stamp. The audit's point
was that they live in six panels across different workspaces, so the one genuinely unusual thing about
this product is invisible in the interface. This is the surface that fixes that, at
`GET /projects/{pid}/elements/{guid}/lifecycle`.

Three rules decide whether a strip like this is worth having, and each of them is a place where the
easy implementation is the wrong one.

**Unknown is not "no".** An element nobody priced and an element priced at zero are different facts.
A state the platform could not consult reads **`unknown`**, never `none` — because a strip that
colours the unexamined as failed is a strip people learn to ignore. For the same reason an amount of
**zero still counts as priced**: free is a price, and conflating it with unpriced is the identical
error one level down.

**`reached` is contiguous.** An element that is verified but was never priced reports as having
reached only *checked*. A later state must never flatter an incomplete earlier one, or the strip
becomes a way of overstating progress rather than measuring it.

**An out-of-order strip reports the inconsistency rather than smoothing it.** "Verified but not
installed" is a real data defect, and quietly downgrading it destroys the only signal that says so.

Every incomplete state names what would advance it — a strip showing six greys and no next step is a
diagnosis with no prescription — and every complete one stays quiet, because telling someone how to
finish what they have finished is noise.

388/388 backend suites green · 670 project routes role-gated.

## v0.3.686 — R26 Sprint A: one room per module, and a project that stops contradicting itself

An external app audit landed with a blunt verdict: *"You built a platform. The UI is presenting it as
a filing cabinet."* Seven workspaces carry **four different left-rail taxonomies**, so nothing learned
in one transfers to the next, and modules land in more than one — Facility Condition twice in the
Developer rail alone, Model Health three times on a single screen.

**This ring changes the front door, not the building.** Every engine survives untouched — the selector
spine, the 130-module config engine, the drawing generators, the 5D cost binding, LOD-500. What
changes is that a module stops being a destination you hunt for in a catalog.

### The app no longer appears to disagree with itself

The audit reported a contradiction: model health *77/100* in one workspace, *24 · at risk* in another.
Investigating narrowed it to something more precise, and the narrower answer is the right one.

The two engines measure **genuinely different subjects** — one scores the *model* (GUID hygiene, ISO
19650 delivery, clash resolution, verified as-built), the other scores the *job* (RFIs, submittals,
T&M, quality, safety, field reporting, closeout). They are already labelled distinctly, and merging
them would produce a number answering neither question.

The real defect sat **inside one engine**: `health_score` is a **mean** across domains while
`overall_status` is **worst-of**, and both render together. Six green domains and one red shows as
*"88/100 · RED"* — each number correct, the pair baffling. A user who catches the app disagreeing with
itself stops trusting every other number on the screen, which is the expensive part.

Both aggregations are worth keeping — a PM needs the average *and* the blocker — so the payload now
declares each basis and **names the domain that governs the band**. An apparent contradiction becomes
the one sentence that was missing.

### One canonical room per module, and a gate that makes the restructure safe

All **132 modules** now resolve to exactly one room — **Model 38 · Cost 37 · Schedule 41 · Deal 16** —
served at `GET /rooms`, with the room carried on every module in `GET /modules`.

The allocation is derived from the `section` each module already declares, through **one readable
table**, rather than stored per module. A new module inherits a room automatically and an editing slip
cannot put one in two rooms. A section with **no** room is a hard build failure, never a default,
because defaulting is precisely what would hide an unreachable module.

**The verification gate ships before the restructure it protects.** `test_module_rooms` reads the
`module.json` files from disk — not a hand-maintained list — and asserts every module has exactly one
home. Losing a module is what an IA change is most likely to do and least likely to notice; this makes
it impossible rather than unlikely.

### The spine, behind a flag

`Model · Cost · Schedule · Deal · Work`, constant for every role. Professional terms are primary and
there is deliberately no second string table — the users are builders, developers, architects and
engineers who already own the vocabulary.

The property that separates a spine from another mode switch is asserted: a workspace **weights** it
and never **replaces** it, so all five rooms survive every workspace including unknown ones. Room
badges are ball-in-*your*-court rather than totals, because a badge you cannot act on is noise. The
flag has a **way back** (`?shell=classic`) — a flag you cannot leave is a migration.

Also: external design bundles can now be dropped into a git-ignored `_prototypes/` **inside** the repo
and actually run, instead of rendering as dead snapshots from outside it.

387/387 backend suites green · 167 vitest · 669 project routes role-gated.

## v0.3.685 — R24-ROLE-EXPLAIN: a refusal becomes a lesson

Controls above the caller's project role were `display: none`. The intent was good and is recorded in
the CSS comment — it removed the "click → 403" rough edge — but it bought that with a worse problem:
**a control you cannot see is one you cannot learn exists, or ask to be given.** A missing button is a
support ticket; a dimmed button that says what it needs is onboarding.

Nineteen controls across the app were hidden this way. They are now **disabled and explained**:
dimmed, padlocked, and — when clicked — answering the question actually behind the click, which is
not *"why didn't that work"* but *"who do I ask"*:

> Needs Editor on this project. You are on this project as GC. Ask a project admin to change your role.

The API remains the enforcement point throughout. This is legibility, not security.

**Three implementation choices worth stating.** The click is intercepted in the capture phase by a
single document-level listener, so it covers every gated control including ones rendered later —
cheaper and more reliable than annotating each on creation and re-annotating on every panel rebuild.
`aria-disabled` is used rather than `disabled`, because a disabled button leaves the tab order, which
would put the explanation out of reach of exactly the keyboard user most likely to need it. And the
annotation is applied on **focus**, since panels render long after capabilities resolve and a screen
reader needs the state *before* the user acts, not after.

**One flaw the live test caught in this change itself:** the click handler read a JS copy of the
capability state while the CSS read the `<body>` attribute — two sources of truth for one fact, which
would eventually disagree about whether a control is disabled while it still *looks* disabled. Both
now derive from the same attribute.

158 vitest · web build green · verified live: the click is suppressed, the reason is shown, and the
control stays visible.

## v0.3.684 — 5D: the money moves into the model

Cost has always been computed *about* the model and stored *beside* it. That is the thing that stopped
it being 5D — a cost in a sidecar cannot travel with the file, cannot be read by another tool, and
drifts the moment the model is re-exported. IFC is our stated source of truth, and a cost sitting
next to the IFC is not in it.

**The research changed the design before any code was written.** The plan was a bespoke task→element
join table. IFC already carries both bindings natively: `IfcRelAssignsToProcess` (products → task, the
4D link) and `IfcRelAssignsToControl` → `IfcCostItem` (elements → priced line, the 5D link), grouped
by `IfcCostSchedule`. A join table would have put the whole spine outside the model. Checking the
schema first turned a violation of the source-of-truth rule into an implementation of it.

### Cost, written into the IFC and read back out

`IfcCostItem` carries the rate, `IfcRelAssignsToControl` binds the elements it prices — by GlobalId,
inside the file — and `IfcCostSchedule` groups an estimate so one model can hold a bid and a GMP
without them merging. The round trip is asserted through a real re-parse from disk, not the in-memory
file: a cost that cannot be read back is a sidecar with extra steps.

**Every quantity states its basis.** "120 m²" is not a measurement; *"120 m², net area, openings
deducted"* is. Two estimators measuring the same wall gross and net disagree by the openings, and an
unstated basis gives nobody a way to find out which happened — so the basis is written into the model
as the quantity's own description. An **absent** basis defaults to `count` (a lump sum genuinely is
"one of these"); an **empty** one is refused, because that is a caller who tried to state one and
failed, and letting it become `count` would silently turn 57.6 m² into a count of 57.6.

A GlobalId that is not in the model is **reported** while the cost line is still written — dropping it
would make the estimate quietly *cheaper* than the project, the worst possible direction for an error
in a bid.

### Cost rules on the selector spine

The takeoff mapped IFC class → cost code and nothing else, so every wall got one rate regardless of
type, storey, fire rating or phase. `query_dsl` is already **the** element selector here — clash
scopes, view filters, smart views and the rule library all compose on it — so a cost rule is now
**a stored selector plus a rate**, not a new engine. That is what lets a fire-rated podium wall be a
different line from a level-12 partition.

- **Later rules win, and every element records which rule priced it.** Layering is how estimates are
  actually built: price all concrete, then override the podium. A line nobody can trace back to its
  selector is a number taken on faith.
- **An element no rule matched is UNPRICED and reported**, never silently zero — the most expensive
  defect an estimate can carry, because the total still looks like a total.
- **A rate with no quantity is an unknown cost, not a cost of nothing.**

`complete` is false whenever either gap exists, which makes the total explicitly a **floor** rather
than an estimate. Exposed at `POST /projects/{pid}/cost/estimate`.

### Design audit implemented

An external interface audit landed with 18 findings, and its thesis reframes the roadmap: **adoption
is the binding constraint, not capability.** 47% of contractors name getting people to *use* new
technology their biggest challenge; 12% of features carry 80% of daily use. With ~130 modules, about
ten matter to any one person — and which ten is role-dependent. A catalog with favourites treats that
as a browsing problem; it is a routing problem.

Recorded in [design-audit.md](docs/design-audit.md), with the actionable work as the **R24 interface
ring** (14 items) and the 5D follow-ons as **R25** (5 rungs). The landing page and README now carry the
promise the audit named — *making the most powerful thing in AEC feel like the simplest* — and a
"four people, four clocks" section, because a developer checking whether it pencils and a
superintendent logging a punch item in the sun are not one user with different permissions.

Two dependency decisions recorded rather than left open: **`ifclite-geom` declined** (MPL-2.0, off the
approved licence list, and 99.9% geometry agreement is not bit-identical — a determinism guarantee is
worth more than a bounds speed-up), and **`kiwisolver` taken** (Modified BSD-3, on the list, already a
transitive dependency, trivially reversible), which unblocks W10-9 dimensional constraints.

385/385 backend suites green · 669 project routes role-gated · ruff clean.

## v0.3.683 — tags that do not land on each other, and views that admit where they stop

Two marks from the same shop-drawing package, and the same underlying idea: a drawing must not assert
something a reader cannot check.

### R21-TAGS — the difficulty is placement, not wording

`space_tags` already labelled rooms, but rooms are large and far apart. Element tags are the hard
case because doors and windows **cluster**, and two tags sharing a baseline are worse than one tag:
the drawing then carries a number nobody can attribute to an element.

The rule: a tag sits **on** its element, and is displaced to the nearest free slot only when that
position is taken — and displacement is exactly what earns it a leader. A leader on an undisplaced
tag is noise; a displaced tag without one is an unattributable number. When every candidate slot is
occupied the tag is pushed clear rather than dropped, because a silently omitted tag is an element
that merely *looks* untagged.

Placement is deterministic. The same plan tags identically on every run, so a drawing can be diffed
and checked rather than re-read.

### R21-BREAKLINE — a partial view that says so

A detail running to the sheet edge tells a reader nothing about what happens beyond it: the element
might stop there, or continue for thirty metres. The break line is the conventional mark that says
*"this element continues; the drawing does not."* Without it a partial view is indistinguishable from
a complete one — the same class of error as a clash report that never states which pairs it tested.

Two details that matter: the zig is normal to the **run**, not to the page, so a vertical break reads
correctly rather than zig-zagging along its own axis. And a short run still produces a mark instead of
vanishing — a break line that disappeared because the view happened to be narrow would silently turn
a partial view back into an apparently complete one.

383/383 backend suites green.

## v0.3.682 — R21-4D-CLASH: two trades in one place at one time

Hard clash finds two things in one space. Soft clash asks whether a person can reach them. This asks
the third question, and it is the one that reaches site as two foremen arguing in a corridor: **are
two crews scheduled into the same place in the same week?**

Nothing in the model is wrong when this happens. Every element clears every other element. The clash
is entirely in the *schedule*, which is exactly why a geometric clash run cannot find it however
thoroughly it runs.

**What is deliberately not a finding.** Same-trade overlap is planning, not contention — one trade
sequencing its own crews through a zone is how work gets done. Adjacent windows are fine, one crew
leaving as another arrives; a single shared day is not. Location matching ignores case and spacing,
so `L3 North` and `l3  north` are one place rather than two clean ones.

**Unreadable activities are counted, never dropped.** An activity with no location, or missing dates,
or finishing before it starts, is reported as skipped with the reason. An empty or entirely
unreadable schedule reports **not clean** rather than vacuously perfect — the same rule the clash
matrix follows, where a matrix that tested nothing is not "coordinated". A clean result over a
half-readable schedule would overstate what was checked.

**Half of this item is named as unbuilt rather than approximated.** The roadmap describes 4D clash as
two things: space contention, and an install sequenced before the support it hangs from. Only the
first is answerable from the data that exists — `schedule_activity` carries location, trade, dates
and crew size, but **no element GlobalId**, so there is no way to know what a task installs. That
half needs a real task→element binding, not a guess, and the response says so in its own payload
rather than in a comment nobody reads.

Exposed at `GET /projects/{pid}/clash/sequence`, with `min_overlap_days` and `crew_threshold` bars.

382/382 backend suites · 668 project routes all role-gated · ruff clean.

## v0.3.681 — R21-SOFT-CLASH: what a coordination report is allowed to claim

Hard clash asks whether two solids overlap. Soft clash asks the question that actually stops work:
**can a person reach this, service it, or pull it out?** A pump clearing every duct by 5 mm passes
hard clash and cannot be maintained.

Checking the premise narrowed this usefully — `geometric_rules.check_clearance` already existed, so
the gap was not "no soft clash". It was two specific things.

**Clearance is a rules problem, not a geometry one.** The existing primitive takes a distance from
whoever calls it. Every rule now carries the code or manufacturer basis it came from — NEC 110.26(A)(1)
working space, coil-withdrawal clearance, valve reach, pump seal access — so a finding can be argued
with rather than merely asserted. A class with **no stated rule gets no rule**, never a default
distance: a made-up clearance produces confident findings nobody can defend, which is worse than
silence.

**The matrix constrains the claim.** Every discipline pair is `clashes`, `clean`, or **`untested`**,
and the third state is the whole point. Structural-vs-plumbing being clean means nothing if that pair
was never run, so an untested pair is reported as untested and never folded into the clean count.
`coordinated` is true only at full coverage with zero findings; an empty matrix reads as
*uncoordinated* rather than vacuously perfect. Evidence outranks the declaration — a finding proves a
pair was tested — but never the reverse, since a declaration with no findings cannot manufacture
coverage. This is the same rule the scan verification follows: absence of evidence is not evidence of
absence.

**A limitation stated rather than hidden.** These evaluate against axis-aligned bounding boxes, which
carry no facing. A working space is *directional* — NEC wants the space in front of the panel, and
clear space behind it satisfies nothing. With an AABB the check can only ask whether some approach
side is clear, which makes a **PASS weaker than a FAIL**: a violation is real, a clean result is
"not disproved". That belongs next to the number, not in a footnote.

Exposed at `POST /projects/{pid}/clash/matrix` and `GET /projects/{pid}/clash/clearance-rules`.

381/381 backend suites green · 667 project routes all role-gated · ruff clean.

## v0.3.680 — the Revit bridge stops leaving our first non-negotiable to a default

R23-REVIT-EXPORT-CFG. The bridge exported with a bare `IFCExportOptions()` — no configuration at all.
One consequence of that outranks every other.

**GlobalId stability is the platform's first non-negotiable.** Pins, RFIs, clash results, cost lines,
the 4D links and the as-built verification stamp all key off IFC GlobalId. Revit only guarantees
stable GlobalIds across a re-export when **`StoreIFCGUID`** is on: it writes the generated GUID back
onto the element as the `IfcGUID` shared parameter so the next export re-uses it rather than deriving
a fresh one. Under the bare default, a republish could silently re-key the model and detach all of
that from the geometry it described — and nothing would raise an error. The data would simply stop
meaning anything.

The export is now configured, and the button **refuses to publish** if the configuration it is about
to apply would not preserve GlobalIds — checked against the map being applied, not trusted from a
constant that someone might later edit.

**Every option carries a stated reason**, asserted in the test, because a curated set is the point;
a pile of everything available is not. Beyond the GUID option: base quantities and schedules-as-psets
(the takeoff and 5D paths read these rather than re-deriving from geometry), site elevation
(georeferencing is its own non-negotiable), and — quietly important — **whole-model export forced on**.
Defaulting to the active view is how a coordination model ships with three-quarters of the building
missing and nobody notices until a clash meeting.

**A pre-publish audit** now names the conditions that reliably produce IFC nobody can coordinate
against: unplaced or unbounded rooms, in-place families, imported CAD instances, and unresolved Revit
warnings. Each finding says *why* it matters. It reports and never enforces — a partial model is often
exactly what someone means to publish — and it lists **only what it actually found**, because an audit
that also lists its clean checks is one people learn to skip.

The Revit API cannot run in CI, so the option map and the audit are pure functions in a library the
button merely applies. That puts the part most likely to be wrong — which options, spelled how — under
test, including that the guard rejects a missing or false GUID option rather than only passing the
happy case. Both files are IronPython-2.7 clean, which is what pyRevit actually runs.

380 backend suites green.

## v0.3.679 — R23-SHADOW-COST: shadows stop re-rendering for a camera that cannot change them

Two changes that are really one, because each is what makes the other safe.

**The frustum now fits the model.** The sun's shadow camera was a fixed ±140 m box. Across a 2048²
map that is ~13.7 cm per texel — for *every* model, so a house's shadows were quantised to about a
brick course while a small site wasted nearly the whole map on empty ground. It now fits the scene's
own bounds, so a 30 m building gets roughly a centimetre per texel and a 200 m tower still gets a
frustum that contains it. The fit uses the bounding **sphere**, not a per-axis extent: a tighter box
looks better on paper and a low sun shears the model straight out the side of it.

**Per-frame shadow re-rendering is off.** This is the expensive half and almost all of it was wasted:
a directional light's shadow depends on the geometry and the sun, and **not on where the camera is**.
Because the frustum is fitted in world space rather than to the view, orbiting cannot change a single
shadow texel — so the per-frame pass bought nothing. That property is precisely what makes disabling
it safe, which is why the two changes ship together rather than separately.

With automatic updates off, an invalidation is the only thing that refreshes a shadow, so a missed one
is a stale shadow — a worse defect than the cost being saved. There are exactly four inputs that can
change a shadow and all four invalidate: the sun moves, geometry loads, render mode turns on, and the
frustum is refitted.

The frustum maths is a pure function, tested directly: it scales with the model, gives a small
building a finer shadow than the old fixed box did, holds the bounding sphere, clears both model and
sun on the far plane, and never collapses to zero on a degenerate or empty model.

Presentation mode only — the ordinary BIM view casts no shadows and is unaffected.

158 vitest · backend untouched since the 379/379 run at v0.3.678.

## v0.3.678 — the viewer stops doing work nobody asked for

R23 Tier 1: a leak, a per-event waste, two context flags that could only ever be set once, and the
runtime test budget that made all of it checkable. Each defect was verified in the source before being
fixed — one of the four turned out to be misdiagnosed, which is exactly why that step exists.

### An animation loop that could not be stopped

The pin overlay started a **second** permanent `requestAnimationFrame` loop, alongside the engine's
own, with **no cancellation path anywhere** — the class had no `dispose()` at all. It survived viewer
teardown and went on projecting pins for a world nobody was looking at, until the page reloaded.

Fixed with two guards, because either alone is insufficient. `dispose()` covers the ordinary case
where a caller tears the overlay down; a detached-node check covers the case that actually leaked,
where the container is dropped and `dispose()` is never called — the loop then stops **itself**.

### One expensive pass per frame, not one per event

Camera controls emit `update` many times per frame, and a full fragments pass ran on every one. Only
the last before the paint can affect what the user sees, so the rest was strictly wasted. Coalesced to
one pass per animation frame; the visual result is identical. The `rest` event keeps its immediate
full-quality pass, since it fires once when motion stops — precisely when the expensive version earns
its cost.

### Renderer flags, and one that should NOT change

WebGL context attributes are fixed at construction; there is no setter to reach for afterwards, so
passing nothing locked in the defaults permanently. Now set explicitly, and **verified on the live
context**: `powerPreference: "high-performance"` (was unset, which lets a dual-GPU laptop hand a BIM
model to the integrated chip) and `stencil: false` (nothing in the pipeline uses it).

`antialias` deliberately **stays on**. The tempting saving was to drop it because the post-processing
composer resolves 4× MSAA — but that composer is opt-in presentation mode, so the ordinary BIM view
renders straight to this canvas. Turning it off would have put jagged edges on every model, for a
saving that only applies in a mode most users never enter. The reasoning is recorded in the source so
the next reader does not re-derive the wrong answer.

### Resolution that responds to the frame rate

The engine pins the pixel ratio once in its constructor and never revisits it, so a 4K display shades
every pixel of a thirty-storey tower at 2× regardless of how the frame rate is doing. Dropping to 1× is
a 4× cut in fragment work — the cheapest large win available on a heavy model.

The hard part is not measuring, it is **not oscillating**: a governor that flips between two ratios
every few frames looks worse than one that never adjusts, because the resolution visibly pulses. So
there is a dead band between the degrade and recover thresholds, recovery additionally requires a
sustained run of good frames, and a single large hitch is discarded rather than averaged in — a GC
pause is not a rendering problem. Degrade fast, recover slow.

### The budget that makes perf claims checkable

The repo had a bundle-size budget and **zero** runtime assertions, so none of the above could be
verified. Asserting `renderer.info` needs a real WebGL context, which the test environment does not
have — so the scheduling logic was extracted behind an injectable frame clock and tested directly:
a burst of 50 triggers costs exactly one pass, a stopped loop leaves nothing queued, a detached loop
terminates permanently rather than pausing, and the governor never reverses direction under
alternating load.

**One of those assertions was wrong when first written** and the failure was informative: it treated
"visited several ratios" as oscillation, when a monotonic walk downward under sustained pressure is
the correct response. The assertion now checks what pulsing actually is — a reversal of direction.

153 vitest (up from 134) · 379 backend suites · CodeQL 0 open alerts.

## v0.3.677 — R21 Tier 1 closes: sections that annotate, sets that can be checked, drawings that read as drawings

Three items, one sprint, all derived from the same issued shop-drawing package as v0.3.676. With
R21-HATCH, Tier 1 of the ring is complete.

### Sections get an annotation layer — they had none

`_leader_callout` has served plans for a long time, and its boxed label is the right mark there: a
plan tag names an **object**. A section keynote does a different job — it names the **material of a
layer in an assembly** — so the convention is a left-hand text column with an unboxed leader to a dot.
Reusing the plan tag would have produced the wrong drawing, which is why this is a separate mark
rather than a parameter on the existing one.

The keynote text is built from what the model knows: its material, its class, its measured thickness
in millimetres. An unfamiliar class degrades to its own name with the `Ifc` prefix stripped — still
true, rather than a guess that would read as authored.

**The rule that earns it its keep is grouping.** A wall cut at four storeys is **one** keynote, not
four. An annotation layer that repeats itself makes a section *less* readable than no annotation at
all, and rows are pushed apart so labels never collide — a reader who cannot tell which label belongs
to which leader has no annotation either. Linework is unchanged with keynotes on or off.

### A drawing set becomes a graph that can be checked

A wall section carries numbered bubbles pointing at enlarged details elsewhere; each detail carries
its own bubble, title and scale. Nothing linked the two, so a set could not be navigated and — the
part that costs money — could not be **checked**.

Two defects, reported apart because they have different owners and different fixes:

- **dangling** — a callout points at a detail that does not exist. The reader follows the reference
  and finds nothing. This is the one that surfaces in the field.
- **orphan** — a detail nothing points at: drawn, paid for, never reached.

Dangling splits again by reason. An unknown **sheet** is a typo or a sheet that was never issued; a
known sheet missing the detail **number** is almost always a renumber nobody propagated — so the
report names what *is* on that sheet. The inverse form `A-501/12` is **refused rather than guessed**,
because silently inverting detail-over-sheet would corrupt half a set with no signal. Free text that
merely contains a slash is reported as unparseable rather than counted as broken, and sheet numbers
are normalised so `A501` and `A-501` are one sheet — which is what stops the check manufacturing
defects out of punctuation.

Exposed at `GET /projects/{pid}/drawing-set/references`.

### Cut vs projection — the distinction that separates a drawing from a dump

View templates already carried hide / isolate / colour rules on the query spine, so the gap was
narrower and more specific than "graphics overrides": there was no line **weight**, no line pattern,
and no **cut-vs-projection** distinction at all.

That last one is the whole feature. The same element draws two ways in one view — heavy where the view
plane cuts it, light where it is only seen beyond the cut — and that weight difference, not colour, is
how a reader reads depth off a flat sheet. Colour rules alone structurally could not express it.

Weights are millimetres **on the sheet** — the same paper-space reasoning the hatch patterns use, so a
wall reads at one weight at 1:100 and at 1:10. Category defaults keep cut heavier than projection for
every class, structure reads heavier than MEP, and an unfamiliar class lands in the neutral group
rather than the heaviest, so it never shouts.

**An override is a partial**, and that is what makes it composable: a rule naming only a colour leaves
the weights exactly as the object style set them. A full-replacement override would let any colour
rule silently erase the cut/projection difference for everything it touched. Rules may scope
themselves to one side, later rules win, and every template saved before this change still validates
and resolves identically.

Exposed at `GET /projects/{pid}/view-templates/{tid}/graphics`.

### Navigation: two drawers holding two people's tools

A live audit against the running stack — measured, not opined: **170** visible controls with **0**
unlabelled, **0** console errors, and **20/20** first-class Design destinations rendering real content.
Two density defects were real. `Build` had grown to **13** entries of which **7** were project
accounting, so a superintendent looking for today's schedule scanned past the general ledger to find
it; `Model & standards` held **14**, mixing "what are the rules for this project" with "what does the
model actually say". A superintendent and a controller are different people, and one drawer holding
both tools serves neither.

Split into **Build / Money** and **Model & standards / Analyse & check**. Largest group **14 → 7**.
Nothing was removed, and the controller now finds the whole accounting set together instead of
hunting it out of a build list.

379 backend suites green · 134 vitest · CodeQL 0 open alerts.

## v0.3.676 — R21-HATCH: cut material says what it is cut *through*

First item of the R21 ring, which was derived from a real issued shop-drawing package (13 sheets,
1:100 → 1:10) rather than from a description of one. At 1:10 that set separates concrete, reinforced
concrete, steel, masonry and insulation by **pattern**, and a reader identifies the assembly from the
patterns alone.

v0.3.673 filled cut geometry with flat grey tones grouped by IFC class. That is enough to say *"this
is cut"* and structurally unable to say *"cut through what"* — the difference between a set that
reads as a study and one that reads as construction documents. Nine conventional patterns now carry
that distinction: concrete, reinforced concrete, steel, masonry, insulation, timber, earth, glass and
finish.

**The category comes from the model.** `material_by_class()` reads the IFC's own material assignments
(including layer sets and constituent sets) and takes the dominant material per class; a stated class
fallback covers models that carry none. An unfamiliar class hatches as the lightest category, never
as structure. Keyword order is load-bearing and asserted — *reinforced concrete* must beat *concrete*.

**Two properties that took the real work:**

- **Hatch is defined in paper space, not model space.** That is the actual drafting convention —
  spacing belongs to the sheet, so the same wall hatches identically at 1:100 and at 1:10. The
  roadmap entry for this item had originally called for "scale-aware pattern density", which was
  wrong.
- Which forces the rule that earns the feature its keep: **an element thinner than a couple of tiles
  cannot be hatched legibly.** Below that the tile is wider than the element and the result is stripes
  nobody can resolve, so the fill degrades to the solid tone — exactly what a drafter does by hand. In
  the test a 200 mm slab degrades while 400 mm walls hatch.

Only the patterns actually referenced are emitted, so a two-material section does not carry nine
unused `<pattern>` definitions. The linework is identical across hatch / tone / line, so the fill mode
changes weight and never content. `hatch=false` returns the previous flat poché; `annotate=false`
still returns bare linework for CAD hand-off; a misspelled `lod` is still refused rather than
defaulted.

Exposed at `GET /projects/{pid}/drawings/section.svg?hatch=true|false`.

376/376 backend suites green.

## v0.3.675 — five modules were contradicting themselves about their own status

`owner_invoice` offered **Draft / Submitted / Approved / Paid** on its status field while its workflow
had only `draft / submitted / paid`. Anyone who set the field to Approved produced a record whose two
representations of the same fact disagreed — and because every count, filter, board column and report
keys on `workflow_state`, that record silently reported as merely *submitted*. It is the
two-tables-one-format failure: invisible until something downstream is quietly wrong.

An audit found seventeen candidates, and **a rule that fixed all seventeen would have been worse than
none.** Most status-ish selects are deliberately a different vocabulary: `company.dbe_status` is a
DBE/MBE/WBE certification, `project_phase.iso_status` is an ISO 19650 suitability code (S0/S1/S2/A),
`change_event.scope_status` is a determination. Forcing those to equal a workflow would merge
unrelated concepts — a rigorous-looking check built on a false premise. Narrowing to fields literally
named `status` whose options *mostly are* workflow states left **five genuine contradictions**:

- **owner_invoice** — no `approved`, so the AIA G702 certification step (an owner certifies a pay
  application before paying it) was unrepresentable. That is the state a real pay app sits in longest,
  and the one a receivables question is actually about. Also gained `rejected` + a revise path.
- **permit** — no `under_review` (the state that carries schedule risk) and no `expired` (a compliance
  failure).
- **prequalification** — no `invited`, so the pipeline had no beginning; `invited` is now the initial
  state, because a prequalification starts when the invitation goes out, not when the sub responds.
- **value_engineering** — no `under_review`.
- **document** — `superseded` was offered but unreachable. It is a genuinely different end from
  `void`: superseded was replaced, void was withdrawn.

New `test_status_workflow_parity` locks the narrow invariant and also checks, by transitive closure
from the initial state, that **every declared state is reachable** — a state nothing can enter is the
same bug wearing different clothes. That check earned itself immediately by catching this change's own
mistake: `invited` was added to prequalification while `initial` still said `submitted`.

The pre-existing direct `submitted → paid` transition on owner invoices is kept deliberately. Some
owners do pay without a separate certification, and removing it would strand every in-flight record.

`test_procurement_gate` was approving a prequalification that had never been submitted — possible only
because of the missing state. Its fixtures now walk the real pipeline; one of them also claimed to
test "submitted, not approved" while sitting in a different state entirely.

375/375 backend suites green.

## v0.3.674 — D2 routed egress: the travel-distance check was measuring the wrong thing

`geometric_rules.check_escape_distance` reported **straight-line** distance to the nearest exit, and
said so plainly. That candour is what makes it worth fixing rather than tuning: IBC 1017 limits travel
distance measured *along the path of egress travel*, and a straight line ignores every wall between a
space and its exit. It is therefore always shorter than the real walk, which means the error runs in
the **unsafe direction** — it passes plans that do not comply. Reading the output carefully cannot
recover that, because the number itself is the wrong measurement.

New `egress_route.py` routes over the actual floor plate: rasterise at the cut height, mark the cells
anything the cut passes through, run a multi-source Dijkstra outward from every exit, and read each
space's distance off the resulting field — which doubles as the route polyline to draw. Deterministic
and offline, no new dependencies. Eight-connected with a √2 diagonal cost, so an open-floor run is not
overstated by ~41% the way a four-connected grid would be.

- `GET /projects/{pid}/egress/routes` — per space: routed distance, the straight-line distance the old
  check used, and their **detour ratio**, so the understatement is visible per space rather than
  asserted in general.
- `GET /projects/{pid}/egress/plan.svg` — the life-safety plan: walls, exits, and every space's actual
  path, coloured by outcome. A reviewer opens this drawing to find the failures, so a compliant route
  in green beside an over-limit one in red makes the finding visible at a glance; one uniform colour
  would hide the finding inside the evidence for it.

Judgement calls the engine makes explicit:

- **No route at all** is reported as unreachable, never folded in with the merely too-long. It is the
  worst finding a plan can carry and deserves its own outcome.
- **No exterior door marked** → the analysis refuses outright rather than routing to an arbitrary
  door, which would produce confident and meaningless distances.
- **Grid resolution is stated** on the drawing and in the payload rather than implied away — a 0.5 m
  grid cannot resolve a 0.4 m gap, and hiding that would repeat the original mistake in a new place.
  A grid too fine to compute is refused with its cell count instead of attempted.
- `max_travel_m` is a **parameter**, defaulting to 61 m (200 ft, IBC 1017.2 sprinklered Business),
  because the limit is occupancy- and sprinkler-dependent and a hard-coded one would be wrong for most
  buildings that used it.

374/374 backend suites green.

## v0.3.673 — sections you can issue, and a route to LOD 500 that doesn't need a thousand clicks

**W10-5 + C6 — the section becomes a drawing.** `section_svg` produced bare linework: every edge the
same weight, no levels, no grid, no dimensions. That output is *correct* and unusable — a section
exists to communicate vertical relationships, and the only way to get a floor-to-floor height out of
it was to measure the screen.

Sections now carry **poché** on cut material, grouped by what the material *is* (structure heavier
than enclosure heavier than openings) — the one distinction pure linework cannot make, because every
edge looks equally solid. The tone follows LOD: solid while the drawing is about mass, stepped back as
the linework sharpens, absent at `line`. The linework is identical across all three, so LOD changes
weight and never content, and a misspelled LOD is refused rather than defaulted to a plausible-looking
weight. Plus **C6 reference-line datums** running the full width past the drawing, grid bubbles from
the in-plane axis, and the **floor-to-floor dimension chain** with an overall height.

**LOD 500 — the assertion existed and the reader ignored it.** `verify_asbuilt` has stamped
`Massing_AsBuilt` into the IFC since the G1 work and `asbuilt_summary` counted it, but the LOD
assessment read only LOIN facets. So a model with every element field-verified still reported "LOD
400, capped". The evidence was in the file and nothing looked at it.

Two things from the BIMForum specification are now encoded, both commonly got wrong:

- **LOD 500 is not "more detail than 400".** It is a field-verified as-built condition, so an
  information-complete element nobody looked at stops at 400 while a *thin* verified one reaches 500.
  An element measured outside tolerance is **not** promoted — it has been verified as wrong, which is
  a punch item rather than a handover.
- **Accuracy must be stated by means other than the LOD number.** A bare VERIFIED flag asserts
  nothing about how closely the model matches the building, and is reported as an incomplete
  assertion rather than counted as a pass.

`GET /projects/{pid}/lod/handover-readiness` returns the gap as a **work list**: every short element
with a reason and the next action, grouped by discipline. A percentage cannot be worked — "62% ready"
does not say which 38% or why.

**Scan → LOD 500.** Verifying element by element is why LOD 500 stays aspirational on any real model.
The existing `/scan/deviation` compares a cloud against every model vertex at once and returns one
number: it can say how close a building is to its model, never which wall is wrong, so it cannot
verify anything. `per_element_deviation` runs the query the other way — nearest **scan** point to each
element's own surface — which makes the result attributable and, more importantly, makes an element
the scanner never saw come back **uncovered with no verdict** instead of quietly passing. Absence of
points is not evidence of correctness.

`POST /projects/{pid}/scan/verify-lod500` turns that into three outcomes: within tolerance → stamped
*with its measured deviation*, so the assertion states an accuracy; outside tolerance → returned as a
finding and deliberately not stamped; uncovered → needs another scan position. `apply=false` shows
exactly what a scan would assert before it touches the model.

Sampling improvement found on the way: vertex-only sampling measures a box's eight **corners** — the
worst case, and exactly where a scan sheet is thinnest. Element sampling now includes triangle
centroids, which put sample points in the middle of each face where a scan actually lands.

373/373 backend suites green.

## v0.3.672 — the option-scoring refusal note stops carrying an exception's text

Third and correct pass at CodeQL `py/stack-trace-exposure` on the option scorer. The previous two
releases hardened the wrong path: the alert's reported location was
`return option_score.score_options(...)` — the *return of the engine result* — and it was read as
though it pointed at the 400 handler. The 400 was never involved.

The real flow is that `_evaluate` catches the takeoff's `OptionError` and puts `str(e)` into
`takeoff.note`, which then travels out in the **response body** attached to every scored option.

`OptionError` now carries a short `code` naming which lever was rejected (`structure`, `wwr`), and
`option_score.TAKEOFF_REFUSALS` maps that code to client-facing literals. The note is selected from
that table, so nothing derived from an exception object reaches a response. A test asserts the note
is always a table value, that codes and table stay in step, and that a caller's raw token is never
echoed back to them.

The v0.3.670 typed exception and v0.3.671 message constant are kept — both are correct hardening of
the 400 path — but neither could have closed this alert.

370/370 backend suites green.

## v0.3.671 — the option-scoring 400 stops deriving its text from a caught exception

Follow-up to v0.3.670. The typed `OptionError` shipped there did not clear CodeQL
`py/stack-trace-exposure`: the scanner re-scanned and re-raised the alert on the new line, because a
caught exception is tainted regardless of its class. Typing it told the reader something it could not
tell the analyzer.

The fix is to look at what actually escapes. Every `OptionError` the takeoff raises is caught
per-option inside `score_options` and turned into `basis="none"`, so exactly **one** refusal ever
reaches the API. That message is now the module constant `option_score.EMPTY_OPTIONS`, which the two
handlers answer with after their own precondition check; a test asserts the constant equals what the
engine raises so the two cannot drift. Every other `ValueError` returns a fixed literal. No response
text on that path derives from an exception object.

370/370 backend suites green.

## v0.3.670 — FAMILY-COMPLETE: the shelf is now checked against what it takes to *build*

Six batches of catalog content took the family shelf from **41 packs / 281 families / 2,370 types**
to **57 / 426 / 2,796** — foundations, fire protection and alarm, electrical distribution and
lighting, mechanical fittings and hydronics, architectural openings and envelope layers, interiors,
conveying and site utilities. The content lives in the external catalog and is generated, never
scraped, so the licensing story stays clean.

The more useful change is the one that made the content necessary. "How many families do we have"
is not the question a modeller cares about; "can I build a hospital with this" is. New
`family_packs.coverage()` answers the second by checking the installed shelf against the IFC **type
classes** each building system needs — structure, envelope, openings, circulation, HVAC, plumbing,
electrical, fire and site for every building, plus what distinguishes a hospital from a warehouse —
and it is exposed at `GET /families/coverage`.

**Writing that check immediately found a hole 413 families had hidden: not one `IfcFootingType`
anywhere.** The catalog carried W-shapes, HSS, tees, channels, precast, timber, rebar and
post-tensioning, and no foundations at all — so every one of the six target typologies was
unbuildable, while the shelf looked enormous. A new `structural-foundations` pack fixes it (spread,
strip, combined and mat footings, grade beams, pile caps, bored/driven/helical piles, piers,
slab-on-grade, foundation walls, below-grade waterproofing), and residential, commercial, hotel,
hospital, industrial and airport now all clear every system.

Coverage is deliberately all-or-nothing per system. An HVAC package with terminals and no duct is
not half an HVAC package — it is one that cannot be issued — so a short system names its missing
classes rather than reporting a comfortable percentage, and an unknown typology is refused instead of
answered with an empty report that would read as a pass.

**Also in this release**

- **Shelf isolation.** `AEC_FAMILY_SHELF` relocates the shelf directory. Two tests that both mutated
  the shipped `families/external/` raced under the parallel runner — the loser read a half-written
  manifest and the failure looked like a bug in the reader rather than shared mutable state in the
  source tree.
- **Option-scoring errors no longer leak internals.** `score_options` grew a deep call path, so an
  incidental `ValueError` (a bad float cast, a library complaint) could reach the client verbatim
  through the 400 handler. Exactly one refusal escapes the engine, so it is now a module constant
  (`option_score.EMPTY_OPTIONS`) the router answers with directly — nothing derived from a caught
  exception reaches a response, and a test keeps the constant and the engine in step. Everything else
  returns a fixed message. (CodeQL `py/stack-trace-exposure`, medium.)

370 backend suites green.

## v0.3.669 — GEN-SCORE depth: carbon from quantities, and an honest word when the bases differ

The option scorer priced each massing variant at one blended conceptual $/SF and rated its carbon
from a whole-building kgCO₂e/m² benchmark by building type. Both are defensible at concept stage, and
both share a weakness: **a benchmark cannot see geometry.** Two options with the same GFA and the
same building type get an identical carbon intensity even when one is a squat plate and the other a
slender tower carrying twice the façade per square metre — which is precisely the trade-off the
scorer exists to expose.

New `option_takeoff.py` derives elemental quantities from the massing itself (perimeter × height for
façade, not GFA alone), prices them element by element, and runs the same quantities through the
platform's **own** EPD factor table (`carbon.FACTORS` — composed on, not copied). Structural system
and window-to-wall ratio are levers; every rate is overridable. In the test, a tower and a plate with
identical GFA and type now differ in both carbon and cost, as they should.

**What it refuses to do:**

- **Elements with no EPD factor are named, not folded in at zero.** MEP, finishes and core carry no
  factor in the table; counting them as carbon-free would flatter every option equally and silently.
  `covered_elements` and `uncovered_elements` are reported, because a bottom-up number over 60% of a
  building is not the same claim as one over 95%.
- **A takeoff is refused rather than faked** when the massing carries no usable geometry —
  `basis: "none"`, and the caller falls back to the benchmark *and says so*.
- **An unpriced element is named**, not dropped into a total that looks complete.

**The model is deliberately hybrid — and the existing test is what proved it had to be.** Replacing
the benchmark wholesale broke `test_option_score`, and the failure was right: the takeoff sees only
*geometry*, so a warehouse and a hospital on the same envelope came out with identical carbon. That
is false, and the difference between them lives in MEP and fit-out — **precisely the elements the
takeoff already reports as uncovered.** So the shell comes from quantities and the programme-driven
remainder from the type benchmark (`FITOUT_CARBON_SHARE`, one named constant rather than a number
buried in a formula). Both axes now reach the score; either source alone loses one.

**The honesty gate.** A hybrid figure and a pure typology benchmark are still different claims.
Ranking options whose carbon came from different bases compares unlike things, and the carbon weight
is then doing work it hasn't earned. `score_options` reports `carbon_basis`, and a mixed set is
flagged — *"1 of 2 option(s) are quantity-derived, the rest are typology benchmarks… not
like-for-like"* — rather than being quietly averaged over. The fallback option is flagged, never
dropped.

**FAMILY-COMPLETE batch 1 — plumbing.** The clarified bar is that a user can model a *complete*
building across six typologies and every discipline, fabricating geometry where no source exists. The
shelf's 270 families were a **completeness floor** — one family per system, which proves a typology
*can* be plumbed but cannot model a real one. Measured, the thinnest disciplines were plumbing
(20 types), electrical (32) and fire (14): you cannot plumb, power or sprinkler a project from 66
types.

Plumbing is now **27 families / 110 types** (16/20 before), pushed to the content repo and rebuilt
into the shelf: copper Type L and Schedule 40 PVC and no-hub cast iron at real ASTM ODs and wall
thicknesses, plus WCs, lavatories, urinals, showers, sinks, drinking fountains with ADA variants and
drainage/supply fixture units, water heaters, booster pumps, RPZ backflow, drains, cleanouts and
valves. Six families were **deliberately not added** — the base catalog already carries them at
equivalent depth, and forking one system across two families is worse than a thinner catalog.

The generator's own schema validation caught two invalid `PredefinedType` enums mid-write
(`WATERHEATER` is not legal on `IfcElectricApplianceType`; `CHECKVALVE` is not legal on
`IfcValveType`) and a guessed Uniclass code was removed rather than shipped unverified.

The full plan — six batches, thinnest-first, targeting the content plan's own ~800 families / ~7,500
types — is the new top item on the roadmap.

## v0.3.668 — WFE-3 per-project workflows, and the family shelf actually stocked

**WFE-3 — per-project workflow overrides.** Module workflows ship as `module.json` defaults:
sensible for most jobs, wrong for some. One owner wants a second approval before a change order is
executed; another runs submittals without a consultant review. Until now that meant editing the
shipped module, which changes it for every project. `workflow_config.py` stores a per-project
transition list (a blob, no migration), and `GET/PUT/DELETE /projects/{pid}/workflow/{key}` manages
it.

**The validation is the feature.** A workflow is not just a schema — records are *sitting in* its
states right now. An override that removes the last way out of an occupied state doesn't fail
loudly; it silently strands every record already there, and a stranded record looks exactly like one
nobody has got to yet, so it goes unnoticed for as long as anyone is willing to wait. So a save that
would strand live records is **refused**, naming the state and the count (`1 in 'answered'`) rather
than filing a warning. A state that is genuinely terminal in the shipped workflow is correctly not
treated as stranding.

Both halves read the same effective workflow — the actions the UI offers and the transitions the
engine honours — so there is no button that 409s. An override may rewire which of a module's
**declared** states connect; it can never invent new ones. Unreachable states are reported rather
than silently ignored, and admin-gated saves are audited.

**The family shelf is stocked.** `fetch_families.py` still can't fetch (no release published
upstream), so the 40 packs were built from the catalog and installed: **270 families · 2,334 types ·
6.1 MB**, importing cleanly with every sampled type measurable.

They **ship with the repo**: this is first-party content, so a fresh clone gets a stocked shelf with
no build or fetch step, and `fetch_families.py` becomes a refresh path rather than a prerequisite.
`.gitignore` tracks `external/*.ifc` and the manifest alongside the generated core library.

One honest gap surfaced by real content: the upstream manifest declares **no licence**, so the shelf
reports `unlicensed: 40` rather than assuming the README's CC0. Absent is not the same as
permissive, and an empty column is not something a reader scanning a shelf will notice.

## v0.3.667 — W10-2: a family can be a real section, not a box

v0.3.662 taught the platform to *read* fourteen parameterised IFC4 profiles, so imported manufacturer
content stopped reporting `dims: null`. The catalog could still only *make* rectangles — so anything
authored in-app was a box regardless of what it represented, and authored content was structurally
poorer than imported content.

New `aec_data/family_shapes.py` closes that. `create_type(..., shape={...})` builds a real
parameterised section, swept or revolved, optionally with boolean cut-outs:

```
{"profile": "ishape", "overall_width": 0.2, "overall_depth": 0.4,
 "web_thickness": 0.01, "flange_thickness": 0.015, "length": 4.0}
```

The result is **native IFC** — the section stays *parameters*, so it round-trips, measures and
schedules exactly like imported content instead of degrading to a mesh. Meshes are deliberately out
of scope: a mesh cannot be resized, scheduled by section, or read back as dimensions, so a family
needing one belongs in an imported pack.

**The write table is asserted symmetric with the read table.** If one grows without the other,
authored content silently stops being measurable — the exact defect class fixed in v0.3.662. That
assertion earned its place immediately: it caught `IfcAsymmetricIShapeProfileDef` as readable but not
writable, now added (bounded by the *wider* flange, matching the reader).

**Three things caught during the build rather than after:**

- **`depth` collides.** It is a *profile* parameter on the T/U/C/Z/L sections. Had the sweep also
  been called `depth`, a 0.2 m-deep tee swept 4 m would have been built **0.2 m long** — geometry
  that parses and is simply wrong. The sweep is `length`, and the error message names the trap.
- **Hand-mapped attribute names are a guessing game.** `round_radius` looked right; IFC4 calls it
  `RoundingRadius`, and ifcopenshell only objects at create time. The test now validates every
  generated attribute name against the real IFC4 schema, so the whole table is checked at once
  instead of one failure at a time.
- **A boolean result is a CSG item, not a SweptSolid.** Mislabelling the `RepresentationType` makes
  conformance checkers and some viewers drop the geometry entirely.

Degenerate parameters — zero web thickness, negative radius, missing, non-numeric — are refused
rather than written as shapes that render as nothing and take off as zero. `area()` is offered only
where it is exact; the sections needing approximation return `None` instead of a plausible guess.

## v0.3.666 — REL-3: modules.py didn't need dependency injection, it needed a layering cut

`modules.py` is imported by **114 files** — the most-depended-on module in the codebase, and the one
carried longest on the decomposition backlog. It sat there because the plan said it needed a
**dependency-injection seam** before its read/feed leaves could come out.

Checking that premise before building to it: the read and workflow-evaluation functions call
**nothing else in the module**. The dependency graph was already acyclic, so no seam was required —
only a cut at the right place. `modules_query.py` now holds the self-contained base (the pure
workflow evaluators `_transition` / `available_actions` / `court_party`, and the read queries
`list_records` / `count_records` / `state_counts` / `state_counts_all` / `active_records` /
`_json_text`), leaving `modules.py` the write path: create, revise, transition, attach, comment,
notify.

`modules.py` re-exports every moved name, exactly as it already does for `modules_registry` and
`modules_search`, so **none of the 114 importers change**. `modules.py` 975 → 859 lines. Full suite
green — which for a change of this shape is the whole verification, since the risk is a missing
re-export rather than a logic error.

The `_pg_document` / `_pg_tsquery` / `search_filter` re-exports are now marked `noqa: F401` with a
note: the linter reads them as dead because nothing in `modules.py` calls them, but they are public
surface — `test_fts_index` and other engines reach them as `modules._pg_document`. Deleting them
would have been a lint-clean way to break the FTS index-vs-query drift check.

## v0.3.665 — COST-SPINE: is it the same scope at every stage?

`margin/by-costcode` totals budget vs committed vs actual vs billed per code. It answers *what is the
margin on 03-3000*. It structurally cannot answer the question underneath: **is 03-3000 the same
scope at every stage** — because a code that appears at one stage and not the next still produces a
row that looks fine. Scope re-coded between the estimate and the buyout, or spend booked against a
code nobody budgeted, hides in exactly that seam.

New `cost_spine.py` + `GET /projects/{pid}/cost-spine` reports **presence, not just amounts**:

- **Which stages each code reaches**, and where its chain *first* breaks — rendered as a stage strip
  so a gap reads at a glance instead of being inferred from four numbers.
- **Spend without budget** — named outright rather than left to surface as a large negative variance.
- **Budget with nothing behind it** — fine early, a re-coding smell late.
- **Invoices exceeding their commitment.**
- **Records carrying no cost code at all** — the worst case, and the one a per-code report can never
  show: that spend appears in no row anywhere. Surfaced separately, with its own total.
- **Codes used on records but missing from the project's register** (free-typed, so two spellings of
  one code silently become two scopes), and register codes nobody ever used.

The headline is `traceability_pct` — the share of committed+actual money sitting on a budgeted code —
and it is stated **on the margin card itself**, because that is the number inheriting the coverage. A
buyout margin computed over 55%-traceable spend is a different claim from one computed over 100%, and
the reader shouldn't have to work that out on another screen. An empty project refuses to report a
percentage at all rather than showing a comfortable 0% or 100%. Flagged rows carry the resolve-action
that fixes them, filtered to the code.

## v0.3.664 — UX-POLISH complete: actions that resolve, and 108 registers that are no longer empty

**UX-DEMO — the empty-state problem, measured then closed.** The hand-written relation-chain seeder
threads ~24 modules — the ones the dashboards and rollups read. **132 modules ship**, so 108
registers rendered nothing: a customer clicking through the nav hit blank screen after blank screen
even though the engine behind each one works. Hand-authoring 108 more registers would be filler, so
`demo_seed.py` generates records **from each module's own field definitions** — `module.json` is
already the single source of truth, so a module added tomorrow gets demo content for free and nothing
drifts. `seed_demo.py --all-modules` fills every register the chains didn't, leaving the
hand-authored related records untouched where they exist.

What it deliberately does **not** do:

- **It never invents a reference, upload or signature.** Two modules have a *required* reference, so
  they are refused outright rather than seeded with a fabricated id — a dangling link renders as
  broken, not as content. `needs_references()` names them so the caller seeds the parent first.
  130 of 132 generate; the test asserts the refused set stays under 20% or the fix isn't landing.
- **It doesn't look suspiciously complete.** Optional fields are filled about two thirds of the time,
  because a grid with every cell populated reads as fake.
- **It isn't random.** Values are hash-seeded per module + row, so two runs are byte-identical and a
  captured demo snapshot stays stable — while distinct rows genuinely differ. Dates straddle today,
  so "overdue" and "upcoming" filters both have members instead of one side always being empty.

**UX-ACT phase-2 — diagnostics that name geometry.** A rule violation points at *elements*, which the
three existing action kinds couldn't express. New `select_elements` kind: a failing rule now hands
back the button that shows the offending elements, and the viewer gained `selectByGuids` to receive
it. The payload is a button, not a data feed — capped at 200 GUIDs, carrying the **true** total and
an explicit `truncated`, so a client can never select a subset while looking like it selected
everything. The scope selector rides along so it can re-evaluate against the live model rather than a
snapshot. The schedule optioneer likewise pairs its caveats with the button that resolves them — an
empty result says which register to go populate; an unmatched critical-path trade opens the schedule
filtered to it. The `navigate` action kind, previously reserved, is now wired.

## v0.3.663 — Path resolution by enumeration; the chip vocabulary reaches the money cards

**Security — four HIGH `py/path-injection` alerts closed** (CodeQL, on v0.3.662's new
`family_packs.py`). The original guards were sound — a name carrying any separator, parent
reference, drive or UNC prefix was rejected, and the resolved path was re-checked against the shelf
root — but the path was still *built* by joining caller input onto a directory. It is now
**selected out of the directory's own listing** instead: the server enumerates `*.ifc` and the
caller's string is only ever compared against what it found. That inverts the trust rather than
fencing it, so no encoding trick can steer the result, and the symlink containment check still runs
on the resolved target. Alerts cleared; the traversal tests are unchanged and still pass.

**UX-POLISH, first slice.**

- **UX-KPI** — the one-line narrative band now sits above the register tiles on the **developer** and
  **design** homes, matching the PX executive band. Deterministic template text, never an LLM; a
  register with no records is absent from the sentence rather than reported as a zero.
- **UX-CHIPS — the vocabulary actually had to learn the vocabulary.** Rolling chips onto the module
  record grid meant measuring what states they'd see: the platform's modules define **112 distinct
  workflow states**, and `toneFor` recognised **30**. Three quarters of every register would have
  rendered the same grey — the chip system looking uniform precisely where it exists to
  differentiate. `toneFor` now carries the real vocabulary as exact-match sets (phrase patterns
  still handle free text), with a deliberate distinction the old version could not make: **neutral
  means "left the live set"**, not "unrecognised". A voided or superseded drawing is withdrawn from
  the set, not an error, so it reads grey; a rejected or missed one reads red. `chips.test.ts` pins
  all 112 states, so adding a module state without a tone now fails the suite.
- **UX-CHIPS rollout** — chips replace hand-rolled badges at the **module record grid** (the widest
  site: every register, including the drawing lifecycle DRAW-STATUS), the **action-items feed** and
  the **brief feed**.
- **UX-CHIPS** — the shared vocabulary reaches the **selections money card**: a net-delta chip that
  knows an overage is bad and a credit is good on a cost line, priced/approved status chips, and a
  count narrative. It also now states the **unpriced remainder explicitly** — a rollup over
  half-priced selections is not the same number as a finished one, and the reader should not have to
  subtract to notice.

## v0.3.662 — Real family content: four geometry defects, and a shelf you can actually import from

Analyzed the external `massing-families` content library (40 discipline packs · 270 families · 2,334
types · CC0, generated parametrically) and made the platform able to hold it. Its own README claimed
"no platform changes needed" — that turned out to be nearly true for *ingest* and not true at all for
what happens to the content afterwards.

**Four defects, each verified against real content before being fixed.** They share one root
assumption: that a type's geometry is always the box our own builder makes. That held while every
family was a box. Real content ends it.

1. **Type sizes read as `null` for any real section.** `_type_dims` only understood
   `IfcRectangleProfileDef`, so every imported W-shape, tube and pipe reported no size — measured:
   **403 of 403** types in the steel-W pack, 52 of 91 in ductwork. Nothing downstream could schedule
   or take off imported content. Now `_profile_bounds()` measures 13 parameterised IFC4 profiles
   plus the bounding box of an `IfcArbitraryClosedProfileDef` polyline (much third-party content
   sweeps arbitrary profiles). After: 400/400 steel, 91/91 ductwork, 47/47 piping.
2. **Resizing *appended* a box instead of replacing.** `geometry.assign_representation` appends, and
   the resize path fell through to it whenever no editable box was found — so the type kept its
   original section **and** gained a box drawn through it. It rendered both, and every take-off
   counted both. `edit_type_params` now clears the representation maps first, and **reports the
   section it discarded** (`geometry_replaced`) rather than letting a catalog section quietly become
   a box.
3. **Hollow sections were silently reshaped as boxes.** `is_a("IfcRectangleProfileDef")` is true for
   `IfcRectangleHollowProfileDef`, so the box path grabbed HSS tubes: it rewrote the outer
   dimensions, kept the wall thickness, and left the type carrying a catalog name that no longer
   described it. A real `HSS24X12X3/4` became a 500×500 tube still called `HSS24X12X3/4` — a section
   in no steel catalog, presented as a standard one. A null is honest; that was a plausible wrong
   answer. The box path now matches the exact class only.
4. **Variant names were hardcoded metric.** The type name is what appears in schedules, the picker
   and drawings, and `Single door 0.9144×0.0508×2.1336 m` is not a size anyone can act on. Names now
   follow the project's `IfcUnitAssignment` — `Door 3'-0" × 0'-2" × 7'-0"` in an imperial job, mm in
   a millimetre job. Geometry is untouched; only the label changes.

**A shelf you can import from.** The platform had both halves of a content story and no bridge:
`GET /families/library` *listed* `services/data/families/external/`, and `/families/import` imported
an IFC the caller **uploaded** — so a pack already sitting on the server had to be downloaded and
uploaded back to be used. New `aec_data/family_packs.py` + `POST /projects/{pid}/families/import-pack`
close that. Packs resolve by **name only** (separators, parent references and non-`.ifc` suffixes are
refused, and the resolved path is re-checked against the shelf root so a symlink cannot walk out
either), carry a size ceiling, and record a **sha256 in the audit trail** so an import can be tied to
exact content later. `GET /families/library` gains a `shelf` block with manifest-derived metadata —
discipline, family/type counts, licence — because forty opaque filenames is not a picker. A pack the
manifest does not describe is still listed and importable, marked `described: false`, claiming
nothing. And when a manifest declares more types than actually arrive, the response says so instead
of smoothing it over.

**`scripts/fetch_families.py`** fetches packs onto the shelf, verifying each sha256 against the
release manifest — which detects a corrupted download, not a compromised release; both come from the
same place. Build/ops-time only, never a runtime dependency. No release is published yet, so it
currently exits with the local-build instructions instead of failing obscurely.

*The upstream repo shipped a patch for defects 1, 2 and 4. It was reviewed rather than applied:
defect 3 is not in it, and its profile table misses arbitrary profiles, trapeziums, and the wider
flange of an asymmetric I. The implementation here is ours, with the reproductions kept as tests.*

## v0.3.661 — Crew shifts follow the critical path; the conformance gauntlet gets teeth

The last two roadmap carry-overs, and two real defects the second one found in our own code.

**Schedule optioneering — crew shifts follow the CPM (SPRINT B phase-4b).** Crew doubling used to be
offered on the *slowest* trades, which is a proxy for the bottleneck, not the bottleneck. A second
crew on a trade that has float buys no days and still costs the premium. `POST /schedule/optioneer`
now takes `critical_path` — either a list of trade names or `"auto"`, which derives it from the
project's own activity network — and draws the crew-doubling candidates from it. Off-path trades are
excluded from the grid **and named** in `crew_selection.off_path_excluded`. A supplied path that
matches no trade, or a project with no schedule at all, falls back to the slowest-trade heuristic and
reports that it did, rather than optimising an imagined bottleneck.

**NORM-VALID — implementer-agreement depth.** The conformance gauntlet now checks the rules a
consuming tool actually assumes:

- **MVD declaration** — parses `ViewDefinition[…]` out of `FILE_DESCRIPTION`. A file that declares
  none is telling the receiving tool nothing about which subset of IFC to expect; an unrecognised
  view is named rather than swallowed.
- **Unit completeness + unambiguity** — "has units" is not "has the units a take-off needs". Missing
  length / area / volume / plane-angle assignments are named individually, and a unit type assigned
  *twice* fails: a consumer has no way to know which one the values are in.
- **Relationship cardinality** — a relationship with a null relating side or an empty related set
  parses, validates against EXPRESS, and means nothing. Plus the single-parent agreements: at most one
  spatial container per element, one whole per part, one voided element per opening, no part both
  aggregated and directly contained (it is taken off twice), and an unbroken spatial-aggregation
  chain.

**Two defects the new checks found, fixed here:**

- The header lane read `model.wrapped_data.header`, which is a *method* on the C++ wrapper — attribute
  access on it raised into a bare `except`, so **every header check has been silently reporting
  "empty" regardless of the file**. Now reads `model.header`, and the checks are live.
- Our own generated models assigned no **PLANEANGLEUNIT** and shipped an empty `FILE_NAME` /
  `FILE_DESCRIPTION`. `massing.stamp_conformance()` now stamps the plane-angle unit (IFC angles are
  radians by definition, but a file that never says so leaves every `IfcPlaneAngleMeasure` consumer
  guessing), the `DesignTransferView` MVD an authoring model actually satisfies, and a real name +
  timestamp. Applied to all three generators.

**Also:** `schedule_cpm.compute()` emitted record ids in `critical_path` but refused to *accept* an id
as a predecessor token — its own output was not valid input. Ids now resolve, with explicit
`ref`/`wbs` still winning on collision.

## v0.3.660 — R20 Tier 3 complete: the IC memo, hold-vs-sell, and the clause playbook

**The 🏙 R20 ring is complete.** Three closing engines, same discipline as the rest.

- **CRE-ICMEMO** — the Investment Committee Memo joins the Report Center, assembled from the
  *governed* scenario (published beats approved beats latest saved). Its one rule: **it refuses to
  render the deal sections when a required input is missing** — basis, NOI, debt, equity, exit cap
  — listing exactly what is absent and what to do about it, rather than filling the template with
  a plausible number. A memo that quietly supplies a cap rate nobody chose is worse than one that
  says the cap rate is missing. Renders the ask, the returns, and the governance trail (who
  approved it, with what note) to PDF/Excel like any preset.
- **CRE-HOLDSELL** (`hold_sell.py` + `POST /projects/{pid}/hold-sell`) — hold versus sell on one
  engine instead of two spreadsheets. Sell-now is today's reversion net of costs and payoff; each
  hold year is measured as **incremental** cash flows against the proceeds declined today, because
  holding costs you the cheque you didn't take. **Cap drift is an explicit input** — "hold"
  silently bets on the exit cap, and a bet nobody wrote down is the one that loses money. Returns
  the breakeven hold period, or states plainly that nothing inside the horizon clears the hurdle.
  Reuses the shipped reversion/returns primitives so it can't disagree with the pro forma.
- **CRE-CLAUSE** (`clause_playbook.py` + `GET/PUT /contracts/playbook`, `POST /contracts/review`) —
  the firm's contract standard as data rather than as a partner's memory: per contract type, each
  clause with its accept / negotiate / **refuse** position, where **a clause with no red line is
  rejected as not a standard**. A review records each clause's position into a deviation register
  — and every playbook clause the review never addressed comes back **`not_reviewed`**, never
  assumed acceptable, because an unread clause is an open risk. A ten-clause starter standard for
  ground-up work ships with it. Reading the contract stays a human job; this makes two reviews
  comparable. Not legal advice.
- `test_cre_tier3` (suite 363). **R20 Tiers 1–3 are all complete.**

## v0.3.659 — R20 Tier 2 complete: covenants + deal-room authority + supply + the committee gate

Four engines about **governance over deal facts** — and the one rule they share: absent evidence
never reads as a pass.

- **CRE-COVENANT** (`covenants.py` + `POST /projects/{pid}/loan/covenants`). Timing alone can
  breach a loan, so the two fields that cause missed filings are first-class: **`day_basis`**
  (calendar vs business days, with holidays) and **`clock_start`** (the lender's notice date vs
  our receipt of it). Every due date shows its anchor, basis, count and each non-working day it
  skipped, so a reviewer can re-derive it by hand — and when the two clock readings give
  *different* dates, both are returned with a warning to confirm the basis with counsel. Financial
  covenants report **untested** when no actual was supplied (an untested covenant is not a passing
  one), and a breach inside an open cure window is reported separately from one past it.
- **CRE-AUTHORITY** (`deal_authority.py` + `GET/PUT /projects/{pid}/deal-room/authority`).
  Authority is declared **per fact type**, not per file: one authoritative rent roll, operating
  statement, tax bill and so on, each with its date, its own freshness threshold, and its
  supersedes chain. Two authoritative documents for one fact type are refused, as is any undated
  entry — a document with no date cannot be judged fresh or stale. Required fact types that are
  missing, stale, or superseded-but-still-active **block** downstream analysis rather than being
  annotated after the fact.
- **CRE-SUPPLY** (`supply_pipeline.py` + `POST /projects/{pid}/supply/competitive`). Competitive
  supply weighted by **recorded evidence** rather than status label: a recorded construction loan
  counts fully, an issued permit at 85%, a rendering at 5% — and rumored supply is reported
  separately, never blended into the certain count. Filters to the subject's delivery-and-lease-up
  window and product type, listing every exclusion with its reason so a thin competitive set is
  visible rather than implied. Feeds the shipped Lot Supply Index, returning the weighted and raw
  months-of-supply side by side because the gap between them is the argument.
- **CRE-DECISION-GATE** (`decision_gate.py` + `POST /projects/{pid}/decision-gate`). Seven
  deterministic gates over the evidence the other engines produce — citation coverage, comp source
  tiers, the T-12 tie-out, the rent-roll scrub, the authority table, required exhibits, and a
  **named** sign-off ("the team" is not a person). **A gate whose evidence was not supplied is
  `unknown`, and unknown blocks.** The response carries the actions to take, not just a list of
  what failed.
- Clients: `loanCovenants` · `dealAuthority`/`saveDealAuthority` · `competitiveSupply` ·
  `decisionGate`. `test_cre_governance` (suite 362). **R20 Tier 2 is complete.**

## v0.3.658 — R20 Tier 1 complete: comp tiers + T-12 tie-out gate + rent-roll scrub

Three engines that all say the same thing in different ways: **a number is only as good as what
it rests on, and missing inputs stop the work rather than quietly passing it.**

- **CRE-COMP-TIER** (`comp_tier.py` + `GET /projects/{pid}/comps/tiered`). The `comparable`
  module's free-text `source` becomes a ranked hierarchy — recorded sale > party-verified >
  vendor-confirmed > vendor estimate > listing/asking > broker package > unattributed. Two things
  follow: comps describing the **same address are resolved by tier rather than averaged** (the
  county deed's $210/sf wins over the offering package's $250/sf, and the overruled figure stays
  visible beside it), and **every derived band reports the weakest tier it rests on** — a median
  carried by one asking price can no longer read like one carried by six recorded sales. An
  unrecognized source lands in the *weakest* tier, never an optimistic middle.
- **CRE-T12** (`t12.py` + `POST /projects/{pid}/t12/normalize`). Maps a trailing-twelve to a house
  **operating** chart of accounts (deliberately separate from the shipped construction chart, which
  cannot express vacancy loss or a management fee), classifying each line recurring / one-time /
  capital / reclass. **The tie-out is a gate, not a report:** if source and mapped totals disagree
  the response is `stopped: true` with the reconciling items and `adjusted_noi: null` — because an
  adjusted NOI on top of a lossy mapping is exactly how a reclass disappears. Past the gate:
  one-time expense added back, capital kept below the NOI line, a last-three-months-annualized
  run-rate view, and the standard owner-operated tells (absent management fee, no payroll,
  below-market R&M, missing taxes or insurance) raised as **questions with the numbers behind
  them** — never applied silently.
- **CRE-RRSCRUB** (`rent_scrub.py` + `POST /projects/{pid}/rent-roll/scrub`). Seven cross-checks
  between the rent roll and the income statement: scheduled rent vs gross potential rent at the
  industry 5% diligence threshold, occupied units with no lease on file, vacant units still
  carrying a receivable, monotonically rising arrears, bad debt rising against flat occupancy,
  stated rent vs executed terms, and expired leases still counted active. **A check that lacks its
  inputs returns `applicable: false` with what it needed — never a pass** — because a clean report
  built on absent data launders missing information into confidence.
- All three use the same active-lease filter as the rent roll, so no two surfaces can describe
  different portfolios. Clients: `tieredComps` · `normalizeT12` · `rentRollScrub`.
  `test_cre_deal_desk` (suite 361). **R20 Tier 1 is complete.**

## v0.3.657 — R20: net effective rent (CRE-NER)

The first R20 item, and it needed no new data — the `lease` module already stored the concessions.

- **`net_effective.py` + `GET /projects/{pid}/rent-roll/net-effective`.** Face rent is what a
  broker quotes; **net effective rent** is what underwriting and agency lenders use, because
  concessions come out of gross potential rent before effective gross income. Both standard forms
  are reported because they answer different questions: **straight-line** (total base rent over the
  term less landlord costs, ÷ term) and **discounted** (the level annual rent whose present value
  equals the actual net cash-flow stream) — the latter prices *when* the free rent and the TI
  cheque land, not just how big they are. A $50/sf TI on a five-year deal costs materially more
  than the straight-line average admits.
- Escalation steps on the **annual anniversary** the way a lease actually reads, not as a smooth
  monthly curve. **Leasing commission is never invented** — it is included only when the caller
  supplies a rate, and the result says whether it was. Leases missing the fields the maths needs
  are **named in `skipped`**, never silently dropped.
- The roll-up uses the **same active-lease filter as the rent roll**, so face GPR and net-effective
  GPR always describe the same set of leases, and reports how many records it excluded — two
  surfaces disagreeing about which leases count is worse than either number being slightly off.
- `test_net_effective` ties the textbook case exactly ($1,200/mo with one free month → $13,200/yr
  straight-line) and proves the draft-lease consistency end to end. Suite 360.

## v0.3.656 — security: postcss >= 8.5.18 (transitive)

- Root npm `overrides` pins **postcss to >= 8.5.18** (was 8.5.15 via Vite), clearing the HIGH
  advisory for path traversal in previous-source-map auto-loading. Build-time toolchain only;
  build and vitest re-verified on the bumped version.

## v0.3.655 — ENERGY phase 1: the gbXML / EnergyPlus envelope export + the 🏙 R20 CRE ring

The first BIG-TICKET track opens — and it opens with the half that needed no solver binaries.

- **ENERGY phase 1** (`aec_data/energy_export.py`). The IFC becomes a **thermal model**:
  - **Zones** from `IfcSpace` (area/volume from the base quantities); a model with no spaces
    exports a single whole-building zone and says which it did, rather than exporting nothing.
  - **Surfaces** — one per envelope element. Energy models use **zero-thickness** surfaces, so a
    wall's mid-plane face is the correct representation, not an approximation; each surface is
    tagged `exact` when the element's mesh provably **is** its bounding box (authored rectangular
    extrusions — checked vertex by vertex, not assumed) or `bbox` when the geometry is irregular,
    so a consumer knows exactly how far to trust each polygon.
  - **Constructions** from the model's own `IfcMaterialLayerSet` assemblies, with each layer's
    conductivity **back-derived from the R the platform already computed** — the export reproduces
    our number instead of doing a second, silently-different catalog lookup.
  - Two writers over one intermediate — **gbXML** (Campus/Building/Space/Surface + Construction/
    Layer/Material) and **EnergyPlus IDF** (Building/Zone/Material/Construction/
    BuildingSurface:Detailed) — so they can never disagree about the building; both
    byte-deterministic. The IDF states its own scope ("no HVAC, schedules or loads") in the file.
  - `GET /projects/{pid}/energy/model` + `/energy/export.gbxml` + `/energy/export.idf`; clients
    `energyModel` / `energyExportUrl`. `test_energy_export` (suite 359). **Phase 2** — running the
    solver binaries through the durable job queue — remains the gated half.
- **The 🏙 R20 CRE deal-desk ring** joins the roadmap from a review of two external field guides on
  AI-assisted CRE and development workflows. Most of their content is document-reading technique,
  which stays our documented non-goal; what was taken is the deterministic discipline underneath —
  net effective rent, comp source tiers, T-12 normalization with a hard tie-out gate, rent-roll
  reconciliation, a loan covenant/reporting register with day-count and clock-start fields, the
  deal-room authority table, evidence-tiered competitive supply, and a pre-committee readiness
  gate. Items already shipping are listed explicitly so nothing gets rebuilt.

## v0.3.654 — Sprint 6: version diff values + model transforms + BCF 3.0

The roadmap's long-standing carry-overs, closed.

- **VERSION-COMPARE — per-property values.** A model diff now reports `FireRating: 2HR → 1HR`, not
  just "FireRating changed". A bounded value snapshot rides fingerprint position [7] — capped at
  20k elements × 40 sorted keys × 64 characters, containers summarized — so a large model's version
  blob can't balloon, and when a cap bites the diff says `values_truncated` rather than implying it
  has everything. Comparison of "did this element change" now reads only the meaning-bearing
  positions, so the first snapshot after the upgrade doesn't report every element as modified.
  `test_version_values`.
- **IFCPATCH-LIB — three transform recipes** (`ifcpatch_lib.py`), all GUID-stable:
  - **`rebase_origin`** — the georeferencing-correct answer to a model a million metres from the
    origin. Shifts every *root* placement (plus the storey datums, so level and geometry never
    disagree) and pushes the same offset **into the `IfcMapConversion`**, so the real-world survey
    position of every element is unchanged; when a file carries no map conversion it says so
    plainly instead of implying the georeference followed.
  - **`convert_length_unit`** — rewrites the project length unit *and* rescales the length / area /
    volume data, so a 3 m storey becomes 3000 mm at the same real elevation. The attribute
    whitelist is explicit and the report names every entity type it touched, so the conversion is
    auditable rather than a black box. Idempotent; an unknown unit is refused.
  - **`split_by_storey`** + `GET /model/split-plan` — the per-storey slice plan (which GUIDs land
    in each slice, plus the unassigned remainder) that pairs with the subset export. *Merging is
    deliberately not added: federation — discipline models plus federated clash — already covers
    multi-model work without destroying model identity.* `test_ifcpatch_transforms`.
- **BCF-API-SRV — the BCF 3.0 surface + attachments over the API.** `/bcf/versions` now advertises
  2.1 **and** 3.0, and a full `/bcf/3.0/…` surface serves topics in the newer shape:
  `server_assigned_id` (the server's own stable handle), a role-derived **`authorization`** block
  so an integration's UI matches what the server will actually permit, and `document_references`.
  **Documents ride the API end to end** — a coordinator's tool uploads a markup PDF straight onto a
  topic, lists documents project-wide, and downloads the bytes, all project-scoped (a guid from
  another project 404s), reusing the shipped attachment storage and filename hardening. The 2.1
  surface is untouched. `test_bcf3`.
- Clients: `modelSplitPlan`. Authoring matrix: 91 recipes / 15 categories. Suite 358.

## v0.3.653 — Sprint 5: round-trip fidelity + wall joins + composite families + shared parameters

INTEROP-RT closes the R19 ring; AUTH-CONSTRAINTS ③ and FAMILY-DEPTH ③④ close the R18 ring.

- **INTEROP-RT — the round-trip fidelity gauntlet** (`aec_data/roundtrip.py`). Serialize → fresh
  parse → compare every product/type on GUID · class · name · containment · related type · full
  occurrence psets; unmatched reported BOTH ways, one `fidelity_ok` verdict. Served at
  `GET /projects/{pid}/model/roundtrip`, suite-gated by `test_roundtrip`, and CI-usable as
  **`massing roundtrip <ifc> --gate`** (exit 1 on any loss). The R19 enterprise track is complete.
- **AUTH-CONSTRAINTS ③ — wall-join resolution** (`aec_data/wall_joins.py`). `find` classifies
  every L join (coincident endpoints) and T join (endpoint on another wall's axis) per storey;
  the **`resolve_wall_joins` recipe** butt-joins them deterministically — the longer wall runs
  through (extended past an L corner by half the stub's thickness to close the outside corner),
  the stub trims back by half the through wall's thickness, geometry edits touch only the profile
  length + placement slide (GUID-stable), world-anchored openings stay put to the millimetre, and
  resolution is **idempotent** (a second pass finds nothing). `GET /model/wall-joins` +
  `test_wall_joins`. The R18 AUTH-CONSTRAINTS item is fully closed.
- **FAMILY-DEPTH ③ — composite (nested) families.** `families.COMPOSITES` — workstation
  (desk + chair), meeting setup (table + 6 chairs), bedroom set — placed through the SAME
  `add_family` recipe: parts at catalog offsets, aggregated under one `IfcElementAssembly`,
  part types deduping through the normal `ensure_type` machinery, round-trip-lossless.
  `test_composite_family`.
- **FAMILY-DEPTH ④ — shared parameters** (`shared_params.py`). A validated project registry
  (`GET/PUT /projects/{pid}/shared-params`: unique letter-first names, `text|number|bool`, 1–20
  IFC classes each, ≤100 definitions, atomic saves) whose parameters **are schedule columns**:
  the computed door/window/room schedules append registered columns scoped by `applies_to`
  (values from each element's psets, blank when unset) — and therefore SCHED-CALC formulas reach
  them by normalized name. Values write through the normal edit recipes; the registry defines
  meaning, the edit pipeline owns mutation. `test_shared_params`.
- Clients: `wallJoins` · `modelRoundtrip` · `sharedParams`/`saveSharedParams`. Authoring matrix:
  89 recipes / 15 categories (regenerated). Suite 355.

## v0.3.652 — UX-POLISH: the shared chip vocabulary + KPI narrative + docs refresh

- **UX-CHIPS** (`ui/chips.ts`): one status/delta chip component for every list and money card —
  `statusChip` (tone auto-mapped from the workflow word, optional timestamp), `deltaChip`
  (sign-colored, `goodWhenNegative` flips for cost metrics, tabular numerals), `kpiHeader` +
  `countNarrative`. Pure escaped-string builders; 4 vitest cases (suite 132). First consumers:
  the 📒 margin card's over-budget/over-committed flags (header + per-row) now render as chips.
- **UX-KPI**: the project-executive band closes with a one-line plain narrative — "2 milestones
  late, 5 due soon, …" — a template string over numbers the card already holds, never an LLM;
  "On plan — no exceptions to chase" when clean.
- **Docs refresh**: the README's rolling highlights gain the v0.3.615–651 era (enterprise &
  finance-platform readiness + authoring-parity depth); roadmap status counters brought current.

## v0.3.651 — R18 tail: level-move re-derivation + instance parameter overrides

The two deepest open authoring-parity slices (AUTH-CONSTRAINTS ② · FAMILY-DEPTH ②).

- **Level moves carry their elements** (`set_storey_elevation`, AUTH-CONSTRAINTS ②). Editing a
  storey's elevation now re-derives every CONTAINED element's placement by Δz — and hosted
  openings/fills that did not ride along automatically (absolute placements) are detected via a
  before/after snapshot and shifted too, so a level move never strands geometry. Opt out with
  `move_elements: false` (the old attribute-only behaviour), in which case the v0.3.637
  constraints checker flags exactly the stranded elements. `test_level_move` proves both
  directions (wall + hosted door land at the new elevation to the millimetre; the opt-out wall is
  flagged by GUID).
- **Instance-level parameter overrides, first-class** (`aec_data/instance_props.py`,
  FAMILY-DEPTH ②). `GET /projects/{pid}/model/element/{guid}/effective-props` returns the merged
  properties-panel view: every pset/property with its **effective value**, its **source**
  (`instance` | `type`), the shadowed type value where an occurrence override is in play, and the
  override count. The **`reset_prop_to_type` recipe** removes the occurrence property so the
  type's value shows through (refused when there's no type backing — that would delete data, not
  reset it; the last property removed also drops the empty pset shell). `elementEffectiveProps`
  client; `test_instance_props` (suite 351).

## v0.3.650 — R19 Sprint 2: the finance-platform pack (FIN-GOV · FIN-CALC · FIN-INGEST · FIN-PORTFOLIO)

Trust before breadth: governance, golden-tested math, reconciliation, and investor reporting on
the development-finance pillar.

- **FIN-GOV — financial governance** (`fin_gov.py`). **Scenario review workflow**: every saved
  pro-forma scenario runs draft → in-review → approved → published (`POST
  /proforma/scenarios/{sid}/review`; reject/reopen walk back with a note; who/when/why persisted —
  Alembic `c6dcec8fe81d`). Approved/published assumptions are **immutable in place** (409 — clone a
  revision); draft edits return (and audit-log) the exact **changed assumption paths**
  (`debt.ltc`). **Locked reporting periods**: `PUT /projects/{pid}/finance/lock` closes the books
  through a month — owner-invoice / sub-invoice / direct-cost / journal-batch mutations dated into
  a closed month are refused **409 in the modules engine**, so every path (routes, imports,
  internal flows) hits the same gate; records can't be edited, deleted, or re-dated across the
  line; adjustments post into open periods. `test_fin_gov`.
- **FIN-CALC — calculation trust.** The **residual-land-value inverse solver**
  (`proforma/residual.py` + `POST /proforma/residual-land`): the land price that hits a target
  equity-IRR / project-IRR / equity-multiple / yield-on-cost / profit-margin, by deterministic
  bisection over the same forward solve every other number comes from — an unreachable target says
  "not achievable even at $0 land" instead of inventing a number. **Golden reference tests**
  (`test_fin_calc`): closed-form XIRR fixtures, the hand-built NPV annuity, EM/YoC ratios, the
  to-the-dollar waterfall reconciliation, and invert-then-forward-solve consistency. The precision
  policy is documented in [calculation-precision.md](docs/engineering/calculation-precision.md).
- **FIN-INGEST — actuals reconciliation + lineage** (`fin_ingest.py`).
  `GET /projects/{pid}/finance/reconcile`: budget ↔ actuals matched **both ways** on the cost-code
  spine (matched / budget-only / actuals-only, never netted) + uncoded actual records surfaced
  with their refs, highest value first. Import batches are audit-logged with source filename +
  counts (`GET /finance/imports`); the period lock reaches imports automatically — backdated rows
  land in the batch's error list, not the ledger. `test_fin_ingest`.
- **FIN-PORTFOLIO — investor reporting.** `GET /proforma/portfolio/compare`: the latest scenario
  per project side-by-side (returns + governance state) with a best/worst spread per metric,
  member-scoped under RBAC. The **Investor Pack** joins the Report Center (`investor_pack`):
  basis scenario (published preferred) with return KPIs, Sources & Uses, every saved scenario
  with its review state, capital summary, and the equity cash-flow chart — PDF/Excel like every
  preset. `test_fin_portfolio`.
- Clients: `reviewScenario` · `financeLock`/`setFinanceLock` · `residualLand` ·
  `financeReconcile` · `financeImports` · `portfolioCompare`. Suite 349.

## v0.3.649 — R19 Sprint 1: the enterprise-readiness pack (SEC-THREAT · COMPLY-SOC2 · OPS-OBS · ENG-STD)

The security/compliance/operations/engineering program layer, grounded in the shipped controls —
plus two gaps closed in-sprint.

- **[docs/security/threat-model.md](docs/security/threat-model.md)** — a STRIDE-organized threat
  model over the real surfaces (auth/session · RBAC/tenancy · upload+conversion · public share
  tokens · API abuse · secrets · audit · supply chain/CI), a verification matrix mapping every
  control to its evidence (test gates, workflow runs), and a prioritized honest gap backlog.
- **[docs/compliance/soc2-readiness.md](docs/compliance/soc2-readiness.md)** — the
  Trust-Services-Criteria control matrix for enterprise diligence: each criterion → the shipped
  control → its evidence source (CC1–CC8, Availability, Confidentiality), with the auditor-facing
  gap list and a sequencing recommendation. Readiness, not an audit.
- **[docs/ops/runbooks.md](docs/ops/runbooks.md)** — eight incident runbooks (API down · Postgres ·
  migration failure · storage loss · bad deploy · Redis · license bridge · stuck conversion),
  reference SLOs with alert thresholds, the correlation-ID triage spine (request id → error log →
  trace), and the postmortem format.
- **[docs/engineering/backend-standards.md](docs/engineering/backend-standards.md)** +
  **[web-standards.md](docs/engineering/web-standards.md)** — the actual conventions codified:
  engine-leaf/adapter/one-gate, the GUID rule, the Alembic + Postgres-IMMUTABLE discipline, money/
  determinism rules, the test-runner contract, the `esc()` discipline, the client.ts seam, gates.
- **Password deny-list (threat-model G-5, closed):** `auth.weak_password_reason()` — the
  breach-corpus head (case + trailing-punctuation normalized), a distinct-character floor, and
  password≠username — enforced at register, self-service change, admin create/reset, and
  token reset, each with a named 400 reason. `test_password_policy` (suite 345).
- **SBOM artifact (threat-model G-2, closed):** the Dependency-scan workflow now publishes an
  SPDX SBOM artifact per run.

## v0.3.648 — security: js-yaml ≥ 4.3.0 (transitive)

- Root npm `overrides` pins **js-yaml to ≥ 4.3.0** (was 4.2.0 via the OpenAPI type-generation
  toolchain), clearing the HIGH advisory for quadratic CPU consumption on YAML merge-key chains.
  Dev-time toolchain only; no runtime surface.

## v0.3.647 — the 🏢 R19 ring: enterprise & finance-platform readiness (roadmap)

An external planning pack (07-24) analyzed and folded into the roadmap; the shipped waves archived.

- **The 🏢 R19 ring** joins the roadmap in two tracks. **Enterprise:** SEC-THREAT (threat model +
  app-sec verification gap analysis) · COMPLY-SOC2 (Trust-Services-Criteria control matrix over the
  shipped controls) · OPS-OBS (incident runbooks + SLOs) · ENG-STD (engineering standards codified
  from the actual conventions) · INTEROP-RT (the automated IFC round-trip fidelity gauntlet).
  **Finance:** FIN-GOV (approval workflow + locked reporting periods on financial records) ·
  FIN-CALC (residual-land-value solver + golden reference tests + a documented precision policy) ·
  FIN-PORTFOLIO (investor/lender reporting pack + portfolio scenario compare) · FIN-INGEST
  (actuals reconciliation + lineage stamps).
- **Analysis verdict recorded honestly:** the pack's authoring gap analysis was already done (R18);
  its interop program is largely shipped (IDS/bSDD/COBie/BCF 3.0/IFC4.3); most of its finance
  engines already ship (the pure pro-forma pipeline, XIRR/NPV/EM/YoC, sensitivity, Monte Carlo,
  waterfalls, WIP/draws/reserve, portfolio benchmarking) — what's new is the governance +
  program-formalization layer. Competitor-matrix deliverables not adopted (standing doc directive).
- **Roadmap cleanup:** the 🧭 R17 backend wave, the 🏛 R18 completed items, and the 10/10 NOW list
  moved to [roadmap-completed.md](docs/roadmap-completed.md); the live roadmap now carries open
  items only, re-prioritized with a fresh sprint-ordered NOW list.

## v0.3.646 — FAMILY-DEPTH ①: named type catalogs (R18)

One family, many cataloged sizes — "Desk 1600 × 800" instead of raw dims.

- **`families.TYPE_CATALOGS`** — curated named sizes for the common families (desk 1400/1600/1800,
  table 4/6/8-seat, bed single/queen/king, wardrobe, kitchen-counter runs, bathtub, shower);
  `catalog_types(key)` lists them (un-cataloged families fall back to their base dims as
  *Standard*), `catalog_dims(key, name)` resolves case-insensitively with the available names in
  the error message.
- **The `add_family` recipe takes `type_name`** — a named catalog size resolves through the SAME
  `ensure_type` variant machinery (placing "1600 × 800" twice dedupes to one IfcTypeProduct;
  a second size adds another; explicit `dims` still win). The place route passes it through, and
  **`GET /families/{key}/types`** serves the catalog.
- `test_type_catalogs` (suite 344). FAMILY-DEPTH remaining: instance parameter overrides · nested
  families · shared parameters driving schedules/tags · cross-project library versioning.

## v0.3.645 — VIEW-TEMPLATES: reusable layered view presets (R18)

The graphics-override layer desktop suites call a view template — on the QUERY-DSL spine we already own.

- **`view_templates.py`** — a template is a **class visibility matrix** (`hide_classes`), an optional
  **isolate scope** (QUERY-DSL), and stacked **color rules** (selector → `#rrggbb`, later rules win).
  Validated atomically on save (selectors parse, colors are hex, caps hold, empty templates rejected);
  stored per project like smart views — no migration.
- **Deterministic resolution** — `GET /view-templates/{tid}/resolve` maps the template + the loaded
  model to sorted visible/hidden GUID sets + the color map: same template + same model = the same
  answer, byte-identical (asserted), so the viewer and the drawing generators consume ONE result
  instead of re-deriving visibility ad hoc.
- Distinct from smart views by design: a smart view is one selector + one mode; a template is the
  reusable *composition* — matrix + scope + n color layers.
- `viewTemplates`/`saveViewTemplates`/`resolveViewTemplate` client methods; `test_view_templates`
  (suite 343). The R18 ring is now down to FAMILY-DEPTH + AUTH-CONSTRAINTS ②③.

## v0.3.644 — ADR-LITE adopted + SDK-VERSIONING verified already shipped (R18)

Two more R18 items resolve — one by a page of process, one by reading the code before building.

- **ADR-LITE**: `docs/adr/` adopted — one page per load-bearing decision (context / decision /
  consequences), sequential numbering, supersede-never-rewrite, **no retroactive backfill** (the
  CHANGELOG already carries the history). [ADR-0001](docs/adr/0001-adopt-adr-lite.md) records the
  adoption itself.
- **SDK-VERSIONING**: verified **already shipped** in the plugin registry — the manifest's
  `api_version` MAJOR must match the host's `PLUGIN_API_VERSION`, incompatible plugins are refused
  with a clear reason (never loaded against a different recipe contract), recipes are namespaced,
  collisions refused. The strategy doc's requirement was already the implementation; recorded, not
  rebuilt.
- Docs-only release; the R18 ring now has ONE engineering item open (FAMILY-DEPTH) plus
  VIEW-TEMPLATES and AUTH-CONSTRAINTS ②③.

## v0.3.643 — the headless `massing` CLI + the `check` CI gate (the last NOW item)

Author, edit, and GATE a model from a terminal or a CI runner — no server, no browser.

- **`python -m aec_data.cli`** grows from an export tool into the full headless surface:
  `new` (a blank authoring model — levels + ground reference, name/storeys/height/size),
  `run` (apply any GUID-stable edit recipe with JSON params → `<stem>_edited.ifc`; unknown recipes
  and bad JSON exit 2 with the known-recipe list on stderr), and
  **`check`** — the constraint/QA report (broken hosts, dangling fills, out-of-extent inserts,
  containment/level issues). Report-only by default; **`--gate` exits 1 on errors** — a firm can gate
  every model commit in their own CI; `--json` emits the machine-readable report.
- The pre-existing export commands (index/qto/spaces/cobie/schedule) survive the subparser rewrite
  unchanged. Scope honesty: server-side macros stay server-side (they're storage-backed); the CLI
  runs the recipe primitives macros compose from.
- `test_cli` (suite 342) exercises new→run→check→gate end-to-end on real IFC files. Closes the last
  NOW-list item — **the reconciled NOW list (v0.3.634) is now 10/10 shipped.**

## v0.3.642 — MEP-EQUIP ties: submittals · budget lines · the curated starter (R16 remainder closed)

The equipment schedule stops being a report and starts driving the buyout thread.

- **`POST /model/equipment/to-submittals`** — one *product-data* submittal per scheduled equipment
  type (spec section derived from the discipline's MasterFormat division), **idempotent by title**:
  re-running after a model change only adds the new types.
- **`GET /model/equipment/budget-lines`** — the schedule as budget-suggestion rows (qty EA per type),
  priced from the project's **own price-observation ledger** where it has seen the type (median unit
  price), else unpriced for a manual allowance. Read-only; nothing is written.
- **`GET /model/equipment/starter-requirements`** — the curated spec-check starter: the properties an
  engineer expects every unit of the common classes to carry before buyout (chiller capacity/condenser
  type, pump flow/power, transformer power/voltage, …). `"*"` = presence-required — `spec_conflicts`
  now treats it as "any non-empty value passes", so the starter reports gaps as *missing* without
  ever fabricating conflicts.
- `test_equipment` extended (presence semantics, idempotent re-run, ledger-median pricing 1000+1200 →
  1100/EA). Closes the R16 MEP-EQUIP carried remainder.

## v0.3.641 — SPACE-UTIL benchmarking: capacity across the portfolio (R16 remainder closed)

- **`GET /benchmarks/space-utilization`** — capacity/utilization across your **modelled** projects,
  computed from each project's own IFC (spaces are geometry, not records): space count, total area,
  capacity at the given m²/person standard, and **m² per space vs the portfolio median**. Scoped to
  the caller's projects; bounded to 12 models per call (newest first, `open_model`-cached; skips and
  unreadable models are counted, never silent); the standard clamps to [1, 100].
- `spaceUtilBenchmarks` client method; `test_space_util` extended (portfolio median, clamping,
  model-less projects simply aren't rows). Closes the last R16 SPACE-UTIL carried remainder — and
  with it, **every R16 carried remainder except MEP-EQUIP ties and the RECIPE-MACROS CLI**.

## v0.3.640 — SEC-SUPPLY: the MCP tool-poisoning self-audit + non-gating CI step

Tool poisoning — hostile instructions smuggled into MCP tool descriptions that agents read as trusted
context — audited on OUR OWN catalog, so a bad merge or a compromised generator surfaces before it ships.

- **`supply_chain.mcp_tool_audit()`** — scans every MCP tool's name, description AND per-parameter
  schema descriptions for the known smuggling shapes: invisible unicode, injection phrasing
  ("ignore previous instructions", system-prompt references, "do not tell the user", tag/comment
  smuggling), long base64 runs, and outbound URLs (a tool description has no business linking out).
  The real 18-tool catalog scans clean; five hostile fixtures each trip their detector in the test.
- **`python -m aec_api.supply_chain mcp-audit`** — non-gating by default (report + exit 0); `--gate`
  fails only on high-severity findings.
- **CI**: a report-only step in the Dependency-scan workflow writes the audit to the run summary
  (`continue-on-error` — surfaces, never blocks). Closes the last R16 SEC-SUPPLY carried remainder.

## v0.3.639 — RULE-PACK FOLD: per-IfcSpace checks join the rule library (R18/R16 remainder)

One rule spine for elements AND spaces — without faking geometry as property selectors.

- Space checks are **geometric** (footprints, envelopes, shared walls) — expressing them as
  property-index selectors would create silently-never-matching rules (a false "pass", the exact trap
  the security checklist warns about). So the **space rule pack** keeps its honest shape —
  `dimensional` (min room dim / area / ceiling height, global or by type) · `daylight` (types that
  must sit on the envelope) · `wet_wall` (types that must share a wall with a wet space) — each with
  its own severity, stored beside the rule library.
- **`GET/PUT /projects/{pid}/rules/space-pack`** — validated atomically (severities, numeric ranges
  [0, 1000], type-list caps; a bad pack 422s without writing).
- **`/rules/run` folds it in**: with a source IFC, the adjacency engine runs the pack and the results
  join the same rollup as `space:*` rows (scoped/passed/failed/fail_guids/detail) — the by-severity
  counts include space failures. Without a model, the run notes the skip instead of failing.
- Closes BOTH carried R16 remainders at once (TESTFIT-ADJ "fold the dimensional pack into
  rule_library" + DESIGN-METRICS "per-IfcSpace code-check rule sets"). `test_rule_library` extended
  with a real authored-spaces model through the folded run.

## v0.3.638 — MODEL-PUBLISH: the review gate over model versions (R18 #4)

Draft → in-review → approved, on the publish history the platform already keeps.

- **Review status on every model version** (`review_status` + who/when/note; Alembic `49640af8f9d8`,
  existing snapshots backfill to `draft` = unreviewed): `POST /versions/{v}/review` with
  `submit | approve | reject` — reject returns the snapshot to draft and keeps the reviewer's note;
  illegal transitions 409, unknown versions 404; every action lands in the audit log. The model file
  pointer is never touched — this is the QA record teams gate issuance on ("issue drawings only from
  approved versions").
- **Scope honesty**: the R18 item's other half — element-level optimistic concurrency — was found
  ALREADY SHIPPED (the COLLAB-1 `base_source` 409 + per-project mutex on `/edit` and `/edit/batch`),
  and rollback is the existing edit-undo path. This release adds the missing review workflow only.
- `reviewModelVersion` client method; review status rides `GET /versions`; `test_versions` walks the
  full submit→reject→submit→approve path. Drift guard clean.

## v0.3.637 — AUTH-CONSTRAINTS ①: the broken-host / illegal-placement checker (R18 #3)

The biggest R18 gap opens: IFC already *persists* the constraint graph (RelVoids/RelFills hosts,
storey containment) — this slice validates it, so a deleted host surfaces instead of dangling.

- **`aec_data/constraints.py`** — seven checks, attribute + placement based, no OCC:
  **errors** — `orphan_opening` (its host wall was deleted), `orphan_fill` (a door/window whose
  opening is gone), `insert_outside_host` (an opening placed beyond its wall's extent, or taller
  than it — measured in the wall's own frame via inverse placement);
  **warnings** — `uncontained_element` (on no storey, not hosted, not in an assembly),
  `level_mismatch` (contained on one storey, sitting at another's elevation, ±1 m grace);
  **info** — `unfilled_opening`, `unhosted_insert` (legitimate cases surfaced, not judged).
  Unmeasurable placements are skipped and counted — never guessed.
- **`GET /projects/{pid}/model/constraints`** + `modelConstraints` client method; issues sort
  errors → warnings → info and carry `{kind, severity, guid, name, detail}` — BCF/rule-composable.
- `test_constraints` breaks a healthy model five ways and asserts each kind + severity (suite 341).

## v0.3.636 — OPS-DR: backup retention + the disaster-recovery runbook (R18 #2)

The procurement-checklist item: backups that age out, and a restore that is *proven*, not presumed.

- **[docs/ops-dr.md](docs/ops-dr.md)** — the runbook: what must survive (Postgres · MinIO · uploaded
  IFCs · operator secrets, which stay OUT of archives by design), backup/restore usage, **RPO/RTO**
  framing, the **quarterly restore drill** (restore into a scratch stack + a concrete verification
  checklist — "a backup is a rumor until restored"), the retention & deletion posture, and a short
  failure playbook (bad deploy / lost volume / lost host / suspected corruption).
- **`scripts/backup.sh` retention**: prunes archives beyond the newest `BACKUP_KEEP` (default 14) —
  a daily cron now self-manages to two weeks of dailies instead of filling the disk.
- The backup/restore scripts themselves already shipped (v0.3.x, `scripts/`); this closes the R18
  OPS-DR quick win with the runbook + retention that were missing.

## v0.3.635 — SCHED-CALC: calculated fields in schedules + module records (R18 #1)

Formula columns without a scripting runtime — the first R18 quick win.

- **`calc_fields.py`** — a deterministic expression evaluator built on a strict Python-AST whitelist:
  arithmetic, string concat via `+`, comparisons, conditionals, and a small function set
  (`round/min/max/abs/len/num/text`). **No attribute access, no subscripts, no lambdas/comprehensions,
  no `**`, no keyword args**, with expression-length and node-count caps — a stored formula can
  compute, never reach. Field names are normalized column titles / data keys (``Width (m)`` →
  ``width_m``); numeric-looking strings auto-coerce so arithmetic works over text tables; a bad ROW
  yields an empty cell while a bad EXPRESSION 422s at definition time.
- **`POST /drawings/schedules/calc`** — the computed door/window/room schedules extended with
  validated formula columns (`round(num(width_m) * num(height_m), 2)` → an Area m² column).
- **`POST /modules/{key}/calc`** — formulas over module-record field maps (+ ref/title/state):
  `amount * 1.0825`, status-conditional flags; capped at 12 calcs / 2 000 records.
- `drawingSchedulesCalc` + `moduleCalc` client methods; `test_calc_fields` (suite 340) covers the
  evaluator, both routes, and eight hostile-expression rejections.

## v0.3.634 — roadmap: the 🏛 R18 authoring-platform parity ring + a fresh NOW list

Analyzed an external strategy review (07-23) that frames the target as a full BIM **authoring platform**
— semantic objects, families, coordinated documentation, model-driven schedules, versioned multi-user
collaboration, enterprise controls, extensibility.

- **Verdict: nearly everything in its 7 phases already ships here** — the review's target state is
  largely our shipped state, and its wedge thesis (open standards, browser-native collaboration,
  construction handoff over discipline-by-discipline parity) is the strategy we already run.
- **What survives is the gap list**, now the 🏛 R18 ring: **AUTH-CONSTRAINTS** (a persisted host/level/
  join constraint layer + broken-host validation — the biggest real gap) · **FAMILY-DEPTH** (type
  catalogs, instance overrides, nested families, shared parameters) · **VIEW-TEMPLATES** (per-view
  visibility/graphics overrides; associativity already comes from derive-from-model) · **SCHED-CALC**
  (calculated fields) · **MODEL-PUBLISH** (review→publish states + element-level optimistic
  concurrency) · **OPS-DR** (backup/restore + DR runbook) · **SDK-VERSIONING** · **ADR-LITE**.
- **The NOW list is reconciled**: the previous top-10 (the R17 backend order) shipped in full
  (v0.3.600–632); the fresh order leads with the R18 quick wins and slices.

## v0.3.633 — the 🪑 Space Utilization panel (Design workspace)

- **New portal panel** over the SPACE-UTIL engine: occupancy **capacity by space type** at an
  adjustable area-per-person standard (recompute in place), and a **program-fit** card — type
  `Office = 40` headcount lines and get required vs modelled area with the per-type gap and a
  color-coded surplus/short status.
- In the Design stage next to Design Metrics; every model-derived string escaped; live-verified in
  the demo (6 spaces · 5,544 m² · capacity 552 @ 10 m²/person). Web-only release (typecheck / lint /
  vitest 128 / build green); closes the SPACE-UTIL carried remainder's panel half.

## v0.3.632 — migration-chain fix (post-baseline module GIN indexes) + TESTFIT-ADJ daylight/wet-wall

The newly-live drift guard caught its second real defect in a day — and the suite now guards the class.

- **Fresh-DB upgrade was broken by v0.3.631's new modules**: the baseline migration's FTS helper reads
  the *live* module registry, so on an empty database it tried to GIN-index `mod_procurement_package`
  before the later revision created it (`UndefinedTable`). The baseline now indexes **only tables that
  exist at its own point in the chain**, and each post-baseline module migration creates its **own**
  GIN index (both v0.3.631 migrations amended) — runtime parity holds.
- **Static guard**: `test_alembic_migrations` now fails any future migration that creates a `mod_<key>`
  table without calling `index_ddl()` — SQLite can't exercise the Postgres DDL, so the shape is
  enforced statically and the real DDL runs in the CI guard.
- **TESTFIT-ADJ program terms** (`adjacency.py`): **needs-daylight** — every space of a listed type
  must sit on the storey envelope (footprint-based, no walls needed; a 3×3 grid's center room is
  correctly the one violation) — and **needs-wet-wall** — a listed type must share a wall with a wet
  space (default set bathroom/WC/kitchen/laundry, overridable via `wet_types`). Closes the R16
  TESTFIT-ADJ carried remainder's term half; the rule_library fold stays open.

## v0.3.631 — field + buyout persistence: Productivity Actuals & Buyout Packages modules

Two R16 carried remainders close at once: the loops stop being one-shot payloads.

- **New `progress_actual` module** (⏱ Field section, `PA-` refs, logged→verified workflow): activity /
  QTO line · schedule task · installed qty + unit · productive vs idle hours · crew · date.
  `POST /projects/{pid}/progress/actuals` now analyzes the **stored records** when the request carries
  no actuals (`source: "progress_actual module"`); an explicit payload still wins.
- **New `procurement_package` module** (📦 Preconstruction, `BP-` refs, draft → rfq_sent → quotes_in →
  awarded): `POST /procurement/packages/save` groups the QTO lines into buyout packages AND persists
  one record per package (est. cost, line count, the RFQ scope as JSON); the **send-RFQ bridge**
  `POST /procurement/packages/{rid}/send-rfq` mints a **Bid Solicitation** (ITB) carrying
  name/trade/due and advances the package to `rfq_sent` — procurement and bidding stay one thread
  (idempotent on re-send, 404 on unknown package).
- Alembic revisions `37bd38285a84` + `cdbb83e0cfe7`; drift guard green (161 tables, real Postgres);
  `test_prod_actuals` + `test_procure_level` extended; suite green.

## v0.3.630 — MASSING-OPT phase 2: emit the chosen option as an executable authoring chain

The optimize→author loop closes: pick a ranked massing option, get the model.

- **`layout_options.emit_recipes`**: one ranked option → the **blank-model bootstrap** (levels at the
  option's floor-to-floor) + a deterministic, **GUID-stable edit-recipe chain** — floor slab, four
  perimeter walls, and a centered core box per storey, sized from the option's own plate and core
  efficiency (side²·floors ≈ GFA). The chain drops straight into `POST /projects/{pid}/edit/batch`
  as one undoable version. Explicitly a massing *stand-in* the designer refines, not a floor plan.
- **`POST /massing/optioneer/recipes`**: server-side deterministic re-run + emit — the best option by
  default, an explicit `option` id honored, unknown id 404.
- The test doesn't just inspect the chain — it **executes it**: blank IFC from the bootstrap, every
  step through the real edit recipes, wall/slab counts and the top-level datum verified on the model.
- `massingOptionRecipes` client method; the R16 MASSING-OPT carried remainder is closed.

## v0.3.629 — fix: Postgres FTS GIN indexes were never actually created (IMMUTABLE violation)

The newly-working drift guard immediately earned its keep.

- The module full-text GIN index expression used `concat_ws`, which Postgres marks only **STABLE** —
  so `CREATE INDEX` was rejected with *"functions in index expression must be marked IMMUTABLE"* on
  **every** module table. `ensure_fts_indexes` logs-and-continues by design (startup must not block),
  so on a real Postgres deployment **full-text search has been running un-indexed** (per-row seq scans
  recomputing `to_tsvector`) with only a startup warning as the trace.
- `_pg_document` rebuilt on `coalesce` + the `||` operator (textcat, IMMUTABLE), every operand
  coalesced so a NULL column can't NULL the chain (concat_ws skipped NULLs; `||` propagates).
  Index and query still share the one builder, so they can't diverge.
- `test_fts_index` now asserts the immutable shape (`||` + coalesce, **no** concat_ws); the CI drift
  guard exercises the real `CREATE INDEX` on postgres:16 from here on. SQLite runtime is unaffected
  (LIKE fallback). Suite green.

## v0.3.628 — CITED-ANSWER × RFI-QA: NL-QA answers now emit the provenance contract

The flagship thesis follow-through: the NL question-answering surface speaks CitedAnswer.

- **`rfi_qa.to_cited()`**: every `/rfi/qa` answer now carries `cited` — the same answer on the
  CitedAnswer contract. Element GUIDs become typed `ifc` CitationRefs, readiness gaps become
  `rule` refs (`readiness/<category>` + the offending GUIDs), spec/detail/document refs become
  `doc` refs — so **coverage, the uncited-claim guard, conflicts, and provenance-as-confidence**
  apply to NL-QA exactly as to cited-query.
- Honesty preserved: the fallback model *overview* (no sources) is emitted as **uncited** —
  `fully_cited: false`, coverage 0 — instead of dressing it up.
- Readiness answers emit **one claim per gap**, each independently cited; the legacy response
  shape is unchanged (the contract rides alongside).
- `test_rfi_qa` extended (typed refs, per-intent coverage, confidence > 0); suite green.
- **CI fix:** the *DB migrations (Alembic drift guard)* workflow had never actually run its checks —
  every run since it was authored died at `CREATE DATABASE` because `psql` defaults the database name
  to `$PGUSER` (`aec`), which the service container doesn't create. Pinned `PGDATABASE: postgres`.

## v0.3.627 — PORTAL-TXN phase 3: the client conversation, backed by a real BCF topic

The share link grows a two-way thread — without a login, an inbox, or a new data model.

- **`POST /shared/{token}/comment`** (public): a client comment through a live share token lands on the
  token's dedicated **feedback topic** — a real BCF topic ("Client feedback — *label*", one thread per
  link, matched by a short label marker, never the full token). The project team reads and answers it
  in the 🗂 Issue Board like any other issue, and it **round-trips through BCF export**.
- **The digest + share page carry the conversation** both ways: the team's Issue-Board replies flow
  back to the client, oldest→newest, every message escaped on the public page.
- Public-surface rails: empty text 422, unknown/revoked token 404, 1 000-char message cap, a hard
  200-comment per-thread cap (409), author name length-capped.
- `sharedComment` client method; `test_portal_txn` extended (XSS-escape asserted, no-conversation
  tokens show no card); suite green; CodeQL 0.

## v0.3.626 — TOPIC-LIFE: the BCF-topic lifecycle spine (state machine · threaded comments · timeline)

Issues stop being flat rows — they get a real workflow, a conversation, and a history.

- **The status state machine** (`topic_lifecycle.py`, enforced on `PATCH /topics/{tid}`): the four
  canonical workflow statuses with real transition rules — resolved can't jump straight back to open,
  closed only reopens to *in progress*, idempotent PATCHes pass, and **vendor statuses from imported BCF
  files pass through unvalidated** (we enforce our workflow, we don't reject theirs).
- **Threaded comments**: `reply_to` on comments (+ Alembic revision), validated to an existing comment
  on the *same* topic (cross-topic threading 422s).
- **The per-topic timeline** (`GET /topics/{tid}/timeline`): creation, every status move, field edits,
  threaded comments, viewpoints and attachments merged from the audit trail oldest→newest, plus the
  canonical status list and this topic's allowed next transitions.
- **Issue Board click-through**: every kanban card now opens an inline timeline drawer (💬 threads shown
  with ↳, "next:" transition chips) — live-verified in the demo, which now seeds a real clash history
  and captures all six topic timelines.
- `test_topic_lifecycle` (suite 339); drift-guard clean; typecheck/lint/build green.

## v0.3.625 — PORTAL-TXN phase 2: the client-facing payment schedule (opt-in per token)

The client sees where the money stands — as a display, never a payment rail.

- **`show_payments` opt-in per share token** (a new ShareToken column + Alembic revision with a
  `server_default=false`, so every existing token stays financials-off): only a token explicitly minted with
  `show_payments: true` carries financials. The default digest's no-financials promise is asserted in both
  directions in the test.
- **The payment schedule** (digest + escaped HTML page): the project's owner invoices as milestones —
  number · period · amount · paid/submitted status — with **billed / paid / outstanding** totals, rendered
  with tabular numerals and a paid/unpaid colour code. Explicitly display-only; the payment rail remains a
  non-goal.
- Hand-checked in `test_portal_txn`: $550k billed / $250k paid / $300k outstanding; the plain token's digest
  and HTML carry no schedule. Drift-guard clean (159 tables); backend suite green; CodeQL 0.

## v0.3.624 — demo: seeded Issue Board + query-tolerant fixture matching (live-verified)

The hosted demo now shows the new kanban with real lanes — verified live in the browser.

- **Demo seed**: six representative BCF topics (an open High-priority clash, open/in-progress RFIs, punch
  items, a closed info note) so the 🗂 Issue Board renders **Open (2) · In Progress (2) · Closed (2)** in
  workflow order instead of an empty state; snapshot regenerated (978 fixtures).
- **`demoApi` query fallback**: fixtures are captured without query strings, but panels call with defaults
  (`/topics/board?group_by=status`) — on an exact-URL miss the matcher now serves the query-stripped base
  capture (exact matches still win). Benefits every current and future query-parameterized panel.
- **Live-verified in the demo preview**: the board renders "6 topic(s) · 3 column(s)" with type/priority/
  assignee chips on each card (DOM-verified; screenshots stay blocked by the known render-loop limitation).
  Typecheck + lint + build green; backend unchanged.

## v0.3.623 — docs: roadmap status + R17 follow-through summary synced (docs)

Status line → 338 backend suites / 128 vitest / v0.3.622 / CI on Node 22 / CodeQL 0; the R17 header now
records the follow-through wave (SCAN-4D · TOPIC-BOARD + panel · WALK-MODE · CLASH-WALKTHROUGH · roof
windows · the ReDoS fix) with the true remainder (CITE-JUMP · 4D5D-VIEWER · WebXR · NODE-CANVAS · carried
sub-phases). No code change.

## v0.3.622 — 🗂 Issue Board: the BCF kanban panel

The TOPIC-BOARD backend (v0.3.617) gets its face — the daily-driver issue view in the portal.

- **`topicBoard.ts` panel** (Build stage → "Issue Board"): a group-by selector (status / priority / assignee /
  type), a **QUERY-DSL smart-filter box** (`status=open & priority=High`, `title~duct` — Enter or Apply), and
  horizontally scrolling **kanban lanes** in the server's stable workflow order, each topic card carrying its
  type / priority / assignee / due-date chips. Every topic value renders escaped (issue titles are free text);
  columns cap at 50 visible cards with an explicit "+N more".
- `/topics/board` added to the demo capture list so the hosted demo shows the board after the next snapshot
  regen. Frontend-only (typecheck + lint + build green; backend unchanged at 338/338). **CodeQL confirmed
  back to 0** — the v0.3.621 ReDoS fix auto-closed the alert on re-scan.

## v0.3.621 — security: WKT parser ReDoS fix (CodeQL HIGH → 0)

The post-push CodeQL sweep flagged a HIGH `py/polynomial-redos` in the new parcel WKT parser
(v0.3.609) — the lazy `\s*(.+?)\s*\)\)` pattern could backtrack polynomially on crafted whitespace.

- **Fixed by removing the regex entirely**: the `POLYGON ((...))` envelope is now parsed structurally
  (`find`/`rfind` — linear time), with a 20k-char input size cap (a real parcel boundary is far smaller).
- **Regression-tested**: crafted 90k-whitespace and padded inputs must parse/reject in < 100 ms, the
  oversized input raises the cap error, and every existing WKT case still parses byte-identically
  (`test_parcel_geometry`). Backend suite green.

## v0.3.620 — roof windows: the add_roof_window authoring recipe (DORMER slice)

The roof-penetration family the authoring suite lacked — the flat-roof half of the dormer item.

- **`add_roof_window` recipe** (in the GUID-stable edit-recipe registry): cuts a skylight opening through a
  host flat `IfcRoof` at an [E, N] plan position — an `IfcOpeningElement` voiding the roof full-depth via the
  standard `feature.add_feature` relation — and fills it with an `IfcWindow` of PredefinedType **SKYLIGHT**
  (`feature.add_filling`), with the glazing panel at the roof plane and `OverallWidth`/`OverallHeight`
  carrying the roof-plane dimensions.
- Multiple skylights coexist on one roof; a bad host GUID raises cleanly; the void/fill relations survive a
  write/reopen round-trip — all asserted in `test_roof_window`. The pitched-roof dormer *assembly* follows
  when pitched roofs land. Backend suite green; CodeQL 0.

## v0.3.619 — CLASH-WALKTHROUGH: every clash topic ships with a framed viewpoint

Review clashes by standing next to them: each clash becomes a navigable place, not a row in a table.

- Both clash runs (single-model `POST /clash` and federated `POST /clash/federated`) with
  `create_topics=true` now attach a **framed BCF viewpoint** to every created clash topic — the camera at a
  deterministic 4 m diagonal standoff, the target on the clash point, and the offending element pair as the
  viewpoint components.
- Reopening the topic in the viewer lands the reviewer right at the clash (the existing viewpoint-restore
  flow), and walk mode (v0.3.618) starts from there — the clash list becomes a walkthrough. Asserted in
  `test_federated_clash`: standoff distance exactly 4 m, target = anchor, components = the pair.
- A step-through UI (next/prev + accept/reject) remains as the follow-up. Backend suite green; CodeQL 0.

## v0.3.618 — WALK-MODE (desktop) + richer BCF viewpoint capture

The first viewer slice of the R17 coordination sprint: review the model the way you'd walk the building.

- **🚶 Walk mode** (`walkMode.ts`): a rail toggle that enters a pointer-lock **first-person WASD walkthrough**
  from the current camera — mouse-look (pitch clamped ±85°, never flips), Shift to run, E/Q to raise/lower
  eye height, forward always horizontal (walking, not flying), Esc exits back to the orbit camera exactly
  where the walk ended. The movement math is a headless `WalkController` covered by **7 vitest unit tests**
  (heading, strafe, run multiplier, pitch clamp, opposed keys cancel); the installer drives
  `controls.setLookAt` per animation frame with long tab-away frames clamped.
- **BCF viewpoint capture upgraded**: creating an issue now **always** captures the live view — previously a
  viewpoint was only saved when a 3D point had been picked. The capture carries the camera position, the real
  orbit target, and the **active section planes**, so reopening an issue lands in context; the `Viewpoint`
  client type gains `clipping_planes` / `snapshot`.
- Honest verification note: typecheck + lint + **128 vitest tests** + build all green; the pointer-lock walk
  itself is geometry-coupled and not live-exercised under the known dev-preview stall. Backend unchanged.

## v0.3.617 — TOPIC-BOARD (backend): a BCF kanban with query-DSL smart filters

The daily-driver view over the BCF topics we already store — deterministic boards, one selector grammar.

- **`topic_board.py` + `GET /projects/{pid}/topics/board`**: kanban columns grouped by `status` / `priority` /
  `assignee` / `type`, in **stable workflow order** (open → in progress → resolved → closed → reopened;
  priority Critical → Low; unassigned always last; newest-modified first within a column) so the board renders
  identically everywhere.
- **Smart filters reuse the QUERY-DSL grammar over topic fields** — `status=open & priority=High`,
  `title~duct`, `assignee` (field-exists) — the same selector spine that scopes model elements, clash runs,
  and rules now scopes the issue log. Bad group/selector → 422; the route is declared ahead of
  `/topics/{tid}` so "board" isn't captured as a topic id (regression-tested).
- `topicsBoard` client method + `test_topic_board`. The frontend kanban panel, status/stage state machine,
  threaded comments, and per-topic timeline remain as the follow-up. Backend suite green; CodeQL 0.

## v0.3.616 — SCAN-4D: the diff between two capture timestamps

Completes the progress pair: PROGRESS-ROLLUP reads one capture; this reads the *change* between two.

- **`progress_rollup.capture_diff` + `POST /projects/{pid}/progress/capture-diff`**: given the design element
  set and the installed GUIDs at two capture timestamps — what got **newly installed** (per IFC class and per
  level), the **progress delta** (t1 vs t2 percent-complete), and a **daily installation rate** when dates
  are supplied.
- Elements present at t1 but absent at t2 are surfaced as **disappeared** — a re-scan or rework flag, never
  silently dropped. GUIDs not in the design set are ignored (only real elements count). Elements derive from
  the model's property index when not supplied.
- `progressCaptureDiff` client method; covered in `test_progress_rollup` (hand-checked: 3 added over 10 days
  = 0.3/day, w1 disappearing flagged). Backend suite green; CodeQL 0.

## v0.3.615 — docs: sync README / roadmap / status to the R17 backend wave (v0.3.600–614)

Documentation refresh capturing the fifteen-release R17 backend wave — no code change.

- **roadmap.md** status → 336 suites / v0.3.614 / CI on Node 22, with a shipped-wave summary (Sprint A
  provenance flagship + Sprints C/E complete + D/F engines) and the remaining viewer-coupled items listed.
- **README.md** lead highlight rewritten around the provenance-first AI (`CitedAnswer`) + the
  estimating/feasibility engine spine. **status.md** watermark → v0.3.614.

## v0.3.614 — CONCEPT-BUDGET: a conceptual budget priced against your own completed projects

The front-of-funnel that matches the "Massing" name: a defensible first number from massing inputs, priced
against the firm's own history rather than an industry average. Completes the R17 estimating sprint.

- **`concept_budget.py` + `POST /projects/{pid}/estimate/concept-budget`**:
  - `derive_rates(history)` — the firm's completed projects (`building_type · gfa · actual_cost · year`) →
    per-type **$/area statistics** (n · p25 · median · p75), each project's rate **escalated to the target
    year** at a given annual rate before aggregation, so old jobs price forward honestly.
  - `budget(program)` — a massing program (use · GFA · stories) priced at the own-history **median** with a
    **p25–p75 range** per line and in total; a supplied default rate covers uses with no history, and a use
    with neither is surfaced **UNPRICED** rather than guessed.
- Every line carries its **source** ("own-history (n=…)" vs "default rate") — composing directly with
  EST-CONFIDENCE (historical > manual) and the BOE-LEDGER assumption trail. Hand-checked: three office
  projects at 300/350/400 $/SF → median 350, a 200k SF massing prices at $70M ($65–75M), +10% contingency.
- `estimateConceptBudget` client method + `test_concept_budget`. Backend suite green; CodeQL 0.

## v0.3.613 — BOE-LEDGER: the Basis-of-Estimate assumption ledger

The traceability layer *under* the estimate numbers — an estimate you can defend line-by-line, pairing with
EST-CONFIDENCE (which scores them).

- **`boe_ledger.py` + `POST /projects/{pid}/estimate/boe`**, three deterministic reads:
  - **ledger** — the normalized BoE (source · quote ref · escalation % · contingency % · basis date per
    line) with **documentation completeness**: lines missing a source or basis date are surfaced, and a
    quote-sourced line without a `quote_ref` is flagged. An undocumented basis is a dispute waiting to happen.
  - **phase_diff** — assumption drift between estimate versions (SD → DD → CD): qty re-based, unit cost
    moved, escalation/contingency shifted, source upgraded (allowance → quote), with the per-line total
    impact, biggest movement first, plus added/removed lines.
  - **vs_actuals** — once actuals land, the assumption→actual variance **decomposed exactly**: qty effect
    (Δqty × assumed unit cost) + price effect (actual qty × Δunit cost) sum to the variance, so the ledger
    says *which assumption* drove the miss, worst first.
- `estimateBoe` client method + `test_boe_ledger` (hand-checked: an $8,800 miss decomposes into $5,200 qty +
  $3,600 price). Backend suite green; CodeQL 0.

## v0.3.612 — PERSONA-ANSWER: persona lenses over the provenance contract (+ Sprint wrap-up)

The same cited data answers differently per seat — deterministically, with the provenance intact.

- **`persona_answer.py`**: Exec / PM / Field lenses over a `CitedAnswer` — the prose trims to the seat (exec
  two sentences, field one line, pm the breakdown) while **claims and citations are never dropped**; a
  deterministic one-line **insight** (priority: source conflicts > uncited claims > no-match > coverage) and
  ≤4 **follow-up chips** derived from what the answer actually contains (a conflict yields "show the
  conflicting sources", an exec match yields "what is the cost exposure…"). Template strings, no LLM.
- Wired into `POST /projects/{pid}/answer/cited-query` via an optional `persona` — without it, the plain
  CitedAnswer contract is byte-for-byte unchanged. The query-DSL scoping already serves as the
  dataset-scoping toggle. Client updated + `test_persona_answer`.
- **TRANSMITTALS verified already covered** (the numbered TR- `transmittal` module + workflow engine +
  issuance/distribution; PORTAL-TXN added the client-acknowledge path) — marked on the roadmap, no duplicate
  build. **SEC-DATAFLOW** folded into the security-monitoring skill: prioritize multi-file/cross-import
  data-flow review (router → helper → engine → storage) — the empirically hardest class, least covered by
  SAST patterns. Backend suite green; CodeQL 0.

## v0.3.611 — PORTAL-TXN phase 1: the client portal turns transactional (tokenized decisions)

The read-only ShareToken digest becomes a lightweight decision surface — the client can act, not just look —
while staying deterministic and hard-capped for a public endpoint.

- **`client_decisions` table** (+ an Alembic revision; the drift-guard stays clean) and a PUBLIC
  **`POST /shared/{token}/decision`**: a timestamped, token-stamped **approve / acknowledge / decline** on a
  shared item (estimate · proposal · change order · selection · invoice · document). Explicitly NOT a payment
  and NOT an e-signature of record — a recorded client decision with status.
- **Hardened for a public write path:** item-type and action whitelists (a `wire_transfer` or `paid` attempt
  is a 422), 120/500-char caps on refs/notes, a **hard 200-decision-per-token cap** (409 — an unauthenticated
  holder can't grow the table unbounded), and revoked/unknown tokens 404 with no enumeration signal.
- The shared digest and the public HTML page now carry the newest-first **activity feed** — rendered fully
  escaped (an injected `<script>` appears only as text). Editors read the project-wide decision feed at
  `GET /projects/{pid}/client-decisions`.
- `sharedDecision` / `clientDecisions` client methods + `test_portal_txn` (decisions, guards, caps, escape,
  revocation, the cap 409). Backend suite green; CodeQL 0.

## v0.3.610 — WALL-ASSEMBLY thermal: R/U-values computed from the layers themselves

The model already carries genuine layered assemblies (`IfcMaterialLayerSet`), and the envelope code-check
demands a U-value — but nothing bridged the two. Now the U is computed, not asserted.

- **`assembly_thermal.py` + `GET /projects/{pid}/model/assembly-thermal`**: every distinct layer set in the
  model → its **R/U** from the layers (R = thickness ÷ design k per material category, an air cavity at its
  fixed R, standard surface films; an explicit per-layer k overrides the catalog), the elements using it, and
  a **per-layer material takeoff** (thickness × face area from the base quantities).
- Hand-checked: a brick / cavity / insulation / gypsum wall computes R 2.224 (R-12.6 imperial) → U 0.45, with
  the insulation contributing 1.667 of it. Representative ASHRAE-style design k-values, clearly labelled an
  analytical pre-check (not a hot-box test).
- `modelAssemblyThermal` client method + `test_assembly_thermal` (pure math + an authored model with applied
  layer sets + the 409 route guard). Backend suite green; CodeQL 0.

## v0.3.609 — PARCEL-IMPORT: cadastral parcel geometry → FAR / coverage / height compliance

Upload-driven parcel ingest (no government scraping) that turns a boundary into the site math zoning and
feasibility key on.

- **`parcel_geometry.py` + `POST /parcels/analyze`**: parses a parcel boundary from **GeoJSON** (Polygon or
  Feature) or **WKT POLYGON** → **area / perimeter / centroid / bbox** via the shoelace formula. Lon/lat
  rings are projected equirectangularly at the centroid latitude (~0.1% accurate at parcel scale, verified
  within 1% in the test); projected-metre rings compute exactly.
- With a **zoning envelope** (`max_far` / `max_coverage` / `max_height_m`) and a **proposal** (`gfa_m2` /
  `footprint_m2` / `height_m`), reports per-axis **compliance with slack** — including the max-buildable GFA
  the FAR limit implies — and the overall violations list. Missing limits report `ok: null`, never guessed.
- Bad boundaries (a Point, malformed JSON/WKT) → 422. `parcelAnalyze` client method + `test_parcel_geometry`.
  Backend suite green; CodeQL 0.

## v0.3.608 — RUNTIME: Node 20→22 in CI + oxlint fast pre-lint (the two benchmarked GO items)

The two RUNTIME-ring items that cleared the "measured win" bar (the other four were already solved or solved
a non-problem — see the roadmap's benchmarked assessment).

- **Node 20 → 22 in CI:** the four GitHub Actions workflows (ci · desktop · pages · security) now run on Node
  22 LTS. Low-risk (Node 22 is a superset of 20 for our toolchain), and it's the prerequisite for later
  unpinning eslint and moving to Vite 7. eslint stays pinned at 9.39.5 for now (the developer's local Node is
  still 20.3.1); unpinning is a follow-up once local Node is bumped.
- **oxlint (MIT) added** as `apps/web` dev-dep + a `lint:fast` (`oxlint src`) script — an *additive*
  sub-second pre-lint for fast local feedback, **not** a replacement for the type-aware eslint gate (37.7 s;
  oxlint doesn't implement typescript-eslint's type-aware rules, so it can't shrink CI). **Caveat:** oxlint
  1.75's launcher requires Node ≥ 20.19, so it runs in CI (Node 22) and locally *after* a Node upgrade, but
  not on a local Node 20.3.1. The existing eslint + build gates are unaffected.

## v0.3.607 — FILL-MATRIX: a property fill-rate pivot that feeds a bulk-edit loop

Pinpoints *which* pset field is systematically blank and hands back the exact GUIDs to fix — the analytics →
selection → bulk-write loop as one move.

- **`fill_matrix.py` + `GET /projects/{pid}/model/fill-matrix`**: for each IFC class, the union of `Pset::Prop`
  keys seen on its elements with, per property, how many carry a non-empty value (`fill_rate`) and the **GUIDs
  that are blank** — the exact selection a `query_dsl` scope + edit recipe fills in one pass (each row also
  carries a ready selector string).
- **`worst_gaps`** surfaces the biggest partially-filled fields (present on some, missing on many) —
  most-blank-first — the highest-leverage data-quality fixes. Fully-filled properties are excluded.
- Pure over the property index we already hold; `modelFillMatrix` client method + `test_fill_matrix`. Backend
  suite green; CodeQL 0.

## v0.3.606 — PROGRESS-ROLLUP: % complete from as-built element presence (by count and value)

Turns element presence into a percent-complete rollup the GC portal and earned value can consume.

- **`progress_rollup.py` + `POST /projects/{pid}/progress/rollup`**: given the design model's expected element
  set and the set of GUIDs verified **installed**, roll up percent-complete **by IFC class, by trade/
  discipline, by level, and overall — by count AND by value**. Count and value diverge exactly where it
  matters (many cheap elements up vs. a few expensive ones outstanding), so both are reported.
- Elements derive from the model's property index when not supplied; discipline falls back to the
  classification map. Deterministic over the elements + installed GUIDs. `progressRollup` client method +
  `test_progress_rollup`. Backend suite green; CodeQL 0.

## v0.3.605 — ABSORPTION-SELLOUT + LOT-SUPPLY-INDEX: the revenue-side underwriting levers

Our market work is cost-side (escalation); the biggest missing underwriting lever is *how fast the product
sells*. Two deterministic engines add it.

- **`absorption.py` + `POST /projects/{pid}/feasibility/sellout`**: an absorption rate (sales/month) phases
  revenue over time → the **monthly sell-out curve**, **months-to-sell-out** (the carry the pro-forma must
  underwrite), total revenue, and carry over the window. The last month sells the remainder on an uneven mix.
- **`POST /projects/{pid}/feasibility/lot-supply`**: the public **Lot Supply Index** —
  `months_of_supply = VDL ÷ monthly absorption`, indexed to a balanced-market target (100 = equilibrium ·
  > 125 oversupplied · < 75 undersupplied) — a defensible supply/demand read for land screening.
- Absorption rate is an input (a comparable rate is an optional market feed — INTEGRATE). Deterministic
  arithmetic; `feasibilitySellout` / `feasibilityLotSupply` client methods + `test_absorption`. Backend suite
  green; CodeQL 0.

## v0.3.604 — PERMIT-TIMELINE: days-to-issue analytics → a pro-forma entitlement driver

We already ingest permit feeds; the missing bridge was the *timeline model* between the raw feed and the
underwriting. This adds it — deterministically, no live fetch.

- **`permit_timeline.py` + `POST /projects/{pid}/permits/timeline`**: over the cached permit records (or a
  supplied set), days-to-issue = issued − filed, grouped by **jurisdiction × permit type × valuation band**
  into a p25 / median / p75 distribution, plus a seasonal issuance profile.
- **`estimate(target)`** returns the **median** (expected entitlement duration) and **p75** (the conservative
  carry the pro-forma should underwrite) for a jurisdiction / type / valuation, automatically **broadening the
  cohort** (band → type → jurisdiction → all) until the sample is statistically stable, and reporting which
  basis it used.
- Reads the project's `permit` module records when `permits` is omitted; 409 when there's no permit data.
  `permitsTimeline` client method + `test_permit_timeline`. Backend suite green; CodeQL 0.

## v0.3.603 — SCOPE-REG: a first-class scope register + gap analysis (the connective spine)

Ties the things we already hold *separately* — quantities, cost breakdown, responsibility, schedule — into
one register, and surfaces the holes.

- **`scope_register.py` + `POST /projects/{pid}/scope/register`**: each scope item resolves its
  **quantity/value** (from the QTO by cost code), its **owner** (responsible party / buyout package), and its
  **schedule window** (the activity that builds it, by id or cost code).
- The payload is the **gap analysis**: which scope is **unquantified**, which is **unallocated** (nobody owns
  it), which is **unscheduled** — the holes that sink a job — surfaced gaps-first, highest-value-first, with
  % quantified / allocated / scheduled and a by-owner value rollup.
- Deterministic over the supplied scope items + QTO lines + activities; the connective spine across QTO · CBS
  · responsibility · schedule. `scopeRegister` client method + `test_scope_register`. Backend suite green;
  CodeQL 0.

## v0.3.602 — BUYOUT-SCHED: time-phased procurement schedule from QTO × the construction schedule

Only we hold both the model *and* the CPM/Takt schedule, so we can answer the buyer's real question
deterministically: what to buy, how much, and by when to order it.

- **`buyout_schedule.py` + `POST /projects/{pid}/procurement/buyout-schedule`**: each QTO line is joined to
  the schedule activity that installs it (by explicit activity id, then cost code, then trade — the earliest
  matching install), and the **last-responsible-order date** = install start − lead time. Sorted
  soonest-order-first.
- With an `as_of` date, each line is classified **overdue / urgent (≤14 days) / upcoming (≤30 days) / ok**;
  lines with no matching activity are surfaced as **unscheduled** (assign a cost code or trade to place them).
  The rollup reports the overdue count, the next-30-day count, and the total value in the window.
- Lead times come from a per-line `lead_time_days`, else a material/trade/cost-code `lead_times` map, else a
  default. Pure arithmetic over the supplied lines + activities (no wall-clock — pass `as_of`).
  `buyoutSchedule` client method + `test_buyout_schedule`. Backend suite green; CodeQL 0.

## v0.3.601 — EST-CONFIDENCE: per-line estimate maturity + confidence scoring

A number should carry how much to trust it, not just its value — the continuity-of-cost idea, as pure
deterministic scoring over estimate lines we already hold.

- **`est_confidence.py` + `POST /projects/{pid}/estimate/confidence`**: each line's confidence is a function
  of its **source** (a quantity measured off the IFC or a returned quote is firm; a parametric assembly is
  softer; a manual allowance is soft) modulated by **design phase** (CD > DD > SD > concept), banded
  high / medium / low.
- Cost-weighted rollup → a project **confidence** score and band, a **"% of budget still assumption-based"**
  KPI (allowance / manual / parametric lines vs. measured / quoted), average contingency, cost-by-band and
  cost-by-source breakdowns, and the **worst-value least-grounded lines** to firm up next. Lines carrying a
  high contingency are flagged.
- No model, no LLM — arithmetic over supplied lines. `estimateConfidence` client method +
  `test_est_confidence`. Backend suite green; CodeQL 0.

## v0.3.600 — CITED-ANSWER: a provenance contract so every AI answer traces to its source

The R17 flagship — the thesis made concrete. A regulated industry can't act on a black-box answer; because
our data is GUID-first and structured we never *lose* provenance, we attach it deterministically.

- **`cited_answer.py`** defines the **`CitedAnswer`** contract: an answer composed from cited atomic **claims**,
  each carrying `CitationRef`s that point to a model element (IFC GlobalId), a data record (`module/{key}/{id}`),
  a rule/code-check, or a document location — always with the **revision** it came from. Minters:
  `cite_ifc` / `cite_record` / `cite_rule` / `cite_doc`.
- Deterministic, no LLM and no model-emitted confidence: **coverage %** (share of claims with ≥1 citation)
  with a hard **uncited-claim guard** (< 100% warns); **conflict surfacing** — when two claims assert
  different values for the same target (e.g. the model says a wall is 2HR but a code rule requires 3HR), both
  provenances are kept, never silently resolved; and **provenance-as-confidence** derived from the number of
  independent sources, a stale-revision penalty, and source-type rank (rule / IFC-property > record > doc).
- First producer: **`cited_query` + `POST /projects/{pid}/answer/cited-query`** — a model query whose every
  claim cites the GUIDs it is derived from, optionally broken down by a property's value. `citedQuery` client
  method + `test_cited_answer`. The AI command bar / RFI-QA / knowledge-graph answers adopt the contract next.
- Backend suite green; CodeQL 0.

## v0.3.599 — roadmap: R17 field-research ring + R16 archived + re-prioritized (docs)

A second broad field-research pass (14 external products across authoring / estimating / finance /
reality-capture / BCF / VR, plus a security research paper) → a new **🧭 R17 ring** on the roadmap, with the
completed **🔬 R16 ring archived** and the NOW list re-prioritized top-down. No code change.

- **Sharpened thesis:** the field ships black-box AI answers a regulated industry can't defend; because our
  data is GUID-first and structured, we can make every AI answer **trace to its source deterministically** —
  the provenance layer is the R17 flagship (**CITED-ANSWER**), scheduled first.
- **R17 sprints A–F** (backend-testable engines first, viewer-coupled after): provenance & AI trust
  (CITED-ANSWER · PERSONA-ANSWER) · model-navigable coordination (BCF viewpoint capture/restore · first-person
  walk + WebXR · topic kanban) · estimating intelligence (per-line confidence/maturity · basis-of-estimate
  ledger · time-phased buyout schedule · parametric conceptual budget) · scope & 4D/5D spine (a first-class
  Scope register · time+cost overlay scrubber) · feasibility (permit days-to-issue percentiles → pro-forma ·
  absorption sell-out schedule + lot-supply index · % complete from scan deviation) · model-QA & authoring
  (property fill-rate pivot → bulk edit · layered wall assemblies · cadastral parcel import · transactional
  client portal). Every external data feed stays an optional offline-degrading connector; LLM/OCR doc
  reconstruction, capture hardware, VR-headset app, and payment rails remain non-goals.
- **R16 ring marked complete** (v0.3.573–598) and its full spec moved to `roadmap-completed.md`, with the
  minor carried remainders kept on the open lists. The security paper's finding (multi-file/cross-import
  data-flow vulnerabilities are the hardest and highest-value) folds into the security-review process.

## v0.3.598 — SEC-SUPPLY: license/SBOM audit + PDF sanity check (supply-chain hardening)

Dependency-free supply-chain tooling (stdlib only), folded into the `security-monitoring` skill — it does
not replace CodeQL or the `esc()` XSS discipline.

- **License audit** (`supply_chain.license_audit`): classifies every installed Python distribution as
  **permitted** (MIT/BSD/Apache/ISC/PSF/Unlicense/Zlib) · **copyleft** · **unknown**, splitting **strong**
  copyleft (GPL/AGPL — the disallowed hard line) from **weak** (LGPL/MPL — accepted for the ifcopenshell /
  certifi core deps but surfaced). Word-boundary matched, so a BSD licence text's "EXEMPLARY" no longer
  false-matches "MPL". `python -m aec_api.supply_chain --gate` exits non-zero only on strong copyleft, so it
  never breaks CI over the known weak-copyleft core deps.
- **SBOM** (`supply_chain.sbom`): a minimal CycloneDX 1.5 component list (name · version · license).
- **PDF sanity check** (`supply_chain.pdf_sanity`): a lightweight pre-ingest validator — header, EOF, size
  cap, and active-content flags (JavaScript / Launch / EmbeddedFile / OpenAction). Not a full parser (no
  AGPL PyMuPDF).
- `test_supply_chain` + a SEC-SUPPLY section in the security-monitoring skill. Backend suite green; CodeQL 0.

## v0.3.597 — TESTFIT-ADJ: space adjacency graph + program-relation score + dimensional rule pack

Turns the program brief into a live constraint beside the geometry — the last R16 Tier-2 engine.

- **`adjacency.py` + `POST /projects/{pid}/model/adjacency`** (409 without a source IFC): builds an
  **adjacency graph** over the model's IfcSpaces — two spaces are adjacent when their footprints sit within a
  wall-thickness gap on the same storey. Footprints come straight from each space's extruded profile +
  placement (no OCC), and a corner-only touch is *not* counted as an adjacency.
- **Program scoring:** the graph is scored against a program's `required_adjacent` type-pairs (a pair is met
  if any A-type space touches a B-type space → satisfied ratio) and `forbidden` type-pairs (each violating
  A↔B instance is listed).
- **Dimensional compliance:** each space is checked against a rule pack — minimum room dimension (the short
  side of its footprint), minimum floor area, minimum clear/ceiling height — global or per space type.
- Pure over an opened model (recomputes on every edit); `modelAdjacency` client method + `test_adjacency`
  over a relabelled 2×2 grid (4 shared-wall edges, diagonals excluded; a required pair met + one unmet + a
  forbidden violation; the dimensional pack). Backend suite green; CodeQL 0.

## v0.3.596 — portal panels for the DESIGN-METRICS and MEP-FITTINGS engines

The two model-derived R16 Tier-2 engines now have UI in the portal (both in the **design workspace →
Model & standards** stage), turning shipped compute into visible product.

- **📐 Design Metrics panel** (`designMetrics.ts`): a program-efficiency KPI header (floors · net floor area ·
  GFA · net-to-gross · units · avg unit · spaces), a **daylight card** with the average-daylight-factor
  estimate colour-banded good/fair/limited (clearly labelled an estimate), and an area-by-space-type table
  with each type's share of net area.
- **🔩 MEP Fittings panel** (`mepFittings.ts`): the total implied-fitting count with per-type chips
  (elbow/tee/cross/reducer), a **QTO-lines** table (EA), and an "inferred at" detail table showing where and
  why each fitting was implied. Both 409 gracefully into a "needs a source IFC" message.
- Frontend-only (backend unchanged); typecheck + lint + build green. Wired via nav destinations + lazy
  importers, following the existing panel pattern. Input-form panels for the POST engines (PROD-ACTUALS,
  PROCURE-LEVEL) are a separate follow-up.

## v0.3.595 — docs: sync README / roadmap / status to the R16 Tier-2 engine wave (v0.3.591–594)

Documentation refresh capturing the four deterministic engines just shipped — no code change.

- **roadmap.md** status line → 320 suites / v0.3.594, with a "recently shipped" summary of the
  DESIGN-METRICS + DAYLIGHT, MEP-FITTINGS, PROD-ACTUALS, and PROCURE-LEVEL wave.
- **README.md** lead highlight rewritten around the four model/field/buyout engines.
- **status.md** point-in-time watermark advanced to v0.3.594.

## v0.3.594 — PROCURE-LEVEL: QTO → buyout packages + coverage/lead-time-aware quote scoring

The buyout loop on top of the estimate: turn the QTO into RFQ-ready packages, then score returned quotes on
more than headline price.

- **`buyout_packages` + `POST /projects/{pid}/procurement/buyout-packages`**: group QTO line items into
  buyout packages (by trade / CSI / material class / discipline), each carrying an **RFQ scope** (item · qty ·
  unit) the buyer can send out, ranked by estimated cost.
- **`score_quotes` + `POST /projects/{pid}/procurement/level`**: score returned quotes for one package against
  its RFQ scope on a normalized basis — **price** (extended over the scope quantities, with uncovered scope
  extrapolated at the supplier's covered average), **coverage completeness** (how much of the scope they
  priced), and **lead time** — into a composite [0,1] score that ranks the suppliers and lists each one's
  scope gaps. Incomplete bids are penalized on coverage, never silently dropped; the lead-time weight folds
  into price + coverage when no lead times are supplied. Per-item low prices are surfaced too.
- Deterministic on top of the existing quote-leveling; `buyoutPackages` / `procurementLevel` client methods +
  `test_procure_level`. Backend suite green; CodeQL 0.

## v0.3.593 — PROD-ACTUALS: installed-rate actual vs planned + crew utilization

The productivity actuals loop — so the line-of-balance / 4D view shows whether the field is gaining or
losing ground against takt, not just what's planned.

- **`prod_actuals.py` + `POST /projects/{pid}/progress/actuals`**: a `{task_id, qto_line, material_class,
  qty, cycle_time, idle_time, unit}` actuals schema rolled up per activity into the **installed rate**
  (qty ÷ productive/cycle hours) and **crew utilization** (productive ÷ (productive + idle)), then compared
  to the **planned** rate → **ahead / on-track / behind** (±5% band). When a planned quantity is known it
  also reports percent-complete, remaining quantity, and the hours projected to finish at the current rate.
- Rates are compared *within* an activity only — units differ across trades, so the rollup surfaces overall
  utilization (dimensionless) and per-group variance counts, worst-variance first, never a cross-trade rate.
- Pure over the supplied rows (field log / telematics CSV / manual entry); `progressActuals` client method +
  `test_prod_actuals`. Backend suite green; CodeQL 0.

## v0.3.592 — MEP-FITTINGS: implied tee / cross / reducer / elbow over the port graph → QTO

Every junction and transition of a connected MEP run *implies* a fitting — a duct/pipe network can't branch,
change diameter, or turn a corner without one. This reads the MEP port-connectivity graph and infers those
fittings deterministically (no CV — IFC already carries the connectivity others reconstruct from scans), so
the fitting count feeds buyout and estimate instead of only the segments drawn.

- **`mep_fittings.py` + `GET /projects/{pid}/mep/fittings`** (409 without a source IFC): **tee/cross** at each
  branch node (degree ≥3 → a tee, degree 4 → a cross, an *n*-way manifold → *n*−2 tees), **reducer** at a
  segment-to-segment joint with a nominal-size step, and **elbow** at a joint where the two segments change
  direction (sweep-axis angle read from the placement, folded so antiparallel still reads as straight).
- Reducer/elbow inference is confined to **segment↔segment** joints where neither element is a branch, so a
  tee's own legs and authored fittings are never double-counted; a reducing elbow counts once (as the elbow).
- Counts roll into a QTO **`qto_lines`** block (EA), plus a per-type breakdown and capped detail list.
  `mepFittings` client method + `test_mep_fittings` over three authored+connected mini-systems (a 3-way
  branch, a 300→200 mm in-line step, a 90° corner). Backend suite green; CodeQL 0.

## v0.3.591 — DESIGN-METRICS + DAYLIGHT: live program-efficiency + daylight estimate over the model

A new design-validation engine turns the model's own geometry into live design KPIs — recomputable on every
edit, so program efficiency and daylight adequacy become active constraints beside the geometry, not a
downstream report.

- **`design_metrics.py` + `GET /projects/{pid}/model/design-metrics`** (409 without a source IFC): **program
  efficiency** — floors, gross floor area (from the model's storey quantities, else net ÷ a typical
  efficiency), net floor area, net-to-gross ratio, unit count + average unit area (residential-typed spaces),
  and area rolled up by space type.
- **Deterministic daylight estimate:** total glazed area from the model's actual `IfcWindow`s → a
  window-to-floor ratio → an **average daylight factor** via the CIBSE formula with documented constants,
  banded **≥2% good · 1–2% fair · <1% limited**. Clearly labelled an *estimate* (an honest analytical first
  look before a real simulation — the ray-traced version rides the energy/daylight jobs lane), not a black box.
- Pure over an opened model (reuses the SPACE-UTIL space extractor); `modelDesignMetrics` client method +
  `test_design_metrics` (band thresholds, the CIBSE constant, metrics over a real authored model, route
  409/200). Backend suite green; CodeQL 0.

## v0.3.588 — GitHub Pages: one branded theme across all pages + clearer CTA

The landing + guide pages now share the **status.html design system** (the navy · cyan→violet "hologram
edges" theme that matches the brand marks), so the whole site reads as one branded product.

- **index.html** re-skinned onto the shared tokens: navy gradient ground + grid backdrop, cyan→violet
  gradient headline accent + primary buttons, mono eyebrows/pills, the Massing logo in the hero.
- **guide.html** palette swapped to the same tokens (it already shared the CSS-variable names, so the
  navy/cyan theme propagates), plus the logo mark added to its sticky header.
- **Clearer CTA:** the vague **"Free IFC viewer →"** button is now the primary **"Open the live demo →"**
  (and the in-page "Open the viewer →" matches); the download button steps back to secondary. Verified in
  the browser — branded palette applied, no horizontal overflow.

## v0.3.587 — observability: DB migrations + error alerting + tracing (#74 · #75)

Sprint 2 of the open-PR cleanup — the production observability stack, all env-gated and no-op until
configured. (#73 Sentry was already contained in #75, so it's closed as redundant.)

- **#74 Alembic DB migrations (C1)** — `alembic.ini` + `migrations/` with a baseline-current-schema
  revision (158 tables), an `env.py` wired to the app's metadata, and a `db-migrations` CI job that runs
  `upgrade head` + `alembic check` (drift guard) against Postgres. `test_alembic_migrations` builds head +
  asserts no drift. `alembic>=1.13` added to `requirements.in`/`.lock`.
- **#75 OpenTelemetry tracing (C2) + Sentry error alerting (C3)** — `otel.py` (traces only; no-op unless
  `OTEL_EXPORTER_OTLP_ENDPOINT` is set; FastAPI + SQLAlchemy instrumentation, sample-rate control,
  request-id on the span) and `sentry.py` (external 500 alerting; no-op unless `AEC_SENTRY_DSN` is set;
  **fail-open** — capture failure never affects the response; PII scrubbing of auth/cookie/api-key +
  body). `test_otel` + `test_sentry` cover the enabled + disabled paths. Deps (`sentry-sdk[fastapi]`,
  the explicit `opentelemetry-*` packages — Apache-2.0/MIT) added to `requirements.in`/`.lock`.

Merged onto current main (run_tests test-list conflicts resolved to keep every test), ruff + full suite green.

## v0.3.586 — merge the ready hardening PRs (#70 · #71 · #72)

Sprint 1 of the open-PR cleanup — three additive, CI-green production-hardening branches, landed together
after re-verifying the full suite on top of current main.

- **#70 security + performance hardening** — from the production/enterprise audit: `serving.py`,
  `bcf_io.py`, and the convert/authoring/bim routers, with an `nginx.conf` pass; covered by
  `test_serving` / `test_subset_export` / extended `test_bcf`.
- **#71 operational hardening** — opt-in `/metrics` auth + configurable compose resource limits
  (`docker-compose*.yml`, `.env.example`, `main.py`); `test_metrics_auth`.
- **#72 dependency hygiene** — pin the Dockerfile base images by digest (api/web/converter) + an
  `npm audit fix` pass on `package-lock.json` + a `dependabot.yml` grouping tweak.

No version/CHANGELOG conflicts (all three were branched off v0.3.584); merged clean, ruff + full suite green.

## v0.3.585 — SPACE-UTIL: space utilization + supply/demand planner (R16 Tier-2)

Turn the model's `IfcSpace` inventory into a workplace-planning answer — deterministically, because we
hold the areas in the IFC (no sensors, no ML).

- **`space_util.py`** — `utilization(spaces, area_per_person)` gives each space an occupancy **capacity**
  (`floor(net-area ÷ area-per-person)`) rolled up by space type + totals; `demand(spaces, program,
  area_per_person)` compares a headcount **program** (`{space_type: headcount}`) against the modelled
  inventory → required vs. supplied area + the **gap** (deficit/surplus) per type, worst-deficit first.
  The computation is pure over a plain space list (fully unit-tested); `from_model` pulls the spaces off
  the IFC (`Qto_SpaceBaseQuantities` net/gross floor area, LongName/ObjectType for the type).
- **`GET /projects/{pid}/model/space-utilization?area_per_person=…`** + **`POST
  /projects/{pid}/model/space-demand`** ({program, area_per_person}). Client `modelSpaceUtilization` /
  `modelSpaceDemand`. `test_space_util` covers capacity math, the standard-changes-count case, the
  bad-standard fallback, the demand gap + worst-first sort, and the routes (409 without a model).

## v0.3.584 — SPRINT MB: the Master Builder brief's gaps are now one click from the fix

The 8-step Master Builder brief named a gap per step but left you to find the tool that closes it. Each
step now deep-links to the portal destination that addresses it — the same diagnosis→action move as UX-ACT.

- **`master_builder.py`** — each protocol step carries a portal `dest` (place→`__modelanalysis__` ·
  program→`__program__` · feasibility→`__budget__` · regulatory→`__standards__` · design→`__modelqa__` ·
  delivery→`__schedule__` · risk→`__review__` · handover→`__turnover__`), surfaced on every brief step.
  `test_master_builder` asserts each step's dest is a valid `__key__` and the full set is present.
- **Portal** — the `__key__`→render dispatch is hoisted out of `buildNav` into `destDispatch()`, and
  `PanelContext` gains a `navigate(key)` method (a clean way for any panel to jump to a first-class
  destination). The 🏛 Master Builder panel renders a **"→ Close this gap"** button per step (emphasized
  on gaps/partials, quiet when ready) that navigates straight there. Client `Step` type gains `dest`.
- Web typecheck + lint + build green.

## v0.3.583 — docs / Pages / demo refreshed to the R16 Tier-1 wave

Marketing + docs surfaces were last refreshed at v0.3.567; this brings them current to the whole
v0.3.573–582 wave (and fixes the stale 80-module count → 130).

- **README** — new lead highlight bullet for "deriving the deal, the buyout and the FM register straight
  from the model" (massing optioneer · cost-code margin + one-click fixes · asset register + equipment RFQ
  + spec-conflict · recipe-macros); module count 80 → **130** in both places.
- **GitHub Pages** — `status.html` "Recently shipped" section + cards rewritten to the R16 wave;
  `guide.html` "Recently added" callout rewritten; `status.md` watermark → v0.3.582.
- **Demo** — `demoData.json` regenerated (970 fixtures) against the current build.
- No code change; the backend suite is unchanged at 311 green.

## v0.3.582 — portal UIs for the shipped MASSING-OPT + MEP-EQUIP engines

The R16 Tier-1 engines shipped with backend + client methods but no portal surface; this makes two of them
usable.

- **🧮 Massing Optioneer** (developer › Acquire) — a compact zoning-envelope + acquisition form (lot,
  FAR, coverage, height, floor-to-floor, efficiency, unit size, land/hard-$/rent/cap) that runs
  MASSING-OPT and renders the ranked options — floors · units · GFA · yield-on-cost · profit · levers,
  with the **cost-vs-profit frontier** marked (✦) and a rank-by selector (yield / profit / units / net
  sellable). Stateless.
- **🔩 Equipment schedule** (construction › Build) — the MEP-EQUIP procurement schedule derived from the
  model: by-discipline tallies + the RFQ line-items (type · class · quantity · discipline · representative
  spec), ducts/pipes/fittings excluded.
- Both are lazy-imported panels wired into the portal nav + dispatch; typecheck + lint + build green.
  *(Live end-to-end not exercised — the dev preview's geometry stall + a frequently-stale local API gate
  interactive portal checks here; the panels mirror the proven asset/margin-card pattern and the backend
  routes are CI-covered.)*

## v0.3.581 — SPEC-CONFLICT: scheduled-vs-specified equipment cross-check (MEP-EQUIP phase-2)

Complete the MEP-EQUIP value prop — catch the "scheduled air-cooled unit vs. the spec's water-cooled
requirement" mismatch deterministically, by comparing the model's own Pset values (no doc-scanning).

- **`equipment.spec_conflicts(lines, requirements)`** — `requirements` is `{ifc_class: {spec_key:
  expected}}` over the canonical schedule spec labels; a **conflict** is a scheduled line whose Pset value
  disagrees with the spec (case-insensitive for strings; `expected` may be a list of acceptable values), a
  **missing** is a specified property the model doesn't carry. Pure over the schedule output.
- **`POST /projects/{pid}/model/equipment/spec-check`** runs the schedule then the cross-check → conflicts
  + missing + `units_in_conflict`. Client `equipmentSpecCheck`. `test_equipment` extended (conflict,
  case-insensitive match, missing, empty-requirements, route).
- *Next:* a curated starter requirement set + surfacing conflicts on a procurement panel / RFQ export.

## v0.3.580 — MEP-EQUIP: procurement equipment schedule from the IFC (R16 Tier-1)

Derive the RFQ equipment schedule straight from the model — no doc-scanning, because we own the model.

- **`equipment.py`** + `GET /projects/{pid}/model/equipment`: groups the procurable MEP units
  (`IfcEnergyConversionDevice` / `IfcFlowMovingDevice` / `IfcFlowStorageDevice` /
  `IfcFlowTreatmentDevice` / `IfcFlowController` / `IfcFlowTerminal` / `IfcTransportElement`, subtype-
  resolved) by **(class, type)** into **RFQ line-items with a quantity**, a representative spec pulled
  from the model's Psets (manufacturer / model / capacity / power / flow / voltage), and the unit GUIDs;
  plus by-discipline / by-class tallies. Ducts/pipes/fittings and controls are excluded (installed
  material / commissioned, not scheduled units). Where ASSET-REG lists every asset one-per-GUID for FM,
  this rolls them up for buyout.
- Client `modelEquipment`. `test_equipment` covers the type-grouping (two same-type terminals → one line,
  qty 2), the pump as its own line, duct exclusion, descending-quantity sort, and the 409.
- *Next:* SPEC-CONFLICT — a `rule_library.py` cross-check of each line's Pset values against a specified-
  requirement set (the scheduled-vs-specified mismatch catch) + a procurement panel / RFQ export.

## v0.3.579 — security: generic proforma solve-error, clearing the CodeQL alert

The actual sink behind the `py/stack-trace-exposure` alert: `_proforma_seed` caught a broad `Exception`
from the proforma solver and returned **`solve_error: str(e)`** in the response — that exception string
flowed out through `/generate/massing/preview`'s return. It now returns a **fixed note** ("the starter
proforma could not be solved") instead. Also hardened the remaining `/generate/massing` envelope 422 to the
same controlled `_ENVELOPE_422` message (v0.3.578 covered the preview + optioneer routes but not this one).
`test_generate` green. (v0.3.578 addressed a related `str(e)` path but not the flagged one — this clears it.)

## v0.3.578 — security: no exception string in the massing 422s (CodeQL)

CodeQL flagged `py/stack-trace-exposure` (medium) after the MASSING-OPT push: the new `/massing/optioneer`
route added a data-flow path in which a `ValueError` from `compute_massing` reached the HTTP response via
`str(e)` — the same pattern the older `/generate/massing/preview` route used. `compute_massing` only ever
raises one controlled validation message, so both routes now return a **fixed 422 detail** (`_ENVELOPE_422`)
instead of flowing the exception string to the client. Behaviour unchanged (still 422 on a bad envelope);
CodeQL back to 0 open alerts.

## v0.3.577 — UX-ACT: actionable inline diagnostics (UX-POLISH ring)

The first UX-POLISH build — pair a computed diagnostic with a one-click action next to it, instead of
leaving it a passive read-only number. We already compute the exposure; now you can act on it in one click.

- **`resolve_hint.py`** — a shared, tiny **resolve-action vocabulary** (`open_module` · `navigate` ·
  `open_record`) so every actionable feed emits the same descriptor shape and the portal renders them
  uniformly. Pure, no I/O.
- **MARGIN-CBS** now attaches an `actions` list to each flagged cost-code row: an **over-budget** code
  gets a "Review direct costs" jump, an **over-committed** code gets a "Review commitments" jump — each
  **pre-filtered to that cost code** so the PM lands on exactly the records behind the flag instead of
  hunting. A healthy code carries none. `test_margin` covers the descriptor shape + filter.
- **Portal** — a shared `dispatchResolveAction` / `resolveActionButtons` (in the margin panel module,
  reusable across the ring) renders the actions as inline buttons in a new **Fix** column on the 📒
  Cost-code Margin card; clicking one opens that module's records filtered to the code. `ResolveAction`
  type + client wiring.
- *Next:* extend the same action descriptors to the rule-run violations and schedule-conflict feeds.

## v0.3.576 — MASSING-OPT: the layout/massing optioneer (R16 Tier-1)

The literal "Massing" play — deterministically enumerate envelope options over a zoning envelope and rank
them by developer yield, mirroring the schedule optioneer but for the massing stage.

- **`layout_options.py`** — `optioneer(envelope, levers?, objective?, limit?)` sweeps the levers a
  developer turns early — **floor-to-floor · core efficiency · coverage strategy (podium vs. tower) · unit
  size/mix** — running each combination through the deterministic `massing.compute_massing` zoning→program
  engine, then scores each option with a transparent **yield-on-cost proforma** (NOI ÷ total cost, from the
  land + hard-$/sf + rent + cap-rate assumptions already on the envelope). Returns the options **ranked by
  objective** (`yield_on_cost` | `profit` | `units` | `net_sellable`) plus a real **Pareto cost-vs-profit
  frontier** (an option is on the frontier if no other is both cheaper *and* more profitable). Duplicate
  programs collapse; the base envelope is validated up front (a bad lot → 422).
- **`POST /massing/optioneer`** — stateless: no IFC is written (authoring the winning massing via the
  blank-IFC → levels/grid → walls/slabs recipe chain is the phase-2 emission). Client `massingOptioneer`.
  `test_layout_options` checks feasibility, yield math, the objective switch, and frontier non-domination
  (no frontier option beaten on both axes; a tighter floor-to-floor fits more floors under the height cap).
- *Next phase:* emit each option as a GUID-stable edit-recipe chain + a 🧮-style comparison panel.

## v0.3.575 — RECIPE-MACROS: save a chained edit-recipe as a named, parameterized command (R16 Tier-1)

The reuse multiplier the GUID-stable edit-recipe spine was built for — capture your standard assemblies
as commands instead of re-typing the same step sequence.

- **`macros.py`** — a macro is an ordered list of authoring-recipe steps (the same `{recipe, params}`
  shape `/edit/batch` runs) with **declared parameters** its steps reference as `${name}` placeholders.
  `expand(macro, args)` resolves placeholders + declared defaults into a concrete step list — pure and
  **model-free**, so a client can preview/validate before it ever touches the model. Type-preserving: a
  bare `"${x0}"` keeps its numeric/list value (a `[x,y]` point survives, not just strings); embedded
  placeholders string-interpolate. A required param with no value raises.
- **Routes** on the authoring router: `GET /projects/{pid}/macros` (saved library, falls back to a
  starter set), `PUT /projects/{pid}/macros` (validates **every step's recipe name against the edit
  engine's registry** before writing — a bad macro rejects the whole save 422, no partial overwrite),
  `POST .../macros/{id}/expand` (model-free preview), and `POST .../macros/{id}/run` (expands with args
  and applies the whole chain as **ONE GUID-stable version** — the same read→apply→pointer-swap
  `/edit/batch` uses, one edit-history entry so the macro undoes as a single step, honoring the COLLAB-1
  optimistic lock via `base_source`).
- Storage mirrors the rule library — one validated JSON blob per project with caps (≤100 macros, ≤60
  steps, ≤40 params) so a stored macro can't be amplified into an unbounded apply. Client
  `listMacros`/`saveMacros`/`expandMacro`/`runMacro` + the `EditMacro` type. `test_macros` covers
  substitution, defaults, atomic bad-recipe rejection, and the list/expand/run round-trip.
- *Next phases:* mirror macro-run into the CADCMD command line + MCP, and a headless `massing` CLI with
  a `massing check` CI gate.

## v0.3.574 — ASSET-REG: maintainable-asset register from the IFC (R16 Tier-1)

The second R16 build — derive the FM handover register straight from the model, deterministically (because
IFC is our source of truth), so it isn't hand-entered.

- **`model_assets.py` + `GET /projects/{pid}/model/assets`**: selects the maintainable serviceable assets
  from the IFC by class (subtype-resolved — `IfcEnergyConversionDevice` / `IfcFlowMovingDevice` /
  `IfcFlowController` / `IfcFlowTerminal` / `IfcFlowStorageDevice` / `IfcFlowTreatmentDevice` /
  `IfcDistributionControlElement` / `IfcTransportElement`, **excluding ducts/pipes/fittings** — you maintain
  the unit, not the duct run), GUID-keyed with discipline (`classification.py`) + storey + type + a coarse
  category, with per-discipline / per-category / per-class tallies.
- **`POST /projects/{pid}/model/assets/seed`** (editor): populates the shipped `asset_register` module from
  the derived assets, **idempotent by tag** (`{ifc_class}-{guid8}`) — one call turns the IFC into a
  populated FM register, ready for `pm_schedule` preventive maintenance + warranty/serial per asset.
- **🔧 Asset Register** portal destination (Operations nav, shown when the project uses the `asset_register`
  module): count + by-category/discipline chips + a "seed from model" button + the asset list. Client
  methods `modelAssets` / `seedModelAssets`. `test_model_assets` covers the class selection (terminals +
  pump + elevator in, duct out), tallies, the 409, and the idempotent seed.

## v0.3.573 — MARGIN-CBS: per-cost-code margin reconciliation (R16 Tier-1)

The first R16 build — the highest-value GC-portal item from the research pass: per-cost-code margin
reconciliation, done deterministically over our own cost modules.

- **`margin.py` + `GET /projects/{pid}/margin/by-costcode`**: one reconciliation view keyed on cost code
  that ties the portal's separate cost modules together — **budget** (revised control number) vs
  **committed** (subcontracts/POs) vs **actual** (direct costs) vs **billed** (sub invoices) — and computes
  per code the projected **buyout margin** (budget − committed), the **cost variance** (budget − actual),
  and **over-committed / over-budget** flags, sorted worst-margin first, with project totals.
- **📒 Cost-code Margin** portal destination (Cost/Budget nav group, shown when the project uses the
  `cost_code` module): a buyout-margin headline + a per-code table (budget/committed/actual/margin/variance,
  over-committed rows flagged). Client method `marginByCostCode`.
- Pure over the module records (tolerant currency parsing, guarded); `test_margin` covers the under/over-
  budget split, worst-first ordering, totals, empty + 404.

## v0.3.572 — Roadmap: R16 external-scan upgrade ring

Synthesized a web scan of 14 AEC/proptech products + 4 dev/skills
resources (css-protips, frontend-dev-bookmarks, awesome-claude-code, Anthropic-Cybersecurity-Skills)
into a new **🔬 R16 ring** in [docs/roadmap.md](docs/roadmap.md), with per-item engine/endpoint/module
specifics and BUILD / INTEGRATE / SKIP tags. Highlights: **MASSING-OPT** (a layout optioneer mirroring the
schedule-optioneer pattern), **MARGIN-CBS** (per-cost-code committed/billed/earned margin), **ASSET-REG +
PM-OPS** (asset register + preventive maintenance from the IFC), **MEP-EQUIP + SPEC-CONFLICT**,
**RECIPE-MACROS + a headless `massing` CLI** with a `massing check` CI gate, plus MEP auto-fittings,
RFQ quote-leveling, test-fit adjacency rules, a live design-metrics/daylight panel, a productivity-actuals
loop, and Tier-3 CSS/security/DX hardening. The recurring strategic note: because IFC is our source of
truth, we skip the "reconstruct structured data from unstructured inputs" problem most of these products
spend their AI budget on. The ▶ NOW list is re-topped with the three highest-value R16 Tier-1 picks.

## v0.3.571 — SCHED-OPT: Pareto frontier chart (SPRINT B phase-4b, part 1)

- The 🧮 Schedule-optioneering card now renders a compact **cost-vs-duration scatter**: every scenario is
  a dot (faint off-frontier, filled on the Pareto frontier), the **recommended** option is ringed (⊙), the
  **baseline** is a square (▢), and the frontier is drawn as a dashed line — so the time/cost tradeoff and
  which options are non-dominated read at a glance, beside the ranked table. Pure SVG, theme-aware.
- Frontend-only over the existing `/schedule/optioneer` data. *(CPM-driven crew shifts off the critical
  path — the other half of phase-4b — remain a backend follow-up.)*

## v0.3.570 — VERSION-COMPARE per-property (R15 tail)

The model version diff now names the **exact** properties/quantities that changed, not just "properties
changed".

- `versions._fingerprints` gained a 7th position — a flat **per-property hash map**
  (`{"SetName.PropName": value_hash}`) over each element's Psets + Qtos. Each is a short hash, so the
  stored version blob stays bounded (no raw values), and it reuses the existing `fingerprints` JSON
  column (**no migration**). Older versions store only positions [0..5] and degrade gracefully.
- `versions.diff` now attaches **`changed_properties`** to each modified element — the sorted keys whose
  hash differs, each tagged **added / removed / changed** — plus a top-level `property_detail_available`
  flag. The viewer's version-compare list appends the named keys after the change labels (e.g. "properties
  changed — Pset_WallCommon.FireRating, Qto_WallBaseQuantities.NetSideArea").
- Names *which* properties changed (the remaining old/new *values* need a richer per-version snapshot, a
  separate stored-column follow-up). `test_versions` extended.

## v0.3.569 — SELECTIONS money card (SPRINT D phase-3c)

The selections & allowances rollup is now surfaced in the portal, completing the SPRINT D phase-3 thread
end to end.

- A **◈ Selections** destination (in the Cost/Budget nav group, shown when the project uses the
  `selection` module): a headline **net over/under** vs. allowance, totals + priced/approved counts, the
  **per-category signed deltas**, and the over-allowance **change-order candidates** — with a one-click
  **"→ Push overages to change events"** button wired to the idempotent `/selections/push-change-events`.
- Frontend-only over the already-shipped, tested `/selections/summary` + `/selections/push-change-events`
  endpoints (v0.3.565–566); build/typecheck-verified (the preview stall limits live click-testing).

## v0.3.568 — Docs & demo refresh to current state

Brought every doc and the offline demo up to the v0.3.543–567 wave.

- **Roadmap reconciled** — the whole ✅-completed wave (quick-wins, SPRINT B Schedule Optioneering,
  SPRINT MB Master Builder + the skill, SPRINT D Client-Portal, SPRINT E rebar bending, SOLVER-OUT,
  RT-ORJSON, the hardening + security bumps) moved into `roadmap-completed.md`; `roadmap.md` rewritten
  fresh with **open items only**, re-prioritized around a bounded backend-testable NOW list (VERSION-COMPARE
  per-property, IFCPATCH-LIB, BCF-API-SRV depth, the SPRINT D/B/MB continuations) + the big-ticket tracks.
- **README** — new lead "Recent platform work" entry for the wave (schedule optioneering, the Master
  Builder brief + in-repo skill, the client-portal + selections/allowances, Code_Aster export, the
  model-warnings feed).
- **GitHub Pages** — `index.html` (GC-portal capability card updated: 130 modules, schedule optioneering,
  client-portal, selections & allowances, Master Builder brief; BIM card gains the model-warnings feed +
  the OpenSees/Code_Aster solver export) and `status.html` (release count refreshed; the second
  "Recently shipped" grid replaced with the current-wave cards). `status.md` watermark → v0.3.567, test
  count → 306.
- **Guide** — a "Recently added" callout covering the six new capabilities.
- **Demo** — `demoData.json` regenerated (970 fixtures) so the offline `/app/` demo renders the current
  feature set.

## v0.3.567 — SOLVER-OUT: Code_Aster mesh export (R15 tail)

A second independent structural-solver exchange beside the shipped OpenSees `.tcl`.

- **`fem_export.to_code_aster` + `GET /projects/{pid}/structure/code-aster.mail`**: exports the W10-7
  analytical frame as a **Code_Aster** mesh (`.mail`, ASTER text format, SI metres) — `COOR_3D` nodes,
  `SEG2` beam elements, a `BASE` node group (the fixed supports) and a `FRAME` element group. Same frame
  topology as the OpenSees export; a structural engineer can now independently verify the frame in
  Code_Aster (GPL) as well as OpenSees.
- Geometry/supports skeleton only — the engineer assigns the section (AFFE_CARA_ELEM), material, BCs on
  BASE, and the load case. A `⬇ Export Code_Aster (.mail)` button sits beside the OpenSees export in the
  structural tools; client method `codeAsterMailUrl`.

## v0.3.566 — SELECTIONS: push overages to change events (SPRINT D phase-3b)

Closes the selections → change-order → budget thread.

- **`POST /projects/{pid}/selections/push-change-events`** (`selections.push_to_change_events`): creates a
  **`change_event`** (reason *Allowance Reconciliation*, ROM = the overage) for every over-allowance
  selection that doesn't already have one — so the deltas flow into the change-order chain and the budget
  (via the change_event PCO rollups). **Idempotent** by a deterministic subject (`Allowance overage —
  {item} ({ref})`), so re-running only adds what's new — no duplicate change events.
- Each summary CO-candidate now carries its `change_subject` (the idempotency key). Client method
  `pushSelectionChangeEvents` wired.

## v0.3.565 — SELECTIONS: allowances → change-order candidates (SPRINT D phase-3)

Turns the owner's selections log into the money picture a builder actually manages.

- **`selections.py` + `GET /projects/{pid}/selections/summary`**: rolls up the `selection` records into
  allowance-vs-actual — total allowance, total actual, the **net over/under**, per-category signed deltas,
  approval count, and the **change-order candidates** (delta = actual − allowance; over is an add to the
  owner, under a credit) worst-first. Priced = selections with an actual cost entered.
- Tolerant currency parsing (`$1,200.50` → number), guarded so an unpriced or malformed selection is
  skipped rather than breaking the rollup; empty project → a zeroed summary. Client method
  `selectionsSummary` wired.

## v0.3.564 — CLIENT-PORTAL: public read-only share page (SPRINT D phase-2)

- **`GET /shared/{token}`** (public, no auth) now serves a **self-contained read-only HTML page** rendering
  the share digest — a readiness bar, the project + jurisdiction, and the 8 protocol steps with their
  status. A stakeholder opens the link and sees the project's readiness with no login and no app.
- **Every value is HTML-escaped** (`client_portal.to_html`), the page is marked `noindex,nofollow`, and it
  exposes only the same curated readiness data as the JSON digest — no record-level data. Covered by a test
  that a hostile project name (`<script>…`) is escaped, not executed.
- The 🔗 Share section in the 🏛 panel now links to the human HTML page (`sharedPageUrl`).

## v0.3.563 — CLIENT-PORTAL: tokenized read-only project digest (SPRINT D phase-1)

Opens the first external-stakeholder surface — a link an owner can hand out to see project readiness
without a login, without touching any record.

- **Share tokens** (`ShareToken` model + `client_portal.py`): an editor mints a **revocable, read-only
  share token** (a strong `secrets.token_urlsafe` secret) for a project — `POST/GET/DELETE
  /projects/{pid}/share-tokens` (editor-gated), bounded at 50 live tokens per project.
- **Public digest** (`GET /shared/{token}/digest`, **no auth** — the token is the credential): returns a
  **curated readiness digest** — project name, jurisdiction, the overall readiness score, and each
  protocol step's title + status. **Nothing else**: no findings detail, no GUIDs, no financials, no
  record-level data, no PII. An unknown or revoked token 404s (no enumeration signal); each view is
  counted on the token.
- **🔗 Share read-only** section in the 🏛 Master Builder panel: create a labeled link, see its view
  count, open it, and revoke it.
- Hard-railed by design (per the build-doctrine): the public surface is strictly read-only and exposes
  only what's safe to share, so a leaked token reveals a readiness summary and nothing more.

## v0.3.562 — MASTER-BUILDER: shareable Markdown brief (SPRINT MB phase-2b)

- `master_builder.to_markdown()` + `GET /projects/{pid}/master-builder/brief.md` (text/markdown): the
  8-step brief as a printable one-page document — readiness header, place grounding (jurisdiction, code
  family, coordinates, climate band), a section per protocol step with its ✅/🟡/⛔ status, findings and
  gaps, the hazards-to-verify list, and the honest-status disclaimer. A **⬇ Markdown** button in the 🏛
  panel downloads it (wired to `masterBuilderBriefMdUrl`).

## v0.3.561 — Security: clear the brace-expansion advisories

- Bumped the two vulnerable transitive `brace-expansion` instances (a ReDoS advisory) to their patched
  versions — `2.1.1 → 2.1.2` and `5.0.6 → 5.0.7` — via a lockfile-only `npm audit fix`. The three
  non-vulnerable `1.1.16` copies are untouched. `npm audit` now reports **0 vulnerabilities**, clearing
  the 2 high Dependabot alerts on the default branch. Build-tooling transitive deps only (eslint /
  redocly / jake), not in the shipped app bundle; no code change.

## v0.3.560 — FAB-DELIVER: rebar bending detail (SPRINT E phase-1)

The first fabrication-delivery slice — the human-read bending schedule a detailer and fabricator
actually work from, ahead of any machine format.

- The bar bending schedule (`rebar_rules.bar_bending_schedule` → `GET /projects/{pid}/rebar/bbs`) now
  carries **per-mark bending detail** off the authored bar geometry: **leg lengths** (mm), the
  **deviation/bend angle** at each interior vertex (degrees), the **bend count**, and a **shape family**
  (straight · single bend (L) · double bend (U/crank) · closed tie/stirrup · N-bend). The CSV export
  gains Bends / Legs / Bend-angles columns.
- Pure `rebar_rules.bending_detail(points, closed)` is unit-testable (an L-bar → 1 bend, two legs, a 90°
  corner; collinear points → 0 bends).
- **The BVBS/BF2D machine bending-file export is deliberately deferred**, held behind a validation gate:
  a byte-wrong bending file makes a machine mis-bend real steel, so per the fabrication-output doctrine it
  ships only once validated against the authoritative BVBS spec **and** a real importer. The `master-builder`
  skill (v0.3.2, `construction-delivery.md`) documents this honest boundary.

## v0.3.559 — Hardening pass over the v0.3.552–558 feature wave

Between-sprint adversarial bug-hunt + XSS/security hand-audit over the seven new releases (WARN-1,
NORM-VALID tails, SCOPE-GAP, GOLDEN-THREAD seed, SCHED-OPT phases 1–4a, Master Builder brief phases 1–2a).
No high-severity issue found — the frontend had **no XSS** (every model-derived string escaped), route
role-gating was sound, the optioneer's 800-scenario cap genuinely bounds enumeration, and the
division/zero paths were all guarded. Three concrete low-severity defects fixed:

- **Master Builder** — `_dms_to_deg` read the coordinate sign only from the degrees component, so a
  sub-degree southern/western site (e.g. IFC `[0, -30, 0]` = −0.5°) decoded as positive and reported the
  wrong hemisphere/climate band. Now the sign is taken from any DMS component (the IFC rule).
- **SCHED-OPT** — the optioneer engine now **normalises caller-supplied trades** (a null / non-numeric /
  string `takt_days`, a non-dict entry, or a nameless trade is coerced or dropped) and **value-clamps
  `floors` (≤ 2000) and zones (≤ 24)** before enumerating — a malformed or absurd body can no longer 500
  or attempt a multi-GB allocation. The route now returns **422** (not 500) for non-numeric
  `floors` / `zone_options` / `overlap_options` / non-list `trades`.
- **SCHED-OPT panel** — the recommended-scenario row highlight compared object identity (`s === rec`),
  which is never true across a JSON round-trip, so the row never highlighted; now matches on `rank`.

## v0.3.558 — MASTER-BUILDER: ground the brief in real coordinates (SPRINT MB phase-2a)

The Master Builder brief now grounds itself in the project's actual place, not just its jurisdiction.

- **Place-grounding** — the brief resolves the **code family** from the jurisdiction (a US state → ICC /
  IBC-derived) and, when the model is **georeferenced**, decodes the site's IFC lat/long (compound
  degrees-minutes-seconds) to derive the **hemisphere** and a broad **climate band** (universal physics).
  The place step now cites the real coordinates as a finding.
- **Hazards to verify locally** — per the ground-in-place doctrine, it never invents load values; it
  emits the list of location-specific parameters to read from the site's hazard basis (seismic Ss/S1,
  basic wind speed, ground snow, flood design elevation, energy-code climate zone) — the parameter to
  look up, marked for local confirmation. Surfaced as a collapsible "Verify locally" card in the 🏛 panel.
- The route feeds the brief the model's georeferencing best-effort (guarded); the engine stays pure
  (coordinates passed in, no I/O). `master-builder` skill co-evolved to v0.3.1 (`global-codes.md` §8
  documents the mechanized grounding).

## v0.3.557 — MASTER-BUILDER: the whole project in one brief (SPRINT MB phase-1)

A new synthesis that holds the entire project in one view — the software embodiment of the
Master Builder Protocol.

- **`master_builder.py` engine** + `GET /projects/{pid}/master-builder/brief`: runs the 8 protocol
  steps (place → program/HBU → feasibility → regulatory → design-integration → delivery → risk →
  handover) over the project's *own* data, **grounds the whole brief in the project's jurisdiction**
  (the field that resolves which code editions and hazard loads govern), and returns a per-step
  readiness status (`ready` / `partial` / `gap`) with the concrete gap and a link to the tool that
  closes it, plus an overall readiness score.
- It is a **synthesis over the platform's existing engines** — georeferencing, budget, schedule + bid
  packages, the compliance-evidence golden thread, the clash coordination log, the risk board, and the
  facility-condition/asset basis — reading the canonical signals, never re-deriving them. Every probe is
  guarded, so a missing module degrades a step to a gap rather than erroring.
- Honest-status boundary carried in the payload: a readiness synthesis over the data on hand is **not a
  substitute** for licensed engineering/architectural judgment, an AHJ plan check, or committed
  underwriting.
- **🏛 Master Builder** panel (Model & standards nav): a readiness header (score + grounded-in-place +
  the reframe prompt) and one card per protocol step (status pill, the "why", what's present, the gap),
  wired to `masterBuilderBrief`.
- Ships with the **`master-builder` skill** (`.claude/skills/master-builder`, v0.3.0) — the reasoning
  doctrine behind the feature; the skill's `build-doctrine.md` gained the "synthesis over sources of
  truth" principle and `digital-toolkit.md` now documents this endpoint as the protocol's reference
  implementation.

## v0.3.556 — SCHED-OPT: optimize the real project — takt train from the schedule (SPRINT B phase-4a)

The optioneer no longer always defaults to the residential takt train — it now **derives the trade
train from the project's own schedule** when one exists.

- When the `/schedule/optioneer` request omits `trades`, the route builds the takt train from the
  project's `schedule_activity` records: group by trade, sum each trade's duration, and set its
  per-floor takt = total ÷ floors; trades order by earliest start (a stable, schedule-honouring
  sequence). Falls back to the residential takt train when there's no usable schedule (< 2 trades with
  duration).
- The response carries `trade_source` (`body` / `schedule` / `default`) and the panel's recommended
  line names it ("… N trades from your project schedule"), so it's clear the optioneer is optimising
  real project data — not a generic template.

## v0.3.555 — SCHED-OPT: scenario-comparison panel (SPRINT B phase-3)

Surfaces the optioneer in the Schedule workspace so the ranked scenarios are usable, not just an API.

- A **🧮 Schedule optioneering** card on the Schedule panel: a **▶ Run** control with a weighting
  selector (Balanced / Fastest / Cheapest) and a fast-track toggle, a **recommended-plan summary**
  (duration, cost, peak crews, saving vs. baseline, its lever mix), and a **ranked scenario table**
  (top 12 — levers, days, cost, peak crews, Pareto-frontier marker) with the recommended row
  highlighted. Wired to the `scheduleOptioneer` client method.
- Frontend only (no backend change) — verified by typecheck / lint / build; the card renders even
  without a model (defaults to the residential takt train), so it's exercisable on any project.

## v0.3.554 — SCHED-OPT: widen the search — fast-track overlap + sequence permutation (SPRINT B phase-2)

Widens the optioneer's search space with two more levers, so the enumerated frontier spans real
schedule-compression moves — not just crews and zoning.

- **Fast-track overlap** — a scenario lever (`overlap_options`) where a successor trade may start a floor
  when its predecessor is `1-overlap` complete (rather than fully finished), while still never *finishing*
  a floor before its predecessor. Compresses the makespan at a **rework-risk premium** proportional to the
  overlap fraction, so fast-tracking shows up as a distinct time/cost tradeoff on the Pareto frontier.
  `overlap=0` reproduces the strict finish-to-start line-of-balance exactly (backward-compatible default).
- **Sequence permutation** — opt-in (`permute_sequence`): trades flagged `reorderable` are permuted among
  their own slots while fixed trades stay put (e.g. Structure keeps leading), surfacing whether a different
  trade order shortens the run. Bounded — capped at 4 flexible trades / 6 sequence variants.
- The whole grid (crews × zoning × overlap × sequence) is **hard-capped at 800 scenarios** with the
  truncation reported (`truncated`), never silent. The result now carries a `levers` summary
  (zones / overlaps / sequence-variant count / crew candidates).
- Deterministic and pure throughout; `test_schedule_options` extended to cover both new levers +
  the bound. Client method `scheduleOptioneer` accepts the new options.

## v0.3.553 — SCHED-OPT: deterministic schedule optioneering (SPRINT B phase-1)

First slice of the schedule-optioneering track — permute the construction plan and score the options,
the way a dedicated optioneering tool does, but exactly and offline because our inputs (the Takt trade
train + per-floor production rates) are already present.

- **SCHED-OPT engine** (`schedule_options.py`) + `POST /projects/{pid}/schedule/optioneer`: enumerates a
  bounded crew-loading + work-face-zoning option grid over the Takt line-of-balance model and ranks every
  scenario. Levers: a **second crew** on the bottleneck (slowest) trades — halves that trade's
  days-per-floor at a mobilisation premium; and **zoning** — splitting each floor into Z work-face zones
  lets the train pipeline tighter (shorter makespan) at the cost of more concurrent crews + a per-zone
  setup. Work content is conserved across scenarios, so the enumerated tradeoff is schedule compression +
  peak congestion vs. a crew premium — the real buyout question.
- Each scenario carries makespan (days/weeks), peak concurrent crews, labor crew-days, and cost; the
  result ranks by a min-max-normalised weighted **time + cost score**, flags the **Pareto frontier** (not
  beaten on both time and cost), and returns a **recommended** option + its saving vs. the single-crew /
  one-zone baseline. Weighting toward cost keeps the baseline; toward time picks a compressed option.
- Deterministic and pure (no solver, no randomness) — fully unit-tested. Client method `scheduleOptioneer`
  wired; the scenario-comparison panel is the phase-2 follow-up.

## v0.3.552 — Quick-wins sprint: model-warnings feed + check-lane depth

A batch of low-risk, high-clarity refinements across the model-quality and coordination engines —
cleaning up the small items before the big-ticket sprints.

- **WARN-1 — unified model-warnings feed** (`GET /projects/{pid}/models/warnings`): a new
  `model_warnings.py` engine flattens every individual defect the hygiene lens (`model_qa` —
  duplicate GUIDs, orphans, overlapping duplicates, unenclosed spaces, blank names, wrong-storey)
  and the normative-conformance lens (`norm_valid`) surface into one worst-first punch list —
  fails before warns, each row carrying its offender sample for zoom-to-GUID. Where the model-CI
  badge says pass/warn/fail, this is the actionable list behind it.
- **NORM-VALID tails** — the conformance gauntlet gains two lanes: a STEP-syntax check that the
  ISO-10303-21 `FILE_NAME` header carries a name + timestamp, and a bSDD/classification-coverage
  check reporting the share of physical elements associated to a classification reference
  (pass ≥ 50%, else warn).
- **SCOPE-GAP spec-section refinement** — bid-package coverage now unions the CSI spec sections
  each covering package cites and surfaces them per discipline; a discipline covered by a package
  that names **no** spec section is flagged as `covered_without_specs` (thin, non-traceable
  coverage) — distinct from a true scope gap.
- **GOLDEN-THREAD seed** (`POST /projects/{pid}/golden-thread/seed`): populate the compliance-
  evidence ledger from the latest model-CI report — each check becomes a tracked requirement
  (outcome mapped from its status) so the thread starts from the checks already run instead of a
  blank slate. Idempotent — re-seeding after a fresh run only adds what's new.
- **DRAW-STATUS** — the drawing module gains a `lifecycle` field (Not Issued · Issued for
  Construction · Shop Drawing · As-Built), surfaced in the drawing list, distinct from the
  revision-status field.

## v0.3.551 — Hardening pass over v0.3.544–550

- Between-sprint adversarial bug-hunt + security hand-audit over the seven new engines (SCOPE-GAP,
  GOLDEN-THREAD, CLASH-TRIAGE XML, GIS-OUT, CBS-1, MEP-GRAPH, the RT-ORJSON swap). No crash / hang /
  security hole found — the two priority suspicions (a possible `mep_graph` longest-path hang on a
  cyclic network; division-by-zero across the ratio helpers) were both **verified safe** (BFS-parent
  reconstruction can't loop; every ratio is `if total else 0.0`-guarded). Three low-severity items fixed:
  - **GIS-OUT** — the near-pole longitude-scale guard was dead code (`cos(90°)` is `6e-17`, not `0`, so
    `or 1.0` never fired); now `max(..., 1.0)` clamps it so a site near the poles can't blow up the transform.
  - **CLASH-TRIAGE** — `_write_issues` no longer pops `_guids` off the caller's parsed rows (reads instead),
    so a future "parse once, write twice" caller can't silently lose the model-GUID anchoring.
  - **CLASH-TRIAGE** — the Navisworks XML import now rejects an over-large upload (>50 MB) before building
    the DOM, bounding memory (the row cap already bounded the created issues).

## v0.3.550 — RT-ORJSON remainder: orjson at the hot storage-blob sites

- **Faster index loads.** The response serializer already used orjson (v0.3.511); this swaps the
  remaining hot `json.loads/dumps` at the storage-blob call sites — the per-project **props.json index
  load** (on every model-index cache miss) and the **scan cache** read/write — to orjson, with the same
  graceful stdlib fallback for an orjson-less venv. **Measured on a 924 KB props blob: `orjson.loads`
  1.7× (19.8→11.4 ms), `orjson.dumps` 4.8× (16.1→3.4 ms)** vs stdlib; `OPT_NON_STR_KEYS` +
  `OPT_SERIALIZE_NUMPY` mirror stdlib's acceptance of int keys and `numpy.float64`. First of the RUNTIME
  ring's measured-win S-items.

## v0.3.549 — MEP-GRAPH: port connectivity graph + run/path extraction

- **From "unconnected ports" to the actual network.** `GET /projects/{pid}/mep/graph` builds a
  first-class port graph over `IfcDistributionPort` (nodes = MEP elements, edges = the port-to-port
  `IfcRelConnectsPorts` connections from `connect_mep`) and extracts the connected **runs**: each with
  its endpoints (degree-1 terminals), branch points (degree ≥3), class tally, and the **longest linear
  path** — the index-run backbone a balancing engineer follows and the foundation a real path-based
  pressure-loss calc needs (vs. today's per-segment sum). Isolated elements (no connected port) are
  reported as the wiring gap. Sixth item off the re-prioritized roadmap (R14 Tier-2), closing the NOW
  batch. *(Parallel/stacked run generation — the geometry-authoring half — remains open.)*

## v0.3.548 — CBS-1: Cost Breakdown Structure over the model estimate

- **The estimator's layering, not the developer proforma.** `GET /projects/{pid}/estimate/cbs` takes
  the model's takeoff-priced **direct cost** and layers it through **indirect / general conditions →
  contingency (known risks) → management reserve (unknown-unknowns, a PMBOK layer held separately from
  contingency) → overhead & profit → taxes & fees**, each with its amount, rate and share of the total.
  Every rate is overridable via query. Surfaced as a **🧱 Cost breakdown (CBS)** button in the Budget
  panel's model-estimate group. Fifth item off the re-prioritized roadmap (R14 Tier-3); conceptual-grade.

## v0.3.547 — GIS-OUT: BIM footprint → WGS84 GeoJSON

- **Drop the model onto a real map.** `GET /projects/{pid}/models/footprint.geojson` exports the
  building footprint (plan bounding box) + a site point as a **WGS84 GeoJSON FeatureCollection**,
  anchored on the model's `IfcSite` reference lat/long and transformed from local metres with a
  dependency-free **equirectangular local-tangent** approximation (rotated by the model's true-north
  bearing) — building-scale accurate, no pyproj. `available` is false when the model carries no site
  lat/long. Complements the inbound CityGML→GeoJSON site-context import. Fourth item off the
  re-prioritized roadmap (R14 Tier-3).

## v0.3.546 — CLASH-TRIAGE: import native Navisworks clash-report XML

- **The other standard clash export.** The XLSX clash-report importer already shipped; this adds the
  **native Navisworks XML** format (the `smart:` namespace `<clashresult>` export coordinators produce
  straight from Navisworks). `POST /projects/{pid}/coordination/import-xml` parses each clash into a
  `coordination_issue` — name → subject, its clash test → discipline, clash type/distance/status →
  description, and both element GlobalIds harvested from the `clashobjects` so it anchors on the model
  and round-trips to BCF. Namespace-agnostic and tolerant; untrusted XML is parsed with **defusedxml**
  (XXE / entity-expansion hardened). Third item off the re-prioritized roadmap (R14 Tier-3).

## v0.3.545 — GOLDEN-THREAD: the compliance evidence ledger

- **Every requirement traced to evidence + a sign-off.** A new **Compliance Evidence** register (one
  record per requirement → outcome → responsible party → evidence artifact, on an `open → evidenced →
  sign-off` workflow) plus `GET /projects/{pid}/golden-thread` — the rollup: how complete the thread is
  (**signed-off %**), the outcome/category spread, and the **broken-thread list** — requirements still
  missing evidence or a sign-off, ranked worst-first (a failed or pending requirement with no evidence
  attached is the top risk). Extends the point-in-time preflight/code checks into an auditable, versioned,
  sign-off-tracked record. Second item off the re-prioritized roadmap (R14 Tier-2). *(A dedicated
  golden-thread rollup panel is the open UI follow-up; the ledger records edit via the Quality workspace.)*

## v0.3.544 — SCOPE-GAP: does every element land in a bid package?

- **The scope hole a GC finds at buyout, found at precon.** `GET /projects/{pid}/bidding/scope-gap`
  maps the model's takeoff (grouped by NCS discipline) against the project's `bid_package` records and
  flags **gaps** — disciplines present in the model with *no* covering package, i.e. quantities not in
  any bid yet (with sample GUIDs to click-highlight the uncovered elements) — a covered-percentage, and
  **over-scoped packages** whose discipline has no model elements. Distinct from the ITB bid-*response*
  coverage. Surfaced under the Bidding leveling view as a **Model coverage** strip. First item off the
  freshly re-prioritized roadmap (R14 Tier-2).

## v0.3.543 — Docs refresh, roadmap reconciliation & dev-console polish

- **Roadmap reconciled + re-prioritized.** The R15 ring and the shippable R14 tiers are fully closed;
  the v0.3.510–542 wave moved to [roadmap-completed.md](docs/roadmap-completed.md) and `roadmap.md` was
  rewritten as a fresh, open-items-only backlog (NOW: SCOPE-GAP · GOLDEN-THREAD · CLASH-TRIAGE · GIS-OUT ·
  CBS-1 · MEP-GRAPH; a RUNTIME ring; R15/R14 tails; the flagship-L builds; decomposition + P2 carry-overs).
- **Docs brought current.** README's "recent work" recap now covers v0.3.413–542; `status.md` corrected
  (stale version + test count + the obsolete "authoring needs Blender" framing — in-browser authoring ships
  as server-side recipes); marketing one-liners gained the structural-solve/OpenSees, NORM-VALID, BEP-GEN,
  subset-export, range-estimate, revision→cost, and live-BCF entries. Pages demo snapshot regenerated.
- **Dev console fix.** The Vite dev "Multiple instances of Three.js" warning is silenced by also excluding
  `three` from `optimizeDeps` (the `@thatopen/*` packages import it raw, so pre-bundling the app's own copy
  loaded a second instance in dev) — with `resolve.dedupe: ["three"]`, every importer now shares the one
  `node_modules/three`. Production was already single-instance via `manualChunks`.

## v0.3.542 — EST-BANDS: range estimate (low / likely / high → probabilistic bid range)

- **A conceptual estimate is a range, not a number.** `GET /projects/{pid}/estimate/bands` prices the
  model's takeoff and puts a three-point **low / likely / high** band on every line from design-stage
  cost uncertainty by discipline (structure ±15%, MEP ±30%, sitework ±35%, …). It rolls up two ways: a
  **correlated envelope** (every line at its extreme together — the worst/best case) and an
  **independent probabilistic P10 / P50 / P90 bid range** (a CLT normal approximation of the summed
  per-line triangular distributions, which diversification tightens inside the envelope). Overlay a
  firm rate sheet by passing `overrides`. Surfaced as a **📊 Range (low/likely/high)** button in the
  Budget panel's model-estimate group. Conceptual-grade — not a bid.
- **Dev CORS fix.** The API's default `AEC_CORS_ORIGINS` now trusts **both** `http://localhost:5173`
  and `http://127.0.0.1:5173` — they're distinct CORS origins, and since the web app's default API URL
  is the `127.0.0.1` form, a dev opening the app at `127.0.0.1:5173` was previously blocked by CORS even
  with the API running. (Production is unaffected — same-origin via the nginx `/api` proxy.)

## v0.3.541 — MEETINGS: link action items to RFIs & issues

- **Minutes that trace to the record.** Meeting **action items** could reference their source meeting;
  they can now also link a **Linked RFI** and a **Linked Issue**, so a flagged action captured in
  minutes traces to the RFI or coordination issue it concerns — and each RFI/issue shows the action as
  an incoming reference in its related view. This closes the last MEETINGS sub-item (the meeting series,
  agenda→minutes, and action-item register were already in place).

## v0.3.540 — TRANSMIT-ITP: Inspection & Test Plan register

- **The QA plan, not just the results log.** Added an **Inspection & Test Plan** register — one record
  per planned inspection/test on a work activity, with the ITP essentials: the inspection point type
  (**Hold Point** / Witness Point / Review / Surveillance / Monitor), method, **acceptance criteria**,
  frequency, responsible + verifying party, and the record/form required. Its `planned → active →
  verified` workflow models a hold point releasing work and gates verification on acceptance criteria
  being set. This complements the existing `inspection` module (which logs field *results*) and closes
  the remaining TRANSMIT-ITP gap — numbered transmittals, the submittal review-matrix routing, and the
  supplier-deliverables register were already covered by the `transmittal` and `submittal` modules.

## v0.3.539 — PM-CLOSE: project charter + lessons-learned register

- **Closing the PMBOK process-group spine.** Two new config-driven registers on the module engine:
  a **Project Charter** (Preconstruction / initiating) — sponsor, business case, SMART objectives,
  scope in/out, budget authority, milestones, assumptions/constraints/risks, stakeholders, with a
  `draft → in_review → approved` authorization workflow — and a **Lessons Learned** register
  (Closeout / closing) — one record per lesson with category, phase, impact, root cause and a
  feed-forward recommendation, on a `logged → reviewed → adopted` workflow. Both appear automatically
  in their workspace nav (construction + developer) with generic CRUD, import, search and the SLA feed.

## v0.3.538 — ROLES-BIM: ISO 19650 information-management responsibility template

- **The BIM-org, not just the construction org.** The responsibility matrix's four starter templates
  were all construction/PM-oriented (design delivery, buyout, execution, closeout) over the same seven
  delivery-role columns. Added a **BIM information management (ISO 19650)** template that brings its own
  role columns — the BIM-org personas *Appointing Party · Information Manager · BIM Manager · BIM
  Coordinator · Task Team · QA/QC* — mapped across nine ISO 19650-2 information-management duties (EIR →
  BEP → CDE setup → authoring → federation/coordination → model QA → authorize → deliver → PIM→AIM
  handover). Templates may now declare their own `roles`, so applying it switches the matrix columns to
  the information-management org. Appears automatically in the existing Responsibility-matrix template
  picker.

## v0.3.537 — BEP-GEN: the BIM Execution Plan, generated from live config

- **The BEP is never a stale side-document.** `GET /projects/{pid}/bep` composes the ISO 19650 BIM
  Execution Plan from what the project *actually* has configured right now: standards + classification
  systems, information requirements (EIR/BEP/AIR coverage + IDS), the RACI responsibility matrix, CDE
  container state + metadata discipline, the source model's schema/exchange formats, and the
  model-quality acceptance gates (NORM-VALID / Model QA / IDS / change-control). Each section reports
  `configured` and degrades gracefully — a fresh project still yields a valid six-section skeleton that
  fills in as the team works, with a completeness roll-up. Surfaced as a **📘 Generate BIM Execution
  Plan** action in the CDE / Standards panel.

## v0.3.536 — REVISION-DELTA: the cost impact of a model revision

- **"What changed" → "what it costs."** `GET /projects/{pid}/versions/cost-delta?a=&b=` turns a
  version diff into a conceptual cost impact: **added** elements (present in the current model) are
  priced from the live quantity takeoff through the conceptual estimator; **removed** elements are
  counted by IFC class from the prior version's fingerprints (their quantities aren't stored, so they
  aren't priced); elements whose **quantity changed** are flagged for re-estimate (before/after
  magnitudes aren't both retained, so no automatic net is claimed). Honest about the version store's
  limits — a change-management aid, not a change order. Surfaced as a **$ Cost impact** button in the
  viewer's Version-compare tool, beside the 3D overlay.

## v0.3.535 — NORM-VALID: normative openBIM conformance gauntlet

- **Does this IFC *conform*, not just is it well-authored.** A validation gauntlet in the spirit of
  the buildingSMART validation service — `GET /projects/{pid}/models/norm-valid` runs header + schema
  + IFC implementer-agreement checks: a recognised `FILE_SCHEMA` and populated header, exactly one
  `IfcProject` carrying units + a geometric context, every `IfcRoot` GlobalId a valid & unique 22-char
  `IfcGloballyUniqueId`, OwnerHistory presence (required in IFC2X3, optional after), and no physical
  element left outside the spatial structure. Each check reports **pass / warn / fail**; `passed` is
  true when nothing fails (warnings don't block). Complements `model_qa` (authoring quality) and IDS
  (data completeness). Surfaced as a **📋 Normative validation** tool in the viewer's QA group.

## v0.3.534 — Harden the subset-export temp path (CodeQL py/path-injection)

- The `/export/subset.ifc` handler built its scratch filename from the URL `pid`
  (`subset-{pid}-….ifc`). Project ids are server-generated UUIDs, so this was not
  exploitable, but the taint tripped CodeQL's `py/path-injection`. The scratch file now
  comes from `tempfile.mkstemp` — a server-chosen path with no request input in it; `pid`
  survives only as the download filename in the `Content-Disposition` header.

## v0.3.533 — SUBSET-EXPORT: hand off a discipline slice as a standalone IFC

- **Selector → standalone IFC.** `GET /projects/{pid}/export/subset.ifc?query=<QUERY-DSL>` streams an
  IFC containing only the elements matching a selector (e.g. `IfcDuctSegment | IfcPipeSegment`,
  `discipline=Structural`) — the scope slice you hand a consultant. Every physical element outside the
  keep-set is removed via `root.remove_product` (which detaches its containment / opening / property
  relationships and purges the owned geometry); the spatial skeleton (project → site → building →
  storey → space) and shared units/contexts are preserved, so the slice is a valid, correctly-contained
  IFC with **GUIDs unchanged**. The export gates behind `require_export` like the source-IFC download,
  and runs on an uncached copy of the model so the shared in-memory index is never mutated. In the
  viewer's Query-select tool a **⬇ IFC** button downloads the slice for the current selector.

## v0.3.532 — FEM-EXPORT: analytical model → OpenSees (.tcl)

- **Third-party structural verification.** Export the W10-7 analytical frame as an OpenSees
  (`.tcl`) input file — dedup shared member endpoints into nodes, fully fix the base-level nodes,
  and write one `elasticBeamColumn` per member with a per-orientation geometric transform (a
  column's local axis is vertical, so it takes a different reference vector than a beam). Units are
  kip·inch·ksi; sections are nominal defaults, so the file is a runnable *geometry + connectivity +
  supports* skeleton an engineer re-sections and loads to independently verify the built-in
  gravity/lateral solver in a third-party FE solver. `GET /projects/{pid}/structure/opensees.tcl`
  streams the file (409 until an analytical model is derived); a **⬇ Export OpenSees (.tcl)** button
  sits next to the statics-solve tool in the viewer's structural panel.

## v0.3.531 — EST-ASSEMBLIES: cost-item unit-rate build-ups (R15)

- New **cost assemblies** — a unit rate composed from its component resources (labour crew +
  material + equipment + sub), the way an estimator actually builds a price, so the number is
  auditable and re-costs when a wage or material price moves. `GET /estimate/assemblies` returns a
  starter library (CMU wall, cast-in-place slab, metal-stud partition) with each rate pre-computed;
  `POST /estimate/assembly/price` builds up a rate from an `assembly_id` or a custom component list
  (`{resource, kind, qty, unit, unit_cost, waste_pct}`), supports per-resource `overrides`, and
  extends over a take-off `quantity`. Analytics panel gains a **Cost assemblies** table with a
  per-line quantity → total.

## v0.3.530 — SMART-VIEWS: clash-freshness (auto-flag stale coordination issues)

- Completes SMART-VIEWS: open **clash / coordination issues whose referenced elements changed**
  between two model versions are surfaced as likely-stale (resolved, moved, or worse).
  `GET /projects/{pid}/coordination/stale?a=&b=` lists them (reusing the version diff's
  added/removed/modified GUIDs against each topic's `element_guids`);
  `POST .../coordination/stale/recheck` flags each with a `model-changed` label + a re-verify comment.
  Deliberately **advisory — never auto-closes** (a changed element doesn't prove a clash is gone), and
  idempotent.

## v0.3.529 — BCF-API-SRV: viewpoints over the API (R15)

- The BCF-API 2.1 surface gains **viewpoints** — the camera + selection + snapshot that make a topic
  navigable in 3D. `GET/POST /bcf/2.1/projects/{pid}/topics/{guid}/viewpoints` map our camera
  (`position`/`target`) to the BCF `perspective_camera` (`camera_view_point` + unit
  `camera_direction`), `components.selection` / `visibility.exceptions`, and clipping planes; the PNG
  snapshot streams from `.../viewpoints/{vguid}/snapshot`. A viewpoint created over the BCF-API is the
  same row the native viewpoint route returns — completing the BCF sync-object set
  (topics · comments · viewpoints) external managers need.

## v0.3.528 — BCF-API-SRV: live BCF-API 2.1 (OpenCDE) endpoints (R15)

- New **server-side BCF-API 2.1** surface (`routers/bcf_api.py`) so external BCF managers — Revit,
  Navisworks, Solibri, BIMcollab, usBIM — connect and sync issues live instead of exchanging
  `.bcfzip` files. `GET /bcf/versions` negotiates the version, `GET /bcf/2.1/auth` advertises the
  token URL, `GET /bcf/2.1/projects` lists accessible projects, and topics (list / get-by-guid /
  create) + comments (list / create) map the standard BCF-API JSON — `topic_type`, `topic_status`,
  `assigned_to`, `creation_author`, `labels` — directly onto the existing `Topic` / `Comment` rows.
  A topic created over the BCF-API is the same row the native `/projects/{pid}/topics` returns (and
  round-trips through `.bcfzip` export), reusing the platform's Bearer-token auth + role gates.

## v0.3.527 — IFCPATCH-LIB: one-click model maintenance recipes (R15)

- New **model cleanup** — deterministic maintenance passes that remove dead data an IFC accumulates:
  **purge orphaned property sets** (an `IfcPropertySet` attached to no element or type — its owned
  properties go with it) and **purge empty groups** (a plain `IfcGroup` with no members; never
  systems / zones). Both are GUID-stable for kept elements, so pins / RFIs / clashes survive.
- `GET /projects/{pid}/model/maintenance` is a **dry-run scan** (what each recipe would remove, with
  a sample) — the recipes ride the existing `POST /edit` apply→republish pipeline
  (`purge_orphan_psets` / `purge_empty_groups`, both idempotent). New **🧹 Model cleanup** viewer tool
  scans and runs each purge with a live count.

## v0.3.526 — VERSION-COMPARE-3D: pick-any-two version overlay (R15)

- The viewer's version tool becomes a real **version compare**: pick **any two** published versions
  (not just the latest pair) and get the added / removed / modified summary plus a **◉ Overlay in 3D**
  that colours added elements green and modified elements amber in the loaded model (with a reset).
  Modified elements still list their change labels (renamed · reclassified · retyped · re-leveled ·
  properties · quantities) and select in 3D on click. Frontend-only — the per-version snapshot diff
  (`GET /versions/diff`) already shipped.
- **Security**: `smart_views.run` no longer echoes a `QueryError` string into its response (the saved
  selector is validated at save, so the branch is defensive) — clears a `py/stack-trace-exposure`
  CodeQL finding.

## v0.3.525 — SMART-VIEWS: saved property-driven view presets (R15)

- New **smart views** — user-authored, per-project saved view presets over the model (the
  Solibri/Navisworks "saved search → view" staple). Each is a name + a QUERY-DSL selector + a display
  mode (**isolate / colour / hide**) + an optional colour, persisted with the project. The **★ Smart
  views** viewer tool lists them, applies one (isolates / colours / hides the resolved elements in
  3D), and saves the current selector as a new preset. Built entirely on QUERY-DSL (`query_dsl.select`)
  + the storage sidecar — cheap glue, not a new subsystem.
- Endpoints (`GET/PUT /projects/{pid}/smart-views`, `GET …/{vid}/run`): selectors are validated at
  save (a bad selector rejects the whole set atomically with 422, never clobbering the saved views);
  caps on count/length + hex-checked colours (HARDEN pattern).

## v0.3.524 — CLOUD-BRIDGE: optional online licence validation (massing.cloud)

- New **massing.cloud licence bridge** (`license_cloud.py`) — the "online check" the licensing module
  always anticipated. Off by default (offline-first): the recorded plan is authoritative on its own,
  so a cloud outage never locks a paying operator out. When enabled, the app validates the recorded
  key against `POST {base}/validate` with the shared `X-Massing-Secret`, normalizes the verdict
  (unknown tier → free), and — via the admin **`POST /license/cloud-check`** (+ a *☁ Validate online*
  button in the licence panel) — writes the cloud-confirmed plan back to Settings. An explicit
  `valid:false` downgrades to Free; an unreachable cloud changes nothing.
- The shared secret lives only in the operator's config (`MASSING_CLOUD_SECRET`, a **secret** setting)
  — masked in the Settings catalog, never returned by any endpoint, never logged. Contract documented
  in [docs/massing-cloud-bridge.md](docs/massing-cloud-bridge.md) for the massing.cloud plugin to mirror.
- **Container hardening**: the API runtime image no longer copies the base image's global `npm` CLI
  (`/usr/local/lib/node_modules`) into production. The API invokes the IFC→Fragments converter via
  `node <script>` with deps in `/app/node_modules` and never runs `npm` at runtime, so dropping the
  npm CLI removes its bundled deps (cross-spawn / glob / minimatch / sigstore / tar) and their CVEs
  from the image, clearing the Trivy container-scan gate and shrinking the image.

## v0.3.523 — JOB-QUEUE: mutating jobs hold the project mutation lock

- Job handlers that **write project state** now run under `pid_lock.mutating(project_id)` — the same
  per-project lock the API edit path and the docmanager/edit_history sidecars already take. A queued
  mutating job (e.g. `escalation_scan`, which escalates records) can no longer interleave its
  read-modify-write with a concurrent edit or another mutating job on the same project.
- `register_kind(name, fn, mutating=True)` declares a mutating kind; the worker wraps only those
  (when the job carries a `project_id`) in the lock. Read/artifact kinds
  (`model_export`, `clash_detect`, `cobie_export`, `compiled_set_pdf`) are unaffected — the wrap is
  a no-op for them, so nothing serializes that doesn't need to.

## v0.3.522 — ENTITLE-1: consistent export entitlement enforcement

- **Closed the IFC-export side-doors**: `/model/export.ifc` and `/model/export.ifcx` now gate on the
  export entitlement just like `/source.ifc` did — previously a licensee could bypass the IFC gate
  through the drawings/standards routes when enforcement was on.
- **Gated the 3D-export routes** (`/model/export.gltf`, `/model/export.glb`) on the base (Home+)
  export entitlement, so free-tier enforcement now covers every model-out path.
- **Fixed the tier matrix**: `glb` (binary glTF) was absent from the base export set — it would have
  402'd even at Enterprise; it's now a Home+ base export alongside `gltf`. `ifcx` (IFC5 / ifcJSON) is
  declared as Commercial+ openBIM data-out. All gates remain **no-ops in open mode** (enforcement is
  off by default — no licence required until an operator flips `MASSING_LICENSE_ENFORCE`).

## v0.3.521 — CX-1: commissioning as a first-class loop (R14 Tier-1 complete)

- **Seed from the model** (`POST /cx/seed` + the ⚡ button on Turnover): equipment classes in the
  published model become GUID-keyed `asset_register` records (deduped on re-seed), and every
  systemed asset gets its phase-typed `commissioning` tests (Pre-Functional + Functional) — the
  Functional stamped with **FPT expected values** from the MEP equipment register (capacity / flow /
  size per system).
- **System × phase matrix** (`GET /cx/matrix`): the Cx wall chart — per-cell total / tested /
  accepted / pass / fail across Pre-Functional → Retro-Cx, with per-system asset counts and
  completion %. Rendered on the Turnover panel with per-system **dossier** drill-down
  (`GET /cx/dossier` — assets, tests by phase, expected values, best-effort punch mentions).
- With CX-1, PROC-LOOP, and REBAR-RULES/BBS shipped, **all of the 🔬 R14 Tier-1 ring is complete**.
- **TEST-GAPS closed**: the audit's "6 untested engines" was mostly overcount (5 already covered);
  the genuine gap — the distribution-waterfall investor allocator — now has a direct suite
  (dollar conservation, pref clearance, pro-rata classes, period synthesis).

## v0.3.520 — MODEL-CI-3 · PROC-LOOP · REBAR-RULES + BBS

- **Security**: the ⧉ compare overlay now allowlists its image source (data:image/png / blob: only),
  closing the CodeQL js/xss-through-dom warning on the file-picked prior revision.
- **REBAR-RULES + BBS (R14)**: a per-typology reinforcement catalog (`aec_data/rebar_rules.py`,
  ACI 318-informed — the column tie-spacing envelope min(16·d_bar, 48·d_tie, least dimension) with
  the governing limb named), a **cage checker** (`GET /rebar/check?column=` + the ✓ viewer tool —
  longitudinal bar count and tie spacing verified against the envelope; a bare column is a finding),
  and the **bar bending schedule** (`GET /rebar/bbs` + `.csv`, 📋 viewer tool): every authored
  `IfcReinforcingBar` grouped into marks by size · shape · cut length with unit mass (π r² × 7850)
  and total tonnage — the fabricator/5D quantity.

- **Model CI grows to a 5-check pack**: `ids` validates the model against the project's **pinned
  IDS** (the information-delivery contract — any failing specification fails the build; unpinned
  projects skip), and `qto_delta` compares headline per-class quantities against the previous CI
  run (>25% swings, appeared/vanished classes → warn — a review flag, never a hard fail; the
  baseline rides inside the stored report). `POST /ci/run?create_topics=true` turns each failing
  check into an open coordination Topic (BCF-model) so CI failures round-trip like any issue.
- **PROC-LOOP (R14)**: quote leveling with `record=true` persists every priced line as a
  `price_observation` (source="quote") — the **price-observation ledger**
  (`GET /procurement/price-history`) rolls up min/median/avg/max, the latest price + vendor,
  latest-vs-median drift, and a spark series per material. **Field material requests**: a new
  `material_request` module (requested→approved→ordered→delivered) plus
  `POST /procurement/material-request/suggest` — a QUERY-DSL model selection becomes per-class
  quantity suggestions straight from the QTO takeoff (volume→m³, area→m², else count), optionally
  created as requests keyed to the element GUIDs. Analytics panel gains the price ledger table and
  the suggest→create flow; the 3-way-match table now escapes record-derived text.

## v0.3.519 — RULE-LIB-2 geometric rule checks + PERF-4 complete

- **Geometric rule checks** (`POST /projects/{pid}/rules/geometry/run` + the ⛶ Geometry check
  viewer tool): AABB-level spatial checks on the clash broad-phase geometry path — `clearance`
  (door/equipment needs a clear approach on at least one side along its thin axis; host wall and
  floor excluded), `escape_distance` (straight-line to the nearest exit ≤ max — the lower bound of
  egress travel distance, so violations are always real), `clear_width` (accessible 815 mm opening
  proxy). QUERY-DSL selectors scope each check; a starter set runs when none are posted; violations
  isolate in the viewer. The spatial questions the property rule library can't express.
- **PERF-4 closed out**: trade AP is now a SQL `SUM` with state exclusion (`sum_field
  exclude_states`, NULL states kept — equivalence-tested against the old Python loop), and CV
  progress name→id resolution is a single id-only SQL probe (`find_id_by_field`, case-insensitive
  on the name field or title) instead of a per-estimate table scan.

## v0.3.518 — SURF-4b: turnover readiness + vendor procurement gate surfaced

- The Turnover panel now opens with a **readiness strip**: substantial-completion certificate ref +
  signers, record-model lock state (and locked version), or "ready to certify / not yet ready" when
  no certificate is on file — `GET /turnover/status`, previously backed but never surfaced.
- New **🚦 vendor gate** check on the bid-leveling tab: name a vendor and see can-bid / can-bill at
  a glance with the exact compliance blockers (COI status + expiry, prequal, subcontract execution,
  lien waiver) — `GET /procurement/gate`, also previously unsurfaced.

## v0.3.517 — SURF-2b: bid-leveling summary + invite-bidders surfaced

- The bid-leveling tab now opens with the **all-packages leveling summary** (`GET /bids/leveling` —
  low / high / avg / spread per package, previously backed but never surfaced); picking a package
  still drills into the per-bid detail. New **✉ Invite** action sends the ITB to comma-separated
  companies via the existing `POST /bidding/packages/{id}/invite` and reports who was invited.
  Frontend-only; panel live-load verified in the preview.

## v0.3.516 — MARKUP-2d: live co-markup — the MARKUP-2 track is complete

- **Live co-markup**: a new SSE stream (`GET /projects/{pid}/drawings/markup/stream`, mirroring the
  pull-plan/notifications pattern — cheap count+latest signature polled server-side, fresh session
  per poll) pushes whenever anyone saves a markup, and the drawings browser subscribes on open — so
  every open sheet **live-refreshes its pins the moment a teammate marks up**, no reload. Resilient
  `liveStream` client handle; the initial snapshot is skipped so opening doesn't double-load.
- With 2a (stamp library + slip-sheet), 2b (cross-sheet grid), and 2c (overlay compare), **queue #1
  MARKUP-2 is fully shipped** across v0.3.512–516. Sheet-space peer cursors remain a polish idea on
  the presence roster (free-form viewpoint payload — no protocol change needed when wanted).

## v0.3.515 — MARKUP-2c: light-table overlay compare

- **"⧉ Compare"** on any sheet view overlays an uploaded prior revision (SVG, or PDF page 1
  rasterized via the bundled pdf.js) on the live sheet, classic light-table style: the current sheet
  tints **blue**, the prior tints **red** with multiply blending — shared linework reads dark,
  removed-since-prior work pops red, added work pops blue. Adjustable prior-layer opacity; rides the
  existing pan/zoom (the overlay lives in the transformed stage); second click toggles off and
  restores normal rendering. Frontend-only — no server change.
- Remaining MARKUP slice: 2d live co-markup (2D presence payload + markup-mutation broadcast).

## v0.3.514 — SPRINT 2: dashboard UNION-ALL · CI-on-publish + clash check · cross-sheet markups grid

**DASH-UNION (PERF-4)** — the role dashboard's per-module status tallies now come from **one
UNION-ALL round-trip** (`modules.state_counts_all`) instead of one GROUP BY per registered module
(~124 queries). Counts proven byte-identical by an equivalence test against every per-module query.

**MODEL-CI-2 (#6)** — the quality gate is now **automatic**: every successful publish enqueues a
`model_ci` job on the durable queue, so the badge is always fresh without anyone clicking "run"
(best-effort — a queue hiccup never fails a good publish). The pack gains a third check: **Latest
clash run** reads the newest `clash_detect` job result (clashes → warn, zero → pass, no run → skip —
coordination work, not automatically a defect). IDS/QTO-delta checks remain open (MODEL-CI-3).

**MARKUP-2b (#1)** — the **cross-sheet markups grid**: a "☰ Markups" button in the drawings browser
lists every markup in the project — sheet, kind, note, measure, author, revision, RFI-link and
⟳ carried-forward status — with Σ totals per kind (count + summed distance/area). DOM built with
`textContent` throughout (XSS-safe by construction). `drawingMarkup()` without a sheet now returns
the whole project (the server always supported it).

## v0.3.513 — SPRINT 1: XLSX round-trip · sheet DXF · selector-scoped clash · 4D variance · apply-leveling

Five queue items in one sprint release (the new cadence: targeted tests per feature while building,
one full-suite + gates + CI pass at the sprint boundary).

**XLSX-ROUNDTRIP (#2)** — the single most-used daily openBIM workflow (IfcCSV-style), end to end:
  - **Export** `GET /projects/{pid}/model/roundtrip.csv?props=Pset_WallCommon.FireRating,…` — one row
    per element (guid, ifc_class, name + the chosen `Pset.Prop` columns), formula-injection-guarded
    for Excel.
  - **Dry-run diff** `POST /projects/{pid}/model/roundtrip/diff` (CSV or XLSX upload) — exactly which
    cells would change (`{guid, pset, prop, old, new}`), unknown GUIDs reported, blank cells ignored,
    **`dtype` inferred from the OLD value's type** so a numeric property edited in a spreadsheet
    doesn't silently flip to a string. Nothing is written by the diff.
  - **Apply** rides the existing GUID-stable edit path: a new **`set_props_by_guid`** batch recipe
    (`aec_data.edit_asbuilt`) applies the whole sheet in ONE model pass + republish — not one edit
    call per cell. Bad rows are skipped, never abort the batch.
  - Viewer gains **"⇄ Property round-trip (CSV/XLSX)"**: pick columns → export → upload the edited
    file → review the diff table → one-click "Apply N changes + republish". New
    `roundtripExport`/`roundtripDiff` client methods.
- `test_xlsx_roundtrip` covers the recipe against a real IFC (str + typed float + skipped bad row)
  and the endpoints (guarded export, diff semantics, 422s).

**DXF-EXPORT (#3)** — every composed **sheet** now exports as editable R12 CAD linework, not just
paper: `GET /drawings/sheet.dxf` (same composition as sheet.svg/pdf) with layers
BORDER / VIEW-n / ANNO / TITLEBLOCK, annotation LINE/CIRCLE/TEXT entities, the titleblock as TEXT,
and the SVG-space Y flipped for DXF's Y-up. New `render_sheet_dxf` + dxf.py entity builders
(LINE/CIRCLE/TEXT/document); a **↓ DXF** button beside ↓ SVG downloads any view or sheet
(plan/section/elevation .dxf routes already shipped). Clears the PDF-only consultant-contract blocker.

**QUERY-DSL wiring (#5)** — the clash engine + route now accept **selector-scoped sides**:
`clash.detect(..., guids_a=, guids_b=)` composes GUID-set filters with the class filters, and
`POST /clash` takes `a_q`/`b_q` selector strings (`IfcDuctSegment & storey=L3`) resolved through
`query_dsl.select` (bad selector → 422). One grammar now scopes isolate, rules, CI, and clash.

**FOURD-SIM-2 (#7)** — planned-vs-actual on the 4D playback: each frame splits its completions into
`late_guids` / `early_guids` (activity `actual_finish` vs `finish`, hard-tied and trade-mapped
elements alike), and the player tints slipped work **red** / ahead-of-plan work **green** over the
amber "built today" flash, with late/early counts in the readout. On-time work stays neutral.

**RESOURCE-LEVEL-2 (#8)** — leveling now has a WRITE half: `POST /schedule/resource-leveling/apply
{cap}` applies one leveling round — over-allocated activities with CPM float shift forward
(week-granular, most-float-first, **the finish never moves**, critical path never shifts), mutating
`schedule_activity` dates through the audited module engine. Returns moves + before/after peak and
over-allocated weeks, truthfully reporting when a plan *can't* level under the cap. Schedule panel
gains **⚖ Level** behind an explicit confirm; re-renders CPM/Gantt on success.

## v0.3.512 — MARKUP-2a: project stamp library in the editor + slip-sheet carry-forward (queue #1)

- First MARKUP-2 slice. Scoping note: the markup stack was far ahead of the roadmap line — the 2D
  editor (8 tools), server-persisted structured markups with RFI promotion, the stamp-template
  library, the full sheet-revision register, and the presence/SSE plumbing all already shipped. The
  genuine gaps are integration + a few net-new UIs; this slice closes the two highest-leverage:
  - **Project stamp library in the editor** — the PDF editor's stamp picker now leads with the
    server library (`GET /stamps/library`: EJCDC/CSI review, inspection, status, seal templates),
    each review template fanned out per disposition as a dynamic `{{user}}/{{date}}` stamp, with the
    quick built-ins behind it. Wired automatically for every server-PDF session via `openPdfUrl`.
  - **Slip-sheet carry-forward (the honest workflow)** — markups now stamp the drawing register's
    **current revision** at save (`data.rev`, both the SVG-pin and `#pdf` editor spaces). Revising a
    sheet (`POST /drawings/{id}/revise`) tags every pre-existing markup `carried_from: <old rev>` —
    they keep rendering (a located comment is never dropped) but show as **⟳ carried — "verify
    against the current revision"** (dashed amber pin + tooltip). Fresh markups stamp the new rev;
    re-revising carries only untagged rows. `markups_carried` reported in the revise response.
- `test_markup` extended with the full slip-sheet round-trip (stamp → revise → carry → fresh-rev →
  re-revise). Remaining slices: MARKUP-2b markups grid · 2c overlay compare · 2d live co-markup.

## v0.3.511 — RT-ORJSON: Rust-backed JSON responses (⚙️ RUNTIME ring #1)

- Every default API response now serializes with **orjson** (Rust; Apache-2.0/MIT) — measured
  **7.1–9.4× faster** than stdlib on our representative payloads (a 5k-element property index drops
  27.5 → 3.8 ms per response; 2k module records 4.4 → 0.6 ms; 300 4D frames 1.6 → 0.2 ms).
- Implementation notes: we ship our **own** thin `JSONResponse` subclass rather than FastAPI's
  `ORJSONResponse` (deprecated in current FastAPI — its native Pydantic path only covers *annotated*
  routes, while most of our endpoints return plain dicts that still render through the default
  response class). `OPT_NON_STR_KEYS` preserves stdlib behavior for int-keyed rollups and
  `OPT_SERIALIZE_NUMPY` for `numpy.float64` (a float *subclass* stdlib accepted silently — the full
  suite caught 12 analysis endpoints emitting it; numpy arrays now serialize natively too). One real
  behavior change: `NaN`/`Infinity` now serialize as `null` instead of stdlib's literal `NaN` — which
  was *invalid JSON* that would have broken any browser `JSON.parse`. Graceful fallback to stdlib if
  orjson is absent. Dependency added via the hash-locked flow (`requirements.in`
  → the `lockfile.yml` pip-compile workflow in the prod py3.12 container → `requirements.lock`; the
  regenerated lock adds exactly one package, zero drift).
- Verified: warnings-as-errors smoke + the full 275-suite gate exercising every endpoint through the
  orjson render path (which also caught the int-key case).

## v0.3.510 — HARDEN-2: security + bug audit of the queue wave · roadmap reconciliation · RUNTIME ring

- A dedicated hand audit of everything shipped v0.3.495–509 (beyond CodeQL's 0-alert baseline) found
  and fixed 2 security issues + 7 bugs — every fix test-locked:
  - **S1 (sec)** — the job queue was a side door around the escalation admin gate: an *editor* could
    enqueue `escalation_scan` (with an arbitrary ladder) even though `POST /escalations/run` is
    admin-only + audited. Job kinds now carry a per-kind minimum role checked at enqueue (mirroring
    `require_role`, incl. the dev bypass) and privileged enqueues write the same audit trail.
  - **S2 (sec)** — the rule library was unbounded: caps added (≤200 rules, ≤500-char selectors,
    ≤40-char ids) so a stored library can't amplify viewer-level `GET /rules/run` into unbounded CPU.
  - **B1** — the v0.3.496 `/topics` + `/pins` payload caps kept the *oldest* rows, silently hiding
    every newly created issue/pin past the cap. The cap now keeps the newest (desc + re-sort so
    under-cap responses are byte-identical to before).
  - **B2** — QUERY-DSL's operator split took the highest-precedence operator *anywhere*, so a quoted
    value containing `=`/`>` (`Reference~"C=1"`) mis-parsed and silently matched nothing — a stored
    rule could false-"pass" Model-CI. Now leftmost-operator, quote-aware; and a bare ifc-prefixed
    *field* (`ifc_class`) is no longer hijacked by the bare-class shorthand.
  - **B3** — `parse_mspdi` imported MS Project *summary* tasks (project/WBS rollups are named + dated)
    as phantom activities; `<Summary>1</Summary>` / outline-0 tasks are now skipped.
  - **B4/B5** — 4D player: an empty-frames reload left live controls over `frames:[]` (TypeError) —
    now fully resets; and `showResult` gained an `onClose` hook so closing the modal (✕/Esc/backdrop/
    replaced) stops the play timer and restores visibility instead of leaving the model isolated.
  - **B6** — Data-QA severity dots never rendered (`high/medium/low` map vs the endpoint's
    `required/recommended`); **B7** — the exported `.xer` now carries the project name in ERMHDR.
- **Roadmap reconciliation:** all shipped items (the v0.3.493–509 queue wave AND the v0.3.457–492
  P1/P2 run) moved to [roadmap-completed.md](docs/roadmap-completed.md); [roadmap.md](docs/roadmap.md)
  rewritten as open-items-only with a fresh prioritized queue (MARKUP-2 → XLSX-ROUNDTRIP → DXF-EXPORT
  → PERF-4 remainder → the *-2 follow-ups → R14 Tier-1 → REL/test-gap carry-overs).
- **⚙️ RUNTIME ring added** (researched, license-vetted): orjson (first), uvloop (prod container),
  msgspec/zstd (investigate), oxlint, Node-22 lane → Rolldown/Vite-8 trial, TanStack Virtual,
  three-mesh-bvh (investigate), knip — each gated on a measured before/after win.

## v0.3.509 — MODEL-CI: "Automate-lite" quality-gate check pack (queue #16)

- A model check pack that runs on demand and produces a **pass / warn / fail badge** stored as an
  artifact, so every model version carries a quality gate. Each check is a thin adapter over an engine
  that already ships — the pack grows by registering one function (same shape as the job-kind registry):
  - **Rule library** — the RULE-LIB rules must pass; a high-severity failure fails the build, medium/low
    warns.
  - **Elements named** — a data-completeness gate on the share of named elements (<50% fail, <90% warn).
- New `aec_api/model_ci.py` (per-project JSON blob, no migration; a broken check fails rather than
  crashing the run) + `POST /projects/{pid}/ci/run` and `GET /projects/{pid}/ci/latest` (the badge
  source). Viewer gains a **"▢ Model CI (quality gate)"** tool showing the overall badge + per-check
  status; `ciRun`/`ciLatest` client methods + `ModelCiReport` type. `test_model_ci` (275 suites green).
- **MODEL-CI-2:** auto-run on publish/option-branch save (enqueue a CI job on the durable queue) + more
  checks (clash / IDS / QTO-delta) and BCF/report artifacts — the engines exist; wiring them into the
  pack + the publish hook is the follow-up.

## v0.3.508 — RESOURCE-LEVEL: multiple named schedule baselines + variance (queue #15)

- The single plan-of-record baseline becomes a **library of named baselines** — "GMP", "Recovery",
  "post-ASI-014" — each a frozen snapshot of every activity's planned start/finish/budget, so a team can
  track drift against the contract baseline *and* a later re-baseline at the same time. Variance can be
  measured against any chosen baseline (or `latest`): per-activity slip in days + added/removed + a
  by-status rollup (slipped / improved / on-baseline / added / removed / max-slip).
- New `aec_api/schedule_baselines.py` (per-project JSON blob, bounded history, no migration) +
  `GET/POST /schedule/baselines`, `DELETE /schedule/baselines/{id}`,
  `GET /schedule/baselines/{id|latest}/variance`. The legacy singular `/schedule/baseline` +
  `/schedule/variance` are untouched — the named library is a superset. Schedule panel gains a
  **"📌 Baselines"** drawer (capture / list / click-to-compare / delete); client methods added.
  `test_schedule_baselines` (274 suites green).
- Resource-loading S-curves + the over-allocation leveling *advisory* already ship
  (`resource_loading.py`); *applying* a level (mutating dates within float) is the RESOURCE-LEVEL-2
  follow-up — it rewrites the schedule, so it lands on its own with an explicit confirm.

## v0.3.507 — RULE-LIB: user-authored parametric rule library (queue #14)

- A Solibri-style rule library a firm can author without code, built on QUERY-DSL. Each rule is two
  selector strings + a severity: **`scope`** (which elements it applies to) and **`require`** (the
  condition each in-scope element must satisfy). An in-scope element that fails `require` is a
  violation — so "every fire door needs a fire rating" is `scope: IfcDoor` / `require:
  Pset_DoorCommon.FireRating`, and "external walls declare a fire rating" is `scope: IfcWall &
  Pset_WallCommon.IsExternal=true` / `require: Pset_WallCommon.FireRating`.
- New `aec_api/rule_library.py` (per-project JSON blob, no migration; a starter set seeds an empty
  library) + `GET/PUT /projects/{pid}/rules` (selectors validated before an atomic save → 422 on a bad
  rule) and `GET /projects/{pid}/rules/run` → per-rule pass/fail + offending GUIDs + by-severity
  rollup. Viewer gains a **"✔ Rule check"** tool listing each rule's pass/fail with an "isolate
  failures" link; new `rulesRun` client method. `test_rule_library` (273 suites green).
- Geometric/relational checks (clearance-in-front-of, escape distance, accessible route) need swept
  geometry, not the property index — deferred to a RULE-LIB-2 riding the logistics/clash geometry path.

## v0.3.506 — QUERY-DSL: a selector language over the model (queue #13)

- Adds a compact selector grammar so one filter language scopes clash runs, view filters, schedules,
  bulk edits, and MCP tools — instead of each feature inventing its own filter shape. Combine terms
  with `&`: `IfcWall & Pset_WallCommon.FireRating=2HR & storey=L3`. Fields: `ifc_class`, `storey`,
  `type_name` (alias `type`), `name`, `discipline`, or any `Pset.Prop`; operators `= != >= <= > < ~`
  (contains) plus a bare `Pset.Prop` for existence. Comparisons are numeric when both sides parse as
  numbers, else case-insensitive string.
- New `aec_api/query_dsl.py` (`parse`/`matches`/`select`, reusing `model_query._val` for field
  resolution) + `GET /projects/{pid}/model/select?q=…` → matching GUIDs + parsed predicates (bad query
  → 422). Viewer gains a **"🔎 Query-select (filter language)"** tool that runs a query and isolates
  the matches in 3D; new `modelSelect` client method. Unit-tested end to end (`test_query_dsl`, 272 suites).

## v0.3.505 — FOURD-SIM: time-phased 4D construction playback in the viewer (queue #12)

- Turns the (already server-computed + unit-tested) `/schedule/4d` timeline into a viewer playback — the
  one genuinely-missing piece of 4D. A new **"⏱ 4D construction sequence (playback)"** tool loads the
  day-by-day timeline and lets you **scrub or auto-play** through construction days: every element built
  up to the current day is shown, everything not yet built is hidden, and the day's completions flash
  **amber** — so the model assembles itself as the sequence advances (the Navisworks TimeLiner / SYNCHRO
  core). Source selector (auto / GC schedule / takt), day slider, play/pause/step/reset, and a
  day·date·%·built readout. Uses the schedule's element↔activity ties (hard-tied first, then by trade +
  floor). New `viewer/fourD.ts` + reusable `LayerManager.colorGuids`/`resetColors` primitives.
- Scope note (audit correction): 4D element↔activity linking and temporary site-logistics geometry were
  **already shipped** (the `element_guids` tie + "Tie 3D selection", and W9-5 logistics with path motion
  and swept-crane clash). The only real gap was the viewer never consuming the 4D frames — now closed.
  Planned-vs-actual variance *coloring* on the timeline (the math ships in `/schedule/variance`) follows
  as FOURD-SIM-2.

## v0.3.504 — SCHED-P6: P6 .xer + MS-Project XML export / round-trip (queue #11)

- Closes the schedule round-trip. Import already read Primavera P6 **.xer** and **PMXML**; this adds the
  return path so contractor updates flow both ways without GUID drift:
  - **Export** `GET /projects/{pid}/schedule/export?fmt=xer|msp` serializes the *live* schedule — every
    `schedule_activity` (imported **and** hand-entered, with the GC's edits) — keyed by the P6 activity
    code (`wbs`). `xer` → a P6 `.xer` (TASK table with task_code/dates/type/percent); `msp` → **MS-Project
    XML (MSPDI)** with the code in each task's `<WBS>`.
  - **Round-trip** closes: re-importing an exported file matches the same records by code and updates in
    place. Import now also auto-detects **MSPDI** (`<Task>`) alongside P6 PMXML (`<Activity>`), so a file
    edited in MS Project comes back cleanly — new `parse_mspdi` + `to_xer`/`to_mspdi` in `aec_data.schedule`.
  - Schedule panel gains **⤓ Export .xer** / **⤓ Export MSP .xml** buttons next to the P6/MSP import;
    new `exportSchedule` client method.

## v0.3.503 — WFE-2: escalation surface on the portal home

- Surfaces the v0.3.502 escalation engine so it isn't a backend orphan. The portal command-center home,
  below the "⏰ Deadlines" feed, now shows an **"▲ Escalations"** section whenever overdue records have
  crossed an escalation rung: a per-level summary (L3×n · L2×n · L1×n), the top items badged with their
  level + days-late + ball-in-court party, and a one-click **"Escalate & notify the ball-in-court
  party"** action. The action is admin-gated on the server (a 403 surfaces as a toast); on success it
  re-renders the home so the freshly-cleared items drop off. New `escalationsScan`/`escalationsRun`
  client methods + `EscalationScan`/`EscalationRun` types.

## v0.3.502 — WORKFLOW-ENGINE: overdue escalation + explicit ball-in-court (queue #10)

- The workflow layer already had the full state machine (per-doc-type states/transitions, party gating,
  `requires`/evidence gates, transition audit, notifications feed + SSE, and a `due_feed` SLA view).
  The genuine gaps were **automation and clarity**, and this closes both:
  - **Explicit ball-in-court** — a record's `party_owner` now **tracks the workflow** instead of going
    stale at creation. Each transition moves it to the new state's court (the party owing the primary
    next move, e.g. an RFI entering `open` → *Consultant/OwnersRep*, then `answered` → *GC*), so
    "whose court is this in?" is a stored, filterable, board-groupable value.
  - **Overdue escalation** — a new `escalation.py` engine turns the read-only `due_feed` into action.
    Each overdue record climbs an escalation **ladder** as it ages (L1 at 0–2 days late, L2 at 3–6,
    L3 at 7+); `run` writes an `escalation:L{n}` entry to the record's timeline, which the existing
    notifications feed surfaces to the ball-in-court party and the assignee — so an ignored RFI /
    submittal / change order nudges the responsible party harder the longer it sits. Idempotent per
    rung (guarded by the highest level already on the timeline), so a nightly pass never spams.
  - Endpoints `GET /projects/{pid}/escalations` (read-only preview) + `POST …/escalations/run`
    (admin, audited), plus an `escalation_scan` durable **job kind** so the pass can run off the
    request path / on a schedule (crash-recovery safe because it's idempotent).
- UI surface (an escalation badge on the notifications/SLA view) follows as WFE-2.

## v0.3.501 — fix(sec): escape untrusted text in the Budget estimating drawer (XSS)

- Closes a stored/DOM-XSS path introduced in v0.3.499 (SURF-2): the "📐 Estimate from the model" card
  wrote an uploaded DXF's **filename** — and server/model-derived free-text (layer names, storey labels,
  trade names, IFC-class strings, unit labels) — into `innerHTML` without escaping. A file named
  `<img src=x onerror=…>.dxf` would have executed script on selection. All such interpolations now pass
  through a shared `esc()` helper (now exported from `ui/charts`). Numeric/enum fields are unaffected.

## v0.3.500 — SURF-4: Data-QA surface — required-property completeness in the viewer (queue #9)

- Fourth UI-surfacing wave item: a **"🔍 Data QA"** button in the viewer's QA section surfaces the
  backed-but-unsurfaced `/elements/qa` required-property-completeness engine. It renders the overall
  compliant/non-compliant split with a percentage, then a per-rule breakdown (label, severity dot,
  present vs. missing counts). Each rule with gaps offers a **"select missing"** link that highlights
  the offending elements in the model (up to 200 GUIDs) via the existing `sets.fromGuids` → `selectMap`
  path — so a modeler can jump straight from "37 walls missing FireRating" to those walls on screen.
- Audit note: the codebase-review "orphan capability" count was materially overstated. SURF-3 (phasing/
  LOD) and most SURF-4 candidates (code-check, model-health, quantity distributions) were already
  surfaced under different route/method names; the recipe dispatch-by-name path produces false-positive
  "orphans" in a wrapper-name heuristic. Verified by feature/route, not wrapper name, before building.

## v0.3.499 — SURF-2: estimating/takeoff surface — model estimates + DXF takeoff (queue #7)

- Second UI-surfacing wave item: a **"📐 Estimate from the model"** card in the Budget panel wires
  up four backed-but-unsurfaced estimating capabilities, each filling a shared results drawer:
  - **＄ Conceptual (unit-rate)** — `estimateFromModel`: the IFC takeoff × cost-DB unit rates →
    priced line items, total, and the unpriced-class list.
  - **🧱 Resource-based (L/M/E)** — `estimateResourceBased`: assembly build-ups (labor + material +
    equipment) with crew-hours and a by-trade table.
  - **🏢 QTO by floor** — `qtoByFloor`: quantity + cost per storey and discipline.
  - **⬒ Takeoff a DXF** — `takeoffDxf`: a 2D CAD file picker → linear metres, enclosed area, and
    block counts per layer (flags unitless DXFs).
- All four routes ship + are CI-covered; pure surface. Frontend-only (backend tree identical to
  v0.3.498); typecheck · lint · 121 vitest · build green; panel load-verified.

## v0.3.498 — SURF-1: schedule interop surface — P6/MSP import, alerts, earned schedule (queue #6)

- First of the **UI-surfacing wave**: three fully-backed schedule capabilities that had **no
  user-facing surface** now appear in the Schedule panel's toolbar:
  - **⇪ Import P6/MSP** — a file picker feeding `importXer` (Primavera `.xer` or MS-Project
    `.xml`/PMXML, auto-detected); imported tasks become editable `schedule_activity` records with
    real calendar dates and the CPM/Gantt re-renders off them. The #1 scheduler-credibility gate.
  - **🔔 Alerts** — the predictive `schedule/alerts` (overdue · late-start · at-risk predecessor ·
    SPI · procurement) in a collapsible drawer with severity dots + high/medium/low counts.
  - **⏱ Earned Schedule** — the time-based EVM metric (`evm/earned-schedule`: SPI(t), SV(t) periods,
    forecast finish) alongside the existing dollar earned-value card.
- All three routes already ship + are CI-covered; this is pure surface. Frontend-only (backend tree
  identical to v0.3.497); typecheck · lint · 121 vitest · build green; panel module load-verified.

## v0.3.497 — PANEL-LAZY: portal panels dynamic-imported out of the eager shell (queue #5)

- The ~30 secondary portal panels (operations/FCA/spine/resilience/energy/turnover, analytics,
  aiassist, EVM, WIP, ledger, traceability, resource-loading, design/lifecycle/diligence/ESG,
  materials, module-graph, standards/program/BIM-KPI/IDS/model-analysis, responsibility, documents,
  budget, schedule-views) are now **dynamically imported at first open** instead of statically bundled
  into the app shell. Each panel file (and its heavy deps — charts, tables, module-graph) becomes its
  own chunk fetched only when the user navigates to that destination.
- The wrapper methods went from `renderX(this.panelCtx())` to `async () => (await import("./panels/Y"))
  .renderX(...)`; every call site already `void`s the result or routes through `goDest`/dispatch
  (Promise-tolerant), so behaviour is unchanged. Verified: the dynamic chunk resolves and exposes its
  renderers; build splits ~15 panel chunks (aiassist 16KB, analytics 20KB, design 18KB, budget 14KB…)
  out of the eager `index-*.js` the CI bundle budget reads.
- Frontend-only (backend tree identical to v0.3.496); web gates green (typecheck · lint · 121 vitest ·
  build); live-verified in the dev preview.

## v0.3.496 — PERF-4a: test-fastpath schema-sync skip · topics/pins payload caps (queue #4)

- **TEST-FASTPATH**: `init_db` now detects a **brand-new database** (no known table present before
  `create_all`) and skips the additive `_ensure_columns`/`_ensure_indexes` reconciliation — on a
  fresh DB `create_all` already builds every table + index current, so the sync (an `inspect`
  round-trip per ~130 tables + a `checkfirst`-create per index) was pure startup overhead. Every
  test spins up a fresh SQLite DB, so this trims the bulk of per-test boot cost; the upgrade path
  (some tables predate the build) still reconciles exactly as before. `test_migrate` still exercises
  `_ensure_columns`/`_ensure_indexes` directly, unchanged.
- **PAYLOAD-CAPS**: `GET /projects/{pid}/topics` gains `limit` (default 500, hard cap 2000) +
  `offset` pagination — on a mega-project the issue/clash log is the unbounded-serialize growth
  driver; `GET /pins` hard-caps at 5000 (beyond usefully renderable). Existing param-less callers
  get the first newest-order page; over-cap limits clamp rather than error.
- Remaining PERF-4: the 124-query dashboard UNION-ALL is a larger rewrite deferred to its own batch.
- 270/270 backend suites; web gates green.

## v0.3.495 — PERF-3: QTO/discipline caching · clash off the request path (queue #3)

- **QTO-CACHE**: `qto.takeoff_file` was already memoized on (path, mtime, cost-map); this extends the
  same mtime-keyed cache to `discipline_summary_file` (the `/quantities/disciplines` roll-up), which
  falls back to per-element `create_shape` for volume/length — it re-ran the geometry pass on every
  GET. Bounded LRU (24 entries), evict-oldest; a re-parse (new mtime) yields a fresh entry so it can
  never go stale.
- **CLASH-JOBS**: a new `clash_detect` job kind runs the narrow-phase (mesh-boolean) clash on the
  durable worker instead of a request slot — the same engine as `POST /projects/{pid}/clash`, so a
  minutes-long large-model run never holds a thread or hits the HTTP timeout. Returns the clash
  summary + top rows as a job result; topic creation stays on the interactive route.
- Test-proven: `clash_detect` round-trips through the queue; `discipline_summary_file` cache verified
  by test_discipline; 270/270 backend suites, web gates green.

## v0.3.494 — PERF: async-block, geometry cache, frontend leaks (execution queue NOW #1–2, #4)

- **PERF-1 (ASYNC-BLOCK)**: the pdf_info/merge/split/extract/rotate routes, the module Excel/CSV
  import parse, and the large source-IFC / discipline-model upload writes now run in a threadpool —
  they were `async def` calling blocking pypdf / openpyxl / multi-hundred-MB `write_bytes` + MinIO
  `put` on the event loop, stalling **every** request in the process. (The sibling pdf_stamp/seal
  routes already did this; now they all do.)
- **PERF-2 (GEOM-CACHE)**: `drawings.bake()` — the dominant per-request CPU cost, re-tessellating the
  whole model on every section/elevation/DXF/sheet view — is now **memoized per model object**
  (`open_model` is lru-cached, so an unchanged file hands back the same object; a re-parse yields a
  new object → fresh bake, so it can't serve stale geometry). Added `world_bounds()` that returns the
  model AABB without building trimeshes (reuses the bake cache when present), and env/wind now derives
  its bounding box through it instead of a full bake. Tested (second bake is identity; bounds agree).
- **PERF-4 (frontend leaks)**: the UX-2 guide-line `pointermove` listener is installed **once**
  instead of stacking a new one (plus a leaked closure) on every persona-triggered `buildToolsPanel`
  rebuild; `collabPresence` now keeps + exposes `dispose()` to clear its 20 s heartbeat interval and
  close its SSE stream on viewer teardown (both previously leaked on re-init).
- Backend suite green; web gates green (typecheck · lint · 121 vitest · build). No behaviour change —
  pure performance + hygiene.

## v0.3.493 — SEC: attachment stored-XSS fix · 🧭 R15 landscape plan + re-prioritized queue

- **SECURITY (stored XSS)**: module-record attachments were served **inline** with the client-supplied
  `Content-Type`, so a `text/html` or `image/svg+xml` upload with `<script>` executed JS on the API
  origin against a lured member's session. Inline serving is now restricted to a **raster-image
  allowlist** (png/jpeg/gif/webp/bmp); everything else is forced to `Content-Disposition: attachment`
  + `application/octet-stream`, with `X-Content-Type-Options: nosniff` and
  `Content-Security-Policy: sandbox; default-src 'none'` on the response. Filenames run through the
  existing whitelist. Regression-tested (HTML + SVG both forced to attachment; images still inline).
- **🧭 R15 ring + re-prioritized execution queue** added to the roadmap from a full research pass —
  commercial + open-source landscape sweeps, a very-thorough codebase gap review, and security +
  performance audits. Headline finding: the **backend is far ahead of the frontend** (~72 shipped
  capabilities have no UI), so the new order leads with security/perf hygiene, then UI-surfacing
  waves, then a real workflow state-machine layer, then the twice-validated interop gaps
  (P6/MSP export round-trip, 4D simulation, model query DSL, a rule-based model-checking library,
  model-CI, PDF markup parity), then the R14/R15 feature tiers. All deterministic + offline; licenses
  mapped; non-deterministic AI/photogrammetry features explicitly out of scope.
- The performance audit's ranked fixes (GEOM-CACHE, ASYNC-BLOCK, QTO-CACHE, CLASH-JOBS, PANEL-LAZY,
  DASH-UNION, PAYLOAD-CAPS, TEST-FASTPATH) are queued as the NOW block for execution.

## v0.3.492 — R14 research ring planned · doc_text ReDoS round 2

- **🔬 R14 ring added to the roadmap** — a field-research pass (13 infographics + 10 open-source
  tools/products studied) synthesized into 18 planned upgrades, ranked in three tiers:
  **Tier 1** — a full commissioning module (model-derived asset registry, phase-typed checklists,
  system×phase matrix, MEP design values as expected FPT values) · per-typology reinforcement rules
  + bar bending schedules with calc-run provenance · procurement close-the-loop (3-way match +
  price-observation ledger into the cost DB). **Tier 2** — bid-scope coverage gaps with cited scope
  lines · a compliance evidence ledger ("golden thread") · an MEP connector-topology graph with
  parallel-run generation · range estimates + firm rate sheets. **Tier 3** — clash-report triage
  import, lean BIM→GIS GeoJSON export, mnemonic shortcuts, view templates, a warnings panel,
  drawing-status lifecycle, CBS rollups, a live BIM Execution Plan generator, BIM-org roles, and
  charter/lessons-learned modules. All deterministic + offline; techniques only, no code lifted.
- **doc_text ReDoS, round 2**: CodeQL re-flagged the section matcher — the leading `\s*` was
  ambiguous against the optional `SECTION\s+` prefix (quadratic on space-runs). The line is now
  stripped before matching and every whitespace quantifier is bounded. Behaviour unchanged.

## v0.3.491 — UX-1 full ribbon merge: physical phase clusters (P2 · designer workspace)

- The Tools rail's sections are now **physically regrouped by lifecycle phase** — the DOM reorders
  into **Build → Analyze & Coordinate → Document → Data** clusters with a header over each, so
  "Advanced authoring" sits beside "Draw elements" instead of at the bottom of an accretion list.
  Every section declares its phase once at creation (`data-phase`); the ribbon filters on that,
  never by parsing titles at runtime.
- The ribbon consolidates to the **four real phases** (+ All): the old separate Analyze / Coordinate
  tabs both showed the same single section. A stale saved tab migrates to All. Persona-secondary
  tools now sort to the end of their phase cluster with a "more" badge (replacing the positional
  "More tools" separator the reorder would have orphaned).
- Live-verified: cluster order + headers, Build-tab filtering to exactly its three groups, header
  hiding on filtered tabs, persistence, and the stale-tab migration.

## v0.3.490 — B5 fastener/connection assemblies (P2 · Wave 11)

- **`add_connection_assembly` recipe**: a connection plate + bolt array authored at the joint
  between two members, grouped into an `IfcElementAssembly`, **and** — the semantic B6's base
  plates/shear tabs lacked — an **`IfcRelConnectsWithRealizingElements`** recording that A connects
  to B *realized by* the plate and fasteners (`ConnectionType` BOLTED/WELDED). That's the construct
  fabrication and detailing tools round-trip. Welded connections carry the weldment plate alone.
- **`connection_summary`** — the fabrication-level connection browser: every realized connection
  with its members, type, and realizing parts.
- Test-proven (A↔B realized by 5 parts; bolted + welded both listed; same-member and unknown kinds
  reject) and registered (83 recipes, matrix guard green). Completes B5.

## v0.3.489 — security: bounded doc_text regexes (CodeQL ReDoS)

- The two section-number regexes in `doc_text.py` used an unbounded `\d+(\.\d+)+`, which backtracks
  polynomially on adversarial `9.9.9…` input (CodeQL `py/polynomial-redos` ×2, flagged on
  v0.3.486's ingestion/search paths). Quantifiers are now **bounded** (`\d{1,4}(\.\d{1,4}){1,6}` —
  real section numbers are short) and the search query is capped at 500 chars as defense in depth.
  Behaviour unchanged (both consumer suites green); the CodeQL count returns to 0.

## v0.3.488 — E3 sketch-to-BIM push/pull (P2 · Master-builder UX)

- **`extrude_profile` recipe** — sketch-to-BIM: a closed 2D profile (XY metres) extruded to height
  as a real IFC element (generic proxy mass by default; walls/slabs/coverings/members when the
  sketch IS one), placed on the storey with an optional base lift. Tessellation-verified: an
  L-shaped sketch becomes exactly a 6 × 5 × 4 m solid.
- **`set_extrusion_depth` recipe** — the **pull**: change any simple extrusion's depth **in place**
  (a wall's height, a slab's thickness, a sketch mass's rise) by editing its
  `IfcExtrudedAreaSolid.Depth`. GUID-stable — the element, psets, and every reference survive; only
  the geometry deepens. Non-extruded targets (meshes/booleans) reject cleanly.
- Both registered (82 recipes, matrix guard green) and guarded (short profiles, bad classes/depths,
  stale GUIDs). Completes E3.

## v0.3.487 — JOB-QUEUE geometry exports · REL-8 complete (P2 · reliability)

- **JOB-QUEUE — `model_export` artifact job**: the heavy **.glb/.gltf geometry exports** now run as
  background jobs — tessellation off the request thread, the file parked in object storage,
  `GET /jobs/{id}/artifact` streams it (valid glTF magic verified). The inline
  `/model/export.glb|.gltf` routes stay for small models; this is the no-timeout path for big ones.
  A bad format errors on the job row (the worker survives).
- **REL-8 — COMPLETE**: audited all 359 first-party modules — every one already opens with a header
  docstring — and made it durable: `test_import_cycles` now **enforces** the header-docstring rule
  alongside the existing no-cycle guard, so a future module can't ship undocumented.

## v0.3.486 — W9-4 document-text ingestion → cited NL answers (P2 · knowledge graph)

- **`doc_text.py` + 4 routes under `/projects/{pid}/doctext`**: ingest a specification / code
  commentary / report (**JSON text or a raw PDF body**, extracted via pypdf) — chunks split at
  spec-section headers ("SECTION 09 21 16") and numbered headings with **page tracking**
  (headerless documents fall back to paragraph chunks). `search` is deterministic token-overlap
  retrieval with section-number boosting; `ask` returns an **extractive answer — the document's own
  words** — cited by document · section · page, and says so honestly when nothing matches. No LLM
  involved or silently invoked: quoting the answer on an RFI is quoting the spec.
- **`/rfi/qa` now falls through to the documents**: a question no model intent claims searches the
  ingested text before the overview — `intent: "document"` with `kind: "document"` citations.
  Completes the W9-4 harder half (spec/code document text → cited NL answers).
- Test-proven end to end, including the PDF path ("4000 psi" survives canvas → pypdf → chunk →
  answer) and the QA fallthrough.

## v0.3.485 — W9-5 4D equipment motion + swept crane-reach clash (P2 · site logistics)

- **Motion along paths**: a logistics resource with a `path` now **interpolates its position by
  schedule progress** (arc-length along the polyline) — a crawler crane walks its runway, a hoist
  relocates bay by bay — and `/logistics/state` carries the interpolated position so the 4D overlay
  draws equipment where it IS on that date, not where it started.
- **`GET /projects/{pid}/logistics/clash` — swept crane-reach clash**: crane pairs whose swing discs
  intersect **while both are on site** (closest approach sampled along any motion paths, with the
  worst date and the overlap in metres — "both tower cranes swing over the same bay in June");
  time-separated or distant pairs clear. Static resources (trailers/laydown/gates/parking) **under a
  crane's hook** surface as safety flags, not clashes. Plan-level screen, honestly disclaimed (not a
  jib kinematic simulation). Completes W9-5.
- Test-proven: schedule midpoint → 50 m along a 100 m runway; a 30 m pair with 20 m jibs clashes
  with 10 m overlap; a **walking** crane creates a clash only as it arrives; the trailer flags.

## v0.3.484 — W9-6b headcount program → zones + auto-furnish (P2 · generative fit-out)

- **W9-6b — `program_fit` recipe**: give it a **headcount program** (`{Engineering: 40, Sales: 20}`)
  and it allocates the model's spaces to departments (largest rooms to the largest remaining asks),
  stamps each allocated space as that department's **zone** (`LongName` + `Pset_Massing_Program`
  Department/SeatsAllocated), and **furnishes it to exactly the allocated seat count** using the
  W9-6 gridder (aisle-cleared desk/table templates). The report partitions allocated vs unallocated
  rooms and never silently under-seats — an over-capacity ask comes back `short_by: N`. Test-proven:
  an 11-seat program authors exactly 11 desks; a 500-seat ask on two small rooms reports the
  shortage. Completes the W9-6 generative fit-out track.

## v0.3.483 — E6 model-option branches · E8 model-aware guardrails (P2 · Master-builder UX)

- **E6 — recipe-log design-option branches** (`model_options.py` + 5 routes under
  `/projects/{pid}/model/options`): **snapshot the current model as a named branch** ("Scheme A —
  steel frame"), keep editing, snapshot again, and **switch between schemes** — each activate goes
  through the same edit-history push as any edit, so the switch itself is one undo step. `GET` lists
  branches (the byte-identical one flagged `current`); `.../diff` reports added/removed element
  GUIDs + per-class count deltas vs the working model; `DELETE` drops a branch (history untouched).
  Whole-model branches — per-element overlays remain the W9-3 layer system. Distinct from
  `design_options.py` (which compares metrics, not models).
- **E8 — model-aware guardrails** (`guards.model_precheck`, enforced in `apply_recipe`): references
  are now validated against the **open model** before any mutation — a typo'd storey (available
  names listed), a door hosted on a slab, a hallucinated host/element GUID, a `connect_mep` end
  with no ports, and a fully-stale GUID batch are all rejected; a partly-stale batch warns and
  proceeds. Batches (`apply_recipes`) deliberately skip this layer — a step may legally reference
  what a prior step in the same batch creates (wired flows use `/edit/graph`). Completes E8.
- Both test-proven end to end (branch → edit → diff `+1 IfcWall` → activate → undo returns to the
  other scheme; slab-hosted door blocked before write).

## v0.3.482 — CI fix: approvability test writes models to a temp dir

- The new D8 BCF test generated its model through `/generate/massing` with the default `IFC_DIR`,
  which resolves under `/app` — **read-only in the CI container** (the container-readonly-tmp
  pattern again). The test now points `IFC_DIR` at a temp dir, like every other generator test.
  No product code changed; the v0.3.480 API gate goes back green.

## v0.3.481 — REL-4 measure/section leaf · REL-5 bridge dataclasses (P2 · reliability)

- **REL-4 — `viewer/measureSection.ts`**: the measure/visibility toolbar group (↔ ▱ ✂ ⊙ ◐ ⌫ ⊞) and
  the section-box tool extracted from `app.ts` into a leaf (two positional installers because other
  groups interleave). Pure extraction — button order, behaviour and DOM unchanged, live-verified;
  `app.ts` 3,970 → 3,948 lines and keeps the tool instances (click handlers, settings, shortcuts).
- **REL-5 — editor-bridge hardening**: `bridge.py`'s `plan`/`execute` now return typed
  **`Plan`/`PlanStep`/`ExecutionResult` dataclasses** (the safety-gate step shapes are part of the
  contract, so they're spelled out), and `recipes.py`'s duplicated storey lookup is deduped into
  `_find_storey`. The offline safety-gate test updated and green (save-first, chunking, confirm
  gate, dry-run default). This closes the REL-5 remainder — the vite/bundle-budget FS item was
  audited earlier as already single-pass.

## v0.3.480 — D8 COMcheck/A117.1 approvability layer + BCF round-trip (P2 · Wave 11)

- **D8 — the approvability pre-flight grows the energy/accessibility layer** (3 new cited checks):
  - **Window-wall ratio** vs the IECC C402.4.1 prescriptive 30% cap — computed from the authored
    exterior walls (explicitly `IsExternal`-flagged; unflagged walls are never guessed at) and the
    windows' overall dims. Over the cap → `info` steering to the COMcheck trade-off/performance path.
  - **Envelope U-values present (COMcheck-ready)** — every envelope element (external walls, windows,
    roofs) must carry a `ThermalTransmittance`/U-value before a COMcheck submission is possible;
    missing ones fail with their GUIDs.
  - **Accessible entrance** (IBC 1105.1 / A117.1 404) — at least one door at the 32 in clear width.
- **D8 → BCF**: `POST /projects/{pid}/codecheck/approvability/bcf` promotes every failed (high) and
  info (normal) check to GUID-anchored, labeled BCF topics — the plan-review punchlist round-trips
  with clashes/RFIs. Idempotent (re-running replaces its own topics).
- Test-proven end to end: WWR 0% → pass, ~32% → info; stamping U-values flips the COMcheck check to
  pass; topics created/replaced idempotently. The model-health issuance gate now legitimately blocks
  on missing envelope U-values.

## v0.3.479 — F0b coarse view derivation · SpecLink breadcrumbs (P2 · Wave 11)

- **F0b — `derive_representations` recipe**: derives the coarse view-keyed representations from Body
  geometry — a dimension-true **`IfcBoundingBox`** in the Model/Box subcontext, a 2-point
  **Axis centreline** (mid-thickness, linear elements only) in Model/Axis, and a closed **FootPrint
  rectangle** in Plan/FootPrint — so massing display and schematic plans have a cheap per-view
  fallback on every element. Bounds-based by design (not a silhouette); idempotent per element+kind;
  sweeps the whole model or a GUID list. Completes the F0 spine's promised derivation half.
- **SpecLink — `set_spec_link` recipe + `GET /projects/{pid}/spec-links`**: stamp
  `Pset_Massing_SpecLink` (MasterFormat **SpecSection** + optional title/url) on elements as the
  quick model→spec breadcrumb (distinct from the formal `classify` carrier), and read the rollup —
  each linked section with its element tally + the unlinked count — for submittal/schedule grouping.
- Both registered in the authoring matrix (79 recipes, completeness guard green) and test-proven
  (bounding-box dims hand-checked against a 5 m × 0.2 m × 3 m wall).
- **B3/B4/C2 — onboarding fast-follows**: first signed-in boot offers a **role picker** (tailors
  workspaces immediately; skippable, never repeats, defers to any manual choice) · the coach-mark
  tour is confirmed at its **5-step cap** · publishing a model edit while signed out shows a one-shot
  dismissible **"sign in to save your work"** nudge (30 s auto-dismiss, never a wall). All three
  live-verified.

## v0.3.478 — W10-4 coincident-port auto-connect · webhook private-IP blocking (P2)

- **W10-4 — `auto_connect_mep` recipe**: one pass wires every unconnected MEP element pair whose
  connection points coincide (segment ends from placement + the sizing pset's length; fittings and
  terminals at their placement point) with `IfcRelConnectsPorts` — a run drawn end-to-end with a
  fitting at each junction snaps into a connected network without N manual `connect_mep` calls.
  Nearest pairs first; at a joint the **fitting claims the ports** (never a direct segment-to-segment
  weld through an elbow); strays stay untouched; re-running is a no-op (already-connected pairs and
  consumed port budgets are respected). Test-proven on an A–elbow–B–tee–C network.
- **REL-6 — webhook private-IP blocking**: set `AEC_WEBHOOK_ALLOW_PRIVATE=0` (env or Settings) and
  outbound webhooks refuse targets that resolve to private/loopback/link-local addresses (blocks
  cloud-metadata and intranet probing via a compromised settings key). Default stays permissive —
  on-prem LAN listeners are a legitimate operator choice; `file://` and friends remain always-refused.
- **A1/A2/C1 — provider-first sign-in modal**: the sign-in dialog now **leads with big Google +
  Microsoft buttons** (co-equal defaults; the first configured provider takes the lead slot when
  neither is set up), every other provider collapses behind **"More sign-in options"**, and the
  password form follows the divider. Live-verified with a stubbed 3-provider config.
- Backend suite green; web gates green.

## v0.3.477 — VIZ-2 presentation FX · CODE-4 local amendments · MEP engineering depth (P2)

- **VIZ-2 — SSAO + bloom presentation FX** in render mode: the viewer's render toggle now routes the
  frame through a three.js **EffectComposer** (SSAO contact shadows → subtle bloom → tone-mapped
  output on an MSAA half-float target), on top of the existing sun/soft-shadow/IBL/PBR upgrade.
  Wraps the engine renderer's per-frame render — no engine changes, overlay/ortho renders stay raw,
  toggling off restores the raw path and disposes the chain. Offline + license-free (bundled three
  examples). Live-verified: one wrapped call runs the full pass chain; off → single raw render.
- **CODE-4 — local-amendment overlay**: `PUT/GET /projects/{pid}/code/amendments` records the AHJ's
  **local amendments** on top of the statewide adoption — a per-family **edition override** (must be
  a published edition; beats the jurisdiction seed everywhere `_project_ibc_edition` is consulted,
  i.e. every model code check) plus recorded **section amendments** (family + section + note) that
  ride on the code context so citations can flag "locally amended — read the ordinance". Hard 422
  validation; an empty list clears the overlay; audited. `codes.apply_amendments` is the pure core.
- **MEP engineering depth** (`mep_sizing.py` + three routes):
  - **`GET /projects/{pid}/mep/pressure-loss`** — friction loss per authored duct/pipe run (empirical
    round-galvanized duct rate + **Hazen-Williams** pipe rate from the sizing pset's size + flow +
    length), checked against equal-friction budgets (0.10 in.wg / 4 ft per 100 ft), with per-system
    series-sum totals and the **index run** a balancing engineer hunts first.
  - **`GET /projects/{pid}/mep/tray-fill`** — **per-conductor NEC 392.22** cable-tray fill computed
    from the actual authored `IfcCableSegment` diameters on each tray's system vs the Table
    392.22(A) allowable (7 in² per 6 in of width) — no supplied ratio needed.
  - **`GET /projects/{pid}/mep/thermal-loads`** — space-by-space **cooling-load screen** (W/sf
    method): people/lighting/equipment densities by space type + a flat envelope allowance per
    IfcSpace, summed to tons vs the block `GFA ÷ 350` estimate, showing *where* the load lives.
  - All hand-checked against the physics in `test_mep_sizing` and honestly disclaimed (screens, not
    PE designs).
- **B2 — sign-in → tour**: signing in from the welcome panel now resumes straight into the coach-mark
  tour after the auth reload (a consumed one-shot flag), instead of dropping the new user on the raw
  workspace. Live-verified: reload with the flag → tour step 1 opens, welcome suppressed, flag cleared.
- Backend suite green (268/268); web gates green (typecheck · lint · 121 vitest · build).

## v0.3.476 — ENV-1 wind-comfort screen · VIZ-1 export parity confirmed (P2)

- **ENV-1 — `POST /projects/{pid}/env/wind`**: a pedestrian **wind-comfort screen** at massing stage —
  corner acceleration, downwash (with the podium-interception rule), and passage channelling, each
  graded on the **Lawson comfort categories** (A sitting → E uncomfortable → unsafe > 15 m/s) with
  the standard mitigations (podium/canopy, corner chamfers, porous screens). Dims explicit or derived
  from the source model's bounds. Deterministic rules of thumb, honestly labelled **NOT CFD** — a
  screen to steer massing, verified with a wind consultant for tall/exposed sites. `test_env_wind`
  covers the physics behaviors (podium cuts the downwash factor; a 10 m gap channels, 40 m doesn't;
  >15 m/s grades unsafe).
- **VIZ-1 — .glb export parity confirmed** against the live dev model: a valid glTF 2.0 binary with
  every geometry class present (Slab/Space/Wall nodes, all named). Noted design trade-off: the
  exporter merges **per IFC class** (compact presentation export), so per-element identity lives in
  the IFC/Fragments path, not the .glb — as documented on the endpoint.
- Backend suite green; web gates green.

## v0.3.475 — COST-AGENT calibration · BOARDS option decks (P2 · AI & finance frontier)

- **COST-AGENT — `GET /projects/{pid}/cost/calibration`**: the project learns from its own history —
  the model's takeoff estimate compared against **awarded subcontract values** and **posted direct
  costs**, deriving a calibration factor (observed ÷ estimate, clamped 0.5–2.0, actuals preferred)
  that `estimate_from_takeoff(benchmark_factor=…)` can apply to the next iteration. Reported, never
  silently applied. Test-proven: awarding a subcontract at 1.2× the estimate yields factor 1.2.
  (The re-estimate-on-geometry-change half shipped as PROFORMA-LIVE in v0.3.473.)
- **BOARDS — `POST /projects/{pid}/design/options/board.pdf`**: a GEN-SCORE run becomes a styled
  one-page **design-option deck** — title + recommendation, the cost/carbon/yield/compliance
  comparison table, and composite score bars — the client-facing artifact of an options study
  (`option_score.board_pdf`, deterministic reportlab).
- `test_productivity` + `test_option_score` extended; backend suite green; web gates green.

## v0.3.474 — NL-QA "audit + suggest fixes" · READY-AGENT make-ready register (P2 · AI & agents)

- **`POST /projects/{pid}/ai/audit`** — the ranked decision-readiness gaps, now with an **executable
  fix step** attached wherever a deterministic recipe can close the gap (elements missing their
  keynote/detail → `apply_detailing_rules`). The returned `fix_steps` drop straight into
  `POST /edit/batch`, so "audit → apply every automatic fix → one undoable version" is a two-call
  flow — proven in-test end-to-end. Gaps without a safe automatic fix keep their prose guidance;
  the audit itself never writes.
- **READY-AGENT — `GET /projects/{pid}/schedule/make-ready?days=N`** — every activity starting in the
  window, its preconditions **checked with cited evidence** (incomplete predecessors by ref + their
  real % complete · open submittals by ref/state) and a ready/blocked verdict. The Last Planner
  "can next week's work actually start?" answered proactively. Test-proven: a start blocked by a 20%-
  complete predecessor cites exactly that.
- Backend suite green; web gates green.

## v0.3.473 — PROFORMA-LIVE: the finance numbers follow the model as you author (P2 · finance frontier)

- **`GET /projects/{pid}/proforma/live`** — the current model version's **takeoff-priced construction
  cost** (the benchmark-guarded recommended total, content-cached per published version so it's cheap
  to poll), slab-derived **GFA**, **cost/m²**, and the **delta vs the developer budget's hard cost**.
- **The viewer surfaces it automatically:** after every model (re)load the status line reads the live
  figures — live-verified on the dev project: *“model cost $166,740 · GFA 958.5 m²”*. Re-publish an
  edit and the number moves with the geometry.
- **E7 — live paper while modeling:** the viewer now broadcasts `aec:model-published` after every
  successful model (re)load, and an open Drawings-workspace sheet — floor plan or door/window/room
  schedule — re-renders itself against the new geometry. Author a wall, watch the plan and the
  schedules update.
- **Fixed the CI flake that reddened v0.3.471/472:** the doc-graph QA's GUID regex was ``-anchored,
  but IFC GUIDs may start/end with `$` (not a word character) — such GUIDs never matched and "what
  governs <guid>?" fell back to the overview answer whenever the random test GUID ended in `$` (it did,
  twice in a row, on CI). Now matched with explicit alphabet lookarounds + a regression test over
  `$`-edged GUIDs.
- `test_productivity` extended (cost > 0, GFA > 0, cost/m², version stamp). Backend suite green;
  web typecheck / eslint / vitest (121) / build green.

## v0.3.472 — AI read tools · sign-in-first welcome (B1) · four P2 items confirmed shipped

- **The model's own numbers, readable by any agent.** The MCP catalog grows four read tools —
  `model_quantities` (discipline QTO roll-up), `computed_schedules` (door/window/room, the A-601
  data), `clash_results` (geometric intersections with GUIDs), `code_violations` (IBC 1004/1005
  occupancy/egress findings) — 18 tools total; model-less projects get a clear error, not a trace.
- **B1 — the welcome now leads with sign-in, never walls.** A 🔐 sign-in row (Google · Microsoft ·
  Procore SSO or username, via the topbar's own modal through the new `openSignIn()` export) heads
  the first-run panel; every quick-start path below it still works signed-out. Live-verified: the
  row renders first, the button opens the login modal, the never-walls copy is present.
- **Confirmed shipped (audited with proof, now marked):** S5 clarifying questions (both planner
  paths return `needs_clarification`; two UI surfaces show it) · E2 type-a-dimension/VCB (the
  dynamic-input layer: type "6", "<30", "6<30" mid-draw — v0.3.453/461/467) · W10-6 keynote legend
  (sheets render the KEYNOTES legend from Track-D codes, test-asserted) · REL-5's build-script
  batch-FS review (bundle-budget is already single-pass; no change needed).
- Backend suite 267/267; web typecheck / eslint / vitest (121) / build green.

## v0.3.471 — per-project jurisdiction + auto-resolved code edition (CODE-1b/3) · one-undo NL batches (S4)

- **CODE-1b — the project knows its jurisdiction.** `Project.jurisdiction` (USPS state code) is now a
  first-class field (PATCH `/projects/{pid}`, returned on GET; the column auto-migrates). **CODE-3 —
  the edition resolves itself:** the egress/occupancy checker cites the jurisdiction's **adopted IBC
  edition** automatically (unset → national baseline, always with the verify-with-AHJ note), and the
  `apply_detailing_rules` recipe at `POST /edit` rewords its citations to the adopted edition when the
  caller didn't pass one.
- **S4 — multi-step commands undo as one step.** New `POST /projects/{pid}/edit/batch`
  (`steps: [{recipe, params}, …]`) opens the model once, applies every step in memory, writes ONE
  version and pushes ONE edit-history entry — so a multi-step NL command reverts with a single undo.
  All-or-nothing: every step is guard-prechecked before anything runs; a bad step aborts the batch
  with nothing written. Honors the COLLAB-1 optimistic lock.
- `test_codes` extended (PATCH round-trip; FL → IBC 2021; no jurisdiction → baseline) and
  `test_edit_undo` extended (3-step batch → exactly one undo entry; one undo reverts all; bad middle
  step aborts atomically; empty batch 400). Backend suite green.

## v0.3.470 — RISK-BOARD: one register for every computed risk signal (P2 · AI & agents)

- **`GET /projects/{pid}/risk-board`** unifies the platform's computed risks into one ranked,
  deep-linked register: **Monte-Carlo schedule risk** (P80 buffer + the top delay driver by
  criticality) · **predictive schedule alerts** (overdue / late starts / blocked predecessors /
  procurement) · **EVM** (CPI/SPI below par with the recommended EAC) · **pre-flight issuance
  blockers** · **overdue open coordination issues** (aging items become claims). Every row is
  re-derived from its engine on each call — aggregation only, no new stored state; a broken lane
  drops out and reports itself in `lanes`, never breaking the board.
- The Schedule panel opens with a **🚨 Risk board** card (band + severity counts + the top 10 items).
- Live-verified on the dev project: all 5 lanes `ok`, band `critical` — 4 pre-flight blockers + the
  9.1-day P80 buffer computed from the EST-1 schedule. `test_risk_board` covers the empty board,
  signal seeding (overdue activity → alert; overdue high topic → coordination + preflight), ranking,
  deep links, and band escalation. Backend suite green; web gates green.

## v0.3.469 — DISC-poché: 2D plans read by trade (P2 · estimating/engineering)

- **`by_discipline=true` on both plan renderers.** The **cut-plane plan** (`/drawings/plan.svg`)
  strokes every element's linework with its canonical discipline color and adds a DISCIPLINES legend
  (`drawings.cut_baked_classed` keeps each polyline's IFC class through the section). The
  **footprint/sheet renderer** (`drawing.plan_svg`, feeding sheet SVG/PDF) tints its poché fills the
  same way with its own legend. Off by default — the classic monochrome poché is untouched.
- The data layer gains its renderer-side mini-spine: `disciplines.discipline_of_class` (walls/roofs/
  coverings/doors → A · slabs/columns/beams/footings → S · duct → M · pipe → P · cable/electrical → E,
  General-grey fallback), mirroring the canonical `aec_api.classification` map without a cross-layer
  import.
- Live-verified on the dev project: the plan cut rendered the DISCIPLINES legend with
  architectural-grey (#4B5563) wall strokes. `test_sections` + `test_drawing` extended (exact hex
  asserts + spine mapping + well-formedness); backend suite green.

## v0.3.468 — REL-4 slice 5: the Report Center becomes its own module

- `reportCenter.ts` (new, 469 lines) now owns the whole Report Center modal — every exportable
  report (PDF / in-app markup / Excel) and the interactive project tools & analytics (drawing-set
  register + issuance + 🚦 pre-flight gate, WH-347 payroll, PDF tools, project health, assistant,
  field-verification coverage). Extracted verbatim from `main.ts`, which drops **1,645 → 1,187
  lines** and keeps a one-line `openReportCenter(api, projectId)` call.
- Live-verified after the extraction: the modal opened with 54 report-download rows, the Drawing-set
  register tool loaded with the 🚦 Pre-flight button, and all three issuance records rendered.
- Typecheck / eslint / vitest (121) / build green.

## v0.3.467 — REL-4 slice 4: the KEYS + dynamic-input layer becomes its own viewer leaf

- `viewer/keysDyn.ts` (new, 126 lines) owns the Revit-style **2-letter draw-tool shortcuts** (WA/SL/
  CL/… · Esc disarms · ? help) with their HUD, the **typed distance/angle constraint** buffer
  ("6", "<30", "6<30") with its ⌨ HUD, and the **snap-glyph** feedback. `app.ts` keeps one
  `installKeysDyn(deps)` call; the handle exposes `dynBuf()/setDynBuf/flashSnapGlyph` for the draft
  flow. `app.ts` **3,957 lines** (4,361 at the start of this arc — five leaves out).
- Live-verified after the extraction: typing `W` showed the shortcut HUD, `WA` armed the Wall tool
  ("Wall armed — click in the model to place"), the dyn HUD is mounted, `?` opened the shortcuts
  help, and Esc disarmed. Typecheck / eslint / vitest (121) / build green.

## v0.3.466 — SHEET-LINK: the compiled drawing set navigates like a hyperlinked document (P1 #9)

- **The cover's drawing index is now clickable.** Every index row on the compiled-set cover carries a
  real PDF **GoTo link annotation** to its sheet page (`_cover_pdf` reports each row's hit-box;
  `compiled_set_pdf` binds them post-merge with pypdf) — open the set, click A-102, land on A-102.
- **Detail callout bubbles cross-link too.** The NCS divided-circle callouts report their hit-box +
  target sheet ref from the PDF renderer (`drawing.sheet_pdf(link_out=…)`); whenever the referenced
  sheet is part of the compiled set, the bubble becomes a clickable link to it. In the **SVG** path
  each bubble is now an `<a class="sheet-link" data-sheet="…">` anchor, so the Drawings workspace (or
  any SVG viewer) can jump on click.
- Links are an enhancement layer — if the binder fails for any reason the un-linked set still ships
  (fail-open). `test_drawing` (SVG anchor + link_out boxes) and `test_drawing_set` (≥4 cover links,
  callout-to-A-102 binding on the plan page) cover it; backend suite green.

## v0.3.465 — 3D-HERO: capture the live 3D view as the project package's hero page (P1 #8)

- **📸 one click in the viewer** renders a fresh frame, captures the WebGL canvas as a PNG, and pins
  it as the project's **hero image** (`PUT /projects/{pid}/hero` — magic-byte checked, 10 MB cap;
  GET streams it back, DELETE clears). The client project-package PDF now opens with it: a
  full-bleed, aspect-preserved **3D hero page** right after the cover (`package.py::_hero_page`).
  Headless server rendering stays out of scope — the capture path is the deliberate design.
- Live-verified end-to-end: the 📸 button captured a real **1.27 MB PNG** of the live model view,
  the server stored + streamed it back, and the package PDF grew to 10 pages with a 779 KB embedded
  image on page 2.
- `test_project_package` extended (404 → magic-byte 400 → PNG round-trip → package gains exactly one
  page → DELETE); backend suite green; web typecheck / eslint / vitest (121) / build green.

## v0.3.464 — JOB-QUEUE: the compiled drawing-set PDF runs on the durable queue with a downloadable artifact (P1 #7 begins)

- **Artifact jobs.** The durable queue gains its first binary-artifact kind: `compiled_set_pdf`
  renders the whole drawing set (cover + plan per storey + schedules) **off the request thread**,
  parks the PDF in object storage, and the poll result carries `artifact_key`. A new
  `GET /projects/{pid}/jobs/{id}/artifact` streams the bytes back (409 while queued/running,
  404 when a job has no artifact) — the reusable pattern the remaining heavy paths (PAdES sealing ·
  large exports · generative runs) migrate onto next.
- Enqueue with the existing `POST /projects/{pid}/jobs` (`{kind: "compiled_set_pdf", params:
  {scale?, max_sheets?, schedules?}}` — the same knobs as the inline endpoint, which stays for
  small sets). Live-verified: enqueue → `running` → `done` in one poll cycle, and the artifact
  endpoint streamed a real multi-page `%PDF` for the dev project.
- `test_jobs` extended (artifact round-trip + no-artifact 404); backend suite green.

## v0.3.463 — REL-4 slice 3: the collab/presence block becomes its own viewer leaf

- `viewer/collabPresence.ts` (new, ~150 lines) now owns the whole COLLAB-1 surface: the 👥 presence /
  ⤴ share-view / 📱 QR rail buttons, the 20 s heartbeat that shares this client's live viewpoint, the
  per-user 3D peer cursors, and the publish-reload banner fed by the model SSE stream. `app.ts` keeps a
  single `installCollabPresence(deps)` call; the handle exposes `captureViewpoint`/`jumpToViewpoint`
  (env tools · BCF viewpoints · share flows) and `resync()` for `loadProjectModel` (your own publish
  never nags you to reload). `app.ts` 4,107 → ~4,010 lines.
- Live-verified after the extraction: the reloaded client's heartbeat appeared in the server roster
  (through the leaf), a seeded peer rendered its view-cone cursor at exactly (20, 10, 15) with cone +
  dot + name sprite, the presence button read 👥 1, and the ⤴ share flow round-tripped.
- Typecheck / eslint / vitest (121) / build green.

## v0.3.462 — EST-1: QTO → crew-day durations → CPM (P1 #5)

- **The labour estimate now prices the real takeoff.** `productivity.from_takeoff` routes each
  measured QTO row (Qto psets + geometry fallback) to its productivity activity — walls → masonry
  face area, slabs → casting volume + finish area, columns/beams/footings → concrete volume (steel
  tonnage → erection), coverings → tile/ceiling area, pipe/duct/tray/cable runs → install lengths.
  `GET /estimate/labor` uses it by default (`qto=false` falls back to the rough dimension parse).
- **One click writes the durations into the schedule.** `POST /projects/{pid}/schedule/from-estimate`
  upserts one `schedule_activity` per trade group (WBS `EST`, crew-day durations, FS-chained) — CPM,
  Gantt, lookahead and Monte-Carlo risk immediately run on model-derived durations. Re-running
  refreshes durations without duplicating; manual activities are untouched. The Schedule panel grew a
  **⚙ Durations from model (QTO)** button.
- Live-verified on the dev project: 2 trade activities (Concrete 112 d → Masonry 6 d, FS chain,
  CPM 118 d); re-running with `crews: 2` refreshed the same records to 56 d + 3 d (CPM 59 d);
  `/schedule/cpm` shows the ACT-001 → ACT-002 critical path and the Gantt SVG renders it.
- `test_productivity` extended (from_takeoff mapping math + the endpoint's upsert/409/CPM chain);
  backend suite green; web typecheck / eslint / vitest (121) / build green.

## v0.3.461 — UX-2: snap-as-you-place annotation + live guide lines (P1 #4)

- **Every placed annotation now lands exactly on geometry.** A plain model click snaps the picked
  point to the hit element's nearest **vertex / bounding-edge midpoint / corner / center** (the
  classic osnap set, 0.4 m tolerance) with the ◻ snap glyph — so notes, 2-point dimensions, revision
  clouds, tags, MEP fittings and every other `lastPoint` consumer anchors on the element, not on the
  raw raycast point. `snapToGeometry` grew the midpoint/center candidates.
- **Live guide line for two-click flows.** Arming a dimension or revision cloud drops an **anchor dot**
  at the first (snapped) point and stretches a **dashed rubber line to the cursor** until the second
  click — you see exactly what will be measured before committing. Cleans up on completion.
- Live-verified: an exact-corner click flashed ◻ snap (the point snapped to the wall corner); arming
  Dimension created the `annot-guide` group (dot + dashed line) and the rubber end tracked the
  pointer across the ground plane. Typecheck / eslint / vitest (121) / build green.

## v0.3.460 — SITE-1: open-geodata site context — drop the model onto its real surroundings (P1 #3)

- **One click adds the neighborhood.** Open ▾ → *Add site context (OSM buildings)…* fetches the
  OpenStreetMap **building footprints (height-extruded), roads, and land-use parcels** around the
  site and renders them as a separate reference layer under the model. Coordinates come from the
  model's georeference (IfcSite lat/long, DMS→decimal) or typed lat/lon; radius 50–2000 m.
- **Fetch-once, offline-after.** The server (`site_context.py` + `GET /projects/{pid}/site-context`)
  queries Overpass once and caches the normalized GeoJSON in object storage — afterwards the layer
  loads fully offline (live: first fetch 4.7 s, cache hit 59 ms). `refresh=true` re-queries; DELETE
  clears. OSM data is **ODbL** — the attribution ships in every payload and shows with the layer.
- **Real heights.** Buildings extrude to their tagged `height` (else `building:levels` × 3 m, else
  6 m). Live-verified in Midtown Manhattan: 210 buildings / 249 roads; the Empire State Building's
  roof lands at exactly **443.2 m** in the scene; projection is centred on the fetch anchor so the
  context sits in the model's frame.
- Engine follows the injectable-transport client pattern — the test suite runs fully offline against
  a MockTransport (`test_site_context.py`: DMS georef, Overpass→GeoJSON normalization, cache/409/
  DELETE paths). Viewer code extends `gis.ts` (`buildSiteContext`: earcut roof caps + wall quads).
- Typecheck / eslint / vitest (121) / build green; backend suite green.

## v0.3.459 — PREFLIGHT: the issuance gate now covers keynotes · drawing-set QA · pinned IDS, deep-links every check, and gates the Issue action (P1 #2)

- **The pre-flight gate is now the full pre-issuance audit.** Three new lenses join model health /
  classification / open-issues: **keynote/spec completeness** (the detail-rule QA — components missing
  a required keynote), **drawing-set QA** (set integrity · issuance hygiene · model cross-checks, when
  sheets exist), and the **pinned-IDS validation** (the project's contractual spec, when one is pinned).
  Every check now carries a **deep link** to the API tool that drills into it (`preflight.py`).
- **Wired into the issuance flow.** `POST /drawing-set/issue` runs the gate automatically and **stamps
  the verdict on the issuance record** (a permanent "what did the gate say at the moment of release");
  `enforce: true` makes a HOLD block the issue with a 409 listing the blocking checks. The Drawing-set
  register UI grew a **🚦 Pre-flight** button (verdict + iconized checklist + ↗ deep links), and
  **📤 Issue set** now enforces by default — on a HOLD it renders the evidence and arms a one-shot
  **⛔ Issue anyway** override.
- **Root-cause bug fix found by live-driving the UI:** the Report-Center `table()` helper used
  `innerHTML +=`, which reparses the whole tool body and **silently detaches every button handler
  wired before it** — the issuance tools (Generate / Issue / Pre-flight) were dead whenever the
  register table rendered after them. It now appends a real element.
- Live-verified end-to-end on the dev stack: gate returned a genuine HOLD with all 8 lenses (the
  pinned IDS correctly failing 2/5 specs against the real model); enforced issue → 409; UI checklist +
  deep links rendered; the override issued and the record carries the 4-blocker HOLD stamp; a corrupt
  pinned IDS degrades gracefully (lens absent, no 500).
- Backend suite green (test_issuance + test_model_health extended); web typecheck/lint/vitest(121)/build green.

## v0.3.458 — COLLAB-CURSORS: multiplayer presence cursors in the viewer (P1 #1)

- **See where everyone is looking, live.** Every peer whose presence heartbeat carries a camera
  viewpoint renders as a colored **view-cone + name tag** at their camera position, aimed at their
  look-target (`viewer/peerCursors.ts` — a REL-4-style leaf from day one). Colors are stable per user
  (name-hash → hue); cursors upsert/track/remove as the roster changes; you are never shown your own.
- **The 20 s presence beat now shares your live camera viewpoint** (previously only the explicit
  ⤴ share button did) — that's what makes the cursors continuous. No protocol change: the heartbeat
  always accepted a viewpoint; the roster + the collab SSE `editors` both feed the same reconciler.
- **Live-verified end-to-end**: a seeded peer's cursor appeared at exactly its camera position
  (15, 9, 12) with cone + dot + name sprite; our own beat's viewpoint showed up in the server roster;
  and when the peer departed, the next beat removed the cursor. This completes COLLAB-1
  (awareness + edit-lock + live-reload shipped earlier; cursors were the remainder).
- Typecheck + eslint + vitest (121) + build green.

## v0.3.457 — roadmap reorganized: completed work archived, open items re-prioritized

- **`docs/roadmap.md` 679 → ~130 lines, open items only.** The full pre-reprioritization snapshot —
  every ✅/🟡-shipped entry across the UI/UX pass, Waves 9–11, the frontier bets, CAD-UX lessons,
  REL/enterprise tracks — is preserved verbatim in `roadmap-completed.md` as a dated archive section.
- The live roadmap is now three rings: **P1** (9 buildable, live-verifiable items, led by multiplayer
  cursors · the PREFLIGHT issuance gate · SITE-1 site context · snap-as-you-place annotation ·
  QTO→CPM durations · continued REL-4 slices · JOB-QUEUE migration · the package 3D hero · sheet
  hyperlinks), **P2** (the designer-workspace, CD-depth, authoring, AI-agent, finance, reliability and
  onboarding rings), and **P3 gated** (each entry names its concrete unblocking event), plus documented
  non-goals + license guardrails.

## v0.3.456 — REL-4 slice 2: the file-IO leaf out of the viewer god-file

- **`viewer/app.ts` 4,215 → 4,044 lines**: every file open / import / export path — IFC (small
  in-browser parse, large via the server pipeline with replace-confirm + publish + reload), Fragments,
  the paid convert bridge, reference overlays (mesh/point-cloud/basemap), sample models, and the
  Tauri-native open/save dialogs — extracted into `viewer/fileIO.ts` (218 lines) behind an explicit
  17-field deps seam. Pure extraction; `refCount` ownership moves into the leaf.
- Verified: typecheck + eslint + vitest (121) + build green, and live in the running viewer the
  `openFile("ifc", …)` dispatch reaches the legacy small-file branch with the correct loading overlay
  (the in-pane WASM import worker itself is a documented headless-pane limitation, identical
  before/after; the Fragments load path is proven by every boot). Cumulative REL-4: app.ts
  **4,361 → 4,044** across two live-verified slices.

## v0.3.455 — REL-4 begins: the first live-verified leaf out of the viewer god-file

- **`viewer/app.ts` 4,361 → 4,215 lines**: the environment & navigation tool set — render mode
  (sun + soft shadows), the **sun/shadow study** panel, the **first-person walkthrough**, and the
  **storey levels overlay** — extracted into `viewer/envTools.ts` (180 lines) behind an explicit deps
  seam (viewer, loader, toolbar factory, viewpoint capture, settings). Pure extraction; the sun study
  now flips the render button via a direct reference instead of scanning the toolbar by title.
- **Why this is the first app.ts split that could ship safely**: the newly-unblocked live loop proved
  behaviour unchanged in the running viewer — render mode toggles, the sun panel opens and computes
  (altitude 71° · azimuth 179° S for July noon at 40.7°N), walk mode engages, and the levels overlay
  adds exactly one grid per storey (4). Typecheck + eslint + vitest (121) + build green.
- REL-4 continues leaf-by-leaf with the same prove-it-live discipline.

## v0.3.454 — SHEET-VIEWPORTS complete: the interactive paper-space editor (lesson #8 done)

- **Drawings ▸ ⊞ Paper space** — the client half of the v0.3.449 layout engine, live-verified:
  - preset picker (`key` / `quad` / `plan-pair`, fetched from the server) + page (A1/A3/A4) + sheet
    number/title;
  - per-viewport controls: view kind (plan storey elevation · section axis@offset · elevation
    direction), fixed **1:N scale** (blank = fit), **class freeze**, add/remove;
  - a live server-composed **SVG preview** with **drag-to-move viewport overlays** — drag a dashed
    rectangle on the sheet; its fraction rect updates and the sheet recomposes (500 ms debounce);
  - **⬇ PDF** downloads the submittable sheet through the real endpoint.
- Composition stays entirely server-side and deterministic — the editor only edits the viewport spec.
- **Live-verified in the running app**: preset composed in ~0.5 s with 3 draggable overlays; a
  pointer-drag moved a viewport from rect (0, 0) to (0.12, 0.12) — exactly the drag delta — the sheet
  recomposed, and the PDF downloaded. Typecheck + eslint + vitest (121) + build green.
- With this, OpenAEC-study lesson #8 is **complete** (server slice v0.3.449 + this editor).

## v0.3.453 — SNAP-KIT phase 2: dynamic input + snap glyphs, live-verified to the IFC (lesson #2 complete)

- **Type the constraint mid-draw.** With a draw tool armed and a first point placed, typing `6`, `<30`
  or `6<30` builds a distance/angle constraint in a **HUD** ("⌨ 8<60 → 8 m @ 60° — click to place");
  the next click is constrained through the tested snap engine — the typed value **beats every
  automatic snap** (geometry, axis inference, polar, grid): explicit intent is never re-snapped away.
  Backspace edits, Esc clears with the tool. Pure parser (`dynInput.ts`), strict like the CAD polar
  tokens (`6<`, double-`<`, zero/negative distance → rejected), +3 vitest.
- **Snap-kind glyphs**: each placed point flashes what won — `◻ snap` (geometry vertex), `∠ axis`
  (inference), `◇ 45°` (polar), `⌨ 8<60` (typed) — the phase-2 osnap feedback.
- **Two interaction bugs found by driving the live viewer** (the newly-unblocked Gate-A loop):
  - a lingering **measure mode silently ate every draft click** — an armed draw tool now always wins
    over measure (measure keeps the click only when nothing is armed);
  - a stalled Fragments **raycast could wedge the click pipeline forever** — it now races a 1.5 s
    timeout and falls back to the ground plane, so drafting keeps working through any worker stall.
- **Live-verified end-to-end, to the IFC bytes**: armed the wall tool via KEYS (`WA`), clicked a point,
  typed `8<60`, clicked again — the placed point measured **exactly 8.00 m @ 60.0°** from the first;
  the wall authored + published, and the source IFC confirms two live-authored walls at **30.0°** (the
  v0.3.439 CAD polar command) and **60.0°** (this dynamic input). Typecheck + eslint + vitest (121) +
  build green.

## v0.3.452 — the "preparing geometry…" hang, root-caused and fixed (Gate A unblocked)

- **The bug**: after a model loads, `fitToModels`/`fitToItems` awaited an **animated** camera-controls
  transition. That promise resolves from the rAF-driven update loop — and a **hidden tab throttles rAF
  to zero**, so the fit never settled and the "preparing geometry…" loading overlay hung forever. Any
  user who switched tabs mid-load hit it; embedded/headless panes hit it every time (which is why the
  dev-preview "geometry loader stall" haunted every prior session — the geometry was actually loaded
  and rendering behind the stuck overlay the whole time).
- **The fix**: animate the fit only when the tab is visible (`!document.hidden`) — a hidden tab gets an
  instant fit, which needs no rAF. One line in each fit path.
- **Verified live, end-to-end, for the first time in this environment**: full stack up (API :8093 +
  Vite), model published (real Fragments conversion), viewer boots past the overlay, the Project
  Browser builds (levels/disciplines/classes/types), and — the capstone — a **polar-coordinate wall**
  (`WALL 0,0 @6<30 3`, the v0.3.439 grammar) typed into the live CAD command bar authored → published →
  reconverted → reloaded (3→4 meshes), with the source IFC confirming the wall axis at **exactly
  30.0°**, midpoint (2.598, 1.5). Undo depth 1.
- This clears the roadmap's **Gate A** (live-viewer verification): SNAP-KIT phase 2, REL-4, the
  paper-space editor, and the SITE-1 composed view are now verifiable in-environment.
- Typecheck + eslint + vitest (118) + build green.

## v0.3.451 — CI fix: the two new suites write IFC uploads to a writable dir

- `test_jobs` and `test_sheet_layout` (new in v0.3.448/449) upload a source IFC, and the default
  `IFC_DIR=/app/ifc` is **read-only in the CI container** (it resolves writable on the Windows dev
  machine, so the local gates were green while CI failed with `PermissionError: /app`). Both now set a
  local `IFC_DIR` the way `test_cost_db` already does. Test-env-only change — no src delta; both suites
  re-verified locally.

## v0.3.450 — roadmap completion: DEV-3 incremental typecheck + the ⛔ gated ledger

- **DEV-3 (measured, not guessed)**: `tsc` incremental mode with the buildinfo in `node_modules/.cache`
  (never committed) — local `npm run typecheck` **67s cold → 9.4s warm (7×)**; CI runs cold and is
  unchanged. Typecheck + eslint + vitest (118) + build verified with the change.
- **The roadmap reaches its honest completion point.** Every item that could be built and verified in
  this environment has shipped across v0.3.413–450 (the audit remediation, GEN-SCORE, PLUGIN-REGISTRY,
  VIEWER-FUNNEL, the zero-row portfolio roll-up, the authoring-router split, JOB-QUEUE, the
  SHEET-VIEWPORTS server slice, and the CAD-UX lesson arc). What remains is now a **⛔ Blocked / gated
  ledger** in the roadmap where every entry names its concrete unblocking event:
  - **Gate A** live-viewer verification (SNAP-KIT phase 2, REL-4, the paper-space editor, SITE-1 UX,
    tile-streaming, multiplayer cursors, AR);
  - **Gate B** upstream dependencies (IFC5/IFCX write, bSI Validation Service);
  - **Gate C** paid/networked services (cloud cost ingest, paid APS, SOC 2 infra, BMS/IoT telemetry);
  - **Gate D** large optional builds with complete prerequisites (coupled-frame FEM, 3D hero, Unity,
    reality capture, the frontier bets).
- DEV-2 closed with rationale (cross-process coverage on a 265-suite parallel gate costs ~30-50% wall
  for an unactioned number); SITE-1's overlay half noted as already shipping (`gis.ts` GeoJSON / DEM /
  basemap loaders).

## v0.3.449 — SHEET-VIEWPORTS: true paper-space viewport composition (CAD-UX lesson #8, server slice)

- **Sheets stop being fit-to-cell grids and become real paper space.** `sheet_layout.py`: a sheet is a
  set of **viewport rectangles** (fractions of the drawable area), each with:
  - its own view — plan storey / section / elevation;
  - an optional **fixed drawing scale** — the view is placed at true 1:N on paper and **geometrically
    clipped** to its rectangle (Liang-Barsky segment clipping, split runs on re-entry) — a fixed-scale
    viewport crops like a real one instead of shrinking to fit;
  - an optional **per-viewport class freeze** (a structure-only or MEP-only viewport of the same model);
  - fit-to-rect fallback when no scale is given (the legacy behaviour).
- Preset arrangements (`key` / `quad` / `plan-pair`) as starting points; rendered through the shared
  titleblock pipeline (SVG + PDF). `POST /projects/{pid}/drawings/layout.svg|.pdf` +
  `GET /drawings/layout/presets` (in the authoring-docs leaf).
- The interactive paper-space editor (drag viewports in the web app) builds directly on these endpoints —
  tracked as the viewer-gated remainder in the roadmap.
- `test_sheet_layout`: hand-computed clipping (corner-crossing kept, exit/re-enter splits, outside
  dropped), exact 1:50 scale text + clipped-inside-rect proof, class-freeze filtering, SVG/PDF render,
  endpoints incl. the 409-without-a-model path. 265/265 suites green; ruff clean.

## v0.3.448 — JOB-QUEUE: durable background jobs (then-bucket)

- **Heavy work stops hanging HTTP requests and stops dying with the process.** `jobs.py` is the smallest
  durable queue that fixes both with no new dependencies:
  - jobs persist as DB rows (`queued → running → done | error`) with params/result/error + timestamps;
  - one daemon worker per process claims the oldest queued job and runs its handler with its own session;
  - **crash recovery** — on worker start, any job orphaned in `running` by a dead process re-queues and
    runs again (handlers are idempotent by contract — they re-derive, never increment);
  - a handler exception lands on the row (`error` + message), never kills the worker;
  - **registry of kinds** (`register_kind`) — one line to add a kind, the same extension shape as edit
    recipes, so plugins can register job kinds too.
- Built-in kinds: `echo` (diagnostic) and the real `cobie_export` — the full-model COBie handover parse
  now proves itself in the background and reports per-sheet row counts.
- Endpoints: `POST /projects/{pid}/jobs` (editor) → `GET /projects/{pid}/jobs/{id}` (poll, cross-project
  404) → `GET /projects/{pid}/jobs` (list, bounded). Worker starts in the app lifespan.
- Unknown kinds fail **at submit** (400 with the registered list), not silently in the queue.
- `test_jobs`: crash recovery (orphaned running → re-queued → completed), error capture, endpoints,
  cross-project 404, the real background COBie export on a generated model. 264/264 suites; ruff clean.
- Inline heavy paths (bundle export, PAdES, generative runs) migrate onto the queue opportunistically —
  the infrastructure and the pattern are now in place.

## v0.3.447 — REL-3: the authoring god-router splits into leaves

- **`routers/authoring.py` 1,350 → 1,030 lines**, with 21 read-only endpoints extracted into two
  responsibility-named leaves included by the parent (so **every URL and main.py are unchanged** —
  zero caller/test churn):
  - `authoring_docs.py` — the documentation & provenance set: plan/sheet/schedule SVG · CSV · PDF, the
    spec manual, detailing/keynote QA, the document graph + element sources;
  - `authoring_analysis.py` — structural (analytical model, gravity solve, ASCE 7 lateral) + MEP
    (system browser, sizing, connectivity, sprinkler coverage) + the element-connection graph;
  - `authoring_shared.py` — the shared project-with-source precondition + safe-filename helper.
- `authoring.py` keeps what it is actually about: the edit/recipe surface (apply, graph, preview,
  history/undo, AI author, publish). Behaviorally smoked: all 12 moved URL families live at unchanged
  paths (409-not-404 on a sourceless project). 263/263 suites green; ruff clean.

## v0.3.446 — PERF: the owner portfolio roll-up goes zero-row

- **`/portfolio/summary` no longer materializes any module rows into Python.** The audit's N+1 finding:
  per project it loaded every open/mitigating risk row (for a sum) and every incident row (for a
  classification tally). Now all four per-project figures are SQL aggregates — risk count via state-scoped
  COUNT, risk exposure via the (new) state-scoped `sum_field`, OSHA-recordable tally via the (new)
  `count_field_in` JSON-classification COUNT, open RFIs via the existing COUNT — so the owner dashboard
  scales with the project count, not the record count.
- New portable helpers in the module engine (Postgres `->>`/SQLite `json_extract`):
  `sum_field(..., states=[…])` and `count_field_in(db, key, pid, field, values)` — reusable for every
  future tally that today walks rows.
- Verified against the 3,000-row mega-project scale suite (dashboard tallies unchanged) + tenant-scoping
  + dashboard suites. 263/263 green; ruff clean.

## v0.3.445 — VIEWER-FUNNEL: the demo gets its free-IFC-viewer identity (+ roadmap closures)

- **massing.build now names what it already ships**: the hero CTA and a dedicated landing section present
  the live demo as a **free in-browser IFC viewer & model checker** — open your own .ifc (small files
  parse in-browser via WASM, "no signup, no install, no upload — your model never leaves your machine"),
  inspect properties/quantities, run read-only model QA — with the explicit upgrade path to the free
  desktop app / full stack. Visually verified. (CAD-UX lesson #5 — the viewer-funnel positioning.)
- **Roadmap closures backed by the v0.3.441 audit evidence** (no code change needed):
  - UI-SURFACE №11 — the caller scan found no zero-caller client methods (flagged names were recipes
    dispatched by string); nothing to delete.
  - REL-5/7 — `errorReporting.ts` already wires window.onerror + unhandledrejection to the error log,
    panel promises carry near-universal `.catch` coverage, and the "~1,075 dead lines" claim did not
    survive proof.

## v0.3.444 — PLUGIN-REGISTRY: manifest-gated recipe plugins (CAD-UX lesson #6)

- **Third-party authoring recipes without archaeology.** A plugin is a directory with a `plugin.json`
  manifest + a `register(api)` entry that adds **namespaced GUID-stable recipes** (`<plugin>.<recipe>`)
  into the same registry every authoring surface dispatches — `POST /edit`, the CAD command line, the AI
  bar, MCP `run_recipe` — and they appear in the authoring matrix automatically, categorized.
- **Three hard gates** (the OpenAEC-study design, adapted):
  - **opt-in** — plugins execute Python at load, so discovery is OFF unless `AEC_PLUGINS_ENABLED=1`;
  - **api-version gate** — the manifest's `api_version` MAJOR must match the host's `PLUGIN_API_VERSION`
    (1.0); a mismatch refuses the plugin with a clear reason instead of loading the wrong contract;
  - **collision refusal** — an existing recipe key is never overwritten.
- Refusals are data + logs, never fatal (one broken plugin can't block the rest); reload is idempotent
  (previous registrations replaced). `GET /plugins` shows loaded + refused with reasons;
  `POST /plugins/reload` is platform-admin (RBAC on). Loaded at boot via the app lifespan.
- **Template + worked example** at `plugins/` (`example-wall-brand`: stamps a pset on every wall by
  reusing the host's own `edit.set_pset_on_class` primitive — build on the toolkit, don't re-invent).
- `test_plugin_registry`: off-by-default, all four refusal modes (bad api / no manifest / register()
  raised / collision), idempotent reload, the namespaced recipe applied through `apply_recipe` on a real
  IFC + visible categorized in the authoring matrix, endpoints incl. the RBAC-on 403 on reload.
  263/263 suites green; ruff clean.

## v0.3.443 — GEN-SCORE: generative design-option scoring (cost · carbon · yield · code)

- **The frontier bet lands**: `option_score.py` generates a deterministic variant grid around a zoning
  envelope (`generate_options` — FAR-utilisation steps × building types) and ranks every candidate
  through the platform's own engines in one pass:
  - **cost** — conceptual $/SF (regionalized, escalated);
  - **carbon** — whole-building embodied-carbon benchmarks (kgCO₂e/m² GFA by building type, editable
    defaults aligned with the cost catalog);
  - **yield** — net sellable/leasable area from the massing engine;
  - **compliance** — FAR-achieved and height-limit zoning checks: a violating option is flagged, its
    composite capped below every compliant one, and it is never `recommended`.
  Criteria are min-max normalized within the option set (a flat criterion scores 100 for all — it can't
  differentiate, so it penalizes no one) and combined by overridable weights.
- `POST /projects/{pid}/design/options/generate` + `/design/options/score`; typed client methods; a
  **⚖ Score options** block on the conceptual-estimator card (Analytics ▸ Risk & Cost): lot W/D + FAR +
  height limit → ranked table (score, $/sf, tCO₂e, floors, GFA, code ✓/✗, ★ recommended).
- Deterministic, offline, no LLM — the "generative" part is a systematic grid, the scoring is the
  engines. Deepen later with per-option 5D takeoffs + EPD carbon once options carry real models.
- `test_option_score`: hand-computed grid (2×3), warehouse-beats-hospital on cost+carbon with equal
  yield, carbon total = GFA × benchmark, weight steering, compliance gating, empty-set 400, endpoints
  end-to-end. 262/262 suites green; web typecheck + eslint + vitest (118) + build green.

## v0.3.442 — full-codebase audit: backend fixes, parse robustness, infra hygiene

The backend + cross-cutting lanes of the same audit as v0.3.441 (three parallel deep passes over the
whole tree), every finding fixed and verified:

- **IFC cache bypass (P1 perf)** — `deps.open_source_ifc` called raw `ifcopenshell.open()` per request,
  so every hit on the QA / health / georeferencing endpoints (which dashboards poll) reparsed the full
  model from disk while authoring endpoints served the same file from the LRU. Now routed through the
  shared `(path, mtime, size)`-keyed cache — same invalidation on re-upload.
- **Cost-vintage import gating (P1)** — importing a vintage flips the global `is_latest`, silently
  repricing every unpinned project's estimate — yet the routes were auth-only. Now: open with RBAC off
  (dev/single-operator parity), **platform-admin** (`AEC_ADMIN_EMAILS`) with RBAC on. +403 test.
- **Authoring race (P1)** — two concurrent edits (or an `/edit` racing an MCP `run_recipe`) both read the
  same `source_ifc` and the last pointer-swap commit silently orphaned the other user's authored version.
  All three read-modify-write paths (`/edit`, `/edit/graph`, MCP `_run_recipe`) now hold the per-project
  `pid_lock` for the whole load→apply→swap→commit cycle, re-reading the pointer under the lock.
- **One escalation baseline (P2)** — the conceptual estimate escalated its headline from a private
  2025/4.5% pair while `total_at_construction_midpoint` in the same response used the market table's
  2026/region rates. Now both derive from `market_intelligence` — no unaccounted gap.
- **Honest GFA benchmark (P2)** — the model-vs-benchmark trust test compared escalated model dollars
  against a base-year benchmark computed from NET area. The benchmark now grosses up net→gross (×1.15)
  and carries the same localization/escalation factor as the model total — `recommended` flips on model
  completeness, not on dollar-year or area-basis skew.
- **Parse robustness (COBie + drawings)** — all 8 silent `except: pass` swallow sites (psets, contact
  emails, zone/system members; mesh bake, section cuts, room tags, element callouts, elevation
  silhouettes) now **count what they skip and log it** (debug per element + one summary warning per
  operation). A half-parsed model is visible in the export log, never silently thin. Shapes unchanged.
- **One billed-to-date** — `project_budget.billed_to_date` (SQL SUM) replaces three hand-rolled
  owner-invoice sums (loan-draws keeps its row-walk — it needs per-tranche dates for interest accrual).
- **Infra** — security scan pinned to Python 3.12 (audit the interpreter that ships); the version guard
  now locks the whole @thatopen suite + three as a recorded known-good tuple (bumping one package alone
  fails CI until the tuple is deliberately updated; negative-tested); inert CodeQL template step removed;
  `cost_db.resolve` docstring corrected (nearest-above fallback).

Audit non-findings worth recording: caches are bounded (LRU + eviction), temp files clean up in
`finally`, the test-manifest guard structurally prevents orphan suites. 261/261 suites green; ruff clean.

## v0.3.441 — web audit fixes: live streams that actually live, honest sorting, strict polar

From the full-codebase audit (frontend lane) — five defects the toolchain can't see:

- **SSE auth (P1)** — the backend accepts an `aec_token` cookie precisely because EventSource cannot send
  an Authorization header, but the client never set it: under production RBAC every live stream
  (model collab, notifications, pull-plan board) resolved anonymous → 403 → silent infinite reconnect.
  `setToken` now mirrors the bearer token into the cookie (Path=/, SameSite=Lax, Secure on https;
  cleared on logout), so the "real-time" features are real in production, not just in dev.
- **SSE demo guard (P1)** — `liveStream` now short-circuits in the Pages/demo build (no backend there):
  previously opening the viewer or Schedule panel in the public demo spawned an EventSource that died
  CLOSED and retried forever (5s→60s), spamming console errors. Same `IS_DEMO` guard every fetch has.
- **Live-board teardown (P2)** — the pull-plan SSE stream + presence timer now close synchronously when
  the Schedule panel re-renders (module-level replacement) and on the first event after the view is
  left — rapid Schedule↔Home toggling used to stack concurrent streams for up to 20 s.
- **Record-list sorting (P2)** — the module-table comparator is now type-aware: numeric fields compare as
  numbers ("10" after "9"), blanks group at the end in both directions ("5 < ''" and "5 > ''" are both
  false, so blank rows used to scatter randomly through a numeric sort).
- **CAD polar strictness (P2)** — malformed polar tokens now error instead of guessing: `5<` (angle
  dropped) drew a wall due east, `<45` a zero-length wall, `@5<45<90` silently ignored the tail —
  `Number("")` is 0. Exactly one `<` with a number on each side is required. +1 vitest case (4 forms).

Typecheck + eslint + vitest (118) + build green.

## v0.3.440 — COST-DB: import your own cost book (custom vintage)

- **A firm can now price through its OWN rates**, not just the shipped benchmark. `POST
  /cost/datasets/import-custom` installs a cost book as a `custom`-origin vintage:
  - body is a flat `{"rates": {"IfcWall": 180, "IfcColumn": 240}}` map (quickest) **or**
    `{"rows": [{"ifc_class": "IfcWall", "total_cost": 180, "description": "…", "uom": "m2"}, …]}`;
  - missing MasterFormat codes are filled from the classification spine off the IFC class;
  - re-importing the same (year, quarter) **replaces that custom vintage in place** (a corrected upload
    never duplicates); it's set latest and a project prices through it, localized + escalated like any
    vintage.
- New `cost_db.import_custom_vintage` + a pure, tolerant `parse_cost_rows` (accepts `total_cost`/`rate`/
  `cost`/`unit_cost`, drops rows without an ifc_class or a positive rate). Offline — this is the "+ import"
  the COST-DB task always implied. `test_cost_db` extended (both body forms, in-place replace, empty→400,
  the parser edge cases). 261/261 suites green; ruff clean.

## v0.3.439 — CAD command line: AutoCAD relative + polar coordinates

- **The command line now speaks the coordinate grammar every drafter already knows.** Point tokens in
  `WALL`/`BEAM`/`SLAB` accept, in addition to `x,y` absolute:
  - `@dx,dy` — **relative** cartesian (offset from the previous point in the command);
  - `d<a` / `@d<a` — **polar** (distance `d` at angle `a`° CCW from east), absolute-from-origin or relative.
  So `WALL 0,0 @5<0` draws 5 m east, `WALL 0,0 @5<90` 5 m north, and `SLAB 0,0 @4<0 @4<90 @4<180 0.3`
  walks a 4 m square slab — no mental cartesian arithmetic. Absolute `x,y` is unchanged.
- Pure-parser change (`cadCommands.ts`), so it's exhaustively unit-tested and flows through the existing
  command-bar dispatch with no viewer wiring. 4 new vitest cases (relative, relative-polar, absolute-polar,
  the polar square). Typecheck + eslint + full vitest (117) + build all green.

## v0.3.438 — the developer proforma carries the cost provenance too

- **One cost basis, visible everywhere.** The dev-budget **sync-from-model** now returns the same
  `cost_adjustment` block (location index · escalation · combined factor) the takeoff and 5D endpoints
  carry — so a developer sees *why* the model-derived hard cost is what it is (which vintage, localized to
  which region, escalated to which year), not just the number. The hard cost itself already priced through
  the localized/escalated vintage (v0.3.436); this surfaces the provenance, it does not re-apply it.
- Completes the cost-provenance theme across all three model-cost surfaces (takeoff · 5D · proforma).
  Backend-only; covered by the existing dev-budget sync test path. 261/261 suites green; ruff clean.

## v0.3.437 — 5D element costs price through the localized/escalated vintage

- **The per-element 5D table now agrees with the takeoff.** `/5d/element-costs` (5D-BIND) priced every
  GUID off the static representative rate table while `/qto/by-floor` priced through the project's
  localized + escalated cost vintage — the two could disagree. `element_5d.element_costs` now takes an
  optional `rate_overrides` map and the endpoint feeds it the same `_vintage_overrides` the takeoff uses.
  The rate **basis** (volume/area/length/count) always stays representative; only the rate magnitude is
  overridden — exactly how the estimate layers overrides. The response carries `cost_vintage` +
  `cost_adjustment` like the takeoff, so per-element and roll-up numbers are one source of truth.
- Falls back to the representative table when no vintage is installed (unchanged behaviour). `test_element_5d`
  extended (override changes only the targeted class; others keep the base rate). 261/261 suites; ruff clean.

## v0.3.436 — COST-DB: localized + escalated cost vintages (offline)

- **Element-level estimates are now project-real, still offline.** A cost vintage stores national-average
  rates for its year; `cost_db.rates_for_project` makes them specific to *this* project by multiplying by
  the project region's **location cost index** and **escalating** from the vintage year to the construction
  midpoint — reusing the shipped market table (`market_intelligence.escalation_factor`), no network.
- **Wired into the estimate path.** `/qto/by-floor` and `/estimate/from-model` price the takeoff through the
  localized + escalated rates and return a `cost_adjustment` block (location index · escalation factor ·
  combined factor); `GET /projects/{pid}/cost-vintage` previews the same adjustment without running a
  takeoff. Region + timeline come from the project's `market_assumption` (adopted, else latest) — the same
  source the market panel reads, so the numbers agree.
- **Refactor:** `escalation_factor(region, from_year=…, to_year|start_year…)` extracted from `escalate` so a
  vintage's rates are only ever escalated over the years they actually span (vintage year → midpoint), and a
  dollar amount still escalates from the base year exactly as before. Neutral by default: no region + no
  timeline → global-average index (1.00) and no escalation, so rates are unchanged.
- Backend-only; no UI change. `test_cost_db` extended (localize × escalate math, neutral defaults, both
  endpoints carry the adjustment). 261/261 suites green; ruff clean.

## v0.3.435 — MCP-PACK: the MCP surface becomes a first-class authoring + analysis agent (CAD-UX lesson #7)

- **The MCP tool catalog grew 8 → 14.** External AI agents (Claude Desktop, an agent) can now drive the
  authoring + analysis engines, not just read status — through the *same* gated engines the UI and HTTP API
  use, so nothing is duplicated and the surface can never exceed a normal caller:
  - `list_recipes` — the authoring-coverage matrix (every recipe drivable, by category + IFC output);
  - `run_recipe` — apply a **GUID-stable authoring recipe** (add_wall, add_column, set_pset, …), saving a
    new audited, undoable IFC version (reconvert/publish stays on the normal flow);
  - `schedule_risk` — Monte Carlo P10/P50/P80/P90 completion + delay drivers;
  - `carbon_report` — A1–A3 embodied carbon + Buy Clean limits + LEED inventory;
  - `permit_readiness` — submission-readiness over egress + code + sheet coverage;
  - `drawing_qa` — drawing-set QA (duplicate/gap numbers, titleblock, model cross-checks).
- **Same authorization as the UI.** The two write tools (`create_rfi`, `run_recipe`) carry the identical
  **editor**-role gate their HTTP routes use when RBAC is on — membership alone isn't enough; a viewer-role
  member is refused. Read tools stay membership-scoped (a non-member identity is refused per SEC-MCP).
- **A drop-in Claude skill pack** at `docs/mcp-skills/` — `SKILL.md` plus three copy-ready playbooks
  (draft-an-RFI, run-a-takeoff, drive-a-recipe) so an agent knows *how* to use the tools: read before
  writing, ground every action in the project's real state, publish after a batch of edits.
- `docs/mcp.md` + README refreshed; `test_mcp_standards` extended (catalog, the new engine tools, the
  editor gate on `run_recipe`, the no-model error signals). 261/261 suites green; ruff clean.

## v0.3.434 — SNAP-KIT (phase 1): the precision engine + polar tracking in draft mode (CAD-UX lesson #2)

- **New authoring precision** (from the OpenAEC study — object-snap / polar / dynamic-input is the other
  half of "friendly CAD"). A pure, unit-tested geometry engine `snapEngine.ts` (sibling to `inference.ts`):
  - **`resolveSnap`** — nearest object-snap among candidates within tolerance, priority-ordered
    (endpoint › intersection › center › perpendicular › midpoint › grid › nearest); **`segmentSnaps`**
    emits endpoint + midpoint candidates for a polyline (the viewer feeds it what it raycasts);
  - **`polarConstrain`** — AutoCAD polar tracking: snap the bearing from an origin to the nearest N°
    increment (distance preserved), with a lock flag + the locked angle;
  - **`applyDynamicInput`** — constrain the rubber-band by a typed distance and/or angle (the
    "5 <Tab> 90 <Enter>" flow) — distance-only keeps bearing, angle-only keeps length, both give an
    exact point.
- **Wired into draft drawing now**: when the axis/parallel inference doesn't lock, the click snaps to the
  nearest **45° increment** from the previous point — catching the diagonals the axis-only inference
  missed. Additive + guarded (a hard geometry-vertex snap always wins).
- 14 exhaustive vitest cases + verified live in the browser runtime (polar ~46°→45° with distance
  preserved, dynamic-input distance/angle exact, endpoint-beats-midpoint). Typecheck + eslint + full
  vitest (113) + build green. *(Phase 2 — osnap glyphs + a live dynamic-input overlay in the cursor — is
  tracked in roadmap §🧭; the tested engine is ready for it.)*

## v0.3.433 — docs: client-vs-server architecture doc (OpenAEC-study lesson #4)

- New [`docs/client-vs-server.md`](docs/client-vs-server.md): where work runs and why — the thin-client /
  Python-authoring-service boundary (client renders/snaps/drafts; server holds the IFC source of truth and
  does every geometry mutation + analysis), plus the two platform limits that shape the client, banked
  from the OpenAEC study: **WebGL2 has no vertex-stage storage buffers** (custom 2D fill/linetype must
  triangulate or gate on WebGPU — today our 2D is server-side SVG/PDF, so it's moot) and **wasm is
  single-threaded without SharedArrayBuffer**, which needs cross-origin isolation (documenting exactly how
  nginx COOP/COEP + the Pages `coi-serviceworker` provide it, and why the attachment route sets CORP).
  Doubles as onboarding + architecture reference; no code change.

## v0.3.432 — docs: roadmap hygiene — archive the shipped upgrade cycle, refresh the intro

- Roadmap maintenance per the file's own "holds only what's OPEN" rule: the intro now reads **latest
  release v0.3.431** (was v0.3.412); the fully-shipped 🎯 upgrade-plan tiers (P0/P1/P2/P3 v0.3.413–428)
  and the CADCMD/AUTHOR-MATRIX study outputs are archived in `roadmap-completed.md` with a compact
  pointer left in `roadmap.md`; the "Current focus" section rewritten to name only what's genuinely open
  (REL-4 web decomposition, REL-3 remainder, DEV-2/3, REL-5/7, COBie robustness, the №11 tail, the №18
  bucket, and the remaining CAD-UX lessons). No code change.

## v0.3.431 — AUTHOR-MATRIX: a live authoring-coverage matrix (OpenAEC-study lesson #3)

- **New reference surface** (from the OpenAEC study — their COMMANDS.md capability tracker is a cheap,
  brutally-honest maturity signal). `authoring_matrix` derives an authoring-coverage table **live from
  the `edit.RECIPES` registry** + a curated category/output map: **76 recipes across 14 categories**
  (create-structure / -enclosure / -opening / -space / -mep / -content · annotate · edit · type · group ·
  data · lifecycle · analysis), each with the IFC element it produces.
- Served at `GET /reference/authoring-matrix`, rendered to the committed `docs/authoring-matrix.md`, and
  guarded by a **completeness test** — a newly-added recipe with no category fails the gate, so the
  coverage doc can't silently drift from what's actually built (the honest tracker only works if it stays
  honest). It also documents that every recipe is one GUID-stable pass, dispatchable from the CAD command
  line, the AI command bar, the node canvas, or the panels.
- Verified: the matrix covers every registry entry exactly once, create-* rows all name an IFC output,
  the markdown renders clean, and the endpoint serves it; `ruff` clean.

## v0.3.430 — CADCMD: a CAD command line over the viewer (OpenAEC-study lesson #1)

- **New authoring surface** (from the OpenAEC / Open CAD Studio study — their single biggest UX win is
  importing AutoCAD muscle memory). A **deterministic CAD command line** in the viewer's authoring tools,
  instant and offline (no LLM roundtrip), driving the same GUID-stable edit recipes as the panels:
  - AutoCAD-style grammar + single-letter aliases — `WALL`/`W`, `COLUMN`/`C`, `BEAM`/`B`, `SLAB`/`S`,
    `LEVEL`/`LVL`, `SPACE`/`SP` — e.g. `WALL 0,0 5,0 3`, `C 2,2 3.2 0.4`, `SLAB 0,0 5,0 5,5 0,5 0.25`;
  - **↑/↓ history**, **spacebar repeats the last command** on an empty line, `Esc` clears, `HELP` lists
    the grammar and `HELP WALL` shows one usage; every parse error carries the usage string.
  - The parser is a **pure module** (`cadCommands.ts`) — no DOM, no network — so it's exhaustively unit
    tested (11 cases: each verb + aliases, defaults, z-coordinate ignore, trailing-thickness detection,
    and the error paths); the viewer supplies only the input + apply/reload.
- Complements (doesn't replace) the AI "type what you want" bar: the CAD line is exact and instant for
  drafters who already know the grammar; the AI bar is forgiving for everyone else.
- Verified: typecheck + eslint + full vitest (99, +11) + production build green. The OpenAEC study's other
  lessons (snap/dynamic-input kit, authoring-coverage matrix, client-vs-server doc, plugin registry, MCP
  pack, sheet viewports) are captured in `docs/roadmap.md` §🧭.

## v0.3.429 — UI-SURFACE: schedule acceleration levers on the Schedule panel (P2 №11)

- Surfaced the **schedule-optimization advisory** (`/schedule/optimize`) — it was API-only. The Schedule
  panel now shows a "🚀 Acceleration levers" card directly under the Monte Carlo risk card: the crash
  candidates (longest critical activities) and fast-track candidates (consecutive critical activities to
  overlap) with the days each saves, the best-single-lever headline, and the optional AI narrative. The
  pairing is the point — the risk card says *how late you might be*, this card says *how to pull it back*.
- Advisory only (it never rewrites the schedule), and it degrades to a hint when the network has no
  critical path. Verified: typecheck + eslint + vitest + build green.
- *(№11 note: the earlier "~70 unused client methods" over-counted — most flagged names are authoring
  recipes dispatched by string, or methods surfaced under a variant name like `bidLevelingDetail`; the
  genuinely-dark high-value read endpoints are being surfaced, not deleted.)*

## v0.3.428 — 5D-BIND: every GlobalId carries its live cost (+carbon) row (P3 №17)

- **New capability** (upgrade-plan P3 №17 — the last buildable P3 item; №16 LAYOUT-EXPORT was found
  already shipped in Wave 8). New `element_5d.element_costs`: the **GUID-keyed 5D table off the live
  property index** — element quantity (in the rate's basis: volume/area/length/count, from the
  element's own Qto sets) × the class rate — so a GUID-stable edit → republish → reindex **reprices
  automatically**, nothing to resync. Honest exclusions: no rate or a basis/Qto family mismatch is
  skipped, never guessed.
- **Carbon rides the same row** where the material matches — one table serving cost heatmaps, carbon
  hotspots, and (later) generative option scoring against cost + carbon + code in one pass. Class +
  storey rollups, top-cost list. `GET /projects/{pid}/5d/element-costs` (404 until a model loads).
- Hand-computed fixture (wall/slab/door/pipe across all four bases; mismatch exclusions asserted) and
  the reprice semantics proven: doubling the slab volume changes exactly that row (cost 825→1650,
  carbon 450→900). cost/estimate suites green.

## v0.3.427 — QA-AGENT: drawing-set QA review, every finding sheet-cited (P3 №15)

- **New capability** (upgrade-plan P3 №15; agentic drawing review is the 2026 benchmark — but most
  tools review raster PDFs; this platform generates its sheets, so QA checks the **structured source**
  directly — no OCR, no hallucination). New `drawing_qa.review`:
  - **Set integrity** — duplicate sheet numbers (critical → HOLD), numbering gaps that name the missing
    sheets, empty titleblock fields (title/discipline);
  - **Issuance hygiene** — issued sheets with no issue date, unparseable revision tokens;
  - **Model cross-checks** — plans-per-storey (an N-storey model needs N plan sheets), a door schedule
    when doors are modeled, S/M/P-series coverage when structural/MEP elements exist;
  - findings ranked critical → major → minor, each **cited to its sheet**, with a HOLD / REVIEW / CLEAN
    verdict. Runs register-only without a model and adds the cross-checks when one loads.
- `GET /projects/{pid}/drawing-set/qa`. Deterministic + offline (the honest core an AI reviewer can
  later narrate). Verified on a deliberately-defective register (dup A-101, missing A-103, issued-no-date,
  bad revision, blank title) + a 5-storey model; drawing-set/sheetgen/issuance suites green.

## v0.3.426 — UI-SURFACE: the new engines are now visible in the portal (P2 №11, first slice)

- The three capabilities shipped in v0.3.423–425 now have a UI (they were API-only):
  - **Schedule panel → "🎲 Schedule risk (Monte Carlo)"** — CPM vs P50 vs P80 (+ calendar finishes),
    on-time odds, the P80 buffer a reliable commitment needs, PPC-calibration note, and the top-5
    delay drivers with criticality % and mean slip.
  - **Risk & Cost panel → "Carbon compliance"** — total tCO₂e off the model with coverage % and
    intensity, the Buy Clean pass/needs-EPD table with headroom, and the top hotspots.
  - **Risk & Cost panel → "Permit-submission readiness"** — READY/NOT-READY verdict, readiness % +
    approvability %, and the ranked deficiency list with actions.
- New typed client methods (`scheduleRisk`, `carbonComplianceReport`, `permitReadiness`); panels degrade
  to a "load a model" hint when no model/index exists. *(Remaining in №11: triage of the legacy unused
  client methods.)*
- Verified: typecheck + eslint + vitest (88) + production build green.

## v0.3.425 — PERMIT-CHECK: permit-submission readiness in one report (P3 №14)

- **New capability** (upgrade-plan P3 №14; cities are rolling out AI plan review in 2026 — applicants
  who arrive pre-checked win the queue). `permit_check.readiness` composes what the platform already
  computes into the intake report a permit tech would produce:
  - the **computed egress check** (IBC 1004/1005 from the model's spaces + doors — a shortfall is a
    plan-review *rejection*, ranked critical), the **approvability pre-flight** (≥80% bar), and the
    **code-analysis summary** (occupancy group + construction type declared, jurisdiction-adopted
    edition resolved);
  - the **drawing register's required sheet series** (G code analysis · A · S · M · E · P) — each
    present/missing with counts.
- Output: an intake **checklist** (requirement · satisfied · evidence), the **deficiency list** ranked
  critical → major → minor with concrete actions, readiness %, and a READY / NOT-READY verdict — with
  the not-a-certified-review disclaimer. `GET /projects/{pid}/permit/readiness`.
- Verified end-to-end: 409 without a model; a seeded 2-storey model + spaces produces the composed
  report; registering the six sheet series + declaring occupancy/type/jurisdiction flips the rows and
  raises readiness. Fixed en route: the engine takes an edition *year*, not a jurisdiction string (the
  test caught the misuse live). codecheck/approvability/code-analysis suites green.

## v0.3.424 — CARBON-EC3: compliance-grade embodied carbon off the model itself (P3 №13)

- **New capability** (upgrade-plan P3 №13; LEED v5 makes an embodied-carbon inventory **mandatory for
  projects registering after July 1, 2026**, and Buy Clean programs set procurement GWP limits). New
  `carbon_compliance` layer on the existing factor table:
  - **Per-element A1–A3** (`GET …/carbon/elements`) — material category matched from each element's
    name/type/material psets, quantity from its **own Qto sets** (volume→m³ else area→m²), carbon keyed
    by **GlobalId** so hotspots click through to 3D. Honest coverage %: a unit-family mismatch or an
    unmatched material is excluded and reported, never guessed. Storey + category rollups, intensity
    per m² GFA.
  - **Buy Clean check** — achieved factor vs representative program GWP limits per category; a fail on
    a default factor reads "obtain a product EPD below the limit" — exactly the procurement action the
    program forces.
  - **LEED-style A1–A3 inventory** (`GET …/carbon/compliance`) — category rows (quantity · factor ·
    source · share), intensity, coverage and a plain-language disclosure. Offline + deterministic;
    factors are labeled representative until a deployment supplies product EPDs.
- Hand-computed test (930 kg over a 6-element fixture with deliberate mismatch/unmatched cases, 60%
  coverage honesty, Buy Clean pass + fail directions, inventory shares = 100%); existing carbon suite green.

## v0.3.423 — SCHED-RISK: Monte Carlo schedule risk over the CPM network (P3 №12)

- **New capability** (upgrade-plan P3 №12; probabilistic forecasting is table-stakes in 2026 CM tools).
  `schedule_risk.simulate` runs a Monte Carlo over the existing FS network: per-activity
  **triangular(optimistic, most-likely, pessimistic)** durations — explicit `duration_optimistic` /
  `duration_pessimistic` fields honored, sensible fat-right-tail defaults otherwise — and reports
  **P10/P50/P80/P90** project duration (+ calendar finishes when the schedule carries a start date),
  the **P80 buffer** over the deterministic CPM date, an on-time probability, a duration histogram,
  the per-activity **criticality index** (share of iterations on the critical path — the near-critical
  work a single CPM pass hides), and a **delay-driver ranking**.
- **PPC calibration** — the team's own Last Planner reliability calibrates the default pessimistic
  tail (auto-pulled from the pull-plan board; 80% PPC = neutral, below widens, above narrows —
  explicit per-activity fields are never overridden). The calibration signal PPC theory says it carries.
- `GET /projects/{pid}/schedule/risk?iterations=&seed=&ppc=` — seeded runs reproduce exactly.
- Verified on a hand-checked diamond network (deterministic CP 40d; percentile ordering; A1/A4 100%
  criticality, long branch ≫ short branch; PPC-50 P80 > PPC-95 P80; degenerate triangle = deterministic;
  cycle + empty guards) + endpoint smoke; cpm/alerts/optimize/pull-plan suites green.

## v0.3.422 — README-TRIM: the README reads like a README again (P2 №10 — P2 docs complete)

- **README** 983 → 560 lines: the "Recent platform work" section keeps the five newest narrative arcs
  (v0.3.113 → v0.3.412) and replaces the ~430-line release-by-release history dump with a one-paragraph
  pointer to `CHANGELOG.md` + `docs/roadmap-completed.md` (which is where that record belongs).
- The five June point-in-time audit docs (`audit-2026-06`, `gc-tools-audit`, `ux-findings`, `ux-ia`,
  `phase2-large-models`) now carry a "superseded — kept for the record" banner so nobody mistakes them
  for current state.

## v0.3.421 — DEMO-REGEN: the Pages demo snapshot rejoins the present (P2 №9)

- The massing.build/app viewer-only demo serves a captured API snapshot — last regenerated at
  **v0.3.309**, ~110 releases ago, so every panel added since rendered empty in the public demo.
- `build_demo_data.py`'s crawl list extended with the v0.3.310–420 surfaces — model QA / health /
  export-QA, versions (+ element-level diff), the structural chain (lateral incl. the drift screen,
  solve, analytical), MEP sizing + sprinkler coverage, doc-graph, scene digest, collab + edit history,
  drawing-set issuances, per-discipline quantities, and the global discipline tree — and re-run against
  the current seed: **952 fixtures (908 KB)**. Pushing this redeploys the live demo via Pages.
- Verified: typecheck + production build green with the new snapshot bundled.

## v0.3.420 — TZ-UTC: one clock for due-date & aging math (P1 №8 — P1 complete)

- **Bug fix** (upgrade-plan P1 №8, the last P1): overdue/aging computations in the dashboard, BIM-KPI
  scorecard, CDE container aging, closeout punch aging, CMMS PM scheduling, EVM data-date and the
  document manager's naming date compared ISO-stored dates against the **server's local wall-clock** —
  "overdue" and "days open" drifted a day around midnight and changed with the host timezone
  (`benchmarking.py` already did this right).
- New `timeutil.utc_today()/utc_now()`; all seven engines now age on the UTC clock. The EVM and
  operations suites' expectations aligned to the same clock — they were computing planned-value /
  next-due on local-today and genuinely tripped the fix during a local evening past UTC midnight
  (the exact drift being fixed, caught live).
- Verified: dashboard / bim-kpi / cde / closeout / evm / operations / docmanager + cycle guard green.

## v0.3.419 — DOC-RACE: per-project locks on the sidecar indexes (P1 №7)

- **Bug fix** (upgrade-plan P1 №7): the document manager and the edit-history stack are
  read-modify-write cycles over a single JSON sidecar in object storage. FastAPI runs sync endpoints in
  a threadpool, so two concurrent uploads to the same project could interleave load→save — the second
  writer clobbered the first (its file's bytes orphaned in storage, invisible in the UI) and both could
  be allocated the same `f{seq}` id.
- New `pid_lock.mutating(pid)` serializes sidecar mutations per project; `docmanager.upload/move/delete`
  and `edit_history.push/undo/redo` now run under it (`@_locked`, zero body changes). Cross-worker
  serialization (`--workers >1`) is documented as the remaining shape needing storage CAS.
- Proven by a new concurrency test: **12 simultaneous uploads → 12 index entries, 12 unique ids**
  (pre-fix this loses entries); docmanager / edit-undo / cycle-guard suites green.

## v0.3.418 — WEB-LIVE + WEB-LEAKS: resilient live streams, no leaked listeners/geometry (P1 №5–6)

- **SSE resilience** (P1 №5): a new `liveStream` core behind `modelStream` / `notificationStream` /
  `pullPlanStream`. EventSource only auto-retries transient drops — a backend restart/deploy answered
  with an HTTP error killed the stream **permanently and silently** (stale notification badge, frozen
  pull-plan board, dead collab banner until a full reload). Streams now re-subscribe with bounded
  backoff (5s→60s) and surface status; the workspace tab dims its badge + explains "live notifications
  disconnected — reconnecting…"; the notification stream closes on `pagehide`.
- **Listener leak** (P1 №6): `nodeCanvas.makeDraggable` added two **permanent** window listeners per
  node (2×N handlers, all running on every pointer move, never removed). Listeners now attach only for
  the duration of a drag and detach on mouseup.
- **GPU leak** (P1 №6): a failed/errored draft publish orphaned the one-element preview Fragments model
  (unique id per attempt → repeated failures accumulated geometry). The preview is now disposed
  explicitly on every non-success outcome (`loader.disposeOne`).
- Verified: typecheck + eslint + full vitest (88) + production build green.

## v0.3.417 — SEC-MCP: membership authorization in the MCP tool dispatch (P0 №4 — P0 complete)

- **Security hardening** (upgrade-plan P0 №4, the last P0): `mcp_tools.dispatch` executed any tool
  against any caller-supplied `project_id` with no authorization — safe only as long as the MCP server
  stays local/stdio. Dispatch now resolves an effective identity (`user` arg → `AEC_MCP_USER` env → the
  historical admin api-key default) and, under RBAC, membership-scopes it: `list_projects` returns only
  member projects and any tool addressing a non-member `project_id` raises `PermissionError`
  (defense-in-depth if the server is ever bound beyond stdio; operators can pin a restricted identity
  via `AEC_MCP_USER`).
- `test_mcp_standards` extended: a no-membership identity sees an empty project list and is refused
  project tools; the api-key default stays unrestricted; existing dispatch/write-tool coverage green.

## v0.3.416 — SEC-GUARD: production safety guard beyond Postgres (P0 №3)

- **Security fix** (upgrade-plan P0 №3): `_production_guard` only enforced its boot checks (RBAC on,
  real `AEC_AUTH_SECRET`, no trusted X-User, non-default MinIO keys) when the database was Postgres. A
  real deployment on MySQL — or a small SQLite self-host — booted straight onto the public dev signing
  secret, making every auth token and signed download URL forgeable.
- The guard now triggers on **any non-SQLite DATABASE_URL or an explicit `AEC_ENV=production`** (so a
  SQLite self-host can opt into the same protection); dev/test SQLite is unchanged and
  `AEC_ALLOW_OPEN=1` remains the deliberate escape hatch.
- `test_prod_hardening` extended: Postgres AND MySQL both refuse without RBAC; `AEC_ENV=production` on
  SQLite refuses; the escape hatch and plain-SQLite dev still boot. api/security/localmode suites green.

## v0.3.415 — WEB-BOOT: a corrupted stored setting can no longer brick the app (P0 №2)

- **Bug fix** (upgrade-plan P0 №2): `main.ts` parsed `localStorage["aec-settings"]` at module top level
  with no guard — the single unwrapped `JSON.parse` in the app. Any invalid stored value (quota-truncated
  write, old-version value, extension tampering) threw during module evaluation → permanent blank screen
  until the user manually cleared storage. Now falls back to defaults.
- Also: the GeoJSON reference-file parse throws a friendly "not valid JSON" (was a raw SyntaxError
  bubbling from the drop handler), and the Responsibility panel's template loader gains its missing
  `.catch` (dropdown now says "Templates unavailable" instead of silently staying empty).
- Verified: typecheck + eslint + full vitest (88) + production build all green.

## v0.3.414 — SEC-TENANT: portfolio roll-ups scoped to the caller's projects (P0 №1)

- **Security fix** (upgrade-plan P0 №1): the cross-project roll-ups — `/benchmarks/costs`,
  `/benchmarks/response-rates`, `/benchmarks/pull-planning`, `/wip/portfolio`,
  `/contractor-statements/portfolio` — aggregated **every project in the database** while gating only on
  authentication. In a shared/multi-tenant deployment, any signed-in user could read every other tenant's
  job P&L, WIP cash positions and per-cost-code actuals. Each now takes the caller's
  `member_project_ids` (the `fca_portfolio` pattern) and the engines filter `project_id IN (…)`; RBAC-off
  dev and the admin api-key keep the unrestricted view.
- Also: the `/projects/{pid}/search` `limit` is clamped to 200 (was unbounded — an oversized SQL LIMIT
  fanned out per module), and `list_attachments` gains an explicit `project_id` predicate
  (defense-in-depth; the download route's membership check already guarded the bytes).
- **New `test_tenant_scoping.py`**: two tenants with distinct financial fingerprints under RBAC — each
  caller's portfolio/benchmarks contain ONLY their member project (admin sees both); limit clamp
  asserted. Wired into the gate; benchmarking / wip / portfolio / route-authz / pull-plan / attachments
  suites all green.

## v0.3.413 — docs & repo surface refresh + the 2026-07-17 upgrade plan

- Output of a four-lane audit (backend scan · web scan · docs/repo review · 2026 industry research):
  - **README** — the stale "current" marker (v0.3.341–371) replaced with a v0.3.372–412 summary
    (analytical chain incl. drift screen, MEP-SIZE/VIEW-RANGE/COVER-SHEET/EXPORT/TAKEOFF-2D, MODEL-DIFF /
    IFC-QA model-QA teeth, the dev-velocity program); clone-path case fix.
  - **Neutral wording** — third-party product comparisons removed from README/guide/index/status per the
    docs policy (drawing inference is now described by behavior).
  - **Status pages** — `docs/status.html` version badge is now the live release shield (was hard-coded
    v0.3.308/371); `docs/status.md` banner marks it a superseded point-in-time snapshot.
  - **Roadmap coherence** — intro updated to v0.3.412; the shipped v0.3.398–412 work archived into
    `roadmap-completed.md` (was stranded in the open file); "Current focus" rewritten now that the
    modularization program is complete.
  - **🎯 The upgrade plan** — a prioritized, research-cited plan added to `docs/roadmap.md`: P0 bugs &
    security (tenant-scoped portfolio rollups, settings-parse boot guard, production-guard breadth, MCP
    authz) → P1 reliability/perf (SSE resilience, listener/GPU leaks, sidecar-index race, UTC dates) →
    P2 docs/demo/surfacing → P3 2026 capabilities (Monte Carlo schedule risk, LEED v5/Buy Clean embodied
    carbon via EC3, permit pre-check, agentic drawing QA, robotic layout export, 5D element binding).
  - **Repo hygiene** — issue templates (bug/feature + Discussions/security links), a PR template
    mirroring the CONTRIBUTING gates, and a root `package.json` description that reflects the whole
    platform (authoring + docs + GC portal + proforma), not just a viewer.

## v0.3.412 — REL-3: split the enclosure recipes out of edit.py (façade) — edit.py under 800

- Fifth and final recipe-group split: the **enclosure/finish group** moves to a new leaf
  **`edit_enclosure.py`** — ceiling/floor coverings (`add_covering`), railings along a run
  (`add_railing`), footprint roofs (`add_roof`), and the wall-hosted opening + parametric door/window
  fill (`add_opening`: IfcRelVoidsElement + IfcRelFillsElement with the LOD-350 lining/panel generators).
- **`edit.py` 2127 → 761 across the six slices (−64%)** — what remains is the genuine engine core:
  spaces/types/query, placement, content, storeys, copy/move/rotate/delete, and the RECIPES registry +
  `apply_recipe`. Each recipe family (structural, MEP, enclosure, annotation, as-built) is now an
  independently evolvable leaf on the `edit_core` foundation, all behind the unchanged `edit.` façade.
- Verified: openings / curtain-wall / wave11-edges / representations suites + the cycle guard (**0
  cycles**, 336 modules), `ruff` clean.

## v0.3.411 — REL-3: split the 2D annotation recipes out of edit.py (façade)

- Fourth recipe-group split: the **drawing-annotation group** moves to a new leaf **`edit_annotate.py`**
  — text notes (`add_annotation`), dimension lines with computed labels (`add_dimension`), scalloped
  revision clouds with rev tags (`add_revision_cloud`), and element-aware tags (`add_tag`) — all authored
  as IfcAnnotation in the 2D Annotation subcontext so they render on the generated plans.
- Built on `edit_core` (annotation context / element-mark / storey lookup); `edit.py` re-exports every
  name. **`edit.py` 2127 → 911 across the five slices** — under 1000 lines for the first time; what
  remains is the engine core (spaces/types/query, placement, openings/coverings, RECIPES + apply_recipe).
- Verified: annotation + drawing suites (author-to-sheet loop intact), cycle guard **0 cycles** (335
  modules), `ruff` clean.

## v0.3.410 — REL-3: split the structural authoring recipes out of edit.py (façade)

- Third recipe-group split on the `edit_core` foundation: the **structural/enclosure group** moves to a
  new leaf **`edit_struct.py`** — sloped walls (`set_wall_slope`), extruded walls/slabs (`add_wall` /
  `add_slab`), concrete columns/beams, steel W-shapes (`add_steel_column` / `add_steel_beam` +
  `_tag_section`, via the `steel` catalog imported lazily), rebar runs and spread footings.
- Built entirely on `edit_core` primitives; `edit.py` re-exports every name (routers, RECIPES, tests,
  generators unchanged). **`edit.py` 2127 → 1103 across the four slices** — the worst file in the tree cut
  nearly in half, with each recipe group now an independently evolvable leaf.
- Verified across 9 suites (structural / wall-slope / steel-connections / rebar / struct-solve /
  wall-analytical / lateral / grid + the cycle guard: **0 cycles**, 334 modules), `ruff` clean.

## v0.3.409 — REL-3: split the MEP authoring recipes out of edit.py (façade)

- Second recipe-group split on the `edit_core` foundation — and the biggest: the **MEP group** (416
  lines) moves to a new leaf **`edit_mep.py`** — system assignment + predefined types
  (`set_system_predefined`), sized risers/runs (`add_riser` / `add_mep_run`), fittings with port counts
  (`add_mep_fitting`), terminals, fire / fire-alarm / comms devices, and the element-connection graph
  (`connect_mep` / `connect_elements` / `element_connections`).
- Built entirely on the `edit_core` primitives (contexts / profiles / storey lookup) — never on another
  recipe; all vendor-util imports were already function-local. `edit.py` re-exports every name (routers,
  RECIPES, nodegraph unchanged). **`edit.py` 2127 → 1378 across the three slices** (core → as-built → MEP).
- Verified across 7 suites (mep / mep-systems / mep-sizing / mep-families / element-connections /
  nodegraph + the cycle guard: **0 cycles**, 333 modules), `ruff` clean.

## v0.3.408 — REL-3: split the as-built / phase record writers out of edit.py (façade)

- First recipe-group split enabled by the `edit_core` foundation (v0.3.406). The element **record**
  writers — W10-8 phasing (`set_phase` / `phase_summary`), G1 field-verified as-built (`verify_asbuilt` /
  `asbuilt_summary`), G2 as-built dimensions (`record_asbuilt_dimension`), G3 manufacturer/serial
  (`set_manufacturer_info`), plus `set_element_pset` / `set_classification` / `_coerce` — move to a new
  leaf **`edit_asbuilt.py`**: no geometry, no placement, just GUID-keyed Pset/classification stamps (the
  LOD-500 reliability layer). Depends only on `edit_core._element` + ifcopenshell.api.
- `edit.py` re-exports every name, so the importers that reach these via `edit` (scene, ebc, detailing,
  the RECIPES registry) are unchanged. `edit.py` 2005 → 1781 (from the original 2127).
- Verified across 8 suites (phasing / lod500 / detailing / content / scene / ebc / verified-progress +
  the cycle guard: **0 cycles**, 332 modules), `ruff` clean.

## v0.3.407 — REL-3: split the raw vendor HTTP clients out of connectors.py (façade)

- Completes the `connectors.py` decomposition. The **outbound I/O half** — the raw Procore / Autodesk
  Construction Cloud / QuickBooks Online / generic-ERP REST clients (urllib GET/PATCH, token in → parsed
  JSON out) — moves to a new pure leaf **`connectors_vendors.py`** (json + urllib only; no DB, no app
  imports, no dispatch logic).
- The **overridable test seams** (`procore_rfis = …`, `acc_projects = …`, `qb_accounts = …`, `erp_read =
  …`) deliberately **stay on `connectors.py`** — tests monkeypatch them there
  (`connectors.acc_projects = fake`) and the per-vendor test/info dispatchers resolve them there, so the
  patchability contract is byte-for-byte unchanged. `connectors.py` 411 → 325 (from the original 495).
- Verified: `test_connections` green end-to-end (Procore two-way sync, ACC/QuickBooks/ERP reads — all
  through the monkeypatched seams), import-cycle guard **0 cycles** (331 modules), `ruff` clean.

## v0.3.406 — REL-3: extract the edit.py authoring primitives into a foundation leaf

- Foundation-first slice on the biggest file in the tree — `data/edit.py` (2127 lines), the GUID-stable IFC
  authoring engine. The nine low-level primitives every recipe builds on — context/profile/mesh/lookup
  helpers (`_body_context`, `_rect_profile`, `_first_storey`, `_box_mesh`, `_annotation_context`,
  `_element_mark`, `_wall_thickness`, `_fill_representation`, `_element`) — move to a new pure leaf
  **`edit_core.py`** that depends only on ifcopenshell, never on a recipe.
- `edit.py` re-exports every name, so the sibling authoring modules that already reach in for these
  (`connections`, `curtainwall`, `families` do `from .edit import _body_context …`) are unchanged.
  `edit.py` 2127 → 2005. The leaf imports nothing back, so no cycle (guard confirms 0 across 330 modules).
- This unblocks splitting the recipe *groups* (MEP, structural, as-built) off later — they can import the
  primitives from `edit_core` instead of dragging in the whole engine. Verified across 10 authoring tests
  (annotation / openings / mesh / content / curtain-wall / family-library / connections / detailing /
  edit-undo), `ruff` clean.

## v0.3.405 — REL-3: split the sheet renderers out of data/drawings.py (façade)

- Next façade extraction. The **paper-output half** of `data/drawings.py` — `render_sheet_svg` /
  `render_sheet_pdf` (turn a composed `layout` dict into an SVG string / PDF byte-stream) plus the shared
  `_dim_h` / `_dim_v` dimension primitives — moves to a new pure leaf **`drawings_render.py`** that imports
  no ifcopenshell / geometry / model code (just `layout`/`meta` dicts + reportlab in the PDF path).
- `drawings.py` re-imports all four (used internally: the renderers in `sheet()`, the dim primitives in the
  plan generator), so `drawings.render_sheet_svg` / `render_sheet_pdf` callers are unchanged. `drawings.py`
  941 → 788. The leaf imports nothing back from `drawings.py`, so no cycle.
- Verified: `test_sheetgen` / `test_pdfops` / `test_issuance` / `test_drawing` / `test_sections` green
  (sheets render through the façade), the import-cycle guard confirms **0 new cycles** (329 modules), `ruff`
  clean.

## v0.3.404 — REL-3: split the pure Procore field-mapping out of connectors.py (façade)

- First façade extraction since the cycle guards landed (which now catch any regression). The **pure
  data-transform half** of `connectors.py` — the dotted-path reader, default/override field maps, and the
  Procore payload↔record mappers — moves to a new pure leaf **`connectors_mappings.py`** (no network, no
  DB, no app imports). `connectors.py` re-exports every name, so callers of `connectors.map_procore` /
  `connectors.DEFAULT_MAPPINGS` are unchanged (zero public-API change). `connectors.py` 495 → 411.
- Verified: `test_connections` green (Procore→rfi/submittal/change_event sync through the façade), the
  import-cycle guard confirms **no new cycle** (328 modules, still 0), `ruff` clean.

## v0.3.403 — DEV-2 (web): runtime import-cycle guard for the viewer/portal

- Completes the DEV-2 import-cycle guard on the **web** side, mirroring the backend one — as a vitest test
  (`src/no-import-cycles.test.ts`), so it runs in the existing web CI job with **no new dependency** (no
  eslint-plugin-import, avoiding the pinned-eslint/Node-20 fragility).
- Asserts **no *runtime* circular imports** among the app's own modules via Tarjan SCC over the top-level
  import graph. `import type` / `export type` are excluded because tsc erases them — the portal's only
  "cycle" is exactly that PanelContext ⇄ PortalHost *type* seam, which emits no runtime import. Today:
  **0 runtime cycles across 92 modules / 162 runtime edges**; a genuine load-time cycle now fails the build
  with the exact path. Includes a self-test asserting the SCC detector catches a synthetic cycle.

## v0.3.402 — DEV-2: import-cycle guard (lock in the REL-3 façade layering)

- The REL-3 modularization repeatedly stalled on *false-positive* circular-import reports (imports that are
  actually function-local / deferred). New **`test_import_cycles.py`** locks in the real invariant: **no
  circular imports at module top level** across the first-party packages (`aec_api` + `aec_data`) —
  the kind that breaks at import time and blocks a clean façade extraction.
- Pure stdlib `ast` (no third-party linter added), runs inside the fast parallel gate. Builds the
  top-level import graph over all 327 first-party modules and fails loudly on any strongly-connected
  component (Tarjan SCC) — function-local/deferred imports are correctly ignored since they don't cycle at
  import time. Today: **0 cycles across 704 intra-package edges**; a regression now fails CI with the exact
  cycle path.

## v0.3.401 — IFC-QA: export round-trip fidelity check (does the export drop anything?)

- The #1 openBIM complaint is **silent loss on export** — entities dropped, GlobalIds churned, property
  sets lost when a model is serialized or pushed through a bridge. New `roundtrip_qa` engine catches it:
  - **`fingerprint(model)`** — a comparable summary of the invariants that must survive an exchange: IFC
    schema, project units, entity counts by class, the full GlobalId set, storey list, and the element
    property/quantity payload size.
  - **`compare(before, after)`** — diffs two opened models and returns two verdicts: **`identical`** (exact
    match — the target for a plain re-serialization) and **`lossless`** (nothing *dropped*: after ⊇ before,
    the bar a legitimate transform must clear), with per-dimension deltas and offender GUID samples.
  - **`roundtrip(model)`** — writes the model out to a temp IFC and reopens it, then compares — a pure
    serialization-fidelity check of the write path the edit recipes use to republish.
  - Exposed at `GET /projects/{pid}/models/export-qa` (409 without a source IFC). Pure + guarded; a
    write/reopen failure is itself reported as a fidelity failure rather than a 500.
- Test coverage: clean write→reopen is `identical`; a dropped wall is caught as EXPORT LOSS (GUID removed
  + IfcWall delta −1); a superset target reads lossless-but-not-identical.

## v0.3.400 — DRIFT: preliminary story-drift screen + torsional-irregularity flag (ASCE 7 §12.12 / §12.3.2.1)

- The lateral engine computed seismic ELF + wind base shear distributed to story forces, but had **no
  drift or torsion check** — the two limit states that most often govern a lateral system. Added, as an
  honest preliminary screen on top of the existing ELF story shears:
  - **`drift_check`** — the ASCE 7-22 §12.12.1 **allowable story drift** `Δa = coeff·hsx` per story (Table
    12.12-1, by Risk Category: 0.020 / 0.015 / 0.010 for I–II / III / IV). When a **story stiffness**
    (kip/in) or a **target elastic drift ratio** is supplied, it also computes the amplified **design
    drift** `Δ = Cd·δxe / Ie` (§12.8.6) and returns pass/fail per story plus the worst drift ratio.
  - **`torsional_check`** — the §12.3.2.1 horizontal-irregularity classifier from the two-end diaphragm
    displacements: `δmax/δavg` → **Type 1a** (> 1.2) / **Type 1b extreme** (> 1.4), with the §12.8.4.3
    accidental-torsion amplification `Ax = (δmax / 1.2·δavg)²` (capped at 3.0).
  - Wired into `lateral_from_model` (the Δa envelope is always emitted; demand + torsion when inputs are
    given) and the `GET …/structure/lateral` endpoint (`risk_category`, `cd`, `elastic_drift_ratio`).
- Still preliminary — real drift needs a member-stiffness model; every result carries the not-a-PE
  disclaimer. Hand-computed test coverage in `test_lateral.py`.

## v0.3.399 — FIN-TEST: lock in the untested lease + change-order money math

- Quality / debug pass from the codebase gap sweep. Two read-side money-computation engines had **no
  dedicated test** asserting their math — where a silent compounding/rounding/recovery bug is consequential.
  Now covered with hand-computed expectations:
  - **`test_leasemgmt.py`** — rent **escalation compounding** (`base·(1+esc)^y`, verified to 5-year), the
    portfolio-by-year sum (active-only), **CAM/expense recovery** (`psf×sf`, recovery ratio, over/under-
    recovery vs the opex pool, zero-pool guard), and **renewal at-risk rent** (expiry bucketing, holdover);
    plus empty/malformed-input robustness.
  - **`test_changeorders.py`** — the CO value pipeline by state (pending / approved / executed / rejected),
    **schedule-day exposure excluding rejected**, ball-in-court mapping, reason mix, and open-only
    change-event ROM exposure.
- The math was **already correct** — no product change; this is regression protection for the developer-
  finance surface. Both wired into the test gate.

## v0.3.398 — MODEL-DIFF: element-level revision diff (what actually changed)

- New capability from a codebase gap sweep. Model version diff previously compared only the GUID **set**
  (added / removed); a moved, resized, re-typed, re-leveled, or re-priced element on a GUID present in both
  revisions read as *"unchanged."* Now each version snapshot stores a per-element **fingerprint** (name ·
  IFC class · type · level · Pset-hash · Qto-hash), so `versions.diff` reports **modified** elements *and
  what changed* — `renamed` · `reclassified` · `retyped` · `moved to another level` · `properties changed`
  · `quantities changed`. The "what changed between Rev C and Rev D" coordination answer, made real by the
  GUID-stable model.
- `GET …/versions/diff` gains `modified[]` (guid · class · name · change labels), `modified_count`, and
  `modified_available` (older versions without fingerprints degrade to added/removed only). The viewer's
  **Version history** shows `+added / −removed / ~modified` and a click-to-select-in-3D list of the modified
  elements with their change labels. `ModelVersion.fingerprints` auto-migrates via `_ensure_columns`.
- Scope: pure rigid geometry *moves* aren't caught (geometry streams as Fragments, not the property index) —
  but a **resize surfaces via its Qto delta**, and all property/type/level/name/cost changes are detected.

## v0.3.397 — REL-3: extract the module registry foundation (modules_registry.py)

- Fourth modularization slice — the **foundation** extraction that unblocks all further `modules.py` splits.
  The registry + table base (the `module.json` REGISTRY, the per-module SQLAlchemy TABLES, the reverse-
  reference index, the field-type selectors, and the `_table` factory / `load_registry` / `get_module`)
  moves to **`modules_registry.py`** — a leaf that imports only `db.Base` + stdlib/sqlalchemy, nothing from
  `modules.py`. Now `modules.py`, `modules_search.py`, and any future `modules_*` layer can share the base
  without a cycle. The mutable globals are mutated in place (never reassigned), so every importer shares the
  one dict object; `modules.py` re-exports the names so `modules.get_module` / `.TABLES` / `.load_registry`
  are unchanged. `modules.py` 969→882.
- Zero behaviour change. Verified: module/schema/config/FTS/traceability/dashboard/imports tests green + the
  **full suite** (this is the app-wide-core engine), ruff clean, all consumers import.

## v0.3.396 — REL-3: extract computed schedules into a pure leaf (drawing_schedules.py)

- Third modularization slice. `data/drawing.py` (941 lines — footprint plans / sheets / PDF / schedules)
  had the **computed door/window/room schedules** (`schedules` / `schedule_csv` / `schedule_svg`) inline.
  They move to **`drawing_schedules.py`** as a **pure leaf** — they read values straight off the model
  elements with no dependency on the plan/section geometry helpers, so it imports nothing from `drawing.py`
  (no cycle). `drawing.py` imports `schedules` for its PDF path and re-exports the three public functions,
  so `drawing.schedules` / `.schedule_csv` / `.schedule_svg` are unchanged. `drawing.py` 941→821.
- Zero behaviour change. Verified: drawing / sections / sheetgen / drawing-set / project-package tests green,
  ruff clean, all consumers import.

## v0.3.395 — REL-3: extract module full-text search into a pure leaf (modules_search.py)

- Second modularization slice, on the biggest backend file. `modules.py` (1009 lines, the config-module
  engine) had its Postgres full-text-search infrastructure (`_is_postgres` / `_pg_tsquery` / `_pg_document` /
  the `LIKE`↔`to_tsvector` search predicate / the GIN-index DDL) inline. It moves to **`modules_search.py`**
  as a **pure leaf** — every function takes the SQLAlchemy `Table` as an argument (dependency injection), so
  it imports nothing from `modules.py` (no cycle). `modules.py` keeps the `fts_index_ddl(key)` /
  `ensure_fts_indexes(engine)` orchestration (which knows the `TABLES` registry) as thin injecting wrappers,
  and re-exports the query helpers so `modules._pg_document` / `modules._pg_tsquery` keep working.
- Zero behaviour change (search + index DDL identical). Verified: search/module tests green
  (fts-index / search-alerts / modules / module-schema / module-config / imports / distribution), full suite
  green, ruff clean, all consumers import. Also made `test_distribution` parallel-safe (stale-lock-tolerant).

## v0.3.394 — REL-3: modularize codecheck (egress engine → its own module, façade)

- First modularization slice. `codecheck.py` (502 lines) mixed two fully-decoupled domains — the free-text
  code-check assistant and the **computed occupancy-load + egress-capacity analysis** (W9-2). The egress
  half (~330 lines) moves to **`codecheck_egress.py`**; `codecheck.py` (now 184 lines) **re-exports** its
  public functions (`egress_analysis`/`code_analysis`/`approvability`/`egress_from_model`) as a façade, so
  every caller (`codecheck.approvability`, …) is **unchanged**. Zero behaviour change — pure structure.
- Verified: all codecheck-dependent tests green (codecheck / code_analysis / codes / approvability /
  rfi-readiness / readiness-bcf / ebc / model-health), ruff clean, all consumers import.

## v0.3.393 — DEV-1: parallel test gate (~30 min → ~11 min) + geometry worker cap

- **Dev-velocity, not a product change.** The API test gate (`run_tests.py`) ran ~180 self-contained
  `test_*.py` **sequentially** (~30 min) — the release bottleneck. It now runs them through a bounded
  `ThreadPoolExecutor` (each test is already an isolated subprocess with its own SQLite db + storage dir).
  `TEST_JOBS` overrides the worker count; `TEST_JOBS=1` restores sequential for debugging.
- **Geometry worker cap** — each geometry pass (`bake`/clash/export/edit) ran ifcopenshell's iterator across
  `cpu_count()-1` processes; under the parallel gate that oversubscribed the CPU (cpu × cpu). A new
  `aec_data.geomconf.geom_workers()` reads **`AEC_GEOM_WORKERS`** (the runner sets `=1`) so each test is
  single-threaded and the outer parallelism owns the cores. **Production default is unchanged** (`cpu-1`).
- Net: the full suite drops from **~30 min to ~11 min (2.7×)**, 250/250 green. Also fixed the runner's
  cp1252 output-capture (now `PYTHONUTF8=1` + utf-8 decode — no more spurious unicode-encode failures) and
  made `test_collab` tolerant of a stale locked db so the parallel run is deterministic.

## v0.3.392 — Analytical supports: fix the base nodes → a solvable model

- Completes the analytical model: the **`apply_structural_supports`** recipe fixes the **base**
  (lowest-elevation) analytical nodes as `IfcBoundaryNodeCondition` supports — **pinned** (translations
  fixed, rotations free) or **fixed** (all six DOF) — so the model is **statically stable and fully
  solvable** (members + loads + supports = a complete analytical model a solver can run).
- Idempotent (re-applying doesn't accumulate conditions), cleared by a re-derive, reported by `summary()`
  as `supports`. The viewer analytical panel gains an **"Add base supports (pinned)"** action and shows the
  support count; the analytical model reads **"solver-ready"** once it has both member loads and supports.

## v0.3.391 — Analytical shear walls: load-bearing walls → vertical surface members

- Completes the W10-7 analytical geometry. `derive_analytical` now idealises each **load-bearing (shear)
  wall** into a vertical `IfcStructuralSurfaceMember` at its mid-plane (a length×height `IfcFaceSurface`
  spanning the wall height), alongside the existing slab surface members. Non-bearing **partitions are
  skipped** (read from `Pset_WallCommon.LoadBearing`), so the analytical model carries the real lateral-
  force-resisting elements, not every wall.
- Idempotent (the `wall_surface_members` count is stable across a re-derive) and cleaned by the analytical
  purge; the derive result + `summary()` report the counts. Pure ifcopenshell topology — no geometry kernel.

## v0.3.390 — STRUCT-LOADS-IFC: write member load actions → a solver-ready analytical model

- The analytical model carried only a self-weight load *case*. The new **`apply_structural_loads`** recipe
  writes a real gravity line load onto **every analytical curve member** as an `IfcStructuralLinearAction`
  (applied `IfcStructuralLoadLinearForce`, global −Z at `(D+L) × 14593.9 N/m`), grouped under the analysis
  model's load group — so the analytical IFC is now **loaded and solver-ready**: SAP2000 / RISA / Robot
  import the actions with the geometry, not just bare members.
- Idempotent (re-applying refreshes the value; counts never accumulate) and cleaned by a re-derive (the
  analytical purge now removes load actions + applied loads with no orphans). `summary()` reports
  `load_actions`; the viewer analytical panel shows the solver-ready count + a **"Write member loads"**
  action. **Preliminary — service D+L only; final loads/combos are the engineer's.**

## v0.3.389 — STRUCT-LATERAL: ASCE 7 wind + seismic base shear → story forces

- The lateral complement to the gravity solve. **`GET /projects/{pid}/structure/lateral`** runs the two
  hand analyses an engineer does before sizing a lateral system:
  - **Seismic — Equivalent Lateral Force (ASCE 7-22 §12.8):** `Cs = SDS/(R/Ie)` with the §12.8-3 upper
    bound + §12.8-5 floor, base shear `V = Cs·W`, vertical distribution `Fx = Cvx·V` (k from the
    approximate period `Ta = Ct·hn^x`), story shears + overturning.
  - **Wind — simplified directional MWFRS (Ch. 26–27):** velocity pressure `qz = 0.00256·Kz·Kzt·Kd·Ke·V²`
    (Kz by the exposure power law), net windward+leeward pressure → story forces, base shear + overturning.
  - The **governing** case is flagged; story weights estimated from floor area × a dead-load psf.
- **Viewer** — the Structural analytical panel gains a **"Lateral (wind + seismic base shear)"** action:
  governing case, both base shears, and the per-story force/shear table.
- Pure ASCE 7 arithmetic (hand-verified in tests). **Preliminary — not a full lateral design (no torsion,
  modal/response-spectrum, drift, or P-delta); must be stamped by a licensed professional engineer.**

## v0.3.388 — TAKEOFF-2D: quantity takeoff from a drawing → the 5D estimate

- The **drawings-only takeoff** the model takeoff misses. Upload a PDF-page image / scan, **calibrate the
  scale** (click two points at a known real distance), then trace regions — click polygon vertices or
  **one-click flood-fill** inside an enclosed area — and each region is measured + priced by assembly.
- **`POST /projects/{pid}/takeoff/2d`** — the deterministic measurement + pricing core: shoelace area /
  polyline length in pixels × the calibration → real m² / m, priced at per-assembly benchmark rates
  (floor slab · roofing · partitions · curtain wall · paving · linear walls/footings …), overridable per
  project vintage; returns per-region rows + per-assembly rollups + total, feeding the same 5D estimate.
- Viewer: a **📐 2D Takeoff** overlay (upload · calibrate · trace/flood-fill · quantify) in the turnover
  group. Preliminary — accuracy is trace/scale dependent; verify against the model takeoff where a model
  exists. (The measurement/pricing core is unit-tested; the canvas tracer is build-verified.)

## v0.3.387 — EXPORT: binary glTF (.glb) + first-class IFC re-export

- **`GET …/model/export.glb`** — the model geometry now exports as a **binary glTF (.glb)** — the compact
  single-file form Blender / three.js / game engines import directly — alongside the existing JSON `.gltf`.
  Same per-class meshes + colours; proper glTF-2.0 container (`glTF`/v2 header · 4-byte-padded JSON chunk ·
  `BIN` chunk). Tessellation runs off the event loop.
- **`GET …/model/export.ifc`** — a **first-class IFC re-export**: stream the project's current authored
  source IFC (edits republish it in place, so this is the live GUID-stable model) directly, not only inside
  the closeout bundle zip — the openBIM source of truth a coordinator can round-trip through any tool.
- **Viewer** — the Document/turnover group gains **Export IFC**, **Export 3D (.glb)**, and **Export 3D
  (.gltf)** actions beside the closeout package. (DWG + USD remain deferred — proprietary/heavy-dependency;
  the on-mission interchange path is IFC + glTF.)

## v0.3.386 — MEP-SIZE: velocity size checks elevate MEP from modeled to engineered

- **`GET /projects/{pid}/mep/sizing`** — over every authored MEP run carrying a design size + flow
  (`Pset_Massing_MEPSizing`), computes the **flow velocity** and checks it against accepted limits, pass/
  fail like the IBC checks: **air** `V = Q/A` vs the ASHRAE low-velocity commercial limit (~2500 fpm),
  **water** `V = 0.408·Q/d²` vs the erosion/noise limit (~8 ft/s), and **cable-tray** NEC 392 fill (≤ 50%,
  reported when a fill ratio is supplied). Undersized/over-driven runs are flagged with the fix ("increase
  the duct/pipe"); runs with no design flow return info. Limits are overridable per call.
- **Viewer** — the MEP system browser gains a **"MEP size check (velocity)"** action: pass/fail counts, a
  per-run table, an "isolate undersized runs in 3D" control, and the not-a-PE disclaimer.
- Physics only (velocity relations + limit values are facts — no license issue). **Preliminary — not a
  full hydraulic/thermal design (no pressure-loss balancing, diversity, or acoustics); all final MEP sizing
  must be stamped by a licensed professional engineer.**

## v0.3.385 — DISC-SSOT: sheet-series derives from the one discipline map

- Internal consolidation. Sheet-series (which drawing series a class belongs to — S/A/M/E/P/FP/FA/T…) was
  hand-maintained in **two** places (`sheetgen._CLASS_SERIES`, plus the cover's own series→name table)
  that could silently drift from the canonical discipline map. Series is now a **derived view** of the
  discipline map: `classification.series_of_ifc_class()` refines `discipline_of_ifc_class` only where a
  *distinct* series exists (fire-suppression → FP, fire-alarm → FA), and `sheetgen.detect_series` + the
  drawing-set cover both derive from it. Verified to reproduce the former hand-kept map **exactly** — no
  behaviour change, one source of truth.
- **Takt trade** (`fourd.TRADE_FOR_CLASS`) is documented as a deliberately separate build-sequence axis
  (a wall's trade is *Envelope*, its discipline *Architectural*), not folded into discipline/series.

## v0.3.384 — COVER-SHEET: rendered cover + discipline-grouped drawing index

- The compiled drawing set's cover was a flat text list. It is now a proper **cover sheet**: a title block
  with the project name, subtitle, **issue date**, and sheet count; a **key-plan thumbnail rendered from
  the model** (the ground-plan footprint, real linework — not text); and a **drawing index grouped by NCS
  discipline** (General · Civil · Structural · Architectural · Fire Protection · Fire Alarm · Plumbing ·
  Mechanical · Electrical · Telecom …) with section headers, bound in the same order a set is issued.
- The index **paginates** — a large multi-discipline set flows onto continuation pages instead of
  truncating at the page bottom (the old cover silently dropped sheets past the first ~90). Backward-
  compatible: short sets still produce a single cover page, so `/drawing-set/compiled.pdf`,
  `/project-package.pdf`, and the issuance flow are unchanged in page count for typical models.

## v0.3.383 — VIEW-RANGE: plan view-depth so foundations show below the cut

- **`GET /projects/{pid}/drawings/plan.svg?view_depth=<m>`** — a plan is no longer a single horizontal
  cut plane. Pass a **view depth** (metres below the cut) and the plan additionally draws the **footprint
  of anything under the cut but within that depth** — foundations / footings / pile caps that a single
  cut plane never intersects — as **dashed light hidden lines**, with a "below cut (view depth)" legend.
  This is the Revit **Top / Cut / Bottom / View-Depth** model rather than one `cut_z`.
- Each below-cut element is sectioned through its own mid-height for a representative outline; the below
  linework shares the plan extent (so it is never clipped) and the class filter scopes it. The cut
  linework, dimensions, room tags, callouts, and titleblock cut-AFF are unchanged when `view_depth` is
  omitted — fully backward-compatible.

## v0.3.382 — STRUCT-SOLVE: apply gravity loads + solve statics on the analytical frame

- **`GET /projects/{pid}/structure/solve`** — closes the biggest analysis gap: the W10-7 analytical model
  carried only self-weight and the ASCE 7 load engine sat isolated. This **applies a gravity load case**
  (dead + live by occupancy) to the analytical curve members and runs a **determinate, member-by-member
  statics solve** — each horizontal member as a simply-supported beam under a uniform line load:
  end **reactions** (`wL/2`), max **shear** (`wL/2`), max **moment** (`wL²/8`), an indicative
  **deflection** vs the L/360 limit, and sampled **shear / moment / deflection diagrams**; vertical
  members carry a tributary **column axial** (from the gravity takedown). Factored member forces use the
  governing ASCE 7 LRFD combination. The beam line load is taken directly (kip/ft) or derived from floor
  pressures over a tributary strip; occupancy live loads come from the ASCE 7 table.
- **Viewer** — the Structural analytical panel gains an **"Apply loads + solve statics"** action: the
  load case, the governing beam (reaction · Vmax · Mmax · deflection check), inline shear + moment
  diagrams, and the column axial, each with the not-a-PE disclaimer.
- **Honest scope:** every member is solved in isolation as a determinate element (the hand-check before
  sizing) — **not** a coupled stiffness (FEM) frame analysis, no lateral (wind/seismic) member solve,
  deflection indicative (assumed E·I). Read-only; nothing is written back to the IFC. Preliminary only —
  all sizing and final design must be performed and stamped by a licensed professional engineer.

## v0.3.381 — PREFLIGHT: one-click "ready to issue?" gate

- **`GET /projects/{pid}/preflight`** — a single **PASS / HOLD** verdict + a pre-issue checklist, the
  pyRevit "run the pre-flight before you publish" moment. Composes the shipped model-health lenses
  (hygiene · clash coordination · code/permit readiness · verified-as-built), adds the one missing lens —
  **discipline-classification completeness** (elements that don't map to the tree can't be scheduled /
  priced / drawn by discipline) — and folds in **open high-priority issues** as a hard blocker. Checklist
  is ordered blockers → warnings → passes; each item carries a status, detail, and (where relevant) the
  offending GUIDs. Reuses the existing engines — no duplicate logic.

## v0.3.380 — KEYS: Revit-style keyboard shortcuts for drawing

- Type a **2-letter code** (no modifier) in the viewer to arm a draw tool, Revit-style, then click to
  place — **WA** wall · **CL** column · **BM** beam · **SL** slab · **RF** roof · **RA** railing · **SC**
  steel column · **SB** steel beam · **RB** rebar · **FT** footing · **DU** duct · **PI** pipe · **CT**
  cable tray · **WR** wire. **Esc** disarms; **?** shows the shortcut list. A small HUD echoes the code as
  you type. Shortcuts are suppressed while typing in any input/textarea, so text fields are unaffected.
  Makes Revit-trained users productive without hunting the tool rail.

## v0.3.379 — fix 3 CodeQL ReDoS alerts (codecheck free-text parser)

- Cleared the 3 open **`py/polynomial-redos` (HIGH)** CodeQL alerts in `codecheck._detect` — the free-text
  code-description scanner used unbounded quantifiers (`[\d,]+`, `\d+`, `\s*`) under `re.search`, which
  re-scans and is polynomial-time on a crafted long string. Bounded the quantifiers (`{1,n}`) and capped
  the input to 20 000 chars; a 100 k-digit crafted input now parses in ~40 ms (was the ReDoS vector).
  Detection of area / stories / occupant-load on real inputs is unchanged.

## v0.3.377 — shareable project package (show someone the whole project)

- **`GET /projects/{pid}/project-package.pdf`** — one bound PDF a GC or architect hands to a client: a
  **cover / contents**, a **visual overview** (plan · section · elevation composed on one sheet), the
  **compiled drawing set**, and a **cost & feasibility** summary (the model-takeoff estimate by discipline
  + the developer budget's capital stack — hard / soft / debt / equity). `…/project-package/contents`
  pre-flights what's available. Composes the existing drawing, estimate, and proforma engines — the
  "show someone the design, drawings, cost, and proforma" deliverable that had no single home before.

## v0.3.376 — model estimate → developer proforma (5D→underwriting)

- **`POST /projects/{pid}/dev-budget/sync-from-model`** ties the developer underwriting to the **real
  model takeoff** instead of a flat `GFA × $/sf` assumption. One click runs the IFC quantity estimate
  (priced through the project's pinned cost vintage) and replaces the budget's **hard** cost with
  **per-discipline** "model takeoff" lines (S/A/M/E/P/…) that reconcile to the estimate total; soft /
  acquisition / contingency are untouched. Closes the ★5 gap where the proforma and the model quantities
  were two disconnected worlds — the deal number now flows from the design.

## v0.3.375 — compiled drawing-set PDF (the whole set, one file)

- **`GET /projects/{pid}/drawing-set/compiled.pdf`** — the whole drawing set bound into **one multi-page
  PDF**: a cover / sheet-index, a floor plan per storey (A-1xx), and the door/window/room schedules
  (A-601). Reuses the proven single-sheet renderers and merges with pypdf. A tall tower samples storeys
  evenly (capped by `max_sheets`) so the set stays a reasonable size; schedules toggle off. The single-file
  handover deliverable a GC or architect issues — closes the gap where the platform could render one sheet
  at a time and a transmittal *cover*, but never the bound set. (Verified on the 30-storey Quay tower.)

## v0.3.373 — reliability: openModule O(n·m) fix + import-cycle verification

- **Perf (REL-4):** the portal's `openModule` built its visible columns with a per-column
  `m.fields.find(...)` linear scan — O(colNames × fields). Now an O(1) `Map` lookup built once per open.
- **Import cycles (REL-1/2) verified false positives** — the flagged web-portal cycle
  (`panelContext ↔ portal`) is entirely `import type` (stripped at build, no runtime cycle), and the API
  `db.py` cycle isn't real (`db.py` has no back-edge; `models.py→db.py` is one-way; `distribution.py→
  modules.py` is a deferred function-local import). Documented in the roadmap; no refactor needed.

## v0.3.371 — security hardening pass (audit + fixes)

- **XXE fix (HIGH):** the Primavera P6 XML (PMXML) schedule-import parser now uses **defusedxml**, so a
  malicious upload can't trigger XML external-entity / entity-expansion attacks (verified: a `file://`
  XXE payload is rejected, valid P6 XML still parses).
- **Weak-hash flags cleared (HIGH×3):** the SHA-1 calls in `clash_intel` (clash identity) and
  `model_capabilities` (model signature) are non-crypto fingerprints — marked `usedforsecurity=False`.
- **Dependency CVEs:** pinned `pillow>=12.3.0` (reportlab's transitive image dep — floors over 8 CVEs in
  12.2.x) and added `defusedxml>=0.7` to the data requirements.
- Audit run across ecosystems: `npm audit` 0 vulns (web), `bandit` HIGH findings now **0**, `pip-audit`
  reviewed (remaining setuptools advisories are build-time only), secret scan of the source tree clean.
  Outbound `urlopen` sites are fixed/configured hosts (Procore) or scheme-validated admin webhooks.

## v0.3.370 — UX-1: lifecycle ribbon tabs over the tool rail

- A **ribbon tab-strip** (All · Build · Analyze · Coordinate · Document · Data) at the top of the model
  tool rail filters the accreted tool sections to one lifecycle phase at a time — so the ~7-section,
  ~90-tool rail reads like a Revit-style task ribbon. A thin nav layer over the existing `section()`s
  (matched off each group's title); the active tab persists. Verified live: Build → only the 3 Build
  sections show, the rest hide.

## v0.3.369 — UX-4: Project-Browser spine (views/sheets/schedules)

- The model-browser panel now opens with a **Project browser** nav strip — quick links to *Plans & views*,
  *Sheets*, and *Schedules* (deep-linking the Drawings workspace) above a labelled *Model* element tree —
  so the browser reads as a full project index (à la a Revit Project Browser), not just a class list.

## v0.3.368 — UX-3: Library filter operators + Recent bucket

- The unified **Library** palette gains scoped search operators — `type:` (name/key), `class:` (IFC
  class), `category:`/`cat:`, and `discipline:`/`tag:` (full-text) — combinable with free terms
  (e.g. `class:ifccolumn`, `category:furniture`). And a **Recent** bucket: the last six placed items
  surface at the top of the list (per-project, in localStorage) for quick re-placement.

## v0.3.367 — AUTH-VS: visual node-authoring canvas

- A **visual node-graph editor** (Build → Advanced authoring → *Visual node authoring*) over the
  recipe-graph engine. Drop recipe nodes from a palette (wall / column / beam / slab / base plate /
  curtain wall / derive-analytical), **drag** them around, and **wire** one node's output ● into another's
  input ○ — the wire auto-injects the `{"$from": "<node id>"}` reference into the target's params so the
  upstream GUID threads through. **Run graph** executes the whole thing as one GUID-stable pass
  (`POST /edit/graph`), republishes, and reloads. Plain DOM + one SVG edge layer; no new deps.

## v0.3.366 — viewer: live co-editing (presence + reload banner)

- The viewer now subscribes to the **COLLAB-1 model-edit stream**: the live-presence roster refreshes
  instantly (not just the 20 s poll), and when **another user publishes a new model version** a "a
  collaborator updated the model — Reload" banner appears. Your own publishes never nag (the loaded
  version re-syncs on every model load). The `EventSource` closes on unload.

## v0.3.365 — viewer: Ask-the-model box + structural analytical panel

- The **Analyze & Coordinate** rail section gains two tools that surface the frontier backends:
  - an **Ask the model** box (RFI-0 NL-QA) — type a plain-language question ("what governs this element?",
    "what's blocking approval?") and get a cited answer, with a one-click *isolate the cited elements*.
  - a **Structural analytical model** tool (W10-7) — shows the derived analysis-model summary (curve /
    surface members · nodes · load case) and a *derive/refresh from the physical model* action.

## v0.3.364 — web client: typed bridge to the new engines

- Typed client methods for the frontier backends shipped this cycle, so the app (and future UI) can reach
  them: `docGraph` / `elementSources` (W9-4 cited sources), `rfiQa` (RFI-0 NL-QA), `analyticalSummary`
  (W10-7), `collabSnapshot` + `modelStream` (COLLAB-1 live co-editing, an `EventSource` wrapper), and
  `editGraph` (AUTH-VS recipe-graph). Typecheck + production build green.

## v0.3.363 — AUTH-VS: recipe-graph execution engine

- New **visual node authoring** backend. A *recipe graph* — authoring-recipe nodes wired by data
  dependencies — runs as one GUID-stable pass: `nodegraph.execute_graph` topologically orders the nodes
  (Kahn sort over the edges; array order when unwired) and threads each node's output into downstream
  params via `{"$from": "<node id>", "key"?: "<field>"}` references (a column node's GUID feeds the base
  plate that sits on it). Over the same `RECIPES` registry as the AI command bar — the no-code sibling.
- Served at `POST /projects/{pid}/edit/graph` (body `{graph, publish?, base_source?}`), versioning the IFC
  like `/edit` and honoring the COLLAB-1 optimistic lock. Bad graphs (unknown recipe/id, cycle, dangling
  ref, duplicate id) are rejected 400.

## v0.3.362 — COLLAB-1: optimistic edit-lock (no silent overwrite)

- `POST /projects/{pid}/edit` accepts an optional **`base_source`** — the model signature the client last
  loaded (from `GET .../collab`). If another user has published since, the edit is rejected **409** ("the
  model changed — reload") instead of silently overwriting their work. Backward-compatible: omitting
  `base_source` keeps the prior fire-and-forget behavior.

## v0.3.361 — COLLAB-1: live co-editing awareness (model stream)

- First slice of **real-time multiplayer co-editing**. A project's *model signature* bumps on every
  authoring publish; `GET /projects/{pid}/collab` bundles it with the live presence roster, and
  `GET /projects/{pid}/model/stream` (SSE) re-emits that snapshot whenever the model version **or** the
  set of present users (and where each is looking) changes — so a second open viewer live-reloads the
  geometry after another user's edit and shows who's in the session. Reuses the existing presence + SSE
  primitives; in-model comments already ride the GUID-anchored Topic/Comment model.
- *Next: per-user cursors/selection overlays and optimistic edit-locks (409 on a stale write).*

## v0.3.360 — RFI-0: NL-QA with cited sources

- **Natural-language QA** over the model, grounded in citations — the read/QA sibling of the AI authoring
  command bar, and the payoff of the doc-graph. `POST /projects/{pid}/rfi/qa` with `{question}` routes to
  the right substrate and answers with sourced facts:
  - *"what governs \<element/GUID\>?"* → element provenance (spec section · detail sheet · level),
  - *"what's blocking approval?"* → ranked decision-readiness gaps + fixes,
  - *"what is spec section 05 12 00?"* → the elements it governs,
  - anything else → a model overview pointing at how to ask a sourced question.
- Fully **deterministic** — the cited facts are the answer, so it works with no API key. Every claim
  carries its source (GUID · spec section · document sheet · readiness check).

## v0.3.359 — W9-4: document / specification graph (cited sources)

- New **doc-graph** layer — the cited-source half W9-4 left open. `docgraph.build` folds two node kinds
  onto the model graph: **spec sections** (an element's classification code → the governing MasterFormat/
  UniFormat section) and **documents** (attached detail/cut-sheets with their derived sheet reference),
  each linked to the elements they govern (`specified_by` / `documented_by`). Served at
  `GET /projects/{pid}/doc-graph`.
- `element_sources(guid)` returns one element's **cited provenance** — its spec sections, attached
  documents (with sheet refs), and spatial container, every fact tagged with its source. Served at
  `GET /projects/{pid}/elements/{guid}/sources`. The substrate the RFI-0 NL-QA layer answers from.

## v0.3.358 — W10-7: analytical surface members (slabs)

- `derive_analytical` now idealises **slabs / roof decks** into `IfcStructuralSurfaceMember`s (SHELL): a
  planar `IfcFaceSurface` bounded by an `IfcEdgeLoop` at the deck footprint, thickness carried, linked
  back to the physical slab. Handles both arbitrary-polygon and rectangle slab profiles. The analytical
  model now spans the frame **and** the floor/roof plates; `GET .../analytical` reports `surface_members`.

## v0.3.357 — W10-7: structural analytical model (frame)

- New **structural analytical model** layer alongside the physical (LOD 300) model. `derive_analytical`
  builds an `IfcStructuralAnalysisModel` from the physical frame: each column/beam → an
  `IfcStructuralCurveMember` (an `IfcEdge` topology) tied at shared `IfcStructuralPointConnection` nodes,
  each analytical member linked back to its physical element (`IfcRelAssignsToProduct`), plus a
  permanent-G self-weight `IfcStructuralLoadCase` + load group. Pure topology — no geometry kernel.
- Re-derive is **idempotent** (purges prior analytical entities via `remove_deep2`, no accumulation, no
  orphan topology). Exposed as the `derive_analytical` edit recipe; read the model back at
  `GET /projects/{pid}/analytical` (analysis models, curve/surface members, nodes, load cases).
- *Slice 1 = the frame. Surface members (slabs/walls → `IfcStructuralSurfaceMember`) and per-member load
  activities are next.*

## v0.3.356 — W10-6: room schedule quantity depth

- The computed **room schedule** now carries `IfcElementQuantity` depth — **Perimeter (m)** and
  **Volume (m³)** columns read from `Qto_SpaceBaseQuantities` alongside floor area. Flows through every
  schedule surface (CSV / SVG / PDF) since they render generically by column.

## v0.3.355 — W10-4: MEP design flow rate on segments

- `add_mep_run` (duct/pipe/cable) and `add_riser` accept an optional **design flow rate** (`flow` +
  `flow_unit`), written to `Pset_Massing_MEPSizing` alongside the nominal size. The flow unit defaults by
  system when omitted — CFM for ducts, GPM for pipes, A for cable — so schedules, QTO, and sizing
  pre-checks read design flow without a geometry parse. Exposed on the `add_duct`/`add_pipe`/
  `add_cable_tray`/`add_wire`/`add_riser` recipes.

## v0.3.354 — D5: detail callouts on the PDF sheet + real sheet refs

- Detail callouts now render on the **PDF** sheet path (`sheet_pdf`), not just SVG — an NCS divided-circle
  bubble (detail number over sheet ref) with a leader to the element, plus a **DETAILS** legend below the
  keynotes.
- The divided-circle bubble carries a **real sheet reference** (bottom half) instead of a placeholder "—":
  the attached document's `Identification` (e.g. `A-541/3`), else the sheet number derived from its
  `Location` basename (`details/S-501.pdf` → `S-501`). `attach_document` no longer leaves the placeholder
  `Identification` that shadowed the derived ref.

## v0.3.353 — DISC-cw: curtain-wall parts read Architectural

- Framing/glazing parts (`IfcMember` mullions/transoms, `IfcPlate` glazing) aggregated under an
  `IfcCurtainWall` or `IfcRoof` now classify as **Architectural**, not Structural — context wins over the
  bare-class default (a façade mullion is enclosure, not frame). The properties index records each
  element's aggregating **host** class, and `discipline_of_ifc_class` consults it. Without a host, parts
  stay Structural.

## v0.3.352 — discipline coverage report

- `GET /projects/{pid}/elements/by-discipline` now returns a **coverage** view over the discipline
  tree: every standard NCS discipline is marked present/absent with its element count, plus
  `disciplines_covered` / `disciplines_total` and a `missing` list. A completeness lens for the model
  — which disciplines are actually populated vs. still empty — computed from the property index with no
  geometry parse.

## v0.3.351 — W10-6: schedule CSV export

The computed door/window/room schedules now export to **CSV** (`GET /projects/{pid}/drawings/schedule.csv?kind=`
for one, or omit for all three) for spreadsheets / procurement / submittals — finishing the schedule views
into the export pipeline alongside the existing SVG/PDF. `drawing.schedule_csv`.

## v0.3.350 — W9-6b: FF&E bill of materials

A new **FF&E / furnishings bill of materials** from the model's placed furniture — `content.furniture_bom`
counts each item (by name) with its IFC class and the levels it appears on, composing `IfcFurniture` /
`IfcFurnishingElement` / `IfcSystemFurnitureElement` (the classes `place_content` + `furnish` author). An
owner/vendor order + procurement starting point. Served on `GET /projects/{pid}/ffe-bom`.

## v0.3.349 — W10-4: nominal-size psets on MEP segments

Authored MEP segments (`add_mep_run` / `add_riser`) now carry a **`Pset_Massing_MEPSizing`** with the
**nominal size (mm)**, shape, and length — so schedules, QTO, and sizing pre-checks can read the size
directly instead of re-deriving it from geometry (nominal sizing normally lives on the IfcType/profile,
which our on-the-fly segments don't carry). Best-effort; never blocks authoring.

## v0.3.348 — UX-4: "Script this" — the recipe interface, made discoverable

A new **⌨ Script this** toolbar button surfaces the app's **scriptable, GUID-safe recipe interface** as a
first-class resource (UX-4 goal). Type a command in plain English and it shows the **exact recipe plan** it
maps to — e.g. *add a 3m wall from 0,0 to 5,0* → `add_wall({"start":[0,0],"end":[5,0],"height":3,
"thickness":0.2})` — the same verbs the AI command bar and the sandboxed `ifcopenshell` runner drive, then
**applies** it (non-destructive plans). Makes the code/authoring layer visible instead of a hidden
power-user path.

## v0.3.347 — Composed sheet: cap plans + per-level sheets (fixes tower timeout)

The composed **key-plan sheet** (`sheet.svg`/`sheet.pdf`, S-101) rendered a plan panel for **every** storey
— on the 30-storey tower that **timed out** (30+ full-model geometry cuts) and crammed 30 illegible plans on
one A3. It now **caps to a few representative levels** (sampled evenly across the building) and takes an
optional **`storey`** to render exactly one level's sheet. On the tower: the key-plan sheet now renders in
~20 s (was ∞) and a single-level sheet in ~12 s, each with the titleblock + per-panel scale + section +
elevation. `GET /projects/{pid}/drawings/sheet.{svg,pdf}?storey=Level%204`.

## v0.3.346 — UX-4: always-visible Info-Box on the 3D canvas

A compact **Info-Box** strip now sits on the 3D view (bottom-left) showing the **selected element's key
facts** — name · IFC class · level · discipline (with the discipline's colour dot from the unified tree) —
**regardless of which rail tab is open** (ArchiCAD's Info-Box pattern). Previously the identity header lived
only inside the Properties tab, so you lost sight of what was selected while on Tools/Tree/Library. Updates
on selection, clears on deselect. First component of the UX-4 designer-workspace shell.

## v0.3.345 — Plan fix: per-level room tags + titleblock / scale / notes

Two fixes to the drawing-set plans. **(1) Room labels no longer stack across levels.** The plan cut its
*geometry* at the level elevation but tagged **every** `IfcSpace` (and door/window callout) in the model —
so a Level 4 plan drew the cellar, lobby, apartment, and amenity room names all on top of each other (every
floor shares the footprint). `space_tags`/`element_callouts` now take the cut plane and label **only the
elements that level's cut passes through**. **(2) Plans now carry a real sheet frame** — a titleblock band
with the sheet title, a compact titleblock box (title · scale · cut-plane AFF · grid), a true **graphic
scale bar** (correct at any zoom), a **north arrow**, and a **general-notes** block. Room names are XML-
escaped so a name with `&`/`<` can't break the SVG.

## v0.3.344 — CODE-3: detail-rule citations follow the resolved edition

The Track-D detail-rule engine seeds its flashing/keynote citations against **IBC 2021**. `apply_rules` now
takes an **`ibc_edition`** so those citations reword to the project's **resolved adopted edition** — an
exterior window in a 2024-adopting jurisdiction cites *IBC 2024 §1404.4* rather than the seed's 2021. Only
the edition year in a citation changes (facts of law); the seed content is untouched. Threaded through the
`apply_detailing_rules` recipe (`ibc_edition` param).

## v0.3.343 — UX-3: unified, searchable Library palette

The 📚 Library now opens **one browsable palette** that unifies the **content catalog** (CONTENT-1 — site
logistics / furniture / landscaping) and the **family types** (W10-1) in a single filterable list —
previously the content parts and the type/family system were separate surfaces. A **search box** filters
across name / IFC class / category / phase as you type; each row shows its class + category; clicking places
the item at an **E,N** point (defaulting to the last picked point). Mesh import (glTF/OBJ/STL → auto-
classified) stays inline. First slice of UX-3 — thumbnails, `tag:`/`type:`/`discipline:` operators, a Recent
bucket, drag-to-place, and appendable IFC libraries follow.

## v0.3.342 — UX-1b: dedicated Annotate + Library tool groups

The interactive **annotation** tools (Add note · Dimension · Revision cloud · Tag) and the **content
library** were buried inside the "Advanced fabrication tools" fold. They're now surfaced as their own
labelled **✍ Annotate** and **📚 Library** groups in the model rail — the two capabilities the UX-1 research
flagged as under-exposed. The Advanced fold keeps the LOD-350/400 fabrication/detailing tools.

## v0.3.341 — UX-1: model tools grouped by lifecycle (ribbon, first slice)

The model rail's tool sections are now labelled and ordered by the **modeling lifecycle** instead of the
seven accreted names — the first slice of the UX-1 task ribbon. Sections read **Data ·** Models / Working
origin · **Build ·** Draw elements / Grids & levels / Advanced authoring, annotate & library · **Analyze &
Coordinate ·** clash / QA · **Document ·** Exports & issue, and the "More tools" group now flows Build →
Analyze/Coordinate → Document. A one-line intro names the lifecycle. (Follow-up UX-1b: split the combined
authoring section into dedicated **Annotate** and **Library** groups.)

## v0.3.340 — CODE-5: applicable code requirements as buildingSMART IDS

The code-analysis engine can now **emit the machine-checkable subset of the applicable code requirements as
a buildingSMART IDS 1.0 file** — so the same jurisdiction-resolved rules validate an IFC in *any* IDS
checker (extends the IDS→BCF pipeline). `codecheck.code_ids(description, edition)` composes the fired code
rules (which requirements apply for this occupancy / size) with the standard IFC common-property IDS specs:
a fire-resistance-rated occupancy (R/A/H/I, or ≥4 stories) pulls in the rated-element groups (wall / door /
slab / column / beam `FireRating`), plus space area/reference (occupant load) and envelope U-value (IECC).
`GET /codes/ids?description=…&edition=…` returns the fired topics + `ids_xml`; `&download=true` returns the
`.ids` attachment. Property requirements (facts of law), never code prose; the AHJ makes the determination.

## v0.3.339 — EST-1 5D: crew-days → schedule duration

The productivity/labour estimate already turned quantities into man-hours → crew-days → cost; now it turns
the crew-days into a **schedule duration** (the 5D loop). Per-line crew-days roll up by **trade group**
(Earthworks · Concrete · Masonry · Structural Steel · MEP · Finishes) into a **working-day** and
**calendar-day** duration — each trade's duration = its crew-days ÷ the number of **parallel crews** of that
trade (a new `crews` control that shortens the trade), and the project duration assumes trades run
sequentially (a conservative critical path; overlap only shortens it). Flows through `labor_estimate` →
`full_estimate` → `from_model`; `GET /projects/{pid}/estimate/labor?crews=N` returns the `schedule` block
(per-group breakdown + working/calendar days) alongside the cost.

## v0.3.338 — COST-DB: the model estimate prices through the pinned vintage

Closes the reproducibility loop (build-order step 8). The model estimate endpoints —
`GET /projects/{pid}/estimate/from-model` and `GET /projects/{pid}/qto/by-floor` — now price the
takeoff **through the project's pinned cost vintage** (its `cost_dataset_id`, else the latest installed),
applying that vintage's `{ifc_class: rate}` map as the rate overrides and returning the `cost_vintage` it
priced with. So a 2024-pinned project's estimate stays on 2024 rates after newer vintages land — defensible
and reproducible. Falls back to the shipped benchmark rates when no vintage is installed.

## v0.3.337 — COST-DB: vintage-versioned cost database (offline first slice)

First slice of the cost-database plan ([cost-db-import-plan.md](docs/cost-db-import-plan.md)) — the
**versioning backbone** so a project's estimate is reproducible against the exact cost vintage it was built
on. New `cost_datasets` + `cost_items` tables (every priced row hangs off a dataset); a **`cost_dataset_id`**
pin on the project; and an **offline `PublicDataImporter`** (`cost_db.py`) that builds a `public_local`
vintage from the app's shipped benchmark rates (one MasterFormat-coded `CostItem` per rate, linked to its IFC
class so the model takeoff prices straight through) — **no network, no subscription**. A vintage **resolver**
(latest · exact year · `nearest`/`strict` fallback) and `is_latest` management round it out.

Endpoints: `GET /cost/datasets` (installed vintages + what the public importer offers), `POST
/cost/datasets/import` (`{vintage, quarter, source}`; a `source:"cloud"` request with no subscription warns +
falls back to the public build), and `GET`/`POST /projects/{pid}/cost-vintage` (pin a project to a vintage;
null = follow latest). The `massing.cloud` subscription importer (signed-bundle download), real public-source
ingest (BLS/FRED/DoD/Census), location factors, and PPI escalation-forward are later build-order steps.

## v0.3.336 — RFI-0: missing-dimension detection in the decision-readiness audit

The decision-readiness / RFI-prevention audit gains a fifth gap source — **missing dimensions**, the
proactive inverse of the classic "what size is this?" RFI. It scans the model for elements a builder or
estimator **can't size, order, or take off** because a dimension the drawings should carry is absent:
doors/windows with no `OverallWidth`/`OverallHeight`, and rooms with no floor area
(`Qto_SpaceBaseQuantities`). Each surfaces as a ranked, GUID-anchored gap (category `dimensions`) with a fix,
alongside the existing code / detail / data / coordination gaps — and rides the same
`POST /rfi/readiness/bcf` promotion to BCF.

## v0.3.335 — One canonical discipline source across both engines

New low-level module **`aec_data/disciplines.py`** holds the shared discipline data — the CSI MasterFormat
division master (`MF_DIVISIONS`) and the discipline colour palette (`DISCIPLINE_COLORS` / `SERIES_COLORS` /
`discipline_color()`). It lives in the geometry engine on purpose: `aec_api` can import `aec_data` but not
the reverse, so anything both need has to sit there. `aec_api.classification` now **imports** these instead
of defining its own copies, and `aec_data.specmanual` drops its duplicate `_DIVISIONS` map — so the project
manual's CSI divisions and the estimate/sheet/viewer vocabularies are literally the same objects. One source
of truth for the division titles and discipline colours across the API and the IFC engine (DISC-3b).

## v0.3.334 — Estimate rolls up by real discipline (not IFC class)

The model estimate's `by_discipline` was a misnomer — it grouped by raw **IFC class**, so a "discipline"
breakdown listed `IfcColumn`, `IfcSlab`, `IfcPipeSegment` … rather than Structural / Plumbing / …. Now each
priced class line carries its **discipline** (name + code + color from the unified tree), and a genuine
**`by_discipline_rollup`** sums the lines into NCS disciplines — so the estimate reads as
Structural $X · Architectural $Y · Mechanical $Z · …, colored to match the viewer. The per-class detail is
kept as `by_class` (and `by_discipline` stays as an alias for backward compatibility). First slice of
folding the data engines onto the one spine (DISC-3).

## v0.3.333 — Tool buttons for Fire Alarm + Telecom; upgraded demo tower

- **🔔 Fire-alarm device** and **📶 Telecom device** tool buttons in the modeling rail (next to
  🧯 Fire-protection), so the DISC-4a recipes are one click at the last-picked point — pick the device kind
  (smoke/heat detector, pull station, horn-strobe, bell, FACP · MDF/IDF/switch/WAP/data outlet) and it's
  authored on the Fire Alarm / Telecommunications system.
- The demo **30-storey tower** is regenerated with a proper building-element breakdown so every discipline
  is represented: a **unitized `IfcCurtainWall`** facade (4 full-height assemblies — 152 mullions/transoms +
  720 glazing panels — replacing the old thin glazed walls + punched windows); **fire-rated construction**
  (286 walls: 2-hr core/shaft enclosure + 1-hr dwelling-unit demising, via `Pset_WallCommon.FireRating`);
  a **roof assembly** (`IfcRoof` over the structural deck); **90 smoke/heat detectors + 61 alarm devices**
  (pull stations / horn-strobes / FACP) on a **Fire Alarm** system; and **37 telecom devices** (MDF/IDF/WAP)
  on a **Telecommunications** system. The model now spans Structural / Architectural / Mechanical / Plumbing /
  Electrical / Fire Protection / Fire Alarm / Telecom — each colored distinctly by the discipline tree.

## v0.3.332 — Fire Alarm + Telecom as first-class authorable systems

Two building disciplines that were previously only reachable as raw IFC classes are now first-class
authoring recipes, mirroring how fire *protection* became first-class (v0.3.311):

- **`add_fa_device`** — a fire-alarm / life-safety device: smoke/heat/duct **detector** (`IfcSensor` with
  `SMOKESENSOR`/`HEATSENSOR`), **manual pull station** / **horn-strobe** / **strobe** / **bell** / **FACP**
  (`IfcAlarm`), enrolled on a named **Fire Alarm** distribution system. Fire alarm is its own discipline
  (the FA sheet series), distinct from fire protection (sprinklers/standpipes).
- **`add_comms_device`** — a telecom / low-voltage device: **MDF/IDF rack**, **network switch**, **wireless
  access point** (`IfcCommunicationsAppliance`) or **data outlet** (`IfcOutlet`), on a **Telecommunications**
  system (discipline **T**).

Both classify correctly under the unified discipline tree — comms → Telecommunications (purple), fire-alarm
devices → Electrical/FA — so they color and group distinctly in the viewer + model browser. Invokable via
`POST /edit` and the AI authoring command bar.

## v0.3.331 — Color-by-discipline in the viewer

The IFC-classes panel gains a **Color by** toggle (IFC class ↔ Discipline). In discipline mode every
class swatch takes its **discipline's canonical color** from the served tree (v0.3.330) — fire = red,
plumbing = green, mechanical = amber, electrical = yellow, structural = blue, architectural = grey — and
a **discipline color legend** appears showing exactly which disciplines are in the model. A **Paint model**
button pushes the current scheme onto every element in the 3D view, the way Navisworks/Revit color a
federated model by discipline. Unmapped classes keep their stable hashed hue.

The model browser now **consumes the same served IFC-class → discipline map** (`setDisciplineLookup`)
instead of its own regex — one shared vocabulary, so "By discipline" grouping and the viewer colors always
agree. `IfcReinforcingBar`/mesh/tendon now classify to Structural (were falling to the default).

## v0.3.330 — Unified discipline tree: colors + full IFC coverage

The Discipline Spine (`classification.py`) gains the two things it was missing to be the app's single
source of truth for *how a discipline looks and what rolls up to it*:

- **A canonical per-discipline color palette** (`DISCIPLINE_COLORS` + `discipline_color()`) — one hex per
  NCS discipline, chosen for perceptual separation and common coordination conventions (fire = red,
  plumbing = green, mechanical = amber, electrical = yellow, telecom = purple, structural = blue,
  civil = earth). Fire Alarm carries its own swatch so it reads apart from Fire Protection red. This is
  net-new — the viewer previously hashed class names to arbitrary colors and no shared palette existed.
- **Full IFC-class → discipline coverage** (`_IFC_DISCIPLINE`) for the MEP / fire / electrical / telecom
  distribution entities the MasterFormat estimate map never enumerated (`IfcSprinkler`→Fire,
  `IfcAlarm`/`IfcSensor`→Electrical, `IfcCommunicationsAppliance`→Telecom, `IfcTransformer`/switchgear→
  Electrical, `IfcPump`/`IfcTank`→Plumbing, `IfcBoiler`/`IfcCoolingTower`/`IfcFan`→Mechanical, …), so
  every element in a real model classifies to a discipline instead of falling to the default.

New `discipline_tree()` composes it all — per discipline: color, MasterFormat divisions (+titles),
UniFormat II groups (+titles), NCS sheet series, and the IFC classes that roll up to it — plus an
`ifc_class_discipline` lookup and a `colors` map. Served on `GET /reference/disciplines` (`tree` key) so
the viewer, plan/PDF poché, sheet generator, and model browser can all color/group by one shared
vocabulary rather than each re-encoding its own. First step of unifying the discipline tree across every
module and engine.

## v0.3.329 — QTO: derive length for linear elements so they price non-zero

Fixes a $0 in the model estimate. Linear elements (`IfcPipeSegment` / `IfcDuctSegment` /
`IfcCableCarrierSegment` / `IfcRailing`) are modelled as swept solids with **no Qto length**, so the
geometry takeoff returned `length = 0` and the per-metre MEP/railing rates (added v0.3.326) totalled them
at **$0**. `aec_data.qto` now derives a `length` in its geometry fallback as the **longest bounding-box
dimension** of the meshed solid — robust whether the run is the extrusion depth (vertical pipe/cable riser)
or lies in the profile plane (a railing extruded to rail height). On `quay_tower.ifc` the 36 pipe segments
now take off 1,153 m ($207,540), the cable riser 100.5 m ($22,110), and railings 112 m ($13,440) — all
previously $0. `test_massing.py` extended (cored-model pipe/duct risers assert metre-scale, non-zero length).

## v0.3.328 — UX-2: element-aware tags

New `add_tag` recipe places an **element-aware tag** — an `IfcAnnotation` (ObjectType "tag") whose label
is **auto-read from the host element** (its Name → a Pset `Reference`/`Tag`/`Mark` → its type name → the
IFC class short-name), positioned at the host's plan centroid and **assigned to it**
(`IfcRelAssignsToProduct`), so the tag tracks the element it describes. `text` overrides the auto-read
label. Renders on the generated plan (via the v0.3.327 annotation pass). New **🏷 Tag selected element**
tool (uses the current selection) + `addTag` client method. This is the "live element-aware tags" slice of
UX-2; only inference-snapped placement remains.

## v0.3.327 — UX-2: revision clouds + view-placed annotations on the plan

Closes the annotation author→sheet loop. Two parts:
- **`add_revision_cloud` recipe** — authors an `IfcAnnotation` (ObjectType "revision") as a **scalloped
  closed polyline** around a region (two opposite [E,N] corners, or ≥3 boundary points) + an optional
  revision tag (`IfcTextLiteral`). GUID-stable, guarded, reachable via `POST /edit`. New **☁ Revision
  cloud** two-corner tool + `addRevisionCloud` client method.
- **Annotations now render on the generated plan** — `drawing.plan_svg` reads view-placed
  `IfcAnnotation`s (from `add_annotation` / `add_dimension` / `add_revision_cloud`) and draws them:
  text notes, element tags, dimension lines + labels, and revision clouds + rev-tags. Previously
  annotations round-tripped as IFC but never appeared on the drawing — the baked-SVG path couldn't
  show model-authored markup. The count is returned as `annotations` and flows through the sheet
  composer, so issued sheets carry them too.

## v0.3.326 — Estimate: price MEP, fire-protection & plant equipment

The model estimator's `DEFAULT_RATES` covered structure + architecture only, so a fully-serviced
building's mechanical/electrical/plumbing scope fell through to *unpriced* — understating the
conceptual total. Added unit rates for MEP distribution (pipe/duct/cable-carrier per metre, fittings
per count), terminals & fixtures (sprinkler heads, air/sanitary terminals, light fixtures, outlets,
switches), and plant equipment (pumps, boilers, tanks, transformers, cooling towers, chillers,
switchgear, unitary equipment, fans) plus steel-connection assemblies. `IfcReinforcingBar` is
intentionally *not* priced separately — the concrete volume rates are quoted in-place incl. rebar, so
pricing it again would double-count; LOD-400 rebar stays a takeoff-only detail. Surfaced on a
2,750-element authored tower whose 232 sprinkler heads, risers and cellar plant returned $0.

## v0.3.325 — Fix: whole-model re-upload served stale from the IFC cache

`ifc_loader.open_model` cached opened models by **path alone** (`@lru_cache`), so re-publishing a
**replacement** model to the same `source.ifc` path returned the *previous* model — reindex, the
scene digest, drawings, schedules and every analysis kept reading the old geometry until the process
restarted. Now keyed by `(path, mtime_ns, size)`: an unchanged path still hits the cache (fast), but a
file **re-written in place** reloads fresh. The `/edit` path was never affected (it writes a new
timestamped file); whole-model replacement to a fixed path was. Regression test `test_ifc_cache.py`
added to the gate. Surfaced while validating a 2,750-element authored tower whose newly-added
architectural finishes (ceilings, floor finishes, unit doors, railings) were invisible until the fix.

## v0.3.324 — Interactive dimensions (UX-2, next slice)

Extends the in-view annotation tool with **dimensions**. New `add_dimension` recipe authors an
`IfcAnnotation` between two [E,N] points — a dimension line (`IfcPolyline`) plus the **measured distance**
as an `IfcTextLiteral` at the midpoint (auto-labelled `5.00 m`, or a custom label), in the Annotation
context; round-trips as real IFC and feeds the drawing generator. New **📐 Dimension** tool with a two-click
flow (first point → second point → measured dimension). The E8 guardrails already validate the two points
(finite + distinct → zero-length rejected). `addDimension` client + `test_annotation.py` extended (a 3-4-5
span → `5.00 m`, custom label, zero-length rejection). *Next: inference-snapped dimension placement + tags
that read a live IFC property.*

## v0.3.323 — Interactive annotation: place notes/tags as IfcAnnotation (UX-2, first slice)

The first slice of the UI/UX Master Pass's annotation gap: annotation existed **only** baked into generated
plan SVGs — now you can place it *in the model*. New `add_annotation` recipe authors an **`IfcAnnotation`**
with an `IfcTextLiteral` (an `Annotation2D` representation in the Annotation context) at an [E,N,z] point —
a note / tag / callout that round-trips as real IFC (and can feed the drawing generator, unlike the baked
SVG path). New **🏷 Add note / annotation** tool places one at the last-clicked point (text + kind prompt);
`addAnnotation` client. Empty text rejected. `test_annotation.py` (authors + round-trips through a written
IFC). *Next (UX-2): dimensions snapped by the E1 inference engine, element-aware tags, revision clouds; and
the UX-1 ribbon consolidation + UX-3 Library palette (best built with a live 3D session to verify the look).*

## v0.3.322 — Scene digest: an LLM-grounding model summary (A4)

A compact, one-glance summary of *what's in the model* — and the grounding the AI command bar was missing.
New `scene.digest(model)` composes the shipped summaries (element counts by class, storeys, spaces, MEP
systems + disciplines, phasing, LOD, model hygiene) into a small dict plus a one-paragraph `prose` overview,
degrading gracefully on a bare model. New `GET /projects/{pid}/scene-digest` + a **🔎 Model digest** tool
(counts, MEP disciplines, phasing, hygiene at a glance). Crucially, `POST /ai/author` now injects the digest
prose into the planner's system prompt, so Claude authoring is **grounded in the current model** ("N walls,
2 storeys, a fire-protection system…") instead of planning blind. `sceneDigest` client + `test_scene.py`.

## v0.3.321 — Mesh→IFC asset import: bring in detailed parts, auto-classified (CONTENT-1 remaining)

The other half of the content library: **import a well-detailed mesh and place it as the *right* IFC**, not
a random shape. New `content.parse_mesh` loads a glTF / GLB / OBJ / STL / PLY (trimesh) into recentred,
metre-scaled verts + faces (glTF Y-up → IFC Z-up; a face-count cap; `scale`), and `content.detect_category`
guesses the catalog category from the filename (`office-chair.glb` → `chair`; `Porta-John.stl` →
`sanitary_unit`; longest synonym wins). New `POST /projects/{pid}/content/import` (multipart) parses the file,
auto-detects (or takes `category=`), and authors it via the `place_content` recipe — correct IFC class +
phase + Uniclass/OmniClass classification — versioned, undo-able, republished. The 🏗 Site content library
tool gains an **⬆ Import mesh** picker (drops the asset at the last-clicked point). License-vet the source
before import. `importContent` client + `test_content_import.py`. Builds on the B4 mesh hatch + the CONTENT-1
catalog. *Next: a curated CC0 seed library + a browsable thumbnail palette (folds into the UX-3 Library pass).*

## v0.3.320 — Element-to-element connections (B5)

The LOD-350 coordination primitive: which elements are physically connected. New `connect_elements` recipe
records an `IfcRelConnectsElements` between two building elements (a beam framing into a column, a brace to a
gusset, a hanger to a slab) — distinct from the MEP port link (`connect_mep`). Idempotent per ordered pair,
rejects self/missing. New `element_connections` read-back reports the connected pairs (with class +
description) and each element's connection **degree**, served at `GET /projects/{pid}/element-connections`;
`connectElements` / `elementConnections` clients. Guarded (needs both GUIDs). Reachable via the AI command
bar; authored edges export for structural-analysis / coordination tools. `test_element_connections.py`.

## v0.3.319 — Vertical MEP risers (standpipes / stacks / vents)

MEP runs could only be drawn horizontally (`add_mep_run` sweeps in plan); a multi-story **riser** was
impossible. New `add_riser` recipe sweeps an `IfcPipeSegment` **vertically** (world +Z) from `bottom_z` to
`top_z` at an [E,N] point, with a port at each end, enrolled on a distribution system — the vertical
complement to `add_mep_run`, for **fire standpipes**, plumbing **stacks**, and **vents**. New **⭱ Vertical
riser** tool places one at the last-clicked point over a bottom→top elevation range. Verified
deterministically (ExtrudedDirection = +Z, Depth, base elevation) and by standalone tessellation (a real
cylinder spanning the height). `test_mep_systems.py` extended; zero/negative height is rejected.

## v0.3.318 — O&M / warranty document refs on the as-built model (G3 follow-up)

Completes the LOD-500 turnover trio (verify · dimensions · manufacturer) with **operation & maintenance /
warranty documents** bound to the physical asset. New `attach_om_document` recipe (a purpose-tagged
`attach_document` — `OPERATION_MAINTENANCE` or `WARRANTY`) associates a manual/warranty reference (name +
link) with the selection via `IfcRelAssociatesDocument`; `asbuilt_summary` now reports `with_om_docs`
(elements carrying an O&M/warranty document, detected by the document's `Purpose`) + the distinct document
names. The ✅ As-built (LOD 500) tool gains an **📄 Attach O&M / warranty doc** control and shows the O&M-doc
count in the readiness line. Guarded (needs a selection) + an `attachOmDocument` client. `test_lod500.py`
extended (2 O&M + 1 warranty doc → `with_om_docs` = 3).

## v0.3.317 — Deeper authoring guardrails (E8)

The pre-apply guardrails now catch more classes of broken edit before they touch the model. `guards.precheck`
gains: nested type **`dims`** validation (each value finite; dimension keys must be positive — mirrors the
top-level rules, non-dimension keys only finite-checked), **`points`** footprint arrays (every vertex a
finite [E,N] pair; ≥2 vertices), **sloped-wall heights** (`start_height`/`end_height` finite ≥ 0),
**procedural-mesh** `verts`/`faces` (non-empty), and new **reference requirements** — `connect_mep` needs
both `guid_a` + `guid_b`, `set_system_predefined` needs a `system`. Still fast, deterministic, params-level
(no I/O); errors block, suspicious-but-legal values warn. `test_guards.py` extended. This closes the E8
"deepen" follow-up (the first slice shipped earlier).

## v0.3.316 — Sprinkler coverage pre-check (NFPA-13-informed)

New `mep.sprinkler_coverage(model, hazard)` counts the SPRINKLER heads and compares against the number
NFPA 13 would require for the model's protected floor area (summed IfcSpace `Qto_SpaceBaseQuantities.
NetFloorArea`) at the hazard class — max protection-area-per-sprinkler is **200 / 130 / 100 ft²**
(light / ordinary / extra), a fact of the standard (copyright-safe; the text stays in NFPA 13). Returns head
count vs required, adequacy + shortfall, and area unknown → `adequate: null` when no spaces are measured. New
`GET /projects/{pid}/mep/sprinkler-coverage?hazard=` + a **🧯 Sprinkler coverage** button in the MEP tool
(shown when a fire-protection system exists). A planning assist — not a hydraulic calc, spacing check, or
obstruction review. `test_mep_systems.py` extended (2 heads / 400 m² → 22 required at light hazard; ordinary
requires more; empty model → n/a).

## v0.3.315 — Fire-protection equipment: hose reel / FDC / hydrant / fire pump (MEP-FP next slice)

Fleshes out the fire-protection system with real devices, not just piping. New `add_fire_equipment`
recipe authors a **sprinkler head**, **hose reel**, **fire-department (siamese) connection**, **hydrant**
(all `IfcFireSuppressionTerminal` subtypes with the right `PredefinedType` — HOSEREEL / BREECHINGINLET /
FIREHYDRANT / SPRINKLER) or a **fire pump** (`IfcPump`), each placed on the `Fire Protection` distribution
system (discipline = fire, so it rolls up in the MEP browser). New **🧯 Fire-protection equipment** tool
places the chosen device at the last-clicked point (mirrors the door/window place flow). `test_mep_systems.py`
extended (hose reel + FDC + fire pump land as the right IFC classes on the fire system). *Next: sprinkler
coverage/spacing check + standpipe risers.*

## v0.3.314 — Full cost estimate: labour + material + equipment (EST-1 next slice)

The model-driven estimate goes from labour-only to a fuller **5D cost**. `productivity.py` gains a
**material $/unit** (`MATERIALS`) and **equipment/plant $/unit** (`EQUIPMENT`) benchmark layer beside the
man-hours rates, and a new `full_estimate` augments each line with `material_cost` / `equipment_cost` /
`line_total` plus `total_material_cost` / `total_equipment_cost` / `total_cost`. `from_model(..., full=True)`
and `GET /projects/{pid}/estimate/labor?full=true` return it; the catalog now carries the unit material +
equipment costs too. The 💰 tool (renamed **Cost estimate — labour · material · equipment**) shows the
labour / material / equipment / total breakdown and a per-line total. Still excludes overhead / profit /
markup; all rates are editable benchmarks. `test_productivity.py` extended (concrete: $130/m³ material +
$15/m³ equipment; masonry $30/m² material, no equipment; totals reconcile).

## v0.3.313 — Decision-readiness gaps → BCF (RFI-0 next slice)

The decision-readiness audit (v0.3.307) now **rounds its gaps to trackable BCF issues**. New
`POST /projects/{pid}/rfi/readiness/bcf` runs `rfi_prevention.decision_readiness` and promotes every gap —
failed code checks, missing details/keynotes, model-data holes, open clashes — to a `type="readiness"` BCF
`Topic`: GUID-anchored (a 3D pin from the gap's first element), category-labelled, priority from the gap's
severity (high → high). Idempotent — re-running clears the prior readiness topics so they never pile up
(mirrors the W9-2b egress→BCF pattern). The 🚫 Decision-readiness tool gains a **📌 Promote N gaps to BCF
issues** button, so the "what's missing before we issue?" list becomes a resolvable, round-tripping issue set
in the Issues panel. New `rfiReadinessBcf` client. `test_readiness_bcf.py` (integration: 9 gaps → 9 topics,
409 without a source IFC, idempotent re-run).

## v0.3.312 — Security: Capacitor 6 → 7, clears the transitive `tar` advisories (SEC-DEP-1)

Dependency-hygiene release. The mobile shell's `@capacitor/*` packages (`android`, `cli`, `core`, `ios`)
move from `^6.2.1` to `^7`, pulling `@capacitor/cli@7.6.8` and its transitive `tar@7.5.20` (was `tar@6.2.1`).
That clears **7 Dependabot alerts** (6 high / 1 medium) — all node-tar extraction-time symlink/hardlink
path-traversal advisories (GHSA-9ppj-qmqm-q256, GHSA-qffp-2rhf-9h96, GHSA-83g3-92jg-28cx, GHSA-34x7-hfp2-rc4v,
GHSA-r6q2-hw4h-h46w, GHSA-8qq5-rm4j-mr97, GHSA-vmf3-w455-68vh) that entered **only** through `@capacitor/cli@6`.
The fix needs `tar ≥ 7.5.16`, but `tar@7` is ESM-only and Capacitor 6's CLI is CJS, so a bare npm override would
break `cap` (`ERR_REQUIRE_ESM`) — hence the full Capacitor 7 bump. Real exploit risk was nil (the CLI extracts
only its own trusted platform templates during a developer-run `cap sync`, never untrusted input, never in CI or
at runtime); this is security-tab hygiene, not an urgent patch. `capacitor.config.ts` needed no v7 changes; no
native `android/`/`ios/` projects are checked in, so there was no Gradle migration. Verified: `npm ls tar` resolves
`tar@7.5.20`, `npm run build` (Node 20) passes, and `cap sync` succeeds.

## v0.3.311 — Fire protection as a first-class distribution system (MEP-FP)

MEP systems now carry a **discipline**, so fire protection stands beside HVAC / plumbing / electrical
instead of being folded into a generic "MEP" group. `IfcDistributionSystem`s are stamped with a
`PredefinedType` (`FIREPROTECTION` / `VENTILATION` / `DOMESTICCOLDWATER` / `ELECTRICAL`…): `add_mep_run` /
`add_mep_fitting` / `add_mep_terminal` take a `discipline` (the segment/fitting/terminal recipes default to
their natural discipline), a new `set_system_predefined` recipe (re)types an existing system, and a new
**`add_sprinkler`** recipe authors an `IfcFireSuppressionTerminal` sprinkler head on the `Fire Protection`
system. The system browser (`mep.mep_summary`) now reports each system's **discipline** + PredefinedType, a
**by-discipline rollup**, and a `has_fire_protection` flag; fire-suppression terminals are counted and are
port-connectable, so the W10-4 connectivity check covers sprinkler runs too. The 🔀 MEP systems tool shows a
discipline rollup (with a "no fire-protection system yet" nudge) and a per-system discipline label. The
discipline is inferred from member classes when a system carries no explicit type, so existing models
classify correctly. `test_mep_systems.py` extended (fire-protection system + sprinkler heads +
`set_system_predefined` retag). *Next: sprinkler coverage/spacing + standpipe/fire-pump equipment.*

## v0.3.310 — Existing-building code: IEBC scope-of-work classifier (CODE-EBC)

Unlocks renovation / adaptive-reuse projects, which are governed by the **International Existing Building
Code**, not the new-construction path. New `ebc.py` (data side, facts-of-law like the CODE-1/2/3 engine —
owns the classification decision tree + published section/chapter numbers, never the copyrighted prose)
classifies a scope of work under the **Work Area Compliance Method**: **Repair · Alteration Level 1 / 2 / 3
· Change of Occupancy · Addition**. `classify(...)` is a pure, deterministic decision tree — a Level-2
trigger (space reconfiguration, adding/removing a door or window, reconfiguring/extending a system, added
equipment) becomes **Level 3** when the work area exceeds 50% of the building (IEBC §505), an addition or
change of occupancy governs as primary while co-occurring alterations still apply, and each result carries
the driving citations (§502–§507 + the requirements chapter), the applicable nested levels, and the
jurisdiction's adopted IEBC edition. `from_model(...)` first-guesses the scope from the model's **phasing**
(existing vs new/demolish → an alteration with a rough work-area estimate) which explicit flags override.
New `GET /codes/ebc/pathways` (reference catalog) + `GET /projects/{pid}/codecheck/ebc` (with `infer=true`
for the phasing-derived guess), an `ebcClassify`/`ebcPathways` client, and a **🏚 Existing-building code
(IEBC scope)** tool in the code-intelligence cluster. Preliminary classification — the AHJ makes the
determination. `test_ebc.py` (16 hand-worked IEBC scenarios + the phasing inference).

## v0.3.309 — Docs + marketing refresh: catch the user-facing surface up to the authoring wave

Non-code release. The README, in-app guide, and GitHub Pages landing had drifted ~14 releases behind
(last refreshed at v0.3.294) and named none of the authoring wave. All three now cover **model undo/redo**,
**SketchUp-style drawing inference**, **sloped-top walls**, **procedural mesh**, the **sandboxed
`execute_ifc_code`** escape hatch, the **site content library** (logistics/furniture/landscaping,
auto-classified), **MEP port-to-port connectivity**, **edition-aware code checks**, **detail callouts**,
the **decision-readiness (RFI-prevention)** audit, the **productivity-rate labour estimate**, and
**field-verified as-built dimensions** — with the new API surface (`/rfi/readiness`, `/mep/connectivity`,
`/estimate/labor*`, `/content/catalog`, `/edit/{undo,redo,history}`, `/authoring/capabilities`). Added a
shareable **current-status page** (`docs/status.html`) that snapshots what the platform does end to end,
and refreshed `docs/marketing-copy.md` with the authoring-stack feature lines. Regenerated the viewer demo
snapshot (`demoData.json`). Competitor-name-free throughout, per the standing directive.

## v0.3.308 — Productivity-rate labour cost + duration estimate (EST-1)

The estimating link from *quantities* to *schedule + 5D cost*. New `productivity.py` holds a
**man-hours-per-unit** rate library (earthworks / concrete / masonry / steel / MEP / finishes) with typical
crew sizes + condition **loading factors** (highrise / remote / summer / congested / night-shift).
`labor_estimate` turns a quantity of work into **man-hours → crew-days → labour cost**; `from_model` derives
a rough takeoff straight from the model (walls → masonry face area, slabs/columns → concrete volume) and runs
it. New `GET /estimate/labor/rates` (catalog) + `GET /projects/{pid}/estimate/labor?loading=&rate=` and a
**💰 Labour estimate** tool showing man-hours / crew-days / cost per activity. Editable benchmarks, labour
only (add materials/equipment/overhead for a full cost). `test_productivity.py`.

## v0.3.307 — Decision-readiness audit: RFI-prevention (RFI-0)

The proactive inverse of the RFI — every RFI is a decision made without the needed information, so this
surfaces the **information gaps a builder would otherwise have to ask about** *before* the set goes out. New
`rfi_prevention.decision_readiness` composes the checks that already ship — the approvability pre-flight
(failed code checks), the Track-D detail-rule validator (elements missing their detail/keynote),
model-hygiene (`model_qa`: orphaned / unenclosed / unnamed / duplicate), and clash coordination (open
clashes) — into one **ranked resolve-before-issue list**, each gap with a category, severity, and a concrete
fix. New `GET /projects/{pid}/rfi/readiness` and a **🚫 Decision-readiness (RFI-prevention)** tool that lists
the gaps and isolates the flagged elements in 3D. A pre-check assist — not a promise of zero RFIs.
`test_rfi_readiness.py`.

## v0.3.306 — Site content library: logistics / furniture / landscaping, auto-classified (CONTENT-1)

Place real-world parts into the **right** IFC place, not as random shapes. New `content.py` catalog maps ~20
categories — **site logistics** (tower/mobile crane, hoist, fencing, sanitary unit, site office, laydown,
gate, dumpster), **furniture** (desk/chair/sofa/table/bed/cabinet), and **landscaping** (tree/shrub/planter/
bollard) — each to its correct IFC class + project phase + classification. New `place_content` recipe authors
an item at an [E,N] point from a supplied detailed mesh **or** a category-sized placeholder box, then sets
the phase (logistics = **temporary**, so it time-phases on the 4D logistics slider) and the classification
(Uniclass/OmniClass). Logistics land as proxies, furniture as `IfcFurniture`, landscaping as
`IfcGeographicElement` (proxy fallback on older schemas). New `GET /content/catalog` + a **🏗 Site content
library** palette tool. Builds on the B4 mesh hatch; content is imported/authored per-asset with license
vetting (the catalog records the intended license tier; geometry is supplied, never bundled unvetted).
`test_content.py`.

## v0.3.305 — Procedural-mesh escape hatch (B4)

Author an element from a **raw triangle mesh** for geometry the parametric recipes can't express. New
`add_mesh_representation` recipe builds an `IfcTriangulatedFaceSet` (Tessellation body) from `verts`
(`[[x,y,z]…]` metres) + `faces` (`[[i,j,k]…]` 0-based), with index/degeneracy validation. GUID-stable,
versioned/undo-able. New **△ Add mesh** tool (JSON input) in the Advanced cluster; also directly callable
by the AI command bar / `execute_ifc_code`. Verified objectively — `test_mesh.py` tessellates a pyramid and
confirms the extents (2×2 base, apex 2 m, ≥6 triangles), and the output round-trips through the real
web-ifc → Fragments converter into a valid fragment.

## v0.3.304 — Sloped-top walls: parapet slope / shed / gable (B3)

Walls can now have a **sloped top**. New `set_wall_slope` recipe rebuilds the selected wall's Body as a
**trapezoidal side profile extruded across the thickness** — a plain `IfcExtrudedAreaSolid` (no boolean, so
every geometry engine renders it), with the top rising from `start_height` (at the wall's start point) to
`end_height`. GUID-stable, versioned/undo-able. New **⟋ Slope wall top** tool (Advanced cluster). Verified
objectively, not by eye: `test_wall_slope.py` tessellates the result (`ifcopenshell.geom`) and confirms the
start end sits at ~2 m and the far end at ~4 m (a real rising slope, base at Z = 0), and the output was
round-tripped through the actual web-ifc → Fragments converter into a valid fragment (it renders). This was
the last item on the Master-Builder order of attack.

## v0.3.303 — Fix: `test_edit_undo` CI failure (read-only `/app`)

The S4 undo test (v0.3.298) failed the CI API gate with `PermissionError: /app` — it drives `/model/blank`,
which writes the source IFC under `IFC_DIR` (defaults to `/app/ifc`, read-only in the container). The test
now points `IFC_DIR` at a writable scratch dir (and cleans it up), per the container-readonly-`/app` gotcha.
Test-only change; no product code affected.

## v0.3.302 — Field-verified as-built dimensions + variance (G2)

Completes the LOD-500 data layer. New `record_asbuilt_dimension` recipe stamps a **field-measured**
dimension on the selection, the **design** value (if given), the **variance** (measured − design), and
whether it's **within tolerance** — into `Massing_AsBuilt​Dim` (`{Dimension}_Measured/_Design/_Variance` +
`WithinTolerance`). `asbuilt_summary` now also reports `with_dimensions` and
`dimensions_out_of_tolerance`, surfaced in the ✅ As-built (LOD 500) tool alongside a measure form. With
G1 (verify) and G3 (manufacturer/serial), the model can carry the full field-verified as-built record for
turnover. `test_lod500.py` extended.

## v0.3.301 — SECURITY: close an RCE escape in the A1 sandbox

An adversarial review of v0.3.300 proved the AST sandbox was escapable to full RCE **when the flag is on**:
exposing the real `ifcopenshell` module let a snippet reach its transitive imports as plain (non-dunder)
attributes — `ifcopenshell.os.system(...)`, `ifcopenshell.api.importlib.import_module('subprocess')`,
`ifcopenshell.api.inspect.builtins.eval(...)`, etc. Fixed by **never exposing a module**: the snippet now
gets a minimal **facade** carrying only the intended authoring callables (`ifcopenshell.api.run`,
`ifcopenshell.guid.new`) — bound functions with no attribute path back to a module. Added an
attribute-name **denylist** (defense-in-depth) that also blocks the `str.format`/`format_map` dunder-read
bypass and `model.wrapped_data`. `test_sandbox.py` now asserts all 12 proven escape payloads are blocked
while the legitimate `ifcopenshell.api.run` authoring path still works. (The feature remains off by default.)

## v0.3.300 — Sandboxed `execute_ifc_code` escape hatch (A1)

The unbounded authoring escape hatch — run a small ifcopenshell snippet against the model for what the fixed
recipe registry can't express. Defense-in-depth, treating this as arbitrary-code territory:
**off by default** (raises unless the operator sets `AEC_ALLOW_IFC_CODE=1`, thereby accepting the risk); an
**AST allowlist** that rejects `import`, `def`/`class`/`lambda`, `while`/`with`/`try`, `del`, decorators,
dunder access (`__class__`/`__globals__`), and reflection/IO builtins (`open`/`eval`/`exec`/`getattr`/
`__import__`/`type`…) before anything runs; and a **curated namespace** exposing only `model`, `ifcopenshell`,
and a small safe builtin set. New `sandbox.py`, an `execute_ifc_code` recipe (runs through the versioned,
undo-able, audited `/edit` path), a `GET /authoring/capabilities` probe, and an **⚡ Run IFC code** tool in
the Advanced cluster. `/edit` now returns clean 403 (disabled) / 400 (rejected) instead of 500.
`test_sandbox.py` covers ~18 rejection cases + the flag gate + a real authoring snippet.

## v0.3.299 — SketchUp-style drawing inference (E1)

Free-hand drawing now lands clean lines automatically. A new `inference.ts` module infers, as you place a
point, an on-axis (±X / ±Z), **parallel**, or **perpendicular** direction from the previous point (and the
previous edge) and snaps the point onto that inference line when the cursor is within ~6° — no need to hold
Shift. A hard geometry-vertex snap always wins, and Shift stays the manual hard ortho-lock. Pure,
unit-tested math (`inference.test.ts`, 7 cases). Builds on the existing endpoint/edge and grid snapping.

## v0.3.298 — Model undo / redo (S4)

Authoring now has a real undo stack. Every `/edit` already wrote a new versioned source IFC and left the
prior versions on disk, so undo is just restoring a prior version + republishing — GUID-stable, so
pins/RFIs/clashes survive. New `edit_history` sidecar stack (no schema change), `POST /edit/undo`,
`POST /edit/redo`, and `GET /edit/history`; the restored path is verified to exist and stay inside the
project's IFC directory. **↶ Undo / ↷ Redo** buttons in the Model tools rail reflect the server-side history
depth and republish on click. A fresh edit invalidates the redo stack. `test_edit_undo.py`. (The
`/edit-preview` ghosting half of S4 already ships.)

## v0.3.297 — MEP port-to-port connectivity + validation (W10-4)

Turns a pile of MEP segments/fittings into a connected logical network. New `connect_mep` recipe wires two
elements **port-to-port** (`IfcRelConnectsPorts`, using the first free port on each; raises when none is
free). New `mep.connectivity` validation report — ports connected vs open, port-to-port link count, and the
**dangling** (floating) elements whose ports are all unconnected — served at `GET /projects/{pid}/mep/
connectivity`. The 🔀 MEP systems tool now shows the connectivity summary, a two-step **Connect** flow (pick
one element → connect to a second), and isolates floating elements in 3D. `test_mep_systems.py` extended.
*Next: flow/sizing psets + coincident-port auto-connect.*

## v0.3.296 — Detail callouts on the plan (D5)

Closes the attach-a-detail → callout-on-the-drawing loop. The plan generator now draws an **NCS-style detail
callout** (a divided circle with a leader) on every element that carries an attached detail drawing
(`IfcRelAssociatesDocument`), plus a **DETAILS legend** keyed to each detail — distinct from the keynote
bubbles (which reference spec/classification codes). `drawing.plan_svg` gains a `details` toggle and returns
a `details` count; the callouts flow through to the issuable SVG sheet automatically. So: attach a detail in
the 🏷 Detailing tool → generate the plan → the referencing callout appears. `test_drawing.py` extended.

## v0.3.295 — Edition-scoped occupant-load factors (CODE-2)

The egress computation is now edition-aware, not just the citations. `egress_analysis`/`egress_from_model`
take an IBC `edition` and apply edition-scoped occupant-load factors — the one well-established Table 1004.5
change: **Business areas are 100 gross ft²/occ in IBC 2012/2015 vs 150 gross in IBC 2018+**. `code_analysis`
resolves the jurisdiction's adopted edition first and threads it in, so a project in a 2015-edition
jurisdiction computes a *higher* occupant load (and required egress width) than the 2021 baseline, exposed
through the existing Jurisdiction field. The egress result carries `code_edition`; the default (no
jurisdiction) keeps the current-edition factor. Facts of law only. `test_code_analysis.py` extended.

## v0.3.294 — Docs, landing page & demo refreshed to the current product

Housekeeping so the outward-facing surfaces match what shipped. The **README**, the **in-app guide**
(`docs/guide.html`), and the **Pages landing** (`docs/index.html`) are reframed around the current
end-to-end capability — model from scratch → generate a permit-ready construction-document set → pre-check
code → hand over field-verified as-built data — with new sections/tutorials for the CD set, code &
permit-readiness, and LOD-500 turnover. Pre-existing competitor comparisons were removed (capabilities are
described directly); interop/connector/standard names kept. The **Pages demo snapshot** (`demoData.json`)
was regenerated against the current API (932 fixtures). The **roadmap** was re-archived: this session's
shipments moved to `roadmap-completed.md`, active roadmap re-prioritized (CODE-2 → D5 → W10-4 → …).

## v0.3.293 — Model Health scorecard gains a Code & permit-readiness lens

The composite **Model Health** scorecard now includes a fifth lens — **Code & permit readiness** — sourced
from the D8 approvability pre-flight (egress, door widths, occupancy classification, substantiated rated
assemblies). It scores by the pre-flight pass rate and headlines the checks still to fix, so the single
"is my project healthy?" number now reflects permit-readiness alongside integrity, ISO-19650 information,
clash coordination, and verified-as-built. Weights rebalanced to include it; the lens shows n/a (excluded
from the mean) when no gating checks apply. `test_model_health.py` updated.

## v0.3.292 — Fix two debug-audit findings in the D6 manual + D8 pre-flight

A post-release debug audit caught two wrong-result bugs (no crashes), now fixed with regression tests:
- **Project manual (D6) missed layer-set materials.** `specmanual._element_materials` (was `_element_material`)
  now resolves an `IfcMaterialLayerSetUsage` → `IfcMaterialLayerSet` → its layer materials (and profile /
  constituent sets + material lists), so a real wall's materials actually reach Part 2 Products instead of
  silently yielding nothing. Returns all distinct names, not one.
- **Approvability (D8) occupancy check always passed.** It counted a space's free-text `LongName` (which our
  own `add_spaces` always sets to "Room NN") as evidence of occupancy classification, so it could never fail.
  It now gates strictly on `Pset_SpaceOccupancyRequirements.OccupancyType`.

## v0.3.291 — Manufacturer / serial for the O&M / turnover layer (G3)

Completes the LOD-500 data layer. New `set_manufacturer_info` recipe stamps the standard IFC
`Pset_ManufacturerTypeInformation` (Manufacturer / ModelLabel / ProductionYear) and
`Pset_ManufacturerOccurrence` (SerialNumber / BarCode) on the selection — the data that round-trips to
COBie and asset/CMMS systems for O&M and turnover. Only non-empty fields are written; GUID-stable; a bad
GUID never aborts the batch. `asbuilt_summary` now also reports `with_manufacturer` / `with_serial` counts,
and the ✅ As-built (LOD 500) tool gains a manufacturer/serial stamp form. `test_lod500.py` extended.

## v0.3.290 — Approvability pre-flight: is the model permit-ready? (D8)

A plan-reviewer pre-flight checklist over the model, mirroring what a reviewer checks first. New
`codecheck.approvability` runs five cited checks — egress capacity (IBC 1005.3), egress door clear width
≥32 in (IBC 1010.1.1 / A117.1), two-exits-where-load>49 (IBC 1006.2), occupancy classification on spaces
(IBC Ch.3), and fire-rated assemblies substantiated by a UL/GA classification or attached detail (IBC Table
721) — returning pass/fail/na/info per check plus a readiness score. New
`GET /projects/{pid}/codecheck/approvability` and a **✅ Approvability pre-flight** viewer tool that lists
the checks and isolates flagged elements in 3D. A pre-check assist — not a certified review or a guarantee
of approval. `test_approvability.py`.

## v0.3.289 — 3-part MasterFormat project manual — the spec book (D6)

Closes the loop from "classify an element + attach its detail" to "a spec section writes itself." New
`specmanual.py` groups the model's elements by their MasterFormat work-result classification into CSI
**divisions → sections**, each framed in SectionFormat 3-part shape: **Part 1 General**, **Part 2 Products**
(the element types + materials actually in that section), **Part 3 Execution** (the installation
instructions attached via `IfcRelAssociatesDocument`, or a manufacturer-instructions fallback). New
`GET /projects/{pid}/spec/manual` (structured) + `/spec/manual.txt` (downloadable outline) and a **📖 Project
manual** viewer tool. A pre-check starting point — the real manual is authored by the spec writer.
`test_specmanual.py`.

## v0.3.288 — Clear the critical dev-dependency advisories (vitest 3, happy-dom 20)

Bumped the two dev/test dependencies carrying critical Dependabot advisories — `vitest` ^2.1.9 → ^3.2.6
(resolved 3.2.7) and `happy-dom` ^15.11.7 → ^20.8.9 (resolved 20.10.6) — clearing 4 critical + several high
alerts. Both are test-only (the runner and its DOM), never shipped to production, so real-world exposure
was low; this is hygiene. Verified the full web test suite (13 files / 79 tests) still passes on the new
majors, plus typecheck + build + bundle budget. (Remaining Dependabot items are transitive build tooling —
`tar`/`esbuild`/`glib` — for a follow-up.)

## v0.3.287 — Harden download filenames (defense-in-depth)

A security pass over this session's new endpoints came back clean; this applies its one hardening note.
The DXF/PDF drawing endpoints interpolate user-supplied `axis`/`direction`/`number`/`sheet` into the
`Content-Disposition` filename. Those are now whitelisted to `[A-Za-z0-9._-]` (`_safe_name`/`_safe_filename`)
so a crafted value can't break out of the filename quoting. Self-reflected only (no cross-user/stored
vector) and the response bodies are inert data files — this is precautionary, not a fix for an exploit.

## v0.3.286 — Edition-aware code analysis: cite the jurisdiction's adopted IBC (CODE-3)

The code-analysis summary now uses CODE-1: pass a `jurisdiction` (US state) and it resolves the adopted
**IBC edition** and names it throughout — the headline badge shows "IBC 2021", the citations read "IBC 2021
Table 506.2 …", and the disclaimer records the code context ("IBC 2021 (CA adoption, as-of 2024)"). With no
jurisdiction it uses the national baseline and prompts for one. The 🏛 Code-analysis tool gains a
**Jurisdiction** field that re-checks edition-aware in place. `GET /codecheck/analysis?jurisdiction=…`. Still
a pre-check assist — verify the edition in force with the AHJ.

## v0.3.285 — Jurisdiction code context: adopted-edition catalog (CODE-1)

The substrate for edition-aware code checking. New `codes.py` encodes only facts of law + published-edition
metadata: the model-code **families** (IBC/IRC/IECC/IFC/IPC/IMC/IEBC/IgCC/A117.1) and their editions (the
I-Codes publish on a fixed 3-year cycle), plus `resolve(jurisdiction)` → the adopted editions for a US
state, falling back to a documented national baseline when not seeded. Every result carries a mandatory
**"verify with the AHJ"** note and an as-of year — the shipped seed is a dated starting point to extend from
authoritative sources, never an authority (adoptions change each cycle and by local amendment). New
`GET /codes/families`, `/codes/adoptions?jurisdiction=…`, `/codes/seeded`, and an **Adopted codes** lookup
in the 🏛 Code-analysis tool. Copyright-safe by design: facts and section numbers only, no code prose. This
unlocks the later edition-aware citation work (thread `code_ctx` through the checks).

## v0.3.284 — Authoring guardrails: reject broken edits before they touch the model (E8)

The reliability edge — a novice can't produce invalid IFC. New `guards.py::precheck` runs params-level,
name-based rules over any recipe: coordinates must be finite [E,N] pairs, a line's endpoints must differ
(no zero-length walls), physical dimensions must be positive and finite, integer counts ≥ 1, LOD-stage in
range, and required host/target references present. **`apply_recipe` now enforces the gate** — a broken
edit raises a clear message and never writes a file (verified against 49 recipe-exercising tests; it
rejects nothing legitimate). Errors block; suspicious-but-legal inputs (an implausibly large dimension →
likely unit slip, a non-standard phase) surface as **warnings**. New `POST /projects/{pid}/edit/precheck`
lets the UI warn *before* committing, and the AI command bar now prechecks each step (blocks on errors,
confirms through warnings). `test_guards.py` covers the rules and the enforcement path.

## v0.3.283 — Progressive-disclosure toolbar: fabrication tools behind an "Advanced" toggle (E4)

Lowering the barrier to entry: the Model tools rail now shows only the everyday authoring + drawing tools
by default (rooms, furnish, types, groups, phasing, query, LOD, as-built, plans/sheets/schedules/sections).
The LOD-350/400 **fabrication + detailing** tools — steel base plates & shear tabs, rebar cages, MEP
fittings, curtain wall, and the detailing/auto-detail tools — tuck behind a **🔧 Advanced fabrication
tools** toggle. A first-time modeler sees a simple toolset; the choice persists in localStorage, so power
users keep their fabrication tools open.

## v0.3.282 — Schedules on an issuable PDF sheet (finishes the CD set)

The computed door/window/room schedules now lay out on an issuable **ARCH-D sheet** (border + titleblock)
and render to PDF — the tabular half of the construction-document set as a submittable sheet, next to the
plan/section/elevation sheets. New `drawing.schedule_pdf` (columns per schedule, row truncation guard),
`GET /drawings/schedule.pdf?kinds=…`, and a **⤓ Schedules sheet (A-601 PDF)** viewer tool. The titleblock
draw was factored into a shared `_titleblock_pdf` helper reused by the plan and schedule sheets. With DXF
(v0.3.281) this completes the near-term CD-set slices.

## v0.3.281 — DXF export for plans, sections & elevations (CAD interchange)

The drawing set now exports to **DXF** so the linework opens in any CAD tool. A hand-written, dependency-free
R12 DXF writer (`dxf.py` — POLYLINE entities, no library, no license exposure) serialises the same
world-placed polylines the SVG views use: `plan_dxf` / `section_dxf` (auto-centred cut) / `elevation_dxf`
on named layers (PLAN / SECTION / ELEVATION). New `GET /drawings/plan.dxf`, `/section.dxf`, `/elevation.dxf`
endpoints and **⤓ DXF** buttons alongside each view in the Sections & elevations tool. `test_dxf.py` covers
the R12 envelope, closed-loop detection, degenerate-skip, and world placement.

## v0.3.280 — Fix: S3 structured-output schema (LLM authoring path) + apply-all recovery

Two follow-ups to the S3 command bar. (1) The plan schema declared each step's `params` as an open
`{type: object}`, which Anthropic's strict structured outputs reject (every object must set
`additionalProperties: false`) — so a keyed request would 400 and silently fall back to the keyword
baseline, meaning Claude multi-step planning never actually ran. `params` is now a JSON **string** the
model fills and `_coerce_params` parses (tolerant of both string and dict, so the keyword path and tests
are unaffected); every object in the schema is closed. (2) **Apply-all** now recovers from a mid-chain
failure: because earlier edits already advance the source IFC but defer their republish to the last step,
a failure part-way used to strand them unpublished — it now republishes what applied and reports
"stopped after N/M steps" instead of leaving the model in a committed-but-unconverted state.

## v0.3.279 — LOD-500 as-built verification (G1)

BIMForum defines LOD 500 as a *field-verified as-built* reliability attribute — with **no** geometric
requirement — so we support it as a data layer over the geometry. New `verify_asbuilt` recipe stamps
elements with `Massing_AsBuilt` (Status=VERIFIED + VerifiedBy / VerifiedDate / Method / Note provenance),
and `asbuilt_summary` reports **LOD-500 readiness** (share of elements field-verified, broken down by
method: field-measure / laser-scan / total-station / photo / submittal / inspection). New
`GET /projects/{pid}/lod500` endpoint and a **✅ As-built verify (LOD 500)** viewer tool — stamp the
selection, watch readiness climb. GUID-stable, round-trips as a Pset. `test_lod500.py` covers the stamp,
method fallback, bad-GUID skipping, and readiness math.

## v0.3.278 — AI command bar S3: Claude multi-step authoring + one-click Apply all

The natural-language command bar ("type what to build") now plans with Claude when an Anthropic API key
is set — a single instruction like *"a 5×4 m room at 0,0"* becomes an ordered **multi-step plan** (four
walls), and *"add three columns along the north wall"* resolves without exact coordinates. New
`nl_ai.plan()` builds the plan against the shared `RECIPE_SPECS` schema and **re-validates every step**
through the same `validate_call` guardrail as the keyword path before it reaches you — the model never
writes anything, never invents GUIDs (host/target elements come from the current selection), and
destructive recipes are withheld from it entirely. No key → the deterministic keyword baseline, unchanged.
Multi-step plans get a **✓ Apply all N steps** button that chains the edits and republishes the model
once instead of per step. The paid path is rate-limited; any LLM hiccup falls back to keyword parsing,
never an error. New `test_nl_ai.py` covers the plan assembly, context-fill, and fallback.

## v0.3.277 — Fix: align room tags & callouts with the world-placed drawing linework

Follow-up to v0.3.276. The bake fix moved section/plan linework into world coordinates, but the two
annotation builders — `space_tags` (room tags) and `element_callouts` (door/window callouts) — still
read element geometry in *local* coordinates, so their label centroids collapsed onto each element's
own origin and no longer sat on the linework (every off-origin room tag stacked at 0,0). Factored the
world-coords setup into a shared `_world_settings()` helper and applied it to both builders, so tags and
callouts land on the elements they label. Regression coverage added to `test_sections.py` (off-origin
model: tags/callouts must fall within the linework bounds, not at the origin).

## v0.3.276 — Sections & elevations in the UI + world-placement fix for all drawings

The section and elevation SVG generators existed server-side but were unreachable — added a **📐 Sections
& elevations** tool to the viewer's drawing rail: cut sections (X–X / Y–Y) and projected N/S/E/W
elevations, true linework from the model geometry. The section cut now **auto-centres** on the model
(`section_svg(offset=None)`) so it lands through the building instead of the world origin — no coordinate
to guess.

**Fix (affects every drawing):** the geometry bake fed the plan/section/elevation/sheet generators
element meshes in *local* coordinates — each element's ObjectPlacement wasn't applied, so anything not
authored at the origin collapsed onto (0,0) and overlapping elements stacked. `bake()` now sets
`use-world-coords`, so all 2D output places elements where they actually are. Plans, sections, elevations,
and composed sheets of any real (off-origin) model are now correct. New `test_sections.py` guards the
auto-centre + world placement.

## v0.3.275 — Fix: code-analysis occupancy group now resolves for every occupancy label

The v0.3.274 code-analysis summary looked up the occupancy group in an exact-match dict keyed on
`"Business"`/`"Assembly"`/…, but the space-mix labels carry qualifiers and synonyms
(`"Assembly (unconcentrated)"`, `"Educational (classroom)"`, `"Industrial"`, `"Parking"`, the
`"Business (assumed)"` default) — so 6 of 13 labels silently fell through to group **"—"**. Replaced the
exact dict with an ordered **substring** matcher (`_occ_group`) so those resolve to A/E/F/S/B correctly;
accessory/utility spaces (no standalone group) still return blank by design. Regression coverage added.

## v0.3.274 — Code analysis: permit-set G-series code summary

The IBC **code-analysis summary** a permit set carries on its G-series code sheet — now computed straight
from the model. `codecheck.code_analysis()` assembles occupancy classification (inferred from the space
mix or set explicitly), construction type, gross area + story count, the **computed occupant load + egress**
(reused from the occupancy/egress pre-check), and the governing sections for allowable area/height
(Table 506.2, §504, §506.3) and element fire ratings (Table 601/602). New `GET /projects/{pid}/codecheck/
analysis` endpoint (occupancy_group / construction_type / sprinklered inputs) and a **🏛 Code analysis**
tool in the viewer's QA rail that lays it out as a code-sheet block. Pre-check assist that cites sections —
verify allowable area with the AHJ; not a certified review.

## v0.3.273 — Security: ReDoS-harden the NL command-bar regexes

CodeQL flagged 5 `py/polynomial-redos` alerts in the natural-language authoring parser (unbounded `\d+` /
`\s*` runs in `nlauthor.py`). Bounded every quantifier (`\d{1,9}(?:\.\d{1,6})?`, `\s{0,6}`) so the parse
is linear on any input — no catastrophic backtracking. Parsing behaviour unchanged (`test_nlauthor.py` green).

## v0.3.272 — Fix: IFC2x3 MEP browser crash + degenerate-input guard

From the post-release debug worktree:

- **IFC2x3 MEP browser crash.** `mep_summary` called `model.by_type("IfcDistributionSystem")`, which *raises*
  on an IFC2x3 model (that class is IFC4+) — and legacy MEP models are commonly IFC2x3. It now degrades to an
  empty result via a schema-safe `_by_type` helper (matches the `energy.py` pattern).
- **Coincident start/end points** in `add_wall`/`add_beam`/`add_rebar`/`add_mep_run`/`add_railing`/
  `add_curtain_wall` produced an opaque "only finite values are allowed" placement crash (zero-length axis).
  They now raise a clear `ValueError("start and end points must differ")`.

Guarded by additions to `test_mep_systems.py` (IFC2x3) and `test_curtainwall.py` (zero length).

## v0.3.271 — Natural-language authoring command bar (the low-barrier way in)

**Type what you want to build.** A new **✨ command bar** at the top of the Author panel turns plain English
into modelling — "add a 3 m wall from 0,0 to 5,0", "put a window in the selected wall", "steel column W14x30
at 6,6", "set LOD 350 on the selection", "add 6 rooms". The instruction is mapped to a **validated plan** of
`{recipe, params}` and shown for **confirmation** — nothing is written until you click Apply, and each step
runs through the normal GUID-stable `/edit` path (audited, undoable). Destructive ops (delete) require a
second confirm.

This is the deterministic **no-API-key baseline** (regex + keyword matching, unit-normalized dimensions
mm/cm/ft/in → metres, coordinate + section/LOD/phase parsing, selection + active-storey context) — so it
works for everyone with zero setup. It's also the foundation (shared `RECIPE_SPECS` table + `validate_call`
guardrail) for the LLM tool-use path next, and the first slice of the AI-authoring moat validated by the
Nonica/Arcol competitor research. Engine `nlauthor.py` (`interpret` / `validate_call` / `RECIPE_SPECS`);
`POST /projects/{id}/ai/author` (interpret-only). `test_nlauthor.py` green.

## v0.3.270 — Wave 11 · B6: curtain-wall systems

Completes the B6 domain-geometry catalog. **🪟 Curtain wall** authors an `IfcCurtainWall` along a line that
**aggregates** a real framing grid: vertical **mullions** + horizontal **transoms** (`IfcMember`, MULLION)
bounding **glazing panels** (`IfcPlate`, CURTAIN_PANEL) on a bays×rows layout — one LOD-350/400 assembly,
contained in the storey, GUID-stable. Oriented to the wall axis; profile dims are unit-scale-correct
(verified identical real sizes on metre **and** millimetre models). Engine `curtainwall.py::add_curtain_wall`;
`add_curtain_wall` recipe + viewer tool. `test_curtainwall.py` green.

## v0.3.269 — Fix: authoring correctness on non-metre models + egress door width

Bug fixes from a parallel correctness-audit worktree (verified against real ifcopenshell):

- **HIGH — profile geometry on millimetre/imported models.** `geometry.add_profile_representation` SI-converts
  only the extrusion *depth*, not the profile — so profile dims must be authored in **file units**
  (metres ÷ unit_scale). `_rect_profile`, `connections._circle`, `steel.i_profile`, `rebar._swept_bar`, and the
  inline builders in `add_spaces`/`add_slab`/`add_mep_run`/`add_rebar`/`add_roof`/`add_covering` wrote raw
  metres — making every wall/column/beam/slab/MEP/rebar **1000× too thin** on a mm model (ifcopenshell's
  default and most imported IFCs). Our own blank models are metre-based (scale=1) so tests never caught it.
  Also fixed `add_rebar_cage` hard-failing ("cover too large") and `add_spaces` double-scaling its placement,
  both consequences on mm models.
- **MED — egress door width always 0.** `codecheck._door_width_m` read `Pset_DoorCommon.Width`, but authored
  doors store width in the `OverallWidth` **attribute** — so `provided_width_in` was 0 and egress adequacy
  meaningless. Now reads `OverallWidth` (unit-scaled).
- **MED — copies re-parented to the wrong storey.** `copy_element` (used by arrays) put every copy in the
  *lowest* storey; now inherits the source element's container.

New `test_unit_scale.py` authors into a forced-millimetre model and asserts column/wall/steel/duct/slab/rebar
carry correct **real** sizes + rebar no longer crashes + egress width > 0. All metre-model tests unchanged
(scale=1 makes every ÷scale a no-op).

## v0.3.268 — Wave 11 · B6 MEP fittings + edge-hardening

**MEP fittings & system browser.** `add_mep_fitting` authors an elbow (`BEND`), tee/cross (`JUNCTION`), or
size change (`TRANSITION`) as an `IfcDuctFitting`/`IfcPipeFitting`/`IfcCableCarrierFitting` at a point — with
the right number of connection **ports** and assignment to a named `IfcDistributionSystem` — the LOD 350/400
detailing that turns loose runs into a real system. A new **🔀 MEP systems** tool browses each
`IfcDistributionSystem` (segment/fitting/terminal counts + a connectivity signal: elements with unconnected
ports, plus anything unassigned), and **🔀 MEP fitting** places a fitting at the last-clicked point. Engine
`edit.py::add_mep_fitting` + `mep.py::mep_summary`; recipe + `GET /mep`. `test_mep_systems.py` green.

**Edge-hardening (parallel bug-audit worktree).** Fixed a real crash — `drawing.sheet_svg` raised
`KeyError('paper')` on an empty model / bogus storey (the empty-geometry branch of `plan_svg` omitted the
`paper`/`inner` keys `sheet_svg` reads); it now composes a border+titleblock sheet instead. Added
`test_wave11_edges.py` — ~30 edge/error-path assertions across all 8 Wave 11 modules (families, groups, rebar,
connections, drawing, detailing, rules, representations): bad-dims/blank-name raises, array-detach invariant,
keynote priority, rule idempotency + untested facets, LOD int-coercion, and the `sheet_svg` regression guard.

## v0.3.267 — Security: CodeQL remediation pass

Hardening from the GitHub CodeQL scan. Genuine fixes:

- **Open redirect (SAML ACS)** — `RelayState` now must be a *same-site absolute path*; protocol-relative
  (`//evil.com`) and backslash (`/\evil.com`) forms — which browsers resolve cross-origin — are rejected.
- **Authenticated arbitrary-file read (federated clash)** — the `disciplines` map may now only *select* from
  the project's own registered model paths (source IFC + appended discipline models); a client can no longer
  point it at an arbitrary server path.
- **Path-traversal defense-in-depth** — a `storage.safe_seg()` whitelist guards every `pid`/`mid` segment used
  to build a filesystem path (upload/publish/models/import), and `LocalBackend` now rejects `..`/absolute/NUL
  keys up front + requires the resolved path to stay under the storage root (`is_relative_to`).
- **ReDoS (SCIM filter)** — the `userName eq "…"` parser drops the ambiguous `\s*…\s*` and uses a bounded
  `[^"]*`, eliminating catastrophic backtracking.
- **DOM-XSS / sanitization** — escape the user-influenced label in the place-family status line; make the nav
  label escape global (`/&/g` + `<`).
- **Stack-trace exposure** — the readiness probe logs the DB error server-side and returns a generic
  "database unavailable" instead of the exception text.
- **Least-privilege CI** — `permissions: contents: read` added to the CI, lockfile, and Rust workflows.

Remaining CodeQL alerts are triaged false-positives (HMAC-SHA256 *token signing* — passwords use
`pbkdf2_sha256`; the signed-token cookie; the intentional admin-only **read-only** SQL console; the trusted-
HTML `resultNote` helper whose callers `escapeHtml` untrusted data; `DOMParser` XML that is never injected;
a `blob:` object URL) and are dismissed with justification.

## v0.3.266 — Wave 11 · B6: rebar cages + research-inbox roadmap

**Reinforcement detailing (LOD 400).** A new **🪝 Rebar cage** tool builds a real reinforcement cage in the
selected concrete column: **4 longitudinal corner bars + stirrups** at a spacing, offset by concrete cover,
as **swept-disk `IfcReinforcingBar`s** (a disk of the bar radius swept along its centreline — the correct way
to model reinforcement; straight for the bars, closed-rectangle for the ties), grouped with the column into an
`IfcElementAssembly`. Engine `rebar.py::add_rebar_cage`; `add_rebar_cage` recipe. `test_rebar.py` green.

**Roadmap — future research inbox.** Folded a 6-source research round (building codes, Unreal, and the
arcol/atomatiq/nonica competitor scan) into a new **🔮 Future** section as parked items: a copyright-safe
**jurisdiction-aware building-code library** (own the rules/facts + deep-link; license prose later), **Unreal
as an optional paid viz bridge only** (glTF export + three.js PBR are the on-mission wins), and competitor-
informed items led by an **MCP server over our edit-recipe engine** (validates Track A), real-time
multiplayer, and auto site/zoning ingestion.

## v0.3.265 — Wave 11 · B6: structural steel connections (LOD 350/400)

Bare steel members become **fabrication assemblies.** Two connection recipes turn LOD-300 members into
LOD-350/400 shop assemblies, on the selected element:

- **🔩 Base plate (steel column)** — an `IfcPlate` base plate + up to 4 anchor bolts (`IfcMechanicalFastener`,
  ANCHORBOLT) authored under the column, then grouped **with the column** into an `IfcElementAssembly`.
- **🔩 Shear tab (steel beam)** — a shear-tab plate + bolts at the beam end, assembled with the beam (a simple
  beam-to-column shear connection).

Each is real IFC geometry, GUID-stable, sized/placed from the member's own placement. This is the first
domain-catalog slice of Track B6 (steel connections → rebar cages → MEP fittings → curtain-wall). Engine
`connections.py` (`add_base_plate` / `add_shear_tab`); `add_base_plate` / `add_shear_tab` recipes.
`test_steel_connections.py` green.

## v0.3.264 — Wave 11 · C4: computed schedules (door / window / room)

The tabular half of a CD set — **schedules computed straight from the model.** A new **📋 Schedules** tool
lists the **door**, **window**, and **room** schedules (marks, widths/heights, types, levels, areas), pulling
values directly from the elements (door/window `OverallWidth`/`OverallHeight`, space `NetFloorArea`, the
containing level). Each is also a standalone SVG table for a schedule sheet. Engine `drawing.py::schedules` /
`schedule_svg`; `GET /projects/{id}/drawings/schedules` (JSON) + `/drawings/schedule.svg?kind=doors|windows|rooms`.
`test_drawing.py` extended (door 0.90 m / window 1.50 m captured, table SVG with header + grid, bad-kind 400).

## v0.3.263 — Wave 11 · C3b: sheet PDF export (the submittable deliverable)

**The payoff of the whole chain: a PDF you can submit to the AHJ.** A new **⤓ Sheet PDF (A-101)** tool renders
the issuable sheet — ARCH-D border + titleblock + plan **poché** + overall dimensions + keynote legend —
**directly to PDF** via `reportlab` (BSD, already a dependency; no SVG→PDF converter, no AGPL). Everything on
the sheet comes from the model: geometry from the authored profiles, keynotes from the Track-D spec codes.

Model → author → auto-detail (IBC flashing rules) → **PDF construction sheet**, all in the browser, offline,
GUID-stable, no Revit/Autodesk. Engine `drawing.py::sheet_pdf`; `GET /projects/{id}/drawings/sheet.pdf`.
`test_drawing.py` verifies valid PDF bytes (`%PDF`/`%%EOF`, non-trivial size, empty-storey safety). Next:
computed schedules on the sheet, sections/elevations, per-GUID cache.

## v0.3.262 — Wave 11 · C3: issuable sheets + titleblock

The plan becomes a **sheet you can issue.** A new **📄 Issue sheet (A-101)** tool composes an **ARCH-D
(36×24″) sheet**: a border, a **titleblock** (MASSING mark, project name, sheet title, sheet number, scale,
north arrow), and the plan placed in a **scaled viewport** (aspect-preserving) inside the drawing area. The
sheet title/number track the active level. This is the construction-document deliverable format — the same
sheet the door/window/room schedules and detail callouts will land on next.

Engine `drawing.py::sheet_svg` (plan refactored to expose its inner content + paper size for composition);
`GET /projects/{id}/drawings/sheet.svg?storey=&scale=&number=&title=`. `test_drawing.py` extended. Pure SVG,
no new deps; **PDF/DXF export is the next C-slice** (permissive svglib+reportlab — reportlab is already
present, BSD-licensed).

## v0.3.261 — Wave 11 · C2: dimensions & keynotes on the plan

The plan drawing now **reads the model's intelligence.** `plan_svg` gains two layers:

- **Dimensions** — overall width &amp; height dimension strings (witness ticks + metric text), so the plan
  carries real measurements, not just linework.
- **Keynotes** — every drawn element carrying a **Track-D classification code** (MasterFormat/UniFormat) gets
  a numbered keynote bubble, and a **keynote legend** maps each number to its code + title. The keynotes are
  generated *directly from the codes the Auto-detail rule engine attaches* — so the loop closes: place a wall
  → it gets a spec code → the plan shows the keynote and legends it. Both layers toggle off.

The 🖨 Generate plan tool automatically produces the richer sheet (dimensions + keynote legend). Pure
computation from the authored geometry + classifications — no geometry kernel. `test_drawing.py` extended
(dimension strings, keynote bubbles + legend from 04 20 00 / 05 12 00). Next C-slices: sections/elevations,
sheets + titleblocks, PDF/DXF.

## v0.3.260 — Wave 11 · C1: plan-drawing generator (SVG)

The first slice of the **construction-document set** — generate a schematic **plan drawing** (SVG) straight
from the model. A new **🖨 Generate plan (SVG)** tool (Grid &amp; Levels) opens a 1:100 plan of the active level:
walls/columns/slabs/roofs/spaces drawn as **class-styled poché** (a CSS class per IFC class controls
linework/fill), correctly scaled to paper millimetres with a viewBox and a title.

Because our geometry path is web-ifc→Fragments (ifcopenshell's OpenCASCADE engine produces no mesh here), the
generator takes the research-recommended optimization: it derives each footprint **directly from the authored
extruded-profile geometry** (profile polygon × placement × solid position) — deterministic, no geometry kernel.
Engine `drawing.py` (`plan_svg`); `GET /projects/{id}/drawings/plan.svg?storey=&scale=`. `test_drawing.py`
green. Next C-slices layer on dimensions, keynotes (from the Track-D codes), sheets/titleblocks and PDF/DXF.

## v0.3.259 — Wave 11 · D3+D7: the detail-rule engine + IBC window-flashing case

The brain that turns model state into construction-document content — and the headline worked case. A new
**✨ Auto-detail (rules)** tool (Grid &amp; Levels) runs an **IDS-shaped condition→content rule library** over
the model:

- **Rules** = an `applies` block (IFC entity, predefined type, a property on the element, or a
  relationship-context facet like "fills an opening in an **exterior** wall") + an `attach` block (the
  content bundle — classification codes + detail/instruction documents), written through the Track-D
  carriers, GUID-stable.
- **The worked case (D7):** a window in an exterior wall auto-gets the **IBC 2021 §1404.4 / ASTM E2112 /
  AAMA 711 flashing detail** (sill-pan → jamb → head shingle-lap sequence, as an installation instruction)
  + **MasterFormat 08 51 00** + **UniFormat B2020**. An interior-wall window gets nothing. Exterior doors get
  their sill-pan/jamb flashing (08 11 00); fire-rated walls get an assembly keynote (09 21 16, tag UL/GA no.).
- **The same rules validate as IDS QA** — a missing-keynote pre-flight lists elements that match a rule but
  lack their required code (author-time attach, QA-time check). Shown before/after in the tool.

Engine `rules.py` (`apply_rules` / `validate_rules` + seed rule library); `apply_detailing_rules` recipe +
`GET /detailing/rules/validate`. `test_rules.py` green. Pure ifcopenshell; code citations are facts.

## v0.3.258 — Wave 11 · Track D carrier layer: codes & detail documents

The join layer between the model and the construction documents — attach **keynote/spec codes** and
**detail/instruction documents** to elements, IFC-natively. A new **🏷 Detailing** tool (Grid &amp; Levels)
on the selected element:

- **Classification codes** — `IfcRelAssociatesClassification` for **UniFormat** (element → keynote),
  **MasterFormat** (work result → spec section), **OmniClass** (product), Uniclass. One element carries
  all three; each code is the join key a keynote, a schedule row and a spec section share.
- **Documents** — `IfcRelAssociatesDocument` → `IfcDocumentReference` → `IfcDocumentInformation` attaches a
  **detail drawing + installation instruction** (name, detail no. like `A-541/3`, URI). Deduped by
  identification so re-attaching a shared detail reuses one record.
- A **detailing inspector** reads an element's codes + documents back.

This is exactly what the (next) detail-rule engine writes when "exterior window → IBC §1404.4 flashing
detail + ASTM E2112 instruction + spec 08 51 00" fires, and what keynote/schedule/spec/drawing generation
will read. Engine `detailing.py` (`classify` / `attach_document` / `element_detailing`); recipes +
`GET /detailing/{guid}`. `test_detailing.py` green.

## v0.3.257 — Wave 11 · B2: parametric door & window generators

Doors and windows now get **real lining, frame and panel geometry** from IfcOpenShell's built-in parametric
generators (`geometry.add_door_representation` / `add_window_representation`) instead of a single flat box
proxy — a LOD 300→350 jump for near-zero geometry code. Every existing **◧ Add door** / **◨ Add window** tool
benefits automatically (parametric is the default); the recipes also accept an `operation` type
(`SINGLE_SWING_LEFT`, `DOUBLE_DOOR_SINGLE_SWING`, window `SINGLE_PANEL`, …). Lining depth is sized from the
host wall's thickness. The host is properly voided (`IfcRelVoidsElement`) and the door/window fills the
opening (`IfcRelFillsElement`); a generator failure falls back to the box proxy so authoring never breaks.
This is the real door/window geometry that the Wave 11 detail-rule engine will hang the IBC/ASTM flashing
detail + keynote + spec off. Engine in `edit.py`; `test_openings.py` green.

## v0.3.256 — Wave 11 · F0: the representation/LOD spine (foundation)

The architectural foundation the rest of Wave 11 hangs off — **one GUID-stable element that can carry
several view-keyed representations, plus an explicit LOD stage**. A new **📶 Level of Development** tool
(Grid &amp; Levels):

- **⚙ Establish drawing contexts** — `ensure_contexts` finds-or-creates the full view-keyed context tree:
  Model + **Plan** roots and the `Body`/`Axis`/`Box`/`Annotation`/`FootPrint` subcontexts (each tagged by
  `TargetView`) that construction-drawing generation and coarse↔fine display need. Idempotent.
- **LOD stage** — tag the selected element or a saved selection set **100 → 500** (`Pset_MassingLOD.Stage`).
  LOD is element *maturity*, not a geometry mode: the same GUID-stable element carries it as its geometry
  and data are refined. Advancing updates in place (no duplicate pset); a distribution overview shows the
  model's maturity at a glance.

Engine `representations.py` (`ensure_contexts` / `set_lod` / `lod_summary`); `ensure_contexts` + `set_lod`
recipes + `GET /lod`. `test_representations.py` green. This is track **F0** — everything downstream (parametric
door/window generators, the SVG drawing generator, detail-follows-LOD) keys off this spine.

## v0.3.255 — Wave 11 · power selection (IfcOpenShell selector DSL)

The first foundation piece of Wave 11 (LOD-400/500 authoring): a **🔎 Query (selector)** tool that runs the
IfcOpenShell **selector query language** over the model — `IfcWall` · `IfcWall, IfcDoor` ·
`IfcWall, Pset_WallCommon.FireRating=2HR` · `IfcElement, material=concrete`. Matches can be **isolated in 3D**
or **saved as a reusable selection set**. This is the power-selection primitive that bulk edits, schedule
scoping, and (next) rule-driven detail/spec attachment all build on. Engine `query_elements` in `edit.py`;
`GET /projects/{id}/query`. `test_selector.py` green (class, multi-class union, pset-value filter, limit
truncation, invalid-query 400).

## v0.3.254 — Wave 10 · W10-8: element phasing

The renovation / demolition-sequencing dimension needed for as-built and phased models. A new **🕐 Phasing**
tool (Grid &amp; Levels) tags elements **new · existing · demolish · temporary** — writing the widely-used
`Massing_Phasing.Status` code (NEW/EXISTING/DEMOLISH/TEMPORARY) so it colours, filters, and round-trips:

- Tag the selected element, or bulk-tag any saved selection set, from a one-click phase palette.
- A phase-distribution overview (counts + bars per status, plus unphased).
- **Isolate a phase in 3D** — pick a status to isolate just those elements.

Re-tagging updates the status in place (no duplicate pset); stale GUIDs are skipped; all GUID-stable. Engine
`set_phase` / `phase_summary` in `edit.py`; `set_phase` recipe + `GET /phasing`. `test_phasing.py` green.
(Design options reuse the W9-3 IFC5 property-override layers already shipped.)

## v0.3.253 — Wave 10 · W10-3: groups, assemblies & arrays

Three IFC-native ways to compose placed elements, all GUID-stable, via a new **🧩 Groups &amp; arrays** tool
(Grid &amp; Levels):

- **Group** (`IfcGroup`) — a named, non-geometric *set* of elements (a saved selection / system you can name,
  isolate, schedule). Members keep their own spatial containers; re-using a name adds to the group. Build one
  from any saved selection set; right-click an existing group to dissolve it (`ungroup`, members untouched).
- **Assembly** (`IfcElementAssembly`) — a real *part-of* whole: a named element that aggregates its parts
  (a braced frame, a curtain-wall unit, a pre-cast panel). The assembly is spatially contained; its parts hang
  under it via `IfcRelAggregates`.
- **Array** — rectangular parametric duplication: copy the selected element on an nx × ny grid at a fixed
  pitch (a bay of columns, a run of fixtures) in one action. Arrayed copies are independent occurrences —
  they don't silently swell the source's group or double-aggregate its assembly.

Existing groups/assemblies are listed with member counts; clicking one **isolates its members** in 3D. Engine
in `groups.py`; `create_group` / `create_assembly` / `array_element` / `ungroup` recipes + `GET /groups` and
`/groups/{guid}` inspectors. `test_groups.py` covers the relationships, inspectors, and recipe path.

## v0.3.252 — Wave 10 · W10-1: first-class type/family system

The box-only type path is now a real **family type system** — the Revit "type properties" surface, IFC-native.
A new **🧱 Family types** tool (Grid &amp; Levels) browses every `IfcTypeProduct` with its placed-occurrence
count, and lets you:

- **Create a custom type** — any type class, an optional sized box, a PredefinedType, and type-level
  property sets (`create_type`). Idempotent by (class, name).
- **Edit a type's size** — and the change flows to **every placed occurrence at once**. Occurrences share
  the type's `RepresentationMap` (via `IfcMappedItem`), so `edit_type_params` mutates the one box solid in
  place — GUID-stable, no re-placement, no lost pins/RFIs.
- **Assign a material layer set** — an ordered `IfcMaterialLayerSet` (name + thickness per layer) that
  occurrences inherit through the type (`assign_material_set`); re-assigning replaces cleanly.
- **Inspect** a type — class, PredefinedType, box dims, type Psets, material layers, and its occurrences.

All three edits run through the versioned, GUID-stable `/edit` recipe path and reconvert. This deepens the
existing `families.ensure_type`/`place_type` spine (shared box-representation builder) into the foundation the
rest of Wave 10 (parametric generators, groups, MEP systems, schedules) stands on.

## v0.3.251 — Wave 9 · W9-2b: round-trip code findings to BCF

The computed occupancy/egress findings can now become **trackable BCF issues** — a "📌 Promote to BCF
issues" button in the Occupancy &amp; egress result turns each below-min door, egress shortfall, and
two-exits-required space into a `codecheck` **BCF topic** (anchored at the element / building, so it shows
in the Issues panel and round-trips via `.bcfzip` with other openBIM tools). Idempotent — re-running a
review replaces the prior code findings rather than piling up. `POST /codecheck/egress/bcf`. Verified
live: an egress-shortfall finding becomes an anchored topic in the Issues list. (Completes W9-2's
"round-trip to BCF"; fire-separation between occupancies still needs space-boundary geometry and stays a
follow-up.)

## v0.3.250 — Wave 9 · W9-5: site logistics on the 4D timeline (first step)

SYNCHRO-style **site logistics** without leaving openBIM. New **🏗 Site logistics** tool places temporary
construction resources — cranes (with a reach ring), hoists, laydown yards, gates, fencing, haul routes,
trailers, parking — in project coordinates, each with a **schedule window**. They render as lightweight
3D glyphs and **time-phase on the timeline**: pick a date and only the resources active then are shown,
so the site plan becomes a constructability + safety rehearsal. `logistics.py` (`state_at` + `summary`) +
`Project.site_logistics` + `/logistics` (GET/PUT) + `/logistics/state` + a `LogisticsOverlay` +
`test_logistics.py`. Verified live: 3 resources → all active mid-schedule, only the open-ended gate after
the crane/laydown windows close; overlay renders glyphs + time-phases visibility. (The static, time-phased
first step; smooth **motion along paths** + swept crane-reach clash is the deferred follow-up.)

## v0.3.249 — Wave 9 · W9-6: generative fit-out (auto-furnish)

Generative design extends from massing into **fit-out**. New **🪑 Furnish spaces** tool (Tools ▸ Grid &
Levels) grids real furniture (`IfcFurnishingElement`) into every `IfcSpace`'s footprint with aisle
clearances — pick a template (desk / table / bed / sofa) and a per-room cap (0 = fill the footprint). It
reads each room's actual geometry, places items on a clearance-aware grid, and contains them in the right
storey, so the furniture is real openBIM that flows into QTO / BOM / COBie. `furnish_spaces` recipe +
`test_fitout.py`. Verified live: a blank 2-storey model → 8 rooms → 432 desks placed end-to-end. (The
headcount-program office space-planning generator is a documented follow-up.)

## v0.3.248 — Wave 9 · W9-4: semantic model graph (v1)

The property index answers attribute lookups ("this door's width"); it can't answer **relational**
questions. New **🕸 Related elements** tool builds a typed graph straight from the model's own IFC
relationships (`contained_in` · `aggregates` · `bounds` · `has_opening` · `fills` · `serves`) and, for
the selected element, returns its **multi-hop neighbourhood with cited relationship paths** — e.g. a wall
→ its level → everything else on that level. Click any related element to select it in 3D. `graph.py`
(`build` + `neighbors`) + `/graph` (stats) + `/graph/neighbors` + `test_graph.py`. Verified live: 117
nodes / 116 edges on a federated model; a wall reaches 38 related elements within two hops. (First,
model-half slice — spec/code-document ingestion and NL→graph query are a deliberate follow-up.)

## v0.3.247 — Wave 9 · W9-3: IFC5-style property-override layers

Brings IFC5's compositional model to the data layer **today**, without waiting on the upstream geometry
alpha. New **🧬 Property layers** tool: build an ordered stack of named, non-destructive **overlay
layers** (base → discipline → coordination → override), each carrying `{guid, pset, prop, value}`
overrides added from the selected element. They **compose over the model without mutating the IFC** — the
strongest enabled layer wins, disagreements surface as **conflicts** (the data-world twin of clash
detection, with provenance and both values), and **Resolve** shows the effective value + what it
overrides. **Bake** flattens the composition into a new GUID-stable IFC version (so pins/RFIs/clashes
survive) and republishes. `layers.py` engine + `Project.prop_layers` column + `/layers` (GET/PUT),
`/layers/resolve`, `/layers/bake` + an `apply_layers` recipe + `test_layers.py`. Verified live: a two-layer
FireRating conflict resolves to the coordination layer's "2HR" and bakes onto the wall.

## v0.3.246 — Wave 9 · W9-2: occupancy load + egress capacity (computed)

Code-checking goes from *presence* to *computation*. New **🏛 Occupancy & egress** tool (Coordination &
QA) computes, straight from the model's IfcSpaces + IfcDoors: **occupant load** per space (IBC 1004.5
area-per-occupant factors by occupancy — Business 1:150, Assembly 1:15, Residential 1:200, …) and the
building total; **required egress width** (occupant load × 0.15 in, IBC 1005.3) vs the **provided**
egress-door width, with an adequate / short verdict; a **32 in minimum clear door** check (IBC 1010.1.1)
with click-to-isolate; and a **two-exits-when-load->49** flag (IBC 1006.2), all with cited sections. It's
a **pre-check / design assist**, not a certified review (thresholds are encoded, not ICC prose; travel
distance is out of scope). `codecheck.egress_analysis` + `codecheck.egress_from_model` +
`/codecheck/egress` + `test_codecheck.py` extended. Verified live on a 40-space model (344 occupants,
required 51.6 in egress).

## v0.3.245 — Wave 9 · W9-1: property mapping / normalization

The missing **transform** verb between IDS-validate and COBie-export. Federated models name the same
concept differently (`Pset_WallCommon.FireRating` vs a vendor's `Fire_Rating`); IDS flags the mismatch
but nothing fixed it. New **🔧 Normalize properties** tool (Coordination & QA): **detect** every
pset/property actually on the model (with counts + samples), build remap **rules** (source Pset.Prop →
target Pset.Prop, with type coercion and move/copy semantics), **preview** the match counts (dry-run),
then **apply** — a GUID-stable `map_properties` edit recipe rewrites the IFC and republishes, so pins /
RFIs / clashes survive. `propmap.py` engine + `/propmap/detect` + `/propmap/plan` endpoints +
`test_propmap.py`. Verified live: `Pset_WallCommon.ThicknessMm` → `Qto_WallBaseQuantities.Width` across
12 walls (source removed, target written, GUIDs preserved). First item of the Wave 9 research scan.

## v0.3.244 — Mobile UX polish (phone-viewport touch targets + nav)

Tuned the header for phones (≤560px): the workspace switcher becomes its own **horizontally-scrollable
row** (five tabs no longer wrap onto two cramped lines), header controls get **tappable ~36–40px touch
targets** (were 22–28px), and the ~200px project-name switcher is **clipped with an ellipsis** so the
project actions pack onto one line. Net: fewer, bigger, easier-to-hit controls and a cleaner nav — the
topbar drops from six cramped rows to five tappable ones, with no horizontal overflow. The verifiable
web/PWA slice of the mobile track (native iOS/Android builds still need a macOS+Xcode / Android-SDK CI
pipeline — see docs/mobile.md).

## v0.3.243 — RVT→IFC (APS) bridge hardening

The paid Autodesk Revit→IFC bridge is hardened: the `/import/rvt` endpoint now **validates input before
the cost gate** — a non-`.rvt` file or an empty upload is rejected with a 400 rather than proceeding
toward a billed conversion — and a new **`test_aps.py`** locks the full gate order (501 bridge-off →
400 wrong-type → 402 unconfirmed-cost → 400 empty → 502 stub-activity). The conversion itself remains a
correctly-gated stub: it can't be implemented generically (the Design Automation WorkItem arguments
depend on the operator's provisioned Activity), so it raises a clear "provision your Activity" error
instead of faking output. The free path (export IFC from Revit, or the pyRevit **Publish to Massing**
button) stays the recommended route.

## v0.3.242 — Command-center density toggle (compact / comfortable)

The role home dashboards (GC executive band, Developer/Finance/Design command centers) get a
**⊞ Comfortable / ⊟ Compact** toggle. Compact tightens card padding, grid gaps and KPI type so more of
the dashboard fits on one screen — no information is removed, just the whitespace. The choice persists
globally (a personal viewing preference, like the per-stage nav collapse memory). Clears the last
open item in the roadmap's UX/nav-density bucket.

## v0.3.241 — Modeling program, phase 5: edit-in-place (drag-to-move gizmo)

Elements can now be **moved by dragging**, not just by typing an offset. Turn on **Edit in place** (◈
in the model toolbar), select an element, and a Blender/Revit-style **transform gizmo** appears on it
with X / Y / Z handles; a translucent amber **ghost box** follows the drag for instant feedback, and a
live ΔE / ΔN / ΔZ readout shows the move. On release the world-space delta is mapped to the GUID-stable
`move_element` recipe and the model republishes — so the moved element keeps its identity and every link
(RFIs, issues, verifications) to it survives. Grid-snap applies to the drag; the gizmo re-attaches to the
element after the move so you can nudge it again. Camera orbit is suspended while a handle is dragged.

Verified live against the loaded federated model: the gizmo constructs, attaches its ghost, cleans up on
hide/dispose, and the world→recipe axis remap is correct (Δx→E, −Δz→N, Δy→Z). This completes the
in-browser modeling initiative's tracked backlog (P1–P6 + model browser, manage levels, selection sets,
and edit-in-place). Stretch/resize of parametric geometry remains a future enhancement.

## v0.3.240 — Modeling program: manage levels + named selection sets

Two model-management tools land in the rail. **Manage levels** (Tools ▸ Grid & Levels) lists every
storey with editable **name** and **elevation** fields — Save re-authors the IFC through the GUID-stable
`rename_storey` / `set_storey_elevation` recipes and republishes, so levels are finally editable, not
just addable. The storey listing now carries each level's **GUID** so edits target the right storey.

**Named selection sets** (Layers panel, the saved-search-set pattern) let you save a
search — by name, IFC class, type, discipline, or level — as a named set and **isolate** it in one click;
"Show all" clears the isolation. Sets persist per-project in the browser (a personal view aid, they never
touch the model). Verified live on a 108-element federated model: a "structural" set resolves to 75
elements, all 75 map to loaded fragment geometry and isolate, and show-all restores visibility.

## v0.3.239 — Modeling program: model-browser groupings + search

The model tree is now a proper **model browser**. A toolbar adds a **group-by** switch — **By level**
(the spatial default), **By discipline** (A/S/M/P/E/FP, using the index's own discipline classification
with an IFC-class fallback), **By IFC class**, and **By type / family** (instances under their type, the
Revit Project Browser view) — and a **search box** that filters every leaf by name, GUID, class, type,
or discipline across all groups, auto-expanding the branches that match so hits are visible without
hunting. Each group header shows its element count; clicking a leaf still selects by GUID.

Verified live against a 108-element federated model: all four groupings render with correct counts
(Structural 75 · Mechanical 24 · Plumbing 6 · General 3), searching "duct" narrows to the 6 matching
segments and auto-expands, clearing restores the full tree, and leaf clicks fire the GUID selection.

## v0.3.238 — Modeling program, phase 6d: docked Properties panel (Revit-style)

Properties used to appear in a **floating** aside on selection; it's now a **docked rail panel** — its own
📋 **Props** toggle in the Author cluster — the way Revit's Properties palette works. The panel leads with a
**Revit-style identity header**: the element name, its **Type** (the family/type it's an instance of), and
its class + level, above the instance parameters and property sets (attributes / quantities / editable
Psets / classification, all unchanged). When nothing is selected it shows a clear "select an element" prompt.
Esc / the ✕ clears the selection.

Verified live: the Props toggle appears in the Navigate / Author / Coordinate rail, the panel docks and
shows its empty-state, no console errors. Completes the rail's Author cluster (Tools/Draft + Properties).
Part of the left-rail redesign; the model-browser groupings, level rename, selection sets, and edit-in-place
are still open (see the roadmap).

## v0.3.237 — Modeling program, phase 6c: cluster the rail Navigate / Author / Coordinate

The left rail's toggles are now grouped into the three workflow clusters standard across BIM authoring
and coordination tools: **Navigate** (Tree · Layers) · **Author** (Tools) · **Coordinate** (Clash ·
Issues), with a subtle divider/label between them (a thin rule in icon mode, the cluster name when the rail
is expanded). Each toggle's aria-label is prefixed with its cluster for screen readers. This completes the
core of the rail redesign — the model workspace now reads as a modeling+coordination cockpit rather than a
flat list of panels. Verified live: the three cluster labels render and grouping is correct.

## v0.3.236 — Modeling program, phase 6b: a dedicated Clash & coordination toggle

The clash/coordination engine was genuinely strong but **buried** inside a "Coordination & QA" accordion in
the Tools panel. It's now a **first-class rail toggle** (💥 Clash), modeled on Autodesk Model Coordination —
the left rail is now Tree · Layers · Tools · **Clash** · Issues.

The panel surfaces tools that already ship: **Run clash — all disciplines** (federated cross-discipline
across the layered models, with coordination KPIs — new / active / resolved / % reduction), a
**single-model check** (structure ✕ MEP/walls) for a model without appended disciplines, a **clash list**
where clicking a clash selects + zooms to it in 3D, **Coordination metrics** (open/closed, resolution rate,
by-discipline-pair, by-severity, reappearance), and **Open in Issues (BCF)** — every clash promotes to a
tracked issue. Backed by `/clash`, `/clash/federated`, `/clash/metrics`.

Verified live end-to-end: the Clash toggle appears, the panel builds, and a single-model check on a
framed+cored model found **1,422 clashes and created 200 BCF issues**. Phase 6b of the left-rail redesign;
next: a docked Properties panel (Revit-style type/instance) and Navigate/Author/Coordinate icon clustering.

## v0.3.235 — Modeling program, phase 6a: cut the duplicative rail sections

Starting the left-rail redesign (a modeling+coordination cockpit, grounded in how established BIM
authoring and markup tools lay out their panels). The Model workspace's "Tools" panel had become an
11-section dumping ground, four sections of which **re-plotted whole other workspaces**: Cost/Pay Apps,
Schedule, Drawings (2D), and Energy & MEP. A modeler coordinating geometry shouldn't scroll past
pay-app tables to reach a tool.

Removed those four from the model rail — and deleted ~700 lines of their now-duplicate builder code — leaving
a compact **deep-link row** (💰 Cost → Construction · 📅 Schedule → Construction · 📐 Drawings → Drawings ·
⚡ Energy → Design) so they're one click away without cluttering the modeling surface. Nothing is lost from
the product; each still owns its real workspace. The rail now keeps only model-native tools: the Draft
authoring palette, Grid & Levels, Working origin, Models (federation), round-trip authoring, Coordination &
QA, and Exports.

Next in the redesign: a dedicated **Clash** toggle (surfacing the existing clash/coordination engine), a
docked **Properties** panel (Revit-style type/instance split), and re-clustering the rail icons
Navigate / Author / Coordinate.

## v0.3.234 — Modeling program, phase 3: author rooms/spaces

The backend `add_spaces` recipe (grid IfcSpace rooms over each floor's footprint) had no UI — you could
author walls and columns but not the **rooms** that drive the space schedule, COBie, gbXML, and area
take-offs. Added an **"➕ Add rooms / spaces"** button to the Grid & Levels section (next to the existing
"➕ Add level"): pick rooms-per-floor + ceiling height and it authors a real space schedule into the model.
Verified live: `add_spaces` authored 8 IfcSpace rooms (4 per floor × 2 floors) on a generated shell. With
level-add already present, the datum/space authoring gap the modeling audit flagged is now covered in the
UI. (Level rename / set-elevation deferred — they need per-storey GUID plumbing.) Phase 3 of the modeling
upgrade; next: edit-in-place (drag/stretch).

## v0.3.233 — Modeling program, phase 4: author-ready starting templates

The old sample models were three static `.frag` files you could only *look at* — they load without a
project, so authoring is impossible on them. The "New model from scratch" flow now opens a **template
picker** with four **author-ready** starting points, each opening as a real, editable IFC project in the
Model workspace with the Draft tools ready:

- **▦ Blank canvas** — 3 levels + a ground datum; draw everything from scratch.
- **🏢 Office bay** — a small framed structural bay (columns + beams + envelope) over 3 levels.
- **🏠 Residential floor** — one floor, double-loaded corridor with unit demising walls.
- **🏭 Warehouse shell** — a large single-storey enclosed clear-span shed to fit out.

Blank uses `…/model/blank` (P1); the rest are presets through the existing massing generator, so they
produce real geometry you then edit — not a locked demo. The picker is an accessible dialog (focus-trapped,
Esc). Verified live: the picker shows all four; the office-bay template generates a published, framed
3-storey editable model in ~1 s. (The static School/BasicHouse samples stay in the Open menu as view-only
reference.) Phase 4 of the modeling upgrade; next: grid/level/space authoring UI and edit-in-place.

## v0.3.232 — Modeling program, phase 2: remove the redundant authoring buttons

Killing the "excess buttons" from the audit. The viewer toolbar had **two ways to place the same element** —
the parameter-driven, snapping, per-level **Draft panel** (the real one) *and* an older click-to-place set
of toolbar buttons (Add wall / Add column / Add beam / Place family) that popped `prompt()` dialogs for
dimensions. The toolbar four were a redundant, clunkier duplicate of what the Draft panel does better, so
they're removed along with their whole legacy code path — `setPlaceMode`, `capturePlacePoint`,
`openFamilyPicker`, and the generic `pickFromList` picker (~90 lines). The Draft panel is now the single
authoring surface (as of P1 it opens front-and-centre on a new model).

The genuinely useful **selection-based** edit buttons stay (delete · add door/window to a selected wall ·
move · rotate · edit property · copy) since the Draft panel doesn't cover those. Net: fewer buttons, one
clear way to draw, no behaviour lost. Verified live: the four place buttons are gone, the selection-edit
buttons remain, and authoring via the Draft panel is unchanged. Phase 2 of the modeling upgrade; next: an
explicit Author/Review tool grouping, then grid/level/space authoring UI.

## v0.3.231 — Modeling program, phase 1: start a model from scratch

**A direction change: the web app becomes a real modeling tool, not just a viewer.** The audit was blunt —
the Model workspace was ~80% viewer/analysis, authoring was buried in an edit-gated Tools-rail sub-panel,
and there was **no way to start a model from nothing** (authoring required an existing IFC). The engine was
never the problem — the backend already has a ~30-recipe GUID-stable IFC authoring API (walls, columns,
steel, rebar, MEP, coverings, families, storeys, spaces, transforms). This ships the missing foundation.

- **Blank model from scratch.** New `generate_blank_ifc` + `POST /projects/{pid}/model/blank` author a
  minimal valid IFC — project/site/building, N **levels** (the datum you draw against), and a thin
  **ground-reference slab** for scale — with no building geometry. `POST` sets it as the source IFC and
  publishes it, so authoring works immediately.
- **"✏️ New model from scratch" flow.** One action creates a project, authors the blank model, lands you in
  the Model workspace, and **auto-opens the Draft/authoring panel** (`viewer.openAuthoring()`) so the
  drawing tools are front-and-centre instead of hidden. In the Open menu.
- Verified end-to-end against a live backend: new model → blank IFC published in ~1 s → Draft panel opens
  with the full element palette → an `add_wall` recipe authors a real wall with a stable GlobalId.

`CLAUDE.md` updated to make in-browser authoring a first-class goal (Blender/Bonsai becomes optional/interop,
not the required editor). This is phase 1 of a multi-release modeling upgrade — next: declutter the toolbar
into Author vs Review modes and remove the redundant legacy buttons; grid/level/space authoring UI;
author-ready templates; and edit-in-place (drag/stretch). Test: `test_generate` (blank model → 4 levels at
the requested height, ground datum only, valid spatial structure to author into).

## v0.3.230 — Collapsible nav stages with per-workspace memory

The left-nav destination rail groups first-class destinations by lifecycle stage (Plan & derisk · Build ·
Turn over · …). Those stage headers are now **collapsible** — fold a stage you don't use and it **stays
folded** next time you're in that workspace (persisted per `workspace:stage` in localStorage), so the rail
stays scannable as destinations keep growing. Each stage is a `<details>` with a disclosure caret; the
stage that owns the active destination always stays open regardless of the saved state, so you never lose
your place. Verified live: folding a stage persists and restores on return to that workspace, and other
stages are unaffected.

*(The "denser multi-card dashboard summary" half of this nav-density item remains a smaller follow-up.)*

## v0.3.229 — Accessibility pass on the new panels

An a11y audit of the panels added this cycle — the Finance command-center home, the module-relations
graph, the material editor, and the takt actual-vs-plan card — closing the gaps that screen-reader and
keyboard users would hit:

- **Named the graphics.** The module-relations SVG and the takt line-of-balance chart now carry
  `role="img"` + an `aria-label` (and the graph a `<title>`) describing the content — e.g. "Module-relations
  graph: 124 modules, 111 links" — instead of being an unlabeled blob. The Finance capital-stack bar gets an
  `aria-label` with the debt/equity split.
- **Labeled every form control.** The material editor's per-class colour, transparency, and name inputs and
  the graph's workspace filter now have `aria-label`s (previously anonymous); the material and takt data
  tables use `scope="col"` headers.
- Added a reusable `.sr-only` utility for visually-hidden accessible text.

All controls were already native buttons/inputs/selects (keyboard-reachable) — the gap was accessible
*names*, which are now present. Verified live: the graph SVG and all material inputs expose their labels.

## v0.3.228 — Finance home: a command-center landing for the finance persona

The Finance workspace opened straight into the proforma editor; now it lands on a **command center** —
the same pattern the Design and Developer personas already have. A new default **Home** tab (alongside
Proforma and Portfolio) summarizes the deal's financial picture: the returns from the latest saved
scenario (equity IRR — tinted good/warn by threshold — equity multiple, project IRR, yield on cost, NPV),
a **capital-stack bar** (senior debt vs equity with the split and a sources-≠-uses warning when it doesn't
balance, from Sources & Uses), and quick-launches to the Proforma editor, the Portfolio roll-up, and the
investor **memo** and **pitch-deck** PDFs. Everything degrades to a clear empty state before a scenario is
solved.

With this, all three non-GC personas have a role-tailored landing (Design = model-health/phase-progress,
Developer = real-estate register + deal returns, Finance = returns + capital + investor docs); the GC keeps
its on-schedule/on-budget PX dashboard.

New `listScenarios(pid)` client method + `openFinanceHomeTab()` in `main.ts`; a Home fintab in the finance
workspace. The home renders its **shell synchronously** (header, KPI placeholders, and the quick-launch
buttons) before the returns/capital data loads — so the panel is never blank even if the data request is
slow, offline, or fails; the returns and capital stack fill in afterward. Verified live: the shell appears
immediately, the capital stack renders from project Sources & Uses, the empty-state shows before a
scenario, and the quick-launches switch tabs / open the PDFs.

## v0.3.227 — Investor pitch deck, expanded: exec summary + capital stack + business plan

The generated investment **pitch deck** (`/investment-deck.pdf`) grew from 6 to **9 slides** toward a real
investor deck, all from the same live project data. Three new slides: an **Executive summary** (the thesis
in prose — total capitalization, the equity ask, the underwritten IRR/multiple over the deal horizon — plus
three headline metrics and highlights); a **Capital stack** (a stacked bar of senior debt vs equity with
loan-to-cost and the equity check, a clearer read than the Sources & Uses table); and a **Business plan &
value creation** slide that frames the **development-margin thesis** — build yield-on-cost vs the exit cap,
with the spread in bps as the value the development creates — followed by the entitle → build → stabilize →
exit strategy. Everything degrades gracefully when no proforma scenario is saved.

The deck now runs: title · exec summary · deal-in-numbers · market & positioning · Sources & Uses · capital
stack · development timeline · business plan · returns & the ask. Landscape, big-number slides, with site
photos from project attachments on the cover.

`report.investment_deck_pdf` in `report.py`. Test: `test_dev_budget` — the deck renders and now has 9
slides (was 6). Completes the §B6 developer-deliverable item (the memo + deck already shipped; this deepens
the deck to the roadmap's 10–20-slide investor-deck target).

## v0.3.226 — Module-relations graph: see how the ~180 config modules wire together

The config-driven modules form a data model; now you can see its shape. New `module_graph.build(registry)`
reads the module registry back as a graph — one node per module, one edge per cross-module link — where
edges come from **reference** fields (a record points at another module's record) and **rollup** fields (a
module aggregates a numeric field from records that point at it). Each node carries its in/out degree, and
the result surfaces the **most-referenced hubs** (the cost code tops it, referenced by ~23 modules) and the
**orphans** with no links. A `workspace` filter keeps a workspace's modules + the targets they reference so
the full ~180-node graph stays legible. Pure over the registry — no database.

Endpoint `GET /modules/graph?workspace=` returns the graph. A **🕸 Module Relations** destination in the
Design workspace renders it as an SVG: nodes on a ring laid out by workspace/section, sized by in-degree so
hubs stand out, reference edges solid and rollup edges dashed, hubs labelled, with a workspace filter and a
most-referenced summary. Hover any node for its links.

Engine `module_graph.py`; `routers/modules.py` endpoint; `portal/panels/moduleGraph.ts`. Tests:
`test_modules` — every module is a node, cost-impact reference edges target cost_code, cost_code tops the
in-degree ranking and its node degree matches its edges, workspace scope is a subset, only reference/rollup
edge kinds. **Completes the §M rendering/computational-depth bucket** (material editor v0.3.225 + this).

## v0.3.225 — Material editor: a per-project palette you can edit and re-apply

The M1 material/colour assignment (each IFC element class → an IfcMaterial + IfcSurfaceStyle colour, so
the model renders in real materials instead of flat grey) is now **editable per project**. New palette
helpers — `materials.palette_to_json()` / `palette_from_json()` / `merge_palette()` — expose the built-in
per-category table as JSON and let a project override any class's material name, category, colour, or
transparency; only the changed classes are stored, the rest fall back to the default.

Endpoints (design router): `GET …/materials/palette` returns the default table, the saved overrides, and
the **effective** merged palette; `PUT …/materials/palette` persists overrides to project storage; and
`POST …/materials/apply` loads the source IFC, re-runs the material/surface-style assignment with the
merged palette (in a tempfile — `/app` is read-only in prod), writes it back, and kicks the
convert→fragments reindex so the viewer shows the new colours. A **🎨 Materials** destination in the Design
workspace's Model & standards group renders the editable palette table (colour picker + transparency +
material name per class) with Save, Apply + republish, and Reset controls.

Engine `services/data/aec_data/materials.py`; `routers/design.py` endpoints; `portal/panels/materials.ts`.
Tests: `test_design_phase` — GET returns default + effective, PUT persists an override, GET reflects it
(unchanged classes keep the default), apply 400s with no source model.

## v0.3.224 — Actual-vs-takt production tracking: the LOB chart learns the real ascent

The line-of-balance takt plan (trades chasing floor-to-floor at a steady rate) now measures **actual
against plan**. New `takt.progress(plan, actuals)` compares each trade's actual floors-complete with the
floors it *should* have finished by that day, giving a **floor variance** (+ahead / −behind), the
**achieved production rate** (floors/week) vs the planned rate, and an on-takt / ahead / behind read for
each trade and the job overall. The lead trade's achieved rate vs the planned pace is the headline: is the
train ascending at takt? `takt_svg` gained an **actuals overlay** — each trade's real ascent drawn as a
dashed line against the solid plan, so plan-vs-actual reads at a glance.

Project endpoint `GET …/schedule/takt/progress` derives per-trade floors-complete from the GC
`schedule_activity` records (100% complete or an actual finish date), sizes the takt plan from the model's
storey count, and **bundles PPC** (Last-Planner reliability) so one payload drives a dashboard card showing
plan health + reliability together; `GET …/schedule/takt.svg` renders the overlaid chart; and a stateless
`POST /schedule/takt/progress` computes it from posted actuals. A **"Takt — actual vs plan"** card in the
Schedule panel shows the overlaid chart + a per-trade variance table (done/plan, variance, actual vs planned
floors/week) + overall status + PPC.

Engine `takt.progress()` + `takt_svg(actuals=…)`; `routers/research.py` endpoints; Schedule-panel card.
Tests: `test_research` — variance sign (ahead/behind/on-takt), achieved-rate math, overlay drawn, unknown
trades ignored, plus the project endpoint (floors-done from activities, clamped to storeys, PPC bundled) +
stateless endpoint. Closes the §R2/R4 production-analytics thread (planned LOB + JIT already shipped).

## v0.3.223 — Monte-Carlo the specialty risk discount → distribution of blended deal IRR

Closes the §U4 thread. The specialty **risk discount** (the U4 haircut that keeps a farm/energy operating
business from being underwritten like de-risked real estate) is now a **Monte-Carlo driver**, not a single
point. New `specialty.monte_carlo()` samples specialty params (`risk_discount`, produce prices, any dotted
path) across a distribution (normal / uniform / triangular, optionally clamped), blends each draw into the
deal's equity, and returns the **distribution of blended deal IRR and specialty-only IRR** — percentiles
(P5…P95), mean/std, P[metric ≥ target], and a histogram. It reuses the proforma Monte-Carlo sampler +
summary, so the readouts match the rest of the risk tooling, and it's reproducible under a fixed seed.

Answers the real question: *once the haircut and price volatility are uncertain, how much does the
farm/energy actually help — and how often does it hurt?* A harsher haircut band measurably lowers the
blended-IRR distribution. Endpoint `POST …/specialty/monte-carlo` (assumptions + variables + iterations +
targets); a **"Risk sim"** button in the Specialty panel runs 500 draws and shows the blended-IRR P5/P50/P95
+ P[≥15%] and the specialty-only spread.

Engine `specialty.monte_carlo()` (reuses `proforma.monte_carlo._sample`/`_summary` +
`proforma.sensitivity._set_path`). Tests: `test_specialty` — ordered percentiles + histogram, seed
reproducibility, target-probability readout, harsher-haircut → lower blended IRR, plus the endpoint
end-to-end. **The full §U underwriting-depth bucket (exit-cap comps · specialty P&L + ramp · blended IRR ·
Monte-Carlo risk) is now cleared.**

## v0.3.222 — Specialty assets modelled over time: multi-year P&L + production ramp + blended IRR

The on-site energy/vertical-farm business is now underwritten as an **operating business over time**, not
a single stabilised year. New `specialty.proforma()` runs a multi-year P&L where revenue and generation
**ramp** linearly from a start fraction to full output over `ramp_years`, while opex (grow-lights, labour)
runs at full load from year 1 — so the early years earn less, or lose money, before the business
stabilises (the honest picture of a startup ag/energy operation). It reports per-year rows (ramp %, revenue
+ offset, opex, net, cumulative), a **specialty-only IRR** (capex at t0, ramped nets, plus a terminal value
= stabilised net ÷ exit cap), and the payback year. All cash flows use the **risk-adjusted** (underwritten)
figures, so nothing is overstated.

New `specialty.blended_irr()` folds that business into the deal's **equity** cash flows and reports
**real-estate-only IRR vs blended IRR and the lift** — the answer to "does the farm/energy actually move
the deal return, net of its risk discount?" Endpoints `GET …/specialty/proforma` (query: years, ramp_years,
ramp_start, terminal_cap) and `POST …/specialty/blended` (solves the RE proforma from the posted
assumptions, then blends the saved specialty params). A **"P&L + ramp"** view in the Specialty panel charts
the year-by-year table, the specialty IRR/payback/terminal, and the blended-deal IRR lift.

Engine reuses the robust `proforma.returns.xirr`. Tests: `test_specialty` — ramp fractions + net rising to
the stabilised plateau, terminal = net ÷ cap, payback, slower ramp → lower IRR, blended lift + guards,
plus both endpoints end-to-end. *(Remaining §U4 thread: wiring Monte-Carlo sensitivity to the specialty
risk discount — next.)*

## v0.3.221 — Surface parking placed on the real parcel remainder (polygon-aware)

Generated surface parking now fills the **actual land the building doesn't use** instead of a fixed
strip stamped behind the plate. New pure `pack_parking(poly, bldg_w, bldg_d, n, …)` lays stalls in
double-loaded modules (two 5 m stall rows sharing a 7 m two-way drive aisle), sweeping the parcel's
bounding box and keeping a stall only when its whole rectangle is **inside the parcel polygon** (ray-cast
point-in-polygon) **and clear of the origin-centred building footprint** (plus a 2 m drive-apron buffer).
`generate_ifc` recentres the parcel on its bbox centre to share the building's frame, then places the
packed stalls as real `IfcSpace(PARKING)` on the Site Parking storey. On an irregular or tight parcel the
supply is now **parcel-bound** — you get the stalls the site can actually hold, not the number requested,
which is the honest feasibility answer. Rectangular-lot inputs with no polygon keep the legacy strip
(unchanged). Completes the A6 remainder (the shoelace footprint + inward setback offset shipped earlier).

Engine `massing.pack_parking()` + `massing._point_in_poly()`; wired through `routers/generate.py`
(passes `metrics["buildable_polygon"]`). Tests: `test_massing` — packer keeps stalls inside a 60×60
parcel and off the building box, supply is parcel-bound (asking for 100 000 returns what fits), triangular
parcel clips corners, degenerate inputs safe; plus an end-to-end `generate_ifc(parcel_polygon=…)` placing
stalls clear of the footprint.

## v0.3.220 — Generated frame follows the load path: per-floor column taper + lateral core

The structural advisor now shapes the *generated geometry* floor-by-floor instead of stamping one fixed
column everywhere. A column at level _i_ carries the floors above it, so its axial load — and thus its
cross-sectional area — grows toward the base; side length scales with **√(floors carried)**, floored at
400 mm and rounded to 50 mm zones (real frames taper in bands, not continuously). The advisor returns a
per-floor `column_schedule` (base = widest, top = narrowest) plus `base_column_mm`/`top_column_mm`, and
`generate_ifc` extrudes each storey's columns at that storey's section, so a tall building visibly narrows
its frame as it rises.

Alongside it, a **central lateral core**: when the recommended lateral system is a core (mid-rise and up),
the advisor sizes a reinforced-concrete core (~20 % of the floorplate, min 6 m) with wall thickness that
grows with height for drift control (250–900 mm), and the generator extrudes the service-core walls as
real shear walls at that thickness — not the thin default. Low-rise buildings (distributed shear walls /
braced bays) correctly get **no** central core. Sized on the real footprint at generate time. The proforma
massing summary now shows the taper (`cols taper 900→500 mm`) and the core (`6×6 m core, 400 mm walls`).

Engine `structure.column_schedule()` + `structure.lateral_core()`; wired through `routers/generate.py`
into `massing.generate_ifc(members=…)`. Tests: `test_structure` (taper monotonic base→top, √-load, 400 mm
floor, core thickens with height, 1-storey edge case), `test_generate` (endpoint returns the schedule +
core), `test_massing` (generated column X-extents taper 0.90→0.50 m; core walls extrude at 400 mm). Also
fixed a stale `test_massing` MEP assertion (the core adds a riser **and** a distribution main per floor).

## v0.3.219 — Desktop build: Windows installer (uvloop) — all three platforms now build

Final piece of the installer repair. With v0.3.218 the macOS + Linux installers built, but Windows
failed: `RuntimeError: uvloop does not support Windows`. `requirements.lock` is resolved on Linux (the
prod image + CI), so it pins the **Unix-only `uvloop`** (a `uvicorn[standard]` transitive) with no
platform marker — and it can't build on Windows. The desktop sidecar now installs the API deps from the
**unpinned `requirements.in`**, letting pip resolve per-platform: `uvicorn[standard]` drops uvloop on
Windows and keeps it on macOS/Linux. Prod reproducibility is unchanged — the hashed lock still governs
the API Docker image and the CI test gate; the desktop sidecar is a bundled per-platform binary. All
three installers (Windows `.msi`/`.exe`, macOS `.dmg`/`.app`, Linux `.AppImage`/`.deb`) now attach to
tagged releases.

## v0.3.218 — Desktop build: Python 3.12 to match the lock (completes the installer fix)

Second half of the desktop-installer repair. After v0.3.217 fixed the requirements *path*, the sidecar
step still failed: the workflow set up **Python 3.11**, but `services/api/requirements.lock` is
pip-compiled under **3.12** and pins `numpy==2.5.x`, which requires Python ≥3.12 — so 3.11 couldn't
resolve it (CI already uses 3.12, which is why CI stayed green). Bumped the desktop workflow's
`setup-python` to 3.12 to match CI and the lock. With v0.3.217's requirements-path fix, tagged releases
now build the Windows/macOS/Linux installers and attach them to the release.

## v0.3.217 — Fix the desktop-installer build (releases were empty drafts)

**Ops fix — restores the signed desktop installers on tagged releases.** The Desktop-release workflow's
"Build the backend sidecar" step still installed `services/api/requirements.txt`, which was renamed to
`requirements.lock` during the hashed pip-compile work (v0.3.198). Every tag since then failed that step
on all three platforms, so no Windows/macOS/Linux installers were built and each GitHub Release stayed an
**empty draft**. Fixed to install the hashed lock (`pip install --require-hashes -r requirements.lock`,
matching CI) and the un-hashed data reqs **separately** (pip forbids mixing hashed + un-hashed files in
one invocation). Also fixed the report-only `security.yml` pip-audit, which pointed at the same missing
file and so wasn't auditing the API dependencies at all. Tagged releases now produce installers again.

## v0.3.216 — Underwriting realism: validate the exit cap against sale comps

Deepens the underwriting guardrails (roadmap ① / §U). A going-out cap tighter than the market supports
silently inflates the reversion (value = NOI ÷ cap) and the whole IRR — the most common way a proforma
"pencils" on paper but not in reality. `underwrite.guardrails(result, comps=…)` now derives the
**cap-rate band from the deal's own `comparable` sale records** and flags the exit cap against it:
**high** when >50 bps below the tightest comp, **med** when below the band, **info** when inside it (and
silent when at/above the comp median — the conservative case). The solve result now surfaces `exit_cap`
in `returns`, and a new project-scoped **`POST /projects/{pid}/proforma/solve`** runs the comp-aware
guardrails; the Finance panel calls it automatically when a project is open, so the exit-cap flag appears
in the underwriting guardrails alongside the IRR/EM/spread/DSCR checks. Pure/backward-compatible: the
stateless `/proforma/solve` and no-comps projects are unchanged. `test_specialty` covers the band math
(high/med/info/silent), the rent-comp exclusion, and the end-to-end project-scoped endpoint.

## v0.3.215 — Test Fit yield optimization: plate-depth sweep + core-efficiency

Deepens the generative Test Fit optimizer (roadmap ① — deepest, highest-value bucket). **Plate depth is
now an optimize dimension.** `test_fit.optimize(…, depths=[…])` (or `targets.sweep_depth=True` for an
auto ×0.6–1.4 range) sweeps unit-mix × parking **× plate depth** and returns a **`depth_curve`** — the
best yield-on-cost, daylight efficiency, and core efficiency at each depth, plus the `best_depth_m` where
daylight-limited yield peaks **before a dark interior core starts eating rentable area** (Willis, *Form
Follows Finance*). New **`core_efficiency`** metric on every layout (share of the gross plate not lost to
the daylight-dark core — 1.0 on a shallow plate, falling as depth pushes area past the ~9 m daylight
reach), distinct from `efficiency` which also nets out the corridor. The Finance **📐 Test Fit** panel
gains a **"sweep plate depth"** toggle that renders the depth curve with the peak depth starred. Backward-
compatible: with no sweep the optimizer is unchanged (15 schemes, single depth). `POST /test-fit/optimize`
accepts `depths`; `test_testfit` covers the sweep, the curve, `core_efficiency`, and the shallow-beats-deep
daylight ordering.

## v0.3.214 — In-browser E57 reality-capture reader + roadmap consolidation

**In-browser E57 (ASTM E2807) reader.** E57 previously required an optional server-side `pye57`
conversion; now `.e57` laser scans decode **fully in the browser, offline** — honoring the
"viewer runs fully offline" non-negotiable. New `viewer/e57.ts` parses the 48-byte header, strips the
CRC-paged logical stream, reads the XML `Data3D` prototypes, and decodes the CompressedVector binary
for the common encodings (**Float single/double + ScaledInteger XYZ with optional RGB**, across one or
more data packets), centring on the bbox midpoint and stride-decimating to the render budget like the
LAS/LAZ path. Anything it can't decode raises a typed `E57Unsupported`, and `main.ts` **falls back to
the proven server converter** — so worst case is today's behavior, best case is no round-trip. Wired
through `referenceLoader` (new `e57` branch) and the Open menu. `e57.test.ts` builds synthetic E57
files (single-page, multi-page CRC-stride, ScaledInteger+RGB, Float) and round-trips them through the
reader. Closes the last data-layer item that was tagged "upstream-blocked."

**Roadmap consolidation.** `docs/roadmap.md` is now lean — the banner + a single, re-ranked
**"What's left"** master backlog (① generative-design depth · ② UX/perf · ③ interop spikes · ④
upstream-blocked · ⑤ deferred-by-decision · ⑥ non-goals), sweeping up every open item from every
archive/parking-lot section (A/U/R/M/L/D + each "*Next:*" sub-note). All shipped history moved to a new
**`docs/roadmap-completed.md`** so *what's left* is never buried under *what's done*.

## v0.3.213 — Two deferred items closed: capital-markets syndication connector + IFC5/IFCX write path

**(1) IFC5 / IFCX write path.** The IFC5 read path shipped earlier (tolerant JSON→element-index parser);
the write path was deferred as "waits on web-ifc / Fragments." That dependency only blocks *geometry*
authoring — the **data** layer (elements + property sets) is plain JSON and tractable now. New
`aec_data/ifc5_writer.py` inverts the reader: it serializes the model index to **ifcJSON**
(buildingSMART `{"type":"ifcJSON","data":[…]}`, full-fidelity — guid/class/name/type/storey + property
groups round-trip exactly) or **IFCX** (the OpenUSD-style node list; USD attributes are flat so property
groups collapse to one attribute set, values preserved). `GET …/model/export.ifcx?flavor=ifcjson|ifcx`
streams it; `openbim` now advertises **IFC5 in `ifc.write`** (not just read). `test_ifcx_write` round-trips
both flavors back through the reader and asserts the registry change. Geometry authoring still lands
upstream — this is the data write path, the inverse of what already reads.

**(2) Capital-markets syndication connector (ledger sync — never moves money).**
Closes the last deferred capital-markets item as a **flagged data connector** (the parcels/APS pattern):
export the investor cap table to a securitization / investor-management platform, without rebuilding the
regulated issuance stack. New `securities_bridge` serializes `capital.cap_table` into a neutral
**syndication package** (`schema: massing.syndication.v1` — fund summary + per-investor positions +
disclosures), served at `GET …/securities/package` and **always available offline** regardless of the
connector. When configured (`SECURITIES_PLATFORM_URL` + `SECURITIES_API_KEY`, admin-editable in
Settings), `POST …/securities/syndicate` pushes the package to the platform over stdlib `urllib` (a
generic authenticated REST target is implemented; named platforms raise an actionable error until wired).
**Scope guard — this connector never moves money:** it syncs the *ledger* (positions, ownership %,
recorded contributed/distributed totals) so the external platform's records match ours; capital calls,
distributions and transfers are executed by the licensed platform, not here. Every response carries
`moves_money: false` and the package a disclaimer. The Investors tab (proforma) gains a **Capital-markets
syndication** card: download the package JSON, see connector status, and sync when enabled. Status gate
uses `current_user`; the push requires **admin**. `test_securities_bridge` covers the disabled export,
the actionable 422, a stubbed generic push (positions only), and the unimplemented-target error.

## v0.3.212 — Cross-workspace deep-link (element → linked records) + FF&E classification
Two roadmap items. **(1) Reverse deep-link — element → linked records.** The portal already had the
forward direction (a record's "👁 Show in model" selects its tagged elements); the reverse was missing.
New `traceability.element_records(db, pid, guid)` scans every **pinnable** module and returns the records
tied to an element by GlobalId (its `element_guids` tag or `data.guid`) — RFIs, coordination issues,
change orders, field verifications, schedule activities, etc. — grouped by module. `GET
…/elements/{guid}/records`; the viewer's on-selection inspector now shows a **🔗 Linked records (N)**
section beside the 5D cost breakdown, so selecting an element in 3D surfaces every record that touches it.
Completes the record↔element round-trip. **(2) FF&E classification** (from the pics8 field scan): the
furnishing IFC classes (`IfcFurniture`, `IfcFurnishingElement`, `IfcSystemFurnitureElement`) now classify
to **MasterFormat Division 12 (Furniture / Furnishings — FF&E)**, so furniture takes off and procures
correctly — additive, no discipline-taxonomy change. `test_element_records` covers the cross-module
reverse lookup (a field-verification + an RFI on one element found across both modules) + the FF&E mapping.

## v0.3.211 — Model Health: one composite score over every model-quality check
The model-quality checks were spread across the Model Tools rail — Data QA, ISO 19650 KPIs, clash
coordination, verified-as-built — so a coordinator had to open four tools to know where the model stands.
New `model_health.py` **composes** them (it re-implements nothing) into a single **0–100 composite
score** with four graded lenses, each linking to the tool that acts on it: **integrity & hygiene**
(`model_qa` — duplicate GUIDs, overlaps, orphans, unenclosed, blanks, wrong-storey), **information &
delivery** (`bim_kpi` ISO 19650 KPI health %), **coordination** (`clash_intel` resolution rate), and
**verified as-built** (`verified_progress` verified-in-place % + trust gap). The composite is a weighted
mean over the lenses that have inputs; a lens with no inputs shows **n/a** and is excluded rather than
guessed, so the score is honest. New `GET …/models/health` (opens the source IFC for the hygiene lens
when present; the other lenses score from records + the published index, so it works without a parsed
model); a viewer tool **🩺 Model Health (all checks, one score)** heading the model-quality group with the
composite band + per-lens breakdown; and a Report Center **Model Health Scorecard** (PDF/Excel, health-by-
lens chart). `test_model_health` covers the composite math, the clean-model = hygiene-100 case, the
n/a-lens exclusion, and the HTTP endpoint. (Part C "first-class Model Health surface" — see `docs/roadmap.md`.)

## v0.3.210 — Wave 8 ③(b): schedule-linked verified-as-built progress (the trust gap)
Closes the last buildable Wave 8 item. Instead of trusting a self-reported "% complete", Massing now
rolls **element-level field verification** up to each schedule activity and surfaces the **trust gap** —
where the claimed percentage runs ahead of what has actually been verified in place (the OpenSpace /
Disperse / Buildots value proposition, done as pure software over the model we already hold). New:
- **`field_verification` module** — one GlobalId-anchored record per element, workflow = the verification
  state (`captured → verified / deviated → resolved`), with deviation (mm), method, photo and a link to
  its schedule activity.
- **`verified_progress.py` engine** — maps every element to the activity that builds it (the same hard-tie
  or class→trade→floor resolution as the 5D map), then computes per-activity **verified-in-place %** vs
  **claimed %** and the trust gap, worst-over-claim first, plus overall coverage. `seed_from_layout` turns
  an as-installed `layout.verify` result straight into verification records (in-tolerance → verified,
  out-of-tolerance → deviated); `layout.verify` now also returns the full per-point deviation list.
- **Endpoints** `GET …/verified-progress` + `POST …/verified-progress/from-layout`; a viewer tool
  **✅ Verified-as-built progress** (verified % vs claimed, trust gap, per-activity breakdown); a Report
  Center report **Verified-as-built Progress** (PDF + Excel, verified-vs-claimed chart). `test_verified_progress`
  covers the rollup math (claimed 80 % but 2/4 verified → 50 % verified, +30 trust gap), the class→trade
  fallback, the layout seeding, and the HTTP endpoint.

## v0.3.209 — Docs: Wave 8 in the in-app tutorial + the guide
Now that the Wave 8 field upgrades have shipped, the onboarding and guide teach them. `docs/guide.html`
gains **Tutorial 🛰️ · Coordinate, lay out & walk the as-built** (six steps: coordinate clashes into
grouped BCF issues, model-driven field setout CSV/DXF, the preliminary load takedown, the wrong-storey
model-QA check, the Construction Execution Plan, and the Gaussian-splat reality overlay) plus a nav link.
The in-app first-run **tour** copy is refreshed: the Open-model step now mentions point-cloud / GIS /
reality-capture overlays, and the Tools step names the field toolkit (coordinate clashes, field layout,
load takedown). Docs/tutorial only — no behavior change.

## v0.3.208 — Wave 8 ③(a): Reality-capture walkthrough (3D Gaussian splats) in the viewer
Walk the as-built reality against the design. The viewer now loads **3D Gaussian-splat** captures
(`.splat` / `.ksplat`, plus splat-PLY auto-detected by header) as a **view-only overlay** beside the BIM
model — the on-site phone/drone photogrammetry → splat that the 2026 reality-capture wave produces, co-
registered with the IFC and the LAS/LAZ point clouds we already read. Built on `@mkkellogg/gaussian-
splats-3d` (MIT): its `DropInViewer` drops into the existing three.js scene as a `THREE.Group` and self-
sorts each frame via `onBeforeRender`, so no render-loop changes were needed; it flows through the same
"open reference model" path (extensions + `accept` filter + federation registry), and its sort worker +
GPU buffers are torn down when the overlay is removed. **Offline-first** (our non-negotiable): the library
and its **inline-blob sort worker** are bundled — no CDN — and the scene parses from an in-memory object
URL, never the network. The library is **lazy-loaded as its own chunk** (252 KB / 66 KB gzip), fetched
only when a user actually opens a capture, so the eager app shell stays within budget (179.7 KB < 220 KB).
`SharedArrayBuffer` is off (no COOP/COEP header requirement); CPU sort for widest device support. Note: the
blob-URL worker needs `worker-src blob:` if the opt-in strict CSP is enabled. `splat.test.ts` covers the
splat-PLY detector. Part (b) — schedule-linked verified-as-built progress — remains on the roadmap.

## v0.3.207 — Wave 8 ⑥: Construction Execution Plan (CEP) generator
The GC counterpart to the BEP: a produced governance document that states **how the project is built**,
assembled live from the construction modules and summary engines rather than a stale Word template. New
`_cep` report builder emits a **ten-section CEP** — (1) project organization & authorities (standard
appointment roles + the awarded subcontractors as appointed trade parties), (2) scope & work breakdown
by bid package, (3) master schedule & key milestones, (4) procurement & subcontracting (prequalified +
executed subs, insurance/bond), (5) cost management & change control (CO totals from the change-order
engine), (6) safety plan (OSHA metrics), (7) quality plan (inspections / NCRs / first-pass yield), (8)
submittal & RFI procedures, (9) permits & regulatory, (10) closeout & turnover (punchlist / commissioning
/ warranties / O&M). Every data pull is guarded — a missing engine or empty module degrades to a
placeholder row, never a 500. Registered in the report catalog (group *Quality*), so it **auto-surfaces
in the Report Center** with PDF / Excel / markup buttons — no frontend change. Covered by the existing
`test_reports` catalog loop (52 reports each render a valid PDF + Excel; dispatch-parity enforced). ISO
21502 / CMAA practice areas paraphrased in original prose (no copyrighted text, no competitor names).
(Wave 8 ⑥ of 7 — see `docs/roadmap.md`.)

## v0.3.206 — Wave 8 ⑤: wrong-storey model hygiene + green CI (in-memory model tests)
Completes the Wave 8 model-hygiene track and fixes the API test gate. `model_qa.py` gains a sixth
integrity check — **wrong storey**: an element assigned to level A but physically placed at level B's
elevation (the classic "wrong level" authoring mistake), flagged only when the placement sits clearly
closer to another storey (1 m margin) and guarded so a malformed storey set degrades to "couldn't check"
instead of 500ing. `test_model_qa` now exercises a positive case (a wall assigned to L1 but placed at
L2's elevation is caught and anchored to its GlobalId). **CI fix:** `test_layout` and `test_loads`
opened `samples/*.ifc` on disk, but `samples/` is gitignored — a fresh CI checkout has no model, so the
API test gate went red on v0.3.204/205. Both now **build their IFC in-memory** (`ifcopenshell.file` — a
64-column grid for the layout points, a 3-storey/12-column stub for the load takedown), matching the
pattern the other model tests already use. No behavior change to the layout/loads engines.

## v0.3.205 — Wave 8 ④: Preliminary gravity load takedown + ASCE 7 load combinations
A defensible, **non-FEA** structural sanity-check from the model — the tributary-area "load takedown"
every engineer runs before sizing columns. New `loads.py`: dead (slab self-weight from thickness × concrete
density + superimposed) + live (ASCE 7-22 Table 4.3-1 by occupancy, with the **§4.7 live-load reduction**
closed form) → tributary area per column → **accumulate storey-by-storey down to the footing** → **ASCE 7
load combinations** (LRFD §2.3 + ASD §2.4) → governing factored axial. Output: per-storey rows + the typical
interior column / footing service & factored loads. New `GET …/loads/defaults` (reads storey + column counts
off the IFC) + `POST …/loads/takedown` (explicit storeys or auto-built uniform); client `loadsDefaults`/
`loadsTakedown`; a viewer tool prompts for floor area/occupancy and shows the column + footing loads with the
governing combinations. `test_loads` checks the ASCE 7 combos (1.2D+1.6L governs; 1.4D dead-only), the §4.7
reduction (50→24.36 psf), and the takedown arithmetic (3×120 psf×1000 sf = 360 kip dead/column, factored
~509 kip). **Preliminary only — no lateral (wind/seismic), and not a substitute for a licensed structural
engineer** (the caveat ships in the API, the UI, and the output). Pure `ifcopenshell` + arithmetic; optional
PyNite/sectionproperties (MIT) tier noted for later. (Wave 8 ④ of 7 — see `docs/roadmap.md`.)

## v0.3.204 — Wave 8 ②: Model → field layout (PENZD/PNEZD CSV + DXF) + as-built verification
The smallest-surface, highest-field-utility Wave 8 item — export the setout that the 2026 field-robotics
wave consumes, straight from the IFC. New `layout.py`:
- **Setout points** — grid intersections (`IfcGridAxis`) + column / footing / opening / wall object
  placements, in **real-world E/N/Z** (the `IfcMapConversion` is applied, so points land on the
  surveyor's grid), each carrying its **IFC GlobalId in the Description** for the round-trip.
- **PENZD / PNEZD CSV** (configurable column order + delimiter) — the near-universal total-station /
  marking-robot interchange (Trimble/Leica/Hilti).
- **Layered DXF** (`ezdxf`, MIT) — points + labels, a layer per element type — for floor printers
  (Dusty-style).
- **As-built verification** — upload the as-installed total-station shots, match by point number, and
  get per-point 3-D deviation with out-of-tolerance flagged and anchored to the element GlobalId.
New endpoints `GET …/layout/{points,points.csv,layout.dxf}` + `POST …/layout/verify`; client
`layoutPoints`/`layoutCsvUrl`/`layoutDxfUrl`/`layoutVerify`; a viewer tool exports CSV/DXF and explains
the stake → shoot → verify loop. `test_layout` runs against a real IFC (208 setout points on
`maple_tower`; PENZD+PNEZD+tab CSV; layered DXF; the 100 mm-off point flagged at 20 mm tolerance; the
IFC2X3 no-map-conversion path degrades gracefully). Pure `ifcopenshell` + `ezdxf`; permissive. (Wave 8 ②
of 7 — see `docs/roadmap.md`.)

## v0.3.203 — Wave 8 ①: Clash Coordination Intelligence (grouping · severity · reconcile · KPIs)
The management layer on top of geometric clash *detection* — the strongest signal from the 2026 field
scan (4 of 14 sheets), built the way Navisworks / Autodesk Model Coordination / Solibri / Revizto do it.
New `clash_intel.py` turns a raw clash result set into **tracked coordination issues**:
- **Grouping** — greedy by-element set-cover: a duct crossing 12 joists becomes **one** issue
  ("relocate this duct"), not 12 clashes (the industry's order-of-magnitude reduction).
- **Severity** — a discipline matrix (structural pairs weigh most) × penetration volume × group size →
  a 0-100 score + Low/Medium/High/Critical band.
- **Stable identity + reconcile** — a `group_hash` (dominant GlobalId + the other discipline) survives
  re-runs, so a federation cycle auto-marks issues **resolved** (gone) and auto-**reopens** them
  (reappeared) *without losing comment history* — the classic Navisworks pain point, handled.
- **KPIs** — status mix, worst discipline pairs, severity, open-issue aging, per-run burn-down +
  reappearance rate.
Issues are created as `coordination_issue` records (already **BCF-native + pinnable + GlobalId-anchored**),
so everything round-trips with any BIM tool. New endpoints `POST …/clash/{coordinate,analyze}`,
`GET …/clash/metrics`, and `coordinate=true` on `POST …/clash/federated`; a `clash_run` module persists
run snapshots; the viewer's federated-clash tool now runs the coordination pass (reduction + new/active/
resolved/reappeared + severity + a KPIs view). `test_clash_intel` covers grouping, severity, and the
resolve→reappear→reopen loop across three runs. Pure Python; no new dependency. (Wave 8 ① of 7 — see
`docs/roadmap.md`.)

## v0.3.202 — Fix: metadata-only project no longer hangs the viewer on "Loading model"
A project with an uploaded **property index but no published `.frag`** (geometry never converted) spun the
viewer's **"Loading model"** overlay forever, and because the auto-load never returned, the Construction /
Finance **portal never mounted** ("No project open"). The backend correctly **404s** `model.frag` for such
a project — that path was already handled — but the degenerate variants weren't: an **empty 200 body**, or a
**non-`.frag` payload** (e.g. a proxy / SPA host that rewrites a 404 into a 200 HTML page) reached the
Fragments worker, which can **hang** (not reject) on input it can't parse, so `withLoading`'s `finally` never
fired. `loadProjectModel()` now fails open to the same graceful no-model state a brand-new project takes:
skip an empty body, and wrap `loadFragments` so unparseable bytes fall through instead of stalling. New
`apps/web/src/ui/autoload.test.ts` covers 404 / empty-200 / non-`.frag` / valid-`.frag`. Verified: backend
`model.frag` 404 + `model_kind: None` confirmed against the API; typecheck + lint clean; full web suite green.

## v0.3.201 — UI cohesion: wire the approval-gated journal batch into the General Ledger panel
A UI/UX cohesion pass over the recent finance work found the v0.3.199 **journal export batch** had shipped
backend-only — its client methods (`createJournalBatch`/`journalBatchExportUrl`) had no surface, so the
approval gate was unreachable from the app. The **General Ledger** panel now carries a **Journal export
batches** section: **Freeze current books into a batch** (period + memo via an accessible modal → draft),
a list of batches with **state badges** (draft / submitted / approved / exported) and frozen Dr/Cr totals,
inline **workflow actions** driven by each record's `available_actions` (submit → approve → reject), and
**GL-CSV / IIF download** links that appear only once a batch is approved. Same GlobalId-keyed data, one
click from the ledger the figures come from. (The v0.3.200 model-WIP cross-check was already wired into the
WIP panel; the only remaining finance client method with no panel — `wipModelProgress` — stays a public
API for embeds, its data already surfaced via the WIP `model` block.) Verified: typecheck + lint clean,
production build green; endpoints exercised live.

## v0.3.200 — Model-quantity-derived WIP %: an independent progress signal that cross-checks cost POC
Roadmap item ②, part 2 (closes item ②). Cost-to-cost percentage-of-completion can mislead — a cost
overrun makes a *behind* job look *ahead*, and front-loaded billing hides under-production. So WIP now
derives a second, **physical** progress signal straight from the model: **installed model elements ÷
total, keyed by IFC GlobalId** (the "units-installed" output method — ASC 606 output measure / EVM
units-completed), optionally weighted by an IFC base quantity (e.g. `NetVolume`). "Installed" = an
element whose field-`verification` status is `installed`/`verified`, so this ties revenue recognition
back to what's actually built in the field, not just what's been spent — and survives re-conversion
because it's GlobalId-keyed. `wip.py` gains `model_progress()`; `schedule()` gains a `method`
(`cost-to-cost` default | `units-installed`) and always carries a `model` block cross-checking physical
vs cost % with a divergence flag (`cost-ahead` = the classic front-loaded-billing signal). New `GET
…/wip/model-progress` + `method=` on `GET …/wip`; client `wip(pid, method)` + `wipModelProgress`; the
WIP panel shows a model cross-check card. Portfolio roll-up skips the per-project model scan (stays
fast). `test_wip` extended (count 50% / NetVolume-weighted 30%; aligned → physical-ahead; units-installed
drives earned 500k → 750k; unavailable with no model).

## v0.3.199 — Accounting interop depth: approval-gated journal export batch
Roadmap item ②, part 1. A **journal batch** freezes the current books — flattened GL + balanced
double-entry journal + trial balance — into an auditable snapshot (`journal_batch` config module) that
moves `draft → submitted → approved → exported`; the config engine gates each transition by party, and
`audit.py` records it. Export (GL-CSV or QuickBooks-IIF) emits from the **frozen snapshot**, and is
**409 until the batch is approved** — so the accountant imports exactly the figures that were reviewed
and signed off, and nothing posts to the books without passing the gate. `accounting.py` gains
`snapshot`/`create_batch`/`export_batch`; new `POST /accounting/journal-batch` + `GET
…/{id}/export?fmt=gl|iif` endpoints + client methods. `test_accounting` extended (freeze → export-409 →
submit+approve → frozen CSV/IIF still balances at 125000; 422 on missing period, 404 on unknown batch).
(Part 2 — model-quantity-derived WIP % — is the remaining half of item ②.)

## v0.3.198 — Supply chain (B2): hash-pinned Python lockfile, generated in the prod interpreter
Closes the last deferred hardening item. Top-level runtime deps now live in `services/api/requirements.in`;
a new `lockfile.yml` CI job runs `pip-compile --generate-hashes --allow-unsafe` **inside `python:3.12-slim`**
(the exact prod base image) and uploads the compiled `requirements.lock` (2,061 lines, every wheel pinned
+ sha256-hashed) — so the resolution always matches production, never a dev box. The API Dockerfile's
build stage and the CI test gate now `pip install --require-hashes -r requirements.lock`, which **rejects
any substituted or tampered wheel** (defends against dependency-confusion / registry compromise). One lock
covers the data-service deps too (a strict subset) and `psycopg[binary]`, so it replaced the two prior
unpinned installs. `lockfile.yml` also gates pushes: it fails if `requirements.in` changed without
regenerating the lock. Verified end-to-end by CI (test gate runs the full backend suite against the pinned
tree; the api image builds from it).

## v0.3.197 — Docs: consolidate + reprioritize the open roadmap into one section
Roadmap cleanup — pulled *every* not-yet-done item (previously split across a "Deferred" block and a
"Feature backlog") into a single prioritized **"What's left"** section: ① actionable next = B2 hashed
pip lockfiles (env-blocked here → a CI `pip-compile --generate-hashes` job in python:3.12-slim);
② optional feature depth = accounting-interop journal export + the exploratory parking lot; ③ upstream-
blocked = IFC5/IFCX write-path, native mobile (Capacitor) shell; ④ intentional non-goal = the A4/A5
portal-core split (deliberately coupled). Refreshed the header to v0.3.196, updated the intro (both the
feature roadmap and the Waves 1–7 hardening initiative are cleared), and corrected stale "in progress"
markers in the archive (Sources & Uses shipped as `proforma/sources_uses.py`; EVM E1–E7 and model
authoring P0–P6 shipped).

## v0.3.196 — Docs: Wave 7 (T5/T6/B3) shipped; only B2 remains deferred
Roadmap updated — the code-quality initiative's Wave 7 (TS strictness + Docker hardening) is now shipped
and CI-green (v0.3.193–195), leaving **only B2** (hashed pip-compile lockfiles) deferred, with the precise
reason: a correct hashed lock must be generated in the prod interpreter (Linux/py3.12) via
`pip-compile --generate-hashes` in a CI/Docker job — this dev sandbox has no Docker, and a Windows/py3.10
lock would pin the wrong wheels. (A4/A5 portal-core splits remain intentionally-not-done: coupled
orchestration where extraction adds indirection over value.)

## v0.3.195 — Docker/build hardening (B3): multi-stage API image + reproducible web npm ci
**API image** — split the Python install into a `pybuild` stage: the build toolchain (`build-essential`,
`python3-dev`) compiles any source-only wheel there, then only the installed packages are copied into the
runtime stage (`pip install --prefix=/install` → `COPY --from=pybuild /install /usr/local`). The runtime
image now carries **no compiler/headers** — smaller, and a reduced attack surface (already ran non-root +
healthcheck). **Web image** — `npm install` → `npm ci` against the workspace-root lockfile (exact, locked
tree; fails on drift) for reproducible builds; removed the vestigial `packages/shared-types` phantom
workspace (no package.json, no imports) so the root install is clean, and regenerated the lockfile.
Added a root **`.dockerignore`** (keeps host `node_modules`/`dist`/`.venv`/`.git`/`.env`/`*.db` out of
every build context). Verified locally: lockfile regenerates clean, web build + ESLint + Vitest (66) all
green; the Dockerfile builds themselves are validated by CI's container matrix. (The nginx web runtime
ships no node deps, so dev-toolchain `npm audit` advisories don't reach production.)

## v0.3.194 — Lint (T6): typed no-floating-promises + 45 unhandled-promise fixes
Enabled type-aware ESLint (`parserOptions.projectService`) scoped to the two promise-safety rules only —
deliberately NOT the full `recommendedTypeChecked` set (which would flood on the intentional `any` at the
IFC/three/@thatopen boundaries). `no-floating-promises` (error) flagged **45** fire-and-forget async calls
that swallow rejections; all fixed with `void` (each verified to be a self-handling navigation/render
method, not a raw `fetch`/`import`, with `errorReporting.ts`'s global `unhandledrejection` handler as
backstop). `no-misused-promises` is scoped to `checksVoidReturn:false` so it catches genuinely-dangerous
promise-in-conditional/spread misuse (0 found) without churning ~90 idiomatic async event handlers. tsc
(251-guard T5 intact) + ESLint + Vitest (66) + build all green.

## v0.3.193 — Type safety (T5): enable noUncheckedIndexedAccess + 251 real guards
Turned on `noUncheckedIndexedAccess` in the web tsconfig — every array/record index access is now typed
`T | undefined`, forcing an explicit check. Fixed all **251** resulting violations across 25 files with
*real* guards (destructure-with-check, `?? <default>`, early-return/`continue`, optional chaining) — not
blind `!`. Non-null assertions were used only where an index is provably in-bounds (right after a
`.length` check or a literal-tuple index), each annotated `// safe: <reason>` (34 total); **zero**
`as any` / `@ts-ignore` / `eslint-disable` escapes. The sweep caught real latent crashes now hardened:
empty-selection `Object.entries(sel)[0]` in `createRfiFromSelection`, malformed-frag-pair `.replace()`,
a `selectedIndex === -1` throw, `CAP_RANK[role]` defaulting unknown roles to rank 0 (correctly denies
review/edit/admin), and malformed-GeoJSON/GeoTIFF coordinate handling (skip vs crash). Money math kept
`?? 0` on numerators/display only, never divisors (no new NaN paths). tsc + ESLint + Vitest (66) + build
all green.

## v0.3.192 — Docs: close out the Code quality & hardening initiative
Roadmap updated to reflect that Waves 1–6 of the four-domain audit all shipped CI-green (v0.3.177–191):
observability, perf/scale, the type boundary (OpenAPI types + `ui/dom.ts`), modularization
(`model_index.py`, `report_builders/`, `httpCore.ts`, `portal/prefs.ts`), and reproducibility/ops
(fragments single-source, fail-closed secrets, Rust PR CI, Trivy split, `money.py`). Four items are
recorded as **deferred with measured blockers** rather than forced: T5 `noUncheckedIndexedAccess`
(251 real violations → per-module, not one sweep), T6 typed-lint (same class), B2 pip lockfiles (must
resolve in prod Linux/py3.12, not this dev box), B3 Docker `npm ci` (CI-only verify, low value).

## v0.3.191 — Add Decimal money helpers money.py (P6)
Float money math drifts at the cent: `round(2.675, 2)` is `2.67`, and a naive `round()` three-way split
of $100 sums to 99.99. Added `aec_api/money.py` — `q2()` (round-half-up to cents), `to_cents()`, and a
penny-accurate `allocate()` (largest-remainder split that always sums to the total). Returns plain
floats/ints so engines can adopt them incrementally without signature changes. New `test_money` suite
registered in the gate. (Additive — existing `round(x, 2)` sites are unchanged; adoption is opt-in.)

## v0.3.190 — Add typed DOM helpers ui/dom.ts (T4)
`document.createElement(...)` + a run of property assignments is the single most-repeated pattern in
the UI (255× in portal.ts alone). Added a thin, dependency-free `ui/dom.ts`: `el(tag, props, children)`
(typed props — `class`/`text`/`style`/`dataset` plus any element property like `onclick`/`type`),
`frag()`, `clear()`, and a typed `readForm<T>()`. Ships with a 7-case Vitest suite and is adopted in the
portal catalog as a first use; available for incremental adoption elsewhere. Vitest now 66 tests; tsc +
ESLint + build green.

## v0.3.189 — Refactor (T3): extract portal preferences into prefs.ts
The portal's favorites/recents and the per-persona "which nav sections open first" map were private
`PortalUI` methods, read by both the nav rail and the module catalog. Pulled them into a small
`portal/prefs.ts` (localStorage-backed, pure functions) so the two consumers share one source of truth
instead of reaching into the class. Verified: `tsc`, ESLint, Vitest (59), Vite build all green.
(portal.ts and viewer/app.ts already received their principled decomposition in earlier releases —
portal→panels/ + PanelContext, viewer→ViewerContext/install modules; the remaining catalog↔nav
orchestration is intentionally coupled, so this pulls out the cleanly-separable preferences only.)

## v0.3.188 — Refactor (T2): extract the API-client transport core into httpCore.ts
The web `ApiClient` mixed its transport plumbing (base URL, bearer token, `json`/`_pdfPost`/`url`/
`health`) in with ~200 typed domain methods in one 2,760-line file. Pulled the transport into a small
`HttpCore` base class (`api/httpCore.ts`); `ApiClient extends HttpCore` and keeps only the endpoint
surface. Every `api.method()` call site is unchanged (facade preserved). Verified: `tsc --noEmit`,
ESLint, and Vitest (59 tests) all green; production Vite build succeeds. (A full sub-client split was
weighed and rejected — it would churn 200+ call sites for no behavioural gain; transport/domain
separation is the value that carries low risk.)

## v0.3.187 — Refactor (A3): shared open_source_ifc() helper for the analysis endpoints
Three analysis endpoints (`models/georeferencing`, `models/qa`, `scan/deviation`) each hand-rolled the
same "resolve the project's source IFC → 409 if missing → ifcopenshell.open → 400 if unreadable" dance.
Added `deps.open_source_ifc(db, pid)` — one resolve-then-open path with consistent 4xx handling — and
converged the three sites onto it (georeferencing + models/qa now one-liners; scan/deviation reuses the
409 resolver, keeping its threadpool open). Behaviour identical; verified via test_georef, test_model_qa,
test_scan_deviation, test_ai_readiness.

## v0.3.186 — Refactor (A2): decompose reports.py into a report_builders/ package
The Report Center's builder module was a 1,436-line god-file holding ~50 per-report builder functions
alongside the catalog + dispatch. Split the builders into a `report_builders/` package — one module per
domain (`finance`, `construction`, `precon`, `bim`, `operations`) over a shared `_common` helper — so
`reports.py` is now a 176-line dispatch layer (the REPORTS catalog, the key→builder registry, and
`build()`). Public API is byte-identical: `reports.build`, `reports.catalog`, `reports.Report`,
`reports.to_pdf/to_sheets` all unchanged. Verified: all 8 report-exercising suites green (test_reports
builds every one of the 51 reports to PDF + Excel); ruff clean whole-tree.

## v0.3.185 — CI: split Trivy into a CRITICAL gate + non-blocking HIGH report
Following v0.3.184: scoping the API scan past npm's bundled tooling wasn't enough — the **web** image
(final stage `nginx:alpine`) carries its own rolling set of fixable HIGH CVEs in its apk packages, which
a shared skip-dir can't cover. Both base images churn fixable HIGHs outside our control, so a blocking
HIGH gate keeps the pipeline red on upstream timing, not on our code. Resolution: **CRITICAL findings
still block the publish**, and a **second, non-blocking Trivy step prints fixable HIGH CVEs every build**
so they're surfaced (not shipped silently) for a human to act on the ones in our own deps — without
base-image noise gating the release. Restores green container publish; keeps O4's real deliverables
(Rust PR CI + fail-closed prod secrets + CLI/dep guards) intact.

## v0.3.184 — CI hotfix: scope Trivy HIGH past npm's bundled build tooling
The v0.3.183 Trivy bump to HIGH immediately flagged **12 HIGH CVEs — all in npm's own vendored
node_modules** (cross-spawn / glob / minimatch / tar, DoS/regex issues) that the `node:20-slim` layer
carries; they're build-time tooling, not runtime attack surface, and can't be pinned by us (they track
the base image). The scan now `skip-dirs` npm's bundled tree, so real HIGH/CRITICAL CVEs in **our**
fragments/web-ifc + Python deps still block the publish, without base-image tooling noise. (The API test
gate, web build, and full backend suite were already green on v0.3.183 — this only unblocks the container
publish.)

## v0.3.183 — Ops/build hardening (Wave 1/6: O3 · O4 · B4) + A1 lint fix
Cross-cutting hardening + a follow-up to v0.3.181.
- **O3 — fail-closed prod secrets.** The prod compose overlay now sets `POSTGRES_PASSWORD` (postgres +
  the API's `DATABASE_URL`) and `S3_SECRET_KEY` (minio + the API) via `${VAR:?}`, so the stack **refuses
  to start** without real credentials instead of silently inheriting the dev `bim`/`minioadmin` defaults.
- **O4 — Rust PR CI + Trivy HIGH.** New `rust-ci.yml` runs `cargo clippy -D warnings` + `cargo fmt
  --check` on the Tauri shell, path-filtered to `apps/web/src-tauri/**` (no cost on unrelated PRs) — it
  previously only compiled at release time. The container scan now gates on **HIGH + CRITICAL** fixable
  CVEs (was CRITICAL-only).
- **B4 — converter CLI + Dependabot.** `cli.mjs` no longer clobbers its input when the file lacks an
  `.ifc/.rvt` extension (appends `.frag` instead); the Dependabot npm ecosystem points at the repo root
  (where the workspace `package-lock.json` actually lives) so it can open working PRs.
- **A1 fix.** Import-sort (ruff I001) slip in `evm.py` from the v0.3.181 `model_index` rename — the only
  thing that had gone red (lint, not tests). Whole-tree ruff is green again.

## v0.3.182 — Single-source the fragments/web-ifc version (Wave 6, B1)
Closes the version-coupling landmine CLAUDE.md warns about. `@thatopen/fragments@3.4.5` +
`web-ifc@0.0.77` were hardcoded in **three** independent places — the web client parser
(`apps/web/package.json`, the source of truth) and the two server-side `.frag` producers
(`services/api/Dockerfile`, `services/converter/Dockerfile`) — with nothing keeping them in lockstep, so
a client bump could silently leave the server emitting fragments the browser can't parse. The Dockerfiles
now take the versions as build ARGs (self-documenting, overridable), and a new
`scripts/check-fragments-version.mjs` (wired into the CI **web-build** job) fails the build if either
Dockerfile drifts from the `package.json` pins. `package.json` is now the one source of truth; CI enforces
agreement.

## v0.3.181 — Extract the model-index engine (Wave 5, A1)
Fixes the worst dependency inversion in the backend. The in-process **property index**
(`pid → {guid → record}`) and the model-version-keyed **scan-result cache** lived as private globals
inside `routers/properties.py`, yet five engines (`bim_kpi`, `energy`, `evm`, `mcp_tools`, `reports`)
reached in with `from .routers.properties import _INDEX, _ensure_loaded` — engines depending on an
HTTP-layer module's internals. Moved to a new `model_index.py` engine with a public API
(`ensure_loaded` / `get_index` / `get_meta` / `load` / `scan_cached`); the router now imports from it
(keeping its endpoints), and the five engines import the engine instead of the router. Compatibility
aliases (`_INDEX`/`_ensure_loaded`/`_scan_cached`) preserve behaviour exactly — same cache objects, so
in-place mutation stays shared. No API or runtime change; the dependency arrow now points the right
way and the index is testable/reusable without importing FastAPI. `test_scan_cache` updated to the new
module.

## v0.3.180 — OpenAPI-generated TypeScript types (Wave 4, T1 foundation)
Establishes a compiler-checked contract to the backend. `openapi-typescript` now generates
`apps/web/src/api/schema.d.ts` (types-only — erased at build, no bundle cost) from the FastAPI
`/openapi.json`, and a thin `openapiTypes.ts` seam re-exports `paths`/`components`/`operations` plus
`Schema<K>` / `OkJson<Op>` / `ReqJson<Op>` helpers so endpoints can adopt generated request/response
types. Regenerate with `npm run gen:api-types` (the intermediate `openapi.json` is gitignored;
`schema.d.ts` is committed). **Scope note, honestly stated:** the backend returns raw dicts on most
endpoints — only ~11 of ~540 declare a response model — so today the generated types are precise for
request bodies, path/query params, the 134 input schemas, and those typed responses; the hand-written
DTOs in `types.ts` remain the source for untyped responses. Coverage grows automatically as backend
endpoints adopt `response_model=` (a follow-on track). tsc/eslint/vitest green; bundle size unchanged.

## v0.3.179 — Scale: SQL-aggregate the portfolio & related-record hot paths (Wave 3)
Removing the linear-in-project-size loads. **P3 — WIP portfolio N+1:** the WIP schedule loaded up to
100k owner-invoice rows into Python *per project* to sum billed-to-date, and the portfolio roll-up runs
that for every job — the worst scale hazard in the codebase. Added a portable
`modules.sum_field(db, key, pid, field)` (SQL `SUM` over the JSON column: Postgres `->>`+cast,
SQLite `json_extract`) and pointed the WIP billed-to-date total at it. **P4 — dashboard timesheet
hours:** the safety-metrics endpoint summed `timesheet.hours` by loading every row; now a single SQL
sum (the manpower log stays row-wise because it needs the headcount→hours fallback). **related_records:**
the per-record detail view full-scanned each reverse-referencing module and filtered the match in Python;
the reference match is now pushed into SQL via the existing `_json_text` extraction (mirrors `_rollup`).
Identical output, far less work at scale. *(The schedule/CPM/gantt `list_records` loads were reviewed and
left as-is — they legitimately need every activity row. The ref-uniqueness DB backstop is deferred as
low-value/higher-risk.)*

## v0.3.178 — Perf & concurrency hardening (code-quality Wave 2)
Applying the audit's highest value-to-effort fixes. **P1 — event-loop stall:** the
`POST /scan/deviation` endpoint was `async` but ran `ifcopenshell.open` + full tessellation and the
point-cloud parse synchronously, stalling every other request on the worker for the duration of a large
scan; all three now run in `run_in_threadpool` (mirroring `run_validate`). **P2 — uncached hot scans:**
the model **data-QA**, **code-readiness**, and **by-discipline** viewer scans recomputed `O(n·psets)`
on every request while their siblings (facets/color-by) were cached; they now go through the same
model-version-keyed `_scan_cached` (Redis-backed, auto-invalidated on republish) — repeat loads are
served from cache. **P5 — concurrency/scale hardening:** a composite `(project_id, ts)` index on
`record_activity` turns the frequently-polled notifications feed from an index-scan-plus-filesort into
one ordered range scan (auto-backfilled on existing DBs); and the in-process property index
(`_INDEX`/`_LRU`) — mutated from multiple threadpool threads — is now guarded by a lock so an eviction
can't fire mid-populate and drop a live project. No API shape changes; behaviour identical, just faster
and safer under load.

## v0.3.177 — Error-log observability (see when things break)
The first wave of the code-quality/hardening initiative: a **background place to see failures** instead
of them dying in a server's stdout. A global exception handler + request-id middleware now catch every
**unhandled server error**, record it (with traceback, route, user, and a correlation id) to a new
`error_log` table, and return a clean `500 {detail, request_id}` — and every response carries an
**`X-Request-ID`** header so a user-reported failure maps straight to its logged row. **Browser errors**
are captured too: a `window.onerror` / `unhandledrejection` hook (throttled + deduped) posts to
`POST /client-errors`, landing in the same feed tagged `source:"web"` — so a viewer crash or a failed
upload is finally visible. Admins get an **Errors** console (account menu → Errors) with source/level
filters, a totals header, expandable tracebacks, and a prune button; the log is **retention-capped**
(rows + age, env-tunable) so it can't grow unbounded on the read-only prod tree. Engine `errorlog.py`,
`routers/observability.py` (`GET/DELETE /admin/errors`, admin-gated), `ErrorLog` model,
`errorReporting.ts`. Test `test_errorlog.py` covers the engine, the 500 handler end-to-end, the intake,
and the admin feed. In-house only — no external APM, consistent with the offline mandate.

## v0.3.176 — 2D → BIM raise (DXF floor plan → IFC model)
The complement to scan-to-BIM: where deviation checks the *built* result against the model, this
raises design intent *up* from flat 2D CAD into one. Upload a **DXF floor plan** and get a real,
GUID-keyed **IFC4 model** — an `IfcWall` extruded from each line-work segment (auto-detecting "wall"
layers, falling back to all line-work) and an `IfcSpace` (with its floor area in the Qto) from every
closed room polygon. Drawing units are read from the DXF `$INSUNITS` header and normalised to metres.
The raised model is registered as a **"2D Raise"** discipline model, so it opens in the viewer and
takes part in federated clash immediately. A `preview` mode returns the detected wall/room counts
without writing anything. Engine `plan_to_bim.py` (ezdxf for the CAD read — MIT, no AGPL; ifcopenshell
for the model, same wall/space patterns as the massing generator), endpoint
`POST /projects/{pid}/raise-plan` (multipart; temp-dir scratch, never the read-only tree), a client
method, and a **🏗 Raise 2D→BIM** viewer tool. Test `test_plan_to_bim.py` round-trips the IFC.

## v0.3.175 — Scan-to-BIM deviation (as-built QA/QC)
Close the reality-capture loop: upload an as-built **point cloud** (ASCII XYZ / CSV / PTS) from a laser
scan or photogrammetry survey and compare it against the model surface to see **where the built work
departs from the design beyond tolerance** — the QA/QC check after a pour or a steel erection. For every
scan point we take the nearest distance to the model's triangulated surface (a KD-tree over the model
vertices), then summarize: **% within tolerance**, mean / 95th-percentile / max deviation, an
out-of-tolerance count, and a **deviation histogram** banded in multiples of the tolerance — the numbers
behind a red/green deviation heatmap. Engine `scan_deviation.py` (numpy + scipy cKDTree; model surface
pulled via `ifcopenshell.geom`, capped so a huge model can't blow memory), endpoint
`POST /projects/{pid}/scan/deviation?tolerance=` (multipart upload; 409 without a source IFC), a client
method, and a **▦ Scan-to-BIM deviation** viewer tool that renders the summary + histogram. All units in
metres; GUID-keyed model geometry, fully offline. Test `test_scan_deviation.py`.

## v0.3.174 — AI / data-readiness scorecard
Roadmap item from the "hidden bottleneck of agentic AI" research: the blocker to AI isn't the model,
it's the **data**. A new scorecard grades a project **0–100 on four measurable dimensions** — **single
source of truth** (a GUID-keyed IFC + federated models), **information completeness** (CDE metadata +
core requirements), **model integrity** (the model-QA defect ratio, when an IFC is loaded), and
**governance** (requirement traceability + a responsibility matrix, on top of always-on RBAC/audit) —
with a per-dimension recommendation and a **ready / partial / not-ready** verdict. Answers "can an agent
act on this project's data yet, and if not, what to fix first?". Engine `ai_readiness.py`, endpoint
`GET /projects/{pid}/ai-readiness`, an **AI / data-readiness** card atop the CDE / Standards panel, and
`test_ai_readiness`. Honest heuristic — a readiness indicator, not a guarantee.

## v0.3.173 — PM: portfolio prioritization matrix
Roadmap **PM artifacts #2.** The Portfolio view now ranks every project you can see with a
**prioritization matrix** — each scored **0–100** on four criteria (financial **return** / equity IRR,
**on-budget** / CPI + variance, **on-schedule** / SPI + % complete penalized for late milestones, and
**delivery-risk** / status) into a weighted composite, ranked best-first with a color-graded score per
criterion. Reuses the executive-portfolio rows (and their membership scoping), so no double-counting.
New engine `prioritization.py` (pure, weight-configurable), endpoint `GET /portfolio/prioritization`,
a ranked card in the Portfolio panel, and `test_prioritization`. Answers "where do capital and attention
go across the book?"

## v0.3.172 — PM: stakeholder register + power/interest analysis
Roadmap **PM artifacts #1** (from the PM-template research). A new **Stakeholders** module (under Project
Controls) registers each party — organization, role, category, power/influence, interest, stance,
engagement strategy. A `stakeholder.py` engine turns the register into the **Mendelow power/interest
grid** — *manage closely* (high/high), *keep satisfied* (high power), *keep informed* (high interest),
*monitor* (low/low) — with a stance tally and, crucially, the **high-power blockers** to address. Exposed
as `GET /projects/{pid}/stakeholders/analysis` and a **Stakeholder Analysis** report (power/interest
quadrants + roster + blockers) in the Report Center, exportable to PDF/Excel. New `test_stakeholder`.

## v0.3.171 — Model QA: integrity / hygiene checks
Roadmap **Model-QA** (from the second research batch's "common modelling mistakes"). Complementing the
LOIN/IDS *data-quality* checks, a new **🩺 Model QA** tool scans the source IFC for the defects a
coordinator catches by eye: **duplicate GlobalIds**, **orphaned elements** (not placed in any storey),
**overlapping duplicates** (same class stacked at one spot), **unenclosed spaces** (an IfcSpace with no
boundaries — the classic "Room is not enclosed"), and **blank element names**. Each check returns a
count + a sample of offenders and a clean/not-clean verdict. New engine `model_qa.py`, endpoint
`GET /projects/{pid}/models/qa`, and `test_model_qa` (builds an IFC in-memory with every defect and
checks each is caught). ifcopenshell only, no new deps.

## v0.3.170 — Coordination: shared coordinates / BIM-to-field setout
Roadmap **Phase C** (from the second research batch's BIM Control Stack). The alignment report only read
a model's eastings/northings; this reads the **full survey basis**. A new **📍 Georeferencing** model
tool reports the complete `IfcMapConversion` — eastings/northings/height, the **true-north bearing**
(derived from the X-axis rotation), and scale — plus the `IfcProjectedCRS` (EPSG name, geodetic/vertical
datums, map projection + zone), and a site lat/long fallback. It grades the model with a **LoGeoRef
level** (0 → 50) so a coordinator sees at a glance how well-referenced it is — the basis federation and
**BIM-to-field layout/setout** both depend on. New engine `georef.py`, endpoint
`GET /projects/{pid}/models/georeferencing`, and `test_georef` (builds a georeferenced IFC in-memory and
checks the bearing/CRS/level). Permissive: reads via ifcopenshell, no new deps.

## v0.3.169 — openBIM: ISO 19650-6 exchange acceptance
Roadmap **Phase A #3.** Distinct from the project-level handover gate, this reviews **each exchanged
container** (anything past Work-in-Progress) against the four ISO 19650-6 acceptance criteria —
**completeness** (type/discipline/originator set), **suitability** (a suitability code), **authorization**
(published/archived, not merely shared), and **traceability** (a revision) — and flags the ones **not yet
acceptable** before the next decision point. Reuses the container data already tracked; no new module.
`cde.exchange_acceptance()`, endpoint `GET /projects/{pid}/cde/exchange-acceptance`, and an **Exchange
acceptance** card (per-criterion % + non-conformances) in the CDE / Standards panel. Extends `test_cde`.
Completes the ISO 19650 delivery-checklist "exchange assurance" step.

## v0.3.168 — openBIM: LOIN + MIDP/TIDP delivery plan
Roadmap **Phase A #2** (from the second research batch). Two ISO 19650 depth items on information
requirements. **LOIN** — each requirement now records its **Level of Information Need** per EN 17412-1 /
ISO 7817: the required depth of **geometry**, **alphanumeric** data, and **documentation** (three
ordered selects), so an EIR states *how much* information a deliverable needs, not just that it's needed.
**MIDP / TIDP delivery plan** — a new engine (`cde.delivery_plan()`) lays the requirements out against
their **programme dates**: each gets an overdue / due-soon / scheduled / issued status, a per-milestone
(due-month) roll-up, the next deliverable, and **LOIN coverage** (the share that actually state a level).
Surfaced as a **Delivery plan (MIDP/TIDP)** card in the CDE / Standards panel with overdue/due-soon
flags. Endpoint `GET /projects/{pid}/info-requirements/delivery-plan`; extends `test_cde`. Ties every
information exchange to a milestone — the "align exchanges with programme dates" step of the ISO 19650
delivery checklist.

## v0.3.167 — openBIM: information-requirement flow-down (ISO 19650 cascade)
Roadmap **Phase A #1.** The requirements register listed OIR/AIR/PIR/EIR/BEP/MIDP/TIDP but nothing tied
a requirement to the higher-level one it flows down from — so there was no actual traceability. Each
Information Requirement now has a **Derives from** link (to another requirement), and the CDE / Standards
panel shows a **Requirement flow-down** card: how many requirements trace up (OIR → PIR/AIR → EIR →
MIDP/TIDP), which ones **don't** (orphans that don't reach organizational intent — a broken cascade),
and any links pointing the **wrong way** (to an equal-or-lower tier). Engine `cde.cascade()`, endpoint
`GET /projects/{pid}/info-requirements/cascade`, extends `test_cde`. The link is set/edited inline with
the relational grid (v0.3.159). This is the openBIM information-delivery moat: intent traced from the
client's organizational requirements down to what each task actually delivers.

## v0.3.166 — Estimating: quantity takeoff from 2D CAD (DXF)
Roadmap **Phase B #4.** Estimating no longer needs an IFC model — a new **▤ DXF takeoff** model tool
takes an uploaded **.dxf** drawing and measures it **by layer**: linear metres (walls, pipe/conduit
runs), enclosed area (rooms, slabs — closed polylines + circles), and **block counts** (doors, fixtures,
devices), converting to metres from the drawing's own units. Built on **ezdxf** (MIT, pure-Python — no
AGPL); DWG converts to DXF first (external, optional). The upload is parsed in a temp file and
discarded, never written to the source tree; a non-DXF file returns a clean 400. New engine
`dxf_takeoff.py`, endpoint `POST /projects/{pid}/takeoff/dxf`, and `test_dxf_takeoff`. Estimators who
live in 2D CAD can now get measured quantities without a full BIM model.

## v0.3.165 — Estimating: labor demand by trade (estimate → staffing)
Roadmap **Phase B #3.** The resource estimate now rolls its crew-hours **up by trade** — total hours
and cost per trade (carpenter, ironworker, cement-mason…), sorted biggest-first — so the model answers
"how many carpenter-hours does this building need?", the input a scheduler or PM uses to staff and load
the schedule. The engine's `labor_demand()` can also imply an **average crew size** to finish in a given
number of weeks (hours ÷ weeks ÷ 40). Shown as a "Labor demand by trade" table in the 🧱 Resource
estimate model tool. Extends `test_assemblies`. This is the bridge from the estimate's L/M/E split to
resource loading — the point of computing crew-hours in the first place.

## v0.3.164 — Estimating: resource estimate in the viewer (labor · material · equipment)
Roadmap **Phase B #2** — surfaces v0.3.163's engine. The model tools now have a **🧱 Resource estimate**
button next to the blended "Estimate from model": it prices the takeoff by building each element up from
a crew and shows the **labor / material / equipment split** (with % of total), **total crew-hours**, and
a per-assembly breakdown (quantity, built-up unit cost, hours). Where the blended estimate answers "how
much," this answers "made of what" — the split a real estimate carries and the crew-hours that feed
resource loading. Unmapped element classes are noted, not hidden.

## v0.3.163 — Estimating: resource-based (assembly) cost build-up
Roadmap **Phase B #1.** Model-based estimating used a single blended $/unit per element class. Real
estimators build a unit cost **up** from a crew: labor hours × rate + materials × quantity + equipment
× hours. A new engine (`assemblies.py`) does exactly that — a catalog of labor/material/equipment
**resources** and **assemblies** (recipes like "cast-in-place wall" = concrete + rebar + formwork +
cement-mason + laborer + pump). Pricing any quantity now returns the **labor / material / equipment
split**, the built-up unit cost, **and total crew-hours** — the last of which can drive resource loading
and the schedule, not just a dollar figure. Two endpoints: `GET /estimate/resources/catalog` (the
reference book, each assembly with its built-up unit cost) and `GET /projects/{pid}/estimate/resource-based`
(prices the IFC takeoff by mapping each element class to an assembly; unmapped classes are surfaced, not
silently dropped). Backend-only this release; a UI to compare blended-vs-resource follows. New
`test_assemblies` (build-up math, L/M/E split, crew-hours, takeoff) — full suite green.

## v0.3.162 — Data-grid UX: choose which columns show
Roadmap **Track X #3.** A module list showed a fixed set of columns (whatever the module defined), so
wide record types either hid fields you needed or you scrolled past ones you didn't. A new **⚙ Columns**
button opens a checklist of every field — tick the ones you want as columns and they render in field
order; **Reset to default** returns to the module's built-in set. The choice is remembered per module on
this device, and the button highlights when a custom set is active. Ref, Title, Assignee, Ball-in-court
and Status always frame the row. Pairs with inline edit / paste so you can shape a wide table down to
just the columns you're working in.

## v0.3.161 — Relational fabric: "referenced by" now reads distinctly on a record
Roadmap **Track R #3.** A record's Related section already listed both the records it points to and the
records that point back at it — but with one identical icon and no labels, so you couldn't tell the two
directions apart. It's now split into two counted groups: **References (n)** — what this record points
to — and **Referenced by (n)** — its dependents, e.g. the change orders raised against a budget line —
each with its own direction icon and a one-line caption. Also hardens the section: linked-record titles
(user text) are now HTML-escaped rather than injected raw. Completes the record-level relational view
alongside the grid's clickable links (v0.3.157) and inline linking (v0.3.159).

## v0.3.160 — Data-grid UX: paste rows straight from Excel
Roadmap **Track X #2.** Getting a batch of records in used to mean saving a spreadsheet and uploading
it. Every module list now has a **⎘ Paste** button: copy a block of cells from Excel or Google Sheets,
paste them in, and the pasted table flows into the **same import step you already know** — column
mapping, preview, then commit. No file, no new code path: paste is converted to CSV and handed to the
existing importer, so it inherits its validation and field-mapping. Keep the header row and map each
column once. Rounds out in-grid data entry alongside inline edit (v0.3.158) and inline linking (v0.3.159).

## v0.3.159 — Relational fabric: link records inline from the grid
Roadmap **Track R #2** (extends v0.3.158's inline edit). In **✎ Edit inline** mode, a reference cell
now becomes a **record picker** — a dropdown of the linked module's records reading as *ref · title* —
so you set or change what a record points at without opening its form. Options come from the data
already fetched for the relational links (no extra requests); a current link that sits outside the
loaded window is preserved so toggling edit mode never drops it. Saves on change with the same green
flash. Read mode still shows the clickable link (v0.3.157). Together with v0.3.158 the whole row —
data fields and relationships — is now editable in place.

## v0.3.158 — Data-grid UX: inline-edit cells for fast bulk entry
Roadmap **Track X #1.** Editing many records meant opening a form for each one. Every module list now
has an **✎ Edit inline** toggle: data cells become inputs (text / number / date / dropdown / checkbox)
you edit straight in the table, and each change **saves automatically** with a brief green flash — no
form round-trip. Enter or blur commits a cell. Works across all 120 config modules and composes with
the existing filter / sort / bulk-select / templates. Reference cells stay as their new relational
links (v0.3.157); the inline record-picker for references comes next. Opt-in — the read view is
unchanged until you toggle it on.

## v0.3.157 — Relational fabric: reference cells become clickable links
Roadmap **Track R #1.** The 120 tools are deeply relational, but in a module's list a reference field
(a commitment's cost code, an RFI's spec section, a change event's PCO…) showed only a truncated id.
Now every reference cell resolves to the **linked record's ref + title** and is a **link** — one click
opens that record in its own module. The list pre-fetches each referenced module once (one lookup per
reference column, not per cell), so it stays fast; unresolved ids fall back to the short id. Applies
automatically to all 120 config modules. Foundation for the record-picker + inline-edit grid to come.

## v0.3.156 — Responsibility matrix (RACI / DACI) — roadmap Phase A, item 1
The role-clarity that ran through the field research (PM vs Superintendent, PM vs CM, RACI vs DACI)
had no home in the app. New **Responsibility** destination (under Plan & Derisk for the GC, and under
Model & Standards for the design seat, where it doubles as the ISO 19650 MIDP/TIDP task-team
responsibility view): an editable grid of activities × project roles, each cell an assignment letter.
- **RACI** (Responsible / Accountable / Consulted / Informed) or **DACI** (Driver / Approver /
  Contributor / Informed) — one-click toggle that remaps the doer letter across the matrix.
- **Live validation** enforces the rules that make a RAM useful: exactly one Accountable per row, at
  least one Responsible — flagged inline as you edit.
- **Starter templates** (design delivery, buyout, construction, closeout) seed a valid matrix in a
  click; add/rename/remove role columns and activities; export to CSV.
- Built on the config-module engine (new `responsibility` module + `responsibility.py`) so every row
  gets CRUD, RBAC, audit and search for free; the panel degrades to a clean empty state offline.

## v0.3.155 — Enterprise: SAML 2.0 single sign-on
Massing can now sit behind a corporate IdP over SAML (Okta, Azure AD/Entra, OneLogin, ADFS,
Shibboleth), alongside the existing OAuth providers. A new SP surface: **`GET /auth/saml/metadata`**
(SP metadata to register), **`GET /auth/saml/login`** (SP-initiated redirect, HTTP-Redirect binding),
and **`POST /auth/saml/acs`** (Assertion Consumer Service). A verified email maps to an
auto-provisioned free-tier user (honoring the same `AEC_OAUTH_ALLOWED_DOMAINS` / no-autoprovision
gates as OAuth); `/auth/providers` now reports `saml: true` when configured.

Verification is the whole game, so it's done carefully (`saml.py`, using `signxml`): the IdP signing
cert is **pinned** from config (never trusted from the message's KeyInfo); identity is read **only
from the cryptographically-verified subtree**, defeating XML Signature Wrapping; and the signed
assertion's **Conditions** (validity window ± a small clock-skew, AudienceRestriction == our SP) and
**SubjectConfirmation Recipient** (== our ACS) are enforced. `test_saml` drives real signed assertions
through the ACS and proves tampered, unsigned, wrong-key, expired, and wrong-audience responses are
all rejected (403). Enabled only when the IdP entityID + SSO URL + cert are set.

## v0.3.154 — Enterprise: SCIM 2.0 user provisioning
Enterprises can now automate account lifecycle from their IdP (Okta, Azure AD/Entra, OneLogin,
JumpCloud) instead of managing users by hand. A new **`/scim/v2`** surface (RFC 7643/7644) implements
the Users resource: **create** (provision), **read / filter** (`userName eq`), **PUT / PATCH**
(including both the Okta `path:active` and Azure `value:{active}` deactivation shapes), and
**DELETE** (de-provision). Provisioned accounts are SSO-only (a random, unusable password — they sign
in via OAuth/SAML), and **deactivation revokes any live token immediately** (bumps the session
watermark), not just at expiry; DELETE is a soft-delete so the audit trail and record authorship
survive, and a later re-provision reactivates (rehire). The whole surface is gated by a single
constant-time bearer token (`AEC_SCIM_TOKEN`); unset ⇒ 503 (disabled), so it can't be probed open.
Adds `User.external_id` (IdP correlation) + `User.provisioned` (additive schema sync).

## v0.3.153 — Search: GIN index behind module full-text search (Postgres)
Module full-text search already used Postgres `to_tsvector(...) @@ to_tsquery(...)`, but nothing
indexed that document — so every search recomputed `to_tsvector` for **every row** (a sequential
scan, brutal past ~100k records). `init_db` now creates a **GIN expression index** on the exact same
`to_tsvector(ref + title + data)` document the query matches (built from the shared `_pg_document`
helper, so the index and the query can't drift). Postgres-only and idempotent
(`CREATE INDEX IF NOT EXISTS`); a **no-op on SQLite** (dev/CI use the substring-LIKE fallback, which
needs no index). The regconfig is rendered as a literal so the expression is index-safe.

## v0.3.152 — Web: decompose the two remaining god-files (client.ts / portal.ts)
No behavior change — the two largest web modules are split along their existing seams:
- **`api/client.ts` 2905 → 2612**: the ~300 lines of DTO `interface`/`type` declarations move to a new
  **`api/types.ts`**; the client re-exports them (`export * from "./types"`) so every
  `import { … } from "../api/client"` site across the app keeps resolving unchanged.
- **`portal/portal.ts` 2816 → 2302**: the GMP **Budget** dashboard and the unified **Schedule** views
  (pull-plan board, lookahead, milestones, CPM, EV, baseline/variance, Gantt/LoB) extract to
  **`portal/panels/budget.ts`** and **`portal/panels/schedule.ts`** via the established `PanelContext`
  seam (the 11 panels already living there); the class keeps one-line delegators.

## v0.3.151 — Web: global keyboard focus indicator (WCAG 2.4.7)
Keyboard users had no consistent visible focus ring — many interactive controls relied on the browser
default, which the app's custom control styling suppressed in places. A single `:focus-visible` rule now
draws a 2px accent outline (with offset) on every focusable control — buttons, links, inputs, selects,
textareas, `summary`, and anything with `tabindex` — **only** for keyboard/AT focus, so mouse clicks
don't get the ring. Meets WCAG 2.4.7 (Focus Visible). CSS-only, no markup or behavior change.

## v0.3.150 — Report dispatch: data-driven registry (replaces the 90-line if/elif ladder)
`reports.build()` chose a builder through a ~90-line `if report == "…"` ladder. It's now a
`_BUILDERS` dict (key → builder) + a `_LOGS` dict for the module-log reports — adding a report is one
registry line, and the dispatch can no longer silently drift from the `REPORTS` catalog. `test_reports`
gains a parity assertion (`REPORTS` keys == builders+logs) so a new report without a builder (or vice
versa) fails the gate. No behavior change — all 50 reports still render.

## v0.3.149 — Primavera P6 **XML (PMXML)** import (alongside the existing XER)
The schedule importer now accepts both Primavera P6 export formats, auto-detected from the content.
- **`schedule.parse_pmxml`** reads a P6 XML (PMXML) export into the same activity rows
  (id / name / planned-or-actual start+finish) as the XER parser — namespace-agnostic (the P6
  namespace varies by version, so it matches on local tag names). **`parse_schedule`** dispatches
  XER vs PMXML by sniffing the first non-space character.
- The existing **`POST /projects/{pid}/schedule/import-xer`** now upserts activities from either
  format (same re-import idempotency, milestone tagging, and 4D date window); the web import button
  and file picker accept **.xer / .xml**.
- `test_research` extends to import a PMXML export end-to-end.

## v0.3.148 — Webhook hardening: HMAC signing + retry/backoff + delivery log
Makes the outbound webhooks (module transitions → external automation) production-grade.
- **HMAC signing** — when `AEC_WEBHOOK_SECRET` is set, every delivery carries
  `X-Massing-Signature: sha256=HMAC(secret, "<timestamp>." + body)` + `X-Massing-Event-Timestamp`, so
  a receiver can verify authenticity and reject replays (the timestamp binds the signature).
- **Retry with exponential backoff** — a failed delivery retries up to `AEC_WEBHOOK_RETRIES` (default
  3) with `AEC_WEBHOOK_RETRY_BASE`-second backoff (0.5s, 1s, 2s…) before giving up. Still fail-open —
  a broken endpoint never blocks the transition.
- **Delivery log** — a bounded, process-local ring of recent attempts (url, event, ok, status,
  attempts, error), surfaced to platform admins at **`GET /webhooks/deliveries`** with the signing
  state — "did my hook fire?" observability.
- `test_webhooks` extends to pin the signature, the retry (2 fails → 3rd ok) + log, and the admin gate.

## v0.3.147 — openBIM: IFC4.3 infrastructure discipline + full ISO 19650 suitability codes
Closes the openBIM standards remainder.
- **IFC4.3 infrastructure entities** (`IfcAlignment`, `IfcRoad`, `IfcRailway`, `IfcBridge`,
  `IfcMarineFacility`, `IfcTunnel`, `IfcCourse`, `IfcPavement`, earthworks, …) now classify to the
  **Civil (C)** discipline instead of being lost to the default — their MasterFormat divisions (34
  Transportation / 35 Marine) sit outside the building divisions, so they're mapped directly.
  `classification.is_infra_class()` exposes the set. (`IFC4X3` was already a supported read schema.)
- **CDE suitability codes** — the information-container vocabulary now carries the higher ISO 19650
  codes **S5 (manufacture/procurement), S6 (PIM authorization), S7 (AIM authorization)** alongside
  the existing S0–S4 / A / B / CR / AB.
- `test_disciplines` pins the infra→Civil mapping.

## v0.3.146 — fix: `test_stored_ids` must set `IFC_DIR` (the actual red-CI cause)
`test_stored_ids` uploads a source IFC via `/source-ifc`, which writes to `IFC_DIR` (default
`/app/ifc`, read-only on CI/in the container). Sibling upload tests set `IFC_DIR` to a writable path;
this one didn't, so the upload — not the `/validate` temp write fixed in v0.3.145 — was what reddened
CI. Test now sets `IFC_DIR=./test_ifc_stored_ids`. (The v0.3.145 tempdir fix remains a valid
defense-in-depth for the `/validate` path.)

## v0.3.145 — fix: `/validate` wrote its temp IDS into the read-only container path
The stored-IDS validation (v0.3.143) wrote the temporary `.ids` next to the source tree
(`_DATA_SRC.parent`), which is writable locally but **read-only (`/app`) in the deployed container** —
so `POST /validate` with an uploaded or pinned IDS raised `PermissionError` in production (and reddened
CI once `test_stored_ids` first exercised that path). Now writes to the OS temp dir via
`tempfile.mkstemp`. No API change.

## v0.3.144 — openBIM: COBie Contact / Zone / System tabs
Rounds out the COBie handover workbook with the three tabs owners most often flag as missing, all
derived from the model.
- **Contact** — the people/organizations behind the model (keyed by email), from
  IfcPersonAndOrganization / IfcPerson / IfcOrganization, deduped.
- **Zone** — spatial groupings of spaces (IfcZone) with their member space names.
- **System** — functional groupings of components (IfcSystem / IfcDistributionSystem) with their
  member component names + predefined type.
- The COBie export now **merges** same-named sheets across sources instead of clobbering — so the
  model-derived System and the commissioning-derived System land in one tab; `_rows_to_sheet` takes
  the **union** of columns so no source loses a field.
- `test_cobie` (synthetic IFC) pins the extraction; `test_closeout` asserts the tabs + the merge.

## v0.3.143 — openBIM: pin a project IDS + validate against it
A project can now **pin the information-delivery specification (IDS)** its model must satisfy — the
EIR/BEP-mandated one — so validation runs against it every time without re-uploading.
- **`PUT/GET/DELETE /projects/{pid}/ids`** store, inspect (`?download=1` streams it), and clear the
  pinned IDS (object storage; editor to change, viewer to read). Store/clear are audit-logged.
- **`/validate` precedence**: an uploaded `.ids` still wins; otherwise `ids=auto` (default) uses the
  pinned IDS when present, else the built-in QA specs. `ids=stored` forces the pinned one (404 if
  none); `ids=default` forces the built-ins. Both JSON summary and the BCF punch list honor it.
- **Web**: the IDS Requirements panel gains a **"📌 Pin as project IDS"** action (builds the selected
  use-case IDS and pins it) with live status + unpin; `client` gets `pinProjectIds`/`projectIdsStatus`/
  `unpinProjectIds`/`idsBuildBlob`.
- Fixed a latent shared-temp-file collision in `/validate` (per-project temp name now).
  `test_stored_ids` pins the full lifecycle + precedence end-to-end (real IFC + real IDS engine run).

## v0.3.142 — openBIM: real bSDD linked-data alignment
Turns the bSDD story from "is it classified?" into "is it *linked* to a buildingSMART Data
Dictionary?" — genuine linked-data alignment, building on the v0.3.137 bSDD client + registry.
- **`bsdd.is_bsdd_uri()` / `parse_uri()`** recognize and decompose real bSDD class URIs
  (`identifier.buildingsmart.org/uri/<org>/<dictionary>/<version>/class/<code>`).
- **Alignment scoring** now reports two honest tiers — `classified` (has any type/classification)
  vs **`bsdd_linked`** (classification is an actual bSDD URI) — plus the distinct dictionaries the
  model references (Uniclass, IFC, an EIR-mandated one…), so a reviewer sees *which* it aligns to.
- **JSON-LD export** emits a bSDD-classified element's URI as a resolvable `@id` classification node
  (`"classification": {"@type": "@id"}` in the context), so the model graph is true linked data that
  resolves against bSDD — not just a bag of local codes.
- `test_bsdd` extends to pin URI recognition/parse, the two-tier alignment, and the JSON-LD linkage.

## v0.3.141 — Enterprise auth: TOTP two-factor authentication
Optional time-based one-time-password MFA, stdlib-only (no new dependencies) — a second factor at
sign-in for accounts that opt in.
- **`totp.py`** implements HOTP/TOTP (RFC 4226 / 6238) with HMAC-SHA1, a ±1-step skew window, an
  `otpauth://` provisioning URI for any authenticator app, and salted one-time recovery codes. The
  crypto is pinned to the published RFC test vectors.
- **Enrollment**: `POST /auth/mfa/setup` issues a secret + QR/manual key; `POST /auth/mfa/enable`
  confirms with a live code and returns 10 one-time **recovery codes** (shown once; only hashes are
  stored). `GET /auth/mfa/status`; `POST /auth/mfa/disable` requires password **and** a live code.
- **Login becomes two-step** when MFA is on: password → a short-lived challenge ticket, then
  `POST /auth/mfa/verify` with a TOTP *or* a (single-use) recovery code → session. Accounts without
  MFA are unchanged.
- **Web**: account-menu "Two-factor auth…" (enroll with key + code, view recovery status, disable)
  and a sign-in challenge step; `askText` gains a masked-`password` option.
- Additive schema sync adds `mfa_secret/mfa_enabled/mfa_recovery`. `test_mfa` pins RFC vectors + the
  full enroll → challenge → recovery → disable flow. Enable/disable/recovery-use are audit-logged.
  (SAML 2.0 SP + SCIM 2.0 remain — they need a live test IdP.)

## v0.3.140 — Enterprise auth: session revocation ("sign out everywhere")
Bearer tokens can now be revoked before they expire — closing a real gap where a leaked token
stayed valid for its full 7-day life even after the password was changed.
- **Token epoch** — every auth token carries an issued-at (`iat`); each account has a `token_epoch`
  watermark. The RBAC gate rejects any token issued before the watermark, so revocation is immediate
  (no session table needed). Additive schema sync adds the column to existing DBs.
- **Password change now revokes other sessions** — changing your password (or an admin resetting it,
  or a reset-token redemption) bumps the watermark, invalidating every other outstanding token. The
  current tab is handed a fresh token so it stays signed in.
- **"Sign out everywhere"** — a new account-menu action (`POST /auth/logout-all`) revokes all other
  sessions after a suspected token leak. Admins get a per-user **Revoke sessions**
  (`POST /auth/users/{u}/revoke-sessions`) for offboarding / lost devices — distinct from
  deactivation (revoke lets them sign in again; deactivate blocks re-login).
- All revocation events are audit-logged. `test_sessions` pins the contract end-to-end.
  (SAML/SCIM and TOTP MFA are the next enterprise-auth increments.)

## v0.3.139 — Web lint gate (ESLint, flat config) wired into CI
Adds static analysis to the web app so genuine defects (unreachable code, bad awaits, dead
expressions) are caught in CI alongside the strict `tsc` typecheck and the Vitest suite.
- **ESLint 9 flat config** (`apps/web/eslint.config.js`) with a pragmatic, low-noise ruleset:
  real-bug rules stay errors; patterns this codebase adopts on purpose (`any` at IFC/three/@thatopen
  boundaries, non-null assertions, `const self = this` closure capture in object-literal getters) are
  off or warnings, so the signal isn't drowned out. New `npm run lint` / `lint:fix` scripts.
- **CI gate** — a Lint (ESLint) step runs before the Vitest job in the web workflow.
- **Baseline cleaned to zero** — the 70-file baseline surfaced only 3 errors + 1 warning, all in
  `portal.ts`/`proforma.ts`; fixed by converting two side-effecting ternaries to `if/else` and one
  `let`→`const`. No behavior change.
- **Single, pinned toolchain** — a root `eslint` pin + override collapses the dependency tree to one
  ESLint (9.39.5), so `npm ci` is deterministic and the CLI resolves the same version everywhere.

## v0.3.138 — Security: pin the auth path fail-closed (regression guard)
Audited the whole auth/authz path for fail-open behavior and confirmed it is already **fail-closed** —
`verify_token` / `verify_password` / `signing.verify_path` all return a deny value (None/False) on any
malformed input or exception, never an allow, and the RBAC middleware denies anonymous callers under
RBAC. To keep it that way, `test_security` now pins the contract: a garbage / undotted / **tampered**
bearer token is rejected (401/403) by the gate and `verify_token` returns `None` for it, while the
genuine token still resolves — so a future edit can't silently turn an auth error into access.

## v0.3.137 — openBIM: version-pluggable standards registry + BCF 3.0 + bSDD; money-math tests
Makes the platform's open-standard support **pluggable to any version**, widens interoperability, and
pins the most error-prone financial math.
- **Money-math correctness tests** — the **equity waterfall** (`proforma/waterfall.run_waterfall`:
  pref accrual → return-of-capital → IRR-hurdle promote tiers) and the **GL trial balance** were only
  exercised indirectly. `test_waterfall` pins them to hand-computed numbers (72 pref + 428 RoC = 500 to
  the LP, 472 unreturned) plus hard invariants: dollar conservation across arbitrary multi-period cash,
  full return of capital before promote, the promote actually promoting the GP, and European style
  withholding promote until the LP is whole. `test_accounting` now asserts the double-entry invariant —
  trial balance debits == credits (== 125000) and the GL columns balance.
- **openBIM version registry** (`openbim.py`) + **`GET /openbim/capabilities`** — one source of truth
  for which open standards the platform speaks (IFC, BCF, IDS, bSDD, COBie, ISO 19650 CDE) and, per
  standard, which versions it **reads** and **writes**. The version lists are **derived from the live
  engines** (BCF versions from `bcf_io`, IFC schemas from `model_capabilities`) so the matrix can't
  drift from what's actually implemented, and adding a future version (IFC5, BCF 3.x, IDS 2.0) is a
  registry entry + an adapter rather than scattered `if version ==` edits. `supports(standard, version,
  mode)` answers "do we read/write X vN?" for guards and agents. `test_openbim_registry`.
- **BCF 3.0 read/write.** `bcf_io.py` (previously 2.1-only) now writes **BCF 3.0** on request and
  auto-detects the version on import. In 3.0 the `<Comments>` and `<Viewpoints>` move inside `<Topic>`
  and `<Labels>` become a `<Labels><Label>…</Label></Labels>` group — so a 3.0 file from a newer
  BIMcollab / ACC no longer silently loses its comments and labels on import. Both BCF export endpoints
  (`GET …/bcf/export` and `GET …/modules/{key}/bcf/export`) take `?version=2.1|3.0` (2.1 remains the
  default); import auto-detects. `test_bcf` gains a 3.0 round-trip + a crafted-3.0-file read.
- **bSDD lookup.** New `bsdd.py` — a thin, cached client for the buildingSMART Data Dictionary
  (`api.bsdd.buildingsmart.org`): `GET /bsdd/search?q=` finds classes, `GET /bsdd/class?uri=` resolves
  a class's canonical URI + property set. Fixed trusted host (no SSRF surface), 8s timeout, graceful
  502 on outage. Turns the classification alignment proxy into a path to real dictionary URIs.
  `test_bsdd` mocks the HTTP (no live network) — search/class parse, cache-hit, defensive parse, 404/502.

## v0.3.136 — openBIM: IDS validation failures export as a BCF punch list
Closes the model-QA loop. `POST /projects/{pid}/validate?format=bcf` now returns a **.bcfzip** of the
IDS non-conformances — one topic per failing specification, with that spec's failing elements selected
as the topic's components — so an IDS audit round-trips into Solibri / ACC / BIMcollab exactly like any
coordination issue, and a coordinator can jump straight to the offending elements. `format=json`
(default) is unchanged. Reuses the existing IDS validator (`aec_data.validate`) and BCF writer
(`bcf_io.export_records_bcfzip`); the new pure `validate.failures_to_bcf_records()` does the mapping.
`test_ids_authoring` covers the conversion + a real round-trip through `parse_records_bcfzip`.

## v0.3.135 — Accessibility: every native prompt/confirm replaced with keyboard-navigable modals
Removes the last blocking `window.prompt()`/`window.confirm()` dialogs from the app — 42 call sites
across the viewer, portal, drawings, connections, account, finance, and PDF-takeoff flows now use the
shared accessible modal helpers (`confirmModal` / `askText` / `promptModal`), which trap focus, close
on Esc/backdrop, restore focus on close, and carry `role="dialog"` + `aria-modal`. Destructive actions
(delete/remove/untie) get a red-styled confirm button. Behavior and every message string are unchanged;
only the dialog is now navigable and screen-reader friendly. (The remaining `window.prompt` in the
built bundle lives inside the third-party @thatopen viewer library, not our code.)

## v0.3.134 — Accessibility: reduced-motion support + screen-reader announcements
P2 a11y quick wins (Section 508 / WCAG 2.1 — often a procurement gate), no functional change.
- **Reduced motion:** a global `@media (prefers-reduced-motion: reduce)` rule near-instantly completes
  every transition/animation (toast slide-ins, spinner, panel fades) for users who set that OS
  preference — state still changes, just without the motion. Leaves the 3D viewer's own render loop
  alone (that's content, not decoration).
- **Screen-reader announcements:** the toast host is now a polite `aria-live` region (`role="status"`),
  so notifications are announced instead of being silently invisible to assistive tech; **error** toasts
  use `role="alert"` for immediate (assertive) announcement. The loading overlay is likewise a
  `role="status"` live region that announces its label (incl. download progress), with the spinner
  marked `aria-hidden`.

## v0.3.133 — P1 hardening: audit the contractual mutations + count without loading + CI test guard
Follow-on to the v0.3.132 P0 block — enterprise-readiness P1 items, all behavior-preserving.
- **Audit-log coverage for contractual mutations:** module workflow **transitions** (RFI answered,
  CO approved — `module.transition:<key>:<action>`, with actor, record id, and the resulting state),
  record **deletes** (`module.delete:<key>`), and **bulk** actions now write to the append-only
  `audit_log` (readable at `GET /audit`). Previously only project/member/user/settings/contract/IFC
  events were audited; the config-engine state changes — the ones an owner or auditor most needs to
  reconstruct — were not. `test_audit_coverage`.
- **Executive report counts via SQL aggregate:** the executive summary tallied open/total RFIs,
  submittals, change orders and incidents by loading every record (up to 100k per module) into memory;
  it now uses a single `GROUP BY workflow_state` per module (`state_counts`), which is hardened to
  return `{}` for an unknown module and key a NULL state by `""`. `test_search_alerts` covers it.
- **CI test-manifest guard:** `run_tests.py` now fails the gate if any `test_*.py` on disk isn't
  registered in its hand-maintained `TESTS` list — a test nobody runs can no longer slip in silently.
- **Green CI restored (bundle-budget false positive):** the app-shell size guard filename-matched every
  `index-*.js` chunk, so it wrongly counted the lazy **pdf.js** vendor chunk (its source module is
  `index.js`, ~163 KB, loaded only when a PDF opens) as part of the eager shell — pushing the reported
  shell to 330 KB and failing the build on every push. It now derives the true entry from
  `dist/index.html` (entry chunk + CSS + the split `app-*` chunk); the real first-party shell is 166 KB,
  well within the 220 KB budget.

## v0.3.132 — P0 security: close cross-tenant access + gate SSO + atomic refs
The must-fix block from the enterprise-readiness audit — no data-shape or workflow change, pure hardening.
- **Cross-tenant access closed:** every `/projects/{pid}/…` route now enforces **project membership**
  via `require_role` (reads→viewer, writes→reviewer/editor) — 59 routes that authorized on identity
  alone (incl. full model exports and financial reads) are gated. A new **CI guard** (`test_route_authz`)
  enumerates all 381 project routes and fails the build if any lacks a membership check, so it can't
  regress. `require_role` is tagged (`_role_gate`) for detection.
- **Portfolio roll-ups scoped to memberships:** the cross-project proforma / construction / executive /
  FCA roll-ups now return only the caller's projects (`rbac.member_project_ids`), never every tenant's
  GMP / EAC / IRR / equity.
- **SSO provisioning gated:** OAuth self-provisioning honors `AEC_OAUTH_ALLOWED_DOMAINS` (and an optional
  `AEC_OAUTH_NO_AUTOPROVISION=1` invite-only mode). The production boot guard now also refuses to start
  on Postgres when `AEC_TRUST_XUSER=1` (impersonation) or when `S3_ENDPOINT` is set with default
  `minioadmin` credentials.
- **Atomic human refs:** record refs (RFI-001…) now come from a per-(project,module) counter row taken
  under a row lock — concurrent creates can't collide, and deleting a record no longer lets a later
  create reuse a ref (the old `COUNT(*)` scheme did). `test_ref_counter`.

## v0.3.131 — Unified sheet view: PDF-editor markups appear on the SVG sheet (shared coordinates)
Completes the 2D convergence with a **shared coordinate space**. Every takeoff markup now stores a
page-normalized (0..1) anchor when saved from the PDF editor, so the SVG drawings viewer renders those
markups **on the same sheet** alongside its native pins — one place to see everything on a drawing.
- **PDF editor** (`pdfTakeoff`): the ⭳ Save-to-sheet path computes each markup's normalized anchor from the
  PDF page dimensions and persists `data.nx/ny`.
- **SVG sheet viewer** (`drawings.ts`): loads both its pins and the PDF-editor's takeoff markups, placing the
  latter by `nx/ny × content-box` (a distinct amber ◆ badge showing the measurement). They're the same
  `drawing_markups` rows, so they promote to RFI / delete right from the SVG view.
- No schema change (nx/ny ride in the existing `data` JSON). Web-only.

## v0.3.130 — One 2D markup model: takeoff markups persist to the sheet + promote to RFI
Converges the two previously-disconnected 2D markup systems onto one server-side store. The pdf.js
takeoff editor's structured markups (distance / area / count / rect / text / stamp) now persist into the
same `drawing_markups` table as the SVG sheet pins — so they reload on reopen and can be **promoted to an
RFI** exactly like a pin, instead of only flattening to a throwaway PDF.
- **Backend** (additive, no migration tool): `drawing_markups` gains `kind` + `data` (JSON geometry).
  New `POST /projects/{pid}/drawings/markup/bulk` saves a whole sheet's scene (`replace` clears the
  caller's own prior unpromoted markups — anything promoted to an RFI is kept). RFI promotion now carries
  the markup's measurement into the issue.
- **2D editor**: opening a drawing sheet's PDF binds it to the sheet — it **loads** existing markups and a
  new **⭳ Save to sheet** button persists them. The SVG pin view is untouched (PDF markups live in their
  own coordinate namespace on the shared store). `test_markup`.

## v0.3.129 — The 2D editor everywhere + save generated PDFs to Documents + pin perf
Optimizes the two editors and uses them to best intention throughout (from an audit of both):
- **Save generated PDFs to Documents** — a marked-up report / pay app / statement / drawing sheet can now
  be filed into the Document Manager (a folder picker → real, versioned revision) via a shared
  `saveToDocuments` helper, not just downloaded.
- **The 2D editor replaces native PDF tabs throughout** — the sheet **PDF markup** button in the drawings
  editor, the viewer's **Compose sheet (PDF)**, **G702/G703 pay app**, **lien waivers**, the project
  **status report**, **investment memo / pitch deck**, the **G702 draw package**, and **WH-347** now open in
  the in-app 2D editor (measure / mark up / save) instead of the browser's native PDF tab.
- **3D pin-overlay perf** — the BCF/RFI pin overlay reprojected every marker every frame; it now skips the
  reprojection + DOM writes unless the camera moved, the viewport resized, or the pin set changed (a still
  scene with many pins costs ~nothing).

## v0.3.128 — Every PDF opens in the in-app viewer, marks up, and saves back
Closes the gap where only local files reached the markup viewer and annotations only downloaded. The
takeoff/markup viewer (`pdfTakeoff.ts`) now opens a PDF from a **server URL** (fetched with auth), not
just a local `File`, and takes an optional **save-back callback** — with a new **⭱ Save to source**
toolbar button that flattens the markups and posts them back. A shared `openPdfUrl(api, url, name, opts)`
helper (`drawings/openPdf.ts`) is the single entry every surface routes through:
- **Record attachments** — a stored PDF attachment now opens in the viewer (📄 tile) instead of a bare
  link; the marked-up copy saves back as a new attachment on the record.
- **Document manager** — each PDF gets a **✎** action: open in the viewer, mark up, and **save as a new
  revision** (docmanager versioning/supersede).
- **Contracts / change orders** — "🖊 View & markup" now saves the redlined copy back as an attachment
  (previously the annotations were lost on download).
- **Module record PDF** — a **🖊 Markup** button opens the generated record PDF in the viewer and saves
  the marked-up copy back as an attachment.
- **Report Center** — a **🖊 Markup** button opens any report in the viewer; **PDF tools** gained
  **👁 Open & mark up…** so any PDF (including a downloaded generated one) can be viewed/marked up in-app.

## v0.3.127 — A/E/C stamps & professional seals (submittal review + PE/RA seal)
Real construction/design stamping on PDFs — the two legally distinct classes, done properly.
- **Stamp template library** (server = source of truth, `stamps.py` + `GET /stamps/library`): submittal
  **review** (both **EJCDC** — Approved / Approved as Noted / Revise and Resubmit / Rejected, and **CSI**
  — No Exceptions Taken / Make Corrections Noted / Amend and Resubmit / Rejected / For Record Only),
  **inspection** (Pass / Partial / Fail), and **status** (For Construction / Void / As-Built …). Review
  stamps carry reviewer, firm, in-responsible-charge, submittal no., spec section, date — and bake in the
  standard **design-conformance disclaimer** (review is only for general conformance with the design
  concept; the contractor keeps responsibility for quantities, dimensions, means/methods, coordination).
- **Professional seal + signature** (`POST /pdf/seal`): renders a *visible* PE/RA seal + signature/date
  block, then applies a **tamper-evident PAdES digital signature LAST** so any later change is detectable.
  Honest about compliance — the self-signed platform certificate is demonstration / tamper-evidence, not
  board-accepted sealing; configure the licensee's own certificate (`ESIGN_P12`) for regulatory use.
- **UI**: a **🏛 Stamp & seal PDF** tool — pick a PDF, choose a template, fill fields / disposition, place,
  and download the stamped or sealed PDF. Client methods `stampLibrary` / `pdfStamp` / `pdfSeal`.
- Rendering is reportlab overlay + pypdf composite (permissive licenses; **no PyMuPDF**). `test_stamps`.

## v0.3.126 — PDF markup: stamps + tool sets + server merge/split/rotate (phases 2–3)
Completes the PDF markup/manipulation stack — interactive stamps/text + reusable tool sets on the
client, and server-side page ops via pypdf. Still permissive-only (no PyMuPDF/AGPL).

- **Text + dynamic stamps** in the PDF takeoff — a 𝗧 Text tool and a 🔖 Stamp picker with dynamic
  stamps (APPROVED / REVIEWED / FOR CONSTRUCTION / VOID / AS-BUILT / `{{user}} · {{date}}` …) whose
  `{{user}}/{{date}}/{{time}}/{{file}}` fields resolve at placement. They render on the overlay and
  **flatten into the exported PDF** (stamps in a red box).
- **Tool sets** — 💾 Save / 📂 Load the whole markup scene (calibration + all markups) as JSON, so a
  set of stamps/measurements is reusable and shareable across sheets (a reusable tool set).
- **Server PDF ops (`pdfops.py`, pypdf)** — `POST /pdf/{info,merge,split,extract,rotate}`: merge a
  drawing set into one file, split to one-PDF-per-page (zip), extract a page range (`1,3,5-7`), rotate
  by 90°. A **🗂 PDF tools** launcher (merge/split/rotate/extract uploaded PDFs). Non-PDF uploads 422.

Verified: `test_pdfops` (engine + HTTP merge/split/extract/rotate + non-PDF reject); web typecheck +
build + 59 vitest.

## v0.3.125 — PDF markup: flatten to a real PDF (markup stack, phase 1)
First phase of a PDF markup/manipulation stack (three decoupled layers: PDF.js
render · interactive markup · pdf-lib/pypdf persistence). Built on the existing PDF takeoff.

- **Flatten markups into a downloadable PDF** — the ⤓ PDF button in the PDF takeoff burns every markup
  (distance, area, count, rectangle + label/quantity) into a real PDF via **pdf-lib** (MIT), so a
  marked-up drawing round-trips as a PDF, not just CSV. Handles the PDF.js(top-left)→PDF(bottom-left)
  Y-flip; markups are page-tagged so multi-page sets export to the right page (also fixes cross-page
  overlay bleed).
- pdf-lib is code-split (dynamic import) — no cost to the main bundle until you export.

Deliberately **permissive-only**: pdf-lib (client) + pypdf (server, already a dep) — **no PyMuPDF**
(AGPL, incompatible with a proprietary product without a paid Artifex license). Next phases: Fabric.js
interactive stamps + tool sets, and server-side pypdf merge/split/rotate.

Verified: web typecheck + build (pdf-lib bundles) + 59 vitest.

## v0.3.124 — Drawing revisions, sealed issuances, title blocks (AIA completion)
Completes the AIA drawing-issuance chain from v0.3.123 — revision deltas, digital seals, and title-block
metadata.

- **Revision / delta register**: `POST /projects/{id}/drawings/{drawing_id}/revise` records a delta on a
  sheet (rev, date, description) and can cite the driving change instrument (**ASI / CCD / Addendum /
  Bulletin**); it appends to the sheet's revision block and bumps the current revision.
  `GET …/drawing-set/revisions` is the cross-sheet register (newest first) with a by-instrument rollup —
  the "what changed, when, and why" log a set carries.
- **Sealed issuances (PAdES)**: `GET …/drawing-set/issuances/{iid}/sealed.pdf` returns the issuance
  transmittal **digitally sealed** by the professional of record via the existing e-sign — the
  tamper-evident electronic seal jurisdictions require for permit/IFC submittal (unsealed with
  `X-Sealed: false` when e-sign isn't configured).
- **Title-block completeness**: generated sheets (`sheet.svg`/`sheet.pdf`) now carry **ISSUED FOR** +
  **REV** in the title block (`?purpose=&rev=`).
- Web: a revision register + 🔏 sealed-PDF links on the Drawing-set register; `reviseDrawing` /
  `drawingRevisions` / `issuanceSealedUrl` client methods.

Verified: `test_drawing_revision` (deltas cite ASI, register rollup, sealed PDF) + `test_preview`
(title-block change safe); ruff clean; web typecheck + build.

## v0.3.123 — AIA drawing issuance: per-discipline sheet set + issuance register
Turn the model into a full, correctly-numbered 2D drawing set, then release it the way an A/E office
does — dated issuances for a purpose, with the sheet-index × issuance matrix the standards expect.

**Discipline sheet-set generation.** **`sheetgen.py`** generates a standard set — **G-** General ·
**C-** Civil · **L-** Landscape · **S-** Structural · **A-** Architectural · **FP-** Fire Protection ·
**FA-** Fire Alarm · **P-** Plumbing · **M-** Mechanical · **E-** Electrical · **T-** Telecom — each a
cover/notes sheet, one plan **per building level** (S-101…S-1NN), and the usual elevations/sections/
details/schedules, numbered per NCS (`M-101` = Mechanical / Plans / 01). **Fire Alarm (FA-)** is a
distinct series from Fire Protection (FP-) in the vocabulary, `parse_sheet_id`, naming validation and
the `drawing` module. `GET …/drawing-set/plan` (preview) + `POST …/drawing-set/generate` (auto-detects
disciplines from the model, or `{all:true}`/explicit list; idempotent). **Mass-ready**: bulk-inserts in
one transaction — a 50-storey, 9-discipline set (532 sheets) generates in ~0.1s (was ~11s).

**Drawing issuance register (AIA/CD).** New **`issuance.py`** + `drawing_issuance` module: issue the
current set for a **purpose** (SD/DD/CD/Issued-for-Permit/Bid/Construction/Addendum/Conformed/Record),
snapshotting every sheet + its revision. `POST …/drawing-set/issue`, `GET …/issuances` (history),
`GET …/issuance-matrix` (the **sheet-index × issuance grid** — each sheet's revision in each issue),
per-issuance transmittal PDF stamped with the purpose. A **📤 Issue set** control + issuance table +
matrix on the Drawing-set register.

Verified: `test_sheetgen` + `test_issuance` (issue snapshots, matrix reconstructs which sheet went in
which issuance, per-issuance transmittal, AIA purposes); mass test 532 sheets / 0.1s; ruff clean; web
typecheck + build clean.

## v0.3.122 — Battle-tested for mega-project scale (200k+ records)
Load-tested every heavy read path against a seeded ~220k-record project (research-sized for a $500M+
job: ~10k RFIs, 20k cost lines, 12k punchlist, 15k timesheets, …) and fixed what didn't hold up.

- **my-work** was returning **every** actionable row across all modules — a ~25 MB, 4 s response on a
  mega project. Now a bounded to-do queue: newest-N per module (indexed) + a 500-item cap, lean columns
  only (no JSON blob). 25 MB → ~100 KB, 4 s → ~0.5 s.
- **BCF export** ran a per-record `get_record` (comments/timeline/rollups it never uses) — an N+1 that
  took ~12 s on an 8k-issue module. `list_records` already returns every column BCF needs, so it's one
  query now (~1 s) with a 25k-record cap (logged when hit).
- **Dashboard** loaded the JSON `data` of the entire non-terminal tail of all 118 modules just to check
  due dates. Now it reads JSON only for modules that have a due-date field and pulls action items from a
  bounded, state-filtered query. 3.8 s → ~1.2 s.
- **Indexes**: added `(project_id, created_at)` — every list does `ORDER BY created_at`, previously a
  filesort — and `(project_id, assignee)` for the work queues. Backfilled on existing DBs at startup.
- **Connection pool** is now sized from the environment (`AEC_DB_POOL_SIZE`/`_MAX_OVERFLOW`/`_RECYCLE`/
  `_TIMEOUT`) instead of SQLAlchemy's 5+10 default, which starves a multi-worker API under load.
- New reusable harness: `seed_scale.py` (bulk-seeds every module at configurable volume) +
  `loadtest.py` (per-endpoint latency + concurrency), and a `test_scale` regression that locks in the
  pagination clamp, bounded my-work, single-query BCF, and index presence.

Verified: full backend suite green (incl. `test_scale`); ruff clean; security review clean.

## v0.3.121 — Cost traceability by IFC GlobalId (model → cost → GL)
Closes the moat of the resourcing/accounting plan — cost and billing tied to the actual model elements
they pay for, by GlobalId. A cost-code-only ledger can't answer "what did *this* column cost?"; this can.

- **`traceability.py`** walks every cost line (budget / commitment / direct cost / sub invoice) that
  carries `element_guids` and computes **coverage** — the share of job cost tied to real model elements —
  overall and **per cost code**, plus `element_costs(guid)` for "what did this element cost?" (by kind).
- Endpoints `GET /projects/{pid}/cost/traceability` and `GET /projects/{pid}/elements/{guid}/costs`.
  A **🔗 Cost Traceability** panel: coverage KPIs (color-banded), a GlobalId lookup, and a
  per-cost-code coverage table. `costTraceability` / `elementCosts` client methods.

Verified: `test_traceability` (coverage 93.3%, element→cost by GUID and by kind, untagged→0); ruff clean;
web typecheck + vitest + build.

## v0.3.120 — General ledger: balanced double-entry journal + trial balance + chart of accounts
Closes A2 of the resourcing/accounting plan — the posting bridge to the accounting system of record.

- **`accounting.py`** gains a standard construction **chart of accounts** (AR, contract asset/liability,
  AP, contract revenue, construction costs) and a **balanced double-entry journal** posted from job cost
  (Dr Construction Costs / Cr AP), owner billing (Dr AR / Cr Revenue) and the **WIP percentage-of-completion
  adjustment** (under-billing → Dr Contract Asset / Cr Revenue; over-billing → Dr Revenue / Cr Contract
  Liability) — so Contract Revenue nets to **earned**. Plus a **trial balance** (debits = credits, per account).
- Endpoints `GET /accounting/chart-of-accounts`, `/accounting/journal-entries`, `/accounting/trial-balance`
  (the GL-CSV + QuickBooks-IIF exports already existed). A **📒 General Ledger** panel (trial balance +
  journal + CSV/IIF export). `journalEntries` / `trialBalance` client methods.

Verified: `test_wip` extended (journal balanced, trial balance ties, revenue nets to earned, over-billing
posts to contract liability) + `test_accounting`; ruff clean; web typecheck + vitest + build.

## v0.3.119 — Contractor financial statements (POC income statement + contract position)
The construction-only statement lines a generic P&L / balance sheet miss — the balance-sheet twin to the
WIP schedule (A2 of the resourcing/accounting plan).

- **`contractor.py`** — from the WIP: a **percentage-of-completion income statement** (revenue = earned,
  not billed; cost of revenue = cost-to-date; gross profit + margin) and a **contract-position** section
  (**contract asset** = under-billings, **contract liability** = over-billings, **retainage receivable**,
  **accounts payable** from unpaid sub invoices, and **net contract working capital** = under-billings +
  retainage − over-billings − AP). Company-wide roll-up too.
- Endpoints `GET /projects/{id}/contractor-statements` + `/contractor-statements/portfolio`; a
  **Contractor Financial Statements** report; the statements render on the WIP panel + a second PDF link.
- `contractorStatements` client method.

Verified: `test_wip` extended (POC income statement, contract asset/liability, net working capital,
portfolio, both report PDFs); ruff clean; web typecheck + vitest + build.

## v0.3.118 — WIP schedule: percentage-of-completion + over/under-billing
The defining construction-accounting artifact, and the accounting twin to the earned-value module —
built on the job cost that already exists, no new cost model.

- **`wip.py`** — percentage-of-completion (**cost-to-cost**: cost-to-date ÷ total estimated cost) →
  **earned revenue** = % complete × contract value → compared to billed for the contract position:
  **over-billing** (billings in excess of costs & earnings — a **liability**) or **under-billing** (costs
  & earnings in excess of billings — an **asset**, and the classic cash drag on profitable jobs). Plus
  retainage, cost-to-complete, gross profit/margin, profit-to-date and backlog.
- Endpoints `GET /projects/{id}/wip` and `GET /wip/portfolio` (one row per job, worst cash position
  first). A **📄 WIP Schedule** panel (KPIs + a colour-coded over/under-billing callout + contract-position
  table + portfolio roll-up) and a signed PDF report. Client `wip` / `wipPortfolio`.
- Contract value comes from the prime contract + approved COs (falling back to the SOV); billings from
  owner invoices; retainage from the G703 — all reused from `cost.py`.

Verified: `test_wip` (POC 50%, under-billed 200k asset flips to over-billed 200k liability, gross profit
+ margin, backlog, retainage, portfolio + PDF); ruff clean; web typecheck + vitest + build. Demo shows a
39%-complete job under-billed ~$7.8M — the profitable-but-cash-short story.

## v0.3.117 — Resource loading, made real: cost-loaded, relational, with leveling
Promotes resource loading from a flat crew-count (and no UI) to a relational, cost-loaded engine with a
panel — tying the schedule to resources and cost codes.

- **`resource_assignment` model** — ties a resource (Labor / Equipment / Material, with a rate) to a
  **schedule activity** and a **cost code**. That's the schedule ↔ resource ↔ cost join; the cost also
  rolls up onto the cost code (`resource_budget`).
- **Cost-loaded engine** — `resource_loading.py` now spreads assignment units + cost across each week
  into a **manpower histogram** (by trade / type) and cumulative **unit + cost S-curves**, with
  over-allocation flags against an availability cap. Falls back to activity `crew_size` when no
  assignments exist, so the classic curve still renders.
- **Leveling advisory** — `GET /schedule/resource-leveling?cap=` lists over-allocated work that still
  has **CPM total float** and can be smoothed (shifted within float) to shave the peak without moving the
  finish; critical-path work is reported as locked. Advisory only.
- **UI** — a `👷 Resource loading` panel (Schedule stage): editable availability cap, stacked-by-trade
  histogram, cost S-curve, KPIs (peak / total cost / over-allocated weeks) and the leveling table, plus a
  PDF report. Demo seeds six crews so the sample shows a real peak + leveling candidates.

Verified: `test_resource_loading` (cost-loaded histogram + S-curves, over-allocation, `resource_budget`
rollup, leveling picks the float-bearing work, crew_size fallback, PDF) + the module-contiguity gate;
ruff clean; web typecheck + vitest + build.

## v0.3.116 — Portfolio CPI (cost efficiency) in the executive roll-up
The cross-project executive dashboard already showed SPI + EAC + variance-at-completion per project;
it now also shows **CPI** — cost efficiency (EV ÷ AC) — so the "which jobs are bleeding money?"
question is answerable at the portfolio level alongside schedule.

- `px.summary()` gains a `cpi` in its budget block (EV/AC, the same numbers the project dashboard
  uses); surfaced per-project in `/portfolio/executive` and as a new **CPI** column (green ≥ 0.95,
  red below) next to SPI in the executive table.

Verified: `test_dashboard`; ruff clean; web typecheck + vitest + build. (Additive field — no
behaviour change to existing rows.)

## v0.3.115 — EVM charts: CPI–SPI quadrant + captured-snapshot performance trend
Two earned-value visualizations that make cost/schedule performance readable at a glance, plus the
persisted snapshots that back a real historical trend.

- **CPI–SPI quadrant (the "bullseye")** — a new `scatterQuadrant` chart plots the project and every
  control account on the cost × schedule plane, split at 1.0: upper-right is under budget + ahead,
  lower-left is trouble. Built from the existing EVM snapshot — no extra query.
- **Persisted EVM snapshots** — a new `evm_snapshot` module + `POST /projects/{id}/evm/snapshot`
  captures the current state (CPI/SPI/SPI(t)/EAC/% complete) as a dated baseline. `GET …/evm/trend`
  returns them oldest-first, and the dashboard shows a **CPI/SPI performance-index trend** (a falling
  line = efficiency slipping) with a 📸 Capture-snapshot button. The trend line also renders in the
  EVM PDF report once ≥ 2 snapshots exist.
- **Sample model** now seeds six weekly snapshots so the demo trend tells a real "schedule slipping"
  story out of the box.

Verified: `test_evm` (capture → trend, quadrant data, PDF with trend) + `charts` (scatterQuadrant plots
+ escapes) ; ruff clean; web typecheck + vitest + build.

## v0.3.114 — Element property + classification editor; sample model refreshed
Closes the model-authoring loop and brings the demo sample in line with everything shipped this cycle.

- **Structured property + classification editor** — selecting an element in the viewer now offers an
  **✎ Edit / Classify** form: set a Pset property (typed str/float/int/bool) and attach a
  **classification reference** (Uniclass 2015 · OmniClass · Uniformat II · MasterFormat), replacing the
  old free-text prompt. Backed by the `set_element_pset` and new **`set_classification`** edit recipes
  (GUID-stable; reuses one `IfcClassification` source per system so tags don't duplicate). Each edit
  re-publishes and the panel re-reads the element.
- **Model-based EV, no false alarms** — `evm.model_ev()` now only flags a *front-loaded SOV* once field
  verification actually exists (`has_field_data`); an un-surveyed job no longer reads as a distortion.
- **Sample model refreshed** — the Pages demo model now carries the full Draft-family set (steel
  columns/beams, rebar, footings, duct/pipe/cable-tray runs, ceiling + floor coverings, railing,
  electrical panel + sanitary terminal), realistic **EVM data** (cost-coded activities with EV methods +
  actuals → CPI/SPI, S-curve, Earned Schedule, model-EV) and a derived grid — surfaced across Model
  Analysis, Earned Value and the drafting refs.

Verified: `test_authoring_props` (Pset + classification round-trip) + `test_evm`; the model-authoring
+ structural/MEP/architectural/grid suites; typecheck + vitest (58) + build; ruff clean.

## v0.3.113 — Earned Value Management, E7: model-based EV (module complete)
The differentiator — earn value off the **physically installed model**, not a billing SOV — completes
the EVM module (E1–E7).

- **Model-based EV** (`evm.model_ev()` + `GET /projects/{id}/evm/model-ev`) — EV grounded in
  field-verified installed model elements (the install-coverage engine): **model % complete = installed
  elements ÷ total × BAC**, the units-complete method sourced from the model. It's independent of the
  schedule/billing %, so it **cross-checks the schedule EV**: when reported EV runs materially ahead of
  physical installation, it flags a likely **front-loaded SOV** — the exact distortion the research warns
  about. Surfaced on the EVM dashboard (with a ⚠ when divergent).
- With this the EVM module is complete: unified metrics + control accounts (E1), forecast family (E2),
  Earned Schedule (E3), S-curve + dashboard + report (E4/E5), EV measurement methods + stage-adaptive
  forecast (E6), and model-based EV (E7).

Verified: `test_evm` (model-EV graceful with no index + structure) + the full E1–E6 checks; typecheck +
vitest (56) + build; ruff clean.

## v0.3.112 — Earned Value Management, E6 + adaptive forecast
EV measurement rules of credit + the stage-adaptive forecast guidance from the construction-forecasting
research.

- **EV measurement methods** — `schedule_activity` gains an **EV method** (percent · **0-100** ·
  **50-50** · **units** · milestone · **LOE**) + units-complete/units-total. The engine honours the rule
  of credit: 0/100 earns nothing until complete; 50/50 earns half once started; units earns
  units_complete/units_total; **LOE earns exactly its planned value (EV=PV)** so it can't distort the
  schedule variance. Applied consistently in the metrics, S-curve, and Earned Schedule.
- **Stage-adaptive forecast guidance** — the forecast now flags the project **stage** and which forecast
  to trust: **early/mid → Earned Schedule (SPI(t))** is most accurate (cost EAC is volatile), **late
  (≥55%) → cost-efficiency (BAC/CPI)** firms up. Straight from the study finding that no single EAC
  formula is best at every stage. Shown on the EVM dashboard forecast card.

Verified: `test_evm` extended (0/100 → EV 0, 50/50 → 50k, units 3/4 → 75k; stage recommendation) +
`test_modules` (new fieldset passes the contiguity gate) + typecheck + vitest (56) + build; ruff clean.

## v0.3.111 — Earned Value Management, E4+E5: S-curve + EVM dashboard
Makes the EVM engine **visible** — an **📊 Earned Value** destination in the construction workspace.

- **S-curve** (`evm.scurve()` + `GET /projects/{id}/evm/scurve`) — cumulative **PV** (full planned
  baseline) plus **EV** and **AC** to the data date, over week/month buckets, drawn as the classic
  three-line performance chart (EV/AC lines end at the data date while PV runs to the planned finish). EV
  is reconstructed from each activity's actual window; AC from dated direct costs.
- **EVM dashboard** (`portal/panels/evm.ts`) — an indices dashboard (**CPI · SPI · SPI(t)** with health
  bands, CV/SV/SV(t)), the **forecast panel** (EAC family, ETC, VAC, TCPI + warning), the **S-curve**,
  the **Earned Schedule** summary (forecast finish + days-late), and the **control-account (cost code)
  table** — worst variance first.
- **EVM report upgraded** — the `evm` report now emits CPI/SPI/SPI(t), the full performance + forecast
  tables, Earned Schedule, control accounts, and the PV/EV/AC S-curve (was SPI + a cash curve).

Verified: `test_evm` extended (S-curve PV-full / EV-AC-to-date shape; upgraded report PDF renders) +
typecheck + vitest (56) + build; ruff clean.

## v0.3.110 — Earned Value Management, E3: Earned Schedule
Adds the modern **time-based** EVM extension that fixes the well-known defect where dollar SV/SPI decay
to $0 / 1.0 at project end regardless of lateness.

- **`evm.earned_schedule()` + `GET /projects/{id}/evm/earned-schedule?period=week|month`** — builds the
  time-phased **PV baseline curve** from the schedule, then projects current EV onto its time axis:
  **ES = C + (EV−PV_C)/(PV_{C+1}−PV_C)**, and from it **SV(t) = ES−AT**, **SPI(t) = ES/AT**, and
  **IEAC(t) = PD/SPI(t) → forecast finish date** (+ days-late). Included in the `/evm` snapshot too.
- SPI(t) stays meaningful right through completion, so a superintendent gets "**4 weeks behind, forecast
  finish 2026-XX-XX**" instead of a dollar SV that quietly returns to zero. The PV curve it returns is
  the same one the S-curve dashboard (E4/E5) will draw.

Verified: `test_evm` extended — a 40-week job at 40% complete in week 20 yields **ES ≈ 16 wk, SPI(t) ≈
0.80, forecast finish beyond plan** — plus the E1/E2 checks; typecheck + vitest (56) + build; ruff clean.

## v0.3.109 — Earned Value Management, E1+E2: unified engine + forecast family
Research-backed (PMI/ANSI-EIA-748 + a construction-forecasting study) EVM. The app had two disconnected
halves — schedule earned value (no Actual Cost) and cost actuals by cost code (heuristic forecast). This
**joins them by cost code (the control account)** into one standards-aligned metric set.

- **`evm.py` + `GET /projects/{id}/evm`** — PV, EV, AC, BAC; **CV = EV−AC, SV = EV−PV, CPI = EV/AC,
  SPI = EV/PV**, % complete, % spent, with **health bands** (good ≥1.0 · acceptable ≥0.95 · concerning
  ≥0.90 · critical). A **per-control-account (cost code) table** joins schedule EV/PV with cost AC, so you
  see which cost codes are over budget vs behind schedule.
- **Forecast family** — the four canonical **EACs** (BAC/CPI · AC+(BAC−EV) · AC+(BAC−EV)/(CPI×SPI)),
  a working EAC, **ETC**, **VAC**, and **TCPI** to BAC and to the working EAC — with the **>1.10
  structural-warning** flag. Shown together, because the best EAC is stage-dependent, not one formula.
- A `data_date` cut-off parameter for period reporting.

This is phase 1 of a full EVM module; Earned Schedule (SPI(t)), the time-phased S-curve + dashboard, EV
measurement methods, and **model-based EV from IFC quantities** follow.

Verified: `test_evm` (BAC 200k / EV 75k / PV 150k / AC 80k → CV −5k, SV −75k, CPI 0.938, SPI 0.5; the full
forecast family + TCPI warning; control-account join) + typecheck + vitest (56) + build; ruff clean.

## v0.3.108 — Model authoring: incremental preview fragments + MEP fittings
Completes the draft-performance work and rounds out MEP.

- **Incremental preview fragment** — `POST /projects/{id}/edit-preview` authors *just the placed element*
  into a minimal one-element IFC at the target level's elevation (`aec_data/preview.py`) and converts
  only that to a fragment, which the viewer loads immediately as real geometry — so the whole-model
  reconvert no longer gates what you see. Fully **fail-open**: if the source or converter is unavailable
  the viewer just keeps the optimistic amber proxy and waits for the normal publish. The preview is
  auto-disposed when the full model re-streams.
- **MEP fittings** — duct/pipe **elbows** and **tees / junctions** (`IfcDuctFitting` / `IfcPipeFitting`
  with BEND / JUNCTION predefined types) join the MEP palette, to detail the runs.
- **Testing & debug pass** — the new `test_preview` plus a regression sweep across the authoring and
  generate paths (`test_generate` / `test_estimate` / `test_engines` and the four model-authoring
  suites) all green, confirming the `edit.py` refactor (optional `profile` arg + the new recipes) didn't
  regress existing authoring.

Verified: `test_preview` (one-element metre model at the target level carrying the steel profile) + the
model-authoring + regression subset + web typecheck / vitest (56) / build; ruff clean.

## v0.3.107 — Model authoring, P6: optimistic draft placement
Drafting now gives **instant feedback** instead of a blank wait while the server authors and re-streams.

- **Optimistic proxy** (`viewer/draft/draftProxy.ts`) — the moment you place an element, a lightweight
  amber proxy (box for equipment, line for a wall/beam/duct/pipe/rebar/railing, polygon outline for a
  slab/roof/covering) appears exactly where it will land, at the active level. When the server finishes
  authoring the real IFC and the fragment is re-streamed, the proxy clears and the real geometry takes
  its place (proxies also clear on failure).

This is the client half of the draft-performance work; the server-side **incremental single-element
fragment** append (converting just the new element instead of the whole model) is the remaining
optimization and is tracked for a follow-up, since it touches the IFC→fragments publish pipeline.

Verified: web typecheck + vitest (56) + build.

## v0.3.106 — Model authoring, P3: architectural finishes (ceilings · tile · wood · cladding · railings)
Interior/finish elements complete the discipline set the Draft palette can author.

- **Coverings** (`IfcCovering`) drawn as a polygon: **ceiling** (hung near the top of the storey),
  **floor tile** (FLOORING + a ceramic-tile material), **wood flooring** (FLOORING + a Wood material),
  and **wall cladding** (CLADDING) — each by PredefinedType with an optional finish **material** and
  `Pset_CoveringCommon`.
- **Railings** (`IfcRailing`) drawn between two points at a set height.
- New `edit.py` recipes `add_covering` / `add_railing`; Architectural Draft entries for the four
  coverings + railing. Placement uses the P1 grid snap + active level.

With this the Draft palette spans all three disciplines (Architectural · Structural · MEP) — from grid
and levels to steel, rebar, MEP runs and equipment, and now finishes.

Verified: `test_architectural` (ceiling at 2.7 m, wood flooring material, cladding, railing) + typecheck
+ vitest (56) + build; ruff clean.

## v0.3.105 — Model authoring, P5: MEP families (HVAC · plumbing · electrical · fire · telecom)
The biggest discipline slice — draw distribution runs and drop equipment, authored as real IFC MEP.

- **Distribution runs** you draw as a segment: **duct** (`IfcDuctSegment`), **pipe** (`IfcPipeSegment`),
  **cable tray / conduit** (`IfcCableCarrierSegment`), and **cable / wire** (`IfcCableSegment`). Each is
  a swept section (round, or rectangular for tray) with two **connection ports** and assignment to a
  named **`IfcDistributionSystem`** (HVAC Supply / Domestic Water / Power).
- **Point equipment** you click to place: **electrical panel** (`IfcElectricDistributionBoard`),
  **outlet** (`IfcOutlet`), **light** (`IfcLightFixture`), **air diffuser** (`IfcAirTerminal`), **floor
  drain** (`IfcWasteTerminal`), **plumbing fixture** (`IfcSanitaryTerminal`), **fire alarm**
  (`IfcAlarm`), **smoke detector** (`IfcSensor`), and **data/telecom outlet**
  (`IfcCommunicationsAppliance`) — each with the correct IFC class + PredefinedType.
- New `edit.py` recipes `add_duct` / `add_pipe` / `add_cable_tray` / `add_wire` / `add_mep_terminal`;
  MEP entries fill out the Draft palette's MEP discipline. Placement uses the P1 grid snap + level.

Verified: `test_mep_families` (four run types + named systems + round/rect sections; seven point-
equipment classes with PredefinedType preserved) + typecheck + vitest (56) + build; ruff clean.

## v0.3.104 — Model authoring, P4: structural steel + rebar + footings
Real structural members in the Draft palette — authored as native, standards-compliant IFC.

- **Steel W-shapes** — `steel.py` holds the AISC W-shape table (W8×31 … W24×76, dimensions re-keyed as
  facts, [attributed](docs/ATTRIBUTIONS.md)); `add_steel_column` / `add_steel_beam` author an `IfcColumn`
  / `IfcBeam` with a **native parametric `IfcIShapeProfileDef`** (no imported geometry), with the section
  name stamped on `Pset_*Common.Reference`. A **Section** picker in the Draft form.
- **Rebar** — `add_rebar` authors a straight **`IfcReinforcingBar`** (circular section swept along the
  bar) sized by US bar designation (#3–#11) with `NominalDiameter` + `BarLength`.
- **Pad footings** — `add_footing` authors an `IfcFooting` pad below the level.
- Draft catalog gains a **`select`** parameter type (for the section / bar-size pickers); placement uses
  the P1 grid snap + active level.

Verified: `test_structural` (W-shape table inches→m; steel column → native IfcIShapeProfileDef W14×30 +
section on Pset; steel beam; #5 rebar nominal diameter + circular section; footing) + typecheck +
vitest (56) + build; ruff clean.

## v0.3.103 — Model authoring, P1: grid + levels as drafting references
The drafting reference frame — so placement lands on a grid and the right level, not free space.

- **Grid & Levels panel** in the Model tools rail. **Load grid + levels** reads the project's grid
  (`services/data/.../grid.py`): real **`IfcGrid`** axes (U/V + bubble tags) when present, else a grid
  **derived from `IfcColumn` centres** (numbered 1,2,3… / lettered A,B,C…). Axes render in 3D with
  bubbles; Draft placement now **snaps to grid intersections**.
- **Editable levels.** An active-level selector sets the **work-plane** (Draft points project onto the
  level's elevation) and passes the storey to every authoring recipe, so elements land on the chosen
  level. New `edit.py` recipes **add / rename / move** a storey (`add_storey`, `rename_storey`,
  `set_storey_elevation`) — authoring real `IfcBuildingStorey` levels.
- New endpoint `GET /projects/{id}/model/grid` (grid axes + snap intersections + storey levels).

Verified: `test_grid` (derived grid from 4 columns → axes 1/2/A/B + 4 intersections snapping to column
centres; add/rename/move-storey recipes) + web typecheck + vitest (56) + build; ruff clean.

## v0.3.102 — Model authoring, P0: the Draft panel (parametric family/element placement)
First slice of the "true model-creation program" upgrade — foundations for a full BIM family library
authored in the browser (intent) and written as real IFC on the server (source of truth), then
re-streamed as fragments.

- **Draft panel** in the Model workspace tools rail (`viewer/draft/`) — a discipline-grouped palette
  (Architectural · Structural · MEP · Site) of parametric elements and the server family catalog, each
  with a **named parameter form** (height, thickness, width, …). Pick an element, set parameters, arm
  **Place**, then click in the model: the server authors the IFC (walls, slabs, columns, beams, roofs,
  and any catalogued family) and streams it back. **Replaces the old `prompt()`-per-dimension flow** —
  no more native prompts for wall height/thickness. Supports point, two-point, and **polygon** (double-
  click to close) placement, with grid/vertex snap, ortho lock (Shift), and Esc to cancel.
- This is additive: the existing authoring recipes (`edit.py`) and the `/families/catalog` + `/edit`
  round-trip are unchanged; the Draft panel is a cleaner front-end over them. Structural depth (steel
  profiles + rebar), then MEP, then architectural coverings/finishes follow in subsequent releases,
  alongside real grid/level drafting refs.

Verified: `draftCatalog.test.ts` (recipe-param mapping for every element + family) + web typecheck +
vitest (56) + build green.

## v0.3.101 — Market intelligence & cost escalation + AI concept-render bridge
Two additions from an industry-research pass:

- **Market Intelligence & cost escalation** (`market_intelligence.py` + `market_assumption` module +
  `/market/*` endpoints + 💹 **Market Intelligence** panel in the developer workspace). A regional table
  (annual escalation %, average labour US$/hr, location index) plus a **two-speed warm/cold** demand
  signal by sector (tech-led sectors — data centres, advanced manufacturing — running hot; residential /
  commercial cold). The engine **escalates a base cost to the midpoint of construction** in the project's
  region — not just "next year" — reading a project's adopted `market_assumption` (region · sector ·
  construction start · duration) or query-param overrides. The **conceptual estimate now carries a market
  block** (regional labour + sector temperature + escalation-to-midpoint), and there's a **Market
  Intelligence & Escalation report**. Seed defaults are the **public headline figures** from Turner &
  Townsend's *Global Construction Market Intelligence 2026* — illustrative, **editable** defaults
  (attributed, not their dataset); a deployment overrides them with its own current rates.
- **AI concept-render bridge** (`render_bridge.py` + `concept_render` module + `/concept-render/*`
  endpoints + 🖼 **Concept Renders** panel in the design workspace). Like the CV-progress and RVT / payment
  bridges, it's **feature-flagged and off by default** (`AEC_RENDER_BRIDGE`): the platform builds a
  **grounded prompt** from the project's space program + massing and hands it to a connected image service,
  then ingests returned image references as reviewable `concept_render` records. When the flag is off, the
  endpoints report the bridge unavailable and **fabricate nothing** — no placeholder images. Reference
  adapter in `docs/render-bridge.md`.

Verified: new `test_market` (escalation-to-midpoint math, warm/cold signal, `market_assumption`-driven
context + escalate, conceptual-estimate market block, report PDF; bridge off fabricates nothing / on
builds a clamped grounded prompt + requires `image_url`) + full suite green, ruff clean; web typecheck +
build green.

## v0.3.100 — Close the two deferred perf items: compressed color-by + cross-worker scan cache
The two follow-ups the audit deferred are now done:

- **Compressed `color-by` + compact `ids=false` mode** — the viewer's colour-by needs the full
  GUID→bucket mapping (inherently O(elements)), so instead of capping it (which would break colouring) the
  large payload is now **gzipped on the wire** (`Content-Encoding: gzip`, transparently decompressed by
  the browser). A new **`?ids=false`** returns just labels + counts — a compact distribution for a legend
  or picker with no per-element payload.
- **Cross-worker scan cache** — the per-model-version cache for the hot `facets-list` / `color-by` scans
  is now **shared via Redis** (gzip+JSON values, TTL `AEC_SCAN_CACHE_TTL`, default 1 h) when
  `AEC_REDIS_URL` is set, so one worker's scan is reused by every other; **fail-open** to the in-process
  cache on any Redis error, matching `model_events` / the rate-limiter. Single-worker / no-Redis is
  unchanged.

Verified: new `test_scan_cache` (gzip round-trip, Redis fail-open, `ids=false`) + full suite green, ruff
clean. This closes every item from the four-dimension code audit.

## v0.3.99 — Audit follow-through (Batch 3): cache the hot model scans + windowed portfolio query
The deep-performance items from the audit — attacking the "recomputed on every request" cost of the
property-index scans:

- **Per-model-version scan cache** — the two hottest read scans (`elements/facets-list`, the O(n·psets)
  distinct-value scan, and `elements/color-by`) are now memoised keyed on the **model version**
  (`model_events`, bumped on publish). Repeated analytics requests for an unchanged model are served from
  cache instead of re-scanning every element × every property; the cache invalidates automatically when a
  new model is published, and evicts LRU-style (bounded).
- **Windowed portfolio scenario query** — `executive_portfolio` fetched **every** scenario's full result
  JSON across all projects just to keep the latest per project; it now uses a windowed
  `GROUP BY project → MAX(created_at)` join to load only the latest scenario per project.

(`color-by` still returns the full GUID→bucket mapping — the 3D viewer needs it to colour — so its payload
size is inherent; a compact run-length encoding is a tracked follow-up rather than a break-the-viewer cap.)

Verified: affected suites (analytics / portfolio / dashboard / api) green, ruff clean. Frontend bundle was
already healthy (code-split + Brotli budget) — no change. This completes the four-dimension audit
follow-through (Batch 1 perf/UX/analytics · Batch 2 demo data · Batch 3 deep perf).

## v0.3.98 — Audit follow-through (Batch 1): perf quick-wins, Documents a11y, surfaced analytics
A four-dimension code audit (wiring, UI/UX, sample data, performance) found the platform structurally
sound — **zero broken wiring** (46/46 routers, 47/47 reports, 32/32 module refs), all panels reachable.
This ships the low-risk quick wins from it:

- **Performance:** dashboard/AI-ask/closeout counts now use a SQL `COUNT` (`count_records`) instead of
  materialising whole JSON tables just to call `len()`; `properties/index` upload parses off the event
  loop (`run_in_threadpool`) and stores the received bytes verbatim (no redundant re-serialize); the
  document-manager `tree()` computes its active-file set once instead of per folder node.
- **Documents file manager (a11y + UX):** the folder tree is now keyboard-operable (`role`/`tabindex`/
  Enter-Space) instead of mouse-only; delete uses the app's accessible modal instead of the native
  `confirm()`; the two-pane layout wraps to stacked on narrow viewports; a **role filter** (PM /
  Superintendent / Architect / Engineer / QS) and a **phase-gap check** (AIA SD/DD/CD/CA/CLOSEOUT) are
  now surfaced (they reuse the by-role and phase-gaps endpoints that were built but unwired).
- **Surfaced built-but-invisible analytics:** the 🔬 Model Analysis panel now shows the **fast STEP model
  summary** (entity-type histogram, no full parse — G3), the **columnar interning efficiency** stat + an
  **EAV `params.parquet`** download (G1), and a **VIM / G3D inspect** control (G2); export links are gated
  on a loaded model (no raw 409s), and Documents + Model Analysis are now reachable from the **developer**
  workspace too.
- **A11y polish:** `th scope="col"` + `aria-label`s on the Model Analysis tables/selects.

Verified: full backend suite green, web typecheck + vitest 49/49, ruff clean.

## v0.3.97 — Ara3D-inspired efficiency track: columnar BIM data, BFAST/VIM reader, fast STEP scan
Three efficiency/interop wins drawn from a review of the [Ara3D SDK](https://github.com/ara3d/ara3d-sdk)
(MIT; see [ATTRIBUTIONS](docs/ATTRIBUTIONS.md)) — ported/adapted where it added value, skipped where our
numpy/trimesh/ifcopenshell stack already wins.

- **Columnar / interned BIM data layer** (`bim_columns.py`, inspired by Ara3D `BimOpenSchema`) — a
  **string/number-interned columnar** view of the property index + an **EAV parameter table** exported as
  **Parquet** for DuckDB/pandas/Polars analytics. Psets repeat the same keys/values across thousands of
  elements, so interning cuts RAM sharply (a small 4-wall fixture already shows ~3.4× string dedup). New
  endpoints: `/model/columnar/stats` (dedup ratio + estimated bytes saved), `/model/columnar/aggregate`
  (group-by via pyarrow compute — no Python row loop), `/model/export/params.parquet`.
- **BFAST / G3D / VIM reader** (`aec_data/bfast.py`) — a pure-Python reader/writer for the BFAST container
  + summarisers for G3D geometry (vertex/index counts + bbox) and VIM files (schema/version, buffer
  inventory, geometry stats). Opens `.vim` / `.g3d` offline via `POST /convert/vim/inspect`. Independent
  re-implementation of the public format; no Ara3D code copied.
- **Fast STEP metadata scanner** (`aec_data/step_scan.py`) — a streaming line-scan of an IFC-SPF file for
  its header + **entity-type histogram** without a full `ifcopenshell` parse (milliseconds, bounded
  memory). `GET /model/step-summary` for an instant "what's in this IFC" on large files.

Also reviewed the OpenAEC-BIM-validator repo — no integration needed: we already validate IFC against IDS
via `ifctester` (per-spec pass/fail + failing GUIDs + BCF) in `aec_data/validate.py`. Verified: new
`test_bim_columns` / `test_bfast` / `test_step_scan` + full backend suite green, web build green, ruff clean.

## v0.3.96 — Document Control: a role-based standard file manager over the project
A first-class **📁 Documents** workspace — an elFinder-style two-pane file manager (folder tree + file
list) built on a **standard, role-based project folder taxonomy** so every project is organised the same
way and required documents are never missing.

- **Standard taxonomy** (`folder_template.py`) — the industry `01_Contract Documents … 11_Final Account`
  tree with sub-folders, each node tagged with an **owner role** (PM owns the business — contracts,
  payments, variations, procurement; the **Superintendent** owns field execution — site instructions,
  inspections, NCRs, daily reports, photos; the **Architect/Engineer** own the drawing set), a discipline
  (NCS), a default **CDE state** (ISO 19650 WIP/Shared/Published) and a **required** flag.
- **Document manager** (`docmanager.py`) — bytes in object storage (`{pid}/docs/<folder>/<name>`) with a
  per-project sidecar index. Uploads **auto-name to the information standard**
  (`Type_Discipline_Description_Revision_Date`) and **never overwrite**: a new upload of the same document
  supersedes the prior revision (P01→P02…), the old one archived for audit. Move, soft/hard delete,
  download, per-folder counts that roll up to parents, and required-doc **gap** flags.
- **Role-based views** — a `by-role` endpoint and owner-role chips per folder, so a PM / Superintendent /
  architect sees the folders they own.
- **Document-Control health** — a Report Center report (naming compliance, required-folder coverage,
  revision control, CDE-state spread, orphans) + AIA **phase-gap** checks (SD/DD/CD/CA/CLOSEOUT flag the
  documents a phase is missing, e.g. a CD set lacking structural drawings).
- **Web**: the 📁 Documents destination in the Construction and Design workspaces — clickable folder
  tree, upload (auto-named, supersede-aware), download, move, delete, and a health strip.

Reuses the discipline spine (NCS), the ISO 19650 CDE states, the naming validator, and the storage
backend already in place. Verified: new `test_docmanager` + full backend suite green, web typecheck +
vitest 49/49, ruff clean.

## v0.3.95 — Close the five deferred slices: Parquet + glTF export, CV bridge end-to-end, live 2D propagation, IFC5 data reads
The items previously scoped as "needs a dependency / external service / upstream support" are now shipped
as far as each honestly can be:

- **Parquet export** — added `pyarrow`; `GET /model/export.parquet` writes a Snappy-compressed columnar
  file (DuckDB / pandas / Polars), alongside the existing CSV + JSON-LD. Returns a clean 503 (never a
  500) if the optional dep is absent.
- **glTF geometry export** — `GET /model/export.gltf` triangulates the model with the same
  `ifcopenshell.geom` iterator the section/clash tools use and writes a **self-contained glTF 2.0**
  (binary buffer embedded as a data-URI), meshes merged per IFC class with per-class colours, Z-up→Y-up.
  The viewer still streams Fragments — this is the portable geometry-*out* path (Blender / Three.js /
  any DCC). Honest scope: triangulated meshes + flat colours, no PBR/textures.
- **CV site-progress bridge, end-to-end** — the feature-flagged bridge now resolves an activity by **id
  or name**, accepts a **batch** (`/cv-progress/ingest-batch` — the per-photo-sweep shape), and writes
  straight to `schedule_activity.percent`. A runnable **reference adapter** ([docs/cv-bridge.md](docs/cv-bridge.md))
  documents the HTTP contract so any vision service wires in. Still no bundled model — that stays external
  by design — but the entire integration surface is complete and tested.
- **Live 2D propagation** — a per-project **model version** bumps whenever a new model is published;
  `GET /drawings/sync-status` surfaces it and `GET /drawings/stream` (SSE) **pushes** the change, so open
  on-demand 2D views regenerate themselves. Single-worker uses an in-process registry; **multi-worker
  shares it via Redis** (atomic `HINCRBY`, keyed off `AEC_REDIS_URL`) so a publish on any worker reaches
  a stream on any other — fail-open to in-process if Redis blips, matching the rate-limiter/lockout.
- **IFC5 / IFCX / ifcJSON data reads** — a tolerant JSON reader parses these into the same element-index
  shape a STEP model produces, so analytics, LOD/naming/envelope audits and CSV/JSON-LD/Parquet export all
  work on an IFC5 file **now**. Capabilities report it as `ifc5: data` (geometry rendering still lands
  upstream when web-ifc / Fragments add it).

Web: the 🔬 Model Analysis panel gains an **Export** row (CSV / JSON-LD / Parquet / glTF) and reflects the
IFC5 data-read distinction. Verified: 6 new/extended backend suites green, web typecheck + vitest 49/49,
ruff clean.

## v0.3.94 — Model Analysis panel: the new model-reading tools, first-class in the UI
A consolidated **🔬 Model Analysis** destination in the Design workspace surfaces the model-reading
endpoints that previously had no bespoke UI (the register-backed features already had module CRUD +
Report Center reports): **IFC capabilities** (supported schemas + the loaded model's detected schema,
IFC5/IFCX reported), a **model query** (saved views — count by discipline / class / storey / type),
**LOD coverage**, **envelope code compliance**, **MEP counts off the model**, and **naming compliance**.
Each section loads independently and degrades gracefully when no model is published. New client methods
wrap the endpoints; the panel follows the extracted-panel (`PanelContext`) pattern. Verified: web
typecheck clean, vitest 49/49, build green, **and live** — booted the full dev stack (API on :8093 +
Vite), navigated to Design → Model Analysis; all six sections render with zero console errors, and IFC
capabilities correctly detected the loaded model as IFC4.

## v0.3.93 — Deferred-item slices: model-driven MEP, staleness, schema detect, CV write-path
The tractable slice of each remaining backlog item (the fuller versions need infrastructure noted below).
- **Model-driven MEP extraction (C1x)** — `mep.extract_from_model` reads MEP elements off the loaded
  model by IFC class (ducts / pipes / terminals / equipment / electrical), counted by class + discipline.
  `GET /mep/model-extract`, and the MEP Equipment Schedule report now shows model counts beside the register.
- **Model-staleness signature (B2x)** — `GET /drawings/sync-status` returns a cheap fingerprint of the
  loaded model (element count + GlobalId hash); the client compares it across renders to know when the
  on-demand 2D is stale. The tractable slice of live-2D propagation, without an event bus.
- **IFC schema detection + capabilities (D4x)** — `GET /model/capabilities` sniffs the source model's
  header, reports the detected schema (IFC2X3 / IFC4 / IFC4X3), and **detects IFC5/IFCX (JSON) and says
  plainly it's not yet parsed** rather than failing cryptically. The read path still lands upstream.
- **CV bridge write-path (E2x)** — with `AEC_CV_BRIDGE` on, `POST /cv-progress/ingest` now **writes the
  estimate to the named schedule activity's percent** (a bad id is handled, not a 500). A real CV service
  now has a working endpoint to drive progress; the vision model remains external.

Still genuinely deferred (need infra, not effort): **Parquet export** (needs the `pyarrow` dependency —
a decision, not built by default), **glTF geometry export** (needs the geometry pipeline), a **real CV
model** (external service), and **full auto-propagate-on-edit** (needs an event bus). Backend 129/129,
ruff clean.

## v0.3.92 — Field AI: labor productivity + CV progress bridge (Phase E)
The final phase of the upgrade initiative.
- **Field labor productivity (E1)** — a new `productivity_log` register (quantity installed · workers ·
  hours) + `productivity.py`: **units per man-hour** per entry, rolled up by trade, with an overall rate.
  `GET /productivity/summary` + a **Field Labor Productivity** report. The field-productivity signal
  Rhumbix-style tools surface, on the same project record.
- **Computer-vision site-progress bridge (E2)** — real CV % complete needs an external vision model, so
  this is a **feature-flagged bridge** (like the RVT and money-processor bridges): with `AEC_CV_BRIDGE`
  off (default) the endpoints report the bridge as unavailable and **fabricate nothing**; an operator
  enables the flag and connects a CV service that POSTs estimates to `/cv-progress/ingest` (clamped
  0–100). `GET /cv-progress/status` documents the contract.
Backend 128/128, ruff clean. **The A–E upgrade initiative (authoring depth · design engine · engineering
depth · interoperability/analytics · field AI) is complete** — 16 items across v0.3.87–v0.3.92.

## v0.3.91 — Interoperability & analytics: model query + data export + envelope compliance (Phase D)
The ifc-lite-inspired items, on our server-Fragments architecture.
- **Model analytics query (D1)** — `model_query.py` + `GET /model/query`: group elements by any
  attribute (ifc_class / discipline / storey / type / `Pset::Property`) and **count** them or **sum a
  quantity** from the IFC quantity sets, with filters and four saved views. The "ask the model a
  question" analytics without shipping the model to the browser.
- **Model data export (D2)** — `GET /model/export.csv` (columnar, one row per element) and
  `GET /model/export.jsonld` (a JSON-LD graph, bSDD-style vocab, GlobalId as `@id`). No external
  dependency. (Parquet + glTF geometry export remain future items.)
- **Envelope code-compliance (D3)** — new `envelope_assembly` register + `envelope.py`: opaque
  assemblies checked against IECC 2021 minimum R-values and fenestration against maximum U-factors by
  climate zone. `GET /envelope/{audit,check}` + an **Envelope Code Compliance** report. A first-pass
  screen, not a stamped energy model.
- **IFC5 / IFCX (D4)** — tracked as a watch-item; the read path lands when web-ifc / Fragments ship
  IFC5 support.
Backend 127/127, ruff clean. Phases A–D of the authoring/design/engineering/interop initiative complete.

## v0.3.90 — Engineering depth: MEP sizing/schedules + resource-loaded scheduling (Phase C)
- **MEP engineering (C1)** — a new `mep_equipment` register (equipment schedule) + `mep.py` with
  deterministic first-pass calculators: **duct sizing** (equal-velocity), **pipe sizing** (velocity
  method → nominal pipe size), **cooling load → tonnage** + a block-load rule-of-thumb, and
  **hanger/support spacing** (SMACNA for duct, MSS SP-58 for pipe). `GET /mep/schedule` rolls the
  equipment up per system; `GET /mep/size` is a stateless sizing calc. An **MEP Equipment Schedule**
  report with sizing reference tables. Extends the D5 parametric MEP (which lays the geometry) with the
  numbers behind it.
- **Resource-loaded scheduling (C2)** — schedule activities gain a **crew_size**; `resource_loading.py`
  buckets every week an activity spans and sums concurrent crew into a **resource histogram** (by trade
  + total), a cumulative **man-week S-curve**, **peak manpower**, and **over-allocation** flags against
  an optional `?cap=` availability. `GET /schedule/resource-loading` + a **Resource-Loaded Schedule**
  report (histogram + S-curve charts). Rides on the existing CPM schedule.
Backend 125/125, ruff clean.

## v0.3.89 — The design engine: options / variants + standards ruleset (Phase B)
Design-side depth so a project can carry, compare and standardize schemes.
- **Design options / variants (B1)** — a new `design_option` register (program + economics per scheme)
  and `GET /design/options/compare`: options compared apples-to-apples with **best-in-class per metric**
  (lowest cost/sf, lowest EUI, highest IRR, largest area, highest efficiency), deltas vs the **selected**
  option, and a state rollup (proposed → shortlisted → selected → rejected). A **Design Options
  Comparison** report (PDF + Excel).
- **Selected-option → drawing linkage (B2)** — each option references a `drawing_set`; the selected
  option's set is the project's current documentation. The 2D drawings (plan / section / elevation /
  sheet) already **generate on demand from the live model**, so they reflect the current state whenever
  requested. (Full auto-propagate-on-every-edit — Higharc-style instant regeneration — remains a future
  item; it needs event wiring on top of the parametric model.)
- **Design standards ruleset (B3)** — a new `design_standard` register (approved / preferred /
  prohibited assemblies, materials, products) with `GET /design/standards` + `GET /design/standards/check`:
  the loaded model is audited against the ruleset — elements are flagged when their type/material matches
  a **prohibited** standard, or (when an approved set is declared) match nothing approved. Keyword-based on
  the openBIM property data the model already carries. A **Design Standards Compliance** report.
Both registers get CRUD via the module engine; both reports surface under a new **Design** group. Backend
123/123, ruff clean.

## v0.3.88 — Authoring depth: LOD matrix + naming-convention validator (A2 + A3)
Completes the authoring-depth phase.
- **LOD matrix & coverage (A2)** — a new `lod_target` register (stage × discipline × element-category →
  LOD 100–500; RIBA/AIA stage defaults when empty) plus an **achieved-LOD assessment** of the loaded
  model. Achieved LOD is *inferred* from the same LOIN facet completeness the quality scorecard scores
  (geometry/type/classification/properties/quantities) and capped at LOD 400 — LOD 500 is a verified
  as-built assertion, not a model read. Endpoints `GET /lod/matrix` + `GET /lod/assessment`, and a
  **LOD Matrix & Coverage** report (target matrix + achieved distribution + per-discipline average).
- **Naming-convention validator (A3)** — validates document/container filenames against
  `Type_Discipline_Description_Revision_Date` (revision-controlled) and drawing sheet numbers against
  the **NCS Sheet ID** grammar (reusing the D3 parser). `GET /naming/{conventions,validate,audit}` and
  a **Naming Convention Compliance** report that audits the CDE containers + drawing register with
  compliance % and a violation list.
Both surface automatically in the Report Center (Quality group, PDF + Excel); the LOD targets get CRUD
via the module engine. Backend 122/122, ruff clean.

## v0.3.87 — BEP generator: the ISO 19650 BIM Execution Plan as a produced document (A1)
The first of an authoring-depth initiative (informed by an industry-practice scan). We already held the
information-requirements register (EIR/BEP/AIR), the CDE, the discipline vocabulary and the delivery
register — now they **assemble into a produced BIM Execution Plan**. A new Report Center entry (**Quality**
group, PDF + Excel) composes the ISO 19650 BEP: an information-requirements register, a **roles,
responsibilities & authorities** matrix (appointing party / lead appointed party / information manager +
an authoring lead per discipline), the **Level of Information Need** targets by delivery stage (LOD
200→500), the **information-delivery schedule** (from the drawing/delivery sets), **information standards
& naming** (NCS sheet IDs + `Type_Discipline_Description_Revision_Date` + MasterFormat/Uniformat
classification), the **CDE workflow** (WIP→Shared→Published→Archived with revision/approval coverage), and
the **model-coordination & QA** process — with core EIR/BEP/AIR coverage flagged. No new data entry: it
reads the registers you already keep. Next in the phase: a per-element **LOD matrix** (A2) and a
**naming-convention validator** (A3).

## v0.3.86 — Code standards S3: lint lock-in (consistency enforced in CI)
The final phase of the standards initiative — the PEP 8-aligned rules the S1 pass satisfied are now
**enforced in CI**, so they stay satisfied. Ruff's rule set expands from correctness-only
(`F`, `E9`, `B`) to add:
- **`I`** — import ordering (isort), with `aec_api`/`aec_data` pinned as first-party.
- **`UP`** — pyupgrade: modern syntax for the Python 3.10+ target.
- **`C4`** — flake8-comprehensions: no needless comprehensions or collection calls.

Nine residual violations (unnecessary comprehensions, `%`-format strings, a redundant `dict()` call)
were cleaned up by hand — all behaviour-preserving. Deliberately **not** enforced, with the rationale
recorded inline in `ruff.toml`: line-length (`E501`) and one-statement-per-line (`E702`), because the
codebase intentionally uses compact one-liners and dense table/PDF/SVG builders; and `RUF100`, because
it would strip the intentional `# noqa: BLE001` annotations that document the logged fail-open idiom.
**120/120 backend suites pass**; no runtime change.

## v0.3.85 — Code standards S1: safe PEP 8-aligned auto-fixes
A mechanical, behaviour-preserving compliance pass across the Python backend (`services/api` +
`services/data`) — the first of a phased standards initiative. Ruff's **safe** auto-fixes only:
- **Import ordering** (isort / PEP 8) — imports sorted into stdlib / third-party / first-party groups.
- **pyupgrade** — deprecated import paths, quoted annotations, and old-style `%` formatting modernized.
- **Comprehension simplifications** — unnecessary `dict()`/`list()` comprehensions and calls collapsed.
- **`contextlib.suppress`** in place of `try/except/pass`.
~200 fixes across 52 files. No behaviour change (**120/120 backend suites pass**, imports clean). The
codebase's deliberate compact idiom (compact one-liners, unused FastAPI-DI args, typographic unicode) is
intentionally preserved. Line-length wrapping (S2) and CI lock-in (S3) follow.

## v0.3.84 — Discipline Spine D5b: parametric MEP generation (spine complete)
The generator now produces real **parametric MEP distribution**, so a generated building reads as a
layered structural / architectural / **MEP** model — completing the five-phase Discipline Spine.
- Beyond the two core risers, each floor gets a **supply-air duct main** and a **domestic-water main**
  at ceiling height plus **ceiling diffusers on a ~bay grid** (`IfcFlowTerminal`, air-terminal). Fully
  parametric — the mains span the plate and the diffuser count scales with the floor size and bay.
- The new elements classify to the right disciplines automatically (D2): ducts + diffusers →
  **Mechanical**, pipes → **Plumbing** — so colour-by-discipline and the `?discipline=` filter show the
  MEP layer, and the takeoff/spine pick it up. Verified: a 7-floor model generates 14 duct segments,
  14 pipe segments and 112 diffusers, correctly disciplined.

**Discipline Spine complete (D1→D5):** shared NCS/MasterFormat vocabularies → discipline-tagged elements
→ discipline sheets + sets → connected spec/bid/cost-code traceability → discipline-aware generation
with parametric MEP. The model, the documents and the money are one traceable thread. (A true multi-file
federation split of the generated model — separate STR/ARCH/MEP IFCs sharing one grid — and a first-class
`IfcGrid` remain as optional model-realism follow-ups; the layered reading already works via the
discipline tagging.)

## v0.3.83 — Discipline Spine D5a: generation seeds a connected spine
Generating a project now produces a **fully-connected discipline spine** out of the box, not just a
model + budget. The GC-portal seeder that already creates cost codes now also seeds a **bid package per
discipline** (Structural / Architectural / Mechanical / Electrical), each linked to its cost code, and a
**spec section per division** linked to that package — so a freshly generated project is **100%
traceable model → specs → bid packages → cost codes → budget** the moment it exists.
- Discipline budgets are computed from the same hard-cost division fractions (Structural, Architectural,
  Mechanical, Electrical), so the seeded packages reconcile with the GMP.
- `test_disciplines` extended: a generated project shows 100% specs-packaged / packages-costed /
  spec-to-budget and every spec fully linked. Reuses the D1 classification vocabulary + the D4 links.
- First half of D5 (discipline-aware generation); D5b adds a real `IfcGrid` + parametric MEP depth.

## v0.3.82 — Discipline Spine D4: connect the procurement chain (traceability)
The payoff phase — the model, the documents and the money are now one connected thread, with the broken
links surfaced so scope can't fall between them.
- **Links wired**: `spec_section` gains **`bid_package`** (which package procures this spec) + a
  discipline field; `bid_package` gains a **`cost_code`** reference + discipline. Spec→bid is N:1, the
  correct direction — a package's specs are all the specs pointing to it.
- **`spine.py` traceability engine** + `GET /projects/{id}/spine/traceability` — traces
  **discipline → sheets → specs → bid packages → cost codes → budget**, with per-discipline rollups
  (sheets/specs/packages/cost-codes/budget) and **coverage bars** for each join (sheets→spec,
  specs→package, packages→cost-code, spec→budget). Discipline is resolved consistently — from the field,
  else derived from the MasterFormat division or the NCS sheet number.
- **Coverage gaps** list the broken links: unpackaged specs, unbudgeted packages, un-specced sheets.
- New **🔗 Discipline Spine** panel (Design workspace): coverage bars, budget-by-discipline chart,
  the gap lists, and the spec→package→cost-code trace. `test_disciplines` extended. Fourth of five phases.

## v0.3.81 — Discipline Spine D3: discipline-tagged drawing sheets + sets
Drawing sheets now read as a proper **discipline-ordered set**, and each sheet links to the specification
and drawing set it belongs to — the documentation layer of the spine.
- **NCS Sheet ID parsing** (`drawingset.parse_sheet_id`) — `A-101` → discipline **A** (Architectural),
  sheet type **1** (Plans), sequence **01**. The drawing-set register now carries the parsed sheet ID on
  every sheet, derives the discipline from the sheet number when the field is blank, and **orders the
  sheet index the way a set is bound** — by NCS discipline (General → Civil → Structural → Architectural
  → MEP), then sheet number.
- **`drawing_set` module** — named issued sets (Schematic Design / Permit / Bid / Issued for Construction
  / Record) with discipline, issue date and purpose.
- `drawing` gains **`drawing_set`** and **governing `spec_section`** references (the sheet→spec link that
  feeds D4) plus issued-date / revision-purpose fields.
- `test_disciplines` extended. Third of five phases (D1→D5).

## v0.3.80 — Discipline Spine D2: discipline-tagged model elements
Every model element now carries its **NCS discipline**, derived from its IFC class through the D1
MasterFormat map — so the model reads as layered structural / architectural / MEP even from a single
federated file, with no republish and no extra scan (pure function of the already-indexed IFC class).
- `GET /projects/{id}/elements?discipline=S` (accepts an NCS code **or** name) filters the property
  index; every element is returned with its derived `discipline`.
- `GET /projects/{id}/elements/by-discipline` — model composition: element count + IFC-class breakdown
  per discipline, in NCS sheet order (Structural → Architectural → MEP).
- **Discipline** is now a first-class **colour-by facet** — it appears automatically in the viewer's
  "Colour by…" picker and buckets the model by discipline in 3D (no client change needed).
- `test_disciplines` extended. Second of five phases (D1→D5) of the model→sheets→specs→bid→budget spine.

## v0.3.79 — Discipline Spine D1: shared classification vocabularies
The foundation for representing a project as layered **structural / MEP / architectural** models whose
sheets, specs, bid packages and budget all thread through two shared, validated vocabularies (rather
than free text). Based on the US National CAD Standard discipline designators + CSI MasterFormat.
- **Discipline vocabulary** (`classification.py`) — the NCS discipline designators (**A** architectural ·
  **S** structural · **M** mechanical · **E** electrical · **P** plumbing · **F** fire · **C** civil ·
  **T** telecom · **G/L/Q**), each with its default MasterFormat divisions + Uniformat groups.
  Derives an element's discipline from its IFC class (via the existing MasterFormat map), and normalizes
  legacy free-text values (e.g. "MEP" → M, "Geotechnical" → C).
- **MasterFormat division master** (25 divisions) + the **Uniformat II ↔ MasterFormat crosswalk** that
  migrates a concept-phase budget into the procurement budget.
- `GET /reference/disciplines` serves all three catalogs (drives the selects + the spine joins).
- Converted the free-text `discipline` (drawings) and CSI `division` (cost codes, spec sections) fields
  to validated **selects**. `test_disciplines`. Deterministic, no new deps. First of five phases
  (D1→D5) building the model→sheets→specs→bid→budget spine.

## v0.3.78 — Performance: trim the physical-climate-risk fan-out
Tightens the scans behind the physical-climate-risk rollup that feeds the ESG scorecard.
- The rollup previously ran the full weather engine — including a scan of `schedule_activity` (one of
  the larger tables) — even though it only needs the site-weather register and the logged delay days.
  Split out a `_weather_exposure` helper so `climate_risk` (and therefore every **ESG summary** load)
  no longer scans `schedule_activity` at all.
- Made `climate_risk` composable: the resilience **report** now passes in the flood / stormwater /
  exposure it already computed instead of recomputing those scans a second time.
- No behaviour change (rollup output is byte-identical); verified. Backs the config-module engine that
  already ships every tool's CRUD, CSV export, kanban board and workflow-flowchart for free.

## v0.3.77 — Real-time collaborative pull board (M3)
The Last Planner pull board becomes a live, multi-trade workspace — every stakeholder edits the same
board and sees each other's changes as they happen, without a page refresh.
- **Live board** — a lightweight Server-Sent-Events stream (`GET /projects/{id}/pull-plan/stream`)
  polls a cheap board change-signature (row count + latest `modified_at`) server-side and pushes it
  when it moves, so the board auto-refreshes the moment any trade adds or moves a sticky note. A
  **🟢 live** indicator sits in the board header.
- **Presence** — reuses the existing presence infra: a heartbeat marks who else is on the board and
  renders **👤 peer chips** in the header (self-cleans when you leave the view).
- **Edit locks / no silent overwrite** — records now expose `modified_at`, and the record editor sends
  it back as an optimistic lock: if someone changed the record while you had it open, the save returns
  **409** (rather than clobbering their edit) and the editor reloads the latest with a *"re-apply your
  edit"* nudge. Opt-in and backward-compatible — an un-locked write still succeeds.
- Reuses the SSE + presence primitives already in the codebase — **no new dependencies**, no CRDT.
  `test_pull_realtime`; the lock is generic (available to every module, not just the pull board).

## v0.3.76 — Climate resilience: weather-sequenced construction + physical-risk rollup (W3–W4)
Extends the **🌊 Climate Resilience** panel from the design phase into construction and up into ESG.
- **Weather-sequenced construction (W3)** — a `weather_sensitivity` flag on schedule activities (rain /
  wind / freeze / heat) so exposed work can be sequenced out of the wet/freeze season, plus a new
  `climate_site_risk` register (hazard type, exposure season, severity, controls) for standing
  site-weather hazards. **Weather-delay days** roll up automatically from the daily reports'
  weather-impact field. Reachable in the construction **Build** stage as well as design/developer.
- **Physical climate-risk rollup (W4)** — a scored **Low / Moderate / High / Severe** rating that
  folds flood-plain exposure, assets below the Design Flood Elevation, open site-weather hazards and
  logged weather delays into one number with its driving factors — and feeds the **ESG scorecard**
  (`physical_risk`).
- Endpoints `GET /projects/{id}/resilience/weather` + `/resilience/climate-risk`; the Resilience
  report gains the rating, the site-weather register and the risk factors; `test_resilience` extended;
  demo seeded. Deterministic — no new deps, no external calls.

## v0.3.75 — Climate & water resilience: flood + stormwater (W1–W2)
Treat rainfall and flooding as **quantifiable design parameters** — a new **🌊 Climate Resilience**
panel in the Design (and Developer) workspace.
- **Flood risk (ASCE 24 / FEMA)** — a `flood_risk` assessment (FEMA zone, Base Flood Elevation, Flood
  Design Class, freeboard) computes the **Design Flood Elevation** (DFE = BFE + freeboard, ASCE 24
  minimum by class) and runs the **flood-proof-MEP check**: any Asset Register item whose new
  *Installed Elevation* is below the DFE is flagged to be elevated or flood-proofed. Flags whether the
  site is in a Special Flood Hazard Area.
- **Stormwater (Rational Method)** — a `drainage_area` (catchment) module → peak runoff **Q = C·i·A**
  (runoff coefficient × rainfall intensity × area), composite C, and a first-order detention volume,
  so drainage is sized against a real design storm rather than guessed.
- Endpoints `GET /projects/{id}/resilience/flood` + `/resilience/stormwater`; a Report Center entry
  (flood + stormwater, PDF/Excel); `test_resilience`; demo seeded. Deterministic — no new deps, no
  external calls.

## v0.3.74 — Docs + hardening pass (M1/M2 consolidation)
- **Docs**: README (operations + schedule) and the in-app guide now cover the Facility Condition
  Index and the pull-planning reliability analytics.
- **Security**: reviewed the new operations/schedule endpoints — authorization matches the existing
  patterns (`current_user` for the cross-project roll-ups, `require_role("viewer")` for project-scoped
  reads); no money movement (facility-condition is cost *estimation* only); no new dependencies or
  outbound calls. Bandit + ruff clean (tightened the portfolio roll-up's defensive catch to log
  rather than swallow). Full backend suite (117) + web typecheck green; live console clean across the
  new panels.

## v0.3.73 — Pull-planning reliability analytics (M2)
Deeper Last Planner metrics on the pull-plan board — the learning-loop signals a team improves week
over week, beyond a single PPC number.
- **`pull_plan.metrics()`** — **Tasks-Made-Ready %** (are constraints cleared ahead of the work?),
  **make-ready runway** (weeks of ready work staged), **perfect-handoff %** (predecessor done and
  successor ready ÷ hand-offs), **PPC trend by week**, and the **variance-reason Pareto** (why
  commitments miss). Endpoint `GET /projects/{id}/pull-plan/metrics`.
- **Cross-project benchmark** — `benchmarking.pull_planning()` + `GET /benchmarks/pull-planning`:
  the PPC and TMR distribution across every project vs the ≥80% target, so a plan is judged against
  the team's own portfolio.
- **Board Analytics view** — a 📊 Analytics toggle on the Pull Planning card renders the reliability
  chips (PPC / TMR / perfect hand-offs / runway), the PPC-trend and variance-Pareto charts, and the
  portfolio benchmark. Test coverage extended; demo seeded.

## v0.3.72 — Facility Condition Assessment + FCI (operations phase, M1)
A facility-condition capability for the operate phase: assess building elements, price their
deficiencies, and score the asset's condition — the metric owners and facility managers use to
prioritize capital.
- **`fca_element` module** (Operations; construction + developer) — one record per building element:
  UNIFORMAT II group, linked building system, condition rating (1 Excellent…5 Critical), install /
  expected-life / replacement cost, deficiency + repair cost, recommended year, photo. Workflow
  identified → planned → funded → resolved (resolved leaves the backlog).
- **`fca.py` engine** — **Facility Condition Index** = (deferred maintenance + capital renewal) ÷
  current replacement value, with the band (Good <5% · Fair 5–10% · Poor 10–30% · Critical >30%), the
  deferred/renewal split, and breakdowns by UNIFORMAT group, condition, worst elements, and
  recommended-year forecast. A **portfolio** roll-up ranks buildings worst-first for capital
  prioritization. FCA deficiency costs now also feed the **reserve study** (condition-based, not just
  age-based).
- Endpoints `GET /projects/{id}/fca/index` + `/fca/portfolio`; a **Report Center** entry (FCA / FCI,
  PDF + Excel); a **🏥 Facility Condition** panel in the Operations stage (FCI + band, deferred vs
  CRV, by-UNIFORMAT table, recommended-spend chart, worst-elements, portfolio card). `test_fca`;
  demo seeded.

## v0.3.71 — Nav polish: fix garbled icons + a naming collision surfaced by the Design workspace
Cleanup found while reviewing the new Design nav.
- **Fixed 5 corrupted module icons** — `daily_report`, `incident`, `inspection`, `ncr`, and `permit`
  carried double-encoded (mojibake) icon glyphs from a past edit; they rendered as garbage (e.g.
  "â–£ Permitting"). Restored to their intended symbols (☼ ⚑ ✓ ⚠ ▣).
- **Renamed the drawing register "Drawings & Specs" → "Drawings"** — its fields are all
  sheet-index data (number, revision, discipline, sheet number); the "& Specs" was a misnomer that
  collided with the real **Specifications** register (`spec_section`, the CSI spec book that drives
  the submittal log). The two are now clearly distinct in the nav.
- **`engines: node >=20`** added to the web package so `npm` warns when an older Node is on PATH (the
  production build's post-step needs the global `crypto`, stable since Node 19).

## v0.3.70 — A Design workspace for the architect & engineer, and role-based tool placement
The platform now has a home for the **design phase**. A new **Design** workspace sits between
Drawings and Construction — the architect/engineer's seat (AIA SD/DD/CD · RIBA stages 2–4) — and the
design tools that were scattered across the GC and developer portals now live there. This is a
methodical placement pass so every tool shows in the view(s) whose role owns it; see
[docs/roles-views.md](docs/roles-views.md) for the full role→view map.
- **Design workspace** — nav grouped by design stage: **Brief & program** (Space Program · Project
  Lifecycle) and **Model & standards** (IDS Requirements · CDE / Standards · BIM KPIs · **Model
  Health**). The Model-Health launcher deep-links to the model-QA checks in the Model **Tools** rail
  (Data QA, code-readiness, clash, IDS validate — they run on the loaded geometry). A design
  command-center dashboard (phase, standards, and register tiles) is the landing page.
- **Registers move to their owner** — Space Program, Project Lifecycle, design reviews, selections,
  information requirements/containers, coordination issues, and the design document register are now
  Design-workspace registers.
- **Shared tools show in both workspaces** — a register can now belong to more than one workspace, so
  the A/E↔GC workflows (RFIs, submittals, drawings, transmittals, meetings, permits, specs) appear by
  default in **both** Design and Construction without duplicating records. The GC's Construction view
  is unchanged; the architect/engineer get a focused Design view.
- **Role routing** — the architect and engineer personas now home into Design; every role can still
  reach every register via **Show all modules** or **⌘K**.

## v0.3.69 — Pull planning: the Last Planner phase board
Collaborative pull planning next to the schedule views — the Last Planner System level that sits
between the master schedule and the weekly work plan. The team pulls a phase backward from a
milestone; every trade posts its own tasks and the hand-offs between them; the lookahead makes work
ready by removing constraints; commitments are scored by PPC.
- **`pull_plan_task` module** (Schedule, construction workspace) — a sticky note per task: milestone,
  trade, responsible party, duration, planned week, **predecessor** (the hand-off), and the
  **constraints** that keep it from being ready (design/RFI, submittals, materials, labour,
  equipment, prerequisite work, permits/inspections, space/access, information). Workflow:
  pulled → made ready → committed → done, with a **missed** state gated on a variance reason, and
  paths to reconstrain or recommit.
- **Phase board** — a trade-swimlane × week matrix built over those records, with the hand-off
  sequence, a make-ready log of open constraints, and readiness / commitment / **PPC** (Percent Plan
  Complete = completed ÷ committed). Rendered at the top of the **📅 Schedule** panel with a
  milestone filter, an inline editor (every trade edits its own notes), and a printable **PDF** of
  the board — the hand-out a pull-planning session runs from. Feeds the existing weekly-plan PPC
  analytics rather than replacing them.

## v0.3.68 — Concept space programming: the adjacency graph (standards C8 of 8)
The front of the lifecycle — programming a building before it's massed — closing the eight-release
standards + AI track. The platform now spans land acquisition → programming → design (ISO 19650) →
construction → turnover → operations.
- **`space_program` module** (Programming, developer workspace) — program spaces as nodes: name,
  use type, target area, quantity, level preference, and **“should be adjacent to”** (the edges).
- **`adjacency.py`** (`GET /projects/{pid}/program/summary`) — the program as a graph: total/net/
  gross area, use mix, the node/edge adjacency graph with **unmet preferences** flagged, an
  efficiency %, and the **massing hints** (gross area + use mix) that feed the zoning→massing
  generator and the proforma.
- **“🧩 Space Program” panel** (Design & build) — area KPI cards, the use-mix table, adjacency chips
  (unmet flagged), and the massing hand-off line.
- **Docs** — README + roadmap now describe the full span (acquisition → programming → ISO-19650
  design → construction → turnover → twin/ESG operations) and the C1–C8 track.
- Verified live (4 nodes, 38,700 sf gross / 35,500 net, 91.7% efficiency, Lobby→Retail unmet) +
  `test_program`. Typecheck + 49 vitest + Pages build green.

## v0.3.67 — Drawing-sheet extraction (standards C7 of 8)
Reading a drawing set into structured data — offline-first and honest, never inventing a sheet.
- **`sheet_extract.py`** (`POST /projects/{pid}/extract/sheets`) — parses an uploaded PDF's text
  layer (pypdf) or a pasted sheet index into `{number, title, discipline}`, inferring the discipline
  from the sheet prefix (A→Architectural, S→Structural, M/E/P→MEP, C→Civil…). Deterministic; an
  image-only scan with no text layer returns nothing and says so (set an Anthropic key to read page
  images). With `create=true` the extracted sheets become **Drawing records** in one step.
- **“🗂 Sheet index” tab** in AI Assist — upload a PDF or paste a list, preview the extracted table,
  optionally create the drawing records.
- Verified live (paste → 3 sheets extracted with disciplines) + `test_sheet_extract` (9-sheet index
  parsed, noise ignored, 9 drawing records created). Typecheck + 49 vitest + Pages build green.

## v0.3.66 — Procurement compliance gate (standards C6 of 8)
Turns the platform's existing COI / prequal / subcontract / lien-waiver records into an enforceable
compliance posture — the “can this sub bid or bill yet?” gate, plus the outbound nudge list.
- **`procurement_gate.py`** — per-vendor readiness from the compliance records:
  - `GET /projects/{pid}/procurement/gate?vendor=` → **can bid** (approved prequalification + active
    insurance) and **can bill** (executed subcontract + active insurance) with the specific blockers;
    reports the COI status/expiry, prequal status, subcontract execution, and whether a waiver is on file.
  - `GET /projects/{pid}/procurement/compliance-feed` → the outbound nudge list: every vendor with an
    expiring / expired / missing COI or an unapproved prequal, so the GC chases the paperwork before it
    blocks a bid invitation or a pay application.
- **Procurement-compliance-gate card** in the ⚖️ Risk & Cost panel (flagged vendors, issues, bid/bill
  status). Money movement stays behind the flagged licensed-rail bridge — this gates on paperwork only.
- Verified live (Bedrock flagged: expired COI + unapproved prequal → can't bid/bill; Acme clears) +
  `test_procurement_gate`. Typecheck + 49 vitest + Pages build green.

## v0.3.65 — Digital-twin readiness + Digital Product Passport (standards C5 of 8)
Deepens the two KPI categories that were placeholders — the data a building needs to run as a digital
twin, and the emerging EU product-passport requirement.
- **`building_system` module** — the HVAC / electrical / plumbing / fire / vertical-transport / BMS
  systems an asset belongs to, with the BMS integration protocol (BACnet, Modbus, KNX, MQTT…).
- **Asset register gains a “Digital Twin” fieldset** (link to a building system + sensor/telemetry
  point ID + sensor type) and a **“Product Passport” fieldset** (GS1 Digital Link ID, EPD/
  environmental reference, manufacturer-data URL).
- **`twin.py`** (`GET /projects/{pid}/twin/readiness`) — asset↔system linkage %, sensor-mapping %,
  a combined twin-readiness score (ISO 23247), the building-system graph with BMS-integration count,
  and **DPP completeness** (honest about the passport being an emerging 2028-30 EU requirement).
- The BIM KPI scorecard’s **Digital Twin Readiness** and **Construction Data Readiness** categories
  now read these richer signals (system-linked + sensor-mapped; product data + DPP).
- **Digital-twin readiness card** in the 🔧 Operations panel.
- Verified live (25% twin-ready on the seeded assets, DPP note) + `test_twin` (66.7% linked / 33.3%
  sensored → 50% twin-ready; DPP 33.3%; KPI reflects both). Typecheck + 49 vitest + Pages build green.

## v0.3.64 — AI over the model: MCP server + standards experts (standards C4 of 8)
Two ways an AI works *with* a project — both offline-first and grounded in real data, never a model
guessing from memory.
- **Standards-compliance experts** (`standards_expert.py`, `GET /projects/{pid}/standards/check?
  standard=iso19650|cobie|ids|uniclass`) — run the named standard against the project's own CDE,
  requirements register, asset data and model-quality index; return findings each with the **clause
  it references** and a recommendation, plus a 0–100 readiness score. Fully deterministic, no key.
  Surfaced as a **Compliance check** card (four standard buttons) in the CDE / Standards panel.
- **MCP server** (`mcp_server.py` + `mcp_tools.py`, `GET /mcp/tools`) — exposes the project to
  external AI agents (Claude Desktop, Cursor) as callable tools: project snapshot, list records, CDE
  status, BIM KPI scorecard, openBIM quality, standards check, and **create RFI** (a write tool).
  Tool logic reuses the same engines the HTTP API does, so an agent's reads/writes pass the exact
  same validation and workflow gates as the UI. The MCP SDK is an **optional** dependency (offline-
  first); the stdio server prints install guidance if it's absent. [docs/mcp.md](docs/mcp.md).
- Verified + `test_mcp_standards` (catalog exposes 8 tools; dispatch runs snapshot/records/CDE and
  creates a real RFI; unknown tool raises; experts return clause-referenced findings). Live:
  compliance card renders ISO 19650 findings with clauses. Typecheck + 49 vitest + Pages build green.

## v0.3.63 — BIM KPI scorecard + handover acceptance (standards C3 of 8)
The information-management scorecard the industry runs on — ten categories, graded from data the
platform already holds, with a formal owner's-acceptance gate at handover.
- **`bim_kpi.py`** (`GET /projects/{pid}/bim-kpi/scorecard`) — the ten categories graded
  good/warn/poor/**n-a**: Information Requirements, Model Authoring Quality, openBIM Exchange,
  Coordination Control, Issue Resolution, CDE Discipline, Asset Data Readiness, Construction Data
  Readiness, Handover Assurance, Digital Twin Readiness. Each rolls up existing data — the CDE
  (C1), model quality (C2, when a model is loaded), and the RFI / coordination / asset / closeout
  records — and shows **n/a rather than a guess** when its inputs are absent. Overall health %.
- **Handover data-drop acceptance gate** (`GET …/handover/acceptance`) — the owner's checklist
  against the AIR: requirements issued, assets tagged for CMMS (≥90%), as-builts, O&M, accepted
  completion certificate → one accept/not-ready verdict.
- **“📊 BIM KPIs” panel** (Plan & derisk) — health + grade-count cards, the acceptance banner, and
  the traffic-light category table. **Report Center: “BIM KPI Scorecard (ISO 19650)”** (PDF/Excel).
- Verified live (health %, 🟢🟡🔴⚪ grades, handover checklist) + `test_bim_kpi` (empty → 10 n/a;
  populated → info-reqs/CDE/asset/handover good; report PDF). Typecheck + 49 vitest + Pages build green.

## v0.3.62 — openBIM model-quality scoring (standards C2 of 8)
Turns the loaded IFC model into measurable buildingSMART quality signals — the layer that makes IDS
authoring (already shipped) actionable, and feeds the coming BIM KPI scorecard.
- **`openbim_quality.py`** (`GET /projects/{pid}/openbim/quality`) — pure scoring over the model's
  property index:
  - **LOIN per element** (Level of Information Need, the ISO 19650 successor to "LOD") — each element
    scored across geometry / type / classification / properties / quantities; reports average score,
    the “coordinated” share (≥4 of 5 facets), and per-facet coverage.
  - **IDS rule-compliance %** — pass `?use_case=` (fire & life safety, handover COBie, energy,
    quantities) and every applicable element is scored against its IDS spec (must carry every
    required property) → per-spec and overall compliance %.
  - **IFC export health** — proxy/untyped share, type coverage, property coverage graded pass/warn/
    fail (the authoring-export defects that quietly break QTO, carbon and IDS).
  - **bSDD / classification alignment %.**
- Surfaced as an **openBIM model-quality card** in the CDE / Standards panel (degrades to a
  “load a model” hint when none is open).
- Verified + `test_openbim_quality` (LOIN distribution, IDS walls 2/3 → 66.7%, export-health proxy
  flag, bSDD %) over a synthetic index — no live model needed. Typecheck + 49 vitest + Pages build green.

## v0.3.61 — ISO 19650 information management: CDE + requirements register (standards C1 of 8)
Opens a standards-alignment track (grounded in ISO 19650, buildingSMART, and the industry BIM-KPI
frameworks). First: formal information management, replacing scattered document status with a proper
Common Data Environment.
- **`information_container` module** — deliverables (models, drawings, docs) move through the ISO
  19650 CDE states **Work-in-progress → Shared → Published → Archived**, carrying a
  **suitability/status code** (S0–S4 shared, A published-for-construction, CR/AB record) and a
  **revision**. Sharing requires a suitability code; publishing requires a revision (the review gates).
- **`info_requirement` module** — the requirements register: OIR/AIR/PIR/**EIR**/**BEP**/MIDP/TIDP
  with appointing / lead-appointed / appointed parties, `draft → issued → superseded`.
- **`GET /projects/{pid}/cde/status`** (`cde.py`) — container state distribution, suitability
  spread, and the three **CDE-discipline** metrics (revision control %, approval-status coverage,
  metadata completeness) that feed the forthcoming BIM KPI scorecard.
- **`GET /projects/{pid}/info-requirements/register`** — requirements by type + **core-document
  coverage** (flags a missing EIR/BEP/AIR).
- **“🗂 CDE / Standards” panel** (Plan & derisk) — container-state cards, CDE-discipline table,
  requirements register with the core-coverage banner.
- Verified live (panel shows 2 WIP / 1 Published, discipline metrics, missing-AIR flag) +
  `test_cde` (WIP→Shared→Published gated on suitability then revision; core-coverage). Typecheck green.

## v0.3.60 — Navigation at scale + a current demo
The panel list had outgrown a flat sidebar. Research pass over the published evidence on
information architecture for feature-dense products (navigation-depth studies, journey-based
step navigation, design-system shell-capacity guidance, and how large platforms restructured
around starred/recent + curated workspaces) — recorded in [docs/ux-ia.md](docs/ux-ia.md) with
the rules for future features (no new top-level items; two disclosure tiers max).
- **Lifecycle-stage navigation** — the portal's first-class destinations are grouped under stage
  headers instead of one flat list. Construction: *Plan & derisk → Build → Turn over & operate*;
  Developer: *Acquire → Design & build → Operate*; both end with *Across projects* (Portfolio,
  Benchmarks). Journey-based IA, matching how AEC teams already think in phases.
- **🕘 Recent** — the last five opened registers surface automatically at the top of the module
  list (below the opt-in ★ Favorites) — zero-setup wayfinding for ~100 registers.
- **⌘K taught in context** — a persistent "Jump anywhere: Ctrl/⌘+K" hint anchors the nav; the
  command palette is the long-tail navigator.
- **Pages demo brought current** — the captured massing.build/app snapshot pre-dated v0.3.49;
  every newer panel (Lifecycle, Turnover, Diligence, Operations, Energy, Asset Mgmt, ESG & POE,
  Risk & Cost, Benchmarks) rendered empty. The demo project now runs the full lifecycle (DD +
  entitlements, design gates, PM-generated work orders, 6 months of meter readings, reserve/CIP,
  leases + CAM, POE) and captures all engine endpoints — 608 fixtures, verified with a full
  two-persona walkthrough and a clean console.
- **Guide updated** — new "Tutorial 7 · Operate it" (diligence go/no-go, PM work orders, EUI,
  reserve study, CAM statements, ESG/POE) + ten plain-English glossary entries (EUI, CAM
  gross-up, Scope 1/2, POE, …).

## v0.3.59 — ESG rollup + post-occupancy evaluation (lifecycle R7 of 7)
The final lifecycle release: the asset's sustainability scorecard and the feedback loop from measured
performance back to design — all computed locally from the platform's own data.
- **ESG rollup** (`esg.py`, `GET /projects/{pid}/esg`) — metered energy (EUI via energy.py),
  **operational GHG Scope 1/2** from a transparent local factor table (on-site fuel vs purchased
  energy; set `AEC_GRID_KGCO2E_PER_KWH` to the local grid subregion factor), GHG intensity, water +
  intensity, and certification tracking (LEED credits targeted vs achieved). Nothing fetched,
  nothing fabricated.
- **`poe` module** — post-occupancy evaluations at levels 1 (indicative) / 2 (investigative) /
  3 (diagnostic) with occupant-satisfaction score, design EUI, findings and feed-forward lessons;
  workflow `planned → fieldwork → reported` (report requires findings). The rollup compares
  **design EUI vs metered actual** and reports the gap.
- **“🌱 ESG & POE” developer panel** — EUI/GHG/water/cert KPI cards, scope split with the factor
  note, latest-POE card with the vs-design gap, one-click PDF.
- **Report Center: “ESG / Sustainability Summary”** — PDF/Excel with GHG table, POE comparison,
  and data-coverage caveats.
- **Docs** — README + roadmap now describe the full span: land acquisition → due diligence &
  entitlements → design → construction → turnover → operations (CMMS, energy, reserves/CIP, CAM,
  ESG/POE). Lifecycle releases R1–R7 complete.
- Verified live (panel + PDF; grid-factor override changes Scope 2) + `test_esg`; typecheck +
  49 vitest + Pages build green.

## v0.3.58 — Capital planning + CAM reconciliation (lifecycle R6 of 7)
Hold-phase capital stewardship: will the reserves cover the roof in 2031, and did tenants pay their
fair share of operating expenses this year?
- **Reserve study** (`reserve.py`) — the asset register grows Reserve Study fields (expected life,
  replacement cost); `GET /projects/{pid}/reserves/study` projects recurring component replacements
  plus open capital-plan items over a 20–40 yr horizon (inflation-escalated), runs the year-by-year
  reserve balance, flags the **first underfunded year**, and solves the **suggested level annual
  contribution** that keeps the fund solvent.
- **`capital_plan` module (CIP)** — capital items with planned year, cost, priority
  (critical/recommended/discretionary), funding source and ROI note; workflow
  `proposed → approved → funded → complete`. Open items ride the reserve projection.
- **`cam_expense` module + CAM true-up** (`cam.py`) — operating-expense lines by standard category
  (janitorial, R&M, utilities, security, admin, management, insurance, taxes) with budget/actual and
  variable/recoverable flags. `GET …/cam/reconciliation`: recoverable pool with **variable-only
  gross-up** to a stated occupancy (fixed expenses pass at actual), each tenant's pro-rata share vs
  estimated payments (lease `recovery_psf` × sf), balance due or credit.
- **Per-tenant statement PDF** — `GET …/cam/statement/{lease}.pdf`: expense pool by category, the
  tenant's share, estimated payments, true-up balance.
- **Finance ▸ “Asset Mgmt” tab** — reserve-study runner (balance / contribution / horizon /
  inflation inputs, funding banner, replacement schedule), CIP table, CAM reconciliation with
  per-tenant statement downloads.
- Verified live (underfunded banner + suggested $/yr, escalated recurring events, CAM table w/ PDF
  served) + `test_reserves_cam`; typecheck green.

## v0.3.57 — Operations: CMMS + metered energy (lifecycle R5 of 7)
The biggest post-turnover gap: ~80% of a building's lifetime cost is operations. Adds the CMMS loop
(preventive maintenance before failures) and utility metering (EUI benchmarking) — fully offline.
- **`work_order` / `pm_schedule` modules** (Operations section) — corrective/preventive/emergency
  work orders with asset refs, priority, labor hours and cost; workflow
  `open → assigned → in_progress → completed → verified` (completion requires a completed date).
  PM schedules carry a task list, frequency and next-due date.
- **PM generation + KPIs** (`cmms.py`) — `POST /projects/{pid}/cmms/generate-pm` turns every due,
  active PM schedule into a preventive work order (idempotent per cycle; advances next-due).
  `GET …/cmms/kpis`: open by priority/type, overdue backlog, **PM compliance %**, **MTTR** (days).
- **`meter` / `meter_reading` modules** — electric/gas/water/steam/chilled-water meters with dated
  consumption + cost readings, entered manually or CSV-imported via the generic module import.
- **Metered energy rollup** (`energy.py`) — `GET …/energy/actual`: site kBtu by utility (standard
  conversion factors), monthly trend, water (tracked in gallons, not energy), utility cost, and
  **EUI (kBtu/sf/yr)** annualized over covered months using the model's GFA (or `?gfa_sf=`).
  Distinct from the design-model simulation at `GET …/energy`.
- **Benchmarking bridge** (`energy_star_bridge.py`, feature-flagged) — reports honestly that no
  provider is configured until a deployment sets `ENERGY_STAR_*` credentials; never fabricates a
  score. Local EUI/trends need no account.
- **“🔧 Operations” + “⚡ Energy” construction panels** — maintenance KPI cards, one-click PM
  generation, open-WO table; EUI/energy/cost/water cards, monthly trend chart, by-utility table.
- Verified live (both panels with seeded meters/readings/schedules; PM generation created WOs and
  was idempotent on re-run) + `test_operations`; typecheck + 49 vitest green.

## v0.3.56 — Pre-acquisition: due diligence + entitlements (lifecycle R4 of 7)
Fills the pre-construction gap the lifecycle research surfaced — the 6–36 months of study and
approvals between site control and capital commitment (grounded in institutional due-diligence
practice: ALTA/ASTM E1527 categories and the standard entitlement pipeline).
- **`due_diligence` module** (Acquisition, developer workspace) — study items by category
  (Title/ALTA survey, Phase I ESA (ASTM E1527), Phase II, Geotechnical, Utility capacity, Traffic,
  Wetlands/species, Zoning verification, Tax/legal) with consultant, findings, risk level, study cost
  and ordered/due/received dates. Workflow `open → in_review → cleared | flagged` — a report can't be
  submitted without findings, and flagging requires a risk level.
- **`entitlement` module** — applications (Rezoning, Site plan, CUP, Variance, Plat, Comp-plan
  amendment, Environmental review, Annexation) with agency, submitted/hearing/decision dates, a
  public-meeting/opposition log, conditions imposed, and **approval expiration**. Workflow
  `draft → submitted → hearing → approved | denied → appealed → hearing`; revisable for resubmittals.
- **Go/no-go rollup** — `GET /projects/{pid}/diligence/readiness`: DD by category
  (cleared/flagged/open), high-risk findings, the entitlement pipeline by state, and approvals
  expiring within 180 days → one `go` flag. New **“📜 Diligence & Entitlements”** developer panel
  (readiness banner, high-risk card, category table).
- Verified live (panel renders the NOT-READY banner, high-risk card, category rollup) +
  `test_diligence` (workflow gates + rollup), typecheck + 49 vitest green.

## v0.3.55 — UX, accessibility & front-end performance (readiness R3 of 7)
- **`prompt()` fully retired from the portal** — a new accessible `promptModal` (on the shared
  modalShell: role=dialog, focus trap, Esc/backdrop close, Enter submits, required-field validation)
  replaces all ten remaining `window.prompt()` calls: lifecycle **gate sign-off**, turnover
  **G704 certify** (both fields in one dialog), save view, templates (apply/save), add enum option,
  quick-create reference records, send-for-signature, and reassign.
- **Accessibility** — all **53** portal table headers now carry `scope="col"`; verified the viewer
  toolbar's icon buttons already ship `aria-label`s.
- **Performance measured** — the portal ships in the main `index` chunk at **92 KB Brotli** (shell
  budget 156/220 KB) — under the lazy-split threshold, so no code-motion was needed; recorded so
  future growth has a baseline.
- Verified **live**: certify flow end-to-end through the new dialog (open → validate → certify →
  “Architect certified” + G704 download), 375 px mobile viewport with no horizontal scroll, zero
  console errors; 49 vitest + typecheck + Pages build + budget green.

## v0.3.54 — Production hardening: ops & supply chain (readiness R2 of 7)
The deployment/ops half of the production-readiness plan — making "did we configure it right?"
a runnable gate and the supply chain deterministic:
- **Runnable go-live gate** — new [docs/PRODUCTION_CHECKLIST.md](docs/PRODUCTION_CHECKLIST.md) +
  `scripts/validate_prod_config.py` preflight (asserts RBAC, real secrets, secure cookies, CSP/HSTS,
  Redis-when-multi-worker, non-default DB/MinIO credentials; exit 0 = go). Referenced from deploy.md.
- **Supply chain** — Dependabot across pip/npm/cargo/actions (the viewer's pinned three/@thatopen pair
  moves as a group); CI now **builds the api+web images, scans them with Trivy (CRITICAL+fix = fail),
  and publishes to ghcr** with immutable `:sha` tags; a one-shot workflow generates + commits
  **Cargo.lock** so desktop builds stop floating transitive Rust deps.
- **Desktop trust** — the PyInstaller backend **sidecar is now Authenticode-signed** alongside the
  Tauri shell when a certificate is configured (SmartScreen inspects it separately).
- **Guardrails** — `seed_demo.py` refuses to run against an instance that already has projects
  (`--force` for labs); Host-header pinning via `AEC_ALLOWED_HOSTS` (TrustedHostMiddleware, opt-in);
  `/metrics` gains `http_responses_by_class_total` (2xx/4xx/5xx) for one-label alerting.
- Verified: preflight self-test (bad env → exit 1 with 4 failures; good env → exit 0), metrics smoke,
  all workflow/compose YAML parse, ruff clean.

## v0.3.53 — Production hardening: backend blockers (readiness R1 of 7)
From a full production-readiness audit (code + docs + deployment). Fixes the findings that make the
difference between "works in dev" and "safe under load, multi-worker, and misconfiguration":
- **Fail-fast production guard** — booting on **Postgres** without `AEC_RBAC=1` or with the default
  auth secret now **refuses to start** (explicit `AEC_ALLOW_OPEN=1` escape hatch). A forgotten env var
  is a loud crash at boot, not an open platform discovered later. CRITICAL log when the rate limit is
  on with multiple workers but no shared Redis counter.
- **Project list scales + doesn't leak** — `GET /projects` filters membership in SQL (join) instead of
  loading every project then running one role query each (N+1), and is paginated.
- **Bounded loads everywhere** — kanban `board()` returns capped per-state cards plus TRUE counts from
  a GROUP BY (was: materialize up to 100k records per request); CSV export **streams** page-by-page;
  the list `?limit=` param is clamped; Procore sync reads only the `procore_id` column via SQL json
  extraction (was: `limit=1_000_000` full-record load).
- **Observability** — fragment-conversion and publish failures now `logging.exception` (they were
  visible only in a status JSON nobody polls); auto-sync schedule failures log at WARNING.
- **Multi-worker autosync** — a Postgres advisory lock elects one runner per tick, so N workers no
  longer each pull the same external records.
- **Uploads & traversal** — the properties-index upload is size-gated (413 over `AEC_PROPS_MAX_MB`,
  default 100); attachment filenames explicitly collapse `..` sequences (belt on top of the existing
  storage containment guard).
- **Complete project deletion** — deleting a project now removes the **whole `{pid}/` storage prefix**
  (source-IFC copies, props index, publish status — not just the model tile) via a new
  `storage.delete_prefix` on both local and S3 backends.
- **Rate limiter** — evicts oldest buckets under IP churn instead of clearing all state at once.
- Verified: new `test_prod_hardening` + adjacent regressions (modules/rbac/security/connections/api/
  bcf) green, ruff + bandit clean.

## v0.3.52 — Architect sign-off + G704 substantial completion + record turnover (lifecycle track 4 of 4)
The final track closes the loop to turnover: the **Architect certifies substantial completion**, signs
off the punch list, and the as-built **record model** is stamped for handover.
- **`turnover.py` + `/turnover/*` endpoints** — `readiness` (punch rollup + latest model version; a
  G704 certifies *with* an open punch list, so the gate is that a punch list is prepared), `certify`
  (Architect certifies on a `completion_certificate` record: records the **Architect (certifying) +
  Owner + Contractor** signatures, stamps the current model version as the record model, issues the
  certificate), and `status` (signed cert + record-model summary).
- **G704 Certificate of Substantial Completion** generator in `contracts.py` — attaches the punch-list
  summary, the record-model version, and the occupancy date; reachable via
  `…/contracts/completion_certificate/{rid}/document.pdf?doc=g704`. The **Architect** is now a signatory
  on the G701 change order too.
- **Turnover package** — `closeout/package.zip` gains `turnover/status.json` (readiness + signed
  substantial-completion cert + record model version) alongside the as-built model, COBie and closeout
  manifest. `completion_certificate` gains occupancy-date / record-model-version / punch-% fields.
- **UI** — a **"🏁 Turnover"** construction-workspace panel: punch readiness, architect certification
  (with signatories), and one-click **G704** download.
- Verified: ruff + bandit clean, backend gate (new `test_turnover` — gate refuses with no punch list;
  architect certifies + Owner/Contractor sign; G704 renders; status reflects the signed cert) +
  `test_contracts`/`test_closeout` regressions, web typecheck + 49 vitest + Pages build + budget green.

**This completes the architect/engineer design-to-turnover lifecycle upgrade (4 tracks, v0.3.49–52).**

## v0.3.51 — Design-change instruments: ASI / Bulletin / Sketch (lifecycle track 3 of 4)
The standard AIA construction-phase change instruments, wired into the existing change chain.
- **New modules `asi`, `bulletin`, `sketch`** (Change Management section, config-driven CRUD + workflow):
  - **ASI** (AIA G710) — the Architect issues a supplemental instruction; **no cost/time**; the
    Contractor acknowledges (`issued → acknowledged → closed`).
  - **Bulletin** — a formal design revision; when it carries cost/time it links to a `change_event`
    (→ `pco_request → cor`) for pricing (`draft → issued → priced → closed`).
  - **Sketch (SK)** — a clarification sketch that attaches to an ASI / Bulletin / RFI / drawing.
- **Document generation** — G710 ASI + Bulletin cover-sheet + **G714 Construction Change Directive**
  (rendered from a `directive` record) added to `contracts.py`; all reachable through the existing
  `GET /projects/{pid}/contracts/{key}/{rid}/document.pdf?doc=asi|bulletin|ccd`. `directive` is the
  platform's CCD (G714) instrument.
- Verified: ruff + bandit clean, `test_change_instruments` (ASI issue→ack no cost; Bulletin cost impact
  links a change_event; SK attaches; ASI/Bulletin/CCD render as PDFs) + `test_contracts` regression,
  web typecheck green.

## v0.3.50 — IFC family library (lifecycle track 2 of 4)
The "families" folder now ships real `.ifc` content and a browsable library, fully offline.
- **Generated parametric core library** — `build_family_library.py` writes the whole catalog to a
  shippable **`services/data/families/library.ifc`** (46 families, each a GUID-stable `IfcTypeProduct`
  with mapped geometry, IFC4). The catalog gained **openings** (single/double door, fixed/sliding
  window), **enclosure** (interior partition, exterior wall, curtain-wall panel), and **concrete
  columns/beams** on top of the existing furniture / sanitary / appliance / lighting / MEP /
  structural / transport / plant families.
- **Family-library server** — `GET /families/library` (generated catalog grouped by category +
  the generated library + any curated external files) and `POST /projects/{pid}/families/place`
  (place a library family, GUID-stable, via the `add_family` recipe). The viewer's **Furnish & equip**
  picker now reflects the full library and its family count.
- **Curated external** — `services/data/families/external/` with a `SOURCES.md` of vetted free openBIM
  sources (buildingSMART samples, opensourceBIM/IFC-files, NBS National BIM Library, bSDD); drop an
  `.ifc` there or use `POST /families/import` to bring in manufacturer content. No third-party binaries
  are bundled without explicit review.
- Verified: ruff + bandit clean, backend gate (new `test_family_library` — library builds + reopens +
  place-from-library), web typecheck + 49 vitest + Pages build + budget green.

## v0.3.49 — Design-phase spine + itemized soft costs (lifecycle track 1 of 4)
Makes the architect/engineer design lifecycle explicit. Grounded in the RIBA Plan of Work 2020 (stages
0–7) mapped to the AIA design phases (Schematic Design → Design Development → Construction Documents →
Construction Administration), ISO 19650 information stages, and standard development soft-cost / design-
fee breakdowns.
- **`design_phase.py` + `project_phase` module** — the eight RIBA/AIA phases as **formal gates**. Each
  phase carries its deliverables, A/E design-fee %, and ISO-19650 status (S0→AM); the gate advances only
  when the **Architect + Owner** sign it off (`approve_gate` transition, requires a signer). Generating a
  project now seeds the eight phases automatically.
- **`soft_costs.py` — itemized, phase-aware soft costs** — the flat "soft = 25% of hard" is replaced by
  a transparent taxonomy (architecture & engineering fee, permits/entitlements, legal, financing &
  interest, insurance & bonds, developer fee, FF&E, marketing/lease-up, soft contingency). Totals are
  unchanged by default, but the **A/E design fee is drawn down across SD/DD/CD/Bid/CA** per standard
  splits. The generate seed (`_seed_dev_budget`, `_proforma_seed`) now emits itemized soft-cost lines.
- **Endpoints** `GET /projects/{pid}/lifecycle` (phases + gate state + soft-cost allocation + current
  stage), `POST …/lifecycle/seed`, `GET /lifecycle/reference`. New **"🧭 Project Lifecycle"** developer-
  workspace panel: the phase rail with deliverables, fee %, ISO status, gate sign-off, and the itemized
  soft-cost table.
- Verified: ruff + bandit clean, backend gate (new `test_design_phase`), web typecheck + 49 vitest +
  Pages build + budget green.

## v0.3.48 — Hardening, accessibility & documentation pass
A quality pass over the recently-shipped features: debug + full test sweep, a security-hardening
review, accessibility on the new UI, and a documentation refresh.
- **Security — outbound-URL guard.** New `net.py` `validate_outbound_url()` gates the bridges that
  fetch an **operator-configured** URL — **webhooks**, the real-estate syndication bridge, and the
  e-sign bridge — rejecting non-http(s) schemes (blocks `file://` / `gopher://` local-file-read + SSRF
  vectors) with an opt-in private-host check. The fixed-provider fetches (Autodesk, Google/Microsoft
  OAuth, Procore) and the already-guarded Speckle bridge were reviewed and left as-is.
- **Accessibility.** The new **Land Screening**, **IDS Requirements** and **conceptual-estimate**
  forms had placeholder-only inputs; every field now carries an `aria-label` so screen readers
  announce it. All new destinations confirmed reachable from the workspace nav (native `<button>`s,
  keyboard-operable).
- **Tests.** New `test_net`; backend gate now **97/97** suites. Web typecheck + 49 vitest + Pages
  build + bundle budget (156 KB shell < 220 KB) all green. `ruff` + `bandit` clean.
- **Docs.** Competitive/vendor comparison removed from the documentation set (README, the public
  landing page, the lifecycle graphic, roadmap/audit notes) in favor of neutral capability language;
  integration/connector references (Procore SSO + sync, ACC, QuickBooks/Sage) are retained as the
  factual product features they describe. README "Recent work", CHANGELOG and the GitHub About refreshed
  to current state; stale internal links removed.

## v0.3.47 — Land parcel screening + data connector
Land acquisition screening. The nationwide parcel dataset is a licensing play, so it's a
feature-flagged connector; the pure-software win — which plays to our GIS + feasibility + proforma
engines — is **screening**.
- **`parcels.py`** — screen a parcel set (imported GeoJSON / entered) by **size, zoning, flood zone,
  sewer/water, price**, and **rank by max-buildable opportunity**: each parcel gets a max envelope
  (area × FAR) and a **conceptual cost** (via `conceptual_estimate`), plus **land cost per buildable SF**
  — a screen → envelope → proforma chain that runs before acquisition, not just after.
- **`parcels_bridge.py`** — nationwide parcel/ownership/comps data is an optional paid connector
  (`PARCEL_PROVIDER`, Regrid/ATTOM/CoreLogic pattern) that raises rather than shipping fake data; the
  screening engine works on parcels you supply without it.
- Endpoints: `POST /parcels/screen`, `GET /parcels/data-status`. A **🗺️ Land Screening** developer-
  workspace panel (paste parcels → set criteria → ranked buildable-opportunity table).
- Verified: ruff clean, 96/96 backend suites (new `test_parcels`), web typecheck + 49 vitest + Pages
  build + budget green.

**This completes the second capability round (4 tracks, v0.3.44–47) on top of the code-quality gate
(v0.3.43).**

## v0.3.46 — Conceptual estimating + AI IFC classification
Two model-native intelligence features that leverage our IFC/massing strengths.
- **`conceptual_estimate.py`** — a parametric **$/SF** cost from building type + GFA + units at the
  massing stage (on-brand for a product called Massing): a low/base/high range **escalated for region
  and year**, with derived $/SF, $/unit and $/key for the proforma before there's a detailed takeoff.
  Built-in cost-per-SF table (16 building types) + regional index + ~4.5%/yr escalation, all overridable.
- **`ifc_classify.py`** — a transparent rules classifier that suggests the right **IfcClass** for
  `IfcBuildingElementProxy`/generic or mis-named elements (a proxy gets no quantity or carbon factor, so
  this directly improves **QTO + embodied carbon** accuracy). Every suggestion carries its reason;
  human-approved — reads the loaded property index or a posted element list.
- Endpoints: `GET /estimate/conceptual/catalog`, `POST …/estimate/conceptual`, `POST …/ifc/classify`.
  Surfaced in the **🛡 Risk & Cost** panel (a $/SF estimate mini-form + a model-classification summary).
- Verified: ruff clean, 95/95 backend suites (new `test_conceptual`), web typecheck + 49 vitest +
  Pages build + budget green.

## v0.3.45 — Materials procure-to-pay: quote leveling + 3-way match
The materials buying loop — distinct from sub-bid leveling. Deterministic/offline on top of the
modules we already have (`commitment` = PO, `delivery`, `sub_invoice`).
- **`procurement.py` — quote leveling** — normalize competing supplier quotes into an apples-to-apples
  grid with the low price per line item, the best-value supplier, per-supplier totals, and line-by-line
  savings (handles split awards where the cheapest supplier differs per item).
- **3-way match** — reconcile each PO against its deliveries and invoices, flagging **over-billing**
  (invoiced > PO), **pay-before-receipt** (invoiced with nothing received), and **un-invoiced
  deliveries**. Surfaced in the **🛡 Risk & Cost** panel.
- **`procurement_bridge.py`** — RFQ dispatch to suppliers is a feature-flagged stub (`RFQ_PROVIDER`)
  that raises rather than pretending to send; the *quote leveling* and *3-way match* work without it.
- Endpoints: `POST /projects/{pid}/procurement/level-quotes`, `GET …/three-way-match`, `/procurement/rfq-status`.
- Verified: ruff clean, 94/94 backend suites (new `test_procurement`), web typecheck + 49 vitest +
  Pages build + budget green.

## v0.3.44 — IDS authoring + EIR
Closing the BIM-standards loop upstream. We already *validate* models against an IDS; the demand is
upstream of that — **authoring** the requirements in the first place.
- **`ids_authoring.py`** — a starter requirements template library (what data each element type should
  carry: walls → FireRating/LoadBearing/…, doors, windows, slabs, spaces, columns, beams — from the
  standard `Pset_*Common` sets), bundled into **use cases** (handover/COBie, fire & life safety, energy,
  quantities). `build_ids()` emits a **standards-valid buildingSMART IDS 1.0** file via `ifctester` that
  **round-trips through our own validator**, and `eir_markdown()` generates an **EIR** (Exchange
  Information Requirements) document for the BIM contract.
- Endpoints: `GET /ids/templates`, `POST /ids/build` (→ downloadable `.ids`), `POST /ids/eir` (→ EIR.md).
  Model compliance-checking stays the existing `/validate` endpoint — closing the spec → implement →
  validate loop.
- **UI:** a **📋 IDS Requirements** portal panel — pick a use case, preview the required properties,
  download the IDS + EIR.
- Verified: ruff clean, 93/93 backend suites (new `test_ids_authoring` round-trips the IDS through
  ifctester), web typecheck + 49 vitest + Pages build + budget green.

## v0.3.43 — Code-quality gate (ruff + bandit in the loop) + BCF XXE fix
Applying the "enterprise-quality code with AI agents" discipline — verification *in the loop*, not after.
- **Static-analysis gate (ruff)** — a tuned config (`services/api/ruff.toml`) enforces the high-signal
  rules that catch real defects and dead code (pyflakes `F`, syntax `E9`, bugbear `B`) while respecting
  the codebase's deliberate idioms (compact `;` one-liners; the logged fail-open `except Exception`
  pattern is *not* linted). Wired into CI as a **blocking** step. Fixed everything it found: **14 unused
  imports + 2 unused variables** (dead code removed) and a **loop-variable closure bug** in the BCF
  camera parser.
- **Security scan (bandit)** — added to the report-only security workflow and run before shipping. It
  surfaced a real one: **`bcf_io.py` parsed untrusted uploaded BCF XML with the vulnerable stdlib
  parser (XXE / billion-laughs vector)** — now uses **`defusedxml`**, the same hardening already applied
  to CityGML import. Fixes an actual vulnerability on the BCF import path.
- `ruff` + `bandit` added to `requirements-dev.txt`; `CONTRIBUTING.md` documents the local gates.
- Verified: ruff clean, 92/92 backend suites, bandit XXE finding resolved.

## v0.3.42 — Tiers 2 & 3: fintech depth + differentiated (carbon, code, pricing)
The rest of the capability roadmap. Every engine is offline/deterministic (AI only where it helps),
source-linked, and never fabricates; money movement and live pricing are feature-flagged bridge stubs
that raise actionable errors rather than faking a result.
- **Subcontractor prequalification** — a transparent Q-score (safety/EMR, financial, experience, rating,
  currency = 100 pts, every point traceable) + a **COI-expiry** feed. A single sub default costs a GC
  1.5-3× the subcontract, so this is a core risk gate before award.
- **Pay-app ↔ lien-waiver reconciliation** — matches what was **paid** (`sub_invoice`) against **waivers**
  on file (`lien_waiver`, conditional vs unconditional) and surfaces per-vendor **lien exposure**. Massing
  never moves money: a `payments_bridge` stub disburses only through a licensed processor and refuses
  release while exposure remains.
- **Accounting export** — double-entry **GL CSV** + **QuickBooks IIF** bills from the cost records, so
  finance stops re-keying. (Live two-way sync remains the connection framework's job.)
- **Embodied carbon (A1-A3)** — computed from `production_quantity` × a built-in EPD factor table with
  unit conversion, rolled up by material + cost code. Zero of this existed before, and it plays to our
  IFC/quantity strength as embodied-carbon reporting goes mandatory on public work.
- **Code-compliance assistant** — describe a project → applicable **IBC/ADA/IECC** sections with citations
  (Claude when keyed; a deterministic IBC checklist triggered by occupancy/area/stories otherwise).
- **Takeoff pricing** — reconcile the takeoff to a built-in unit price book (+ a `pricing_bridge` stub for
  a live supplier/RSMeans feed) with **variance vs the estimate**.
- **UI:** a **🛡 Risk & Cost** portal panel (prequal scores, COI expiry, lien exposure, carbon, priced-
  takeoff variance, GL/IIF export) and a **Code check** tab in AI Assist.
- Verified: 92/92 backend suites, web typecheck + 49 vitest + Pages build + bundle budget all green.

## v0.3.41 — Tier 1: AI drafting, bid leveling, cross-project benchmarking
Market-driven upgrades. Each AI engine mirrors the existing
`review.py`: Claude when `ANTHROPIC_API_KEY` is set, a deterministic **offline fallback** otherwise,
every output **source-linked**, never fabricated; heavy calls run off the event loop and are throttled.
- **AI drafting** (`drafting.py`, **AI Assist** panel) — turn a note or a PDF into an editable
  first-draft **RFI**, **submittal summary**, or trade **scope of work** with page citations, so teams
  stop retyping from documents (the report's "18% of project time is spent searching for data").
  Human-in-the-loop: nothing is created until you click **Create**.
- **Bid leveling** (`bid_leveling.py`) — level a package's `bid_submission` records into an
  apples-to-apples grid: base-bid stats + >25% **outlier** flags, a **scope matrix** (who includes/
  excludes each item), **scope-gap** detection, and a **scope-adjusted low** recommendation (a low bid
  missing scope others carry is flagged). Optional AI canonicalizes free-text scope phrases.
  `GET /projects/{pid}/bids/leveling/{package_rid}`; shown as a grid in the AI Assist panel.
- **Cross-project benchmarking** (`benchmarking.py`, **Benchmarks** panel) — your own history across
  every project: actual **cost distribution** (low/p25/median/p75/high) per cost code, and RFI/submittal
  **turnaround + overdue %** (ball-in-court accountability). Answers the survey's "76% aren't realizing
  their data's potential." `GET /benchmarks/costs`, `/benchmarks/response-rates`.
- **Test-gate fix:** `run_tests.py` used a hardcoded list that silently skipped 12 on-disk suites
  (this session's throttle/route-order/module-schema/interop + pre-existing review/gbxml/analytics/
  discipline/module-config). All are now wired in — the gate runs **86 suites** (was counting 74).
- Verified: 86/86 backend suites, web typecheck + 49 vitest + Pages build + bundle budget all green.

## v0.3.40 — P2: Pydantic module-schema layer (single source of truth for module.json)
- **`module_schema.py`** — a Pydantic `ModuleSchema`/`FieldDef`/`Workflow`/`Transition` layer that
  formalizes what a valid `module.json` is. The config test and the runtime loader now validate against
  the *same* definition: `test_module_config` asserts every shipped module passes it (authoritative,
  fails the build); `load_registry` runs it at startup and logs a warning for a malformed module rather
  than crashing (advisory). New `test_module_schema` proves the layer catches each misconfig class
  (dup fields, unknown types, select-without-options, bad reference target, bad title_field /
  list_column / workflow state / transition / requires) and stays quiet on valid input.
- **Record value validation** (`validate_record`) at create/update: rejects a non-numeric value in a
  numeric field (`number`/`currency`/`percent`) with a 422 before it can land in the JSON `data` blob.
  Select `options` are treated as *suggestions*, not a closed enum (the system routinely stores
  free-form values a picklist didn't anticipate), so membership is deliberately not enforced.
- Fixed the `party` transition key to accept a bare string as well as a list (matches
  `rbac.party_allowed`), and corrected the module-authoring guide's workflow example (`action`, not
  `label`; `party`; convention-based due dates; derived terminal states).

## v0.3.39 — P1: don't block the event loop on heavy IFC/convert/AI work
- **Async offload of blocking work** (P1 from the review). Several `async` endpoints ran CPU/network-
  bound work directly on the event loop, stalling *every* other request on that worker for its whole
  duration. Each now runs in a threadpool (`run_in_threadpool`):
  - `POST …/validate` — `ifcopenshell.open` + IDS validation (seconds+).
  - `POST /convert` — the APS RVT→IFC `subprocess.run` (up to a 30-minute block!) and the E57
    point-cloud decode.
  - `POST /convert/citygml` — CityGML XML parse.
  - `POST …/review/{contract,scope,ask}` — server-side PDF text extraction and the LLM calls.
- **Model load progress** was already real (streamed % + MB with a graceful fallback when the server
  sends no `Content-Length`) — verified, no change needed.

## v0.3.38 — P0 hardening: SQL aggregates, SSRF guard, per-endpoint throttle, bounded property cache
Quick, safe, high-value fixes from the code/UX/perf/security review (Cesium globe deferred — the
recommendation is to adopt the OGC **3D Tiles** format into the existing three.js viewer if geospatial
demand arises, not build a bespoke globe).
- **Performance — SQL aggregates over full-table Python scans.** `due_feed` now filters unfinished,
  soon-due records in SQL (JSON due-date `< horizon` + state `not in` terminal) instead of loading
  every module row + JSON blob; `project_pins` prunes un-anchored rows in SQL; the construction
  **portfolio** dashboard loads only open/mitigating risks and counts open RFIs with a SQL `COUNT`
  rather than three `limit=1_000_000` full scans per project. (`my_work` was already SQL-filtered.)
- **Security — SSRF guard on the admin-settable Speckle URL.** The Speckle server URL comes from the
  Settings UI (untrusted), so `speckle_bridge` now requires `https://` and refuses hosts that resolve
  to private / loopback / link-local / cloud-metadata addresses before any request — closing an
  internal-network / metadata-probe vector. A self-hosted LAN server can opt back in with
  `SPECKLE_ALLOW_PRIVATE=1`.
- **Security — per-endpoint rate limiting for expensive ops** (`throttle.py`). The AI **review**
  endpoints (LLM per call) and the **convert** endpoints (subprocess / paid APS cloud translation)
  now get an always-on per-caller cap independent of the opt-in global limiter; tune or disable per
  bucket via `AEC_THROTTLE_<BUCKET>_RPM`. The "Test connection" AI probe is bounded to a 10s timeout
  with no retries so it can't hang a worker.
- **Perf/memory — bounded property cache.** The in-process element index (`properties.py`) is now an
  LRU capped at ~16 projects/worker (`AEC_PROPS_CACHE_PROJECTS`); evicted projects reload transparently
  from storage — a busy worker no longer holds every project's full element list forever.
- **UX — discoverable command palette.** Added a visible **🔍 Search ⌘K** button in the header so the
  palette isn't hidden behind a keyboard shortcut. Backend suite + web typecheck green.

## v0.3.37 — Design tokens: theme-aware modal error text
- Modal/error message colors across the Account, Connections, and Settings dialogs now use the
  theme-aware **`--err`** token instead of a hardcoded red, so they read correctly in light mode too
  (completing the v0.3.23 status-token pass). The remaining literal colors are intentionally raw:
  canvas drawing colors (takeoff/markup — canvas can't read CSS variables) and already-tokenized
  `var(--status-*, #fallback)` uses. Web typecheck + production build clean.

## v0.3.36 — Module-config validator + forms/CRUD audit
- **Forms/CRUD audit** across all 85 modules — found + fixed a broken list view: `asset_register`
  listed a `warranty_expiry` column that didn't exist (the field is `warranty_expires`).
- **`test_module_config.py`** now validates every `modules/*/module.json` on each test run and fails the
  build on: duplicate field names, `reference` fields with a missing/non-existent target module,
  `select`/`multiselect` with no options, unknown field types, `title_field` or `list_columns` pointing
  at non-existent fields, and workflow `initial`/transition states or `requires` that reference
  unknown states/fields. Prevents the whole class of config-driven-CRUD misconfig going forward.

## v0.3.35 — Frontend load speed: code-split the secondary workspaces
- **~24% smaller initial shell** — the **Finance (proforma)** and **Drawings** panels are now
  code-split and load on first open instead of shipping in the startup bundle. Initial `index` chunk
  **646 kB → 535 kB (139 → 106 kB gzip)**; proforma (77 kB) + drawings (8.8 kB) are separate chunks.
  The default **Construction/Developer** portal stays eager; the 3D viewer engine (@thatopen, ~6 MB)
  and **Studio** were already lazy. Verified live: Finance + Drawings load on first switch with no
  errors; web typecheck + production build clean.

## v0.3.34 — Security hardening: gate the conversion + interop endpoints
- **Auth gap closed.** `POST /convert` (RVT/DWG/NWC bridge) and `POST /convert/citygml` were reachable
  anonymously — they now require an authenticated identity (`current_user`), and `/convert` + `/interop`
  were added to the RBAC middleware's protected-prefix list (defense-in-depth when `AEC_RBAC=1`).
  Combined with the earlier defusedxml + body-cap hardening, the CityGML endpoint is now auth-gated,
  XXE-safe, and size-bounded.
- Web dependency audit clean (`npm audit --omit=dev`: 0 vulnerabilities); Python dep scan runs in CI.

## v0.3.33 — Discipline quantities: rebar tonnage + MEP runs (C)
- **🔩 Discipline quantities** in the viewer's Exports — a quantity roll-up straight from the IFC:
  **reinforcement tonnage** (from `NetWeight`, or estimated from volume × steel density when bars
  aren't weighed), **MEP linear runs** (duct / pipe / cable metres + segment & fitting counts), and
  **structural element volume**. Backs the rebar-viz / MEP-takeoff use case (Koh · WithRebar).
- New `aec_data.qto.discipline_summary` (reuses the QTO quantity reader + geometry fallback) +
  endpoint `GET /projects/{pid}/quantities/disciplines`. `test_discipline.py` covers weights (modelled
  vs volume-estimated), MEP runs, and structural volume; verified live against a real IFC. Typecheck clean.

## v0.3.32 — gbXML energy-model export (B4)
- **↓ gbXML (energy model)** in the viewer's Exports — exports the model to **Green Building XML** for
  OpenStudio / EnergyPlus / IES / DesignBuilder. Spaces carry **area + volume + occupancy from the real
  IFC geometry**, plus building-level **exterior envelope** surfaces (wall + window opening / roof /
  ground slab) with areas from geometry. Valid gbXML 6.01.
  - Honest scope: a **simplified early-design (shoebox) model** — building-level envelope, not a full
    per-space surface-boundary thermal model (that needs IfcRelSpaceBoundary geometry). It seeds an
    energy tool with the spaces/areas/volumes rather than replacing detailed energy modelling.
  - New `aec_data/gbxml.py` (reuses the space schedule + envelope-area extractors) + endpoint
    `GET /projects/{pid}/exports/model.gbxml`. `test_gbxml.py` validates the structure; verified live
    against a real IFC (72 spaces). Web typecheck clean.

## v0.3.31 — Settings: "Test connection" per integration
- Every integration in **Settings ▸ Integrations & API keys** gets a **Test** button with instant
  ✓/✗ + message, so a non-technical admin knows a key actually works before relying on it:
  - **AI** — validates the Anthropic key with a 1-token call.
  - **Email** — connects + STARTTLS + login (no send).
  - **Speckle** — live GraphQL `serverInfo` connectivity check.
  - **Autodesk APS** — 2-legged OAuth (validates client id/secret).
  - **SSO** — confirms client id/secret are present (full sign-in still completes from the login page).
  - **Licence** — key-format check.
- New `conntest.py` dispatcher + `POST /settings/integrations/test` (admin-only). `test_interop.py`
  covers the dispatcher; suite + web typecheck green.

## v0.3.30 — Settings: add all API keys in the UI (no code/env editing)
- **Speckle** and **Autodesk APS** are now in the **Settings ▸ Integrations & API keys** panel, joining
  AI (Anthropic), Email (SMTP), SSO (Google / Microsoft / Procore), and licensing. A non-technical
  admin pastes keys and hits **Save** — no editing `.env` files or code. Secrets stay **write-only**
  (the catalog reports only whether a key is configured, never the value).
- The Speckle and APS bridges now read config via the settings store (DB-saved UI value wins, else the
  env var), so keys entered in the app take effect immediately — same pattern as the AI key.
- Clarified the admin hint: "add API keys here — no code or config files to edit."
- `test_interop.py` asserts the catalog exposes Speckle/APS with write-only secrets; suite + typecheck green.

## v0.3.29 — Federation alignment report + security hardening
- **Model alignment check** (Coordination) — a lightweight companion to federated clash: do a
  project's discipline models share the same **storey scheme** and **georeferenced origin**? Reads each
  model's storey elevations + IfcMapConversion and flags mismatched storey counts/elevations (different
  datums) and survey-origin offsets — the #1 coordination problem. New endpoint
  `/projects/{pid}/models/alignment` + a "📐 Alignment check" viewer action beside Federated clash.
- **Security hardening** of this session's new upload/parse surfaces:
  - CityGML parsing now uses **defusedxml** → XXE / billion-laughs / external-entity bombs are
    rejected (`EntitiesForbidden`) instead of expanding, so a tiny malicious file can't exhaust memory.
  - The contract/spec review engine caps analysed text (~800k chars) so a huge PDF can't drive the
    regex scan unbounded (the global 1 GB body cap still applies to the upload itself).
  - `pypdf` + `defusedxml` pinned in `requirements.txt`.
- `test_interop.py` extended (XXE bomb → 422, alignment → 409); backend suite + web typecheck green.

## v0.3.28 — Interoperability: Speckle bridge + CityGML site-context import
- **Speckle bridge** (Interoperability) — optional, open-source & self-hostable data exchange with the
  wider AEC ecosystem (Rhino/Grasshopper, Revit, Blender, web). Off unless `SPECKLE_SERVER` +
  `SPECKLE_TOKEN` are set; when on, `status()` verifies live connectivity (GraphQL `serverInfo`).
  IFC/Fragments stay the source of truth. Endpoints `/interop/speckle/status` + `…/send` (the chunked
  object upload runs in your credentialed deployment — it never fabricates a commit).
- **CityGML → GeoJSON site context** (GIS & Site) — import CityGML (the OGC standard behind the 3D City
  Database / Cesium city tiles) via **Open mesh / point cloud / GIS…**; the server extracts building
  footprints (with heights) → GeoJSON that renders in the existing GIS reference layer. Namespace-
  agnostic (CityGML 1.0–3.0), fully offline. Endpoint `/convert/citygml`; `.gml/.citygml` accepted.
- `test_interop.py` (Speckle gating + CityGML parse/422) green; web typecheck clean.

## v0.3.27 — Code-readiness check (Safety & Compliance)
- **🏛 Code-readiness check** in the viewer — does the model carry the *data* a plan review needs?
  A property-level rule engine (not a certified geometric code review) checks: egress door width
  recorded (≥ 0.813 m, IBC 1010.1.1), fire rating on walls (IBC Table 601/602), spaces carry floor
  area (IBC 1004.5) + occupancy classification (IBC 1004), egress stairs modelled (IBC 1011), and
  elements typed/classified. Returns a readiness %, a per-rule table with code references, and a
  one-click **3D highlight of the elements to review**. New endpoint `/elements/code-check`.
- Extends the v0.3.25 Data-QA into rule-based checks (Kestrel-style). Rules target IFC classes,
  try several attribute/pset keys, and check presence or a numeric minimum. `test_analytics.py`
  covers it; web typecheck clean.

## v0.3.26 — Preconstruction intelligence: contract risk review + scope-gap + doc Q&A
- **Risk Review** (new Construction-workspace destination — preconstruction intelligence, inspired by
  the AI pre-con review category). Upload a contract/spec PDF (or paste text) and:
  - **Contract risk review** — flags risky clauses by severity (high/med/low) with rationale + a
    suggested redline: pay-if-paid, no-damage-for-delay, broad indemnity, termination-for-convenience,
    sole discretion, lien waivers, LDs, backcharges, retainage, etc. One click adds a finding to the
    **Risk Register**.
  - **Scope-gap detection** — surfaces ambiguous/missing scope in specs & drawing notes ("by others",
    "N.I.C.", "TBD", "as required", "or equal", "match existing"…).
  - **Ask a document** — answers a question grounded in the uploaded doc with **page citations**.
  - New `review.py` engine + `/projects/{pid}/review/{contract,scope,ask}` endpoints. Uses Claude when
    an Anthropic key is set; otherwise a **deterministic clause/marker library** so it works fully
    offline and never fabricates (only flags language actually present).
- **Risk register depth** — the `risk` module gains **response strategy** (Avoid/Transfer/Mitigate/
  Accept), **trigger / warning signs**, and **contingency (Plan B)** to match risk-register best practice.
- Backend suite green (+ test_review, test_analytics); web typecheck clean.

## v0.3.25 — Thematic "Color by property" + BIM data-QA (built-world analytics)
- **Color by any property.** Generalized the 5D heatmaps into a thematic override: pick any IFC
  attribute (class, storey, type, name) or pset/qto property and the model recolours by value —
  numeric ranges get a blue→red ramp, categorical values distinct hues, with a live legend and an
  "N unset" count. New endpoints `GET /projects/{pid}/elements/facets-list` (the picker) and
  `…/color-by?prop=` (server-side bucketing over the property index — scales to large models).
- **BIM data-QA (completeness).** A validation pass over the property index: for each element,
  which required (Name / IFC class / Storey) and recommended (Type / property sets) attributes are
  present vs missing → a headline compliance %, a per-rule table, a one-click **3D highlight of the
  non-compliant elements**, and a CSV export. Endpoint `GET /projects/{pid}/elements/qa`.
- Inspired by computational-AEC data-viz/asset-data workflows; both reuse the existing viewer
  colorize/selection plumbing. Backend 75/75 + web typecheck green.

## v0.3.24 — Construction ↔ Developer split + role-geared dashboards
- **Workspace split.** The oversized single "Construction" portal is now two role-scoped workspaces
  driven by a new `workspace` tag on every `module.json`: **Construction** (the GC build lifecycle —
  Engineering, Preconstruction, Field, Cost, Change Management, Quality, Contracts, Safety, Closeout,
  BIM, Schedule, Resources, Sustainability) and **Developer** (real estate — **Feasibility** `zoning`,
  **Market & Sales** `comparable`/`listing`, **Capital** `investor`, **Operations** `lease`, plus the
  proforma via a one-click **Underwriting →**). A **Show all modules** toggle keeps every register one
  click away for every role — everyone still has access to all data.
- **Role-geared dashboards.** The Developer workspace opens on a real-estate command center (deal
  returns · listings · comps · capital · leases · feasibility) instead of the GC KPIs. The GC
  dashboard now orders its KPI cards by role: the **superintendent** leads with the field
  (punchlist/safety/quality), the **project manager** with controls (RFIs/COs/overdue). Same cards,
  role-appropriate emphasis.
- **Top header.** The role picker is now labeled **👤 Viewing as** and grouped by function
  (Real estate · Construction office · Construction field · Design), set off with a divider.
- **Deeper registers.** `comparable` rebuilt into a full appraisal-grade sales/rent comparison grid
  (comp type, $/unit, NOI, GBA, units, land area, year built, occupancy, condition, distance to
  subject, net adjustment, adjusted price, source + a recorded→verified→excluded workflow);
  `investor` gains ownership %, preferred return %, and commit date. Backend 74/74 + web typecheck green.

## v0.3.23 — Design tokens: theme-aware status colors
- Extracted the hardcoded traffic-light status colors (green/amber/red — 43 occurrences across the
  portal dashboard + proforma) into CSS variables (`--status-good/warn/crit`, `--err`) defined for
  both dark and light themes. Previously the dark-mode hexes bled into light mode; now status colors
  adapt to the theme and there's a single place to tune them. Web typecheck + 49 tests green.

## v0.3.22 — Speed: rollup fields filter in SQL (no more full-table scan per read)
- **Rollup fields** (e.g. a cost code's committed/budgeted/direct totals, a COR's PCO sum) previously
  loaded *every* source-module record for the project and matched the reference in Python on each
  `get_record` — O(N) per rollup, amplified by rollup-heavy dashboards. Now the reference match runs
  **in SQL** via portable JSON extraction (Postgres `->>` / SQLite `json_extract`), so only the
  matching rows are fetched. Same values, far less data scanned/shipped as record counts grow.
  Backend 74/74 (rollup-exercising tests unchanged).

## v0.3.21 — Forms/CRUD accuracy pass (field types, required flags, itemized costs)
- Audited all ~80 module forms against construction best practice and fixed the concrete, verified
  issues:
  - **Currency types**: material/equipment/labor unit rates and `budget.budget` / `budget.forecast`
    were plain numbers — now `currency` (proper `$` formatting, consistent with the rest of the budget).
  - **Required flags** where the field is genuinely mandatory: `submittal.type`,
    `inspection.inspection_type`, `ncr.disposition` — the form now blocks submit + the API validates.
  - **Itemized change-order cost breakdown**: `cor` gains Labor / Material / Equipment / Overhead &
    profit currency fields backing the total (standard COR format).
  - **Process fields**: `permit.applied_date` (processing time), `incident.reported_date` (OSHA
    reporting window), `daily_report.crew_by_trade` (manpower breakdown).
- Demo seed + test updated to supply the newly-required fields. Backend 74/74; web typecheck + 49
  tests green. (Riskier dedup/reference-type findings from the audit are deferred pending consumer
  analysis.)

## v0.3.20 — Command palette (⌘K / Ctrl-K)
- A global **command palette** (Cmd/Ctrl-K from anywhere) — the fast way to reach any workspace,
  module, action, or record without hunting through menus. Fuzzy-ranked, keyboard-first (↑/↓, Enter,
  Esc), with live **record search** (matches ref/title/data via the search endpoint) appended as you
  type. Commands cover the 5 workspaces, shell actions (new project, open IFC/mesh, Report Center,
  save, help), and every construction module (jump straight to its register). First of the Tier-1
  UX-2.0 upgrades from the audit; new `ui/palette.ts` + `PortalUI` open-by-key/record hooks.
- Verified live: opens on Ctrl-K, "fin"→Finance ranks first, Enter navigates; no console errors.
  Web typecheck + 49 tests green.

## v0.3.19 — Fix: attachment images / thumbnails not loading (route collision + COEP/CORP)
- **Portal record images now load.** Three compounding bugs, found by driving the app + reading
  network traces:
  1. **Route collision** — bim.py's `GET /attachments/{id}/download` (the `Attachment` table,
     registered first) shadowed the module-record handler (`RecordAttachment` table), so every
     module attachment 404'd. Moved module attachments to a distinct `/module-attachments/{id}/download`.
  2. **Bad auth gate** — that handler used `require_role("viewer")`, which reads the project id from
     the path; with no `pid` in the path FastAPI demanded it as a query param → 422. Now authenticated
     like bim's download: `current_user` + the attachment's own project (+ signed-URL support).
  3. **COEP blocked the `<img>`** — the SPA is cross-origin isolated (`require-corp`, for the viewer's
     SharedArrayBuffer WASM), which blocks cross-origin image subresources without a
     `Cross-Origin-Resource-Policy` header. Added `CORP: cross-origin` to the module-attachment
     download and to `range_response` (so BIM/topic attachments **and** `model.frag` embed cross-origin too).
- Verified live: an uploaded photo renders on the record (decodes, `naturalWidth>0`, no COEP block).
  Backend 74/74 (new `test_attachments`: distinct path 200 + bytes + `inline` + CORP; old path 404s);
  web typecheck + 49 tests green.

## v0.3.18 — Security: fix stored XSS in portal record rendering
- **Stored-XSS fix (high severity)**: record list cells, the record-detail title/fields, the
  cross-module search results, action-item / due / notification feeds, and the portfolio table all
  rendered user-entered values (titles, field data, project names) via `innerHTML` without escaping —
  a malicious record title like `<img src=x onerror=…>` executed for every user who viewed it. List
  cells now use `textContent`; every remaining `innerHTML` interpolation of record/user data is passed
  through `escapeHtml()`. Verified live: a hostile-title RFI renders as literal text on both the list
  and detail pages, injects no elements, and does not execute. (Found in a full-codebase UI/UX audit.)
- Web typecheck + 49 tests green.

## v0.3.17 — Saved-search alerts + Postgres full-text search
- **Saved-search alerts**: every saved view now tracks a `last_seen_at`, and the portal home shows a
  **🔔 Saved searches with new matches** band — each saved view with its **new-since-you-last-opened**
  count (a never-opened view counts all matches as new). Click a chip to open that filtered list; it
  clears the count. New `GET /projects/{pid}/views/alerts` + `POST …/views/{vid}/seen` + a
  `count_records` engine helper. Opening a view from the dropdown also marks it seen.
- **Postgres full-text search**: cross-module + in-module search is now **dialect-aware** — on Postgres
  it uses `to_tsvector` + a safe **prefix `to_tsquery`** (`conc beam` → `conc:* & beam:*`, so partial
  words and multi-term queries match) ranked by **`ts_rank`**; SQLite (dev) keeps the substring-LIKE
  fallback. No new service (per the earlier no-Elasticsearch decision) and no schema change — the FTS
  is a query-time expression. (For very large prod tables, a GIN index on the tsvector is the natural
  follow-up.)
- Additive migration adds `saved_views.last_seen_at` on startup (nullable ADD COLUMN). Backend 73/73
  (new `test_search_alerts`: alert lifecycle + prefix-tsquery builder + SQLite search); Postgres FTS
  SQL compile-verified (`to_tsvector @@ to_tsquery` + `ts_rank`); web typecheck + 49 tests green.

## v0.3.16 — Bulk-action pickers replace raw prompts (data-entry polish)
- The list bulk-action bar no longer uses `prompt()` for **Assign** / **Transition**: Transition is
  now a dropdown of the module's valid workflow actions + Apply, and Assign is an inline input + Apply
  (Delete stays behind a confirm). Faster, less error-prone bulk edits on a selection — the last
  rough edge from the CRUD/UX audit. Web typecheck + 49 tests green.

## v0.3.15 — Paginated module lists (large registers stay snappy)
- Module list views now **page** the records (100/page) with **‹ Prev / Next ›** controls and a
  position indicator, instead of fetching and rendering every record at once. A register with
  thousands of RFIs/issues/cost codes no longer stalls the browser on open; filter/search/state
  changes reset to the first page. Uses the list endpoint's existing `limit`/`offset` (fetches one
  extra row to detect "more"), so no API change — the pager only appears when the list spills past a
  page. Completes the data-entry UX upgrade set (import → validation → search → pagination).
- Backend 72/72 (limit/offset assertions added); web typecheck + 49 tests green.

## v0.3.14 — Data-entry UX upgrade Phases 2–4: form validation, searchable pickers, faster search
- **Form validation (buy-in + clean data)**: create/edit forms now enforce **required fields
  client-side** — offending inputs get outlined, the first is focused, and submit is blocked with a
  clear "Please fill required field(s): …" message instead of a silent server 422. If the server does
  reject (`missing required field(s): …`), the exact fields are parsed out and highlighted; the form
  keeps all entered values.
- **Searchable reference picker (ties everything together at scale)**: a reference field with more
  than 8 options gets a type-to-filter box, so picking e.g. a cost code stays fast when a project has
  hundreds — the "＋ Add new" inline-create still works.
- **Server-side search (easy to access, scalable — no Elasticsearch)**: the module list/search `q`
  filter now runs in **SQL** (`ref`/`title`/`data`-as-text `LIKE`, applied before `LIMIT`) instead of
  loading a page of rows and scanning JSON in Python — so a search returns the right matches across the
  whole module, not just those on the first page, and scales. Portable across SQLite (dev) and
  Postgres (prod); the JSONB/`tsvector` + GIN upgrade is a clean future step on the same query.
- Backend 72/72 (search assertions added to `test_imports`); web typecheck + 49 tests + Pages build green.

## v0.3.13 — Generic Excel / CSV import for any module (Phase 1 of the data-entry UX upgrade)
- **The #1 data-entry / adoption lever**: every module now has an **⤓ Import** button that bulk-loads
  records from an Excel (.xlsx) or CSV file. New `imports.py` + endpoints
  (`/modules/{key}/import/preview`, `/modules/{key}/import`, `/modules/{key}/import-template.csv`).
- **Two-step, mapping-driven UX**: pick a file → the server sniffs the header row and **auto-maps
  columns to fields** by name/label → a mapping screen lets you adjust each column (or skip), warns
  about unmapped required fields, and shows a sample → import. Type coercion (currency `$1,250` →
  1250.5, dates → ISO, multi-select split); rollup/computed fields excluded. A **blank template**
  download seeds the right headers.
- **Robust + safe**: required-field validation per row (a bad row is reported, never aborts the
  batch), 10k-row import cap, editor-gated + audit-logged. Answers "how do I create a new cost code" —
  the ＋ New form, the inline "＋ Add new" on a reference field, or now a spreadsheet import.
- Verified live: 3 cost codes imported from a CSV via the mapping UI, no console errors. Backend
  72/72 (new `test_imports`); web typecheck + 49 tests green.
- Decision (researched): **no Elasticsearch** — a self-hosted/offline app on Postgres should use
  built-in full-text search; a portable search upgrade lands in a follow-up phase.

## v0.3.12 — UI/UX + security pass over recently-added features
- Consolidated review of four features (site feasibility, feasibility scenario compare, clash-report
  import, BCF viewpoint fidelity).
- **Security**: hardened the clash-report XLSX import against oversized sheets — caps imported issues
  at 5,000 rows and scanned rows at 200,000 (surfacing a `truncated` flag), on top of the existing
  request body-size limit; `read_only` streaming keeps memory bounded. Audited RBAC on every new
  endpoint (feasibility / compare → viewer; clash import → editor + audit log) and confirmed the BCF
  XML parse path uses stdlib ElementTree (no external-entity expansion → not XXE-exploitable).
- **UI/UX**: verified all three new Report-Center tool launchers render and function live against a
  real backend (feasibility envelope, scenario ranking with deltas, clash-report file import), with
  graceful empty states and no console errors.

## v0.3.11 — BCF viewpoint fidelity: orthographic cameras + per-element coloring
- BCF viewpoints now round-trip the **full camera**, not just the view point: camera direction
  (derived from position→target when absent), up-vector, and field-of-view for perspective — plus
  **OrthogonalCamera** (view point + direction + up + view-to-world-scale) so section/elevation
  viewpoints from Solibri / ACC / BIMcollab survive the round-trip instead of collapsing to a bare
  point. Shared helpers (`_camera_xml`/`_parse_camera`) used across every export/import path.
- **Per-element coloring** in viewpoints (`<Coloring><Color><Component/>`) now exports and imports —
  the "the clashing beam is red" emphasis state carries through BCF. Imported viewpoints (incl.
  orthographic + coloured) are re-materialised as `Viewpoint` rows, not just the pin anchor.
- Viewer `captureViewpoint()` now records the projection (perspective/orthographic) + FOV, and
  `jumpToViewpoint()` restores the projection — shared/presence and saved views recreate the actual
  camera. Closes the fidelity gap flagged in the arsray146/ifc-bcf-viewer review.
- Backend 71/71 (BCF test extended with perspective + orthographic + coloring round-trips and an
  end-to-end orthographic-camera import); web typecheck + 49 tests green.

## v0.3.10 — Feasibility scenario comparison (test schemes side by side)
- **New `GET /projects/{pid}/feasibility/compare`** + `feasibility.compare()`: rank every zoning
  scheme (one `zoning` record = one scheme, e.g. "Scheme A · FAR 6" vs "Scheme B · FAR 8") by
  buildable yield — units then GFA — with the binding constraint and Δ-units / Δ-GFA vs. the top
  scheme. The Giraffe-style "test 20 scenarios in the time others analyze one," on the feasibility
  engine shipped in v0.3.8.
- `api.feasibilityCompare()` client + a "▟ Compare feasibility scenarios" tool launcher.
- Backend 71/71; web typecheck + 49 tests green.

## v0.3.9 — Import Solibri / Navisworks clash reports (XLSX → coordination issues)
- **New `clash_import.py` + `POST /projects/{pid}/coordination/import-xlsx`**: drop in a Solibri or
  Navisworks (or any tabular) clash/coordination report `.xlsx` and each row becomes a tracked
  **coordination issue** — which already round-trips to BCF and drops a model pin. GCs receive these
  reports constantly from the BIM coordinator; this turns the spreadsheet into model-anchored issues
  with no re-keying.
- Tolerant parser: sniffs the header row (skips title/preamble rows), maps a wide set of column
  aliases (Solibri Name/Description/Severity/Ruleset/Component-GUID/Location; Navisworks
  Clash-Name/Status/Grid-Location/Item 1/Item 2) by best whole-word match, maps severity → priority
  (Critical/High/Medium/Low), and extracts IFC GlobalIds from one or more component columns into
  `element_guids` so issues anchor on the model.
- `api.importClashXlsx()` client + an "⤓ Import clash report" tool launcher. Inspired by the
  arsray146/ifc-bcf-viewer + addd.io reviews (Solibri/QA-report ingest).
- Backend 71/71; web typecheck + 49 tests green.

## v0.3.8 — Site feasibility / zoning envelope (Giraffe-style) + live-demo fix
- **Fixed the broken live demo**: `massing.build/app/` was 404'ing — GitHub Pages had been switched to
  the legacy branch source (`/docs`), which serves the landing page but not the viewer and conflicts
  with the `pages.yml` Actions deploy. Restored Pages to the "GitHub Actions" source so `/app/`
  deploys again; regenerated the demo snapshot.
- **New `zoning` module + `feasibility.py` engine + `GET /projects/{pid}/feasibility`**: a site
  feasibility / zoning-envelope study (the "Massing" feasibility tool, inspired by Giraffe). From site
  area + zoning controls (FAR, height, floor-to-floor, lot coverage, setbacks, open space, parking,
  unit size) it computes the **maximum buildable GFA as the binding minimum of the FAR cap vs. the
  physical envelope** (footprint × floors), then net buildable area, **unit yield**, parking demand and
  required open space — and **reconciles allowed GFA against the model's actual GFA** (FAR used,
  % of allowed, headroom, over/under) when a source IFC is present.
- New **Site Feasibility / Zoning Envelope** report (Report Center) + a "▟ Site feasibility" tool
  launcher + `api.feasibility()` client method. Demo seeds a zoning record so it's demonstrable.
- Reviewed giraffe.build, synaps.app, addd.io and arsray146/ifc-bcf-viewer; most of their AEC
  capabilities are already covered (clash/BCF, IFC takeoff, dashboards, ask-the-model, reports). Site
  feasibility was the clearest on-brand gap; shipped first.
- Backend 70/70; web typecheck + Pages build green; demo verified live.

## v0.3.7 — Specifications → submittals: spec register, spec-driven submittal log, AI extraction
- New `spec_section` module — the project manual / specification register (CSI MasterFormat section
  number + title, division, the Part 1 "Submittals" article text, Part 2 products, responsible party;
  issued/under-revision/void workflow).
- **Spec-driven submittal log** (`specs.py` + `GET /projects/{pid}/specs/submittal-log`): derives the
  required submittals per spec section from the SectionFormat Part 1 Submittals article (typed via a
  submittal-type classifier — Shop Drawing, Product Data, Sample, Mock-up, Certificate, Test Report,
  Calculations, O&M, Warranty), reconciles them against the submittals actually logged (matched by
  MasterFormat section number), and surfaces **missing submittals** per section with a coverage %.
- **AI/rules submittal extraction** (`ai.extract_submittals` + `POST /specs/extract-submittals`):
  paste spec text → a typed submittal list (Claude when configured, deterministic rules fallback
  offline); `create=true` logs each item as a `submittal` and records the `spec_section`, building the
  log straight from the spec book.
- New **Spec-Driven Submittal Log** report (KPIs, by-type chart, by-section table flagging gaps);
  two tool launchers (spec submittal log; extract submittals from a spec) + client methods.
- Backend 69/69; web typecheck + 49 tests + Pages build green.

## v0.3.6 — Preconstruction depth: decision log, assumptions, VE cycle + alignment dashboard
- New `decision` (cross-stakeholder decision log: rationale, alternatives, cost/schedule impact,
  Aligned/Pending/Disputed) and `assumption` (assumptions & clarifications register with allowance
  exposure) modules. `precon.py` rollups + `GET /precon/decisions` and `/precon/assumptions`:
  open counts, disputed, open cost & schedule exposure, by category.
- **VE cycle** analytics on the existing `value_engineering` module — `GET /precon/ve?target=`:
  proposed/accepted/rejected savings + gap-to-close against an over-budget target.
- **Calibrate-style alignment dashboard** — `GET /precon/alignment`: per-domain RAG (estimate vs budget,
  VE coverage of the gap, decisions, assumptions) + an alignment score. New reports: Decision Log,
  Assumptions & Clarifications, Preconstruction Alignment; tool launchers + client methods.
- Completes the preconstruction-depth parity vs Concntric (estimate continuity + decisions + assumptions
  + VE + alignment). Backend 68/68; typecheck + build green.

## v0.3.5 — Preconstruction estimate continuity (Concntric-style design-phase cost tracking)
- New `estimate_set` module (snapshot tagged by design **milestone** — Concept/SD/DD/CD/IFC/GMP/Award —
  with total, gross SF, basis, source) + `precon.py` engine + `GET /projects/{pid}/precon/estimate-continuity`:
  per-milestone **$/SF**, **milestone-to-milestone cost drift**, first→latest drift, and the **gap vs the
  project budget/GMP** (over/under). A one-click `POST /precon/snapshot?milestone=` prices the current
  model (IFC takeoff) and saves it as an estimate set.
- An **Estimate Continuity** report (PDF/Excel) + Report Center tool launcher; client `estimateContinuity`
  + `preconSnapshot`. Closes the design-phase cost-tracking gap vs Concntric, built on Massing's existing
  estimate/budget primitives. Backend 68/68.

## v0.3.4 — Optional licence enforcement (off by default)
- Licence entitlements can now be **enforced**, but it's **opt-in and OFF by default** — the app stays
  fully open and a licence is optional (no registration) until the operator sets `MASSING_LICENSE_ENFORCE=1`
  (Settings ▸ Massing licence). In open mode every `allows()/require()` gate is a no-op.
- When enabled, gates bite by tier: **IFC export** (`GET /source.ifc`) needs Commercial+ (402 otherwise),
  and **programmatic publishing via the REST API key** (e.g. the pyRevit bridge) needs Commercial+ —
  while interactive "Open IFC…" by a signed-in user stays free on any plan. `require()/require_export()`
  helpers + `_MIN_TIER` upgrade messaging; `/license` + `/capabilities` report `enforced`.
- Settings shows an **"open mode — licence optional"** status when enforcement is off (no nagging).
  Backend 67/67 (open mode grants all; enabling gates IFC/API by tier and clears on upgrade).

## v0.3.3 — Help surfaces the Revit add-in
- The in-app **"Import from Revit for free"** dialog now leads with the one-click **Massing for Revit**
  pyRevit add-in (Publish to Massing), then the free manual IFC-export path and batch pyRevit export,
  with a direct link to the add-in. The docs guide FAQ ("Do I need Revit?") lists the same three paths.
  Keeps the help current with the v0.3.2 bridge + licensing.

## v0.3.2 — Massing for Revit (free pyRevit bridge)
- New **pyRevit extension** (`integrations/pyrevit/Massing.extension`) — a free, open **Revit → Massing**
  bridge that needs no paid Autodesk APS bridge. A **Massing** tab with **Publish to Massing** (exports
  the active model to IFC via Revit's built-in exporter, uploads it, runs the server-side Fragments
  conversion, opens the web viewer), **Open in Massing**, **Sync Issues (BCF)** (RFI/clash/punch
  round-trip over BCF, keyed by IFC GlobalId), and **Settings**.
- `lib/massing_api.py` — a std-lib REST client (works on pyRevit's IronPython 2.7 + CPython 3 engines,
  no `requests`): find/create project → upload `source-ifc` → poll `publish/status` → BCF in/out.
  Covered by `test_revit_bridge.py` (67/67). Built on the LearnRevitAPI StarterKit conventions; uses
  the REST API, so it's a Commercial-plan (and up) path while manual IFC export stays free on any plan.

## v0.3.1 — Massing licensing in Settings
- New `licensing.py` engine + `GET /license`: records the workspace's **Massing licence key**
  (`MASS-XXXX-XXXX-XXXX-XXXX`) and **plan tier** (Free · Home · Commercial · Enterprise) and exposes the
  per-tier feature entitlements (export formats, REST API, SSO, Navisworks) per massing.cloud/docs.
- **Settings** gains a "Massing licence" group (paste key + set plan) and a licence-status line showing
  the active plan, masked key, what it unlocks, and a link to manage at massing.cloud. The key format is
  validated on save (malformed keys / unknown plans are rejected); the key is **masked and never echoed
  back**. `/capabilities` now reports `license_tier`. Backend 66/66.

## v0.3.0 — Massing milestone (analytics + RE/capital depth, hardened, rebranded)
First minor release on the Massing brand — marks a coherent, production-ready milestone after the
0.2.x line: the full **construction-analytics suite** (quality · RFI · submittal · T&M · field-log ·
OSHA safety · closeout) stitched into an executive **project-health rollup**; **real-estate / capital
depth** (lease management, equity-waterfall distributions, investor-portal signed statements, comps
import, WPRealWise/MLS syndication); **production hardening** (non-root API container, `/metrics`,
empty-project + malformed-input regression tests); and the **Massing rebrand** end-to-end. All verified
live in the browser. Backend 65/65; web typecheck + vitest (49) + Pages build green; `npm audit` clean.
- Polish: Excel-export buttons alongside the PDF ones on the rent-roll and cap-table Finance cards
  (backend already served `.xlsx`); optimized the social `og-image.png` (674 KB → 94 KB, palette PNG).

## v0.2.16 — Rebrand to Massing (massing.build)
- Renamed the product from "AEC BIM Platform / ModelMaker" to **Massing** across the app, docs, and
  packaging: window title + PWA name, README/CHANGELOG/SECURITY/guide/roadmap/capability-matrix, the
  Pages landing page (canonical + OG → massing.build), and backend report/branding strings.
- New brand assets — Massing isometric-massing logo + icon (`favicon.svg` / `icon.svg`, header logo,
  landing hero, `docs/img/massing-*`).
- GitHub repo renamed to **ibuilder/massing**; GitHub Pages now serves at **massing.build** (CNAME),
  with `VITE_BASE` switched to root `/app/`. Desktop bundle identifier kept (`com.ibuilder.aecbim`) so
  existing installs keep auto-updating; the updater endpoint follows the renamed repo.
- No functional change — backend 65/65, web typecheck + build green; verified live (title/header/favicon).

## v0.2.15 — Wrap-up: reachability, docs & GitHub refresh
- UI reachability audit of the whole v0.2.x arc — all new features confirmed reachable; closed the one
  gap by folding the **T&M-by-change-event** breakdown into the T&M rollup tool (was PDF-only).
- Docs refreshed to current: README "Recent platform work" now leads with the construction-analytics
  suite + RE/capital depth + production hardening; `SECURITY.md` documents the second signed-anonymous
  surface (investor `statement.public.pdf`) and the non-root API container; GitHub About updated.
- Verified green: backend 65/65, web typecheck + vitest (49) + Pages build, `npm audit` 0 vulnerabilities.

## v0.2.14 — Production hardening: non-root API container + observability test
- The API image now runs as a **non-root user** (`appuser`, uid 10001) — `/app` and the `ifc-data`
  volume path are chowned before mount so the named volume inherits writable ownership; added a
  container-level `HEALTHCHECK` for bare `docker run` (compose already health-gates the stack).
- New `test_metrics.py` (65 suites) locks the `/metrics` Prometheus surface: text exposition with
  `http_requests_total` + latency summary + in-flight gauge + uptime, counted by route template and
  incrementing across requests.
- Closes the production/ops phase — backup/restore runbook, `/metrics`, full healthchecks +
  depends-on conditions, rate-limit env knobs, and the Caddy HTTPS overlay were already in place.

## v0.2.13 — Polish & harden: empty-project robustness + a11y
- New `test_empty_project.py` (64 suites): every analytics / RE surface (14 endpoints + 13 PDF/XLSX
  reports) must return 200 with a sane zeroed structure on a brand-new project — guards the "no data
  yet" path against 500s and blank crashes.
- **Hardened** the equity-waterfall scenario: with no investors in the cap table it now returns a clean
  zeroed result + an explanatory note instead of phantom LP/GP splits; the UI surfaces the note.
- Accessibility: `aria-label`s on the new Finance inputs (capital-call amount, waterfall exit/years,
  comparables CSV textarea + file upload).

## v0.2.12 — Comparables import automation (CSV / RESO) — completes RE/capital depth
- New `comps.py` + `POST /projects/{pid}/comparables/import`: bulk-load comparables from **CSV**
  (`{csv}`) or a **RESO array** (`{reso|rows}`) into the `comparable` module, feeding the
  sales-comparison appraisal. Forgiving header mapping (case/space/underscore-insensitive; accepts
  human headers *and* RESO field names like `UnparsedAddress`/`ClosePrice`/`ClosePricePerSquareFoot`);
  coerces `$1,250,000`/`5.5%`; rows without an address are skipped.
- Appraisal tab: an **Import comparables** card (paste CSV or upload a file → recomputes the sales
  approach); client `importComparables`. Backend 63/63.
- **Milestone:** completes the real-estate / capital depth phase (syndication bridge, lease management,
  equity-waterfall scenarios, investor-portal sharing, comps import). Next: polish & harden, then production/ops.

## v0.2.11 — Investor-portal document sharing (signed statement links)
- `POST /projects/{pid}/investors/{iid}/share` mints a signed, expiring (default 30-day) link to an
  investor's capital-account statement, and `GET …/statement.public.pdf` serves it behind HMAC sig
  verification — the investor opens their statement with **no login** (the private analog of the public
  listing). Forged/absent signatures → 403; reuses `signing.py`, so the RBAC posture is unchanged.
- Finance ▸ Investors: a **🔗** button per cap-table row mints the link and shows a QR/share modal;
  client `shareInvestorStatement`. Backend 63/63 (signed link passes, forged/absent → 403).

## v0.2.10 — Equity-waterfall distribution scenarios (cap-table-tied)
- New `distwaterfall.py` + `POST /projects/{pid}/waterfall`: model a distribution / exit through the
  equity waterfall (preferred return → return of capital → IRR-hurdle **promote tiers**, reusing the
  proforma `run_waterfall`), then **allocate each side's take pro-rata across the actual investor
  records** by commitment. Body: `{exit_amount, contribution_date, exit_date}` or `{distributable[],
  dates[]}`; pref/tiers/style default from the latest proforma scenario, overridable. Returns LP/GP
  totals, IRR & equity multiple, period splits, and the per-investor allocation.
- Finance ▸ Investors gains a **Distribution waterfall (scenario)** card (exit $ + years → LP/GP +
  per-investor); client `waterfallScenario`. Backend 63/63 (waterfall clears to the exit, GP earns
  promote, LP split 2:1 by commitment).

## v0.2.9 — Lease-management depth (renewals · escalations · CAM recovery)
- New `leasemgmt.py` + `GET /projects/{pid}/leases/management`: the **renewal/expiration pipeline**
  (leases expiring ≤90/180/365 days, holdover, options outstanding, rent-at-risk), a forward
  **rent-escalation schedule** (each active lease compounded by its `escalation_pct`, plus the
  portfolio base-rent curve by year), and **CAM / expense-recovery reconciliation** (recoverable
  income = `recovery_psf × rentable_sf` for NNN/recovery leases; pass `?recoverable_opex=` for the
  recovery ratio + over/under-recovery gap).
- A **Lease Management** report (PDF/Excel) + a lease-management card under Finance ▸ Operations
  (expiry buckets, escalation step, CAM recovery); client `leaseManagement`. Backend 63/63.

## v0.2.8 — Real-estate Phase 4: WPRealWise / MLS listing syndication + marketing flyer
- New `re_bridge.py` — a feature-flagged outbound syndication bridge (off unless `REALWISE_URL` +
  `REALWISE_API_KEY` set), mirroring the APS / e-sign bridges. `GET /re-syndication/status` reports
  config; `POST /projects/{pid}/listings/{lid}/syndicate` serializes the listing via `marketing.to_reso()`
  and **upserts it into WPRealWise** (`/wp-json/realwise/v1/listings`, Bearer auth, keyed by `ListingKey`
  so re-pushes update not duplicate). Unconfigured → actionable 422; the RESO export endpoint still works.
- Disposition tab gains **⤴ Syndicate to WPRealWise** (bridge-aware) and a **Marketing Flyer** report
  (`marketing_flyer`, PDF/Excel) alongside the fact sheet. Client `reSyndicationStatus` + `syndicateListing`.
- This completes Phase 4 of docs/realestate-marketing.md (the only deferred real-estate item). `.env.example`
  documents the bridge. Backend 63/63 (test_marketing extended: gate-off 422 + stubbed push asserts
  RESO + ListingKey + Bearer); typecheck + vitest (49) + build green.

## v0.2.7 — Field-capture depth (GPS geotag, offline-queue review, PWA shortcut)
- Field capture now **geotags** records: a "📍 Tag GPS location" one-shot fix stores `gps_lat`/`gps_lon`/
  `gps_accuracy_m` on the captured record (online + queued offline).
- New **offline-queue review** sheet: list pending captures (photo/note + geotag), **Sync now**, or
  discard individual items — reachable from the capture sheet (shown when the queue is non-empty).
- **PWA app shortcut** "Field capture" (manifest `shortcuts`) + a `?capture=1` deep link that opens the
  capture sheet on load — long-press the installed icon to snap a jobsite photo in one tap.

## v0.2.6 — Opt-in self-hosted basemap tiles (GIS)
- New `gis.loadBasemap` + **Open → "Add basemap (self-hosted tiles)…"**: lays a Web-Mercator XYZ raster
  tile grid on the ground as a georeferenced reference overlay (focus lat/lon + zoom; tiles placed at
  their projected metric positions, North → −Z). Lists in the federation panel (align ⛭ / remove) via a
  new `viewer.addReferenceObject`.
- **Offline-first / honors CLAUDE.md:** nothing loads unless the operator supplies a tile-URL template
  (e.g. their own/self-hosted `https://tiles.internal/{z}/{x}/{y}.png`) — no public CDN default.

## v0.2.5 — E57 point-cloud import (server-side, optional pye57)
- New `e57.py` + `POST /convert` (`.e57`) / `GET /convert/e57/status`: converts E57 laser-scan files
  to a decimated `.xyz` (x y z [r g b], capped at 2M points) **server-side**, since there is no viable
  in-browser E57 parser. Optional, dependency-flagged on `pye57` (heavy/native, not a default dep) — the
  status/gate is testable without it and the convert returns an actionable 503 until `pip install pye57`.
- The viewer's **Open mesh / point cloud / GIS…** now accepts `.e57`: it routes the file through the
  converter and loads the resulting point cloud as a reference overlay (federation list, align, remove).
  Clients `e57Status`, `convertE57`. Backend 63/63.

## v0.2.4 — Live e-signature bridge (DocuSeal, self-hosted OSS)
- The feature-flagged 3rd-party e-signature bridge (`esign_bridge.py`) now **implements DocuSeal
  end-to-end** over its REST API (stdlib `urllib`, no SDK): create a template from the rendered PDF →
  open a submission with the signers → return submission id + per-signer signing URLs.
- New `POST /projects/{pid}/contracts/{key}/{rid}/send-for-signature` (renders the doc, routes it,
  stores `data.esign_submission`, audited) + a **"Send for signature"** action in the contract record
  tools; `POST /esign/webhook` reflects provider completion. `GET /esign/status` now reports whether the
  configured provider is `implemented`. Off unless `ESIGN_PROVIDER=docuseal` + `ESIGN_API_KEY`/`ESIGN_BASE_URL`.
- Clients `esignStatus`, `sendForSignature`; transport is monkeypatchable + unit-tested (gating 409,
  template+submission shaping, stored submission, webhook parse). Other providers keep an actionable
  stub. Backend 62/62.

## v0.2.3 — Change-order log + meeting action-item tracker (analytics suite rounded out)
- New `changeorders.py` + `GET /projects/{pid}/change-orders/log`: the **CO value pipeline**
  (pending / approved / executed / rejected), reason mix, schedule-day exposure, ball-in-court, plus
  the upstream **change-event ROM exposure** (potential cost not yet a CO).
- New `actions.py` + `GET /projects/{pid}/action-items/tracker`: **action items** open / overdue /
  by assignee & priority, completion %, and the **meeting log** (by type, last meeting).
- Two new reports — **Change-Order Log** and **Meeting Action-Item Tracker** (PDF/Excel) — plus tool
  launchers; clients `coLog`, `actionTracker`. Backend 62/62.

## v0.2.2 — Executive health banner on the GC dashboard
- The GC dashboard now leads with a **project-health banner** driven by `GET /projects/{pid}/health`:
  a 0–100 score, overall green/amber/red, open/overdue totals, a per-domain RAG chip strip (hover for
  each domain's headline), and the top ranked attention items — the executive rollup surfaced
  first-class instead of only in a tool modal.

## v0.2.1 — Closeout dashboard + project-health executive rollup
- New `closeout.py` engine + `GET /projects/{pid}/closeout/summary`: **punchlist completion &
  ball-in-court** (open=Subcontractor, ready=GC-verify, verified; % complete, overdue, open-cost,
  by trade/priority), **commissioning pass rate** (by result & test type), **completion certificates**,
  **warranty expirations** (active / expiring-90d / expired), and **O&M-manual turnover** (% accepted).
- New `projecthealth.py` engine + `GET /projects/{pid}/health`: an **executive rollup** that stitches
  the seven analytics domains (RFIs, submittals, quality, safety, T&M, field reporting, closeout) into
  per-domain green/amber/red status, an overall 0–100 health score, open/overdue totals, and a ranked
  list of attention items.
- Two new Report-Center reports — **Closeout Dashboard** and **Project Health (Executive)** (PDF/Excel) —
  plus "Project health" (top of tools) and "Closeout dashboard" launchers; clients `projectHealth`,
  `closeoutSummary`. Verified live over HTTP against the preview DB (endpoints + all 6 new PDFs). Backend 62/62.

## v0.2.0 — Safety dashboard (OSHA TRIR / DART) + construction analytics suite complete
- New `safety.py` engine + `GET /projects/{pid}/safety/summary`: **OSHA incident rates** — TRIR,
  DART, LTIFR, and severity rate on the 200,000-hour base, computed from the incident module's
  classification / osha_recordable / lost-days / restricted-days fields. Worker-hours are taken from
  `?hours=`, else estimated from daily-report manpower (man-days × 8h). Also rolls up the
  **safety-observation leading-indicator mix** (safe vs at-risk, safe:at-risk ratio, close-out %),
  **toolbox-talk coverage** (talks + attendees), and the **safety-violation log** (open / overdue / by severity).
- A **Safety Dashboard (OSHA)** report (PDF/Excel) — distinct from the existing simple Safety/Incident
  Log — plus a "Safety dashboard (OSHA)" tool launcher; client `safetySummary`. Backend 62/62.
- **Milestone:** this completes the construction analytics suite — every core field log (submittals,
  RFIs, T&M, quality, daily reports, safety) now has a first-class rollup, exportable report, and tool launcher.

## v0.1.99 — Field-log rollup (daily reports → manpower / weather / coverage)
- New `dailylog.py` engine + `GET /projects/{pid}/daily-reports/summary`: **manpower trend**
  (total / avg-per-day / peak with date, preferring the manpower_log rollup over the typed count),
  **weather-impact lost-day equivalents** (Minor 0.1 / Half 0.5 / Full & Stoppage 1.0), **delay days**,
  and **reporting coverage** (logged days vs the date span), with by-weather & by-impact breakdowns.
- A **Field-Log Rollup** report (PDF/Excel) in the Report Center + a "Field-log rollup" tool launcher;
  client `fieldLogSummary`. Backend 62/62.

## v0.1.98 — RFI register / log analytics
- New `rfi.py` engine + `GET /projects/{pid}/rfi/register`: **ball-in-court** (draft→GC, open→Consultant,
  answered→GC-accept, closed/void), **overdue** (date-required passed while awaiting a response),
  **response turnaround**, and **cost/schedule-impact exposure**, with by-discipline & by-priority breakdowns.
- An **RFI Register** report (PDF/Excel) in the Report Center + an "RFI register" tool launcher;
  client `rfiRegister`. Backend 62/62.

## v0.1.97 — Quality dashboard (inspections / NCR loop / deficiency ball-in-court)
- New `quality.py` engine + `GET /projects/{pid}/quality/summary`: **inspection pass-rate KPIs**
  (pass rate = pass+conditional / decided, first-pass yield = clean pass / decided, by type & result,
  agency count); the **NCR disposition→corrective-action→close loop** (by state/disposition/severity,
  overdue, undispositioned, avg days-to-close); and the **deficiency ball-in-court rollup**
  (open=Subcontractor, corrected=GC-verify, closed; by trade & severity, overdue).
- A **Quality Dashboard** report (PDF/Excel) in the Report Center + a "Quality dashboard" tool
  launcher; client `qualitySummary`. Backend 62/62.

## v0.1.96 — T&M → change-event tie
- eTickets gain a **change_event** link; `tm.by_change_event` rolls up field T&M by the change event
  it belongs to (`GET /tm-by-change-event`), with linked vs unassigned totals — closing the chain
  field T&M → change event → CO → SOV → AIA billing (G702/G703 already in `cost.py`). The T&M Log
  report gains a "T&M by change event" table. Backend 62/62.

## v0.1.95 — RFI/submittal distribution lists
- RFIs & submittals gain a **Distribution (CC)** field; `distribution.py` resolves it (names or emails,
  comma/semicolon/newline-separated) against the **Contact directory** into recipients + emails.
- `GET /projects/{id}/modules/{key}/{rid}/distribution` returns the resolved list; the resolved emails
  now ride the **record.transition webhook** (`distribution: [...]`) so a listener can notify the CC list.
- Tests in `test_distribution.py` (backend 62/62; rfi/submittal fieldsets kept contiguous).

## v0.1.94 — drawing transmittals + issuance diff
- The drawing-set register now classifies each current sheet as **new** vs **revised** (issuance diff)
  and reports `new_count` / `revised_count`.
- **Drawing transmittal PDF** (`GET /drawing-set/transmittal.pdf?to=…&note=…`): the controlled current
  set grouped by discipline with current revision + New/Revised status, recipients and a note — a ⬇
  Transmittal button in the drawing-set view. Backend 61/61.

## v0.1.93 — construction depth: T&M rollup + submittal register
- **T&M / eTicket cost rollup** (`tm.py`): aggregates eTickets into labor/material/equipment totals,
  by status, with **billed vs unbilled**; `GET /tm-summary` + a T&M / eTicket Log report.
- **Submittal register** (`submittals.py`): spec-section-organized log with **turnaround**
  (received→returned), **ball-in-court**, and **overdue** flags (required-on-site passed, not closed);
  `GET /submittals/register` + a Submittal Register report.
- Both auto-list in the Report Center (PDF/Excel) and have interactive launchers in "Project tools &
  analytics". Tests in `test_construction_depth.py` (backend 61/61).

## v0.1.92 — capital calls & distributions now post to the cap table
- `POST /capital-call` and `/distribution` accept `persist: true` — posting each allocation to the
  investor's **contributed** / **distributed** running total, so the cap table's contributed /
  distributed / unreturned (and the statement PDF) track over time instead of being preview-only.
- Investors tab: **Preview** vs **Record** buttons; recording refreshes the cap table live.
- Backend 60/60 (incl. a persisted-call assertion).

## v0.1.91 — dedicated Operations & Investors tabs + investor statements
- Finance gains two first-class sub-tabs: **Operations** (the hold-phase rent roll — occupancy, WALT,
  in-place income, value-from-rent-roll) and **Investors** (cap table, capital-call/distribution
  tools, per-investor downloads) — moved out of the Valuation tab so each has a clean home.
- **Per-investor capital-account statement PDF** (`GET /projects/{id}/investors/{iid}/statement.pdf`):
  commitment, ownership, contributed/distributed, unreturned + unfunded — a ⬇ per row on the cap table.
- Verified live (both tabs render with seeded data; statement link present); backend 60/60.

## v0.1.90 — accessibility pass: every feature reachable in the UI
A UX audit found seven computed features were API/report-only (no buttons). All are now wired in:
- **Finance ▸ Valuation tab** gains a **Rent roll** card (occupancy/WALT/in-place income + "value
  from rent roll"), an **Investor cap table** card with **capital-call / distribution** tools, and
  the existing appraisal/disposition cards.
- **Report Center ▸ Project tools & analytics** adds launchers for the **Project assistant**,
  **WH-347 certified payroll** (week picker + preview), **Drawing-set register**, **ITB coverage**,
  and **Field-verification coverage**. (The rent_roll/cap_table/appraisal/listing reports already
  auto-list there.)
- **Login** now shows an "SSO available — set `AEC_OAUTH_*`" hint when no providers are configured,
  instead of silently hiding sign-in options.
- Verified live (all surfaces render, console clean), authz re-audited (every new endpoint
  `require_role` + project-scoped; financial writes = editor), `npm audit` 0 vulns, and the new
  tables (`mod_lease`, `mod_investor`, `element_verifications`) confirmed to migrate on **Postgres**.

## v0.1.89 — operate, capital, payroll, drawing-set, assistant & ITB
Six capability gaps closed across operations, capital, payroll, drawing-set control, the project
assistant, and invitation-to-bid.
- **Operating asset mgmt (rent roll):** a `lease` module (Operations) + `rentroll.py` — occupancy,
  WALT, lease-expiration schedule, in-place income; `GET /rent-roll` + a Rent Roll report. The
  appraisal income approach can value off the actual roll: `GET /appraisal?rentroll=1`.
- **Investor / LP capital:** an `investor` module (Capital) + `capital.py` — cap table by commitment,
  pro-rata **capital-call** & **distribution** allocation; `GET /cap-table`, `POST /capital-call`,
  `POST /distribution` + a Cap-Table report. Data-room reuses the document module + attachments.
- **Certified payroll (WH-347):** `payroll.py` aggregates timesheets × labor rates into a weekly
  Davis-Bacon certified-payroll PDF (straight/OT split, prevailing-wage flags); `GET /payroll`,
  `GET /payroll/wh347.pdf`.
- **Drawing-set register:** `drawingset.py` derives the controlled current set from `drawing`
  records (latest revision per sheet = current, earlier = superseded) + sheet index + discipline
  rollup; `GET /drawing-set`.
- **Project assistant:** `assistant.py` extends "ask" from the BIM index to the whole project
  (module tallies, schedule, budget, risk, rent roll); `POST /assistant` (+ `/assistant/snapshot`),
  AI-optional (returns the snapshot without a key).
- **ITB tracking:** `itb.py` rolls up bid packages vs submissions (invited / responded / bonded /
  low bid / coverage gaps); `GET /bidding/itb` + `POST /bidding/packages/{id}/invite`.
- Tests: `test_operate_capital`, `test_payroll_drawings`, `test_assistant_itb` (backend 60/60).

## v0.1.88 — model intelligence, field verification & embeddability
Three features adapted from a scan of **Argyle** (AR field verification) and **Flinker** (OpenBIM in
M365) — built to Massing's open, self-hosted, $0 identity (no AR hardware, no MS-365 lock-in).
- **Ask the model** — `POST /projects/{id}/ask` answers plain-English questions ("how many fire-rated
  doors on L3?", "total curtain-wall area") grounded in a snapshot of the property index (counts by
  class/storey, Psets, facets). Uses the configured AI provider; **degrades to the data snapshot**
  when no key is set. A "✦ Ask" button in the Model workspace.
- **Field verification + install coverage** — mark elements **installed / verified / deviation**
  against design (keyed by GUID, photo-anchored) from the element panel; a coverage summary
  (`GET …/verification/coverage`, % verified/installed of the model total) + a **deviation log** for
  the verified-handover to operations. Argyle's core value, no AR hardware. New `ElementVerification`
  table + `routers/verification.py`.
- **Embeddable viewer + outbound webhooks** — `?embed=1` renders a chrome-less, read-only viewer for
  an `<iframe>` / web-component / Teams tab; module transitions fire **outbound webhooks**
  (`AEC_WEBHOOK_URLS`, fail-open) so Power Automate / Zapier / a custom listener can react. New
  `webhooks.py`.
- Tests: `test_ask.py`, `test_verification.py`, `test_webhooks.py`. Verified live (Ask snapshot,
  embed chrome-less, webhook dispatch + fail-open).

## v0.1.87 — workflow engine upgrades
Cross-cutting upgrades to the config-driven modules engine — each lights up across all ~75 modules,
drawn from construction-management workflow best practice.
- **Transition field-gating** — a workflow transition can declare `requires: [field, …]` that must be
  filled before it fires (RFI can't be *Answered* without an answer). `available_actions` advertises
  it; the action button disables with a "(needs …)" hint until satisfied. Generalizes the attachment
  evidence-gate.
- **Company / Contact directory + first-class lookups** — new `company` + `contact` modules; vendor /
  sub / contact fields become `reference` lookups into the directory (`subcontract.vendor_company`),
  with the picker, resolution and reverse links for free.
- **Due dates / SLA feed** — `GET /projects/{pid}/due-feed` + a "⏰ Deadlines" portal-home widget:
  open records past or near their due date (overdue / due-this-week), across the 11 modules with a
  due field; terminal/closed records excluded.
- **In-app workflow map** — the record view renders a compact state diagram (current state
  highlighted, reachable next-states emphasized). (Saved views already existed.)
- Tests: `test_workflow_gate.py`, `test_due_feed.py`, `test_directory.py` (backend 54 suites).

## v0.1.86 — disposition & valuation (real-estate marketing)
Close the development loop from build to **sell/lease** and **market value** — the two things only a
BIM-native platform can do, because Massing owns the model + proforma. (See
[docs/realestate-marketing.md](docs/realestate-marketing.md).)
- **BIM-native marketing kit** — a config-driven `listing` module (RESO-aligned fields + a workflow
  mirroring RESO `StandardStatus`) that **auto-fills from the project**: areas/unit-mix from the model,
  NOI/cap/asking price from the proforma. One click generates a **Listing Fact Sheet** PDF and a
  signed, expiring **public link + QR** to share a listing without a session (the only anonymous
  surface — token-scoped, read-only, rate-limited).
- **Tri-approach appraisal** — `appraisal.py` fuses the three classic approaches from data already
  in-system: **Cost** (replacement cost from the estimate + land − depreciation), **Income** (NOI ÷
  cap from the proforma), **Sales comparison** (adjusted $/SF from the `comparable` module),
  reconciled into an opinion of value with a range. New **Valuation** tab in Finance (three approach
  cards, editable reconciliation weights, value-by-approach chart) + a **Valuation report** (PDF/Excel).
- **RESO export seam** — `marketing.to_reso()` serializes a listing to RESO Data Dictionary fields, so
  a later bridge can push listings to WPRealWise / an MLS as a serialization, not a rewrite.
- Endpoints: `GET /projects/{pid}/listings/autofill`, `GET|POST /projects/{pid}/appraisal`,
  `GET …/listings/{lid}/reso`, `POST …/listings/{lid}/share`, `GET …/listings/{lid}/public`.
  Tests: `test_appraisal.py` (engine) + `test_marketing.py` (autofill → appraisal → reports → RESO →
  signed public link).

## v0.1.85 — production readiness
- **Readiness probe:** new `GET /ready` (and `/readyz`) pings the DB (`SELECT 1`) and returns `503`
  when it's unreachable, so a load balancer / orchestrator stops routing to a degraded instance;
  `GET /health` (`/healthz`) stays a cheap dependency-free liveness check. The ping runs under a hard
  wall-clock timeout (`AEC_READY_TIMEOUT`, default 3s) and the Postgres engine gets a connect timeout +
  TCP keepalives, so a *black-holed* DB (paused host / partition) yields a prompt `503` instead of
  hanging the probe — verified against a real paused Postgres.
- **Multi-worker login lockout:** the brute-force lockout now shares its counter across workers via
  `AEC_REDIS_URL` (atomic Redis `INCR`+`EXPIRE`), fail-open to the in-process counter — matching the
  per-IP rate limiter. The API runs multi-worker in production, so the lockout now actually holds.
- **Hardened-by-default deploy:** `docker-compose.prod.yml` now sets RBAC, `AEC_REQUIRE_SECRET`,
  HSTS, secure cookie, strict CSP, body cap, rate limit, and ships a `redis` service for the shared
  counters; `.env.example` documents every hardening flag (and how to generate a strong secret).
- **Schema migrations documented + tested:** the app uses an additive, dbDelta-style startup sync
  (fits the config-driven dynamic module tables) rather than Alembic; `SECURITY.md` documents the
  policy + the manual escape hatch for non-additive changes, and `test_migrate.py` proves a new
  nullable model column is ALTERed onto an existing DB and new indexes backfill (additive-only).

## v0.1.84 — security hardening
- **Access control:** RBAC defense-in-depth gate (anonymous blocked from project/finance/admin
  prefixes when `AEC_RBAC=1`), `require_role` on every project-scoped finance/data endpoint, attachment
  download IDOR fixed, projects list scoped to the caller's memberships.
- **Hardening headers** on every response (nosniff, frame DENY, referrer, CSP) + **opt-in strict CSP**
  (`AEC_CSP=1`); **request body-size cap** (`AEC_MAX_UPLOAD_MB` → 413).
- **Path traversal** closed at the storage layer (resolved-path containment) + upload-filename sanitization.
- **Auth:** login brute-force lockout (429), `Secure` auth cookie over HTTPS, fail-fast on a default
  signing secret (`AEC_REQUIRE_SECRET=1`).
- **Signed/expiring download URLs** for `model.frag` + attachments (HMAC, short-lived) — for QR share /
  worker fetch / deep links without a session.
- **Docs:** new `SECURITY.md` (disclosure policy, threat model, production env-flag checklist).
- Production npm dependencies carry no known vulnerabilities (CI runs `pip-audit` + `npm audit`).

## v0.1.83 — charts & graphs (construction + real-estate best practice)
- **Reusable SVG chart kit** (`ui/charts.ts`, dependency-free, theme-aware): multi-series line
  (S-curve), grouped/stacked bar, waterfall, tornado, histogram, donut, progress bar, sparkline.
- **Finance (proforma)** — Underwriting: a **capital-stack donut** (debt/LP/GP), a **JV-distributions
  donut**, equity cash-flow bars, and a one-way **IRR tornado** (derived from the 2-way matrix).
  Statements: **NOI vs net-income** line + **cash-flow-by-year** stacked bar.
- **Construction (GC portal)** — executive **progress bars** (% complete · bought-out · spent) and a
  **budget vs committed vs actual vs EAC** grouped bar by category.
- **Report Center** — charts embedded in the PDFs (cost bar, EVM cash-flow S-curve, financials
  NOI/net-income line) via reportlab's built-in graphics; Excel keeps the data tables for re-charting.

## v0.1.82 — financial statements & tax modeling
- **Three financial statements + tax** — the Finance proforma gains a **Statements** tab (and a
  Report-Center "Financial Statements" PDF/Excel) built on `financials.py`:
  - **Income statement** — stabilized operating P&L (Potential Gross Rent → vacancy/credit → Effective
    Gross Income → operating expenses → **NOI**; then interest, straight-line **depreciation**, income
    tax → **net income**) plus a year-by-year operating summary.
  - **Balance sheet** — Assets (land + improvements net of accumulated depreciation + capitalized
    financing + cash) = Liabilities (loan) + Equity (paid-in + retained); **balances every year**.
  - **Cash-flow statement** — GAAP three-section (Operating / Investing / Financing), indirect method.
  - **Tax** — 27.5-yr residential / 39-yr commercial straight-line (land non-depreciable), annual income
    tax with **passive-loss carryforward** (§469: loss years are suspended, offset later income, and the
    remainder releases against the gain at sale), and at sale **§1250 depreciation recapture** (≤25%)
    stacked on **capital gains** (+ NIIT) — driving an **after-tax** equity IRR / multiple. Institutional
    defaults, overridable via a `tax` block.
  - **Per-year columns** — columnar **balance sheet by year** (balances every column) and **cash flow by
    year** alongside the stabilized-snapshot cards.
  - **Two-sided budget** — the development budget as **Uses** (left) vs **Sources** (right); both tie.
  - Endpoints: `POST /proforma/financials`, `GET /projects/{pid}/financials`,
    `GET /projects/{pid}/budget/two-sided`.

## v0.1.81 — properties panel, multi-city permits, money + BCF hardening
- **Robust properties panel** — the element inspector is now structured (IFC-class badge, copyable GUID,
  collapsible **Attributes / Quantities / Property Sets** with counts), formats values (numbers,
  Yes/No, dashed empties, `{value,unit}`), and adds a live **filter**, per-row click-to-copy, and
  **Copy all**. Quantities (qtos) are shown for the first time; the no-backend fallback renders a
  collapsible tree instead of raw JSON.
- **Interchangeable multi-city permit open data** — a Socrata-based feed (NYC · SF · Chicago · LA ·
  Austin, one-entry to add a city) normalized to one record shape; query near a point/by text, a GeoJSON
  GIS overlay, and a **"Import from city open data"** action that seeds the GC `permit` log
  (source-tagged, deduped). From the github.com/ibuilder portfolio review.
- **Sources & Uses reconciles to the dollar** — line items now sum exactly to the totals and sources tie
  to uses (no per-line rounding drift); `balanced` is a strict check. (WPLedger money-handling review.)
- **BCF round-trip preserves pins** — project-Topic export/import now carry a pin's element GUIDs +
  anchor (previously dropped); 5 orphaned test suites wired into CI; empty/cyclic-project edge cases and
  a 404 (not 500) for unknown modules. Backend suites: 47.
- **Schedule acceleration advisory** — rule-based crash / fast-track / near-critical levers off the CPM
  critical path; `GET /projects/{pid}/schedule/optimize` + an "Accelerate (advisory)" tool. Advisory only.
- **Project risk digest** — cost + schedule + open-items + safety drivers with a prioritized narrative;
  `GET /projects/{pid}/risk-digest` + a Report Center "Risk Digest" report.

### audit follow-ups (ties, queue-readiness, RFI triage, schedule alerts)
- **Predictive schedule alerts** — `GET /projects/{pid}/schedule/alerts` (+ a section in the Executive
  report): overdue work, late / at-risk starts (incomplete predecessor), behind-schedule SPI, and a
  procurement-risk proxy, from the cost-loaded schedule + CPM.
- **AI RFI triage** — categorize + ball-in-court + draft response (see e-sign/AI sections).
- **Relationship ties** — COR ⤳ SOV line, awarded bid ⤳ subcontract conversions; cor→change_event ref.
- **Queue-readiness (no Celery)** — IFC publish extracted to a worker-callable `run_publish(pid)` +
  interrupted-job recovery; rationale in docs/audit-2026-06.md.

### PDF digital signatures (PAdES) + e-sign options
- **Digitally sign (PAdES)** — a contract/CO can be signed with a certificate-based **PAdES** digital
  signature (a true digital signature, not a SaaS e-signature) via **pyHanko**: the document is
  rendered, signed (tamper-evident, self-validating), attached, and the signer + cert
  **fingerprint** recorded. Uses a self-signed
  platform certificate by default (offline, no cost); set `ESIGN_P12` to sign with your own / a CA cert.
- **3rd-party bridge (feature-flagged)** — `esign_bridge.py` + `GET /esign/status` scope DocuSign /
  Dropbox Sign / self-hosted DocuSeal·Documenso for legally-binding multi-party signing (off until
  `ESIGN_PROVIDER` is configured). Decision write-up in **docs/esign-options.md** (electronic vs
  digital vs SaaS vs OSS; eIDAS / ESIGN Act / UETA; recommendation).

### Report Center (detailed, exportable reports)
- **📊 Report Center** — a catalog of detailed reports, each downloadable as **PDF or Excel**:
  **Executive Summary** (CPI/SPI/EAC, % complete, open RFIs/submittals/COs, safety), **Cost Report**
  (budget/committed/actual/forecast/variance by category), **EVM / S-Curve** (SPI, EAC, cash-flow
  curve), and operational logs (Change Order / RFI / Submittal / Daily / Safety) + **Contracts &
  Signatures**. Built from the existing px / budget / module engines (`reports.py`); endpoints
  `GET /reports` + `GET /projects/{pid}/reports/{report}.{pdf,xlsx}`. Opens from the 📊 toolbar button.

### contract & change-order document lifecycle
- **Generate contract documents** — from a contract record: **Prime Contract**, **Subcontract**
  (AIA A401-style), and **Change Order** (AIA G701-style, showing original → revised contract sum)
  PDFs, merged with project/contract data (`contracts.py`, reportlab).
- **Exhibit generator** — **Compose Exhibit A — Scope of Work** from an editable clause/scope library
  (`scope_library.py`: general/supplementary conditions + per-CSI-division scopes with `{{merge}}`
  tokens); pick clauses → exhibit PDF, attachable to the record.
- **View & markup** — open any generated contract/CO in the PDF markup overlay to redline
  before signing.
- **Signatures & approval** — capture per-party typed signatures (`POST …/contracts/{key}/{rid}/sign`,
  one per party, audited) that render into the document; route/approve via the existing party-gated
  workflow. Endpoints: `GET /scope-library`, `GET …/contracts/{key}/{rid}/document.pdf?doc=&clauses=&attach=`.

### AI estimate (text → BOQ)
- **Draft a Bill of Quantities from a description** — the conceptual-estimate tool gains
  **✨ Draft BOQ from description**: type the scope and the AI returns priced line items
  (description / qty / unit / rate / CSI division) with a rolled-up total. Reuses the existing
  Anthropic provider + `ai_enabled()` gate; degrades to a clean stub (no fabricated numbers) when no
  API key is configured. Endpoint `POST /projects/{pid}/ai/estimate`.

### regional classification standards + GAEB export
- **Regional classifications** — map the model estimate's IFC-class line items to **DIN 276** (DACH),
  **RICS NRM 1** (UK), or **CSI MasterFormat** (US/CA) via `GET /classifications` + a built-in code
  table (`classification.py`).
- **GAEB DA XML (X83) export** — `GET /projects/{pid}/estimate/gaeb.x83?system=…` exports the
  estimate as a GAEB 3.2 Bill of Quantities (the DACH tender standard); the conceptual-estimate
  result now has **↧ GAEB · DIN 276 / NRM 1 / MasterFormat** download buttons.

### PDF takeoff & markup
- **PDF takeoff** — **Drawings → 📄 PDF Takeoff** opens a PDF drawing (pdf.js, offline worker),
  lets you **calibrate the scale** (draw a line, enter its real length), then **measure distance /
  area**, **count** items, and drop **rectangle** annotations directly on the sheet — with a running
  Σ length / area / count panel, an editable measurement list, and **CSV export** of the takeoff
  lines. Coordinates are stored in PDF user-space so measurements stay correct as you zoom.

### GIS / topography layer
- **Import GIS & topography** — **Open ▾ → Open mesh / point cloud / GIS…** now also opens
  **GeoJSON** (parcels, contours, site vectors → points/lines/filled polygons) and **GeoTIFF DEMs**
  (→ a hypsometric terrain mesh displaced by elevation). Layers are georeferenced (lon/lat projected
  to metres; projected coords pass through), list in the federation panel, and align with the same
  ⛭ transform / working-origin as other reference models. Offline (`geotiff` + `earcut`, no CDN).

### model federation, alignment & federated clash
- **Navisworks-style model layering** — each reference overlay (mesh / point cloud) now has a ⛭
  transform panel in the federation list: X/Y/Z offset, a **Z-up → Y-up** flip, uniform scale,
  **Move to picked point**, and Reset — so you can align several models in one space.
- **Multi-discipline models** — append discipline IFCs (STR / MEP / ARCH …) to a project via the
  Coordination panel's **＋ Add discipline IFC** (or `POST /projects/{pid}/models`); they layer in
  the viewer and join clash.
- **Federated (cross-discipline) clash** — **🔗 Federated clash** runs `detect_federated_files`
  across the project's layered models (primary source IFC + appended disciplines), excludes
  intra-model overlaps, lists clashes grouped by model-pair, and turns the top hits into BCF clash
  topics → pins / Issues. (Clash needs real IFC geometry — meshes/point clouds don't clash.)

### multi-format reference models + QR share
- **Open meshes & point clouds** — alongside IFC/Fragments, the viewer now opens **OBJ, STL, PLY,
  glTF/GLB** meshes and **PCD, XYZ, LAS, LAZ** point clouds as **view-only reference overlays** (IFC
  stays the source of truth). LAS/LAZ are decoded locally (offline) via a vendored `laz-perf` WASM;
  big clouds are decimated to stay responsive. Reference models list in the federation panel with
  visibility + remove. **Open ▾ → Open mesh / point cloud…**
- **QR share** — a toolbar **📱 Share via QR** shows a scannable deep link to open the project on a
  phone/tablet.
- **Faster Open IFC** — the native file dialog now appears instantly (the heavy 3D module warms in
  parallel); large IFCs (>~60 MB) route through the server pipeline and stream optimized fragments
  instead of parsing the whole file in-browser.
- **Live demo shows the full platform** — the GitHub Pages viewer-only build now bundles a read-only
  sample project so the GC portal, Budget/GMP, Schedule and Finance panels render with real data.

## v0.1.80 — multi-user persona views + optional paid RVT→IFC bridge
- **Membership shapes the view** — a project member's party role (GC / Owner / Consultant /
  Subcontractor) now auto-selects their persona on open, so they land in the right workspace set;
  capability role already gated edit controls. Members modal (add / role / party / remove) present.
- **Revit (.rvt) → IFC bridge (optional, paid)** — feature-flagged on `APS_CLIENT_ID/SECRET`, doubly
  gated: bridge off → 501 + the free IFC-export path; on → must `confirm_cost` (Autodesk bills per
  conversion). Real RVT→IFC runs Revit's exporter via APS Design Automation (`APS_DA_ACTIVITY`).

## v0.1.79 — 4D colour scrub + quantity takeoff by floor
- **Time-aware 4D scrub** — scrubbing the timeline paints the model green floor-by-floor (rest
  ghosted) with a live **cost-burn** readout from the cost-loaded cash-flow curve.
- **QTO by floor & discipline** — quantities + cost mapped to the storey they sit on, per-floor
  totals + a discipline (IFC class) roll-up.

## v0.1.77–78 — 5D element intelligence
- **Click an element → its 5D** — schedule activity (%-complete, dates, hard-tied vs by-trade) +
  cost-code budget vs committed vs actual. **Model heatmap** — colour by %-complete or cost variance.
- **One-click generate seeds the GC portal** — lot→building→deal also creates cost codes, a
  hard-cost-allocated budget, a GMP prime contract, and a cost-loaded schedule.

## v0.1.73–76 — dashboards + investor deliverables, one language
- **Developer Overview command center** + cross-pillar **Portfolio** (GC status *and* developer
  returns per project, blended IRR), one-click **Save scenario**, and a **Construction Status**
  section in the investor memo + deck. **PX executive band** — on-schedule next to on-budget.

## v0.1.67–72 — developer ↔ GC capital chain
- **GMP ↔ hard-cost reconciliation + one-click sync**, construction **draws** from the schedule, an
  **actuals loop** (owner invoices → re-forecast IRR), **construction-loan draws** (equity-first)
  with **interest accrual** + **per-cost-code composition**, and a **lender draw-request PDF**.

## v0.1.60–66 — GMP project budget (its own destination)
- **Budget** is a first-class destination: the agreed GMP broken to every cost code & bid package +
  General Conditions / Requirements (incl. **staffing** projections) + overhead / fee / contingency,
  each budget vs committed vs actual vs **EAC/ETC**. **Buyout savings**, **change orders → revised
  GMP**, owner **SOV from the budget**, a **cash-flow S-curve**, **baseline + variance** — reconciled
  to the developer proforma's hard cost.

## v0.1.53–59 — relational schedule, field/mobile, GC module depth
- **Relational scheduling** — `schedule_activity` drives the Gantt / Line-of-Balance / CPM **and**
  the 3D 4D model; editable P6 `.xer` import; **lookahead** + **milestone** schedules.
- **Field/mobile** — bulk photo + camera capture, photo-first records, offline upload queue;
  **coordination-issue BCF round-trip**.
- **GC module depth** — ball-in-court, super/PM personas, fieldsets, researched Tier-1/2/3 field sets
  across the 73 modules. **Release pipeline hardened** (version from git tag; single-draft publish).

## v0.1.52 — GC dashboard redesigned as a command center
- **Dashboard rebuilt around the new nav rail** — the redundant "All modules" catalog is gone (the
  persistent left rail owns navigation now), and the dashboard is a focused command center: **clickable
  KPI cards** that jump straight to the relevant filtered module (Open RFIs → RFIs · open), a risk
  summary, a prominent **"Ball in your court"** action list (with a caught-up empty state), a grouped
  **Project health** card (budget over/under + safety + lean PPC), trend charts, and Ask AI at the
  bottom — in a two-column layout that stacks on narrow screens.

## v0.1.51 — cost-code workflow: inline add + wider links (roadmap D1 + X1)
- **Inline "add new" from reference dropdowns (D1)** — every reference field (cost code, location, sub…)
  now has a "＋ Add new …" option that creates the record without leaving the form and selects it. So
  while coding a budget line you add the cost code on the spot. Falls back to the target module's
  required field, so a new Cost Code is created with its `code`.
- **Cost-code links on cost-impacting modules (X1)** — RFIs, CORs, change events, PCO requests and
  proposals gained a `cost_code` reference, so impacts tag a code and roll up to the budget (joining
  budget/commitment/direct-cost/timesheet). `/modules` now exposes `title_field`/`ref_prefix`.

## v0.1.50 — GC portal navigation rail + module improvement roadmap
- **Persistent left nav rail in the GC portal** — opening a module used to replace the whole panel, so
  moving between the 73 modules meant going "back" every time. Now a sticky left rail (Dashboard +
  filter + favorites + collapsible sections) stays visible and loads each module into a content pane —
  jump anywhere in one click, with the active module highlighted. (Stacks above the content on phones.)
- **GC module deep-dive roadmap** ([docs/gc-modules-roadmap.md](docs/gc-modules-roadmap.md)) — a
  field-by-field audit of all 73 modules against how large GCs run these workflows, with cross-cutting
  themes (cost-code links everywhere, ball-in-court
  /assignee, fieldsets, inline add-from-dropdown, super-vs-PM views, cross-module conversions) and
  tiered per-module priorities. How to **add cost codes**: Construction → Cost Codes (Resources) → + Add.

## v0.1.49 — left rail revamp (crisp icons + expandable labels)
- **Modernized the left icon rail** — the oldest piece of the UI. The cryptic `⌗`/`≣` Unicode glyphs
  are replaced with crisp inline **SVG icons** (hierarchy / layers / flag / gear), and the rail is now
  **expandable** (VS Code activity-bar style): a `‹`/`›` toggle widens it 46→150 px to show **Tree /
  Layers / Issues / Tools** labels beside each icon, persisted to localStorage. Structure unchanged
  (the four Model-workspace panels were already the right set); this is legibility + feel.

## v0.1.48 — closeout package reachable in the UI
- **Full turnover .zip now has UI access** — the `closeout/package.zip` deliverable (as-built IFC +
  COBie/QTO/space workbooks + status report + closeout records) worked via the API but had **no
  button anywhere**. Added it to **Save ▾ → Closeout package (.zip)** and the **Tools → Exports**
  panel (📦). Found by debugging every menu item against a real demo project. (The `.mmproj` bundle —
  geometry + full database + blobs, round-trips via Open/Save — was already wired.)

## v0.1.47 — end-to-end demo hardening (closeout filename + generate→finance)
Two real bugs found by a full login→closeout demo run (only surface with a realistic project):
- **Closeout package 500** on any project name containing a non-latin-1 char (em-dash, smart quote,
  accent, emoji): the name went into a `Content-Disposition` header, which HTTP encodes as latin-1 →
  crash. Fixed with a shared `safe_filename()` (also hardens the `.mmproj` bundle vs CJK/emoji).
- **Finance showed $0 right after generating a model**: generate didn't persist a cost budget, so
  Sources & Uses read the empty starter. Generate now seeds a `dev_budget` (land + hard from GFA×$/sf
  + soft) → Finance immediately shows the real deal ($21.2M uses on the demo).
Regression-locked: the closeout test now uses an em-dash project name; the generate test asserts
non-zero Sources & Uses. Full gate green (API 30/30).

## v0.1.46 — Studio UX hardening
- **Studio layout bug fixed** — `#panel-studio` carries both `.fullpanel` and `.studio`, and
  `.fullpanel.active{display:block}` was overriding `.studio{display:flex}`, so the node canvas grew
  to its full 1700 px content instead of filling the viewport. Now a higher-specificity rule forces
  the flex column; the canvas is viewport-bounded and **scrolls internally**.
- **Touch support** — node dragging uses pointer events (+ `setPointerCapture`, `touch-action:none`),
  so it works on tablets/phones, not just mouse.
- **Empty-state guidance** — an in-viewport hint ("add a node… then wire… Run", or "connect the API")
  when the canvas is empty.
- **Smarter node placement** — new nodes drop into the current scroll viewport (with a small cascade)
  instead of a fixed corner that overlapped after a few adds.

## v0.1.45 — custom unit-mix editor (A1b — Test Fit A-theme complete)
- **Define your own unit mix** — the Test Fit panel gains an editor to add/remove unit types
  (name · target SF · mix %), saved to localStorage. "Compare schemes" sends it with `with_defaults`
  so your mix is **ranked against the built-in presets**. Completes A1b — the Test Fit A-theme
  (A1–A6 + egress check + auto egress geometry) is now fully done.

## v0.1.44 — P6 .xer → 4D dates + auto code-positioned egress (A2)
- **Primavera P6 schedule → 4D dates** — `POST /projects/{id}/schedule/import-xer` parses a P6 `.xer`
  (TASK table) and stores it; the **4D scrub then reports real calendar dates** (`source:"p6"`, the
  project's start→finish window) instead of relative takt days. New "⬆ Import P6 schedule (.xer)"
  button beside the 4D tool; a 📅 line shows the imported range. `DELETE …/import-xer` reverts to takt.
  (Element build-order stays takt-derived — no per-activity element mapping is claimed.)
- **A2 — auto code-positioned egress geometry** — generated models with a service core now place
  **two means of egress**: the core stair plus a second "Egress stair 2" at the opposite corner
  (≥⅓-diagonal remoteness, IBC 1007.1.1). Completes the generative half of Test Fit A2 (the egress
  pass/fail check already existed).

## v0.1.43 — demo-aware empty states, mobile/PWA polish, P6 .xer import
- **Demo-aware empty states** — the GC portal & drawings no longer show a misleading "pick a project"
  in the viewer-only Pages demo (there's no backend there). A shared `noProjectHtml` explains it's the
  viewer demo + links to the full app; in the real app it gives an actionable "create/open a project"
  hint.
- **Mobile / PWA polish** — `touch-action:none` + `overscroll-behavior:none` on the 3D container so
  camera-controls own touch gestures (orbit/pan/pinch) instead of the page scrolling; PWA install meta
  (theme-color, apple-mobile-web-app-*, viewport-fit=cover); bigger tap targets for the rail + viewer
  tools on phones.
- **Primavera P6 .xer schedule import** — `schedule.parse_xer` reads the TASK table (planned→actual→
  early date fallback) into the activity rows the CSV mapping path consumes, so a P6 schedule can drive
  the 4D scrub. `.mpp` stays export-to-XML/CSV (proprietary binary). Gated in test_analysis.
- **Roadmap reconciled** — A-theme status clarified (A1/A3/A4/A5/A6 + egress check + parking geometry
  + polygon offset done; only unit-type presets + auto-placed egress geometry remain); schedule-import
  + "what else to import" + Revit/Navisworks-plugin + IFC5-alpha verdicts recorded.

## v0.1.42 — main.ts refactor round 2 (account/admin UI) + login on modalShell
- **Modularization** — the account / auth / admin surface (sign-in + SSO, reset, account menu,
  self-service password, admin user management, audit log, project-member management; ~330 lines)
  moves out of `main.ts` into `account/accountUI.ts` behind a small deps object. With round 1's
  connections extraction, **`main.ts` drops from 1205 → 657 lines**.
- **Login fix** — the sign-in dialog hand-rolled its own overlay and so lacked Esc-to-close, a focus
  trap and dialog ARIA. It's now built on the shared `modalShell` like every other modal — consistent
  look + behaviour + accessibility.

## v0.1.41 — main.ts modularization (round 1) + XSS hardening
- **Security (stored-XSS fixes)** — admin modals interpolated user/remote values straight into
  `innerHTML`. Now escaped via a shared `escapeHtml`: connection **name/type**, Procore **project ID**
  + sync info, **browsed DB** column names & cell values, and audit-log fields (the audit modal's
  weaker local escaper is replaced). No user- or database-controlled string renders as HTML anymore.
- **Modularization + perf** — the ~240-line admin **Data-connections UI** (list/add, Procore
  schedules + field-mapping, SQL browser) moved out of `main.ts` into `connections/connectionsUI.ts`,
  **lazily imported** so its ~13 kB leaves the initial bundle and loads only when an admin opens it.
  `main.ts` drops from ~1205 to 963 lines. Behavior unchanged; verified via the vite transform
  pipeline + typecheck + web unit tests.

## v0.1.40 — viewer camera fix + egress surfaced (UX verification pass)
- **Fix: NaN camera / broken 3D view** — loading a model while the Model workspace wasn't visible
  (e.g. a reload that restored the Finance/Drawings workspace, or opening a model from another
  workspace) created the viewer in a 0×0 container, making `camera.aspect` = 0/0 = NaN; the subsequent
  `fitToSphere` baked NaN into the camera position and the viewport showed nothing once you switched
  to Model. Now the fit is **deferred while the viewport is hidden** and run once it has real
  dimensions, the aspect is forced valid synchronously (OBC's ResizeObserver is async), and a
  hard camera reset recovers an already-NaN camera that `setLookAt` alone can't clear.
- **Egress / life-safety now reachable** — the deepened A2 check (occupant load, travel distance,
  required exits, exit separation) was computed but had no UI. `test-fit/compare` now returns the
  plate-level egress result and the Test Fit panel shows a ✅/⚠️ life-safety line with the figures and
  any code flags.
- Found during a full hands-on verification of everything built this session (viewer tools, Studio
  node editor, generate+parking, families/import, deck, lien waivers, COBie, dashboard, 4D) — all
  others confirmed working end-to-end.

## v0.1.39 — accessibility pass (tab semantics, labels, live region)
- **a11y** — the workspace switcher and finance sub-tabs now carry `role="tablist"`/`role="tab"` with
  `aria-selected` kept in sync as you switch (screen readers announce the active view); the role/persona
  picker gained an `aria-label`; and the status bar is a polite `role="status"` live region so status
  updates are announced. Builds on the existing landmarks (`main`/`nav`/`header`/`footer`), `lang`, and
  icon-button `aria-label`s.

## v0.1.38 — Redis rate limiting (multi-worker) + dashboard perf
- **Distributed rate limiter** — set `AEC_REDIS_URL` and the per-IP request limit is now shared across
  workers/processes via an atomic Redis `INCR`+`EXPIRE` (fixed 60s window), so the limit holds under a
  multi-worker deployment instead of being per-process. Fail-open: any Redis error falls back to the
  in-process bucket so limiter infrastructure can never take the API down; redis is imported lazily
  only when the URL is set (no new dependency for the single-worker/desktop build). New `test_ratelimit`
  gate covers the enforcement path (health/metrics exempt, 429 + Retry-After past the limit).
- **Dashboard perf** — the GC dashboard no longer loads and JSON-parses every record across all
  modules. Status tallies now come from a single indexed `GROUP BY workflow_state` per module (zero
  JSON), and the `data` blob is parsed only for the **active** (non-terminal) records that feed
  overdue + action-items — so completed-record-heavy projects build the dashboard far faster. Output
  is byte-for-byte identical (`test_dashboard` unchanged).

## v0.1.37 — COBie field depth (C2) + investment-deck market/timeline slides
- **COBie model-derived field enrichment (C2)** — the handover sheets gain the fields FM teams use:
  Space net/gross **area** + usable height (from Qto), Type **manufacturer / model / warranty /
  expected-life / replacement-cost / color / material**, Component **serial / install-date /
  warranty-start / tag / asset-id**, plus a new **Attribute** sheet that flattens every remaining
  property set (Name/Value/SheetName/RowName) so nothing is lost in handover.
- **Investment deck — Market & Timeline slides** — the pitch deck grows from 4 to 6 slides: a
  **Market & positioning** slide plotting the deal's yield/IRR/soft-cost against conceptual benchmark
  bands, and a **Development timeline** gantt bar (predev → construction → lease-up → stabilization →
  exit, durations from the saved scenario), plus a **site photo** on the cover from project attachments.

## v0.1.36 — printable statutory lien-waiver documents
- **Lien-waiver documents / PDFs** — pay-app accounting, lien-waiver *record tracking* and COBie
  enrichment already shipped earlier; this adds the piece they lacked: the actual **printable
  statutory waiver form**. `cost.lien_waiver` renders the four conditional/unconditional ×
  progress/final forms (Cal. Civ. Code §8132–8138 style) from a pay application — notice, body and
  amount (current payment due for progress, contract sum to date for final) — exposed as
  `GET /projects/{id}/cost/lien-waiver` (JSON) and `.pdf`, plus a "⚖ Lien waiver / release" action in
  the viewer cost panel. Complements the existing `POST /cost/lien-waiver` record-tracking endpoint.

## v0.1.35 — Test Fit depth (egress · parking · polygon footprint · proforma)
- **Deeper egress / life-safety check (A2)** — `test_fit.egress` now screens the big four IBC fails:
  max travel distance, **occupant load** & required **egress width**, minimum **number of exits**, and
  **exit separation** (½ diagonal / ⅓ sprinklered) — with per-check detail + flags (e.g. an assembly
  hall trips ≥4 exits). Back-compatible with the prior keys.
- **Parking as real IFC geometry** — `generate(..., parking=N)` lays out a surface lot of `N`
  IfcSpace `PARKING` stalls (2.5×5 m + drive aisles) on a dedicated *Site Parking* storey, each with
  area QTOs. Exposed on the generate API + a "Surface parking stalls" field in the proforma form.
- **True polygon-offset footprint** — for `lot_polygon` parcels the buildable footprint is now a real
  inward setback (`offset_polygon`, handles reflex vertices + over-collapse), surfaced as
  `buildable_polygon`, instead of a bounding-box approximation.
- **Optimize tied to the proforma** — the generative sweep's yield-on-cost + new **development
  spread** (bps vs exit cap) come from the canonical `proforma.returns` functions (with stabilized
  occupancy), so the quick screen matches the full underwriting; you can rank by `dev_spread_bps`.

## v0.1.34 — import external IFC families (M3) + visual node editor (M4 complete)
- **Import IFC type content** — bring manufacturer / 3rd-party families into a project from any IFC:
  `families.import_types_from_ifc` copies every IfcTypeProduct (with geometry) in via
  `project.append_asset` (deduped, idempotent), then they're placeable like the built-in catalog.
  New endpoint `POST /projects/{id}/families/import` + *"⇪ Import IFC families…"* in the authoring
  panel. Completes M3.
- **Studio — visual computational graph (M4)** — a new **Studio** workspace renders the Dynamo/
  Hypar-style compute engine as a node editor: drag node types from a palette, wire output→input
  ports (click-to-connect, SVG bezier edges), edit params inline, and **Run** to execute the graph
  server-side in dependency order with values flowing through the wires (zoning → cost → yield, etc.).
  Graph persists locally; shown for developer/architect/engineer personas. Completes M4 — the whole
  **M-theme (M1–M4) is now done**.

## v0.1.33 — material layer sets + family library (M3)
- **Layered construction assemblies** — generated models now carry real **IfcMaterialLayerSet**
  data on walls, slabs and roofs (e.g. exterior wall = brick · cavity · insulation · CMU · gypsum),
  the way Revit's compound structures work — attached via IfcMaterialLayerSetUsage and chosen from
  `IsExternal` / slab type. Feeds take-off, U-value and schedules.
- **Expanded parametric family library** — the placeable catalog grows from 16 to 37 entries across
  new **Lighting**, **MEP** (AHU, fan-coil, diffuser, electrical panel), **Structural** (steel
  column/beam) and **Transport** categories, plus more furniture/sanitary/appliances. Families are
  now **parametric**: pass `dims` to place a distinctly-named, correctly-sized **type variant**
  (Revit-style type families). New element classes get palette colours too.

## v0.1.32 — first-person walkthrough (M2 complete)
- **Walkthrough mode** (🚶 toolbar) — Matterport-style first-person navigation: drops to eye height
  (1.6 m), **W/A/S/D** to walk (locked horizontal so you stay on the floor) and drag to look around.
  Switches to a perspective view on enter and restores your prior camera on exit. Completes M2.

## v0.1.31 — sun & shadow study (M2)
- **Sun / shadow study** (☀ toolbar) — drive the render-mode sun by **date, time-of-day and
  latitude/longitude** with a live panel; shadows track the real solar arc (NOAA solar-position
  math), with warm low-angle light and a below-horizon night state. Opening it auto-enables render
  mode. Pure solar math is unit-tested.

## v0.1.30 — PBR materials + free Revit import
- **PBR pass (M2)** — render mode now upgrades plain lit surfaces to `MeshStandardMaterial`
  (roughness/metalness, keeps the M1 IFC colours) lit by an **IBL studio environment** for soft
  ambient + reflections, on top of the sun/shadows. Reversible; Fragments' own shader meshes are
  left untouched so the engine renderer is never at risk.
- **Free Revit → IFC path** — the Open menu now has *"Free: export IFC from Revit (no bridge)…"*:
  a guide to Revit's built-in IFC export + the free, open-source **pyRevit**, so getting a model in
  doesn't require the paid Autodesk bridge.
- **Docs** — library interoperability evaluation (roadmap §L: IFClite, pyRevit, FreeCAD, Pascal
  Editor) and ADR 0001 on dependency bundling & the signed-update policy (deps are pinned and ship
  inside the app update — never background-updated independently).

## v0.1.29 — render mode (M2 start)
- **Viewer render mode** (◓ toolbar) — a directional **sun with soft (PCF) shadows**, hemisphere
  sky/ground fill + fill light, **ACES tone mapping** and sRGB output, and a shadow-catching ground
  plane. Off by default (flat shading stays the cheap default); re-applies as new models load.
  First step toward Revit/Rhino/Matterport-style rendering.

## v0.1.28 — faster large-model loading
- **Download progress** — large models stream with a live "downloading N% (x/y MB) → preparing
  geometry" label instead of a generic spinner that looked frozen.
- **ETag revalidation** — `model.frag` now serves an ETag + `must-revalidate`: unchanged models
  re-open instantly via **304**, while a republished/edited model is always refetched (fixes a
  stale-cache bug where an immutable 1-year cache served the old geometry forever).

## v0.1.27 — computational graph (M4 start)
- **Dynamo-style node graph** over the pure engines: `GET /compute/nodes` (palette) and
  `POST /compute/graph` run a {nodes, edges} graph in dependency order (zoning → structure / takt /
  cost → yield-on-cost). Zero-touch: function params become input ports, dict returns become outputs.

## v0.1.26 — IFC materials & surface colours (M1 start)
- **Materials & surface styles** — generated/dome models get an IfcMaterial + IfcSurfaceStyle colour
  per element class (concrete, glazing, steel, vegetation…), so models carry real material data.

## v0.1.25 — gamified getting-started
- **Getting-started checklist** — a floating progress pill guides new users through the 6 core
  actions (load a model, generate, test-fit, budget, project, memo) with a progress bar + celebration.

## v0.1.22 — 4D & the vertical assembly line
- **4D construction sequencing** — map model elements onto a takt plan; **scrub the build sequence
  in the viewer** (a slider isolates what's built to date).
- **Takt / line-of-balance chart** (SVG) and an **egress check** (two means + travel distance).

## v0.1.21 — lean & multi-period billing
- **Lean / Last-Planner PPC** — a weekly-plan module + Plan-Percent-Complete analytics with reasons
  for non-completion.
- **Multi-period pay apps** — roll completed-to-date across successive draws; retainage release on
  the final application.

## v0.1.20 — underwriting realism (II)
- **Capital reserves above NOI**, **citable guardrail bands** (sourced from the benchmarks), and
  **Test Fit optimize seeded from the live project** (real land + cost budget).

## v0.1.19 — built-world techniques (Willis · Salvadori · CM/RE research)
- **Takt / line-of-balance** scheduling with a just-in-time delivery plan (R2).
- **Lean PPC** engine (R4) and citable **benchmarks + a comparables module** (R5).

## v0.1.18 — structural-system advisor (R3)
- Pick a plausible system by height/span (flat-plate · shear-core · outrigger) with rough member
  sizing + a load-path read — driving the generated frame (after Salvadori).

## v0.1.17 — form follows finance (R1)
- Generative massing / Test Fit reward **daylight-limited rentable depth** + core efficiency — the
  highest rentable yield wins, not max FAR (after Carol Willis).

## v0.1.16 — underwriting realism (I) + Finance revamp
- **Risk-adjusted** specialty/operating revenue + **guardrails** that flag returns outside market
  bands. Finance reorganized into sub-tabs with a sticky live-returns bar.

## v0.1.15 — pitch deck
- One-click **pitch-deck PDF** variant of the investment memo (B6).

## v0.1.14 — generative optimize + real parcels
- **Generative design** sweeps unit-mix × parking and ranks by yield-on-cost (A5); **real lot
  polygons** drive the program by shoelace area (A6).

## v0.1.13 — Test Fit + property/tax
- **Test Fit** — corridor unit-mix layout, parking solver, scheme compare (A1/A3/A4); **property &
  tax assumptions** feeding OPEX (B3).

## v0.1.11 — specialty assets
- On-site **energy** (solar/wind/battery/rainwater) and **vertical-farm (PFAL)** revenue flow into
  capex / revenue / opex (B4).

## v0.1.10 — developer cost portal
- Line-item **hard/soft cost budgets** (B1), **Sources & Uses** (B2), and a one-click **investment
  memo PDF** (B5).

## v0.1.6–0.1.8 — accounts, AI & hardening
- **SSO** (Google / Microsoft / Procore) + a no-admin free-tier model; first-run **onboarding + tour**.
- **"Ask AI"** project assistant over a live snapshot; AI risk summaries + drafted RFIs.
- **Field capture** (offline photo → punchlist/observation, syncs on reconnect).
- Production hardening — rate limiting, security headers, auth-secret fail-safe, takeoff caching.
- Full generative lifecycle from zoning (frame + units + envelope + core).

## v0.1.0–0.1.5 — foundation
- **BIM viewer** (Three.js + Fragments, offline WASM), federation, clash, IDS, 2D drawings/sheets,
  in-viewer authoring round-trip.
- **GC portal** — config-driven modules (RFIs, submittals, change-order chain, daily, QA, safety…),
  CPM, pay apps, dashboards.
- **Development proforma** — S&U with interest-reserve circularity, XIRR/NPV/EM, JV waterfall,
  sensitivity + Monte Carlo.
- **Generative massing + family library**; free single-project **desktop app** with signed,
  auto-updating releases.