docs(audits): the strictness ledger stops asserting a union flattening the tree no longer does

[claude]

Part of #14977 — this delivers the card's narrow ask only. The card's other half, "a decision by the ledger's owner on how a row records a limitation that was later lifted elsewhere", is deliberately not settled here, so the card stays open for that ruling. See Scope below.

Three clauses in docs/audits/2026-07-unknown-key-strictness-ledger.md asserted, in the present tense, that a strict union branch's prescription is flattened away before it reaches an author. The tree has not done that since 2026-08-05. Each clause is corrected in place and now names packages/spec/src/shared/union-branch-policy.ts as what lifted it.

Exactly three lines change — :676, :737, :940, the three the card names. 3 insertions, 3 deletions; the file is 1870 lines before and after. The os-regen companion .counts.md is untouched.

Green is not the evidence here

pnpm --filter @objectstack/spec check:strictness-ledger grades row structure and the generated counts, not prose, and is green either way. It is reported below for completeness and proves nothing about this diff. The evidence is the reproduction.

What the tree actually does — measured on this branch at 88717a548, @objectstack/spec freshly built

A. defineStack, the state-machine.zod.ts row's OWN door (AgentSchema.lifecycle -> StateNode.entry[] -> ActionRefSchema, a union whose object arm is strict), given entry: [{ type: 'log', parms: { a: 1 } }]:

defineStack validation failed (1 issue):

  ✗ agents.0.lifecycle.states.idle.entry.0: Invalid input
    ✗ agents.0.lifecycle.states.idle.entry.0: Unrecognized key(s) on this action reference: `parms`. Did you mean `parms` → `params`? Until this shape was closed, an undeclared key here was dropped silently ...

The key, the surface and the rename all arrive. The union's cost is one wrapper line, not a lost message.

B. zodIssuesToFields, the wire door #5014 named — same body, prescription delivered as a second entry:

[
  { "field": "agents.0.lifecycle.states.idle.entry.0", "code": "invalid_shape", "message": "Invalid input" },
  { "field": "agents.0.lifecycle.states.idle.entry.0", "code": "unknown_field", "message": "Unrecognized key(s) on this action reference: `parms`. Did you mean `parms` → `params`? ..." }
]

C. what zod itself still raises at the top — so the parenthesis each corrected row KEEPS is still true:

code=invalid_union path=["agents",0,"lifecycle","states","idle","entry",0] message="Invalid input" branches=2

D. the chart.zod.ts row's own site, with no packages/lint anywhere in the path — ChartAggregateSchema.safeParse({ field: 'amount', function: 'sum', groupBy: { field: 'stage', dateGranularty: 'month' } }) rendered by spec's own formatZodError:

chart aggregate (1 issue):

  ✗ groupBy: Invalid input
    ✗ groupBy: Unrecognized key(s) on this chart groupBy: `dateGranularty`. Did you mean `dateGranularty` → `dateGranularity`? ...

Mechanism: formatZodIssue (packages/spec/src/shared/error-map.zod.ts:254) descends invalid_union and ranks the branches through selectUnionBranches; zodIssuesToFields (packages/spec/src/api/zod-issues-to-fields.ts:213) calls the same function. Since #8318 there is one implementation of that policy, packages/spec/src/shared/union-branch-policy.ts. packages/spec/src/automation/state-machine.zod.ts:90-93 already records the lift in its own JSDoc — the ledger row is the copy that was never updated.

The probe was a scratch file, run and deleted; it is not committed and nothing in this diff is a test.

Provenance — why the three clauses are NOT corrected the same way

git log -S on each clause, against the dates the three flatteners landed:

clause	written	true when written?
:737 state-machine.zod.ts — "which formatZodError then flattens away"	2026-08-04, 5278e11f1 (批 10)	yes — expired the next day
:940 view.zod.ts — "the #5014 flattening, so the key that caused it is not in the message the author sees"	2026-08-04, 8064b079f (#5114 hotfix)	yes — expired the next day
:676 chart.zod.ts — "reaches an author only through packages/lint/src/zod-issue-format.ts's arm unpacking"	2026-08-08, e0f300ba5 (#5583)	NO — already false the day it was written

The three flatteners the campaign filed: #4971 formatZodError at 546ab3c49, 2026-08-05 · #5014 the wire mapper at 2d2530300, 2026-08-05 · #5341 the CLI at 3d94141ec, 2026-08-04. git merge-base --is-ancestor 546ab3c49 e0f300ba5 exits 0, so spec's own renderer was already unpacking in the tree of the commit that wrote the chart clause.

That asymmetry decides the edit shape:

• :737 and :940 are re-tensed into the batch they belong to and given the file's own ✅ ... LIFTED note, naming union-branch-policy.ts.
• :676 cannot be rescued that way. Re-tensing it to "at the time, X" would write a NEW false sentence, and the row's own "the cell below is kept as WRITTEN AT THE TIME" rule does not license that. So its only is struck, and the generalisation it grounded — "a general constraint on every remaining union site in this campaign" — is withdrawn, with a pointer to the dispatch cycle that generalisation cost (stack.devPlugins[] hides ManifestSchema's named unknown-key refusal under invalid_union — an author sees a keyless "Invalid input" at that one door #14722).

Scope — what was deliberately NOT touched

The convention question is not settled, and did not have to be. The file already demonstrates its own idiom for a verdict that later expired, in two places outside this diff: the chart.zod.ts row's "✅ That fix landed at #5020, and this row's no gate verdict is spent", and the api/ row's "the flat wire verdict this row used to carry was correct when written and then silently expired, which is the finding". This diff applies that existing idiom per clause. It adds no rule to the Format contract section and rewrites no row.

Not touched, on purpose:

• the dashboard.zod.ts row (:673), whose compareTo union caveat is already framed as "批 14 recorded that ..." and already carries its own RESOLVED note — correct as written;
• every other row's batch-tense prose;
• docs/audits/2026-07-unknown-key-strictness-ledger.counts.md (os-regen generated);
• packages/spec/src/data/analytics.zod.ts and runtime/src/domains/analytics.ts (fenced for PR feat(spec)!: close timeDimensions[].dateRange's string arm to the date-range preset vocabulary (#16041) #16618 / card driver-memory analytics silently accepts an unparseable dateRange and matches EVERY row — and the platform's own documented spelling 'Last 7 days' is one of them #16041).

Gates

Derived, not guessed: node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack on the merged tree, then reconciled with --ran.

✓ dispatch-gates --ran: 17 derived famil(ies) accounted for — 17 run, 0 NOT-MEASURED.
Run reconciliation — 17 derived, 17 run, 0 NOT-MEASURED, 0 UNRUN.

All 17 exit 0. Two verdict lines worth quoting (each printed by the gate itself, not read from $?):

✓ strictness ledger: 60 file(s) across 5 triaged director(ies) — every row names a live sited file, no undeclared schema files.
✓ docs/audits/2026-07-unknown-key-strictness-ledger.counts.md is current — 444 site(s) measured, 1 authorable strip site(s) left.
check-nul-bytes: OK (scanned 8275 text file(s) -- 8275 tracked, 0 untracked-not-ignored; skipped 7 binary; no raw ASCII control bytes).

One gate first returned exit 3 — check:doc-formula-expressions, PREREQUISITE NOT MET, its own words for "nothing was measured". @objectstack/formula and @objectstack/lint were built as the gate instructed and it was re-run: exit 0. It is recorded as measured only for that second run.

The first derivation ran on a stale tree and said so; origin/main was fetched and merged (88717a548) and the derivation re-taken, which cleared the warning.

No changeset

skip-changeset. Nothing published moves: docs/audits/** appears in no package's files[] (checked across all 70 packages that declare one — zero mention docs or ..), and the root package is private: true. The changed file is a repo-internal audit document.

验收备注

A fourth site carries the same stale claim and is NOT corrected here. docs/audits/2026-07-unknown-key-strictness-ledger.md:973-978, in the ui/ batch narrative:

(a) The zod-4 union collapse is now load-bearing on this file. ... What carries the named surface and the rename to the author is packages/lint/src/zod-issue-format.ts's arm unpacking, which #5020 had already built; a strict object arm inside a union is only as loud as its consumer's unpacking, and that is a general fact about this campaign's remaining union sites, not a chart detail.

It is the same claim as :676, from the same commit (e0f300ba5, 2026-08-08), and therefore also false the day it was written. It is left alone because it is framed as "Two things #5583 recorded that a later batch will need" — a record of what its own batch recorded, which is exactly the shape this PR was told not to touch — and because the card and the dispatch both name three sentences, not four. Flagged rather than fixed: the ledger owner should decide it in the same pass as the convention question, since after this PR the file carries a corrected chart row and an uncorrected restatement of it 300 lines below. Noted, not filed — a stale prose sentence is not a reproducible defect, a declared-contract violation, or a metadata-authoring trap.

The ledger never names #4971. The state-machine.zod.ts row said "filed, not fixed here" with no number, which is part of why the filing was hard to follow to its fix. The corrected clause now names it.

---

Generated by Claude Code