fix(lint): give the tenant-audit census refusals an exit to CI (#18534)

Fixes #18211

Clause-②: no

## What

Two halves, and the second is what makes the first landable.

1. **`scripts/check-tenant-audit-census.mjs` gains check C,
`censusRefusals()`** — it reads
`census.unledgered` and `census.staleLedgerRows` off the census it
already runs and routes
   both to the gate's exit code.
2. **The two sites that check C then found are fixed at the receiver** —
`claimOrphanOrgRows`
and `claimOrgSeedOwnership` took `ql: any`, so they are given the narrow
`OrgScopingEngine`
   type they actually call through.

## Why check C

`runCensus()` reports two failures about the **tree** rather than about
the artefacts:
`unledgered` (a write call site whose receiver is erased and that none
of the three placement
rules reaches) and `staleLedgerRows` (an `UNTYPED_RECEIVERS` row
matching no call).

The generator's own `main()` prints both and exits 1. But `lint.yml`
(lines 1995/1996 on this
tree) invokes the **gate**, never the generator — and the gate read
neither field. Measured on
this branch's base `1e496f979`:

| file | `unledgered` reads | `staleLedgerRows` reads | control:
`writeCallSites` reads |
|:---|---:|---:|---:|
| `scripts/check-tenant-audit-census.mjs` | **0** | **0** | 17 |
| `scripts/tenant-audit-census.mjs` | 3 | 3 | 5 |

The control is counted in the same file as each zero, so those zeros are
readings, not a grep
that failed to fire.

So the census could find an unplaceable receiver, say so to nobody, and
`Lint & Repo Gates`
stayed green — a defect arriving as **compliance**. This direction is
published:
`content/docs/permissions/tenant-audit-census.mdx` tells readers that a
receiver none of the
three place is an error, never a default.

The fix is the **read**, not a second run of the generator in the
workflow: that would walk
the same corpus and build the same AST twice for one verdict the gate
already holds in hand.
`.github/workflows/**` is untouched.

## Why the receivers are typed, and not ledgered

Check C found exactly two unplaced sites, both `ql: any` seed/back-fill
helpers writing
`schema.name` under `context: SYSTEM_CTX`:

- `packages/plugins/organizations/src/claim-org-seed-ownership.ts`
(`:52` the parameter, `:93` the write)
- `packages/plugins/organizations/src/claim-orphan-org-rows.ts` (`:61`
and `:106`)

Both match the already-ledgered
`plugin-security/src/claim-seed-ownership.ts` row word for
word, so they are engine writes and `engine: false` was never on the
table. What settles the
remaining choice is the ledger's own first line,
`scripts/tenant-audit-census.mjs` at
`origin/main` `1e496f979`, line 803: **"SHRINK-ONLY, and keyed by (file,
receiver) — never by
line"**. Adding two rows to a shrink-only ledger runs against its own
discipline. A typed
receiver needs no row at all, so `UNTYPED_RECEIVERS` is untouched and
`placedByLedger` stays
at **11**.

`OrgScopingEngine` follows `OrphanCleanupEngine` in `plugin-sharing`: a
narrow, locally
declared interface naming only the doors these functions call — `find`,
`update`, and an
optional `registry`. Optional on purpose, because "registry unavailable"
is a real, tested,
logged no-op path that the type has to be able to describe.

It is **package-private**, and that is load-bearing rather than
incidental. The census reads
the type declared at the **receiver**, in this source tree; it never
reads the package's public
entry. Exporting the interface from `index.ts` therefore bought the
placement nothing and only
widened a published surface — so `src/index.ts` exports exactly the nine
names it exported
before, byte for byte:

Taken by diffing the `^export` lines of that file as `git show` prints
them at `origin/main`
against the same lines at `HEAD`: **exit 0, no output, 9 lines on each
side.**

Fire control for that zero: the identical comparison run against the
commit that *did* carry
the export reports one added line — the `export type { OrgScopingEngine
}` re-export — and
exits 1. So the comparison can see an added export, and is reporting
none.

The emitted declarations still carry `interface OrgScopingEngine`
inline, so a consumer's call
resolves without ever naming it; it is simply absent from the shipped
export list.

### The caller had to state it too

Naming the parameter turned an invisible coupling into a type error:
`OrgScopingQuerySlot` in `organizations-plugin.ts` declared the three
members the plugin calls
itself — but the plugin also **forwards** that value to
`claimOrphanOrgRows`, which writes
through it. That is the finding, not an obstacle, and the slot now
extends `OrgScopingEngine`
to say so.

## Measurements

All commands run in a dedicated worktree on `origin/main@1e496f9`
after `pnpm install`.

**Acceptance 1 — the generator, on the day** (`node
scripts/tenant-audit-census.mjs`):

- exit code **1**
- `unledgered` — **2** entries, the two sites above
- `staleLedgerRows` — **0** entries (empty). Fire control for that zero:
the same `--json`
dump reports `unledgered.length = 2` and `unresolved.length = 2`, so the
reader is live.
- Population: 223 write call sites, 569 sources scanned.

**Acceptance 3 — both directions, measured twice.**

First on the gate-only commit, to show check C is real:

| direction | how | gate exit |
|:---|:---|---:|
| red on the day's sites | check C, before the receivers were typed |
**1** (2 x `[untyped-receiver]`) |
| same tree, no check C | `HEAD~1` | **0** |
| green once the sites are placed | one-shot ablation removing them from
the corpus | **0** |

Then again on the finished tree, which is the direction that matters
now:

| leg | gate exit | `[untyped-receiver]` lines |
|:---|---:|---:|
| finished tree | **0** | 0 |
| erase ONE receiver back to `ql: any` | **1** | **1**, naming the file
and line |
| same mutated tree, `censusRefusals()` neutered | 1 (drift/prose only)
| **0** |

The third row is the control: with check C disabled, the
untyped-receiver finding disappears
while the unrelated findings remain — so that red is unambiguously check
C's and nothing
else's. All mutations were one-shot, each proven on disk by counting
both the injected and
the removed string before any result was read, each script carrying
`trap restore EXIT INT TERM` with absolute paths, and each restored to a
blob hash equal to
`git rev-parse HEAD:PATH` with `git diff HEAD --stat` empty afterwards.

**The self-test was made to fail before its green was believed:**
neutering `censusRefusals()`
reds it with 4 of 24 cases failing by name; deleting the whole `census
refusals` battery block
reds it with `self-test battery "census refusals" DID NOT RUN — 0 cases
registered, 5 pinned`.
The new battery carries its own control (a census with neither an
unplaceable site nor a stale
row is **not** a finding), so its four positive cases cannot be passed
by a function that
simply reports everything handed to it.

**What the population did.** 223 to **225**, and both new sites read as
elevated. Worth
recording, because on the gate-only commit the population was **also**
223 with the two sites
unplaced: they were never counted at all — they were the hole in the
certified population, and
nothing on the way to a CI verdict said so. The generated region and the
audit ledger are
regenerated with `--write`; the page's eight hand-written prose figures
are restated by hand,
which `--write` does not do.

**Package verification:** `pnpm --filter @objectstack/organizations
typecheck` and `test` both
exit 0 — 8 test files, 108 tests. No test file changed: both fakes are
declared `const ql: any`,
which the narrowed parameter accepts. No in-repo package depends on
`@objectstack/organizations`,
so the consumer sweep is empty by construction rather than by omission.

**Clause-②:** the whole diff is a **narrowing**. Two exported function
parameters go from `any`
to an interface; `OrgScopingQuerySlot` is declared without `export` and
stays package-private;
and the package entry gains no name, measured above. Nothing relaxes an
accepted set and
nothing widens a published surface.

## Changeset

**A changeset is required and `skip-changeset` has been removed** — the
judgement flipped when
the diff grew past `scripts/`, and it was re-verified rather than
assumed.
`@objectstack/organizations` is not private and ships `files: ["dist",
"README.md",
"CHANGELOG.md"]`. After `pnpm --filter @objectstack/organizations
build`, the shipped
`dist/index.d.ts` declares `claimOrphanOrgRows(ql: OrgScopingEngine,
...)` where it previously
declared `ql: any`, and exports the new `OrgScopingEngine` type. Fire
control for that reading:
the same grep over the same file scores **0** for a symbol that should
not be there.

Bumped `minor`, not `patch`: runtime behaviour is unchanged, but a
consumer passing a value
that does not structurally offer `find` and `update` no longer compiles.
Such a consumer
already got `[]` and a warning from the existing guards, so nothing that
worked stops working
— the failure moves from run time to build time.

## Gates run

Derived from the diff with `node scripts/pm/dispatch-gates.mjs --repo
objectstack-ai/objectstack --commands`
and reconciled with `--ran`, every line recording its exit code: **105
derived, 105 run, 0
NOT-MEASURED, 0 UNRUN**, and the tool confirms that zero is derived from
the recorded codes
rather than claimed. `pnpm check:pm-dispatch-gates` (the bare ~1746-case
battery) exits **0**
in 814.8s, run detached and waited on with `tail --pid`.

Two families needed a built tree and say so themselves rather than
skipping
(`check:skill-examples`, `check:dual-build-cjs-loads` at `exit 3`,
"PREREQUISITE NOT MET");
both were re-run after a full `pnpm build` and both exit **0**.

One family reds locally and is **not** this diff: `pnpm
check:cross-package-test-inputs`
reports that `@objectstack/cli` descends from `packages/spec/dist/`
through a radius no
declared glob reaches, rooted in
`packages/cli/test/init-created-files-summary.e2e.test.ts` —
a file this PR does not touch. It reds only because a local
`packages/spec/dist/` exists.
Proven by moving that directory aside and re-running: **exit 0**, `29
package(s) read outside
themselves, all declared`. The `lint` job that runs this gate does not
build, so CI sees the
unbuilt state. Reported upward as a finding in its own right.

## 验收备注

卡面四条,原样照抄:

1. 先 `pnpm install`,再重跑 `node
scripts/tenant-audit-census.mjs`,读**今天的**退出码与 `unledgered` /
`staleLedgerRows` 的**实际内容**。⛔ 零要有发火对照。
2. 给这两个字段一条**到 CI 的出口**。⛔ 不许用「把 census 也加进 `lint.yml` 跑一遍」糊过去(那会让同一份 AST
走两遍),修法落在门禁文件内。
3. ⭐ **两个方向的对照都要**:门禁对今天这些站点**必须红**;去掉其中一个(或补上 ledger 条目)之后**必须绿**。⛔
只给一个方向不算量过。
4. ⛔ **不许为了让门禁绿而把那些站点写进 ledger 当既成事实** —— 先裁它们该不该被落位,再决定记不记。⚠️
若你判断需要这次裁定,**回报 PM 席**,⛔ 不要自己裁。

Verdicts: 1 — measured above, with a fire control on each zero. 2 —
`censusRefusals()` in the
gate file; no workflow touched; the corpus is walked once. 3 — both
directions measured, twice.
4 — the ruling was escalated and returned as "type the receivers, do not
grow the ledger"; no
`UNTYPED_RECEIVERS` row was written.

Two things the card recorded as unmeasured, now measured: the generator
does exit **1** on the
day's tree, and `staleLedgerRows` is **empty**, so the whole of that red
was the
unplaceable-receiver half.

### The two regenerated artefacts

`content/docs/permissions/tenant-audit-census.mdx` and
`docs/audits/2026-08-tenant-audit-write-call-sites.counts.md` are in the
diff as the
**mandatory companions** of the population moving 223 to 225, not as
independent edits.

- Both are written by `node scripts/tenant-audit-census.mjs --write`,
the gate's one documented
  repair arm. Re-running it on the finished tree rewrites nothing.
- **Eight** figures on the page were changed **by hand**, because
`--write` does not touch the
page's hand-written prose: `223` to `225` in five places, `74` to `76`,
and `104` to `106` in
two. Each is a figure `PROSE_COUNTS` in the gate holds to the census,
and the gate names every
one of them — the eight edits are exactly the eight it named, no more.
The hand-written
`(47%)` beside the elevated share was re-checked and still rounds to 47.
- Nothing else on either artefact was hand-edited, and the last round of
work moved neither:
`git diff --stat` over both paths is empty after removing the package
export, which is the
  evidence that a visibility change moves no census reading.

### Noted, not filed

- `main()` in `scripts/tenant-audit-census.mjs` returns 0 from its
`--write` branch before it
reaches the `unledgered` / `staleLedgerRows` reporting, so `--write` is
silent about both.
It is a repair arm rather than a verdict and CI never calls it — an
observation, not a
defect class. Next toucher: anyone regenerating these artefacts, since
`--write` is the
  command they run.

## Attribution

Authored by Claude Code, session `session_017ef78bLdybu3AffehKkhfk`
(https://claude.ai/code/session_017ef78bLdybu3AffehKkhfk). The tail
footer below this line is
appended by the platform on every body edit, which is why this PR
carries its session id in
prose rather than only in that footer.


---
_Generated by [Claude Code](https://claude.ai/code)_

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: os-try-charles

.changeset/18211-org-scoping-engine-named-receiver.md

@@ -0,0 +1,15 @@
+---
+"@objectstack/organizations": minor
+---
+
+`claimOrphanOrgRows` and `claimOrgSeedOwnership` name the ObjectQL doors they write through — a package-private `OrgScopingEngine` interface replaces `ql: any` on both, and `OrgScopingQuerySlot` states the doors the plugin forwards rather than only the three it calls itself (#18211).
+
+The package's public entry is unchanged: `src/index.ts` exports exactly the nine names it exported before, byte for byte. What moved on the published surface is the two exported functions' signatures, and nothing else.
+
+Runtime behaviour is unchanged: the same guards run, the same rows are updated, and an engine without a `registry` still returns `[]` with a warning instead of throwing — `registry` is optional on the new type precisely so that tested path stays describable.
+
+- **Why a type and not a comment.** The tenant-audit census decides whether a write call site is an engine write by reading the **receiver's declared type**. An `any` receiver has no type to read, so both of these sites were reported as sites nothing could place — an error in that census, never a default, because a write it cannot see is a write the tenant-audit population does not certify. Naming the doors places both by type. The certified population moves 223 to 225 and both read as elevated (they write under `context: SYSTEM_CTX`).
+- **Narrow on purpose**, following `OrphanCleanupEngine` in `@objectstack/plugin-sharing`: `OrgScopingEngine` declares `find`, `update` and an optional `registry`, and nothing else. Widen it by adding a door that is actually used, never by re-exporting the engine's full contract — and keep it package-private: the census reads the type declared at the receiver, never the package entry, so exporting it would widen a published surface and buy the fix nothing.
+- **The slot change is a finding, not a refactor.** `OrgScopingQuerySlot` declared `registerMiddleware`, `find` and `getSchema` — but the plugin also hands that value to `claimOrphanOrgRows`, which writes through it. While the back-fill's parameter was `any` that coupling was invisible to the type system; naming the parameter turned it into a type error, and the slot now states it.
+- **Type-level tightening for consumers.** A caller passing a value that does not structurally offer `find` and `update` no longer compiles. Such a caller already got `[]` and a warning at run time from the existing guards, so nothing that worked stops working — but the failure moves from run time to build time, which is why this is not a patch. The parameter type is inlined into the emitted declarations, so a consumer never needs to name it.
+- ⛔ **No `UNTYPED_RECEIVERS` ledger row was added.** That ledger is documented shrink-only and keyed by (file, receiver); growing it by two rows to silence two sites runs against its own discipline, and a typed receiver needs no row at all.

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

@@ -106,7 +106,7 @@ 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 223 sites are spelled that way**. A
+forwarding shim cannot, and **67 of the 225 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.
 
@@ -155,10 +155,10 @@ 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 | **223** |
+| 175 write call sites | quoted in the merged changeset | **225** |
 | 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 | **149 of 223** decidable, **74** undecidable |
-| 135 (77%) silenced by the `isSystem` guard before the posture gate | the lost issue body — **no surviving corroboration** | **not reproduced**: 104 decidably elevated, 0 decidably not, 102 undecidable |
+| 127 of 175 statically decidable, 48 runtime-parameter-name sites | restated on the `isSystem`-scoping card | **149 of 225** decidable, **76** undecidable |
+| 135 (77%) silenced by the `isSystem` guard before the posture gate | the lost issue body — **no surviving corroboration** | **not reproduced**: 106 decidably elevated, 0 decidably not, 102 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
@@ -175,11 +175,11 @@ 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
-104 of 223 (47%) as decidably elevated, with 102 more whose elevation is a
+106 of 225 (47%) as decidably elevated, with 102 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 / 223`, and say what it is**: the sites whose options argument was
+⇒ **Cite `9 / 225`, 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
@@ -191,31 +191,31 @@ cannot read, and they are neither in nor out.
 
 | what | count |
 | :--- | ---: |
-| write call sites on the application surface | **223** |
+| write call sites on the application surface | **225** |
 | …whose object name is statically decidable | 149 |
-| …whose object name is chosen at run time | 74 |
+| …whose object name is chosen at run time | 76 |
 | …against an object with tenancy ENABLED | 149 |
 | …against an object that declares tenancy off | 0 |
-| threading a tenant context | 139 |
+| threading a tenant context | 141 |
 | 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 | 104 |
+| threading a decidably ELEVATED (`isSystem`) context | 106 |
 | threading a context that is decidably NOT elevated | 0 |
 | threading a context whose elevation is a run-time fact | 102 |
 
 | how the instrument reached the site | count |
 | :--- | ---: |
-| receiver carried a readable engine type | 179 |
+| receiver carried a readable engine type | 181 |
 | receiver erased, placed by the object NAME | 18 |
 | receiver erased, placed by an `object: string` PARAMETER | 15 |
 | receiver erased, placed by an `UNTYPED_RECEIVERS` row | 11 |
 
 | object name spelled inline | 109 |
 | object name spelled through a `const` | 40 |
 | object name is an `object: string` parameter | 19 |
-| object name is some other run-time expression | 55 |
+| object name is some other run-time expression | 57 |
 
 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
@@ -232,13 +232,13 @@ 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-09-14 at `d4554d4f5`.
+Measured on 2026-09-16 at `11daf7f69`.
 
 | corpus scale (not enforced) | count |
 | :--- | ---: |
-| tracked non-test sources scanned | 568 |
-| engine-shaped types recognised | 61 |
+| tracked non-test sources scanned | 570 |
+| engine-shaped types recognised | 63 |
 | declared objects in the registry | 117 |
-| same-named calls subtracted as non-engine | 140 |
+| same-named calls subtracted as non-engine | 146 |
 
 {/* END GENERATED: tenant-audit-census */}

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

@@ -29,17 +29,17 @@ silent, and `node scripts/tenant-audit-census.mjs --write` is the resolution.
 
 | Measure | Value |
 |---|---:|
-| Write call sites | 223 |
+| Write call sites | 225 |
 | Object name statically decidable | 149 |
-| Object name chosen at run time | 74 |
+| Object name chosen at run time | 76 |
 | Against a tenancy-enabled object | 149 |
 | Against an object declaring tenancy off | 0 |
-| Threading a tenant context | 139 |
+| Threading a tenant context | 141 |
 | Provably carrying none | 17 |
 | …and decidably tenancy-enabled | 9 |
 | Options argument unreadable | 67 |
 | …and decidably tenancy-enabled | 32 |
-| Threading a decidably elevated context | 104 |
+| Threading a decidably elevated context | 106 |
 | Threading a decidably non-elevated context | 0 |
 | Threading a context of undecidable elevation | 102 |
 
@@ -52,19 +52,21 @@ 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-09-14 at `d4554d4f5`.
+Measured on 2026-09-16 at `11daf7f69`.
 
 | corpus scale (not enforced) | count |
 | :--- | ---: |
-| tracked non-test sources scanned | 568 |
-| engine-shaped types recognised | 61 |
+| tracked non-test sources scanned | 570 |
+| engine-shaped types recognised | 63 |
 | declared objects in the registry | 117 |
-| same-named calls subtracted as non-engine | 140 |
+| same-named calls subtracted as non-engine | 146 |
 
 ## Every site
 
 | file | verb | object | tenancy | tenant context | n |
 |---|---|---|---|---|---:|
+| `packages/plugins/organizations/src/claim-org-seed-ownership.ts` | `update` | `schema.name` | undecidable | elevated | 1 |
+| `packages/plugins/organizations/src/claim-orphan-org-rows.ts` | `update` | `schema.name` | undecidable | elevated | 1 |
 | `packages/plugins/plugin-approvals/src/approval-service.ts` | `update` | `object` | undecidable | context, elevation undecidable | 1 |
 | `packages/plugins/plugin-approvals/src/approval-service.ts` | `insert` | `sys_approval_action` | enabled | elevated | 14 |
 | `packages/plugins/plugin-approvals/src/approval-service.ts` | `delete` | `sys_approval_approver` | enabled | elevated | 2 |

packages/plugins/organizations/src/claim-org-seed-ownership.ts

@@ -23,6 +23,8 @@
 
 import type { ServiceObject } from '@objectstack/spec/data';
 
+import type { OrgScopingEngine } from './org-scoping-engine.js';
+
 interface ClaimOwnershipOptions {
   logger?: {
     info: (message: string, meta?: Record<string, any>) => void;
@@ -49,15 +51,15 @@ function hasField(schema: ServiceObject, field: string): boolean {
  * and updates the org's unowned rows as `isSystem`. Returns a per-object summary.
  */
 export async function claimOrgSeedOwnership(
-  ql: any,
+  ql: OrgScopingEngine,
   organizationId: string,
   ownerUserId: string,
   options: ClaimOwnershipOptions = {},
 ): Promise<{ object: string; count: number }[]> {
   const logger = options.logger;
   if (!organizationId || !ownerUserId) return [];
   if (!ql || typeof ql.update !== 'function' || typeof ql.find !== 'function') return [];
-  const registry = (ql as any).registry;
+  const registry = ql.registry;
   if (!registry || typeof registry.getAllObjects !== 'function') {
     logger?.warn?.('[org-scoping] claimOrgSeedOwnership: registry unavailable');
     return [];

packages/plugins/organizations/src/claim-orphan-org-rows.ts

@@ -28,6 +28,8 @@
 
 import type { ServiceObject } from '@objectstack/spec/data';
 
+import type { OrgScopingEngine } from './org-scoping-engine.js';
+
 interface ClaimOptions {
   logger?: {
     info: (message: string, meta?: Record<string, any>) => void;
@@ -58,15 +60,15 @@ function hasOrganizationField(schema: ServiceObject): boolean {
  * Returns a per-object summary `{ object, count }[]`.
  */
 export async function claimOrphanOrgRows(
-  ql: any,
+  ql: OrgScopingEngine,
   organizationId: string,
   options: ClaimOptions = {},
 ): Promise<{ object: string; count: number }[]> {
   const logger = options.logger;
   if (!ql || typeof ql.update !== 'function' || typeof ql.find !== 'function') {
     return [];
   }
-  const registry = (ql as any).registry;
+  const registry = ql.registry;
   if (!registry || typeof registry.getAllObjects !== 'function') {
     logger?.warn?.('[org-scoping] claimOrphanOrgRows: registry unavailable');
     return [];

packages/plugins/organizations/src/org-scoping-engine.ts

@@ -0,0 +1,39 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * The ObjectQL doors the org-scoping back-fills reach through, named instead of
+ * erased.
+ *
+ * Both back-fills (`claimOrphanOrgRows`, `claimOrgSeedOwnership`) used to take
+ * `ql: any`. That is not a style preference in this corpus: the tenant-audit
+ * census reads the RECEIVER's declared type to decide whether a write call site
+ * is an engine write at all, and an `any` receiver has no type to read. Sites it
+ * cannot place are reported as `unledgered` -- an error, never a default,
+ * because a write it cannot see is a write the tenant-audit population does not
+ * certify. Naming the doors here places both sites by their TYPE, which is the
+ * one placement route that needs no ledger row.
+ *
+ * ⛔ Deliberately narrow, following `OrphanCleanupEngine` in `plugin-sharing`:
+ * it declares only what these two functions call, so it cannot drift into a
+ * second, competing description of the whole engine. Widen it by adding the door
+ * you actually use, never by re-exporting the engine interface.
+ *
+ * ⛔ And deliberately PACKAGE-PRIVATE -- the same restraint one layer out. The
+ * census reads the type declared at the RECEIVER, in this source tree; it never
+ * reads the package's public entry, so exporting this bought the placement
+ * nothing and only widened a published surface. ⛔ Do not add it to `index.ts`.
+ */
+
+import type { ServiceObject } from '@objectstack/spec/data';
+
+export interface OrgScopingEngine {
+  find(object: string, query: any, options?: any): Promise<any>;
+  update(object: string, data: any, options?: any): Promise<any>;
+  /**
+   * Optional on purpose. "registry unavailable" is a real, tested, logged no-op
+   * path in both back-fills -- a caller handing over an engine without one gets
+   * an empty result and a warning, not a throw -- so the type must be able to
+   * describe that engine rather than forcing the guard to be dead code.
+   */
+  registry?: { getAllObjects(): ServiceObject[] };
+}

packages/plugins/organizations/src/organizations-plugin.ts

@@ -2,6 +2,7 @@
 
 import { Plugin, PluginContext } from '@objectstack/core';
 import { claimOrphanOrgRows } from './claim-orphan-org-rows.js';
+import type { OrgScopingEngine } from './org-scoping-engine.js';
 import { isDefaultOrganizationBootstrapTrigger } from '@objectstack/plugin-auth';
 import { ensureDefaultOrganization } from './ensure-default-organization.js';
 import { assertWalledMembershipPolicyDeclared } from './membership-policy-gate.js';
@@ -66,13 +67,18 @@ export interface OrganizationsPluginOptions {
  * repository types its lookups rather than inheriting a grandfather clause it is
  * not on. Structural rather than the engine's full contract for the same reason
  * `membership-policy-gate.ts` states about ITS probes: this plugin needs three
- * members, the `catch` arms below already treat every one of them as possibly
- * absent, and naming the whole engine interface here would claim a coupling the
- * runtime checks do not make.
+ * members, and the `catch` arms below already treat every one of them as
+ * possibly absent.
+ *
+ * It extends `OrgScopingEngine` because this plugin does not only CALL the slot,
+ * it FORWARDS it: `claimOrphanOrgRows(ql, ...)` below writes through this very
+ * value. While that parameter was `any` the forwarded doors were a coupling the
+ * types did not state and the tenant-audit census could not read. Naming them
+ * here is the narrow claim -- only the doors that are actually forwarded, not
+ * the engine's full contract.
  */
-interface OrgScopingQuerySlot {
+interface OrgScopingQuerySlot extends OrgScopingEngine {
   registerMiddleware(mw: (opCtx: any, next: () => Promise<void>) => Promise<void>): void;
-  find(object: string, query: unknown, options?: unknown): Promise<any>;
   getSchema?(object: string): any;
 }