fix(plugin-auth): report at error when a single-posture deployment holds more than one organization (#17010)

[claude]

Fixes #17010

Clause-②: no

(declaration line written by the domain:services review seat, not by the implementer — the Clause-②: line is the claim's, and Check Changeset reads it only as a line-initial literal in this body; a prose or quoted mention is "a near miss, not a declaration". Measured on THIS diff rather than predicted from the card: 0 added lines containing export, 0 new ERROR_CODE_LEDGER / code: entries, 0 added throws. This adds a boot-time diagnostic — it accepts nothing new, refuses nothing new, publishes no symbol and changes no wire field. ⛔ Do not delete this line; the gate re-reads the body on the next edited event, so removing it re-reds the PR.)

ADR-0131 §1.2(3) states, verbatim: 「The measured leak's precondition — many organizations with Layer 0 inert — is today a refused boot (ADR-0093 D5, cloud#1020, cloud#1664).」 It is not. A deployment that never REQUESTS a walled posture and simply HOLDS more than one sys_organization row under single boots, serves, and says nothing.

What changed

packages/plugins/plugin-auth/src/tenancy-service.ts takes a count(sys_organization) census and reports at error when a non-walled deployment holds more than one, naming the posture it DECLARED, the count it HOLDS, and the two remedies the card spells out (declare a walled posture, or hold one organization).

⛔ The boot is NOT refused. This only reports — the dispatching seat's ruling for this card, 2026-09-10: making the state visible restores a declared invariant and takes nothing away from anyone, whereas actually refusing the boot would stop deployments that run today (the card's own measured instance, objectstack-ai/ats, is one). That fork stays open and is the maintainer's; nothing here has to be undone if the answer is "refuse". The per-write ambiguous-organization refusal (#8844) is untouched — it is this card's evidence, not its target.

Why the reading lives on TenancyService.defaultOrgId() and not in a new boot hook

That is the seam the card names as silent, it already reads sys_organization, and it already knows the REQUESTED posture — so the census needs no second reader and no second store read to keep in step with.

It is reached at boot on a default deployment: AuthPlugin registers a kernel:ready hook that runs backfillMemberships with resolveTargetOrg: () => tenancy.defaultOrgId(), and the membership policy gating it defaults to auto (AuthManager.getMembershipPolicy() returns this.config.membershipPolicy ?? 'auto'). That claim is not asserted in prose only — it is pinned against the real backfillMemberships pass in the suite, so the day the wiring stops reaching this seam, the test says so. A deployment that opts out of that pass (OS_SKIP_MEMBERSHIP_BACKFILL=1, or an invite-only policy) takes the census at the first single-posture organization resolution instead — still once per process, still before anybody has been mis-bound.

The alternative placement — a new kernel:ready probe wired from auth-plugin.ts, the shape boot-sign-in-reachability.ts uses — was NOT taken: auth-plugin.ts is outside this card's declared file surface and is held by open draft PR #17443.

The cost of the reading

One count(sys_organization) per process — one SELECT COUNT(*), via IDataEngine.count, over a table whose population under single is by definition one row (N greater than one IS the defect being reported).

• A walled posture pays zero: the census sits downstream of the existing postureEnforcesWall early return. Pinned (engine.count asserted never called for both group and isolated).
• A healthy deployment reaches it exactly once: it also sits downstream of the memoized resolution. Pinned (three defaultOrgId() calls, one count()).
• An engine that cannot answer — every reduced mock embedding, any engine with no count — pays nothing and stays silent, and the census is not latched, so a store that comes up later is still censused. Pinned.
• No connection is needed that this path did not already need: the read goes through the same lazily-resolved deps.getEngine() the existing sys_organization read uses. Nothing was added at init(), where the engine is not yet resolvable.

Negative control

Exactly one organization under single stays silent, and so does a store with none yet — pinned as two separate tests, because a check that fires on a healthy install is worse than no check. Both stayed GREEN under the ablation below, which is the point: they do not depend on the check existing.

Ablation

Mutation: the census call removed from defaultOrgId(), on the committed tree (7c6720e9e).

• On-disk proof, not an exit code: marker if (!organizationCensusTaken) { counted 1 before, 0 after; blob 9db367209c21a7bf0052561260c71520309e787e became 439b3dc2d08267734d4b1157adfaeb8f77b2505a.
• Result: 6 failed | 28 passed (34), every failure AssertionError: expected "vi.fn()" to be called 1 times, but got 0 times — the six that assert the report fires, including the boot-reachability pin. The negative controls stayed green.
• Restoration proven BY STATE: git diff HEAD empty, and git hash-object back to 9db367209c21a7bf0052561260c71520309e787e — equal to the HEAD blob. Restored with git checkout HEAD -- path from an EXIT INT TERM trap holding an absolute path.

Verification

Run at 0126be826.

• pnpm --filter @objectstack/plugin-auth exec vitest run src/tenancy-service.test.ts — 34 passed.
• pnpm --filter @objectstack/plugin-auth typecheck — exit 0 (includes check:test-typecheck, which is what covers the test layer here: the package tsconfig excludes **/*.test.ts).
• Gates derived from the ACTUAL diff with node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack (3 changed paths), reconciled with --ran: 60 commands, 58 exit 0, 2 exit 3.
  • check:dual-build-cjs-loads and check:type-check-debt both exit 3 = PREREQUISITE NOT MET (they read built output of the whole tree). Recorded as NOT MEASURED, ⛔ not as a pass — CI builds the closure and measures them.
• Two families run because the diff implicates them even though the derivation did not name them: pnpm check:optional-error-sink — exit 0 (the new sink is in its census: optional error beside a REQUIRED warn), and pnpm check:durability-log-level — exit 0.
• Repo-wide scans (pnpm lint and the rest of the lint workflow) are CI's run, not this branch's.

Acceptance notes

• ADR-0131 §1.2(3) is still factually wrong after this lands, and arguably more so — it says the precondition "is today a refused boot"; this builds a REPORT. docs/adr/** is a governed surface and a code PR editing it is exactly what that guardrail stops, so it is named here and routed to the PM as its own card rather than fixed in this diff.
• The census is deliberately module-private: it has exactly one caller and it is in the same file, so nothing new is published through the package barrel. The exported surface of tenancy-service.ts is byte-identical to origin/main — which is also what keeps the dispatch's Clause-②: no declaration true.
• A DEGRADED walled deployment (a wall requested, the runtime absent) is not censused here: defaultOrgId() returns null before any read, and ADR-0093 D5 already refuses that boot. Observation only, no card.

🤖 Generated with Claude Code

https://claude.ai/code/session_01ToDPcx9AESFubJkDiFMtKW

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/plugin-auth, touching 12 documentable anchor(s).

5 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/deployment/seed-tenancy-repair.mdx (via sys_organization (literal, a string literal in probeOrganizationCount; a string literal in resolveSinglePostureManyOrganizationsReport))
• content/docs/deployment/tenancy-modes.mdx (via TenancyService (symbol, a top-level interface))
• content/docs/permissions/administrator-guide.mdx (via sys_organization (literal, a string literal in probeOrganizationCount; a string literal in resolveSinglePostureManyOrganizationsReport))
• content/docs/protocol/kernel/config-resolution.mdx (via sys_organization (literal, a string literal in probeOrganizationCount; a string literal in resolveSinglePostureManyOrganizationsReport))
• content/docs/protocol/objectql/schema.mdx (via sys_organization (literal, a string literal in probeOrganizationCount; a string literal in resolveSinglePostureManyOrganizationsReport))

⛔ 3 release-owned page(s) also name something this change touched. These are read-only:

• content/docs/releases/implementation-status.mdx (via sys_organization (literal, a string literal in probeOrganizationCount; a string literal in resolveSinglePostureManyOrganizationsReport))
• content/docs/releases/v17/17-1.mdx (via sys_organization (literal, a string literal in probeOrganizationCount; a string literal in resolveSinglePostureManyOrganizationsReport))
• content/docs/releases/v17/17-4.mdx (via sys_organization (literal, a string literal in probeOrganizationCount; a string literal in resolveSinglePostureManyOrganizationsReport))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

What this run could not see

• 3 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 60 of 215 client-bound route-ledger rows — the other 155 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 155: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 55 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 100 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 13 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json fd62a66b7c48be167deb74467ca93e6ad3223f38 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 541dc5b0249823ab6735d92ed1fbffb67dc10d70 — the merge of head 0126be826a9b5849da0b946bec8246478dee199c into base fd62a66b7c48be167deb74467ca93e6ad3223f38, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 541dc5b0249823ab6735d92ed1fbffb67dc10d70 && git checkout 541dc5b0249823ab6735d92ed1fbffb67dc10d70
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin fd62a66b7c48be167deb74467ca93e6ad3223f38 0126be826a9b5849da0b946bec8246478dee199c && git checkout -B drift-repro fd62a66b7c48be167deb74467ca93e6ad3223f38 && git merge --no-ff 0126be826a9b5849da0b946bec8246478dee199c

node scripts/docs-audit/affected-docs.mjs --json fd62a66b7c48be167deb74467ca93e6ad3223f38

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs fd62a66b7c48be167deb74467ca93e6ad3223f38 → pass the list as
args.docs, on the commit named under Which tree this was computed on.