fix(cli,driver-sql): os migrate plan/apply compose what os serve mounts around the stack, so sys_account.issuer is a drop (#22506)

[objectstack-fleet]

Fixes #22506
Clause-②: no
os migrate plan / apply start composing what the boot composes, so a retired column the published upgrade step names as a destructive drop becomes one. No accepted input, flag, key or export changes.

What changes

os migrate plan and os migrate apply only examine the objects their own boot registers. That boot stopped at the stack: its config, its metadata and the platform floor. Nothing os serve mounts around a stack was there. This is the third time the family has surfaced (#12938, #21732), and each earlier fix grew one list. This PR composes through the rules serve itself reads and pins parity with a real serve boot.

packages/cli (utils/schema-migration-plugins.ts, utils/schema-migrate.ts, commands/migrate/plan.ts, apply.ts). With the new servedPlatform option, which plan and apply set (and unmapped-columns, below), the composition adds:

• The auth family, behind serve's auth gate. The gate is resolvePlatformAuthComposition (@objectstack/core, feat(cli): os migrate security-catalog-overlays — list, and with --apply delete, the environment rows a v18 cold boot refuses #22523's shared rule), fed by resolveStackTiers and resolveAuthSecret. Plugin-auth's objects come through createIdentityObjectsPlugin(), AuthPlugin's declaration twin: the same manifest under the same package id, and no authentication. The security plugin and the audit plugin are composed beside it. The family sits where serve registers it, ahead of the host plugins.
• The provider of every capability serve mounts. That means the stack's requires, read by serve's rule, plus PLATFORM_ALWAYS_ON_CAPABILITIES, as os serve with no --preset composes them. Each is looked up through CAPABILITY_PROVIDERS and skipped when already held, by providesCapability (@objectstack/core, feat(core,cli,verify): bootStack composes what serve composes — item 1 stage 2 of #22301 (HELD at stop conditions) #22381's shared rule). It replaces the cli: os migrate plan / apply cannot boot the stock showcase or a fresh blank app — Dependency 'com.objectstack.service-automation' not found for the connector plugins #21732 "only when hard-depended on" narrowing for these two commands.
• The REST API plugin. serve composes it on every boot, and its init() declares sys_import_job.
• Every plugins entry, by serve's entry rule (materializeStackPlugin, @objectstack/core). A string is loaded host-anchored through Serve.importConfigPlugin, and a bundle is wrapped as an AppPlugin. Before, a string entry vanished silently and a bundle reached the kernel raw. An entry that cannot be loaded makes the config unloadable, so the os migrate plan exits 0 when the host config exists but could not be loaded — the one remaining UNMEASURED shape after #12938 #12953 refusal applies. This rule applies to every caller of the host composition.
• The config's pinyin-search stamp (stampSearchPinyinEnabled, the one helper serve calls). A config-only project used to plan without the __search companion columns its boot provisions. Measured on examples/app-crm: 49 destructive drop_column __search entries before the stamp, none after.

Posture. Every provider is composed through a new composeProviderForDeclarations: its init() runs, its start() does not, and it registers no lifecycle hook, kernel:ready included. That is stricter than the host-plugin posture, for a measured reason. With the host posture, MessagingServicePlugin's notification and outbound-HTTP dispatchers (armed from kernel:ready hooks its init() registers) ticked inside plan. The write guard comes off when the bootstrap ends, so on a database holding pending deliveries a dry run could have sent them. With this posture, zero dispatcher lines. The automation token keeps its #21732 inert posture.

When no auth secret resolves, outside development, the plan says it did not compose the auth family and names the command that does: re-run with the deployment's OS_AUTH_SECRET exported. os migrate reads no .env file.

packages/drivers/driver-sql (previewDeferredSchemaWork only, per the surface extension 6091922191). A rotation-declared object (ADR-0057 P2) lives as its current shard (__rYYYYMMDD) plus a read view under its base name. The preview asked hasTable of the base name, which is false for a view, so it listed create_table on every plan. The flush then took the sync's rotation branch and created nothing. Once the composition registers the audit plugin's sys_activity, that would have been a finding no apply can clear on every auth-enabled deployment. The preview now answers from the rotator's facts: its shard key for now and the two names in sqlite_master. When the current shard and the read view are both present, nothing is pending. The rotator, syncSchema's rotation branch and flushDeferredSchemaDdl are untouched.

commands/migrate/unmapped-columns.ts (review round, claim widened in 6092886177). Its bootSchemaStack call passes composeServedPlatform: true too, and its comment names it; nothing else in the command changes. Its documented contract (content/docs/deployment/cli.mdx: "the same differ, the same boot") is the plan's own unmapped_column findings over the plan's object set. With the flag on plan / apply only, os migrate unmapped-columns --object sys_account answered OBJECT_NOT_FOUND for a platform object the plan reports on.

commands/migrate/account-issuer.ts. A one-line change: the clean prescription is now true whether or not the column is still there. While os migrate plan still lists the drop, run os migrate apply --allow-destructive; once it lists none, the retirement is done.

Readings

All readings go through the public doors. The hotclm shape is an app config with requires: ['auth'] and no plugins, over a SQLite database a real os serve boot created, then given the legacy sys_account.issuer column plus uniq_sys_account_issuer_account_id.

step	main 4638625e07	this branch
os migrate plan	9 of the 68 boot-created tables examined; sys_account listed as an undeclared platform table; 0 drift	74 examined; sys_account declared; 2 destructive: drop_column sys_account.issuer, drop_index uniq_sys_account_issuer_account_id
os migrate apply --allow-destructive --yes	0 applied; column and index still present	both applied; column and index gone
os migrate account-issuer	ok, 0 collisions, prescribes apply --allow-destructive again	ok, 0 collisions
next os serve boot	two [schema-drift] sys_account … lines prescribing apply --allow-destructive	no sys_account drift line
re-plan after apply	—	0 drift, nothing pending (pinned)

No-secret production leg (in-process, NODE_ENV=production, no OS_AUTH_SECRET): sys_account is not registered, and the note names the remedy above.

Parity per example app (a real os serve --no-server boot with OS_MIGRATE_AND_EXIT=1 provisions a fresh database, then os migrate plan --json runs on it):

• examples/app-showcase, the real host config, at 47823309b4: drift and pending empty; unmanaged only sys_packages; 105 of 107 registered objects examined, the other 2 federated (correctly out of scope). The 107 boot tables are the 105 plus sys_packages and _objectstack_sequences, the driver's internal auto-number table.
• examples/app-crm 82/82, app-todo 77/77 and app-multi-package 75/75: drift empty, unmanaged only sys_packages. These were measured before the driver fix, so each still listed the sys_activity phantom that the driver pin now clears.

This composition widens the telemetry-sibling mismatch from 1 object to 7

A development boot, or one with OS_TELEMETRY_DB set, keeps lifecycle-classed objects in a sibling objectstack.telemetry.db (ADR-0057 §3.6, provisionTelemetryDatasource). The one-shot migration boot does not provision that database, so it examines those objects against the primary one.

Measured with a development boot of the hotclm shape: the boot's objectstack.telemetry.db holds sys_audit_log, sys_activity, sys_metadata_audit, sys_job_run, sys_notification, sys_notification_delivery and sys_http_delivery.

• On main, os migrate plan lists one of them (sys_metadata_audit) as create_table against the primary, and apply --yes creates it there.
• With this branch's composition (audit, job and messaging now composed), plan lists all seven: sys_activity, sys_audit_log, sys_http_delivery, sys_job_run, sys_metadata_audit, sys_notification, sys_notification_delivery.

Production boots without OS_TELEMETRY_DB are unaffected: they keep these objects in the primary database, and the plan matches it. The seat keeps the telemetry sibling out of this card (its ruling 6091922191) and files it at ACCEPT.

Pins

• driver-sql: src/sql-driver-deferred-ddl.test.ts, "a rotation-declared object previews from the rotator's facts". Already sharded previews no work; the never-sharded control previews create_table; after a flush, the next preview is empty.
  • At 306a75dcf2 with sql-driver-rotation.test.ts: 2 files, 23 passed.
  • Red against base, with sql-driver.ts at 4638625e07 written to the tree only: 2 failed (already sharded, converges), 16 passed (the control among them).
  • Restore: git diff HEAD empty, hash back to the HEAD blob.
• hotclm shape: src/commands/migrate/apply.account-issuer-retirement.integration.test.ts. It runs in-process over a sys_account built by the driver from today's definition, then given the legacy column, index and one issuer-carrying row. The four cases: plan names both drops; apply performs them; account-issuer reaches zero (scanned 1); a re-plan is in sync, with no phantom sys_activity.
• parity: src/commands/migrate/plan.boot-parity.integration.test.ts. One case per app shape: an app with requires: ['auth', 'automation'], a host config with plugin instances beside its own metadata, and a compiled-artifact standalone stack.
  • Each asserts: pending empty and drift empty (plan ⊆ boot); the boot's tables equal the examined objects plus sys_packages, which with pending empty makes equal sets (boot ⊆ plan); and, where the sweep runs, unmanaged only sys_packages. sys_packages is named as raw DDL from PackageServicePlugin.start(), outside the object set.
  • Ablation through scripts/ablation-replace.mjs: composeServedPlatform: false in plan.ts (anchor 1 to 0, blob changed) turns all 3 red, with boot tables 78 / 76 / 75 against examined-plus-raw 10 / 11 / 10. Restore verified.
• unmapped-columns: src/commands/migrate/unmapped-columns.integration.test.ts, "a platform object the plan declares (os migrate apply --allow-destructive cannot drop sys_account.issuer on a 17.4.0-created SQLite database, while os migrate account-issuer and the boot's schema-drift line keep prescribing it (17.7.0) #22506)". The seed adds a sys_account table built by the driver from today's definition, plus the retired issuer column and one row; on an auth-enabled stack --object sys_account --json exits 0 and reads issuer for that row, the same column set os migrate plan --json reports as unmapped_column for the table. With the flag removed (scripts/ablation-replace.mjs, anchor 1 to 0): that case red with {"error":"Object 'sys_account' not found","code":"OBJECT_NOT_FOUND"}, exit 1, the other 9 cases green; restored (blob back to HEAD, git diff HEAD empty).
• unit: src/utils/schema-migration-plugins.test.ts, "servedPlatform (os migrate apply --allow-destructive cannot drop sys_account.issuer on a 17.4.0-created SQLite database, while os migrate account-issuer and the boot's schema-drift line keep prescribing it (17.7.0) #22506)" and "composeProviderForDeclarations (os migrate apply --allow-destructive cannot drop sys_account.issuer on a 17.4.0-created SQLite database, while os migrate account-issuer and the boot's schema-drift line keep prescribing it (17.7.0) #22506)". They cover the family behind the gate, ahead of the host plugins; the slate providers and the REST API plugin; a host-supplied provider winning; no secret, with the remedy named; a stack mounting its own AuthPlugin; the bundle entry rule and the unloadable string entry; the pinyin stamp; the control without servedPlatform; and the provider posture against the host posture.

Verification

Review round, head 5bdfba6bc1 (unmapped-columns boots the plan's object set):

• Typecheck (pnpm --filter @objectstack/cli typecheck): exit 0.
• Unit (vitest run --project unit): unmapped-columns.test.ts plus schema-migration-plugins.test.ts: 2 files, 67 passed.
• Integration, through the verify lock: unmapped-columns.integration.test.ts, plan.boot-parity.integration.test.ts and apply.account-issuer-retirement.integration.test.ts: 3 files, 17 passed. The flag-removed leg is in Pins.
• Lint, the same proven narrowing: the 12 changed source files give 12 files, 0 errors and 0 warnings.
• Gates: dispatch-gates --commands derives the same 69 families; all 69 exit 0 at 5bdfba6bc1, with check:type-check-debt and check:dual-build-cjs-loads last. --ran reads 69 derived, 69 run, 0 NOT-MEASURED (derived from recorded exit codes).

First round, head 47823309b4:

The source has been identical since 143f14e192; later commits touch two test files only.

• Typecheck (pnpm --filter @objectstack/cli typecheck, tsc --noEmit plus check:test-typecheck) at 143f14e192: exit 0.
• CLI unit layer (vitest run --project unit) at 143f14e192: 276 files, 4085 passed. At 47823309b4, schema-migration-plugins.test.ts plus test/exit-signal.pin.test.ts: 2 files, 160 passed.
• CLI integration layer, through the verify lock, as a declared narrowing: the integration-tier files that boot the schema stack or drive the migrate commands. Filters: src/commands/migrate/, src/utils/schema-migrat, unmanaged-tables, platform-migrations-arming, artifact-boot-migration, sqlite-occupancy, test/migrate-, test/dev-standalone-self-heal.
  • At 143f14e192: 34 files, 317 passed, 2 skipped, 2 failed. Both failures were in the parity pin, fixed in 47823309b4, where the parity file passes 3/3.
  • The one-shot family's no-write pin is among the passing files: every no-write mode, plan included, still moves no byte.
  • The rest of the integration project is declared to CI.
• driver-sql: see Pins.
• Lint, as a proven narrowing at 47823309b4, with three pieces of evidence:
  • the checked population is eslint.config.mjs's **/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs} minus the global NEVER_LINTED;
  • the 10 changed source files, linted as pnpm lint invokes ESLint (--no-inline-config, --format json), give 10 files, 0 errors and 0 warnings;
  • the config never enables type-aware linting (its own statement: no parserOptions.project, no typed rules), so this diff cannot move the verdict of any untouched file.
• Gates: dispatch-gates --commands derives 69 families from this branch; all 69 exit 0 at 47823309b4.
  • The --ran reconciliation reads: 69 derived, 69 run, 0 NOT-MEASURED (derived from recorded exit codes).
  • check:i18n-coverage and check:dual-build-cjs-loads first exited 3 (PREREQUISITE NOT MET, from showcase-only and 8 unrelated packages without dist/ in this worktree). Both re-ran green after those builds.
  • check:type-check-debt and check:dual-build-cjs-loads ran last.
• Dogfood is declared to CI. git grep for migrate plan|apply, MigratePlan, MigrateApply, bootSchemaStack and buildSchemaMigrationPlugins over packages/qa/dogfood exits 1 (zero hits).

Acceptance notes

• The telemetry sibling (above), the fact that os migrate reads no .env file, and the absence of --preset / --dev on plan / apply stay out of this card, by the seat's ruling.
  • .env, measured on main: a fixture whose .env sets OS_DATABASE_URL gets a plan of .objectstack/data/objectstack.db, while serve loads that .env.
  • A deployment served with --preset minimal gets the always-on slate examined.
• utils/unmanaged-tables.ts still reports itself unreadable on a project with no host config, saying the composed set is "the compiled artifact plus the platform floor". For plan / apply that reason is now false (the served platform is composed); the conservative verdict is unchanged. The file is outside this card's surface; carrier: none.
• sys_packages (raw DDL) and _objectstack_sequences (the driver's auto-number table) are tables no object declares. The parity pin names the first; its fixtures declare no auto-number field.
• The kernel prints CORE: Core service missing … auth during plan / apply once the identity objects are composed without AuthPlugin. This is cosmetic stderr noise.
• The rotation preview, per the seat's rule, does not diff the current shard's columns. The rotator column-syncs every retained shard when the flush runs.
• Both the preview and the flush read the shard key from the clock, so a plan run across UTC midnight can list the new day's shard as create_table. That is real work the flush then does.
• formatAccountIdentityPreflightReport (plugin-auth) still prints "sys_account.issuer is safe to drop." when the column is already gone. Only account-issuer.ts's own prescription changed.
• origin/main moved 7 commits since the base 4638625e07, including the dispatch-gates rework (tooling(pm): dispatch-gates — the hand-written tables move out as data, the self-test out as a module with fast/slow tiers, derivation byte-identical #22531). None of them touches this diff's files, so nothing was merged.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 2 package(s): @objectstack/cli, @objectstack/driver-sql, touching 18 documentable anchor(s).

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

• content/docs/ai/skills-reference.mdx (via os migrate apply (command, read off packages/cli/src/commands/migrate/apply.ts), os migrate plan (command, read off packages/cli/src/commands/migrate/plan.ts))
• content/docs/data-modeling/drivers.mdx (via os migrate apply (command, read off packages/cli/src/commands/migrate/apply.ts))
• content/docs/data-modeling/indexing.mdx (via os migrate plan (command, read off packages/cli/src/commands/migrate/plan.ts))
• content/docs/data-modeling/queries.mdx (via os migrate apply (command, read off packages/cli/src/commands/migrate/apply.ts), os migrate unmapped-columns (command, read off packages/cli/src/commands/migrate/unmapped-columns.ts))
• content/docs/deployment/cli.mdx (via os migrate account-issuer (command, read off packages/cli/src/commands/migrate/account-issuer.ts), os migrate apply (command, read off packages/cli/src/commands/migrate/apply.ts), os migrate plan (command, read off packages/cli/src/commands/migrate/plan.ts), os migrate unmapped-columns (command, read off packages/cli/src/commands/migrate/unmapped-columns.ts))
• content/docs/deployment/index.mdx (via os migrate apply (command, read off packages/cli/src/commands/migrate/apply.ts), os migrate plan (command, read off packages/cli/src/commands/migrate/plan.ts))
• content/docs/deployment/self-hosting.mdx (via os migrate apply (command, read off packages/cli/src/commands/migrate/apply.ts))
• content/docs/kernel/services-checklist.mdx (via os migrate apply (command, read off packages/cli/src/commands/migrate/apply.ts), os migrate plan (command, read off packages/cli/src/commands/migrate/plan.ts))
• content/docs/protocol/kernel/lifecycle.mdx (via os migrate apply (command, read off packages/cli/src/commands/migrate/apply.ts), os migrate plan (command, read off packages/cli/src/commands/migrate/plan.ts))
• content/docs/upgrading.mdx (via os migrate apply (command, read off packages/cli/src/commands/migrate/apply.ts), os migrate plan (command, read off packages/cli/src/commands/migrate/plan.ts))

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

• content/docs/releases/v17/17-0.mdx (via os migrate plan (command, read off packages/cli/src/commands/migrate/plan.ts))
• content/docs/releases/v17/17-3.mdx (via os migrate apply (command, read off packages/cli/src/commands/migrate/apply.ts), os migrate plan (command, read off packages/cli/src/commands/migrate/plan.ts))
• content/docs/releases/v17/17-4.mdx (via os migrate plan (command, read off packages/cli/src/commands/migrate/plan.ts))
• content/docs/releases/v17/17-5.mdx (via os migrate account-issuer (command, read off packages/cli/src/commands/migrate/account-issuer.ts), os migrate apply (command, read off packages/cli/src/commands/migrate/apply.ts), os migrate plan (command, read off packages/cli/src/commands/migrate/plan.ts))
• content/docs/releases/v17/17-6.mdx (via os migrate apply (command, read off packages/cli/src/commands/migrate/apply.ts), os migrate plan (command, read off packages/cli/src/commands/migrate/plan.ts))
• content/docs/releases/v17/17-7.mdx (via os migrate apply (command, read off packages/cli/src/commands/migrate/apply.ts), os migrate plan (command, read off packages/cli/src/commands/migrate/plan.ts), os migrate unmapped-columns (command, read off packages/cli/src/commands/migrate/unmapped-columns.ts))

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

• 4 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 — 35 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 25be87612d9a61f9f921ab4e993822669f04b321 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 28df4c1a4549354f9793da765c3df44eca893310 — the merge of head 5bdfba6bc1e74f7ef36bb09424594d7f64c7dfa7 into base 25be87612d9a61f9f921ab4e993822669f04b321, 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 28df4c1a4549354f9793da765c3df44eca893310 && git checkout 28df4c1a4549354f9793da765c3df44eca893310
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 25be87612d9a61f9f921ab4e993822669f04b321 5bdfba6bc1e74f7ef36bb09424594d7f64c7dfa7 && git checkout -B drift-repro 25be87612d9a61f9f921ab4e993822669f04b321 && git merge --no-ff 5bdfba6bc1e74f7ef36bb09424594d7f64c7dfa7

node scripts/docs-audit/affected-docs.mjs --json 25be87612d9a61f9f921ab4e993822669f04b321

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