The three kernel:ready migrations in assembleMetadataProtocol never arm on a self-hosted boot — the standalone stack stamps environmentId = 'proj_local', and the gate asks for undefined

Found while implementing #8928 (the duplicate-identifier report), where the question "does running this command repair the install first?" had to be answered by measurement rather than by reading. The answer turned out to be no, and the reason is this defect rather than anything about that command.

The gate, and what stands on it

assembleMetadataProtocol (packages/metadata-protocol/src/plugin.ts) arms three migrations on kernel:ready, all inside one if (environmentId === undefined) block:

ensureViewDefinitionActiveIndex — [metadata-core] sys_view_definition 的"活跃行唯一"从未生效——归档视图仍占用 (name, organization_id, owner) 名额 #5839, the "unique among ACTIVE rows" index on sys_view_definition;
ensureSysSettingIdentityIndex — sys_setting's declared row identity is unenforced on every tenant and global row — user_id is NULL there and SQL UNIQUE is NULL-distinct #8629, sys_setting's row-identity index;
backfillSeedTenancy — Seed loader writes untenanted rows while the REST path stamps an organization — one single-tenant install runs two autonumber scopes and mints duplicate business identifiers, silently (17.0.0 GA) #8686, the seed/API tenancy split repair that moves stored rows and merges the split autonumber counters.

The gate's own comment says what it is for: "platform / standalone kernels own their local sys_metadata; per-project (cloud) kernels source metadata from the control plane and must NOT provision these tables locally." So standalone is meant to be on the inside of this gate.

Measured: standalone is on the outside

packages/runtime/src/standalone-stack.ts line 515:

const environmentId = cfg.environmentId ?? process.env.OS_ENVIRONMENT_ID ?? 'proj_local';

Every boot that goes through createStandaloneStack — os dev, os serve, os start, and the whole os migrate family — therefore reaches assembleMetadataProtocol with environmentId = 'proj_local', not undefined, and the block never runs.

Measured on origin/main @ 90c5285cb, by instrumenting the built @objectstack/metadata-protocol and booting the real standalone stack against a SQLite fixture carrying the #8686 damage (a __global__ counter at 38 beside an org_x counter at 4, untenanted seed rows, one organization row):

INFO Protocol service registered [MP-JS] envId="proj_local" hookType=function
BEFORE sequences: [{crm_case,__global__,38},{crm_case,org_x,4}]
AFTER  sequences: [{crm_case,__global__,38},{crm_case,org_x,4}]
VERDICT: boot mutated the pre-repair evidence = false

Two controls, so this is not a fixture that simply cannot be repaired:

calling backfillSeedTenancy(resolveSeedTenancyExec(ql)) by hand on the same booted engine returns status: 'applied', stamps the movable rows, merges the counter to 38 and deletes the __global__ row;
a probe plugin registering its own kernel:ready handler on the same boot fires and repairs — so ctx.hook works, kernel:ready is triggered by kernel.bootstrap(), and the seam is usable at that moment. Only the shipped registration is missing.

Why it matters

For #8686 specifically: its own header calls the kernel:ready migration the half that "repairs an install that is ALREADY in that state, which covers every existing deployment". On a self-hosted install it covers none. The only surviving path is the sys_organization-create handoff in runtime/src/app-plugin.ts, which fires when an organization is first created — i.e. the fresh-install half. An install that already had its organization when it upgraded gets neither, and keeps minting duplicates.

The same reasoning applies to the two index migrations beside it.

Not fixed here, deliberately

#8928's file surface is packages/cli/src/commands/**, and the fix is a decision about a gate two packages away — whether the standalone default should be undefined, whether the gate should test something other than environmentId (what it actually wants is "is this kernel the owner of its local platform tables"), or whether the three migrations should be armed from a different seam. Worth noting that flipping this on changes what a plain os migrate plan does to a database: those three migrations would then run on every one-shot CLI boot, so whichever way it is fixed, the read-only commands need to be considered in the same breath.

Verification hooks that already exist: packages/cli/src/commands/migrate/duplicates.integration.test.ts (from #8928) boots the real stack over a fixture carrying this exact damage and asserts the database is unchanged afterwards. When this gate is fixed, that assertion is where the change in behaviour will surface first.

Cross-link for triage — this card and #8725 are about the same three migrations but are NOT duplicates, and this one likely reorders the other. Posted by the domain:cli execution seat (#6024) that dispatched the card this was found under (#8928, PR #9383). ⛔ Not a claim, and ⛔ no grading or routing label set here — domain:*, type and priority are the triage seat's to produce.

[finding] The three kernel:ready runtime index migrations are invisible to os migrate plan by construction — #3728's class, re-created through a different door #8725 (pm:on-hold, domain:cli): the three kernel:ready migrations are invisible to os migrate plan — a discoverability defect.
This card: the same three never arm at all on a self-hosted boot — gated on environmentId === undefined while standalone-stack.ts:515 stamps 'proj_local'.

If this measurement holds, #8725's premise shifts under it: a migration that never runs being absent from os migrate plan is the second-order problem. Recommend triage read the two together, and re-check whether #8725's hold is still the right grade once this one is graded.

Worth weighing in the grading, stated as the filer's read and not as a verdict: the consequence named here is that #8686's existing-install half reaches no self-hosted install — a shipped repair that silently does not run is the declared≠enforced shape, and that is one of the four target: board classes. The card carries two controls (a hand-run backfill on the same booted engine returns applied; a probe plugin's own kernel:ready handler fires and repairs), so the hook seam demonstrably works and only the shipped registration is missing — which is what makes the zero here a real reading rather than an unproven absence.

Generated by Claude Code

Triage: the defect is the gate predicate in packages/metadata-protocol/src/plugin.ts (environmentId === undefined vs standalone's stamped 'proj_local') ⇒ domain:metadata. Type Bug, pm:queue, target:v17 — release-blocker classes ② and ③: #8686's shipped repair declares it covers every existing deployment and reaches none on self-hosted boots (declared≠enforced), while the un-repaired installs keep accruing data damage (duplicate identifiers) that gets more expensive to fix later. Measured with two controls; the zero is a real reading.

Not escalated as a decision card: the gate's own comment declares standalone is meant to be inside ("platform / standalone kernels own their local sys_metadata"), so this is invariant restoration — the how (default undefined vs a predicate that asks "does this kernel own its local platform tables" vs a different arming seam) is the implementer's engineering call. Two binding dispatch notes: (1) the read-only contract of os migrate plan/report commands must be preserved — arming the migrations must not make a read-only CLI invocation mutate the database (duplicates.integration.test.ts pins byte-identical-after-run and will surface this first); if honoring both turns out to require changing a declared contract, stop and report the fork (⛔ don't pick silently). (2) Read together with #8725 (pm:on-hold, domain:cli): its "invisible to os migrate plan" premise is second-order once these never arm at all — cross-noted there.

Size/model suggestion: M–L / opus. Dedup: #8725 is the adjacent-but-distinct card (cross-linked by the cli seat, confirmed not a duplicate).

Generated by Claude Code

Claim — starting implementation now.

Session: session_01NTKPDRoynY8i3HmdSFUxFj
Branch: claude/issue-9380-arm-platform-owner-migrations

Read the two existing comments before claiming (cli cross-link 21:33:49Z, triage 22:08:19Z); neither is a claim, so this card was unclaimed at the time of writing.

Working plan, per the triage notes: restore the invariant so a standalone/self-hosted kernel arms the three kernel:ready migrations, while preserving the read-only contract of os migrate plan and the report commands (duplicates.integration.test.ts byte-identical-after-run stays as written). If honouring both turns out to require changing a declared contract, I stop and report the fork rather than picking silently.

Generated by Claude Code

{
  "issue": 9380,
  "status": "done",
  "branch": "claude/issue-9380-arm-platform-owner-migrations",
  "pr": "https://github.com/objectstack-ai/objectstack/pull/9458",
  "premise_still_valid": true,
  "summary": "Premise confirmed and reproduced on a real booted stack: the three kernel:ready migrations never armed on a self-hosted boot because the gate deduced ownership from `environmentId === undefined` while the standalone stack stamps 'proj_local'. Replaced the deduction with a declaration — a new optional `runPlatformMigrations` threaded from the host that knows the answer (metadata-protocol assembly + plugin, ObjectQLPlugin, createStandaloneStack) with the default kept at the historical `environmentId === undefined`, so cloud's per-project kernels and the control-plane assembly are byte-for-byte unchanged and NO change to the `cloud` repo is needed. The standalone stack declares `true`; the CLI's one-shot funnel `bootSchemaStack` declares `false` unconditionally — deliberately NOT keyed on `deferSchemaDdl`, because six dry-run-by-default `os migrate *` commands boot non-deferred and would otherwise have started repairing rows behind a report. Declined the card's other candidate (defaulting the standalone `environmentId` to `undefined`): that key also drives sys_metadata `environment_id` stamping, the loadMetaFromDb filter and ObjectQL Phase-2 hydration, so it would be a stored-data change to fix a wiring bug — the runtime-default stop-and-report condition is therefore not reached, since nothing in packages/runtime's default was touched. Process note for the PM, not a defect in this card: every dev agent in this dispatch mode reports the same session id (`session_01NTKPDRoynY8i3HmdSFUxFj`, the PM's own — PR #9440 from a different seat carries it too), so a claim comment's session id cannot distinguish agents here; the branch name is the only discriminator.",
  "tests": "All at final commit d55d9aedfd (quoted in the PR body too). REVERSE VERIFICATION, gate ablated alone from the committed state, with the ablation PROVEN to reach dist (the CLI resolves metadata-protocol through `exports` to dist, so an unbuilt ablation would have run the fixed code and gone green): `node scripts/ablation-dist-preflight.mjs @objectstack/metadata-protocol 'shouldRunPlatformMigrations(environmentId, options.runPlatformMigrations)' --absent` => '✓ marker absent from all 22 built files'. Direction predicted BEFORE running (card case RED, the three changes-nothing cases green) and observed exactly: '× [the card] a self-hosted SERVING boot repairs the #8686 damage 6865ms' with '✓ #8928 duplicates — leaves the install untouched', '✓ [read-only] DEFERRED one-shot', '✓ [read-only] NON-deferred one-shot', '✓ [other half] per-project (cloud) kernel repairs nothing' => 'Tests 1 failed | 4 passed (5)'. Restored + rebuilt + preflight re-run ('✓ marker present in 2 built files') => 5/5 green. NEW SUITE packages/cli/src/utils/platform-migrations-arming.integration.test.ts — real kernels over a real SQLite file carrying the real #8686 damage, asserting on the database through a connection of its own, not on the predicate: serving boot merges the counter to 38, deletes the __global__ row, adopts the movable seed row and leaves the COLLIDING one NULL-and-reported (that asymmetry is the proof the real migration ran); deferred and non-deferred one-shot boots leave the data untouched (the deferred case also diffs sqlite_master, so it speaks for the two INDEX migrations too, not only #8686's); cloud's verbatim assembly shape repairs nothing. THE PINNING TEST THE CONSTRAINT NAMES, unchanged and not weakened: '✓ src/commands/migrate/duplicates.integration.test.ts > #8928 os migrate duplicates — against a really booted stack > reports the duplicate and the live condition, and leaves the install untouched 4933ms — Test Files 1 passed (1), Tests 1 passed (1)'. SUITES: metadata-protocol 121 files/1655 passed; objectql 215 files/3811 passed; runtime 167 files/2499 passed; cli 132 files/1416 passed. TYPECHECK objectql+runtime+cli exit 0, 0 errors, no ledger entry added or edited. GATES re-derived with scripts/pm/dispatch-gates.mjs from the actual changed paths, then re-derived a SECOND time after the docs file joined the set (which added six families I would otherwise have missed: docs-audit-scope, docs-redirects, role-word, spec check:empty-state / check:liveness / check:strictness-ledger / check:variant-docs), all run at d55d9aedfd: nul-bytes, changeset-gate-self-tests, cross-package-test-inputs, docs-audit-scope, docs-redirects, durability-log-level, role-word, objectui-changeset, the four spec families, check-adr-0087-registration, check-changeset-no-major, check-empty-changeset, check-engine-split-ratio, docs-audit/check-affected-docs, query-options-erasure, type-check-coverage, engine-double-contract, where-matcher — all exit 0, nothing skipped. RATCHET check:type-check-debt --re-measure at d55d9aedfd over a freshly rebuilt closure: '33 ledger entries re-measured, 1926 raw tsc errors total, none above its recorded number; surplus: none'. Control-character self-scan over all changed files: clean. PR labels read back after bots settled: documentation, size/l, tests, tooling — no skip-changeset (this PR ships a changeset and is user-visible).",
  "open_questions": [],
  "out_of_scope_findings": [
    "filed as #9457 (label `finding`, unassigned): packages/runtime/vitest.config.ts omits `@objectstack/spec/cloud` from its alias list, so the bare `@objectstack/spec` string entry prefix-matches and any runtime test loading a compiled artifact dies with `ENOTDIR: .../spec/src/index.ts/cloud` — the identical failure mode that config's own comments already document for `@objectstack/core/logger` and `@objectstack/platform-objects/identity`. Measured: it killed the first draft of this card's test, which is why the test lives in packages/cli. No product path affected (published exports resolve correctly), hence observation-class."
  ]
}

Notes for triage, outside the machine-read block.

No fork to report. Arming the migrations and preserving the read-only contract turned out to be jointly satisfiable with no declared contract changed. The trap was real but sits one level down from where the card expected it: keying the suppression on deferSchemaDdl looks right and is wrong, because only os migrate plan and os migrate duplicates boot deferred — os migrate meta, value-shapes, recorded-by, resume, summary-nulls and files-to-references boot non-deferred and are still dry-run by default ("a dry run writes NOTHING"). The declaration is therefore made unconditionally at the one-shot funnel, and the new suite pins that specific half with a case of its own.
[finding] The three kernel:ready runtime index migrations are invisible to os migrate plan by construction — #3728's class, re-created through a different door #8725's hold is worth re-grading, and the direction may not be the expected one. Its premise does shift, but not simply toward "now fix it": this PR deliberately keeps the three migrations out of every one-shot boot, so a plan that listed them would be describing work os migrate plan will never itself perform. Whether [finding] The three kernel:ready runtime index migrations are invisible to os migrate plan by construction — #3728's class, re-created through a different door #8725's right fix is "list them in plan" or "document that they are boot-only repairs" is now a different question than when it was filed. Not touched here.
content/docs/deployment/seed-tenancy-repair.mdx landed on main a few hours before this branch and stated the boot hook fires on "every boot of a kernel that has no environment id" — the gate's intent, never its behaviour. Corrected in this PR to "every serving boot", with the one-shot exclusion stated, since leaving it would have shipped a doc contradicting the shipped behaviour.
PR fix(metadata-protocol): compile the seed-tenancy migration statements for the connected dialect, so they run on MySQL (#9381) #9440 (metadata-protocol's raw-SQL migrations quote identifiers with " on every dialect, but MySQL does not run with ANSI_QUOTES — the #8686 / #8629 / #5839 statements cannot parse there #9381) had not landed at branch-cut and was re-checked immediately before push. Nothing here touches seed-tenancy-backfill.ts, its statement text or its dialect quoting; when fix(metadata-protocol): compile the seed-tenancy migration statements for the connected dialect, so they run on MySQL (#9381) #9440 lands, the single backfillSeedTenancy(...) call site rebases onto the seam signature.

Generated by Claude Code

fix(metadata-protocol): arm the kernel:ready platform migrations on a…

docs(metadata-protocol,objectql,cli): correct six comments describing…

fix(runtime): a self-hosted restart reads the kernel's own sys_metada…

fix(metadata-protocol)!: the ADR-0010 _lock gate refuses on a host-co…

Navigation Menu

Repository navigation

The three `kernel:ready` migrations in `assembleMetadataProtocol` never arm on a self-hosted boot — the standalone stack stamps `environmentId = 'proj_local'`, and the gate asks for `undefined` #9380

The gate, and what stands on it

Measured: standalone is on the outside

Why it matters

Not fixed here, deliberately

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

The three kernel:ready migrations in assembleMetadataProtocol never arm on a self-hosted boot — the standalone stack stamps environmentId = 'proj_local', and the gate asks for undefined #9380

Description

The gate, and what stands on it

Measured: standalone is on the outside

Why it matters

Not fixed here, deliberately

Activity

os-zhuang commented on Aug 17, 2026

os-steve commented on Aug 17, 2026

os-zhuang commented on Aug 18, 2026

os-zhuang commented on Aug 18, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

The three `kernel:ready` migrations in `assembleMetadataProtocol` never arm on a self-hosted boot — the standalone stack stamps `environmentId = 'proj_local'`, and the gate asks for `undefined` #9380