fix(metadata-protocol, objectql, core): platform store reads and writes carry the explicit system opt-in

[objectstack-fleet]

Fixes #21911
Clause-②: no

• Each producer takes the explicit system opt-in that exists today. No gate before the hand-off fires on any of them, so nothing accepted or refused changes today.

This is a slice of #21908: the engine-lane producers of the principal-less hand-off. #21908 stays open, and it builds the deny itself once every producer has a route.

What changed

Every engine call in the card's functions now passes context: { isSystem: true }. Inside a SysMetadataRepository transaction it passes { ...ctx, isSystem: true }, so the transaction handle still rides along. This is the opt-in that already exists. There is no new API, no export change, and no change to what any door authorizes.

Row	Package	Function (engine calls moved)
1	metadata-protocol	findServedOverlayRow (1 findOne)
2	metadata-protocol	overlayLockLayerAt (1 find, in its store reader)
3	metadata-protocol	readActiveOverlayRows / queryByOrg (2 find), readFlattenedMetaItems (2 find, draft preview)
4	metadata-protocol	foldStoredCollection (1 find). These are the only reads assertRuntimeAuthoringRules issues.
5	metadata-protocol	SysMetadataRepository: get 1, put 6, delete 3, promoteDraft 1, restoreVersion 2, listDrafts 1, nextItemVersion 1, nextEventSeq 1
6	metadata-protocol	recordMetadataAudit (insert), persistPackageCommitRow (insert), publishPackageDrafts, resolveOverlayPackageBinding, storedFlowBindingAgrees, deletePackage, duplicatePackage (1 read each), reassignOrphanedMetadata (find + update)
9	objectql	ObjectQLPlugin.readAuthoredActionRows (3 find), readAuthoredHookRows (2 find)
10	core	readAuthoredTranslationLayer (2 find)

H1 holds: every row sits where the card says on cab63967. Every engine call in each named function was enumerated with the TypeScript AST, not only the first one: 32 in metadata-protocol, 5 in objectql and 2 in core. Each now carries the opt-in.

The six gates: none fires on these calls (Zone 1)

A system context skips the six gates the middleware still runs before the hand-off's next(). Each one, on the sys_metadata family (sys_metadata, _history, _audit, _commit):

• package-managed: acts only on sys_permission_set.
• system-row: acts only on sys_position and sys_capability.
• curated-capability: acts only on sys_capability.
• audience-anchor: acts only on sys_position_permission_set.
• engine-owned: the bucket matches (the family is engine-owned / append-only), but isUserContextWrite needs a userId. A context with no principal passes it by construction, exactly as a system one does.
• delegated-administration: acts only on the RBAC link tables and sys_member.

Measured. A local, uncommitted instrument sat at plugin-security's engine middleware. It wrapped each of the six gates, so a throw was recorded per gate and per operation. It also recorded the outcome after the hand-off. After the change it dry-ran the six gates for every moved isSystem call, with the flag cleared. The run covered the dogfood suite and a booted showcase dev composition.

• Before: 0 gate throws on any of 35,248 (dogfood) + 388 (boot) principal-less operations, from any producer. 0 downstream failures on the card's functions.
• After: 0 gates would fire on any moved call.

The instrument was reverted, and security-plugin.ts equals its HEAD blob (5b4ab280). plugin-security's dist/ was rebuilt clean, and ablation-dist-preflight --absent passed.

Before and after, per function (H2)

Principal-less, non-system operations credited to each function. A function is credited when it is the first frame past the engine, its closures and the repository transaction wrapper.

Function	dogfood before → after	boot before → after
findServedOverlayRow	13,614 → 0	80 → 0
overlayLockLayerAt	13,736 → 0	80 → 0
queryByOrg (readActiveOverlayRows)	2,037 → 0	16 → 0
readFlattenedMetaItems draft preview	0 → 0 (no run reached it; unit-pinned)	0 → 0
foldStoredCollection	761 → 0	0 → 0
SysMetadataRepository.get / put / delete	169 / 296 / 41 → 0	0
promoteDraft / restoreVersion / listDrafts	6 / 2 / 1 → 0	0
nextItemVersion / nextEventSeq	105 / 105 → 0	0
recordMetadataAudit / persistPackageCommitRow	110 / 1 → 0	0
publishPackageDrafts / resolveOverlayPackageBinding / storedFlowBindingAgrees	1 / 1 / 6 → 0	0
deletePackage / duplicatePackage / reassignOrphanedMetadata	1 / 1 / 2 → 0	0
readAuthoredActionRows / readAuthoredHookRows	810 / 496 → 0	3 / 2 → 0
readAuthoredTranslationLayer	496 → 0	2 → 0
all principal-less operations, any producer	35,248 → 2,476	388 → 204

After the change, the same calls arrive as isSystem operations in matching numbers. For example: findServedOverlayRow 13,618, queryByOrg 2,037, put 296, recordMetadataAudit 110. The dogfood suite was green on both sides with identical counts: 205 files passed + 1 skipped, 1,590 tests passed + 9 skipped. The boot answered the same statuses on both sides: admin data reads 200, anonymous reads 401. The 2,476 / 204 operations that remain come from the other slices' producers (settings, messaging, storage, auth, webhooks, datasource).

Tests

• Unit pins, one per package (H4):
  • metadata-protocol/src/protocol.platform-store-system-opt-in.test.ts: the engine double records the context of every call. It drives draft save → publish → active save → rollback → delete, the overlay and list reads (each private reader directly, too), and reassign / duplicate / uninstall. Each step asserts that it reached the store and that every call carried isSystem: true. Inside the transaction the context is exactly { transaction, isSystem: true }.
  • objectql: plugin-authored-actions.test.ts and plugin-authored-hooks.test.ts each gain one case.
  • core: authored-translation-sync.test.ts gains one case.
• Ablations, each committed first and restored through scripts/ablation-replace.mjs (blob equals HEAD, git diff HEAD empty). Each pin resolves its subject from src, so no dist leg was needed. The expected direction was red, and red is what was observed:
  1. findServedOverlayRow opt-in dropped: 2 of 3 metadata-protocol cases red.
  2. put's history-insert opt-in reverted to { context: ctx }: 2 of 3 red.
  3. readAuthoredHookRows' first read set to isSystem: false: 1 of 11 red.
  4. readAuthoredTranslationLayer's first read set to isSystem: false: 1 of 6 red.
  • The first attempt at 3 and 4 used a replacement that was a prefix of its anchor. The tool refused it as a no-op and nothing ran. They were re-run with the false spelling.
• Package suites (H4 falsified test-side; see the acceptance notes), at 89ced04af3. The merge to 9fd7113eaa brought only two docs pages and one rest test:
  • metadata-protocol: 217 files passed + 3 skipped, 27,921 tests passed.
  • objectql (local + repo): 376 files, 7,476 tests passed.
  • core: 80 files, 2,226 tests passed.
  • typecheck for all three exit 0, including objectql's and core's check:test-typecheck.
• Instrumented runs: the dogfood suite (7 chunks, 206 files) and a booted showcase dev composition, before and after, all under os-verify-lock. The numbers are in the table above.
• Gates: dispatch-gates --commands at 9fd7113eaa derives 76 families. All 76 were run there and exited 0, and --ran reconciles 76 derived, 76 run, 0 NOT-MEASURED.
  • check:engine-split-ratio first refused on the shallow clone. It was deepened (--shallow-since=2026-06-30) and re-run.
  • check:dual-build-cjs-loads first needed dists of unbuilt packages and a plugin-audit declaration. These were built, and the gate re-ran green.
  • check:objectql-double-limit flagged the new double as limit-blind. The double now applies the caller's bound.
• Lint, a proven narrowing (CI runs the full pnpm lint):
  1. The population comes from eslint.config.mjs: **/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs} plus the packages/** object.
  2. eslint --no-inline-config --format json over the 13 changed .ts files: 13 files, 0 errors, 0 warnings.
  3. The config never enables type-aware linting (no parserOptions.project, no typed rules), so this diff cannot move any untouched file's verdict.

Acceptance notes

• Same family, not moved here (static, not in the card's list): SysMetadataRepository.getByHash, list, history and replayFromHistory still reach the engine with no context. No measured run reached them (0 records in either probe). They belong to security(spec, plugin-security): the AI tool contract says a context with no caller runs "RLS-on, sees-nothing", but plugin-security hands a principal-less context straight through, and on a hosted kernel it read and wrote more than a member may #21908's closure census.
• One engine check besides the six gates also stands down under isSystem: the referential-integrity check on a caller-supplied lookup. On these writes the only lookup it judged was sys_metadata.organization_id, which the repository fills from the door-derived organization. The probe recorded 0 refusals from it (0 downstream failures on the card's functions). The other isSystem reads on the census page touch none of these four objects, or only change a log line (the tenant-audit warning, the reference-cleanup actor label).
• H4 was falsified, and the fix is test-side only: objectql's protocol suites held seven exact-argument expectations, the reassign rebind and the listDrafts WHERE. Each now includes the opt-in. Two revert/rollback conflict pins (protocol-commit-history, protocol-writepath-object-ownership) found put's in-transaction read by a bare context key, and every repository read now carries one. Their engine now hands its transaction callback a handle, as ObjectQL.transaction does, and the pin discriminates on that handle. metadata-protocol's and core's own suites passed unchanged.
• scripts/engine-double-contract.pinned.json gains three rows (--write, a grow-only coverage ledger) for the new pin's double. That double is copied from the pinned one in protocol-publish-drafts-org-scope.test.ts.
• Probe artifact: after the change, the isSystem count for overlayLockLayerAt reads 10. This is not because its reads vanished. The function is not async, so it does not appear in the async stack the probe filtered system records by. Its principal-less count (the claim) is 0 on both runs.
• H5: fix(rest,metadata-protocol): a public form's intake withdrawal at any metadata layer holds; layering can only narrow intake #21864's head (d8657b5c, re-tested after every merge of main) test-merges cleanly onto this branch at 9fd7113eaa. Its hunks are in anonymousFormIntakeOrgScopeRefusal, saveMetaItem and promoteDraftForPublish, and none of them is a named function here. All 16 protocol calls keep the opt-in in the merged tree.
• H6: the cross-lane declaration is on [PM seat] domain:engine — 🟢 os-project-manager · session_017ErfyP2Rx7XWHJA27QjyUi #6367 (6003826474).
• H3: the isSystem census page needs no edit. Object-literal producers are not elevation reads, and the census gate is green with its counts unchanged.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 3 package(s): @objectstack/core, @objectstack/metadata-protocol, @objectstack/objectql, touching 23 documentable anchor(s).

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

• content/docs/api/error-catalog.mdx (via sys_metadata (literal, a string literal in SysMetadataRepository; a string literal in deletePackage; a string literal in duplicatePackage; a string literal in findServedOverlayRow; a string literal in put; a string literal in readActiveOverlayRows; a string literal in readFlattenedMetaItems; a string literal in reassignOrphanedMetadata))
• content/docs/api/index.mdx (via sys_metadata (literal, a string literal in SysMetadataRepository; a string literal in deletePackage; a string literal in duplicatePackage; a string literal in findServedOverlayRow; a string literal in put; a string literal in readActiveOverlayRows; a string literal in readFlattenedMetaItems; a string literal in reassignOrphanedMetadata))
• content/docs/automation/flows.mdx (via sys_metadata (literal, a string literal in SysMetadataRepository; a string literal in deletePackage; a string literal in duplicatePackage; a string literal in findServedOverlayRow; a string literal in put; a string literal in readActiveOverlayRows; a string literal in readFlattenedMetaItems; a string literal in reassignOrphanedMetadata))
• content/docs/concepts/metadata-lifecycle.mdx (via SysMetadataRepository (symbol, a top-level class), sys_metadata (literal, a string literal in SysMetadataRepository; a string literal in deletePackage; a string literal in duplicatePackage; a string literal in findServedOverlayRow; a string literal in put; a string literal in readActiveOverlayRows; a string literal in readFlattenedMetaItems; a string literal in reassignOrphanedMetadata))
• content/docs/data-modeling/drivers.mdx (via sys_metadata (literal, a string literal in SysMetadataRepository; a string literal in deletePackage; a string literal in duplicatePackage; a string literal in findServedOverlayRow; a string literal in put; a string literal in readActiveOverlayRows; a string literal in readFlattenedMetaItems; a string literal in reassignOrphanedMetadata))
• content/docs/data-modeling/objects.mdx (via sys_metadata (literal, a string literal in SysMetadataRepository; a string literal in deletePackage; a string literal in duplicatePackage; a string literal in findServedOverlayRow; a string literal in put; a string literal in readActiveOverlayRows; a string literal in readFlattenedMetaItems; a string literal in reassignOrphanedMetadata))
• content/docs/deployment/cli.mdx (via sys_metadata (literal, a string literal in SysMetadataRepository; a string literal in deletePackage; a string literal in duplicatePackage; a string literal in findServedOverlayRow; a string literal in put; a string literal in readActiveOverlayRows; a string literal in readFlattenedMetaItems; a string literal in reassignOrphanedMetadata))
• content/docs/deployment/environment-variables.mdx (via sys_metadata (literal, a string literal in SysMetadataRepository; a string literal in deletePackage; a string literal in duplicatePackage; a string literal in findServedOverlayRow; a string literal in put; a string literal in readActiveOverlayRows; a string literal in readFlattenedMetaItems; a string literal in reassignOrphanedMetadata))
• content/docs/deployment/validating-metadata.mdx (via sys_metadata (literal, a string literal in SysMetadataRepository; a string literal in deletePackage; a string literal in duplicatePackage; a string literal in findServedOverlayRow; a string literal in put; a string literal in readActiveOverlayRows; a string literal in readFlattenedMetaItems; a string literal in reassignOrphanedMetadata))
• content/docs/kernel/cluster.mdx (via sys_metadata (literal, a string literal in SysMetadataRepository; a string literal in deletePackage; a string literal in duplicatePackage; a string literal in findServedOverlayRow; a string literal in put; a string literal in readActiveOverlayRows; a string literal in readFlattenedMetaItems; a string literal in reassignOrphanedMetadata))
• content/docs/kernel/contracts/metadata-service.mdx (via sys_metadata (literal, a string literal in SysMetadataRepository; a string literal in deletePackage; a string literal in duplicatePackage; a string literal in findServedOverlayRow; a string literal in put; a string literal in readActiveOverlayRows; a string literal in readFlattenedMetaItems; a string literal in reassignOrphanedMetadata))
• content/docs/kernel/services-checklist.mdx (via sys_metadata (literal, a string literal in SysMetadataRepository; a string literal in deletePackage; a string literal in duplicatePackage; a string literal in findServedOverlayRow; a string literal in put; a string literal in readActiveOverlayRows; a string literal in readFlattenedMetaItems; a string literal in reassignOrphanedMetadata))
• content/docs/permissions/authorization.mdx (via sys_metadata (literal, a string literal in SysMetadataRepository; a string literal in deletePackage; a string literal in duplicatePackage; a string literal in findServedOverlayRow; a string literal in put; a string literal in readActiveOverlayRows; a string literal in readFlattenedMetaItems; a string literal in reassignOrphanedMetadata))
• content/docs/permissions/permission-sets.mdx (via sys_metadata (literal, a string literal in SysMetadataRepository; a string literal in deletePackage; a string literal in duplicatePackage; a string literal in findServedOverlayRow; a string literal in put; a string literal in readActiveOverlayRows; a string literal in readFlattenedMetaItems; a string literal in reassignOrphanedMetadata))
• content/docs/plugins/packages.mdx (via sys_metadata (literal, a string literal in SysMetadataRepository; a string literal in deletePackage; a string literal in duplicatePackage; a string literal in findServedOverlayRow; a string literal in put; a string literal in readActiveOverlayRows; a string literal in readFlattenedMetaItems; a string literal in reassignOrphanedMetadata))

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

• content/docs/releases/implementation-status.mdx (via sys_metadata (literal, a string literal in SysMetadataRepository; a string literal in deletePackage; a string literal in duplicatePackage; a string literal in findServedOverlayRow; a string literal in put; a string literal in readActiveOverlayRows; a string literal in readFlattenedMetaItems; a string literal in reassignOrphanedMetadata))
• content/docs/releases/v16.mdx (via sys_metadata (literal, a string literal in SysMetadataRepository; a string literal in deletePackage; a string literal in duplicatePackage; a string literal in findServedOverlayRow; a string literal in put; a string literal in readActiveOverlayRows; a string literal in readFlattenedMetaItems; a string literal in reassignOrphanedMetadata))
• content/docs/releases/v17/17-0.mdx (via deletePackage (symbol, a method of class ObjectStackProtocolImplementation), sys_metadata (literal, a string literal in SysMetadataRepository; a string literal in deletePackage; a string literal in duplicatePackage; a string literal in findServedOverlayRow; a string literal in put; a string literal in readActiveOverlayRows; a string literal in readFlattenedMetaItems; a string literal in reassignOrphanedMetadata))
• content/docs/releases/v17/17-1.mdx (via publishPackageDrafts (symbol, a method of class ObjectStackProtocolImplementation))
• content/docs/releases/v17/17-3.mdx (via sys_metadata (literal, a string literal in SysMetadataRepository; a string literal in deletePackage; a string literal in duplicatePackage; a string literal in findServedOverlayRow; a string literal in put; a string literal in readActiveOverlayRows; a string literal in readFlattenedMetaItems; a string literal in reassignOrphanedMetadata))
• content/docs/releases/v17/17-5.mdx (via sys_metadata (literal, a string literal in SysMetadataRepository; a string literal in deletePackage; a string literal in duplicatePackage; a string literal in findServedOverlayRow; a string literal in put; a string literal in readActiveOverlayRows; a string literal in readFlattenedMetaItems; a string literal in reassignOrphanedMetadata))
• content/docs/releases/v17/17-6.mdx (via sys_metadata (literal, a string literal in SysMetadataRepository; a string literal in deletePackage; a string literal in duplicatePackage; a string literal in findServedOverlayRow; a string literal in put; a string literal in readActiveOverlayRows; a string literal in readFlattenedMetaItems; a string literal in reassignOrphanedMetadata))

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 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 — 39 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 9e33ee7c5936e35a38158a7f9fdbcbd4445797a8 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 0808399c1e87cca260c86c2580a12189b0894a70 — the merge of head 58ac17e71fec4921c7cab56958a6f3e2be500758 into base 9e33ee7c5936e35a38158a7f9fdbcbd4445797a8, 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 0808399c1e87cca260c86c2580a12189b0894a70 && git checkout 0808399c1e87cca260c86c2580a12189b0894a70
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 9e33ee7c5936e35a38158a7f9fdbcbd4445797a8 58ac17e71fec4921c7cab56958a6f3e2be500758 && git checkout -B drift-repro 9e33ee7c5936e35a38158a7f9fdbcbd4445797a8 && git merge --no-ff 58ac17e71fec4921c7cab56958a6f3e2be500758

node scripts/docs-audit/affected-docs.mjs --json 9e33ee7c5936e35a38158a7f9fdbcbd4445797a8

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

[objectstack-fleet]

CI note from domain:services seat 1: the red Lint & Repo Gates at 9fd7113eaa is not this PR's

• Failing check: Lint & Repo Gates (job 112078665316), step check:pm-dispatch-gates. One self-test case of 1976 fails: "no mkdtempSync site in this tree takes a base the scan cannot read — UNRESOLVED: packages/qa/dogfood/test/per-file-cwd.setup.ts:60". This PR touches no file there.
• Why it is not this PR's: the site came from test(dogfood): every test file runs in its own temporary working directory #21919 (be97cf3c93), which this branch inherits from main, and main is red on the same case (Lint & Repo Gates at 9dce635337).
• The fix exists: PR test(dogfood): each file's temporary cwd is created from a base the scratch-dir scan can read #21935 (hourly full run: red on main (Lint & Type Check) #21924) makes that temporary directory's base readable to the scan. It is green and in the merge queue. When it lands, this branch merges origin/main (a merge commit) and CI runs again on the combined head. That is the same change test(dogfood): each file's temporary cwd is created from a base the scratch-dir scan can read #21935 makes, taken through the base rather than copied into this PR's packages/qa files.

---

Generated by Claude Code