`bootstrapSystemCapabilities` still reads `sys_capability` one name at a time — and it, not the declared seeder, is the loop whose size is the union of every `systemPermissions` string

[os-sam]

Found while implementing #11096 + #11097 (batching the declared-capability seed and the env overlay reconciler). This is the seeder next door, and it was not in either card's scope.

The shape

packages/plugins/plugin-security/src/bootstrap-system-capabilities.ts:

• the definition set is built in memory first — curated KNOWN_CAPABILITIES (line ~326), then every systemPermissions[] string across every seeded permission set that is not already curated or already materialized (lines ~332-338);
• then one loop over that set (line ~347) issues a per-item existence read: const existing = await tryFind(ql, 'sys_capability', lookup, 1) (line ~356);
• and the curated half's reconcile is an UPDATE (line ~497) that fires whether or not label/description differ from what is stored.

Same shape as the two loops #10946 measured at slope 4.0000 / R² = 1.000000, and the same shape #11096 has just removed from bootstrapDeclaredCapabilities.

Why this is worth its own card

⚠️ The cost argument on #11096 actually describes THIS loop. #11096 said the capability count "is the union of every capability every package declares, which is typically larger than either axis #10946 measured" — but bootstrapDeclaredCapabilities iterates stack.capabilities, i.e. only the EXPLICIT defineCapability declarations. The union-of-systemPermissions set is the one built here, at lines 332-338. So the larger of the two capability loops is the one still unbatched.

Both run on every kernel:ready, back to back (security-plugin.ts ~3209 then ~3218).

Why it is not a mechanical copy of #11096

⛔ The two halves do not share a lookup key, which is exactly the exclusion that makes buildExistingByName non-reusable as-is here:

const lookup = isDerived
 ? { name: def.name }
 : { name: def.name, managed_by: 'platform', organization_id: null };

buildExistingByName (seed-name-lookup.ts) answers "does a row exist for this NAME", optionally scoped to one organization. The curated half asks a narrower question — the platform's own organization-less row for this name — and that narrowing is load-bearing: #8470 put it there precisely because an unqualified find(..., limit: 1) has no ORDER BY and could reconcile an arbitrary organization's row, leaving the platform's own row unseeded.

So batching this needs a real design step, one of:

1. two batched reads (one per half) with the curated half post-filtering on managed_by/organization_id in memory — cheap, but it reads rows the current query never returns;
2. extending seed-name-lookup.ts to carry an extra equality predicate alongside the $in — a shared file that three seeders now depend on, so widening it is not a drive-by;
3. leaving the derived half per-item and batching only the curated half, whose size is fixed by KNOWN_CAPABILITIES — which optimizes the half that does not grow.

Option 1 or 2 look right; the choice should be made deliberately, not inside another card's PR.

Not measured

The slope of this axis has not been measured. The hosted bootstrap-curve.mjs rig lives in objectstack-ai/cloud and its axes are permission sets / positions / objects. What is established here is the code shape, by reading, plus the round-trip counts #11096 pinned for the sibling seeder in bootstrap-seed-round-trips.test.ts — the natural home for a pin on this one too.

Refs #11096 · #10946 (the precedent and the buildExistingByName machinery) · #8470 (why the curated lookup is narrowed) · objectstack-ai/cloud#1555 (the 20s request budget)

[claude]

Triage (daily round, session session_01Kktexqp6uVuFMztvvTMf3V, 2026-08-24): lands in plugin-security/bootstrap-system-capabilities.ts → domain:services + pm:queue, Task. Mechanical batching per the #11096/#10946 established pattern (the card shows the cost argument on #11096 actually describes this loop). Serial note: verify #11096/#11097 PRs are landed; reuse their batching shape.

---

Generated by Claude Code

[os-sam]

Claimed by the domain:services execution seat — PM session session_01APWX2AwT3a4xDcjPCe8bk4, branch claude/issue-11451-batch-bootstrap-system-capabilities. Now pm:dispatched.

Serial precondition from triage is satisfied: PR #11470 (cards #11096 + #11097) is merged, so the batched $in read, the equality-gated writes, seed-name-lookup.ts's buildExistingByName, and the bootstrap-seed-round-trips.test.ts pins are all on main. The dev branches from a tree containing the shape it is asked to extend.

Dispatch fences carried to the dev:

• The card names three design options and says the choice should be made deliberately, not inside another card's PR. That choice is in scope for this card — but it must be written down before the code, with the reason, and the PR must state which option was taken and why the other two were not.
• ⛔ Option 2 widens seed-name-lookup.ts, which three seeders now depend on. If option 2 is chosen, every existing caller must be shown unaffected by measurement, not by inspection — and the #8470 narrowing (the platform's own organization-less row) must be shown still load-bearing, not merely still present.
• ⛔ Do not move or relax any round-trip pin to make a number fit. bootstrap-seed-round-trips.test.ts is the ratchet; a pin that has to move is a finding to report, not a line to edit.
• ⛔ No packages/spec/** edits.
• The card is explicit that the slope of this axis has not been measured and that the hosted rig lives in objectstack-ai/cloud. Do not claim a measured speedup. The defensible claim is the round-trip count, pinned in-repo — nothing more.

---

Generated by Claude Code

[os-sam]

{
 "issue": 11451,
 "status": "done",
 "branch": "claude/issue-11451-batch-bootstrap-system-capabilities",
 "pr": "https://github.com/objectstack-ai/objectstack/pull/11537",
 "premise_still_valid": true,
 "summary": "Premise re-verified on origin/main (c2dd951474) before any code: the per-item `tryFind(ql,'sys_capability',lookup,1)` and the unconditional `tryUpdate` were both still there; searches for '11451' across issues and PRs (title and body, not closed_by_pull_requests) returned zero prior work. DESIGN CHOICE, written down before the code and preserved in the module header: option 2's MECHANISM (seed-name-lookup.ts gains an optional equality predicate carried alongside the $in) applied to the CURATED half only. The card's three options conflate two questions — how to batch a predicated read (1 vs 2) and which halves to batch (3) — so the honest answer is option 2's mechanism at option 3's scope, with the scope reason written down. Option 1 rejected on three measured//structural grounds: it returns the WRONG row (an org row, not the platform's), it TRUNCATES (unscoped page cap is names.length while post-#8461 a name can carry a row per organization), and it would not even avoid widening the shared file (get() returns one row by arrival order, so filtering needs an all-rows accessor — the two-spellings shape #10103 repaired). The derived half is NOT batched, and not because it is smaller — it is the half that grows: its lookup is cross-organization by construction and derivedRowIsOurs/skippedAuthored/#8751's platformStampedInOrg all derive from the lowest-id row installation-wide, so narrowing it stops counting a real anomaly and starts seeding the bucket in the case #8552 ruled must be left alone; batching it unnarrowed needs an unbounded read. Filed as #11520 (sub-issue of #11451) rather than decided. Also in scope and done: the unconditional UPDATE is equality-gated, which sits after the derived-ownership guard and so removes write round trips from BOTH halves. CapabilitySeedResult gains `unchanged` and `unreadable`; an unreadable database now declines instead of attempting an insert per curated name and reporting a blockedCurated collision nobody ever saw. PR is `Part of #11451`, not `Fixes` — the derived half remains; body verified to contain ZERO closing keywords so nothing silently closes 11451/11518/11520 on merge.",
 "tests": "All at 968f91714c, the head of the branch. (1) `tsc --noEmit` for @objectstack/plugin-security -> TSC_EXIT=0. (2) vitest over all four buildExistingByName callers' suites plus both capability suites -> 'Test Files 6 passed (6) · Tests 189 passed (189)'; 12 new tests confirmed present and green by name in a --reporter=verbose run. (3) `pnpm lint` repo-wide (eslint . --no-inline-config) -> exit 0, no findings — the whole farm, NOT a narrowed run. (4) Gate union re-derived with `node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack` (no paths passed; script confirmed the --repo assertion holds); all green, each quoted from the gate's own verdict line: engine-double-contract 'OK — 390 pinned, 133 in the DEBT ledger, 2 exempt'; test-source-alias 'OK — 72 packages with tests scanned'; cross-package-test-inputs 'OK: 14 package(s) read outside themselves, all declared'; query-options-erasure '✓ ratchet holds: 67 unswept non-test site(s), none new'; slot-lookup '✓ ratchet holds: 107 unswept site(s), none new'; type-check-coverage 'OK — 65/78 workspace packages type-checked'; plus changeset-gate-self-tests, objectui-changeset, published-files, type-source-resolution, ci-filter-parity, plugin-teardown-shape, nul-bytes, adr-0087, no-major, empty-changeset all exit 0. NOTE: three of my first invocations exited 1 on MODULE_NOT_FOUND — my own wrong filenames, not red gates; re-run via their real `pnpm check:*` commands. (5) check:type-check-debt needs the whole workspace built, so its ledger entry was reproduced directly instead: tsc --noEmit with the **/*.test.ts exclusion lifted reports exactly 11 raw errors, matching TEST_DEBT['@objectstack/plugin-security'], and NONE of the 11 diagnostics names a file this PR touches — so the ratchet cannot move. This mattered: the package tsconfig excludes **/*.test.ts (verified with --listFiles: 0 hits for the two test files I edited), so the clean package typecheck says nothing about the new test code. Probe tsconfig removed, tree verified clean. ABLATION (fence: the #8470 narrowing must be shown load-bearing, not merely present): CURATED_LOOKUP relaxed to {}. Mutation confirmed ON DISK in both directions by anchored grep (injected form x1, removed predicate body x0) — the python replace also asserted its anchor matched exactly once, so a zero-hit edit could not pass as a run. No rebuild interposed: the suites resolve the seeder through a RELATIVE import, not a package exports map, so nothing resolves from dist. Direction PREDICTED IN WRITING first (RED, more failures) and observed exactly: 85 passed unmutated -> 9 failed ablated — seven named [#8470] tests including 'reconciles the platform row and only the platform row (adverse — the org row sorts FIRST)' and 'is unaffected by the NUMBER of organizations holding the name', plus my new 'the seeder itself is unharmed by the fixture that breaks the unpredicated read' and 'the batched read carries the #8470 predicate IN the query, with no other keys'. The two tests calling buildExistingByName directly use a test-local literal and stayed green, as intended. RESTORE LEG: the trap's `git checkout` ran from the wrong cwd and DID NOT restore — caught because its own `git hash-object` echoed EMPTY. Restored by hand from the repo root and verified byte-identical (382ee3d6458e864cc81e8745ccdad57734bc88a5 == the HEAD blob), `git status` clean. Had I trusted the trap, every later measurement would have been taken on a mutated tree. NOT MEASURED: no speedup and no slope — the hosted bootstrap-curve.mjs rig is in objectstack-ai/cloud and its axes are permission sets/positions/objects, not this one; nothing here measures wall time. Also not measured: real-driver behaviour — every number comes from in-memory doubles. One verify-lock attempt returned exit 99 / queue-timeout (540s, holder named); recorded as NOT MEASURED and re-run to a real verdict, never read as a pass.",
 "open_questions": [
 {
 "question": "Should the DERIVED half's per-item cross-organization read be batched, and at what cost? It is the half that grows (the union of every systemPermissions[] string), but its counters are computed from the lowest-id row installation-wide, so no bounded read reproduces it. Full analysis in #11520.",
 "options": [
 "A — truncation-detecting batched read: read {name:{$in}} with a generous cap and, when the page comes back full, treat it as 'could not answer' and degrade to per-item, reusing the machinery readNamePage already has for a driver without $in. Bounded and behaviour-preserving (a complete page holds every row for every name, so the first row per name IS the lowest-id row). Costs new machinery in a file four callers share, and overlaps #11518.",
 "B — bucket-scoped batched read ({name:{$in}, organization_id:null}): cheapest and provably a singleton per name, but it stops counting #8751's platformStampedInOrg whenever our own bucket row also exists, and it starts seeding the platform bucket in the case #8552 explicitly ruled must be left alone. Needs a maintainer ruling on both.",
 "C — leave it per-item. Note the derived set is EMPTY on a stock installation: the platform's own permission sets grant only names already in KNOWN_CAPABILITIES, and package-declared names are excluded via materializedCapabilityNames. It grows only for an app whose defaultPermissionSets grant capability strings nothing declares."
 ],
 "recommendation": "A, folded into #11518 rather than done twice — and only if #11518 is being repaired anyway. Until then C is defensible on its own: the growth axis is real but the stock cost is zero, and both A and B spend either a shared file's complexity or a maintainer ruling to buy it. B should not be taken quietly — it reverses part of #8552 by way of a read shape."
 }
 ],
 "out_of_scope_findings": [
 "filed as #11518: buildExistingByName's UNSCOPED page cap (limit: names.length) truncates once a name can carry more than one row — which #8461/ADR-0120 D1 made reachable — and a truncated page reads as 'absent', which inserts. Live on main for the two callers that read unscoped: bootstrapDeclaredCapabilities and permission-set-projection. #10103 already applied this exact repair to the SCOPED arm only. Demonstrated by a test on this branch.",
 "filed as #11520 (sub-issue of #11451): the derived half of bootstrapSystemCapabilities is still per-item, and batching it trades away #8751's platformStampedInOrg signal or reverses part of #8552 — a ruling, not a refactor. Carries the options above so the next attempt does not re-derive them."
 ]
}

---

Generated by Claude Code