Re-derive the tenant-audit write-call-site census as an in-tree artifact (page + generator + drift gate)

.claude/workflows/docs-accuracy-audit.js

@@ -166,6 +166,7 @@ const ALL_HANDWRITTEN = [
  "content/docs/permissions/sharing-rules.mdx",
  "content/docs/permissions/sso.mdx",
  "content/docs/permissions/system-context.mdx",
+ "content/docs/permissions/tenant-audit-census.mdx",
  "content/docs/plugins/adding-a-metadata-type.mdx",
  "content/docs/plugins/anatomy.mdx",
  "content/docs/plugins/development.mdx",

.github/workflows/lint.yml

@@ -1381,6 +1381,58 @@ jobs:
  node scripts/check-system-context-census.mjs --self-test
  node scripts/check-system-context-census.mjs
 
+ # #13548 tenant-audit census. `content/docs/permissions/tenant-audit-census.mdx`
+ # carries the population `SqlDriver.auditMissingTenant` acts on: every
+ # application-surface write call site against a tenancy-enabled object, and
+ # what execution context each one threads.
+ #
+ # ⭐ The reason it is an in-tree artefact at all is the failure it replaces.
+ # That census used to live in a COMMENT on an issue; the issue became
+ # unreachable (404 on three independent channels while its neighbours
+ # answer 200) and took the list with it, while three open cards still named
+ # it as their input and nothing noticed. What survived did so because a
+ # changeset author had happened to quote two of the figures in prose. A
+ # measurement that decides a repair family's severity and a ruling's scope
+ # is not a comment.
+ #
+ # ⚠️ It is a DRIFT gate, deliberately NOT an anchor gate like its `isSystem`
+ # sibling above. The generated region aggregates by (file, verb, object,
+ # tenancy, context posture) and carries no line numbers, so a pure
+ # displacement — an import inserted above a site — cannot move it. That
+ # skips the sibling's whole open defect class: anchors that rot on
+ # displacement, and a repair arm that then misreads displacement as a
+ # population change and asserts it on a security-relevant surface. There is
+ # exactly one repair path here (`node scripts/tenant-audit-census.mjs
+ # --write`), it is mechanical, and it has no case where it must guess.
+ #
+ # It lives in THIS job, next to its sibling, for the same reason that one
+ # does: the job has no paths filter, so the census runs on code-only PRs —
+ # the ones that ADD a write call site. The `--self-test` invocation is what
+ # `check:self-test-wired` requires, and it is the only instrument on this
+ # gate's matching rules; a clean tree cannot tell a working rule from a
+ # weakened one.
+ #
+ # ⭐ THREE commands, not two. The GENERATOR carries a self-test of its own
+ # because its classifiers are published FIGURES rather than findings: the
+ # gate's verdict is "no unplaceable receiver", and the elevation and
+ # tenant-context verdicts are not part of it. Nothing else reads them, so a
+ # clean tree cannot tell a working classifier from a weakened one. Both of
+ # the shapes it pins were measured WRONG on the first edition — a spread
+ # read as a denial of the flag it might carry, and an unreadable options
+ # argument folded into "carries no tenant context" — and six of its
+ # eighteen cases red against that reading.
+ #
+ # Invoked as `node` rather than through a `pnpm check:*` alias: see the
+ # GATE INVOCATION IDIOM note at the top of this file. AST walk over every
+ # tracked non-test source under the two roots plus the object registry, no
+ # spawns; ~8s. ⛔ The source COUNT is deliberately not quoted here: it is
+ # corpus scale, it moves on any file added under those roots, and a comment
+ # nothing checks is exactly where a stale number hides.
+ - name: Tenant-audit census matches the tree
+ run: |
+ node scripts/check-tenant-audit-census.mjs --self-test
+ node scripts/check-tenant-audit-census.mjs
+
  # #12236 one <h1> per doc page. `DocsTitle` renders the frontmatter `title`
  # as the page's <h1> unconditionally (apps/docs/app/[lang]/docs/[[...slug]]/
  # page.tsx), so a body-level `# ` heading compiles to a SECOND one inside

content/docs/permissions/index.mdx

@@ -67,6 +67,7 @@ alike — is [Declaring Capabilities](/docs/permissions/capabilities).
 - [Social & Enterprise SSO](/docs/permissions/sso)
 - [Authorization Architecture](/docs/permissions/authorization)
 - [System Context (`isSystem`)](/docs/permissions/system-context) — what the platform's one elevation flag short-circuits, and what it deliberately does not
+- [Tenant-Audit Census](/docs/permissions/tenant-audit-census) — every application-surface write call site against a tenancy-enabled object, re-derived from the tree rather than quoted
 - [Profiles (removed)](/docs/permissions/profiles)
 - [Permission Sets](/docs/permissions/permission-sets)
 - [Positions](/docs/permissions/positions)

content/docs/permissions/meta.json

@@ -7,6 +7,7 @@
  "sso",
  "authorization",
  "system-context",
+ "tenant-audit-census",
  "profiles",
  "permission-sets",
  "positions",

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

@@ -0,0 +1,236 @@
+---
+title: Tenant-Audit Census
+description: The authoritative enumeration of every application-surface write call site against a tenancy-enabled object — how many thread an execution context, how many thread none, and how much of the population a static instrument can decide at all. Built by census over the whole repo, not by recall.
+---
+
+`SqlDriver.auditMissingTenant()` is the platform's one *diagnostic* on write-side
+tenancy. It warns when a write lands on a tenancy-enabled object without
+`options.tenantId` — the shape of a seed, migration or background path that
+forgot to thread the acting session.
+
+This page is **the authority** for the population that control acts on: every
+write call site on the application surface, what object it targets, and what
+execution context it threads. The figures below are generated, not written —
+rebuilt from the tree by `scripts/tenant-audit-census.mjs`, and
+`scripts/check-tenant-audit-census.mjs` fails the build when what is committed
+and what the tree says disagree.
+
+The per-site rows live next door, in
+`docs/audits/2026-08-tenant-audit-write-call-sites.counts.md`, and are written by
+the same command. The split is the one `packages/spec`'s strictness ledger
+already uses and is there for the same reason: this page has prose worth
+preserving and the row table has none, so the table is regenerated whole while
+the page keeps a small generated region for the figures its prose reasons about.
+
+## ⚠️ Why this page exists at all
+
+The measurement this page carries used to live in **a comment on an issue**. That
+issue became unreachable — it returns 404 on unauthenticated REST, on the rendered
+web page and on authenticated API access alike, while its immediate neighbours
+answer 200 — and it took the census with it. Three open cards named that comment
+as their input, and nothing anywhere noticed that their input had gone.
+
+What survived did so by luck. A changeset author had happened to quote two of the
+figures in prose, so "175 write call sites, 24 of them carrying no tenant context"
+is still readable on `main` in
+`.changeset/tenant-audit-update-delete-half-repairs.md` — while the list of 24
+that a downstream card was briefed to classify is not recoverable at all.
+
+⇒ A census that decides a repair family's severity and a ruling's scope is not a
+comment. It is a re-runnable instrument plus a committed page. Losing any issue
+now costs nothing, and the population is **re-derivable** rather than quoted.
+
+## What the control does, and what a call site controls
+
+`auditMissingTenant(object, op, options)` is gated in this order:
+
+1. `OS_TENANT_AUDIT=0` — off entirely;
+2. `options.bypassTenantAudit` — the engine sets this for **every**
+ `ExecutionContext.isSystem` write (ObjectQL's `buildDriverOptions`);
+3. a present `options.tenantId` — the engine fills it from `execCtx.tenantId`;
+4. the deployment posture — the warning is only meaningful on a walled install;
+5. the object having a tenant field.
+
+Both of the guards a *caller* can move are downstream of one decision at the call
+site: **whether it threads an execution context at all**. Thread an elevated one
+and guard 2 silences the warning; thread a tenant-bearing one and guard 3 does;
+thread none and the site is what this census counts.
+
+## How the population is decided
+
+A site is a call to one of the three `IDataEngine` write doors — `insert`,
+`update`, `delete` — on a receiver whose declared type is an engine, in tracked
+non-test sources under `packages/services/` and `packages/plugins/`.
+
+**The verb name is not the signal.** `.delete()` alone answers some 250 call sites
+in this corpus, and most of them are `Map.delete`, `Set.delete`, `Headers.delete`,
+a crypto `Hash.update`, a blob-storage delete-by-key and a search-index de-index.
+So the receiver is typed structurally: a declared interface or type literal counts
+as an engine when it declares a write door whose first parameter is named
+`object` / `objectName` / `objectApiName` / `name` and typed `string` — the
+`IDataEngine` door signature. Interfaces that extend one inherit it; aliases that
+narrow one (`Partial<Pick<IDataEngine, …>>`) carry it.
+
+**The expensive failure direction is a keyword.** Sites whose receiver the author
+typed `any` have no type to read, and there are 45 of them — better than a fifth
+of the population, concentrated in exactly the seed and bootstrap paths this
+control exists for. Scoring an unreadable receiver as "not an engine" would have
+dropped every one of them silently, with a clean exit and a smaller number that
+reads exactly like a smaller truth. So `any` is not a classification here: it goes
+to the unreadable pile, and the unreadable pile is placed by facts about the tree
+(the argument names a declared object; the argument is a parameter declared
+`object: string`) or by a written `UNTYPED_RECEIVERS` row. **An unreadable
+receiver that none of the three place is an error, never a default.**
+
+Tenancy itself is enabled *by default* — `isTenancyDisabled()` reads
+`tenancy.enabled === false` and nothing else — so the object registry only has to
+find the opt-outs. Across 297 declared objects — the dated, ⛔ unenforced
+corpus-scale figure below — exactly two opt out (`sys_api_key`,
+`sys_sso_provider`), and no write call site on this surface targets either.
+
+## ⛔ What this instrument cannot decide
+
+A site whose object name is an inline literal or a local `const` is statically
+decidable. A site whose name is a parameter or a field — `ql.insert(object, …)`
+inside a shared seed helper, `this.objectName` on a per-object service — is not,
+and no amount of AST work makes it so: the object is chosen at run time. Those
+are reported as `undecidable` rather than assumed either way.
+
+The same holds twice over for the context. An options argument spelled as a
+literal can be read; one spelled `options`, `{ ...opts }`, or handed through a
+forwarding shim cannot, and **67 of the 215 sites are spelled that way**. A
+context resolved from an inline literal or a local `const` can be tested for
+`isSystem`; one arriving from a helper call cannot.
+
+⇒ **A third of this population is undecidable in one dimension or another, and
+that is reported rather than smoothed over.** A census that quietly guessed on
+those sites would publish a number in the one direction this page cannot survive
+— claiming completeness while short — and a gate seeded from it would then hold
+the page to it.
+
+## ⚠️ Two over-claims this instrument made, and what they cost
+
+Both were found by the drift gate firing on this page's own artifact, and both
+are recorded here rather than quietly corrected, because the numbers they moved
+were published first.
+
+**The elevation classifier read a spread as a denial.** It walked an object
+literal's named properties looking for `isSystem` and returned "not elevated"
+when the loop ended — so `{ ...SYSTEM_CTX }` was scored **decidably NOT
+elevated** while every `SYSTEM_CTX` in the tree is `{ isSystem: true, … }`. It
+also never unwrapped `as const`, so a bare `context: SYSTEM_CTX` read as
+undecidable. Fixing both moved **51 sites' verdicts**: 45 from undecidable to
+elevated, and 6 from *decidably not elevated* to *elevated* — an inversion, on a
+security-relevant classification. The count of decidably-not-elevated sites is
+now **0**: nothing on this surface threads a context that provably lacks the flag.
+
+**"No tenant context" counted sites it had not read.** An options argument the
+walker could not parse was folded into the same bucket as one it had read and
+found empty. That published **84 sites "carrying no tenant context at all"**
+when 17 said so and 67 were simply unread — an over-claim in the *alarming*
+direction, on the very figure this page tells other cards to cite. `carries` is
+now three-valued, and an unreadable argument can never contribute to the
+provable count.
+
+⭐ Both are the same shape as the failure this artefact exists for, wearing
+opposite hats: one scored an unread thing as *nothing to report*, the other
+scored an unread thing as *a finding*. `node
+scripts/check-tenant-audit-census.mjs --self-test` pins all of it — 18 classifier
+cases, 6 of which red against the old reading, driven from the gate's own
+self-test rather than from a flag on the generator.
+
+## ⭐ Deviations from the carried figures, untrimmed
+
+Four figures were carried forward from the lost census. They are **control inputs
+for this re-derivation, not targets**, and this instrument was not shaped to
+reproduce them. Where it disagrees, it disagrees on the page:
+
+| carried figure | where it survives | this census |
+| :--- | :--- | ---: |
+| 175 write call sites | quoted in the merged changeset | **215** |
+| 24 carrying no tenant context | quoted in the merged changeset | **9** provable and tenancy-enabled; **32** more whose options argument is unreadable |
+| 127 of 175 statically decidable, 48 runtime-parameter-name sites | restated on the `isSystem`-scoping card | **143 of 215** decidable, **72** undecidable |
+| 135 (77%) silenced by the `isSystem` guard before the posture gate | the lost issue body — **no surviving corroboration** | **not reproduced**: 97 decidably elevated, 0 decidably not, 101 undecidable |
+| 141 and 132, two independent re-derivations | the card that filed this work | — |
+
+**The differences are not reconciled, and deliberately so.** The old census's
+population definition is not recoverable — that is the whole reason this page
+exists — so no honest reading can attribute the gap to a specific cause. What can
+be stated is what this instrument counts, which is written above and re-runnable
+at any commit.
+
+Two structural facts do plausibly widen this reading against any hand or regex
+one, and both are counted in the generated tables below: the 45 sites reached
+through an erased (`any`) receiver, and the 37 that name their object through a
+`const` rather than inline. An instrument that read either the way a person does
+would report a smaller number and would not say so.
+
+The fourth row is the one worth flagging to anyone citing it. **The 135 / 77%
+figure has no surviving corroboration anywhere in the tree.** This census reads
+97 of 215 (45%) as decidably elevated, with 101 more whose elevation is a
+run-time fact — so the claim is neither confirmed nor refuted, and the honest
+answer is that a static reading cannot settle it.
+
+⇒ **Cite `9 / 215`, and say what it is**: the sites whose options argument was
+READ and holds no tenant context, against a decidably tenancy-enabled object.
+That is the control's provable yield surface. ⛔ Do not cite it as "the sites
+without tenant context" — **32 further sites** have an options argument this
+cannot read, and they are neither in nor out.
+
+{/* BEGIN GENERATED: tenant-audit-census (scripts/tenant-audit-census.mjs) — DO NOT EDIT */}
+
+## The measurement
+
+| what | count |
+| :--- | ---: |
+| write call sites on the application surface | **215** |
+| …whose object name is statically decidable | 143 |
+| …whose object name is chosen at run time | 72 |
+| …against an object with tenancy ENABLED | 143 |
+| …against an object that declares tenancy off | 0 |
+| threading a tenant context | 131 |
+| PROVABLY carrying none (options read, no context key) | **17** |
+| …of those, against a decidably tenancy-enabled object | **9** |
+| options argument UNREADABLE — may or may not carry one | 67 |
+| …of those, against a decidably tenancy-enabled object | 32 |
+| threading a decidably ELEVATED (`isSystem`) context | 97 |
+| threading a context that is decidably NOT elevated | 0 |
+| threading a context whose elevation is a run-time fact | 101 |
+
+| how the instrument reached the site | count |
+| :--- | ---: |
+| receiver carried a readable engine type | 170 |
+| receiver erased, placed by the object NAME | 19 |
+| receiver erased, placed by an `object: string` PARAMETER | 15 |
+| receiver erased, placed by an `UNTYPED_RECEIVERS` row | 11 |
+
+| object name spelled inline | 106 |
+| object name spelled through a `const` | 37 |
+| object name is an `object: string` parameter | 19 |
+| object name is some other run-time expression | 53 |
+
+The corpus walked is every tracked non-test source under `packages/services/`
+and `packages/plugins/`; calls to a same-named method on something that is not
+a data engine were subtracted. Every site is listed in
+[`docs/audits/2026-08-tenant-audit-write-call-sites.counts.md`](https://github.com/objectstack-ai/objectstack/blob/main/docs/audits/2026-08-tenant-audit-write-call-sites.counts.md),
+regenerated by the same command.
+
+### Corpus scale — present and dated, ⛔ NOT enforced
+
+⛔ These four describe the CORPUS this census walked, not the population it
+certifies, and the gate deliberately does not hold them to the tree — a source
+file arriving anywhere under the two roots moves them while every verdict above
+holds still. They are required to be HERE and to say WHEN they were true;
+their values are not compared. The reasoning, and the measurement behind it,
+are in `scripts/check-tenant-audit-census.mjs`.
+
+Measured on 2026-08-31 at `fc8858a24`.
+
+| corpus scale (not enforced) | count |
+| :--- | ---: |
+| tracked non-test sources scanned | 534 |
+| engine-shaped types recognised | 56 |
+| declared objects in the registry | 297 |
+| same-named calls subtracted as non-engine | 119 |
+
+{/* END GENERATED: tenant-audit-census */}