Skip to content

Commit f2101d0

Browse files
fix(scripts): tenant-audit census stores declared type text as written, and resolves names by scope (#19650)
Fixes #19300 Two defects in one file's TypeScript reading, with two independent fixes. Route ① for the first, as triage on the predecessor card named it; scope-keyed name resolution for the second. ## Defect 1 — the census collapsed declared type text before re-parsing it `declaredTypesIn` stored a declared type through `getText(sf).replace(/\s+/g, ' ')`. The door rule is later read off that text by re-parsing it as a synthetic alias (`type CensusReceiver = THE_STORED_TEXT;`). A type literal may separate its members by a NEWLINE alone — legal TypeScript — and the collapse turns that separator into nothing, so the synthesis does not parse and the site is refused as `type-text-not-round-trippable`. The author was told to restyle legal TypeScript to work around the tool's own re-serialisation. The text is now stored exactly as the source spells it. The collapse was never needed at the storage boundary: every reader of that text either scans it for identifiers or re-parses it, and the one place a single line is genuinely required — the artefacts — already collapses at the point of render (`runCensus`, `cell()`). **The real site set is TWO, not the three the card names.** Measured on this branch: | site | in the set? | why | | :--- | :--- | :--- | | `note()`'s `type` field | **yes** | feeds `readTypeTextDoor` through `fromEntry` | | the `shapes` member type | **yes** | feeds it through `memberTypeOfShapes` | | `receiverKey` | no | a receiver's own spelling, for ledger keys and diagnostics; never re-parsed | | `note()`'s `init` field | no | a diagnostic, truncated to 120 chars; scanned by regex, never re-parsed | | the `as` path's `r.type.getText(sf)` | no | never collapsed in the first place — it is the lit control that already proved raw text round-trips | | the spread / opaque / runtime-name sites | no | diagnostics and object names, never type texts | | `:355` in `memberIsEngineDoor` | no | `replace(/\s+/g, '')` — an **empty** replacement, and its only consumer is `t !== 'string'`. It normalises for an equality test and is never handed to a parser. | ## Defect 2 — `locals` was keyed by bare identifier, with no scope A file may contain several `engine`s. Keyed on the identifier alone they were one entry, and the first TYPED one decided for all of them. That is **three** failures, not one, and which one you get depends on declaration order: | shape | before | after | | :--- | :--- | :--- | | engine-typed `engine` declared first, `Map` second | `Map.delete` scored an **engine write** and admitted to the certified population | the Map is subtracted | | `Map` first, engine-typed second | the **real engine write** subtracted as `platform-type` — a DEFENDED arm, so it prints nothing and is counted nowhere | the engine write is placed | | both engine-typed, one unreadable | both refused (the card's measured instance) | both placed | The middle row is the expensive one and the card does not name it: the census's own header calls a silent subtraction the direction it cannot survive being wrong in, and the bare-name map was producing them. The conflation also decided two other verdicts the artefacts carry — **which object** a site writes (`resolveObjectNameArg`) and **whether it is elevated** (`elevationOf`). Both are pinned now. `declaredTypesIn` resolves a name through its innermost enclosing scope, with the old file-wide map kept as an explicit floor tier: consulted only when no enclosing scope declares the name, so **no receiver that resolved before stops resolving**. ## What this moves on the real corpus The population is unchanged — **227 sites before, 227 after, none added, none removed**. Fourteen sites change attribution, and one receiver becomes honestly unreadable: - 6 sites stop needing an `UNTYPED_RECEIVERS` row (the census can now read their declared type), so three ledger rows are deleted as stale. - 2 sites in `bootstrap-declared-webhooks.ts` resolve their object name to `sys_webhook` for the first time — `undecidable` becomes `enabled`. - 6 sites in `metadata-store.ts` move from `declared-type` to the object-name rescue. Their receiver is a **contextually typed** arrow parameter (`(engine) => engine.insert(…)` against a declared `run: (engine: IDataEngine) => …`), which needs a type checker this module does not have. The bare-name map had been answering it from an unrelated declaration and happened to be right; the verdict is unchanged either way. - 1 receiver — `const db = context.database` in `auth-manager.ts` — was being answered by a a `Record` keyed by string declared 2000 lines away and silently subtracted as `platform-type`. It is the better-auth adapter bound to the SCIM transaction, and it arrives in `UNTYPED_RECEIVERS` saying so. ## ✅ Closed: the artefacts are regenerated in this PR This PR's originally declared file surface was `scripts/tenant-audit-census.mjs` plus its self-test and fixtures, and the defect-2 repair moves the census totals, which stales the committed artefacts. The dev **stopped at that fence and declared the red** rather than widening silently. The seat then **widened the fence** — the artefacts ride the source PR rather than a follow-up card, per the lane rule 「其重生成的 references 产物归源 PR」. Both steps are done: 1. `node scripts/tenant-audit-census.mjs --write` regenerated `content/docs/permissions/tenant-audit-census.mdx` and `docs/audits/2026-08-tenant-audit-write-call-sites.counts.md`. 2. The hand-written prose numbers `--write` does not touch were taken **from the gate's own output**, not retyped from any summary: `const` 41→43, unreadable-and-tenancy-enabled 32→34 (twice), statically decidable 151→153, undecidable 76→74. `check-tenant-audit-census.mjs` and its `--self-test` are now **green (27/27, up from 6 failing)**, which also confirms the diagnosis: all six failures were the drift. **Defect 1 is artefact-neutral and was measured as such**: with only the two storage-site lines changed, the census `--json` is byte-identical to the base tree (`diff` exit 0 over the full document). Every count that moves comes from defect 2. ## Verification All **66** gates `scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands` derives for the widened diff were run and reconciled with `--ran` on the final head: **66 derived / 66 run / 0 NOT MEASURED / 0 UNRUN, every family carrying a recorded exit code, all zero.** The set grew from 29 because the diff now reaches `content/docs/**`, `docs/audits/**` and `ts-parse.mjs`. ⚠️ Five families first returned PREREQUISITE NOT MET (three needing `@objectstack/lint` built, one `packages/spec/json-schema`, one `@objectstack/client-react` declarations). They were recorded as **NOT MEASURED, never as clean**, and re-measured to exit 0 after two builds through `scripts/pm/os-verify-lock.sh`. Reverse verification — three ablations through `scripts/ablation-replace.mjs`, each run from the committed state with the on-disk mutation proven and the restore verified `blob == HEAD` with `git diff HEAD` empty: | ablation | red | | :--- | :--- | | re-collapse `note()`'s `type` | 3 of 67 — the inline, parameter-annotation and non-door newline cases | | re-collapse the `shapes` member type | 1 of 67 — the interface-member case only, proving the two storage sites are independently reached | | drop the lexical tier, leave only the floor | 4 of 67 — both declaration orders, the object name and the elevation | The self-test grows 57 to 67 cases. The `type-text-not-round-trippable` arm is **kept and still exercised**: a genuinely unparseable text is still refused and still places nothing. What changed is what it means — it is now the alarm for a defect in this module's own re-serialisation, never an instruction to restyle the corpus, and the refusal text says so. ## Acceptance notes - ✅ **`scripts/check-tenant-audit-census.mjs`'s refusal prescription** ("spell the literal's members with `;` separators so the stored text round-trips") was made false by this change and is the copy CI prints. **Fixed in this PR** — text only. It no longer asks the author to restyle anything; it says the fault is the census's own and to file it there. - ✅ **`scripts/ts-parse.mjs`'s header** documented the collapse as a live defect. **Fixed in this PR** — text only, now historical. ⛔ It deliberately does NOT retire the door it documents: the measurement is a fact about the PARSER, which has not changed, and any caller re-parsing text it synthesised itself can fail the same way. - **The same conflation survives one map over**, and it is reproducible today. Two classes in one file sharing a property name: `class B`'s `this.engine.delete('k')` on a a `Map` of string to number scores `engine/IProbeEngine` — a `Map` admitted to the certified tenancy population. `fnReturns` behaves the same way for two same-named local functions. `thisProps` needs CLASS scope rather than lexical scope, which is a different notion from the one this PR adds, so it is reported rather than folded in. **Filed by the seat as #19652.** - **Contextually typed parameters are unreadable to this census**, before and after — see the `metadata-store.ts` note above. A capability gap, not a regression; recorded so the 6 sites' move to the object-name rescue is not read as one. - **This change makes #19299 acutely live.** That card is the census self-test's clean-census control being coupled to the live tree through `refuse`. The coupling was latent while the tree was clean; with the artefacts drifted, **6 of the gate's 27 self-test cases now fail, and 5 of them are controls** asserting that a stale number is NOT a finding. They fail for the reason they exist to deny. ⛔ Not folded in — it is a different defect and deliberately serialised behind this card. --- _Generated by [Claude Code](https://claude.ai/code)_ --------- Co-authored-by: Claude <noreply@anthropic.com>
1 parent 79854f7 commit f2101d0

5 files changed

Lines changed: 357 additions & 122 deletions

File tree

‎content/docs/permissions/tenant-audit-census.mdx‎

Lines changed: 17 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -187,8 +187,8 @@ reproduce them. Where it disagrees, it disagrees on the page:
187187
| carried figure | where it survives | this census |
188188
| :--- | :--- | ---: |
189189
| 175 write call sites | quoted in the merged changeset | **227** |
190-
| 24 carrying no tenant context | quoted in the merged changeset | **9** provable and tenancy-enabled; **32** more whose options argument is unreadable |
191-
| 127 of 175 statically decidable, 48 runtime-parameter-name sites | restated on the `isSystem`-scoping card | **151 of 227** decidable, **76** undecidable |
190+
| 24 carrying no tenant context | quoted in the merged changeset | **9** provable and tenancy-enabled; **34** more whose options argument is unreadable |
191+
| 127 of 175 statically decidable, 48 runtime-parameter-name sites | restated on the `isSystem`-scoping card | **153 of 227** decidable, **74** undecidable |
192192
| 135 (77%) silenced by the `isSystem` guard before the posture gate | the lost issue body — **no surviving corroboration** | **not reproduced**: 108 decidably elevated, 0 decidably not, 102 undecidable |
193193
| 141 and 132, two independent re-derivations | the card that filed this work | — |
194194

@@ -200,7 +200,7 @@ at any commit.
200200

201201
Two structural facts do plausibly widen this reading against any hand or regex
202202
one, and both are counted in the generated tables below: the 44 sites reached
203-
through an erased (`any`) receiver, and the 41 that name their object through a
203+
through an erased (`any`) receiver, and the 43 that name their object through a
204204
`const` rather than inline. An instrument that read either the way a person does
205205
would report a smaller number and would not say so.
206206

@@ -213,7 +213,7 @@ answer is that a static reading cannot settle it.
213213
⇒ **Cite `9 / 227`, and say what it is**: the sites whose options argument was
214214
READ and holds no tenant context, against a decidably tenancy-enabled object.
215215
That is the control's provable yield surface. ⛔ Do not cite it as "the sites
216-
without tenant context" — **32 further sites** have an options argument this
216+
without tenant context" — **34 further sites** have an options argument this
217217
cannot read, and they are neither in nor out.
218218

219219
{/* BEGIN GENERATED: tenant-audit-census (scripts/tenant-audit-census.mjs) — DO NOT EDIT */}
@@ -223,29 +223,29 @@ cannot read, and they are neither in nor out.
223223
| what | count |
224224
| :--- | ---: |
225225
| write call sites on the application surface | **227** |
226-
| …whose object name is statically decidable | 151 |
227-
| …whose object name is chosen at run time | 76 |
228-
| …against an object with tenancy ENABLED | 150 |
226+
| …whose object name is statically decidable | 153 |
227+
| …whose object name is chosen at run time | 74 |
228+
| …against an object with tenancy ENABLED | 152 |
229229
| …against an object that declares tenancy off | 1 |
230230
| threading a tenant context | 143 |
231231
| PROVABLY carrying none (options read, no context key) | **17** |
232232
| …of those, against a decidably tenancy-enabled object | **9** |
233233
| options argument UNREADABLE — may or may not carry one | 67 |
234-
| …of those, against a decidably tenancy-enabled object | 32 |
234+
| …of those, against a decidably tenancy-enabled object | 34 |
235235
| threading a decidably ELEVATED (`isSystem`) context | 108 |
236236
| threading a context that is decidably NOT elevated | 0 |
237237
| threading a context whose elevation is a run-time fact | 102 |
238238

239239
| how the instrument reached the site | count |
240240
| :--- | ---: |
241241
| receiver carried a readable engine type | 183 |
242-
| receiver erased, placed by the object NAME | 18 |
242+
| receiver erased, placed by the object NAME | 24 |
243243
| receiver erased, placed by an `object: string` PARAMETER | 15 |
244-
| receiver erased, placed by an `UNTYPED_RECEIVERS` row | 11 |
244+
| receiver erased, placed by an `UNTYPED_RECEIVERS` row | 5 |
245245

246246
| object name spelled inline | 110 |
247-
| object name spelled through a `const` | 41 |
248-
| object name is an `object: string` parameter | 19 |
247+
| object name spelled through a `const` | 43 |
248+
| object name is an `object: string` parameter | 17 |
249249
| object name is some other run-time expression | 57 |
250250

251251
### Subtractions the census could NOT defend — enforced
@@ -262,10 +262,10 @@ or dependency-owned declaration is one this census never saw, and «never saw it
262262
must not be spelled the same way as «read it, not an engine».
263263

264264
⚠️ One arm here says something else again: `type-text-not-round-trippable` is a
265-
receiver whose declared type the census STORED whitespace-collapsed and could
266-
not read back — the source parsed, the re-serialisation of it did not, so the
267-
door rule could never be read off it. That is a fault in this tool rather than
268-
a fact about the corpus, and it is the one row here that also fails the gate.
265+
receiver whose declared type THIS TOOL derived and then could not read back —
266+
the source parsed, the re-serialisation of it did not, so the door rule could
267+
never be read off it. That is a fault in this tool rather than a fact about the
268+
corpus, and it is the one row here that also fails the gate.
269269

270270
| what | count |
271271
| :--- | ---: |
@@ -296,7 +296,7 @@ holds still. They are required to be HERE and to say WHEN they were true;
296296
their values are not compared. The reasoning, and the measurement behind it,
297297
are in `scripts/check-tenant-audit-census.mjs`.
298298

299-
Measured on 2026-09-20 at `215840f43`.
299+
Measured on 2026-09-22 at `9db2c6234`.
300300

301301
| corpus scale (not enforced) | count |
302302
| :--- | ---: |

‎docs/audits/2026-08-tenant-audit-write-call-sites.counts.md‎

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -34,15 +34,15 @@ silent, and `node scripts/tenant-audit-census.mjs --write` is the resolution.
3434
| Measure | Value |
3535
|---|---:|
3636
| Write call sites | 227 |
37-
| Object name statically decidable | 151 |
38-
| Object name chosen at run time | 76 |
39-
| Against a tenancy-enabled object | 150 |
37+
| Object name statically decidable | 153 |
38+
| Object name chosen at run time | 74 |
39+
| Against a tenancy-enabled object | 152 |
4040
| Against an object declaring tenancy off | 1 |
4141
| Threading a tenant context | 143 |
4242
| Provably carrying none | 17 |
4343
| …and decidably tenancy-enabled | 9 |
4444
| Options argument unreadable | 67 |
45-
| …and decidably tenancy-enabled | 32 |
45+
| …and decidably tenancy-enabled | 34 |
4646
| Threading a decidably elevated context | 108 |
4747
| Threading a decidably non-elevated context | 0 |
4848
| Threading a context of undecidable elevation | 102 |
@@ -61,10 +61,10 @@ or dependency-owned declaration is one this census never saw, and «never saw it
6161
must not be spelled the same way as «read it, not an engine».
6262

6363
⚠️ One arm here says something else again: `type-text-not-round-trippable` is a
64-
receiver whose declared type the census STORED whitespace-collapsed and could
65-
not read back — the source parsed, the re-serialisation of it did not, so the
66-
door rule could never be read off it. That is a fault in this tool rather than
67-
a fact about the corpus, and it is the one row here that also fails the gate.
64+
receiver whose declared type THIS TOOL derived and then could not read back —
65+
the source parsed, the re-serialisation of it did not, so the door rule could
66+
never be read off it. That is a fault in this tool rather than a fact about the
67+
corpus, and it is the one row here that also fails the gate.
6868

6969
| what | count |
7070
| :--- | ---: |
@@ -90,7 +90,7 @@ holds still. They are required to be HERE and to say WHEN they were true;
9090
their values are not compared. The reasoning, and the measurement behind it,
9191
are in `scripts/check-tenant-audit-census.mjs`.
9292

93-
Measured on 2026-09-20 at `215840f43`.
93+
Measured on 2026-09-22 at `9db2c6234`.
9494

9595
| corpus scale (not enforced) | count |
9696
| :--- | ---: |
@@ -195,8 +195,8 @@ Measured on 2026-09-20 at `215840f43`.
195195
| `packages/plugins/plugin-sharing/src/sharing-service.ts` | `delete` | `sys_record_share` | enabled | elevated | 2 |
196196
| `packages/plugins/plugin-sharing/src/sharing-service.ts` | `insert` | `sys_record_share` | enabled | elevated | 1 |
197197
| `packages/plugins/plugin-sharing/src/sharing-service.ts` | `update` | `sys_record_share` | enabled | elevated | 1 |
198-
| `packages/plugins/plugin-webhooks/src/bootstrap-declared-webhooks.ts` | `insert` | `subscriptionsObject` | undecidable | options unreadable | 1 |
199-
| `packages/plugins/plugin-webhooks/src/bootstrap-declared-webhooks.ts` | `update` | `subscriptionsObject` | undecidable | options unreadable | 1 |
198+
| `packages/plugins/plugin-webhooks/src/bootstrap-declared-webhooks.ts` | `insert` | `sys_webhook` | enabled | options unreadable | 1 |
199+
| `packages/plugins/plugin-webhooks/src/bootstrap-declared-webhooks.ts` | `update` | `sys_webhook` | enabled | options unreadable | 1 |
200200
| `packages/plugins/plugin-webhooks/src/migrate-webhook-secrets.ts` | `update` | `subscriptionsObject` | undecidable | options unreadable | 1 |
201201
| `packages/services/service-automation/src/builtin/crud-nodes.ts` | `delete` | `objectName` | undecidable | context, elevation undecidable | 1 |
202202
| `packages/services/service-automation/src/builtin/crud-nodes.ts` | `insert` | `objectName` | undecidable | context, elevation undecidable | 1 |

‎scripts/check-tenant-audit-census.mjs‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -642,13 +642,13 @@ export function censusRefusals(census) {
642642
}
643643
for (const u of notRoundTrippableSites(census)) {
644644
problems.push(
645-
`[type-text-not-round-trippable] ${u.file}:${u.line} \`${u.receiver}\`.${u.verb}() -- the census `
646-
+ `stored this receiver's declared type whitespace-collapsed and cannot re-parse it as a type `
647-
+ `alias, so the door rule could not be read off it and the census cannot say whether this site `
648-
+ `is an engine write at all: \`${u.type}\`. The SOURCE parsed -- what did not is the census's own `
649-
+ 're-serialisation of a fragment of it, so this is a fault in the tool and not a fact about the '
650-
+ 'corpus. Give the receiver a NAMED type the engine type index can be keyed on, or spell the '
651-
+ "literal's members with `;` separators so the stored text round-trips.",
645+
`[type-text-not-round-trippable] ${u.file}:${u.line} \`${u.receiver}\`.${u.verb}() -- this tool `
646+
+ `cannot re-parse the declared type it derived for this receiver, so the door rule could not be `
647+
+ `read off it and the census cannot say whether this site is an engine write at all: `
648+
+ `\`${u.type}\`. The SOURCE parsed -- what did not is the census's own re-serialisation of a `
649+
+ 'fragment of it, so this is a fault in the tool and not a fact about the corpus. ⛔ Nothing is '
650+
+ 'wrong with the code at this site and nothing here asks you to restyle it: file this against '
651+
+ 'the census, with the located parse verdict the generator prints under the site.',
652652
);
653653
}
654654
for (const r of census.staleLedgerRows ?? []) {

0 commit comments

Comments
 (0)