fix(objectql): lifecycle tenant scan asks the registry before reading sys_organization

[objectstack-fleet]

Fixes #21597
Clause-②: no

What changed

• packages/objectql/src/lifecycle/lifecycle-service.ts: loadGovernance's tenant scan now asks engine.registry.getObject('sys_organization') before it reads that object.
  • An unregistered sys_organization is the single-tenant answer. There is no read and no tenant override, and the sweep runs one global pass on each declared window.
  • A registered one is read exactly as before. The catch still accepts only isMissingTableError(error, 'sys_organization'). Every other failure still aborts the sweep, and that includes an OBJECT_NOT_FOUND thrown from that read.
• LifecycleEngineLike['registry'] declares the optional getObject?(name: string): unknown member the scan reads, because a published type must not refuse a key the code below it reads.
  • It is optional so that a double modelling only getAllObjects stays a legal engine. Such a registry cannot be asked, and the scan then reads as before.
  • Every real engine has it: ObjectQL.registry is the SchemaRegistry.
• packages/runtime/src/expected-read-refusal-noise.ts (the claim's declared cross-lane path, comment only): the header no longer says the org probe catches only a missing table. It now says that the probe and the lifecycle snapshot both ask the registry first, and it states what the seed-loader accepts.
• New pins in packages/objectql/src/lifecycle/lifecycle-service.organization-registry.test.ts: six cases on a REAL ObjectQL engine over a stub driver, so the refusal the guard avoids is the engine's own and not a double's guess.
• .changeset/21597-lifecycle-registry-first-guard.md: patch for @objectstack/objectql only. The runtime half is measured below.

Why: the mechanism, measured

• Since eb9ef791bd, ObjectQL.resolveObjectName throws objectNotFoundError(name) exactly when this._registry.getObject(name) is falsy. Every in-process verb resolves through it. So engine.registry.getObject is the refusal's own predicate: the guard asks the very question the refusal asks, never a list of names.
  • getAllObjects was not used for this. It is a full merging walk with a side effect, and it can disagree with getObject's short-name and FQN index. The dangerous direction of that disagreement is "absent" for an object that resolves.
• Premise at base 36ad3210d4: the new file was run before the fix and gave 5 passed, 1 failed.
  • The premise case shows the engine refusing find('sys_organization') with code: 'OBJECT_NOT_FOUND', status: 404 and object: 'sys_organization', with no driver read at all.
  • The unregistered case fails on the scan having read sys_organization (expected 1 to be +0).

Which shape was followed, and why

No shared helper exists: there is no registry-presence helper in objectql, core or types. #21545 left two shapes:

• the engine probe's registry presence before the read (probeInstallOrganizations);
• the seed-loader's catch-side refusal attributed on object (resolveSoleOrganizationId).

This follows the engine probe's shape, with its catch unchanged. It is spelled with MigrationRecoveryPlugin's capability check (typeof ... === 'function' && !...), because LifecycleService holds a duck-typed engine rather than the registry itself. It is not the seed-loader's catch-side shape, for three reasons:

1. The card's ruling names the registry-first guard.
2. On a real engine the registry question makes a catch-side sys_organization arm unreachable, so adding that arm as well would make a third variant.
3. An OBJECT_NOT_FOUND that arrives after the registry said "registered" either names another object or contradicts the registry. It propagates, and this is pinned.

There is no new engine API and no engine.ts edit. The registry comes from the engine's existing registry accessor, which settles H3.

Pins (real ObjectQL, engine.find spied with call-through)

case	asserts
control: registered, provisioned, one org with a 90d tenant override	scan reads once (reaches the driver); tenant pass at 90d, then the global 30d pass; no error
premise: unregistered	the engine refuses the read: OBJECT_NOT_FOUND, 404, object: 'sys_organization'; the driver saw nothing
unregistered: single-tenant sweep	report.errors empty; zero scan reads; one global 30d pass; report.swept records the 30d cutoff; no warn
registered but unprovisioned (no such table)	the scan reads and the driver throws; global pass; no error (unchanged missing-table answer)
real driver fault (ECONNREFUSED)	the scan's read rejects with code: 'ECONNREFUSED'; no candidate read, no delete, nothing swept; report.errors and the warn quote that fault's own message
OBJECT_NOT_FOUND attributed to ANOTHER object (a beforeFind hook reads an unregistered sys_org_unit)	rejection OBJECT_NOT_FOUND, 404, object: 'sys_org_unit'; the sweep aborts; not read as absence

Verification, at final head 190cea2e9e

• Reverse verification. The fix was committed first, then the guard was ablated through scripts/ablation-replace.mjs: the anchor hit once, and the blob went a3ff3c2d4d3d to 6c3fa03e505d. Result: src/lifecycle/ gave 1 failed, 115 passed (116). Only the unregistered pin went red, and it reported the defect itself: governance snapshot could not be loaded (Object 'sys_organization' not found) — sweep aborted before any policy was applied.
  • The restore was git checkout HEAD -- ABSPATH. The blob is back at the HEAD blob a3ff3c2d4d3d, git diff HEAD is empty and git status --porcelain is empty.
  • The first run of the same ablation, at dfb2af2144, gave the same direction.
  • The 110 pre-existing lifecycle tests stay green with the guard ablated. Their doubles have no getObject, so they never reach the guard.
• Tests.
  • pnpm --filter @objectstack/objectql test: Test Files 368 passed (368), Tests 7421 passed (7421).
  • src/lifecycle/: 2 files, 116 passed.
• Typecheck. pnpm --filter @objectstack/objectql typecheck exit 0, with check:test-typecheck: OK. The new file is in the test program (tsc -p tsconfig.test.json --listFilesOnly: 1 hit) and compiles with zero errors.
• Import side. objectql's published .d.ts gains the optional member. Three test files in other packages build typed LifecycleEngineLike doubles, all registry: { getAllObjects } and none passing getSettings.
  • pnpm --filter @objectstack/service-messaging typecheck exits 0.
  • Reverse leg: pasting getObject: 42 into its double gives TS2352 ... The types of 'registry.getObject' are incompatible against the rebuilt .d.ts. The same paste passes an as assertion against the old type, so this proves the consumer read the rebuilt declarations. Restore proven.
• Runtime.
  • pnpm --filter @objectstack/runtime typecheck exit 0.
  • src/expected-read-refusal-noise.channel-asymmetry.test.ts: 4 passed.
  • The edited module is not in runtime's published files. After a build, its header text and its export captureExpectedReadRefusals have 0 hits in dist/, and the module is 0 of 79 sources in both sourcemaps. The positive control migration-recovery-plugin is 1 of 79, and its export hits 4 dist files. So the changeset carries no runtime entry.
• Gates. node scripts/pm/dispatch-gates.mjs --commands derived 64 commands at 190cea2e9e, and all 64 exited 0. --ran reconciliation: 64 derived, 64 run, 0 NOT-MEASURED (a derived zero, every exit code recorded).
  • check:query-options-erasure was red once on the first head (test surface 236 to 238: two as any query options in the new file). Both are typed now, and the ratchet holds at 236.
• Lint (a proven narrowing; pnpm lint is CI's). eslint --no-inline-config --format json was run on the three TS files in the diff: 3 files, 0 errors, 0 warnings. The changeset .md is outside eslint's configuration ("no matching configuration"). eslint.config.mjs states that it never enables type-aware linting, so this diff cannot move any untouched file's verdict.

Acceptance notes

• Boundary of the ruling, noted, not filed. Take a composition that registers no sys_organization while its database still holds an organization table written by another composition. It now sweeps every tenant on the global window. That is the card's stated semantics, and it is the same answer probeInstallOrganizations gives. Since eb9ef791bd no in-process verb can read that table by its raw name anyway.
• Clause line. Clause-②: no is copied from the claim. The only type change is the optional member on the published input type LifecycleEngineLike['registry']. Every engine accepted before is still accepted, and there is no new export. Precedent: commit 0f38ab084 added the optional tenancy key to LifecycleObjectLike, and it shipped as an objectql patch.
• Branch base. The branch is 2 commits behind origin/main (f97660cdd6). Neither commit touches objectql, the lifecycle or the runtime header, so the branch is not merged here.
• Worker count. The full objectql run passed --maxWorkers=2 after a bare --, which vitest drops, so it ran at vitest's default worker count. It is still a whole-package measurement.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 2 package(s): @objectstack/objectql, @objectstack/runtime, touching 4 documentable anchor(s). ⚠️ 1 changed file(s) yielded no anchor (packages/runtime/src/expected-read-refusal-noise.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

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

• content/docs/automation/flows.mdx (via sys_organization (literal, a string literal in loadGovernance))
• content/docs/data-modeling/drivers.mdx (via LifecycleService (symbol, a top-level class))
• content/docs/data-modeling/objects.mdx (via LifecycleService (symbol, a top-level class))
• content/docs/deployment/cli.mdx (via sys_organization (literal, a string literal in loadGovernance))
• content/docs/deployment/seed-tenancy-repair.mdx (via sys_organization (literal, a string literal in loadGovernance))
• content/docs/kernel/services.mdx (via LifecycleService (symbol, a top-level class))
• content/docs/permissions/administrator-guide.mdx (via sys_organization (literal, a string literal in loadGovernance))
• content/docs/permissions/attachments-access.mdx (via LifecycleService (symbol, a top-level class))
• content/docs/protocol/kernel/config-resolution.mdx (via sys_organization (literal, a string literal in loadGovernance))
• content/docs/protocol/knowledge.mdx (via LifecycleService (symbol, a top-level class))
• content/docs/protocol/objectql/schema.mdx (via sys_organization (literal, a string literal in loadGovernance))

⛔ 6 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 loadGovernance))
• content/docs/releases/v14.mdx (via LifecycleService (symbol, a top-level class))
• content/docs/releases/v15.mdx (via LifecycleService (symbol, a top-level class))
• content/docs/releases/v17/17-1.mdx (via sys_organization (literal, a string literal in loadGovernance))
• content/docs/releases/v17/17-4.mdx (via sys_organization (literal, a string literal in loadGovernance))
• content/docs/releases/v17/17-5.mdx (via sys_organization (literal, a string literal in loadGovernance))

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

• 1 changed file(s) yielded no anchor (packages/runtime/src/expected-read-refusal-noise.ts) — pages documenting those are invisible to this run
• 1 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 54 of 206 client-bound route-ledger rows — the other 152 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 152: 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; 97 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.
• a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a [REMOVED] tombstone on another for each of active, aria, joins, objects, template, tools and version (censused on [finding] tools is a key on BOTH AgentSchema (tombstoned, dead) and SkillSchema (live, cloud-attested), so a name-based search attributes skill examples to the agent key — it produced a false stop-the-line alarm on PR #19059 #19093 over the liveness ledger's governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on fix(spec): the agent.tools liveness row says dead — it claimed live on a key the schema tombstoned #19059: content/docs/ai/agents.mdx was reported as contradicting the agent.tools tombstone over its tools: example at :161, which is inside the defineSkill({ block opened at :155 — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES SkillSchema, and as an AgentSchema it FAILS at tools with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a .strict() guidance map leaves no tombstone in the walked shape and none of them here (tool.category, live as AIToolDefinition.category).

Coarse fallback — 35 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 045b946256d988653fdca185c7fd33d6d86bd78d → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 16e12a21aece8ba28e65e473337e33d812033d09 — the merge of head 190cea2e9edaa43f98079514ba36bf240a956026 into base 045b946256d988653fdca185c7fd33d6d86bd78d, 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 16e12a21aece8ba28e65e473337e33d812033d09 && git checkout 16e12a21aece8ba28e65e473337e33d812033d09
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 045b946256d988653fdca185c7fd33d6d86bd78d 190cea2e9edaa43f98079514ba36bf240a956026 && git checkout -B drift-repro 045b946256d988653fdca185c7fd33d6d86bd78d && git merge --no-ff 190cea2e9edaa43f98079514ba36bf240a956026

node scripts/docs-audit/affected-docs.mjs --json 045b946256d988653fdca185c7fd33d6d86bd78d

⚠️ 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 045b946256d988653fdca185c7fd33d6d86bd78d → pass the list as
args.docs, on the commit named under Which tree this was computed on.