fix(runtime): the artifact boot has one registrar for its security collections — the door (#12892 step 2)

[os-trump]

Fixes #12892

Step 2 of the maintainer's two-step ruling (2026-08-29, quoted in the step-1 claim): step 1 — the door covers capabilities — landed in PR #13125; this PR is step 2. AppPlugin stops registering the four artifact security collections (positions / permissions / capabilities / sharingRules; policies was retired from both maps by PR #13009) on the ARTIFACT boot, so the artifact door is that boot's single registrar — preceded by the census below of every non-artifact-boot path that depends on AppPlugin's ADR-0057 SECURITY_FIELDS block, and stating per path who registers after this change. Option 3 (two permanent writers with matched shapes) ends here, as the ruling required.

What was measured before deciding

• The door (MetadataPlugin._parseAndRegisterArtifact) strict-parses, forward-converts and ADR-0010-stamps; AppPlugin's block forward-converts only. On a real artifact boot AppPlugin starts last, so its copy won: the sharing-rule condition a consumer read from metadata.list('sharing_rule') was a bare STRING (the door's copy carries { dialect: 'cel', source }), and a capability carried no scope default and no _packageVersion. Reproduced in this PR's real-boot CONTROL case (below), not inferred.
• The door throws on a present-but-unparseable artifact (_loadFromLocalFile swallows only ENOENT on the optional path), so on the artifact boot either the door registers every collection or the boot dies — there is no partial-door state that this removal could widen into a silent hole.
• AppPlugin's metadata:reloaded subscriber seeds new objects only; the ADR-0057 block is AppPlugin's ONLY registration site for these kinds. On an artifact HMR reload the door re-registers and its copy already overwrote AppPlugin's before this change — the boot-time copy was the one exception, and it is gone now.

The change

• AppPlugin takes securityMetadataRegistrar: 'app-plugin' | 'artifact-door' in its constructor opts (default 'app-plugin', a public readonly field). Under 'artifact-door' the ADR-0057 block registers nothing and logs one debug line naming the collections left to the door; an unknown value is refused loudly at construction instead of falling into either silent branch.
• createStandaloneStack — the ONE composition in this repo that runs the door (MetadataPlugin({ artifactSource: { path: artifactPath } })) over the same artifact it hands AppPlugin — declares 'artifact-door' on that AppPlugin. Nothing else changes; SECURITY_FIELDS stays enumerated (the check:stack-collection-maps eighth site) and only the registration around it became conditional.
• The #12878 divergence pins are rewritten to pin the unified state (red-first evidence below); a real-boot test with a pre-step-2 control and a composition pin are added.

The boot-path discriminator, and why it is a declaration

Zone 2 asked for the existing signal before inventing one. Measured on origin/main:

• AppPluginProjectContext.source is 'package' | 'user' — app provenance for the ADR-0010 stamp, not boot shape; overloading it would misroute the stamp.
• loadArtifactBundle returns bare parsed JSON; with unwrapEnvelope: true (what the standalone stack passes) the bundle is byte-for-byte a defineStack()-shaped definition. No marker survives that AppPlugin could read, and stamping one there would equate "read from an artifact file" with "the door runs on this boot" — true in every composition this repo contains, unverifiable for compositions it cannot see (the cloud stack composes its own kernel; loadArtifactBundle is a public export). A stamp fails SILENT in the wrong composition (zero registrars, a boot that stays green — measured at step 1); the declaration fails SAFE (two copies, today's state).
• MetadataPlugin's artifactSource is a private option of another plugin; reading it needs a door change (fenced: engine lane) or a reach into another plugin's internals.
• Reading the registry at AppPlugin.start() ("has the door already registered these?") turns the decision on start ORDER — the dependence the ruling removes — and is the startup-registry-verdict shape AGENTS.md forbids (no declared ordering between com.objectstack.metadata and AppPlugin; the standalone list order is positional).

So the option is declared where the two facts that make it true sit 20 lines apart (standalone-stack.ts), named for the door it defers to rather than for the boot shape, and pinned on the factory's real output (standalone-stack.test.ts: the composed AppPlugin carries 'artifact-door' AND the composed MetadataPlugin reads the same artifactPath).

Census — every path that depends on SECURITY_FIELDS, and who registers after this PR

Two registries hold copies of these declarations on a full boot, and the readers pick differently: the ObjectQL SchemaRegistry (filled by AppPlugin.init() → manifest.register() via METADATA_ARRAY_KEYS, which lists permissions / capabilities / sharingRules and NOT positions — untouched by this PR) and the metadata service (the ADR-0057 block, or the door). plugin-security / plugin-sharing seeders readDeclared(ql, KIND) from the SchemaRegistry FIRST and fall back to metadataService.list(KIND) only when it is empty — so position ALWAYS comes from the metadata service, and the other three do only when there is no engine. The permission evaluator (resolvePermissionSets), GET /meta/KIND and Studio read the metadata service directly.

#	Boot path (composition site)	AppPlugin bundle	Door composed on this boot?	Metadata-service registrar of the four kinds AFTER this PR	Readers on this boot	Changed?
1	createStandaloneStack (packages/runtime/src/standalone-stack.ts) — reached by os serve / os dev / os start in standalone mode (serve.ts boot-mode dispatch), createDefaultHostConfig (artifact fallback and empty os start), os migrate plan/apply (schema-migrate.ts → createStandaloneStack)	loadArtifactBundle(artifactPath) — the compiled artifact	YES — MetadataPlugin({ artifactSource: { mode: 'local-file', path: artifactPath } }) in the same list, bootstrap default eager → _loadFromLocalFile → door	the DOOR, alone (declares 'artifact-door')	seeders (registry first; position via the door's copy), permission evaluator (door's copy), sharing seeder, GET /meta/KIND	YES — the only row that changes
2	serve.ts:2811 new AppPlugin(config) — host configs (plugins[] holds instantiated plugins → shouldBootWithLibrary false), OS_MODE=off, or a standalone stack that found no artifact	the loaded defineStack() module	NO by default; ⚠ in os dev with a server, a dev-only HMR MetadataPlugin({ artifactSource: dist/objectstack.json }) is ALSO composed when that file resolves (serve.ts:3024) — see "Residual"	AppPlugin (default 'app-plugin'), exactly as today	same reader set as row 1	NO
3	serve.ts:3708 — plain stack objects inside config.plugins[] wrapped in AppPlugin each	nested stack objects	NO (the door never sees nested plugin stacks)	AppPlugin, as today	as row 1	NO
4	schema-migration-plugins.ts:784 new AppPlugin(config) — os migrate composing a host config that carries top-level metadata (composeHostStack)	the host config module	NO (the standalone base's door reads the artifact, not this module)	AppPlugin, as today	none — os migrate composes no SecurityPlugin / SharingServicePlugin (the file's own header records why)	NO
5	plugin-dev DevPlugin (dev-plugin.ts:503) new AppPlugin(this.options.stack)	the stack object	NO — no MetadataPlugin; the kernel's metadata service is core's createMemoryMetadata() fallback, which implements registerInMemory for exactly this block	AppPlugin, as today (sole registrar into the fallback)	GET /meta/KIND when REST is mounted	NO
6	@objectstack/verify bootStack (harness.ts:409) new AppPlugin(config) — and packages/qa/dogfood through it	the stack config	NO — no MetadataPlugin (core fallback)	AppPlugin, as today	SecurityPlugin + SharingServicePlugin seeders (registry first; position from the fallback's copy = AppPlugin's), evaluator	NO
7	External compositions — the cloud stack (createCloudStack, "no compiled artifact at all" per schema-migration-plugins.ts), embedders constructing AppPlugin or calling the public loadArtifactBundle themselves	whatever they pass	unknown / not visible from this repo	AppPlugin, as today — the default is the registering branch, so a composition that never heard of the option cannot lose a registrar	theirs	NO
8	Artifact HMR reload (MetadataPlugin._reloadAndAnnounce) on row 1	n/a — AppPlugin's metadata:reloaded subscriber seeds new objects only	YES (re-runs the door)	the DOOR (already was, after the first reload)	as row 1	NO

The "boot it and see whether anything complains" shortcut was not used: a declared collection with zero registrars boots green and logs nothing (H8 clearance measurement on the card). Every row above names its registrar from the composition source, and rows 1 and 6 are driven by tests in this PR.

Red-first evidence (the maintainer's pins did their job)

At 65c744efc3 (the WIP commit on this branch: implementation landed, harness reader 2 constructed the way createStandaloneStack now constructs it, pins untouched) pnpm --filter @objectstack/runtime exec vitest run --maxWorkers=2 src/app-plugin-artifact-forward-conversion.test.ts → Tests 6 failed | 2 passed (8), verbatim failures:

• registration ORDER no longer changes any conversion-governed value — but the two copies are STILL not interchangeable → AssertionError: expected [] to deeply equal [ '_packageId', …(4) ]
• capabilities: BOTH readers register them since #12892 step 1, and the two copies diverge on exactly four keys → AssertionError: AppPlugin must still register the capability: expected undefined to be defined
• the two readers agree on every ADR-0087 CONVERSION-governed key (the vacuity guard) → expected [] to deeply equal [ 'capability:crm.export', …(3) ]
• plus the three per-collection cases (permissions / sharingRules / positions) that doubled as the artifact-boot reader's positive controls.

⚠ Stated plainly rather than fitted to the template: the pins went red only once the harness constructed reader 2 with the declaration. A default-constructed AppPlugin(bytes) is the door-less boot and legitimately stayed green on the production edit alone — the discriminator is a composition-site declaration, not a property of the bytes.

The pins are REWRITTEN (never skipped, it.fails'd or relaxed — grep -cE "it\.(skip|todo|fails)|describe\.(skip|todo)|\.only\(" over both test files = 0): artifact boot ⇒ reader 2 writes nothing and the door reaches all four kinds; both start orders ⇒ exactly the door's copy, deep-equal to a measured DOOR_COPY key by key; the non-artifact boot as the positive control; the parse-axis residual kept as a measured difference between BOOT SHAPES.

Real-boot measurement (new standalone-stack-security-registrar.test.ts)

pnpm --filter @objectstack/runtime exec vitest run --maxWorkers=2 src/app-plugin-artifact-forward-conversion.test.ts src/standalone-stack-security-registrar.test.ts src/standalone-stack.test.ts at fc1581e364, after turbo run build --filter='@objectstack/runtime^...' on the merged tree (the runtime suite resolves @objectstack/metadata through dist/, no vitest alias; this PR's change is in runtime and is reached from source) → Test Files 3 passed (3) / Tests 34 passed (34), lock VERDICT command-exit 0.

• FIXED leg — a real Runtime kernel over createStandaloneStack({ artifactPath, projectRoot, databaseUrl: 'memory://…', skipSeedData: true, runPlatformMigrations: false }).plugins, the kernel ordering the starts: metadata.list('sharing_rule')[0].condition is { dialect: 'cel', source: 'record.status == "open"' }; the capability carries scope: 'platform', _packageId, _packageVersion: '2.0.0', _provenance: 'package'; the position carries delegatable: false; the permission set carries isDefault: false and neither allowRestore nor the RLS priority; exactly one item per kind.
• CONTROL leg — the same kernel with the AppPlugin swapped for a default-constructed one over the same bytes (the pre-step-2 composition, byte for byte): still one item per kind (two WRITERS, not two items) and the survivor is the raw copy — typeof condition === 'string', scope undefined, _packageVersion undefined. The defect reproduces on the pre-step-2 composition and not on the fixed one, on one kernel, in the order the kernel chooses.
• Two-reader harness (rewritten pins): under the declaration reader 2 writes no security item and the door registers all four kinds; door-first and AppPlugin-first orders both leave exactly DOOR_COPY in the registry, deep-equal key by key; the parse-axis residual is pinned as a difference between boot shapes; the default AppPlugin (positive control) still registers all four, forward-converted.
• Composition pin (standalone-stack.test.ts): the factory's real output carries an AppPlugin with securityMetadataRegistrar === 'artifact-door' AND a MetadataPlugin whose artifactSource is { mode: 'local-file', path: artifactPath } — the two halves of the invariant, on one object.

Verification

All readings at head fc1581e364 (merge of origin/main 1dcb995f23); exit codes captured by redirect-then-capture; verdict lines quoted from the gates' own output.

• Typecheck: pnpm --filter @objectstack/runtime typecheck → exit 0, 0 errors. ⚠ That program excludes **/*.test.ts, so the test files were measured directly: the same config with the exclusion lifted (temp tsconfig, removed by trap) → 206 error TS lines = EXACTLY the check-type-check-coverage DEBT entry for @objectstack/runtime (206), 0 of them naming any file this PR touches, and all three test files present in the program (--listFiles, 1 hit each).
• Gate union: node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands at fc1581e364 (change set derived from git: 6 paths vs merge base 1dcb995f2) → 36 families; the pre-merge derivation at 65c744efc3 named 35 and the merge added check-system-context-census, which was run as well. 33 green on their own verdict line, among them check:stack-collection-maps ("8 enumerations reconciled against 31 declared collections (17 waiver rows, each with a reason)" — SECURITY_FIELDS intact as the eighth site), check:nul-bytes ("scanned 7833 text file(s) … no raw ASCII control bytes"), check:cross-package-test-inputs, check:test-source-alias, check:type-source-resolution, check:engine-double-contract, check:where-matcher, check:query-options-erasure, check:type-check-coverage, check:dispatcher-error-vocabulary, check:published-files, check-plugin-teardown-shape, check-system-context-census, and the changeset family (check-adr-0087-registration: "this PR adds no declared-breaking changeset"; check-changeset-no-major; check-empty-changeset; check:changeset-gate-self-tests). Three declare their own non-measurement, quoted: node scripts/pm/check-half-states.mjs → "PREREQUISITE NOT MET — the transport authenticates but repo-scoped reads are refused"; node scripts/check-test-completeness.mjs → "PREREQUISITE NOT MET — this gate grades a saved turbo run test log, and no log was named"; pnpm check:type-check-debt / pnpm check:dual-build-cjs-loads → "PREREQUISITE NOT MET — this gate reads built output, and some package has no dist/ … NOT a pass: nothing was measured" (both need the full workspace build; the direct per-package tsc reading above substitutes for the first, CI owns both).
• pnpm lint, narrowed and proven: population read from eslint.config.mjs (files: ['**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}'] minus its ignores); eslint --no-inline-config --format json over the 5 touched files → 5 files, 0 errors, 0 warnings, and over all of packages/runtime/src → 287 files, 0 errors, 0 warnings (re-measured at this head); invariance: the config enables no parserOptions.project and no typed rules (its own comment, line 328), so this diff cannot move any untouched file's verdict.
• Control bytes: a grep -naP for the ASCII control class (backslash-x 00 through 08, 0b, 0c, 0e through 1f, 7f) over every touched file → grep exit 1, nothing found; check:nul-bytes above agrees.
• Not measured, declared: the rest of @objectstack/runtime's suite beyond the three files (CI's Test Core shards own it); the HTTP hop of GET /meta/KIND (the producer read is driven on the real boot, RestServer is not); the @objectstack/verify / dogfood boots (census row 6 is unchanged code, read from source, not re-driven).

Residual — out of scope, recorded

• os dev over a HOST config (serve.ts:2811 wrap + the dev-only HMR MetadataPlugin at serve.ts:3024) is a second boot shape with two writers over two SOURCES of one stack (the config module and its compiled twin). Not an artifact boot — AppPlugin's bundle is the module — and not this card's: filed as os dev over a HOST config composes two registrars for stack-declared security metadata — AppPlugin over the config module and the dev-only HMR MetadataPlugin over dist/objectstack.json #14397 (unassigned, dedup-searched) rather than patched here; os dev over a HOST config composes two registrars for stack-declared security metadata — AppPlugin over the config module and the dev-only HMR MetadataPlugin over dist/objectstack.json #14397 remains open.
• The ObjectQL SchemaRegistry copy (manifest.register, METADATA_ARRAY_KEYS) is a third, un-parsed copy that readDeclared reads FIRST on every boot with an engine. Pre-existing, unchanged, and the seam ObjectQL's two collection-registration copies diverge: jobs / emailTemplates / tools / skills register from a manifest but NOT from a nested plugin — a package shipping them via a nested plugin registers nothing, stamps no ADR-0010 provenance #7049 dealt with for its own two copies; noted so the census is complete.

Generated by Claude Code

🤖 Generated with Claude Code

https://claude.ai/code/session_016yfqQh2dBgPAymYd7xipza

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/runtime, touching 4 documentable anchor(s).

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

• content/docs/api/environment-routing.mdx (via createStandaloneStack (symbol, a top-level function))
• content/docs/data-modeling/drivers.mdx (via createStandaloneStack (symbol, a top-level function))
• content/docs/deployment/single-project-mode.mdx (via createStandaloneStack (symbol, a top-level function))
• content/docs/kernel/services-checklist.mdx (via AppPlugin (symbol, a top-level class))
• content/docs/permissions/authentication.mdx (via AppPlugin (symbol, a top-level class))
• content/docs/permissions/capabilities.mdx (via AppPlugin (symbol, a top-level class))
• content/docs/plugins/index.mdx (via AppPlugin (symbol, a top-level class), createStandaloneStack (symbol, a top-level function))
• content/docs/plugins/packages.mdx (via AppPlugin (symbol, a top-level class))
• content/docs/protocol/kernel/index.mdx (via AppPlugin (symbol, a top-level class))
• content/docs/protocol/kernel/lifecycle.mdx (via AppPlugin (symbol, a top-level class))
• content/docs/protocol/kernel/plugin-spec.mdx (via AppPlugin (symbol, a top-level class))

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

• content/docs/releases/v15.mdx (via AppPlugin (symbol, a top-level class))
• content/docs/releases/v17.mdx (via AppPlugin (symbol, a top-level class))

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

• 2 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 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 — 24 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 038f3332e62d61469b67ffa2cf8d3ef7ac8ccea4 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 406bc3a1ac2059b7620e768d382b498ba68b09d1 — the merge of head fc1581e364950c862e4dcb5ce26a4467d9397daa into base 038f3332e62d61469b67ffa2cf8d3ef7ac8ccea4, 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 406bc3a1ac2059b7620e768d382b498ba68b09d1 && git checkout 406bc3a1ac2059b7620e768d382b498ba68b09d1
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 038f3332e62d61469b67ffa2cf8d3ef7ac8ccea4 fc1581e364950c862e4dcb5ce26a4467d9397daa && git checkout -B drift-repro 038f3332e62d61469b67ffa2cf8d3ef7ac8ccea4 && git merge --no-ff fc1581e364950c862e4dcb5ce26a4467d9397daa

node scripts/docs-audit/affected-docs.mjs --json 038f3332e62d61469b67ffa2cf8d3ef7ac8ccea4

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

[hotlong]

Landing provenance — director seat (summon #9, session session_01WXyGTWPbbreqXow7Z2pZCk): contract review PASS at head fc1581e364 recorded on #12892 (comment 5507258502; served claude-fable-5-1 vs CONTRACT_REVIEW_TIER claude-fable-5, floor reading). Under the 2026-08-31 ruling (in-seat at-tier review clears the label; 清标即落地): needs:contract-review stripped on this PR and on #12892 and read back; check-governed-merges --test on the six changed paths → NOT governed; merge-tree against origin/main clean, no generated file on the diff; PR flipped ready and auto-merge armed (SQUASH requested) at 09:18Z. check-clause2-carriers --pair 14398 exits 3 here (repo-scoped REST 403 — NOT MEASURED); the pair was read by hand on both carriers. Followed to MERGED by this seat; on merge the card's pm:dispatched is stripped in the same window.

---

Generated by Claude Code