fix(security): measure the unscoped existence page cap instead of trusting it

[claude]

Fixes#11518

The defect

buildExistingByName (packages/plugins/plugin-security/src/seed-name-lookup.ts) is the batched
existence oracle the identity seeders consult in place of a per-item read. Its UNSCOPED page was
capped at limit: names.length — exact only while one row can exist per name. Since #8461 /
ADR-0120 D1 sys_capability.name and sys_permission_set.name are unique per organization, and
ADR-0066 D1 explicitly encourages admins to EXTEND the registry inside their own organization, so one
name legitimately carries a row per organization plus the platform's.

The rows that fall off a full page are the highest ids under #4363's ORDER BY id ASC tie-breaker,
so whole names vanish from the page — and a name missing from the page reads as absent, which
routes its caller to the INSERT branch. #10103 had already found and repaired exactly this on the
SCOPED arm (its comment sat directly above the line); the unscoped arm never got the repair, and two
seeders on main read unscoped — bootstrapDeclaredCapabilities and permission-set-projection's
env-overlay pass.

⛔ names.length * 2 is not the fix — it is the same defect with a larger constant. Rows-per-name
is bounded only by the number of organizations, so no constant multiplier is correct.

The shape implemented

The cap stopped being a promise and became a measurement. readNamePage asks the driver for one
row more than the budget it is willing to hold:

• page.length <= budget — the driver had no budget + 1-th row to give, so the page is provably the
  complete set for these names;
• page.length > budget — there is at least one more row than this read will hold, so the page is a
  prefix of the answer and cannot be read as one.

Both directions are exact, which is what makes the budget a free choice: no complete page is ever
mistaken for a truncated one, and no truncated page for a complete one. An over-budget page joins the
module's existing "could not answer" causes and reuses the degradation path that was already there
for a driver that cannot do $in — perItemIndex. No second fallback was invented.

Budgets:

arm	budget	why
unscoped	max(names.length * 4, 20)	a budget, not a bound — nothing bounds rows-per-name here. Shape matches the sibling generous cap on the same table in security-plugin.ts's permission-set loader
scoped	names.length * 2 (unchanged, #10103)	here the number is a proven bound: applyTenantScope returns this organization's rows plus organization-less ones, and the declared name index is unique per organization

The scoped arm keeps #10103's exact cap and gains the same probe, so a scoped page that overflows the
proven bound — reachable only where the unique index is absent or not yet created, the deployment the
module header already calls out — becomes a loud degradation instead of a silent truncation.

⭐ Declared behaviour change

This changes existing callers' behaviour in the truncating case: from a silent wrong answer to a
loud slow one. That is the intended direction — a read that under-reports and then inserts is the
defect — but it lands on two shipped seeders and is stated here rather than slipped in:

• names that used to be reported absent (and re-inserted as duplicates, or refused by the unique key
  as a "collision" naming a row nobody ever saw) are now answered correctly;
• the cost is one read per name plus one warning naming the object and the budget it could not fit
  inside. [security] batched seed existence read TRUNCATED — … is a separate diagnostic from the
  existing failed-read one, because the remedies differ: an outage versus an install whose catalog is
  simply wider than one page.
• An install that does not overflow the budget — every stock one, where a name carries a single row —
  issues exactly the same single read it issued before and says nothing.

Scope

• ⛔ Serial, not folded.The DERIVED half of bootstrapSystemCapabilities is still per-item, and batching it is a ruling, not a refactor — it trades away #8751's platformStampedInOrg signal or reverses part of #8552 #11520's option A (batching the derived half) is deliberately NOT in this
  PR, per the claim decision on buildExistingByName's UNSCOPED page cap truncates once a name can have more than one row — and a truncated page reads as "absent", which inserts #11518: The DERIVED half of bootstrapSystemCapabilities is still per-item, and batching it is a ruling, not a refactor — it trades away #8751's platformStampedInOrg signal or reverses part of #8552 #11520 is pm:blocked and its own text says that change
  "trades away [finding] The derived capability seeder rewrites a platform-marked row INSIDE an organization and still leaves the platform bucket unseeded — silently, on the UPDATE branch #8536 did not scope #8751's platformStampedInOrg signal or reverses part of [Decision] When a curated capability name is already held in the platform bucket, should the seeder keep declining — or adopt, backfill, or refuse the collision at authoring time? #8552 — a ruling, not a
  refactor." The truncation-detection machinery is built here; The DERIVED half of bootstrapSystemCapabilities is still per-item, and batching it is a ruling, not a refactor — it trades away #8751's platformStampedInOrg signal or reverses part of #8552 #11520 re-grades against it.
• Clause-②: no (triage's determination) — and it holds: this PR widens no exported surface.
  seed-name-lookup.ts exports exactly what it exported before (NAME_CHUNK_SIZE, SeedLookupLogger,
  ExistingLookupResult, ExistingByNameIndex, buildExistingByName); the budget constants and the
  NamePage outcome type are module-private on purpose.
• ⛔ packages/spec untouched. ⛔ content/docs/releases/** untouched.
• Stale-comment repairs, named rather than slipped in (same defect class, mechanical, evidence
  pinned by this very commit): packaged-permission-set-lock.ts and its test file both documented this
  fail-open as live on main. Left alone they would tell the next reader the opposite of the truth.
  Both are re-dated to "before buildExistingByName's UNSCOPED page cap truncates once a name can have more than one row — and a truncated page reads as "absent", which inserts #11518" and keep their argument, because what those controls actually
  pin outlives the repair: unscoped, buildExistingByName still answers with the FIRST row by id, so on
  a name several organizations hold it answers with somebody else's row — a different wrong answer to
  the same question, and one no page budget reaches. No assertion in that file changed.

Verification

Every exit code captured before any pipe; each gate quoted by its own verdict line. Union run at
cb9d109c25, the head commit of this branch.

The failing case the card handed over transplants.bootstrap-system-capabilities.test.ts's
makeQl double is the one that HONOURS limit and orders by id ascending (the two shipped-driver
behaviours the defect is made of), and its 8-curated-platform-rows + 2-organization-rows fixture is
reused directly. The test that pinned the defect — "WITHOUT the predicate the page also TRUNCATES, and
a truncated page reads as "absent"" — asserted the wrong outcome and is rewritten in place, with
the change flagged in its body as the repair rather than a weakened assertion. #11451's own argument is
preserved and sharpened: what the predicate buys, and what no page budget can reach, is which row
answers.

Reverse-verification. Prediction written before the run; seed-name-lookup.ts restored to its
origin/main blob by plain file write (never git checkout <ref> -- <path>, which stages the ablated
blob), under a trap … EXIT INT TERM restore. Mutation confirmed on disk by marker counts, not by
an editor exit code: limit: budget + 1 1 → 0, names.length * 2 : names.length 0 → 1.
No rebuild is involved and none is owed: the ablated subject is imported relatively
(./seed-name-lookup.js) from inside the same package, so vitest reads src/ — there is no
exports/dist hop for the mutation to miss.

Predicted RED: 5 named tests. Observed: exactly those 5, at exactly the predicted assertions.

test	predicted	observed
#11451 › WITHOUT the predicate the page hauls every organization's copy	names[6..7] read absent	studio.access: expected 'absent' to be 'present'
#11518 › reads every name whose row exists, in ONE round trip	absent === [names[6], names[7]]	expected [ 'studio.access', 'manage_sharing' ] to deeply equal []
#11518 › an overflowing page degrades to the per-item read — LOUDLY	silent truncation, names read absent	manage_org_users: expected 'absent' to be 'present'
#11518 › a SCOPED page that overflows that bound degrades too	status assertions still hold; the warn assertion fails	expected "vi.fn()" to be called 1 times, but got 0 times
#11518 › re-seeds a healthy multi-organization install WITHOUT writing anything	out.seeded === 2, two duplicate INSERTs	expected 2 to be +0

Tests 5 failed | 71 passed (76). Every control stayed green as predicted — both POSITIVE CONTROLs
(they pin the DOUBLE, so they hold on both sides), the unreadable-page diagnostic, and the scoped
exact-bound test. Restored and verified byte-identical: disk 0775e020d9… == index == HEAD, git status --porcelain empty.

The consequence measured on the seeder, not argued.bootstrap-declared-capabilities.test.ts's
double ignored limit entirely, which made this whole class of page-cap defect inexpressible in the
file where its consequence actually lands. It now honours limit with the #4363 id-ascending
tie-breaker, matching the sibling double. On a REBUILD over a healthy multi-organization install the
old code inserted two duplicate rows (out.seeded === 2); it now writes nothing.

Gates, each by its own verdict line:

• pnpm --filter @objectstack/plugin-security test — Test Files 80 passed (80) / Tests 1523 passed (1523), os-verify-lock: VERDICT command-exit 0
• pnpm --filter @objectstack/plugin-security typecheck — VERDICT command-exit 0
• ⭐ pnpm check:type-check-debt (the ratchet half, --re-measure, run on a built closure) —
  check-type-check-coverage --re-measure: OK — 32 ledger entr(ies) re-measured in 243.5s, 1898 raw tsc error(s) total, none above its recorded number.@objectstack/plugin-security is not among the
  drifted; the one reported surplus is @objectstack/plugin-approvals (−1, an entry that can be
  lowered), a package this PR does not touch. The ledger was not raised.
• pnpm check:type-check-coverage — OK — 65/78 workspace packages type-checked … 19 package(s) still hide their own tests
• pnpm check:engine-double-contract — OK — 405 pinned, 133 in the DEBT ledger, 2 exempt.
• pnpm check:where-matcher — 297 matcher(s) discovered, 297 answer the combinator battery correctly or refuse it loudly … none new.
• pnpm check:query-options-erasure — ratchet holds: 67 unswept non-test site(s) … none new · test surface: 240 site(s) … at the ceiling
• pnpm check:cross-package-test-inputs — OK: 16 package(s) read outside themselves, all declared
• pnpm check:test-source-alias — OK — 72 packages with tests scanned
• pnpm check:nul-bytes — OK (scanned 6655 text file(s) … no raw ASCII control bytes)
• pnpm check:i18n — OK (9 package(s) — all bundles in sync, no undeclared authoring keys).⚠️ its
  first run returned PREREQUISITE NOT MET — the workspace CLI is not built, which is not measured,
  never a pass; re-run green after the closure build.
• pnpm lint (the full repo scan, eslint . --no-inline-config) — VERDICT command-exit 0, so no
  narrowing is claimed here
• also green: check:published-files, check:slot-lookup, check:type-source-resolution,
  check:changeset-gate-self-tests, check:objectui-changeset, check-plugin-teardown-shape,
  check-ci-filter-parity, check-adr-0087-registration, check-changeset-no-major,
  check-empty-changeset, release-rehearsal-clone --self-test

Gate family derived with node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack
(gate list derived from the tree of 'objectstack-ai/objectstack' at commit cb9d109c25), not from a
recalled list.

Changeset: .changeset/seed-name-lookup-unscoped-page-budget.md (@objectstack/plugin-security: patch)
— the behaviour change is stated there too, since it is what a reader of the release notes needs.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

7 anchor(s) derived from 1 changed package(s); no hand-written page names any of them. ⚠️1 changed file(s) yielded no anchor (packages/plugins/plugin-security/src/packaged-permission-set-lock.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

What this run could not see

• 1 changed file(s) yielded no anchor (packages/plugins/plugin-security/src/packaged-permission-set-lock.ts) — pages documenting those are invisible to this run
• the SDK route bridge reached 45 of 222 client-bound route-ledger rows — the other 177 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run: 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 — 14 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 0140e678fa4771ea8330a9da075af96e1f8798bd → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 5bfa01440689d67350dea7af31d1adc675e5eb0d — the merge of head cb9d109c258aa6039df7482c9d983965245bb544 into base 0140e678fa4771ea8330a9da075af96e1f8798bd, 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 5bfa01440689d67350dea7af31d1adc675e5eb0d && git checkout 5bfa01440689d67350dea7af31d1adc675e5eb0d
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 0140e678fa4771ea8330a9da075af96e1f8798bd cb9d109c258aa6039df7482c9d983965245bb544 && git checkout -B drift-repro 0140e678fa4771ea8330a9da075af96e1f8798bd && git merge --no-ff cb9d109c258aa6039df7482c9d983965245bb544
node scripts/docs-audit/affected-docs.mjs --json 0140e678fa4771ea8330a9da075af96e1f8798bd

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

[os-sam]

Docs hand-read done — no page is falsified, and one page is un-falsified

PM note (domain:services seat). The drift check on this PR reported 7 anchors with no page naming them, plus ⚠️ one changed file yielding no anchor (packaged-permission-set-lock.ts) — and it says in terms that this is "not a clean bill of health." Its self-documented blind spot is that a page stating a rule by its inputs shares no identifier with the emitter, so an emitter-only diff can never list it. That blind spot is only closed by hand, so I closed it.

Method — pinned to a ref rather than a working tree (git grep … origin/main -- 'content/docs/**'), with a positive control (5 pages mention sys_capability on that ref, so the channel reaches the docs tree).

Result — two pages name this seeder's implementation directly, which the anchor set did not surface: content/docs/permissions/authorization.mdx:179 and content/docs/permissions/capabilities.mdx (lines 52, 67, 159).

⭐ The load-bearing one is capabilities.mdx:159:

bootstrapDeclaredCapabilities runs on kernel:ready and is idempotent: it re-seeds on every boot, so the row always reflects the shipped declaration.

That sentence was false on main, and this PR is what makes it true. On any install using ADR-0066 D1 — an admin extending the registry inside their own organization — the truncated page reported the package's own names absent and the seeder re-inserted them. This PR's own fixture says so in the assertion comment: "Before the repair this was seeded: 2 and two DUPLICATE rows for names whose package rows were sitting in the table — every boot." A seeder that writes two duplicate rows on every boot is not idempotent.

⇒ No docs edit is owed by this PR, and none should be added to it. The page already documents the intended contract correctly; the code was the half that disagreed. Worth recording because it is independent corroboration of severity from a source neither the card nor the implementation cited: the documentation asserted an invariant the read path had quietly stopped honouring, and nothing connected the two.

⚠️ On the file the bot could not anchor (packaged-permission-set-lock.ts): its diff here is docblock prose only — no behaviour — so no page can have gone false against it. The "not covered" warning is real in general and inert on this particular diff.

⛔ No action requested from the implementer. This is a review-side measurement, recorded so it is not re-derived.

---

Generated by Claude Code