fix(cli): make a declaration boot write nothing at the driver seam, not by suppressing start() alone

.changeset/declaration-boot-write-suppression.md

@@ -0,0 +1,73 @@
+---
+"@objectstack/cli": minor
+---
+
+fix(cli): make `os migrate plan`'s "writes nothing" a property of the mechanism, not of an unwritten host convention (#13332)
+
+`composeForDeclarations` documented the plan path's guarantee in its own words —
+*"(init runs, start does not — a plan writes nothing)"* — and implemented it as a
+Proxy whose only override is `start`. `packages/core/src/kernel.ts` then fires
+three phases unconditionally after the suppressed start pass: `kernel:ready`
+(Phase 3), `kernel:bootstrapped` (Phase 3.5) and `kernel:listening` (Phase 4). A
+writing hook **registered from `init()`** survives the suppression and executes
+on all three. The guarantee was therefore a property of plugins that happen to
+seed from `start()` — the shape of the one plugin that had been measured — and
+not of the plan path.
+
+Measured, twice. The module header records 14 `Insert operation failed` rows
+against `sys_permission_set` from a deferred `plan` boot, and notes that on a
+database whose tables already exist those inserts **succeed**: a command
+documented as writing nothing seeds rows into an operator's production control
+plane. Downstream, a control plane hit exactly this on the `apply=false` run
+that is its mandatory human review gate before a production schema apply
+(`driver.create` / `driver.update` on `sys_ai_model`, from an
+`init()`-registered `kernel:ready` hook).
+
+**What changed.** For the length of the kernel bootstrap, `os migrate plan` /
+`os migrate apply` now refuse the row-write members of the data-driver contract
+(`IDataDriver`: `create`, `update`, `upsert`, `delete`, `bulkCreate`,
+`bulkUpdate`, `bulkDelete`, `updateMany`, `deleteMany`) on every `driver.*`
+instance the kernel publishes. The refusal sits at the driver, not at a list of
+lifecycle phase names: it is phase-agnostic (a phase added tomorrow is covered
+on the day it ships), it covers writes that arrive through the ObjectQL engine
+as well as direct `driver.*` calls (the engine holds the same instance), and
+read/log-only hooks still run — which is what an operator reading a plan before
+a production apply needs them to do. A refused write returns a contract-shaped
+value rather than throwing (boot hooks dispatch propagating, so throwing would
+abort the bootstrap and leave the operator with no plan at all), and every
+refusal is reported: one warning on stderr per driver/method/object triple,
+plus a line in the composition notes the plan prints and `--json` carries.
+
+The contract's raw-execution escape hatch — `IDataDriver.execute()`, a required
+member on every driver — is FORWARDED and REPORTED rather than refused: a raw
+command is `unknown` by contract ("SQL string, shell command, or API payload"),
+and SQL text cannot be classified as read-vs-write reliably, so refusing would
+break boot-legitimate reads and the framework's own index DDL on a guess. A
+boot-window `execute()` is counted per driver, warned once per driver on
+stderr, and named in the composition notes — and on such a run the notes do
+NOT claim the plan wrote nothing, because the guard cannot verify it.
+
+The guard is disarmed the moment the bootstrap returns, so `os migrate apply`'s
+confirmed DDL flush and the coverage measurement are untouched.
+
+**Who this affects.** A host whose plugins write during a `plan`/`apply` boot
+from anywhere other than a suppressed `start()`. Contract row writes previously
+landed and now do not; the run says so. A host whose plugins call raw
+`execute()` during the boot keeps its behaviour (the call is forwarded) and
+now sees it reported. A host that did neither sees no change at all — no
+disarm note is emitted when nothing was refused and no raw command went
+through.
+
+Boundaries stated rather than hidden: `execute()` is reported, never refused
+(above); `getKnex()` (a driver-sql extension, genuinely off-contract) is not
+intercepted. DDL splits: `deferSchemaDdl` holds back the
+`initObjects`/`syncSchema` path (flushed on purpose by `apply` once the
+operator confirms), while `dropTable`/`rotateShards` are NOT held back by that
+deferral — they are gated only by `assertSchemaMutable`
+(schemaMode/dialect) and stay a genuinely open boundary during the boot.
+Drivers the engine holds for a NON-default datasource are never published as
+`driver.*` (`DatasourceConnectionService.connect()` hands them to
+`engine.registerDriver` directly), so they are invisible to the guard's scan
+and objectql-mediated writes to objects bound to them would land. The guard
+also does not cover writes a plugin makes outside the database, or work a hook
+defers past the end of the bootstrap.

packages/cli/src/utils/schema-migrate.host-composition.integration.test.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
 
 import { describe, it, expect, beforeAll, afterAll } from 'vitest';
-import { mkdtempSync, mkdirSync, writeFileSync, symlinkSync, rmSync } from 'node:fs';
+import { mkdtempSync, mkdirSync, writeFileSync, appendFileSync, readFileSync, symlinkSync, rmSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { tmpdir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
@@ -494,3 +494,295 @@ describe('a host that brings its OWN ObjectQL engine (#13028 — cloud\'s measur
  }
  }, 60_000);
 });
+
+/**
+ * #13332 — the same guarantee, end to end, against a real SQL driver.
+ *
+ * The unit half
+ * (`schema-migration-plugins.declaration-boot-write-guard.test.ts`) pins the
+ * mechanism on a recording driver. This half proves the property the operator
+ * actually depends on: `os migrate plan`'s boot, with a host plugin that
+ * registers a writing hook from `init()`, leaves the DATABASE unchanged — on a
+ * database whose tables already exist, which is the condition under which the
+ * measured inserts SUCCEED instead of failing.
+ *
+ * The positive control comes first and is load-bearing. The identical plugin,
+ * on a boot that composes no host stack (so no declaration composition and no
+ * write guard), lands its rows. Without that leg the assertion below would be
+ * green over a fixture that could not have written.
+ */
+describe('a plan writes nothing even when the host writes from init() (#13332)', () => {
+ let dir: string;
+ let dbFile: string;
+ let hookLog: string;
+ const savedEnv: Record<string, string | undefined> = {};
+
+ const PHASES = ['kernel:ready', 'kernel:bootstrapped', 'kernel:listening'] as const;
+
+ /**
+ * cloud's measured shape, as a plugin this file can hand to either boot: the
+ * writing hooks are registered from `init()`, so `composeForDeclarations`'s
+ * `start()` suppression never sees them, and they fire on each of the three
+ * phases `kernel.ts` triggers unconditionally after the suppressed pass.
+ *
+ * The driver is found by scanning `driver.*` — the same surface
+ * `ObjectQLPlugin`'s discovery loop reads — rather than by naming one, so the
+ * fixture does not depend on what the standalone stack calls its default.
+ */
+ const initWritingPlugin = (tag: string): any => ({
+ name: `com.example.writes-from-init.${tag}`,
+ version: '1.0.0',
+ init: async (ctx: any) => {
+ for (const phase of PHASES) {
+ ctx.hook(phase, async () => {
+ appendFileSync(hookLog, `${tag}|log-only|${phase}\n`);
+ });
+ ctx.hook(phase, async () => {
+ const services: Map<string, any> = ctx.getServices();
+ const entry = [...services.entries()].find(([n]) => n.startsWith('driver.'));
+ if (!entry) return;
+ await entry[1].create('sys_metadata', {
+ id: `os13332-${tag}-${phase}`,
+ name: `os13332-${tag}-${phase}`,
+ type: 'os13332_probe',
+ });
+ appendFileSync(hookLog, `${tag}|write|${phase}\n`);
+ });
+ }
+ },
+ });
+
+ const probeRows = async (driver: any): Promise<number> => {
+ const rows: any = await driver.knex('sys_metadata')
+ .where({ type: 'os13332_probe' })
+ .count({ c: '*' });
+ return Number((Array.isArray(rows) ? rows[0] : rows)?.c ?? -1);
+ };
+
+ beforeAll(async () => {
+ dir = mkdtempSync(join(tmpdir(), 'os-13332-'));
+ dbFile = join(dir, 'control.db');
+ hookLog = join(dir, 'hooks.log');
+ writeFileSync(hookLog, '');
+
+ savedEnv.NODE_ENV = process.env.NODE_ENV;
+ savedEnv.OS_ARTIFACT_PATH = process.env.OS_ARTIFACT_PATH;
+ process.env.NODE_ENV = 'production';
+ process.env.OS_ARTIFACT_PATH = join(dir, 'dist', 'objectstack.json');
+
+ // Materialize `sys_metadata` FIRST, with no host config on disk yet. The
+ // measured defect is precisely that on a database whose tables EXIST the
+ // inserts succeed rather than fail, so neither case below may run against
+ // an empty schema — and the fixture must not depend on the fix to build
+ // itself: with the guard ablated, a writing hook against a table that does
+ // not exist yet THROWS, and boot hooks dispatch propagating, so the whole
+ // bootstrap dies. Setting the schema up before the writer exists keeps an
+ // ablation landing on the assertions below instead of on this hook.
+ const boot = await bootSchemaStack({
+ jsonOutput: false,
+ databaseUrl: `file:${dbFile}`,
+ deferSchemaDdl: true,
+ composeHostStack: false,
+ projectRoot: dir,
+ });
+ try {
+ await boot.flushSchemaDdl();
+ } finally {
+ await boot.shutdown();
+ }
+
+ // A host config carrying the SAME plugin shape, so the composed path is
+ // exercised as an operator would hit it — the plugin comes out of
+ // `objectstack.config.ts`, through `composeForDeclarations`.
+ writeFileSync(
+ join(dir, 'objectstack.config.ts'),
+ [
+ "import { appendFileSync } from 'node:fs';",
+ '',
+ `const LOG = ${JSON.stringify(hookLog)};`,
+ "const PHASES = ['kernel:ready', 'kernel:bootstrapped', 'kernel:listening'];",
+ '',
+ 'export default {',
+ ' plugins: [{',
+ " name: 'com.example.host-writes-from-init',",
+ " version: '1.0.0',",
+ ' init: async (ctx: any) => {',
+ ' for (const phase of PHASES) {',
+ " ctx.hook(phase, async () => { appendFileSync(LOG, `host|log-only|${phase}\\n`); });",
+ ' ctx.hook(phase, async () => {',
+ ' const entry = [...ctx.getServices().entries()]',
+ " .find(([n]: [string, unknown]) => n.startsWith('driver.'));",
+ ' if (!entry) return;',
+ " await entry[1].create('sys_metadata', {",
+ ' id: `os13332-host-${phase}`,',
+ ' name: `os13332-host-${phase}`,',
+ " type: 'os13332_probe',",
+ ' });',
+ " appendFileSync(LOG, `host|write|${phase}\\n`);",
+ ' });',
+ ' }',
+ ' },',
+ ' }],',
+ '};',
+ '',
+ ].join('\n'),
+ );
+
+ writeFileSync(hookLog, '');
+ }, 60_000);
+
+ afterAll(() => {
+ if (savedEnv.NODE_ENV === undefined) delete process.env.NODE_ENV;
+ else process.env.NODE_ENV = savedEnv.NODE_ENV;
+ if (savedEnv.OS_ARTIFACT_PATH === undefined) delete process.env.OS_ARTIFACT_PATH;
+ else process.env.OS_ARTIFACT_PATH = savedEnv.OS_ARTIFACT_PATH;
+ try { rmSync(dir, { recursive: true, force: true }); } catch { /* ignore */ }
+ });
+
+ it('POSITIVE CONTROL: the same plugin lands three rows on a boot with no declaration composition', async () => {
+ const stack = await bootSchemaStack({
+ jsonOutput: false,
+ databaseUrl: `file:${dbFile}`,
+ deferSchemaDdl: true,
+ // No host composition ⇒ no declaration wrapper and no write guard. This
+ // is the leg that proves the fixture can write at all.
+ composeHostStack: false,
+ extraPlugins: [initWritingPlugin('control')],
+ projectRoot: dir,
+ });
+ try {
+ expect(await probeRows(stack.driver)).toBe(3);
+ const log = readFileSync(hookLog, 'utf8');
+ for (const phase of PHASES) expect(log).toContain(`control|write|${phase}`);
+ } finally {
+ await stack.shutdown();
+ }
+ }, 60_000);
+
+ it('THE FIX: the declaration boot lands none of them — from the host config or from anywhere else', async () => {
+ const before = await (async () => {
+ const s = await bootSchemaStack({
+ jsonOutput: false,
+ databaseUrl: `file:${dbFile}`,
+ deferSchemaDdl: true,
+ composeHostStack: false,
+ projectRoot: dir,
+ });
+ try { return await probeRows(s.driver); } finally { await s.shutdown(); }
+ })();
+ // The control's three rows are still there — this case measures a DELTA,
+ // not an empty table, so a fixture that silently stopped writing cannot
+ // pass it.
+ expect(before).toBe(3);
+
+ writeFileSync(hookLog, '');
+ const stack = await bootSchemaStack({
+ jsonOutput: false,
+ databaseUrl: `file:${dbFile}`,
+ deferSchemaDdl: true,
+ composeHostStack: true,
+ // Both routes at once: the host config's own plugin (composed through
+ // `composeForDeclarations`) and one handed straight to the kernel. The
+ // guard sits at the driver, so neither reaches the database.
+ extraPlugins: [initWritingPlugin('extra')],
+ projectRoot: dir,
+ });
+ try {
+ expect(await probeRows(stack.driver)).toBe(before);
+
+ const log = readFileSync(hookLog, 'utf8');
+
+ // The property (b) was chosen for: the hooks RAN — the log-only ones
+ // included — on the path an operator reads before a production apply.
+ for (const phase of PHASES) {
+ expect(log).toContain(`host|log-only|${phase}`);
+ expect(log).toContain(`extra|log-only|${phase}`);
+ // …and the writing hooks got all the way to their `create()` call,
+ // which returned instead of throwing: the line after it was reached.
+ expect(log).toContain(`host|write|${phase}`);
+ expect(log).toContain(`extra|write|${phase}`);
+ }
+
+ // The refusals are REPORTED, not swallowed — this is the line the plan
+ // prints and `--json` carries. No raw execute() went through on this
+ // boot, so the outcome claim HELD and is printed with the report.
+ const notes = stack.composition.notes.join(' ');
+ expect(notes).toContain('Refused 6 write(s) during the declaration boot — a plan writes nothing');
+ expect(notes).toContain('create() on sys_metadata');
+ } finally {
+ await stack.shutdown();
+ }
+ }, 60_000);
+
+ it('R1 (#14053): a raw execute() is FORWARDED — the row lands — and the run reports it instead of claiming it wrote nothing', async () => {
+ // The at-tier review's own control shape, pinned: in one guarded boot, a
+ // hook issues a contract write (refused — the in-run control) and a raw
+ // `execute("INSERT …")`. `execute()` is a REQUIRED member of `IDataDriver`
+ // (`packages/spec/src/contracts/data-driver.ts`, "Raw Execution (Escape
+ // Hatch)"), and the guard cannot classify a raw command as read-vs-write,
+ // so the row LANDS — that is the documented behaviour, not the defect.
+ // The defect was the SILENT half: before this case's fix, the same run
+ // printed "a plan writes nothing" and a refusal list that looked
+ // complete. Now the notes name the forwarded call and drop the claim.
+ const rawWritingPlugin: any = {
+ name: 'com.example.raw-execute-from-init',
+ version: '1.0.0',
+ init: async (ctx: any) => {
+ ctx.hook('kernel:ready', async () => {
+ const entry = [...ctx.getServices().entries()]
+ .find(([n]: [string, unknown]) => n.startsWith('driver.'));
+ if (!entry) return;
+ const driver = entry[1];
+ // In-run control: the guarded surface refuses this one.
+ await driver.create('sys_metadata', {
+ id: 'os14053-create-probe',
+ name: 'os14053-create-probe',
+ type: 'os14053_create_probe',
+ });
+ // The escape hatch: forwarded, so this one LANDS.
+ await driver.execute(
+ "INSERT INTO sys_metadata (id, name, type) VALUES "
+ + "('os14053-exec-probe', 'os14053-exec-probe', 'os14053_exec_probe')",
+ );
+ });
+ },
+ };
+
+ const stack = await bootSchemaStack({
+ jsonOutput: false,
+ databaseUrl: `file:${dbFile}`,
+ deferSchemaDdl: true,
+ composeHostStack: true,
+ extraPlugins: [rawWritingPlugin],
+ projectRoot: dir,
+ });
+ try {
+ const countByType = async (type: string) => {
+ const rows: any = await (stack.driver as any).knex('sys_metadata')
+ .where({ type }).count({ c: '*' });
+ return Number((Array.isArray(rows) ? rows[0] : rows)?.c ?? -1);
+ };
+ // The control half: the contract write was refused.
+ expect(await countByType('os14053_create_probe')).toBe(0);
+ // The escape hatch half: the raw INSERT landed — forwarded on purpose.
+ expect(await countByType('os14053_exec_probe')).toBe(1);
+
+ // …and the run SAYS so. The refusal line drops the flat claim (the
+ // colon directly after "boot" is the dropped phrase), the forwarded
+ // call is named with its count, and no note in the run claims the
+ // plan wrote nothing. 4 refusals: the host config's plugin on three
+ // phases, plus this fixture's in-run control.
+ const notes = stack.composition.notes.join(' ');
+ expect(notes).toContain('Refused 4 write(s) during the declaration boot:');
+ expect(notes).toContain('Raw execute() was called 1 time(s) during the declaration boot');
+ expect(notes).not.toContain('a plan writes nothing');
+
+ // The guard's structural surface carries it too, for `--json` consumers.
+ expect(stack.composition.writeGuard?.rawExecutions).toEqual([
+ expect.objectContaining({ count: 1 }),
+ ]);
+ } finally {
+ await stack.shutdown();
+ }
+ }, 60_000);
+});

packages/cli/src/utils/schema-migrate.ts

@@ -350,6 +350,18 @@ export async function bootSchemaStack(
  }
  await runtime.start();
 
+ // #13332 — the kernel bootstrap is over, and with it the window the
+ // declaration boot's write guard covers. `composeForDeclarations` suppresses
+ // a host plugin's `start()`, but `kernel.ts` fires `kernel:ready`,
+ // `kernel:bootstrapped` and `kernel:listening` unconditionally afterwards, so
+ // a hook REGISTERED from `init()` runs on a plan; the guard refuses those
+ // writes at the driver instead of at a list of phase names. Everything from
+ // this line on is work the command was ASKED for — `apply`'s confirmed DDL
+ // flush, the #13028 coverage pass — so the guard comes off here and reports
+ // whatever it refused, which the plan prints and `--json` carries.
+ const refusalNote = composition.writeGuard?.disarm() ?? null;
+ if (refusalNote) composition.notes.push(refusalNote);
+
  const driver = findSqlDriver(kernel);
 
  // #13028 — the composed host declared its objects in `init()`; the pass that

.changeset/declaration-boot-write-suppression.md

@@ -0,0 +1,73 @@
+---
+"@objectstack/cli": minor
+---
+
+fix(cli): make `os migrate plan`'s "writes nothing" a property of the mechanism, not of an unwritten host convention (#13332)
+
+`composeForDeclarations` documented the plan path's guarantee in its own words —
+*"(init runs, start does not — a plan writes nothing)"* — and implemented it as a
+Proxy whose only override is `start`. `packages/core/src/kernel.ts` then fires
+three phases unconditionally after the suppressed start pass: `kernel:ready`
+(Phase 3), `kernel:bootstrapped` (Phase 3.5) and `kernel:listening` (Phase 4). A
+writing hook **registered from `init()`** survives the suppression and executes
+on all three. The guarantee was therefore a property of plugins that happen to
+seed from `start()` — the shape of the one plugin that had been measured — and
+not of the plan path.
+
+Measured, twice. The module header records 14 `Insert operation failed` rows
+against `sys_permission_set` from a deferred `plan` boot, and notes that on a
+database whose tables already exist those inserts **succeed**: a command
+documented as writing nothing seeds rows into an operator's production control
+plane. Downstream, a control plane hit exactly this on the `apply=false` run
+that is its mandatory human review gate before a production schema apply
+(`driver.create` / `driver.update` on `sys_ai_model`, from an
+`init()`-registered `kernel:ready` hook).
+
+**What changed.** For the length of the kernel bootstrap, `os migrate plan` /
+`os migrate apply` now refuse the row-write members of the data-driver contract
+(`IDataDriver`: `create`, `update`, `upsert`, `delete`, `bulkCreate`,
+`bulkUpdate`, `bulkDelete`, `updateMany`, `deleteMany`) on every `driver.*`
+instance the kernel publishes. The refusal sits at the driver, not at a list of
+lifecycle phase names: it is phase-agnostic (a phase added tomorrow is covered
+on the day it ships), it covers writes that arrive through the ObjectQL engine
+as well as direct `driver.*` calls (the engine holds the same instance), and
+read/log-only hooks still run — which is what an operator reading a plan before
+a production apply needs them to do. A refused write returns a contract-shaped
+value rather than throwing (boot hooks dispatch propagating, so throwing would
+abort the bootstrap and leave the operator with no plan at all), and every
+refusal is reported: one warning on stderr per driver/method/object triple,
+plus a line in the composition notes the plan prints and `--json` carries.
+
+The contract's raw-execution escape hatch — `IDataDriver.execute()`, a required
+member on every driver — is FORWARDED and REPORTED rather than refused: a raw
+command is `unknown` by contract ("SQL string, shell command, or API payload"),
+and SQL text cannot be classified as read-vs-write reliably, so refusing would
+break boot-legitimate reads and the framework's own index DDL on a guess. A
+boot-window `execute()` is counted per driver, warned once per driver on
+stderr, and named in the composition notes — and on such a run the notes do
+NOT claim the plan wrote nothing, because the guard cannot verify it.
+
+The guard is disarmed the moment the bootstrap returns, so `os migrate apply`'s
+confirmed DDL flush and the coverage measurement are untouched.
+
+**Who this affects.** A host whose plugins write during a `plan`/`apply` boot
+from anywhere other than a suppressed `start()`. Contract row writes previously
+landed and now do not; the run says so. A host whose plugins call raw
+`execute()` during the boot keeps its behaviour (the call is forwarded) and
+now sees it reported. A host that did neither sees no change at all — no
+disarm note is emitted when nothing was refused and no raw command went
+through.
+
+Boundaries stated rather than hidden: `execute()` is reported, never refused
+(above); `getKnex()` (a driver-sql extension, genuinely off-contract) is not
+intercepted. DDL splits: `deferSchemaDdl` holds back the
+`initObjects`/`syncSchema` path (flushed on purpose by `apply` once the
+operator confirms), while `dropTable`/`rotateShards` are NOT held back by that
+deferral — they are gated only by `assertSchemaMutable`
+(schemaMode/dialect) and stay a genuinely open boundary during the boot.
+Drivers the engine holds for a NON-default datasource are never published as
+`driver.*` (`DatasourceConnectionService.connect()` hands them to
+`engine.registerDriver` directly), so they are invisible to the guard's scan
+and objectql-mediated writes to objects bound to them would land. The guard
+also does not cover writes a plugin makes outside the database, or work a hook
+defers past the end of the bootstrap.

packages/cli/src/utils/schema-migrate.host-composition.integration.test.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
 
 import { describe, it, expect, beforeAll, afterAll } from 'vitest';
-import { mkdtempSync, mkdirSync, writeFileSync, symlinkSync, rmSync } from 'node:fs';
+import { mkdtempSync, mkdirSync, writeFileSync, appendFileSync, readFileSync, symlinkSync, rmSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { tmpdir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
@@ -494,3 +494,295 @@ describe('a host that brings its OWN ObjectQL engine (#13028 — cloud\'s measur
  }
  }, 60_000);
 });
+
+/**
+ * #13332 — the same guarantee, end to end, against a real SQL driver.
+ *
+ * The unit half
+ * (`schema-migration-plugins.declaration-boot-write-guard.test.ts`) pins the
+ * mechanism on a recording driver. This half proves the property the operator
+ * actually depends on: `os migrate plan`'s boot, with a host plugin that
+ * registers a writing hook from `init()`, leaves the DATABASE unchanged — on a
+ * database whose tables already exist, which is the condition under which the
+ * measured inserts SUCCEED instead of failing.
+ *
+ * The positive control comes first and is load-bearing. The identical plugin,
+ * on a boot that composes no host stack (so no declaration composition and no
+ * write guard), lands its rows. Without that leg the assertion below would be
+ * green over a fixture that could not have written.
+ */
+describe('a plan writes nothing even when the host writes from init() (#13332)', () => {
+ let dir: string;
+ let dbFile: string;
+ let hookLog: string;
+ const savedEnv: Record<string, string | undefined> = {};
+
+ const PHASES = ['kernel:ready', 'kernel:bootstrapped', 'kernel:listening'] as const;
+
+ /**
+ * cloud's measured shape, as a plugin this file can hand to either boot: the
+ * writing hooks are registered from `init()`, so `composeForDeclarations`'s
+ * `start()` suppression never sees them, and they fire on each of the three
+ * phases `kernel.ts` triggers unconditionally after the suppressed pass.
+ *
+ * The driver is found by scanning `driver.*` — the same surface
+ * `ObjectQLPlugin`'s discovery loop reads — rather than by naming one, so the
+ * fixture does not depend on what the standalone stack calls its default.
+ */
+ const initWritingPlugin = (tag: string): any => ({
+ name: `com.example.writes-from-init.${tag}`,
+ version: '1.0.0',
+ init: async (ctx: any) => {
+ for (const phase of PHASES) {
+ ctx.hook(phase, async () => {
+ appendFileSync(hookLog, `${tag}|log-only|${phase}\n`);
+ });
+ ctx.hook(phase, async () => {
+ const services: Map<string, any> = ctx.getServices();
+ const entry = [...services.entries()].find(([n]) => n.startsWith('driver.'));
+ if (!entry) return;
+ await entry[1].create('sys_metadata', {
+ id: `os13332-${tag}-${phase}`,
+ name: `os13332-${tag}-${phase}`,
+ type: 'os13332_probe',
+ });
+ appendFileSync(hookLog, `${tag}|write|${phase}\n`);
+ });
+ }
+ },
+ });
+
+ const probeRows = async (driver: any): Promise<number> => {
+ const rows: any = await driver.knex('sys_metadata')
+ .where({ type: 'os13332_probe' })
+ .count({ c: '*' });
+ return Number((Array.isArray(rows) ? rows[0] : rows)?.c ?? -1);
+ };
+
+ beforeAll(async () => {
+ dir = mkdtempSync(join(tmpdir(), 'os-13332-'));
+ dbFile = join(dir, 'control.db');
+ hookLog = join(dir, 'hooks.log');
+ writeFileSync(hookLog, '');
+
+ savedEnv.NODE_ENV = process.env.NODE_ENV;
+ savedEnv.OS_ARTIFACT_PATH = process.env.OS_ARTIFACT_PATH;
+ process.env.NODE_ENV = 'production';
+ process.env.OS_ARTIFACT_PATH = join(dir, 'dist', 'objectstack.json');
+
+ // Materialize `sys_metadata` FIRST, with no host config on disk yet. The
+ // measured defect is precisely that on a database whose tables EXIST the
+ // inserts succeed rather than fail, so neither case below may run against
+ // an empty schema — and the fixture must not depend on the fix to build
+ // itself: with the guard ablated, a writing hook against a table that does
+ // not exist yet THROWS, and boot hooks dispatch propagating, so the whole
+ // bootstrap dies. Setting the schema up before the writer exists keeps an
+ // ablation landing on the assertions below instead of on this hook.
+ const boot = await bootSchemaStack({
+ jsonOutput: false,
+ databaseUrl: `file:${dbFile}`,
+ deferSchemaDdl: true,
+ composeHostStack: false,
+ projectRoot: dir,
+ });
+ try {
+ await boot.flushSchemaDdl();
+ } finally {
+ await boot.shutdown();
+ }
+
+ // A host config carrying the SAME plugin shape, so the composed path is
+ // exercised as an operator would hit it — the plugin comes out of
+ // `objectstack.config.ts`, through `composeForDeclarations`.
+ writeFileSync(
+ join(dir, 'objectstack.config.ts'),
+ [
+ "import { appendFileSync } from 'node:fs';",
+ '',
+ `const LOG = ${JSON.stringify(hookLog)};`,
+ "const PHASES = ['kernel:ready', 'kernel:bootstrapped', 'kernel:listening'];",
+ '',
+ 'export default {',
+ ' plugins: [{',
+ " name: 'com.example.host-writes-from-init',",
+ " version: '1.0.0',",
+ ' init: async (ctx: any) => {',
+ ' for (const phase of PHASES) {',
+ " ctx.hook(phase, async () => { appendFileSync(LOG, `host|log-only|${phase}\\n`); });",
+ ' ctx.hook(phase, async () => {',
+ ' const entry = [...ctx.getServices().entries()]',
+ " .find(([n]: [string, unknown]) => n.startsWith('driver.'));",
+ ' if (!entry) return;',
+ " await entry[1].create('sys_metadata', {",
+ ' id: `os13332-host-${phase}`,',
+ ' name: `os13332-host-${phase}`,',
+ " type: 'os13332_probe',",
+ ' });',
+ " appendFileSync(LOG, `host|write|${phase}\\n`);",
+ ' });',
+ ' }',
+ ' },',
+ ' }],',
+ '};',
+ '',
+ ].join('\n'),
+ );
+
+ writeFileSync(hookLog, '');
+ }, 60_000);
+
+ afterAll(() => {
+ if (savedEnv.NODE_ENV === undefined) delete process.env.NODE_ENV;
+ else process.env.NODE_ENV = savedEnv.NODE_ENV;
+ if (savedEnv.OS_ARTIFACT_PATH === undefined) delete process.env.OS_ARTIFACT_PATH;
+ else process.env.OS_ARTIFACT_PATH = savedEnv.OS_ARTIFACT_PATH;
+ try { rmSync(dir, { recursive: true, force: true }); } catch { /* ignore */ }
+ });
+
+ it('POSITIVE CONTROL: the same plugin lands three rows on a boot with no declaration composition', async () => {
+ const stack = await bootSchemaStack({
+ jsonOutput: false,
+ databaseUrl: `file:${dbFile}`,
+ deferSchemaDdl: true,
+ // No host composition ⇒ no declaration wrapper and no write guard. This
+ // is the leg that proves the fixture can write at all.
+ composeHostStack: false,
+ extraPlugins: [initWritingPlugin('control')],
+ projectRoot: dir,
+ });
+ try {
+ expect(await probeRows(stack.driver)).toBe(3);
+ const log = readFileSync(hookLog, 'utf8');
+ for (const phase of PHASES) expect(log).toContain(`control|write|${phase}`);
+ } finally {
+ await stack.shutdown();
+ }
+ }, 60_000);
+
+ it('THE FIX: the declaration boot lands none of them — from the host config or from anywhere else', async () => {
+ const before = await (async () => {
+ const s = await bootSchemaStack({
+ jsonOutput: false,
+ databaseUrl: `file:${dbFile}`,
+ deferSchemaDdl: true,
+ composeHostStack: false,
+ projectRoot: dir,
+ });
+ try { return await probeRows(s.driver); } finally { await s.shutdown(); }
+ })();
+ // The control's three rows are still there — this case measures a DELTA,
+ // not an empty table, so a fixture that silently stopped writing cannot
+ // pass it.
+ expect(before).toBe(3);
+
+ writeFileSync(hookLog, '');
+ const stack = await bootSchemaStack({
+ jsonOutput: false,
+ databaseUrl: `file:${dbFile}`,
+ deferSchemaDdl: true,
+ composeHostStack: true,
+ // Both routes at once: the host config's own plugin (composed through
+ // `composeForDeclarations`) and one handed straight to the kernel. The
+ // guard sits at the driver, so neither reaches the database.
+ extraPlugins: [initWritingPlugin('extra')],
+ projectRoot: dir,
+ });
+ try {
+ expect(await probeRows(stack.driver)).toBe(before);
+
+ const log = readFileSync(hookLog, 'utf8');
+
+ // The property (b) was chosen for: the hooks RAN — the log-only ones
+ // included — on the path an operator reads before a production apply.
+ for (const phase of PHASES) {
+ expect(log).toContain(`host|log-only|${phase}`);
+ expect(log).toContain(`extra|log-only|${phase}`);
+ // …and the writing hooks got all the way to their `create()` call,
+ // which returned instead of throwing: the line after it was reached.
+ expect(log).toContain(`host|write|${phase}`);
+ expect(log).toContain(`extra|write|${phase}`);
+ }
+
+ // The refusals are REPORTED, not swallowed — this is the line the plan
+ // prints and `--json` carries. No raw execute() went through on this
+ // boot, so the outcome claim HELD and is printed with the report.
+ const notes = stack.composition.notes.join(' ');
+ expect(notes).toContain('Refused 6 write(s) during the declaration boot — a plan writes nothing');
+ expect(notes).toContain('create() on sys_metadata');
+ } finally {
+ await stack.shutdown();
+ }
+ }, 60_000);
+
+ it('R1 (#14053): a raw execute() is FORWARDED — the row lands — and the run reports it instead of claiming it wrote nothing', async () => {
+ // The at-tier review's own control shape, pinned: in one guarded boot, a
+ // hook issues a contract write (refused — the in-run control) and a raw
+ // `execute("INSERT …")`. `execute()` is a REQUIRED member of `IDataDriver`
+ // (`packages/spec/src/contracts/data-driver.ts`, "Raw Execution (Escape
+ // Hatch)"), and the guard cannot classify a raw command as read-vs-write,
+ // so the row LANDS — that is the documented behaviour, not the defect.
+ // The defect was the SILENT half: before this case's fix, the same run
+ // printed "a plan writes nothing" and a refusal list that looked
+ // complete. Now the notes name the forwarded call and drop the claim.
+ const rawWritingPlugin: any = {
+ name: 'com.example.raw-execute-from-init',
+ version: '1.0.0',
+ init: async (ctx: any) => {
+ ctx.hook('kernel:ready', async () => {
+ const entry = [...ctx.getServices().entries()]
+ .find(([n]: [string, unknown]) => n.startsWith('driver.'));
+ if (!entry) return;
+ const driver = entry[1];
+ // In-run control: the guarded surface refuses this one.
+ await driver.create('sys_metadata', {
+ id: 'os14053-create-probe',
+ name: 'os14053-create-probe',
+ type: 'os14053_create_probe',
+ });
+ // The escape hatch: forwarded, so this one LANDS.
+ await driver.execute(
+ "INSERT INTO sys_metadata (id, name, type) VALUES "
+ + "('os14053-exec-probe', 'os14053-exec-probe', 'os14053_exec_probe')",
+ );
+ });
+ },
+ };
+
+ const stack = await bootSchemaStack({
+ jsonOutput: false,
+ databaseUrl: `file:${dbFile}`,
+ deferSchemaDdl: true,
+ composeHostStack: true,
+ extraPlugins: [rawWritingPlugin],
+ projectRoot: dir,
+ });
+ try {
+ const countByType = async (type: string) => {
+ const rows: any = await (stack.driver as any).knex('sys_metadata')
+ .where({ type }).count({ c: '*' });
+ return Number((Array.isArray(rows) ? rows[0] : rows)?.c ?? -1);
+ };
+ // The control half: the contract write was refused.
+ expect(await countByType('os14053_create_probe')).toBe(0);
+ // The escape hatch half: the raw INSERT landed — forwarded on purpose.
+ expect(await countByType('os14053_exec_probe')).toBe(1);
+
+ // …and the run SAYS so. The refusal line drops the flat claim (the
+ // colon directly after "boot" is the dropped phrase), the forwarded
+ // call is named with its count, and no note in the run claims the
+ // plan wrote nothing. 4 refusals: the host config's plugin on three
+ // phases, plus this fixture's in-run control.
+ const notes = stack.composition.notes.join(' ');
+ expect(notes).toContain('Refused 4 write(s) during the declaration boot:');
+ expect(notes).toContain('Raw execute() was called 1 time(s) during the declaration boot');
+ expect(notes).not.toContain('a plan writes nothing');
+
+ // The guard's structural surface carries it too, for `--json` consumers.
+ expect(stack.composition.writeGuard?.rawExecutions).toEqual([
+ expect.objectContaining({ count: 1 }),
+ ]);
+ } finally {
+ await stack.shutdown();
+ }
+ }, 60_000);
+});

packages/cli/src/utils/schema-migrate.ts

@@ -350,6 +350,18 @@ export async function bootSchemaStack(
  }
  await runtime.start();
 
+ // #13332 — the kernel bootstrap is over, and with it the window the
+ // declaration boot's write guard covers. `composeForDeclarations` suppresses
+ // a host plugin's `start()`, but `kernel.ts` fires `kernel:ready`,
+ // `kernel:bootstrapped` and `kernel:listening` unconditionally afterwards, so
+ // a hook REGISTERED from `init()` runs on a plan; the guard refuses those
+ // writes at the driver instead of at a list of phase names. Everything from
+ // this line on is work the command was ASKED for — `apply`'s confirmed DDL
+ // flush, the #13028 coverage pass — so the guard comes off here and reports
+ // whatever it refused, which the plan prints and `--json` carries.
+ const refusalNote = composition.writeGuard?.disarm() ?? null;
+ if (refusalNote) composition.notes.push(refusalNote);
+
  const driver = findSqlDriver(kernel);
 
  // #13028 — the composed host declared its objects in `init()`; the pass that

.changeset/declaration-boot-write-suppression.md

@@ -0,0 +1,73 @@
+---
+"@objectstack/cli": minor
+---
+
+fix(cli): make `os migrate plan`'s "writes nothing" a property of the mechanism, not of an unwritten host convention (#13332)
+
+`composeForDeclarations` documented the plan path's guarantee in its own words —
+*"(init runs, start does not — a plan writes nothing)"* — and implemented it as a
+Proxy whose only override is `start`. `packages/core/src/kernel.ts` then fires
+three phases unconditionally after the suppressed start pass: `kernel:ready`
+(Phase 3), `kernel:bootstrapped` (Phase 3.5) and `kernel:listening` (Phase 4). A
+writing hook **registered from `init()`** survives the suppression and executes
+on all three. The guarantee was therefore a property of plugins that happen to
+seed from `start()` — the shape of the one plugin that had been measured — and
+not of the plan path.
+
+Measured, twice. The module header records 14 `Insert operation failed` rows
+against `sys_permission_set` from a deferred `plan` boot, and notes that on a
+database whose tables already exist those inserts **succeed**: a command
+documented as writing nothing seeds rows into an operator's production control
+plane. Downstream, a control plane hit exactly this on the `apply=false` run
+that is its mandatory human review gate before a production schema apply
+(`driver.create` / `driver.update` on `sys_ai_model`, from an
+`init()`-registered `kernel:ready` hook).
+
+**What changed.** For the length of the kernel bootstrap, `os migrate plan` /
+`os migrate apply` now refuse the row-write members of the data-driver contract
+(`IDataDriver`: `create`, `update`, `upsert`, `delete`, `bulkCreate`,
+`bulkUpdate`, `bulkDelete`, `updateMany`, `deleteMany`) on every `driver.*`
+instance the kernel publishes. The refusal sits at the driver, not at a list of
+lifecycle phase names: it is phase-agnostic (a phase added tomorrow is covered
+on the day it ships), it covers writes that arrive through the ObjectQL engine
+as well as direct `driver.*` calls (the engine holds the same instance), and
+read/log-only hooks still run — which is what an operator reading a plan before
+a production apply needs them to do. A refused write returns a contract-shaped
+value rather than throwing (boot hooks dispatch propagating, so throwing would
+abort the bootstrap and leave the operator with no plan at all), and every
+refusal is reported: one warning on stderr per driver/method/object triple,
+plus a line in the composition notes the plan prints and `--json` carries.
+
+The contract's raw-execution escape hatch — `IDataDriver.execute()`, a required
+member on every driver — is FORWARDED and REPORTED rather than refused: a raw
+command is `unknown` by contract ("SQL string, shell command, or API payload"),
+and SQL text cannot be classified as read-vs-write reliably, so refusing would
+break boot-legitimate reads and the framework's own index DDL on a guess. A
+boot-window `execute()` is counted per driver, warned once per driver on
+stderr, and named in the composition notes — and on such a run the notes do
+NOT claim the plan wrote nothing, because the guard cannot verify it.
+
+The guard is disarmed the moment the bootstrap returns, so `os migrate apply`'s
+confirmed DDL flush and the coverage measurement are untouched.
+
+**Who this affects.** A host whose plugins write during a `plan`/`apply` boot
+from anywhere other than a suppressed `start()`. Contract row writes previously
+landed and now do not; the run says so. A host whose plugins call raw
+`execute()` during the boot keeps its behaviour (the call is forwarded) and
+now sees it reported. A host that did neither sees no change at all — no
+disarm note is emitted when nothing was refused and no raw command went
+through.
+
+Boundaries stated rather than hidden: `execute()` is reported, never refused
+(above); `getKnex()` (a driver-sql extension, genuinely off-contract) is not
+intercepted. DDL splits: `deferSchemaDdl` holds back the
+`initObjects`/`syncSchema` path (flushed on purpose by `apply` once the
+operator confirms), while `dropTable`/`rotateShards` are NOT held back by that
+deferral — they are gated only by `assertSchemaMutable`
+(schemaMode/dialect) and stay a genuinely open boundary during the boot.
+Drivers the engine holds for a NON-default datasource are never published as
+`driver.*` (`DatasourceConnectionService.connect()` hands them to
+`engine.registerDriver` directly), so they are invisible to the guard's scan
+and objectql-mediated writes to objects bound to them would land. The guard
+also does not cover writes a plugin makes outside the database, or work a hook
+defers past the end of the bootstrap.

packages/cli/src/utils/schema-migrate.host-composition.integration.test.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
 
 import { describe, it, expect, beforeAll, afterAll } from 'vitest';
-import { mkdtempSync, mkdirSync, writeFileSync, symlinkSync, rmSync } from 'node:fs';
+import { mkdtempSync, mkdirSync, writeFileSync, appendFileSync, readFileSync, symlinkSync, rmSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { tmpdir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
@@ -494,3 +494,295 @@ describe('a host that brings its OWN ObjectQL engine (#13028 — cloud\'s measur
  }
  }, 60_000);
 });
+
+/**
+ * #13332 — the same guarantee, end to end, against a real SQL driver.
+ *
+ * The unit half
+ * (`schema-migration-plugins.declaration-boot-write-guard.test.ts`) pins the
+ * mechanism on a recording driver. This half proves the property the operator
+ * actually depends on: `os migrate plan`'s boot, with a host plugin that
+ * registers a writing hook from `init()`, leaves the DATABASE unchanged — on a
+ * database whose tables already exist, which is the condition under which the
+ * measured inserts SUCCEED instead of failing.
+ *
+ * The positive control comes first and is load-bearing. The identical plugin,
+ * on a boot that composes no host stack (so no declaration composition and no
+ * write guard), lands its rows. Without that leg the assertion below would be
+ * green over a fixture that could not have written.
+ */
+describe('a plan writes nothing even when the host writes from init() (#13332)', () => {
+ let dir: string;
+ let dbFile: string;
+ let hookLog: string;
+ const savedEnv: Record<string, string | undefined> = {};
+
+ const PHASES = ['kernel:ready', 'kernel:bootstrapped', 'kernel:listening'] as const;
+
+ /**
+ * cloud's measured shape, as a plugin this file can hand to either boot: the
+ * writing hooks are registered from `init()`, so `composeForDeclarations`'s
+ * `start()` suppression never sees them, and they fire on each of the three
+ * phases `kernel.ts` triggers unconditionally after the suppressed pass.
+ *
+ * The driver is found by scanning `driver.*` — the same surface
+ * `ObjectQLPlugin`'s discovery loop reads — rather than by naming one, so the
+ * fixture does not depend on what the standalone stack calls its default.
+ */
+ const initWritingPlugin = (tag: string): any => ({
+ name: `com.example.writes-from-init.${tag}`,
+ version: '1.0.0',
+ init: async (ctx: any) => {
+ for (const phase of PHASES) {
+ ctx.hook(phase, async () => {
+ appendFileSync(hookLog, `${tag}|log-only|${phase}\n`);
+ });
+ ctx.hook(phase, async () => {
+ const services: Map<string, any> = ctx.getServices();
+ const entry = [...services.entries()].find(([n]) => n.startsWith('driver.'));
+ if (!entry) return;
+ await entry[1].create('sys_metadata', {
+ id: `os13332-${tag}-${phase}`,
+ name: `os13332-${tag}-${phase}`,
+ type: 'os13332_probe',
+ });
+ appendFileSync(hookLog, `${tag}|write|${phase}\n`);
+ });
+ }
+ },
+ });
+
+ const probeRows = async (driver: any): Promise<number> => {
+ const rows: any = await driver.knex('sys_metadata')
+ .where({ type: 'os13332_probe' })
+ .count({ c: '*' });
+ return Number((Array.isArray(rows) ? rows[0] : rows)?.c ?? -1);
+ };
+
+ beforeAll(async () => {
+ dir = mkdtempSync(join(tmpdir(), 'os-13332-'));
+ dbFile = join(dir, 'control.db');
+ hookLog = join(dir, 'hooks.log');
+ writeFileSync(hookLog, '');
+
+ savedEnv.NODE_ENV = process.env.NODE_ENV;
+ savedEnv.OS_ARTIFACT_PATH = process.env.OS_ARTIFACT_PATH;
+ process.env.NODE_ENV = 'production';
+ process.env.OS_ARTIFACT_PATH = join(dir, 'dist', 'objectstack.json');
+
+ // Materialize `sys_metadata` FIRST, with no host config on disk yet. The
+ // measured defect is precisely that on a database whose tables EXIST the
+ // inserts succeed rather than fail, so neither case below may run against
+ // an empty schema — and the fixture must not depend on the fix to build
+ // itself: with the guard ablated, a writing hook against a table that does
+ // not exist yet THROWS, and boot hooks dispatch propagating, so the whole
+ // bootstrap dies. Setting the schema up before the writer exists keeps an
+ // ablation landing on the assertions below instead of on this hook.
+ const boot = await bootSchemaStack({
+ jsonOutput: false,
+ databaseUrl: `file:${dbFile}`,
+ deferSchemaDdl: true,
+ composeHostStack: false,
+ projectRoot: dir,
+ });
+ try {
+ await boot.flushSchemaDdl();
+ } finally {
+ await boot.shutdown();
+ }
+
+ // A host config carrying the SAME plugin shape, so the composed path is
+ // exercised as an operator would hit it — the plugin comes out of
+ // `objectstack.config.ts`, through `composeForDeclarations`.
+ writeFileSync(
+ join(dir, 'objectstack.config.ts'),
+ [
+ "import { appendFileSync } from 'node:fs';",
+ '',
+ `const LOG = ${JSON.stringify(hookLog)};`,
+ "const PHASES = ['kernel:ready', 'kernel:bootstrapped', 'kernel:listening'];",
+ '',
+ 'export default {',
+ ' plugins: [{',
+ " name: 'com.example.host-writes-from-init',",
+ " version: '1.0.0',",
+ ' init: async (ctx: any) => {',
+ ' for (const phase of PHASES) {',
+ " ctx.hook(phase, async () => { appendFileSync(LOG, `host|log-only|${phase}\\n`); });",
+ ' ctx.hook(phase, async () => {',
+ ' const entry = [...ctx.getServices().entries()]',
+ " .find(([n]: [string, unknown]) => n.startsWith('driver.'));",
+ ' if (!entry) return;',
+ " await entry[1].create('sys_metadata', {",
+ ' id: `os13332-host-${phase}`,',
+ ' name: `os13332-host-${phase}`,',
+ " type: 'os13332_probe',",
+ ' });',
+ " appendFileSync(LOG, `host|write|${phase}\\n`);",
+ ' });',
+ ' }',
+ ' },',
+ ' }],',
+ '};',
+ '',
+ ].join('\n'),
+ );
+
+ writeFileSync(hookLog, '');
+ }, 60_000);
+
+ afterAll(() => {
+ if (savedEnv.NODE_ENV === undefined) delete process.env.NODE_ENV;
+ else process.env.NODE_ENV = savedEnv.NODE_ENV;
+ if (savedEnv.OS_ARTIFACT_PATH === undefined) delete process.env.OS_ARTIFACT_PATH;
+ else process.env.OS_ARTIFACT_PATH = savedEnv.OS_ARTIFACT_PATH;
+ try { rmSync(dir, { recursive: true, force: true }); } catch { /* ignore */ }
+ });
+
+ it('POSITIVE CONTROL: the same plugin lands three rows on a boot with no declaration composition', async () => {
+ const stack = await bootSchemaStack({
+ jsonOutput: false,
+ databaseUrl: `file:${dbFile}`,
+ deferSchemaDdl: true,
+ // No host composition ⇒ no declaration wrapper and no write guard. This
+ // is the leg that proves the fixture can write at all.
+ composeHostStack: false,
+ extraPlugins: [initWritingPlugin('control')],
+ projectRoot: dir,
+ });
+ try {
+ expect(await probeRows(stack.driver)).toBe(3);
+ const log = readFileSync(hookLog, 'utf8');
+ for (const phase of PHASES) expect(log).toContain(`control|write|${phase}`);
+ } finally {
+ await stack.shutdown();
+ }
+ }, 60_000);
+
+ it('THE FIX: the declaration boot lands none of them — from the host config or from anywhere else', async () => {
+ const before = await (async () => {
+ const s = await bootSchemaStack({
+ jsonOutput: false,
+ databaseUrl: `file:${dbFile}`,
+ deferSchemaDdl: true,
+ composeHostStack: false,
+ projectRoot: dir,
+ });
+ try { return await probeRows(s.driver); } finally { await s.shutdown(); }
+ })();
+ // The control's three rows are still there — this case measures a DELTA,
+ // not an empty table, so a fixture that silently stopped writing cannot
+ // pass it.
+ expect(before).toBe(3);
+
+ writeFileSync(hookLog, '');
+ const stack = await bootSchemaStack({
+ jsonOutput: false,
+ databaseUrl: `file:${dbFile}`,
+ deferSchemaDdl: true,
+ composeHostStack: true,
+ // Both routes at once: the host config's own plugin (composed through
+ // `composeForDeclarations`) and one handed straight to the kernel. The
+ // guard sits at the driver, so neither reaches the database.
+ extraPlugins: [initWritingPlugin('extra')],
+ projectRoot: dir,
+ });
+ try {
+ expect(await probeRows(stack.driver)).toBe(before);
+
+ const log = readFileSync(hookLog, 'utf8');
+
+ // The property (b) was chosen for: the hooks RAN — the log-only ones
+ // included — on the path an operator reads before a production apply.
+ for (const phase of PHASES) {
+ expect(log).toContain(`host|log-only|${phase}`);
+ expect(log).toContain(`extra|log-only|${phase}`);
+ // …and the writing hooks got all the way to their `create()` call,
+ // which returned instead of throwing: the line after it was reached.
+ expect(log).toContain(`host|write|${phase}`);
+ expect(log).toContain(`extra|write|${phase}`);
+ }
+
+ // The refusals are REPORTED, not swallowed — this is the line the plan
+ // prints and `--json` carries. No raw execute() went through on this
+ // boot, so the outcome claim HELD and is printed with the report.
+ const notes = stack.composition.notes.join(' ');
+ expect(notes).toContain('Refused 6 write(s) during the declaration boot — a plan writes nothing');
+ expect(notes).toContain('create() on sys_metadata');
+ } finally {
+ await stack.shutdown();
+ }
+ }, 60_000);
+
+ it('R1 (#14053): a raw execute() is FORWARDED — the row lands — and the run reports it instead of claiming it wrote nothing', async () => {
+ // The at-tier review's own control shape, pinned: in one guarded boot, a
+ // hook issues a contract write (refused — the in-run control) and a raw
+ // `execute("INSERT …")`. `execute()` is a REQUIRED member of `IDataDriver`
+ // (`packages/spec/src/contracts/data-driver.ts`, "Raw Execution (Escape
+ // Hatch)"), and the guard cannot classify a raw command as read-vs-write,
+ // so the row LANDS — that is the documented behaviour, not the defect.
+ // The defect was the SILENT half: before this case's fix, the same run
+ // printed "a plan writes nothing" and a refusal list that looked
+ // complete. Now the notes name the forwarded call and drop the claim.
+ const rawWritingPlugin: any = {
+ name: 'com.example.raw-execute-from-init',
+ version: '1.0.0',
+ init: async (ctx: any) => {
+ ctx.hook('kernel:ready', async () => {
+ const entry = [...ctx.getServices().entries()]
+ .find(([n]: [string, unknown]) => n.startsWith('driver.'));
+ if (!entry) return;
+ const driver = entry[1];
+ // In-run control: the guarded surface refuses this one.
+ await driver.create('sys_metadata', {
+ id: 'os14053-create-probe',
+ name: 'os14053-create-probe',
+ type: 'os14053_create_probe',
+ });
+ // The escape hatch: forwarded, so this one LANDS.
+ await driver.execute(
+ "INSERT INTO sys_metadata (id, name, type) VALUES "
+ + "('os14053-exec-probe', 'os14053-exec-probe', 'os14053_exec_probe')",
+ );
+ });
+ },
+ };
+
+ const stack = await bootSchemaStack({
+ jsonOutput: false,
+ databaseUrl: `file:${dbFile}`,
+ deferSchemaDdl: true,
+ composeHostStack: true,
+ extraPlugins: [rawWritingPlugin],
+ projectRoot: dir,
+ });
+ try {
+ const countByType = async (type: string) => {
+ const rows: any = await (stack.driver as any).knex('sys_metadata')
+ .where({ type }).count({ c: '*' });
+ return Number((Array.isArray(rows) ? rows[0] : rows)?.c ?? -1);
+ };
+ // The control half: the contract write was refused.
+ expect(await countByType('os14053_create_probe')).toBe(0);
+ // The escape hatch half: the raw INSERT landed — forwarded on purpose.
+ expect(await countByType('os14053_exec_probe')).toBe(1);
+
+ // …and the run SAYS so. The refusal line drops the flat claim (the
+ // colon directly after "boot" is the dropped phrase), the forwarded
+ // call is named with its count, and no note in the run claims the
+ // plan wrote nothing. 4 refusals: the host config's plugin on three
+ // phases, plus this fixture's in-run control.
+ const notes = stack.composition.notes.join(' ');
+ expect(notes).toContain('Refused 4 write(s) during the declaration boot:');
+ expect(notes).toContain('Raw execute() was called 1 time(s) during the declaration boot');
+ expect(notes).not.toContain('a plan writes nothing');
+
+ // The guard's structural surface carries it too, for `--json` consumers.
+ expect(stack.composition.writeGuard?.rawExecutions).toEqual([
+ expect.objectContaining({ count: 1 }),
+ ]);
+ } finally {
+ await stack.shutdown();
+ }
+ }, 60_000);
+});

packages/cli/src/utils/schema-migrate.ts

@@ -350,6 +350,18 @@ export async function bootSchemaStack(
  }
  await runtime.start();
 
+ // #13332 — the kernel bootstrap is over, and with it the window the
+ // declaration boot's write guard covers. `composeForDeclarations` suppresses
+ // a host plugin's `start()`, but `kernel.ts` fires `kernel:ready`,
+ // `kernel:bootstrapped` and `kernel:listening` unconditionally afterwards, so
+ // a hook REGISTERED from `init()` runs on a plan; the guard refuses those
+ // writes at the driver instead of at a list of phase names. Everything from
+ // this line on is work the command was ASKED for — `apply`'s confirmed DDL
+ // flush, the #13028 coverage pass — so the guard comes off here and reports
+ // whatever it refused, which the plan prints and `--json` carries.
+ const refusalNote = composition.writeGuard?.disarm() ?? null;
+ if (refusalNote) composition.notes.push(refusalNote);
+
  const driver = findSqlDriver(kernel);
 
  // #13028 — the composed host declared its objects in `init()`; the pass that

.changeset/declaration-boot-write-suppression.md

@@ -0,0 +1,73 @@
+---
+"@objectstack/cli": minor
+---
+
+fix(cli): make `os migrate plan`'s "writes nothing" a property of the mechanism, not of an unwritten host convention (#13332)
+
+`composeForDeclarations` documented the plan path's guarantee in its own words —
+*"(init runs, start does not — a plan writes nothing)"* — and implemented it as a
+Proxy whose only override is `start`. `packages/core/src/kernel.ts` then fires
+three phases unconditionally after the suppressed start pass: `kernel:ready`
+(Phase 3), `kernel:bootstrapped` (Phase 3.5) and `kernel:listening` (Phase 4). A
+writing hook **registered from `init()`** survives the suppression and executes
+on all three. The guarantee was therefore a property of plugins that happen to
+seed from `start()` — the shape of the one plugin that had been measured — and
+not of the plan path.
+
+Measured, twice. The module header records 14 `Insert operation failed` rows
+against `sys_permission_set` from a deferred `plan` boot, and notes that on a
+database whose tables already exist those inserts **succeed**: a command
+documented as writing nothing seeds rows into an operator's production control
+plane. Downstream, a control plane hit exactly this on the `apply=false` run
+that is its mandatory human review gate before a production schema apply
+(`driver.create` / `driver.update` on `sys_ai_model`, from an
+`init()`-registered `kernel:ready` hook).
+
+**What changed.** For the length of the kernel bootstrap, `os migrate plan` /
+`os migrate apply` now refuse the row-write members of the data-driver contract
+(`IDataDriver`: `create`, `update`, `upsert`, `delete`, `bulkCreate`,
+`bulkUpdate`, `bulkDelete`, `updateMany`, `deleteMany`) on every `driver.*`
+instance the kernel publishes. The refusal sits at the driver, not at a list of
+lifecycle phase names: it is phase-agnostic (a phase added tomorrow is covered
+on the day it ships), it covers writes that arrive through the ObjectQL engine
+as well as direct `driver.*` calls (the engine holds the same instance), and
+read/log-only hooks still run — which is what an operator reading a plan before
+a production apply needs them to do. A refused write returns a contract-shaped
+value rather than throwing (boot hooks dispatch propagating, so throwing would
+abort the bootstrap and leave the operator with no plan at all), and every
+refusal is reported: one warning on stderr per driver/method/object triple,
+plus a line in the composition notes the plan prints and `--json` carries.
+
+The contract's raw-execution escape hatch — `IDataDriver.execute()`, a required
+member on every driver — is FORWARDED and REPORTED rather than refused: a raw
+command is `unknown` by contract ("SQL string, shell command, or API payload"),
+and SQL text cannot be classified as read-vs-write reliably, so refusing would
+break boot-legitimate reads and the framework's own index DDL on a guess. A
+boot-window `execute()` is counted per driver, warned once per driver on
+stderr, and named in the composition notes — and on such a run the notes do
+NOT claim the plan wrote nothing, because the guard cannot verify it.
+
+The guard is disarmed the moment the bootstrap returns, so `os migrate apply`'s
+confirmed DDL flush and the coverage measurement are untouched.
+
+**Who this affects.** A host whose plugins write during a `plan`/`apply` boot
+from anywhere other than a suppressed `start()`. Contract row writes previously
+landed and now do not; the run says so. A host whose plugins call raw
+`execute()` during the boot keeps its behaviour (the call is forwarded) and
+now sees it reported. A host that did neither sees no change at all — no
+disarm note is emitted when nothing was refused and no raw command went
+through.
+
+Boundaries stated rather than hidden: `execute()` is reported, never refused
+(above); `getKnex()` (a driver-sql extension, genuinely off-contract) is not
+intercepted. DDL splits: `deferSchemaDdl` holds back the
+`initObjects`/`syncSchema` path (flushed on purpose by `apply` once the
+operator confirms), while `dropTable`/`rotateShards` are NOT held back by that
+deferral — they are gated only by `assertSchemaMutable`
+(schemaMode/dialect) and stay a genuinely open boundary during the boot.
+Drivers the engine holds for a NON-default datasource are never published as
+`driver.*` (`DatasourceConnectionService.connect()` hands them to
+`engine.registerDriver` directly), so they are invisible to the guard's scan
+and objectql-mediated writes to objects bound to them would land. The guard
+also does not cover writes a plugin makes outside the database, or work a hook
+defers past the end of the bootstrap.

packages/cli/src/utils/schema-migrate.host-composition.integration.test.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
 
 import { describe, it, expect, beforeAll, afterAll } from 'vitest';
-import { mkdtempSync, mkdirSync, writeFileSync, symlinkSync, rmSync } from 'node:fs';
+import { mkdtempSync, mkdirSync, writeFileSync, appendFileSync, readFileSync, symlinkSync, rmSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { tmpdir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
@@ -494,3 +494,295 @@ describe('a host that brings its OWN ObjectQL engine (#13028 — cloud\'s measur
  }
  }, 60_000);
 });
+
+/**
+ * #13332 — the same guarantee, end to end, against a real SQL driver.
+ *
+ * The unit half
+ * (`schema-migration-plugins.declaration-boot-write-guard.test.ts`) pins the
+ * mechanism on a recording driver. This half proves the property the operator
+ * actually depends on: `os migrate plan`'s boot, with a host plugin that
+ * registers a writing hook from `init()`, leaves the DATABASE unchanged — on a
+ * database whose tables already exist, which is the condition under which the
+ * measured inserts SUCCEED instead of failing.
+ *
+ * The positive control comes first and is load-bearing. The identical plugin,
+ * on a boot that composes no host stack (so no declaration composition and no
+ * write guard), lands its rows. Without that leg the assertion below would be
+ * green over a fixture that could not have written.
+ */
+describe('a plan writes nothing even when the host writes from init() (#13332)', () => {
+ let dir: string;
+ let dbFile: string;
+ let hookLog: string;
+ const savedEnv: Record<string, string | undefined> = {};
+
+ const PHASES = ['kernel:ready', 'kernel:bootstrapped', 'kernel:listening'] as const;
+
+ /**
+ * cloud's measured shape, as a plugin this file can hand to either boot: the
+ * writing hooks are registered from `init()`, so `composeForDeclarations`'s
+ * `start()` suppression never sees them, and they fire on each of the three
+ * phases `kernel.ts` triggers unconditionally after the suppressed pass.
+ *
+ * The driver is found by scanning `driver.*` — the same surface
+ * `ObjectQLPlugin`'s discovery loop reads — rather than by naming one, so the
+ * fixture does not depend on what the standalone stack calls its default.
+ */
+ const initWritingPlugin = (tag: string): any => ({
+ name: `com.example.writes-from-init.${tag}`,
+ version: '1.0.0',
+ init: async (ctx: any) => {
+ for (const phase of PHASES) {
+ ctx.hook(phase, async () => {
+ appendFileSync(hookLog, `${tag}|log-only|${phase}\n`);
+ });
+ ctx.hook(phase, async () => {
+ const services: Map<string, any> = ctx.getServices();
+ const entry = [...services.entries()].find(([n]) => n.startsWith('driver.'));
+ if (!entry) return;
+ await entry[1].create('sys_metadata', {
+ id: `os13332-${tag}-${phase}`,
+ name: `os13332-${tag}-${phase}`,
+ type: 'os13332_probe',
+ });
+ appendFileSync(hookLog, `${tag}|write|${phase}\n`);
+ });
+ }
+ },
+ });
+
+ const probeRows = async (driver: any): Promise<number> => {
+ const rows: any = await driver.knex('sys_metadata')
+ .where({ type: 'os13332_probe' })
+ .count({ c: '*' });
+ return Number((Array.isArray(rows) ? rows[0] : rows)?.c ?? -1);
+ };
+
+ beforeAll(async () => {
+ dir = mkdtempSync(join(tmpdir(), 'os-13332-'));
+ dbFile = join(dir, 'control.db');
+ hookLog = join(dir, 'hooks.log');
+ writeFileSync(hookLog, '');
+
+ savedEnv.NODE_ENV = process.env.NODE_ENV;
+ savedEnv.OS_ARTIFACT_PATH = process.env.OS_ARTIFACT_PATH;
+ process.env.NODE_ENV = 'production';
+ process.env.OS_ARTIFACT_PATH = join(dir, 'dist', 'objectstack.json');
+
+ // Materialize `sys_metadata` FIRST, with no host config on disk yet. The
+ // measured defect is precisely that on a database whose tables EXIST the
+ // inserts succeed rather than fail, so neither case below may run against
+ // an empty schema — and the fixture must not depend on the fix to build
+ // itself: with the guard ablated, a writing hook against a table that does
+ // not exist yet THROWS, and boot hooks dispatch propagating, so the whole
+ // bootstrap dies. Setting the schema up before the writer exists keeps an
+ // ablation landing on the assertions below instead of on this hook.
+ const boot = await bootSchemaStack({
+ jsonOutput: false,
+ databaseUrl: `file:${dbFile}`,
+ deferSchemaDdl: true,
+ composeHostStack: false,
+ projectRoot: dir,
+ });
+ try {
+ await boot.flushSchemaDdl();
+ } finally {
+ await boot.shutdown();
+ }
+
+ // A host config carrying the SAME plugin shape, so the composed path is
+ // exercised as an operator would hit it — the plugin comes out of
+ // `objectstack.config.ts`, through `composeForDeclarations`.
+ writeFileSync(
+ join(dir, 'objectstack.config.ts'),
+ [
+ "import { appendFileSync } from 'node:fs';",
+ '',
+ `const LOG = ${JSON.stringify(hookLog)};`,
+ "const PHASES = ['kernel:ready', 'kernel:bootstrapped', 'kernel:listening'];",
+ '',
+ 'export default {',
+ ' plugins: [{',
+ " name: 'com.example.host-writes-from-init',",
+ " version: '1.0.0',",
+ ' init: async (ctx: any) => {',
+ ' for (const phase of PHASES) {',
+ " ctx.hook(phase, async () => { appendFileSync(LOG, `host|log-only|${phase}\\n`); });",
+ ' ctx.hook(phase, async () => {',
+ ' const entry = [...ctx.getServices().entries()]',
+ " .find(([n]: [string, unknown]) => n.startsWith('driver.'));",
+ ' if (!entry) return;',
+ " await entry[1].create('sys_metadata', {",
+ ' id: `os13332-host-${phase}`,',
+ ' name: `os13332-host-${phase}`,',
+ " type: 'os13332_probe',",
+ ' });',
+ " appendFileSync(LOG, `host|write|${phase}\\n`);",
+ ' });',
+ ' }',
+ ' },',
+ ' }],',
+ '};',
+ '',
+ ].join('\n'),
+ );
+
+ writeFileSync(hookLog, '');
+ }, 60_000);
+
+ afterAll(() => {
+ if (savedEnv.NODE_ENV === undefined) delete process.env.NODE_ENV;
+ else process.env.NODE_ENV = savedEnv.NODE_ENV;
+ if (savedEnv.OS_ARTIFACT_PATH === undefined) delete process.env.OS_ARTIFACT_PATH;
+ else process.env.OS_ARTIFACT_PATH = savedEnv.OS_ARTIFACT_PATH;
+ try { rmSync(dir, { recursive: true, force: true }); } catch { /* ignore */ }
+ });
+
+ it('POSITIVE CONTROL: the same plugin lands three rows on a boot with no declaration composition', async () => {
+ const stack = await bootSchemaStack({
+ jsonOutput: false,
+ databaseUrl: `file:${dbFile}`,
+ deferSchemaDdl: true,
+ // No host composition ⇒ no declaration wrapper and no write guard. This
+ // is the leg that proves the fixture can write at all.
+ composeHostStack: false,
+ extraPlugins: [initWritingPlugin('control')],
+ projectRoot: dir,
+ });
+ try {
+ expect(await probeRows(stack.driver)).toBe(3);
+ const log = readFileSync(hookLog, 'utf8');
+ for (const phase of PHASES) expect(log).toContain(`control|write|${phase}`);
+ } finally {
+ await stack.shutdown();
+ }
+ }, 60_000);
+
+ it('THE FIX: the declaration boot lands none of them — from the host config or from anywhere else', async () => {
+ const before = await (async () => {
+ const s = await bootSchemaStack({
+ jsonOutput: false,
+ databaseUrl: `file:${dbFile}`,
+ deferSchemaDdl: true,
+ composeHostStack: false,
+ projectRoot: dir,
+ });
+ try { return await probeRows(s.driver); } finally { await s.shutdown(); }
+ })();
+ // The control's three rows are still there — this case measures a DELTA,
+ // not an empty table, so a fixture that silently stopped writing cannot
+ // pass it.
+ expect(before).toBe(3);
+
+ writeFileSync(hookLog, '');
+ const stack = await bootSchemaStack({
+ jsonOutput: false,
+ databaseUrl: `file:${dbFile}`,
+ deferSchemaDdl: true,
+ composeHostStack: true,
+ // Both routes at once: the host config's own plugin (composed through
+ // `composeForDeclarations`) and one handed straight to the kernel. The
+ // guard sits at the driver, so neither reaches the database.
+ extraPlugins: [initWritingPlugin('extra')],
+ projectRoot: dir,
+ });
+ try {
+ expect(await probeRows(stack.driver)).toBe(before);
+
+ const log = readFileSync(hookLog, 'utf8');
+
+ // The property (b) was chosen for: the hooks RAN — the log-only ones
+ // included — on the path an operator reads before a production apply.
+ for (const phase of PHASES) {
+ expect(log).toContain(`host|log-only|${phase}`);
+ expect(log).toContain(`extra|log-only|${phase}`);
+ // …and the writing hooks got all the way to their `create()` call,
+ // which returned instead of throwing: the line after it was reached.
+ expect(log).toContain(`host|write|${phase}`);
+ expect(log).toContain(`extra|write|${phase}`);
+ }
+
+ // The refusals are REPORTED, not swallowed — this is the line the plan
+ // prints and `--json` carries. No raw execute() went through on this
+ // boot, so the outcome claim HELD and is printed with the report.
+ const notes = stack.composition.notes.join(' ');
+ expect(notes).toContain('Refused 6 write(s) during the declaration boot — a plan writes nothing');
+ expect(notes).toContain('create() on sys_metadata');
+ } finally {
+ await stack.shutdown();
+ }
+ }, 60_000);
+
+ it('R1 (#14053): a raw execute() is FORWARDED — the row lands — and the run reports it instead of claiming it wrote nothing', async () => {
+ // The at-tier review's own control shape, pinned: in one guarded boot, a
+ // hook issues a contract write (refused — the in-run control) and a raw
+ // `execute("INSERT …")`. `execute()` is a REQUIRED member of `IDataDriver`
+ // (`packages/spec/src/contracts/data-driver.ts`, "Raw Execution (Escape
+ // Hatch)"), and the guard cannot classify a raw command as read-vs-write,
+ // so the row LANDS — that is the documented behaviour, not the defect.
+ // The defect was the SILENT half: before this case's fix, the same run
+ // printed "a plan writes nothing" and a refusal list that looked
+ // complete. Now the notes name the forwarded call and drop the claim.
+ const rawWritingPlugin: any = {
+ name: 'com.example.raw-execute-from-init',
+ version: '1.0.0',
+ init: async (ctx: any) => {
+ ctx.hook('kernel:ready', async () => {
+ const entry = [...ctx.getServices().entries()]
+ .find(([n]: [string, unknown]) => n.startsWith('driver.'));
+ if (!entry) return;
+ const driver = entry[1];
+ // In-run control: the guarded surface refuses this one.
+ await driver.create('sys_metadata', {
+ id: 'os14053-create-probe',
+ name: 'os14053-create-probe',
+ type: 'os14053_create_probe',
+ });
+ // The escape hatch: forwarded, so this one LANDS.
+ await driver.execute(
+ "INSERT INTO sys_metadata (id, name, type) VALUES "
+ + "('os14053-exec-probe', 'os14053-exec-probe', 'os14053_exec_probe')",
+ );
+ });
+ },
+ };
+
+ const stack = await bootSchemaStack({
+ jsonOutput: false,
+ databaseUrl: `file:${dbFile}`,
+ deferSchemaDdl: true,
+ composeHostStack: true,
+ extraPlugins: [rawWritingPlugin],
+ projectRoot: dir,
+ });
+ try {
+ const countByType = async (type: string) => {
+ const rows: any = await (stack.driver as any).knex('sys_metadata')
+ .where({ type }).count({ c: '*' });
+ return Number((Array.isArray(rows) ? rows[0] : rows)?.c ?? -1);
+ };
+ // The control half: the contract write was refused.
+ expect(await countByType('os14053_create_probe')).toBe(0);
+ // The escape hatch half: the raw INSERT landed — forwarded on purpose.
+ expect(await countByType('os14053_exec_probe')).toBe(1);
+
+ // …and the run SAYS so. The refusal line drops the flat claim (the
+ // colon directly after "boot" is the dropped phrase), the forwarded
+ // call is named with its count, and no note in the run claims the
+ // plan wrote nothing. 4 refusals: the host config's plugin on three
+ // phases, plus this fixture's in-run control.
+ const notes = stack.composition.notes.join(' ');
+ expect(notes).toContain('Refused 4 write(s) during the declaration boot:');
+ expect(notes).toContain('Raw execute() was called 1 time(s) during the declaration boot');
+ expect(notes).not.toContain('a plan writes nothing');
+
+ // The guard's structural surface carries it too, for `--json` consumers.
+ expect(stack.composition.writeGuard?.rawExecutions).toEqual([
+ expect.objectContaining({ count: 1 }),
+ ]);
+ } finally {
+ await stack.shutdown();
+ }
+ }, 60_000);
+});

packages/cli/src/utils/schema-migrate.ts

@@ -350,6 +350,18 @@ export async function bootSchemaStack(
  }
  await runtime.start();
 
+ // #13332 — the kernel bootstrap is over, and with it the window the
+ // declaration boot's write guard covers. `composeForDeclarations` suppresses
+ // a host plugin's `start()`, but `kernel.ts` fires `kernel:ready`,
+ // `kernel:bootstrapped` and `kernel:listening` unconditionally afterwards, so
+ // a hook REGISTERED from `init()` runs on a plan; the guard refuses those
+ // writes at the driver instead of at a list of phase names. Everything from
+ // this line on is work the command was ASKED for — `apply`'s confirmed DDL
+ // flush, the #13028 coverage pass — so the guard comes off here and reports
+ // whatever it refused, which the plan prints and `--json` carries.
+ const refusalNote = composition.writeGuard?.disarm() ?? null;
+ if (refusalNote) composition.notes.push(refusalNote);
+
  const driver = findSqlDriver(kernel);
 
  // #13028 — the composed host declared its objects in `init()`; the pass that

.changeset/declaration-boot-write-suppression.md

@@ -0,0 +1,73 @@
+---
+"@objectstack/cli": minor
+---
+
+fix(cli): make `os migrate plan`'s "writes nothing" a property of the mechanism, not of an unwritten host convention (#13332)
+
+`composeForDeclarations` documented the plan path's guarantee in its own words —
+*"(init runs, start does not — a plan writes nothing)"* — and implemented it as a
+Proxy whose only override is `start`. `packages/core/src/kernel.ts` then fires
+three phases unconditionally after the suppressed start pass: `kernel:ready`
+(Phase 3), `kernel:bootstrapped` (Phase 3.5) and `kernel:listening` (Phase 4). A
+writing hook **registered from `init()`** survives the suppression and executes
+on all three. The guarantee was therefore a property of plugins that happen to
+seed from `start()` — the shape of the one plugin that had been measured — and
+not of the plan path.
+
+Measured, twice. The module header records 14 `Insert operation failed` rows
+against `sys_permission_set` from a deferred `plan` boot, and notes that on a
+database whose tables already exist those inserts **succeed**: a command
+documented as writing nothing seeds rows into an operator's production control
+plane. Downstream, a control plane hit exactly this on the `apply=false` run
+that is its mandatory human review gate before a production schema apply
+(`driver.create` / `driver.update` on `sys_ai_model`, from an
+`init()`-registered `kernel:ready` hook).
+
+**What changed.** For the length of the kernel bootstrap, `os migrate plan` /
+`os migrate apply` now refuse the row-write members of the data-driver contract
+(`IDataDriver`: `create`, `update`, `upsert`, `delete`, `bulkCreate`,
+`bulkUpdate`, `bulkDelete`, `updateMany`, `deleteMany`) on every `driver.*`
+instance the kernel publishes. The refusal sits at the driver, not at a list of
+lifecycle phase names: it is phase-agnostic (a phase added tomorrow is covered
+on the day it ships), it covers writes that arrive through the ObjectQL engine
+as well as direct `driver.*` calls (the engine holds the same instance), and
+read/log-only hooks still run — which is what an operator reading a plan before
+a production apply needs them to do. A refused write returns a contract-shaped
+value rather than throwing (boot hooks dispatch propagating, so throwing would
+abort the bootstrap and leave the operator with no plan at all), and every
+refusal is reported: one warning on stderr per driver/method/object triple,
+plus a line in the composition notes the plan prints and `--json` carries.
+
+The contract's raw-execution escape hatch — `IDataDriver.execute()`, a required
+member on every driver — is FORWARDED and REPORTED rather than refused: a raw
+command is `unknown` by contract ("SQL string, shell command, or API payload"),
+and SQL text cannot be classified as read-vs-write reliably, so refusing would
+break boot-legitimate reads and the framework's own index DDL on a guess. A
+boot-window `execute()` is counted per driver, warned once per driver on
+stderr, and named in the composition notes — and on such a run the notes do
+NOT claim the plan wrote nothing, because the guard cannot verify it.
+
+The guard is disarmed the moment the bootstrap returns, so `os migrate apply`'s
+confirmed DDL flush and the coverage measurement are untouched.
+
+**Who this affects.** A host whose plugins write during a `plan`/`apply` boot
+from anywhere other than a suppressed `start()`. Contract row writes previously
+landed and now do not; the run says so. A host whose plugins call raw
+`execute()` during the boot keeps its behaviour (the call is forwarded) and
+now sees it reported. A host that did neither sees no change at all — no
+disarm note is emitted when nothing was refused and no raw command went
+through.
+
+Boundaries stated rather than hidden: `execute()` is reported, never refused
+(above); `getKnex()` (a driver-sql extension, genuinely off-contract) is not
+intercepted. DDL splits: `deferSchemaDdl` holds back the
+`initObjects`/`syncSchema` path (flushed on purpose by `apply` once the
+operator confirms), while `dropTable`/`rotateShards` are NOT held back by that
+deferral — they are gated only by `assertSchemaMutable`
+(schemaMode/dialect) and stay a genuinely open boundary during the boot.
+Drivers the engine holds for a NON-default datasource are never published as
+`driver.*` (`DatasourceConnectionService.connect()` hands them to
+`engine.registerDriver` directly), so they are invisible to the guard's scan
+and objectql-mediated writes to objects bound to them would land. The guard
+also does not cover writes a plugin makes outside the database, or work a hook
+defers past the end of the bootstrap.

packages/cli/src/utils/schema-migrate.host-composition.integration.test.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
 
 import { describe, it, expect, beforeAll, afterAll } from 'vitest';
-import { mkdtempSync, mkdirSync, writeFileSync, symlinkSync, rmSync } from 'node:fs';
+import { mkdtempSync, mkdirSync, writeFileSync, appendFileSync, readFileSync, symlinkSync, rmSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { tmpdir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
@@ -494,3 +494,295 @@ describe('a host that brings its OWN ObjectQL engine (#13028 — cloud\'s measur
  }
  }, 60_000);
 });
+
+/**
+ * #13332 — the same guarantee, end to end, against a real SQL driver.
+ *
+ * The unit half
+ * (`schema-migration-plugins.declaration-boot-write-guard.test.ts`) pins the
+ * mechanism on a recording driver. This half proves the property the operator
+ * actually depends on: `os migrate plan`'s boot, with a host plugin that
+ * registers a writing hook from `init()`, leaves the DATABASE unchanged — on a
+ * database whose tables already exist, which is the condition under which the
+ * measured inserts SUCCEED instead of failing.
+ *
+ * The positive control comes first and is load-bearing. The identical plugin,
+ * on a boot that composes no host stack (so no declaration composition and no
+ * write guard), lands its rows. Without that leg the assertion below would be
+ * green over a fixture that could not have written.
+ */
+describe('a plan writes nothing even when the host writes from init() (#13332)', () => {
+ let dir: string;
+ let dbFile: string;
+ let hookLog: string;
+ const savedEnv: Record<string, string | undefined> = {};
+
+ const PHASES = ['kernel:ready', 'kernel:bootstrapped', 'kernel:listening'] as const;
+
+ /**
+ * cloud's measured shape, as a plugin this file can hand to either boot: the
+ * writing hooks are registered from `init()`, so `composeForDeclarations`'s
+ * `start()` suppression never sees them, and they fire on each of the three
+ * phases `kernel.ts` triggers unconditionally after the suppressed pass.
+ *
+ * The driver is found by scanning `driver.*` — the same surface
+ * `ObjectQLPlugin`'s discovery loop reads — rather than by naming one, so the
+ * fixture does not depend on what the standalone stack calls its default.
+ */
+ const initWritingPlugin = (tag: string): any => ({
+ name: `com.example.writes-from-init.${tag}`,
+ version: '1.0.0',
+ init: async (ctx: any) => {
+ for (const phase of PHASES) {
+ ctx.hook(phase, async () => {
+ appendFileSync(hookLog, `${tag}|log-only|${phase}\n`);
+ });
+ ctx.hook(phase, async () => {
+ const services: Map<string, any> = ctx.getServices();
+ const entry = [...services.entries()].find(([n]) => n.startsWith('driver.'));
+ if (!entry) return;
+ await entry[1].create('sys_metadata', {
+ id: `os13332-${tag}-${phase}`,
+ name: `os13332-${tag}-${phase}`,
+ type: 'os13332_probe',
+ });
+ appendFileSync(hookLog, `${tag}|write|${phase}\n`);
+ });
+ }
+ },
+ });
+
+ const probeRows = async (driver: any): Promise<number> => {
+ const rows: any = await driver.knex('sys_metadata')
+ .where({ type: 'os13332_probe' })
+ .count({ c: '*' });
+ return Number((Array.isArray(rows) ? rows[0] : rows)?.c ?? -1);
+ };
+
+ beforeAll(async () => {
+ dir = mkdtempSync(join(tmpdir(), 'os-13332-'));
+ dbFile = join(dir, 'control.db');
+ hookLog = join(dir, 'hooks.log');
+ writeFileSync(hookLog, '');
+
+ savedEnv.NODE_ENV = process.env.NODE_ENV;
+ savedEnv.OS_ARTIFACT_PATH = process.env.OS_ARTIFACT_PATH;
+ process.env.NODE_ENV = 'production';
+ process.env.OS_ARTIFACT_PATH = join(dir, 'dist', 'objectstack.json');
+
+ // Materialize `sys_metadata` FIRST, with no host config on disk yet. The
+ // measured defect is precisely that on a database whose tables EXIST the
+ // inserts succeed rather than fail, so neither case below may run against
+ // an empty schema — and the fixture must not depend on the fix to build
+ // itself: with the guard ablated, a writing hook against a table that does
+ // not exist yet THROWS, and boot hooks dispatch propagating, so the whole
+ // bootstrap dies. Setting the schema up before the writer exists keeps an
+ // ablation landing on the assertions below instead of on this hook.
+ const boot = await bootSchemaStack({
+ jsonOutput: false,
+ databaseUrl: `file:${dbFile}`,
+ deferSchemaDdl: true,
+ composeHostStack: false,
+ projectRoot: dir,
+ });
+ try {
+ await boot.flushSchemaDdl();
+ } finally {
+ await boot.shutdown();
+ }
+
+ // A host config carrying the SAME plugin shape, so the composed path is
+ // exercised as an operator would hit it — the plugin comes out of
+ // `objectstack.config.ts`, through `composeForDeclarations`.
+ writeFileSync(
+ join(dir, 'objectstack.config.ts'),
+ [
+ "import { appendFileSync } from 'node:fs';",
+ '',
+ `const LOG = ${JSON.stringify(hookLog)};`,
+ "const PHASES = ['kernel:ready', 'kernel:bootstrapped', 'kernel:listening'];",
+ '',
+ 'export default {',
+ ' plugins: [{',
+ " name: 'com.example.host-writes-from-init',",
+ " version: '1.0.0',",
+ ' init: async (ctx: any) => {',
+ ' for (const phase of PHASES) {',
+ " ctx.hook(phase, async () => { appendFileSync(LOG, `host|log-only|${phase}\\n`); });",
+ ' ctx.hook(phase, async () => {',
+ ' const entry = [...ctx.getServices().entries()]',
+ " .find(([n]: [string, unknown]) => n.startsWith('driver.'));",
+ ' if (!entry) return;',
+ " await entry[1].create('sys_metadata', {",
+ ' id: `os13332-host-${phase}`,',
+ ' name: `os13332-host-${phase}`,',
+ " type: 'os13332_probe',",
+ ' });',
+ " appendFileSync(LOG, `host|write|${phase}\\n`);",
+ ' });',
+ ' }',
+ ' },',
+ ' }],',
+ '};',
+ '',
+ ].join('\n'),
+ );
+
+ writeFileSync(hookLog, '');
+ }, 60_000);
+
+ afterAll(() => {
+ if (savedEnv.NODE_ENV === undefined) delete process.env.NODE_ENV;
+ else process.env.NODE_ENV = savedEnv.NODE_ENV;
+ if (savedEnv.OS_ARTIFACT_PATH === undefined) delete process.env.OS_ARTIFACT_PATH;
+ else process.env.OS_ARTIFACT_PATH = savedEnv.OS_ARTIFACT_PATH;
+ try { rmSync(dir, { recursive: true, force: true }); } catch { /* ignore */ }
+ });
+
+ it('POSITIVE CONTROL: the same plugin lands three rows on a boot with no declaration composition', async () => {
+ const stack = await bootSchemaStack({
+ jsonOutput: false,
+ databaseUrl: `file:${dbFile}`,
+ deferSchemaDdl: true,
+ // No host composition ⇒ no declaration wrapper and no write guard. This
+ // is the leg that proves the fixture can write at all.
+ composeHostStack: false,
+ extraPlugins: [initWritingPlugin('control')],
+ projectRoot: dir,
+ });
+ try {
+ expect(await probeRows(stack.driver)).toBe(3);
+ const log = readFileSync(hookLog, 'utf8');
+ for (const phase of PHASES) expect(log).toContain(`control|write|${phase}`);
+ } finally {
+ await stack.shutdown();
+ }
+ }, 60_000);
+
+ it('THE FIX: the declaration boot lands none of them — from the host config or from anywhere else', async () => {
+ const before = await (async () => {
+ const s = await bootSchemaStack({
+ jsonOutput: false,
+ databaseUrl: `file:${dbFile}`,
+ deferSchemaDdl: true,
+ composeHostStack: false,
+ projectRoot: dir,
+ });
+ try { return await probeRows(s.driver); } finally { await s.shutdown(); }
+ })();
+ // The control's three rows are still there — this case measures a DELTA,
+ // not an empty table, so a fixture that silently stopped writing cannot
+ // pass it.
+ expect(before).toBe(3);
+
+ writeFileSync(hookLog, '');
+ const stack = await bootSchemaStack({
+ jsonOutput: false,
+ databaseUrl: `file:${dbFile}`,
+ deferSchemaDdl: true,
+ composeHostStack: true,
+ // Both routes at once: the host config's own plugin (composed through
+ // `composeForDeclarations`) and one handed straight to the kernel. The
+ // guard sits at the driver, so neither reaches the database.
+ extraPlugins: [initWritingPlugin('extra')],
+ projectRoot: dir,
+ });
+ try {
+ expect(await probeRows(stack.driver)).toBe(before);
+
+ const log = readFileSync(hookLog, 'utf8');
+
+ // The property (b) was chosen for: the hooks RAN — the log-only ones
+ // included — on the path an operator reads before a production apply.
+ for (const phase of PHASES) {
+ expect(log).toContain(`host|log-only|${phase}`);
+ expect(log).toContain(`extra|log-only|${phase}`);
+ // …and the writing hooks got all the way to their `create()` call,
+ // which returned instead of throwing: the line after it was reached.
+ expect(log).toContain(`host|write|${phase}`);
+ expect(log).toContain(`extra|write|${phase}`);
+ }
+
+ // The refusals are REPORTED, not swallowed — this is the line the plan
+ // prints and `--json` carries. No raw execute() went through on this
+ // boot, so the outcome claim HELD and is printed with the report.
+ const notes = stack.composition.notes.join(' ');
+ expect(notes).toContain('Refused 6 write(s) during the declaration boot — a plan writes nothing');
+ expect(notes).toContain('create() on sys_metadata');
+ } finally {
+ await stack.shutdown();
+ }
+ }, 60_000);
+
+ it('R1 (#14053): a raw execute() is FORWARDED — the row lands — and the run reports it instead of claiming it wrote nothing', async () => {
+ // The at-tier review's own control shape, pinned: in one guarded boot, a
+ // hook issues a contract write (refused — the in-run control) and a raw
+ // `execute("INSERT …")`. `execute()` is a REQUIRED member of `IDataDriver`
+ // (`packages/spec/src/contracts/data-driver.ts`, "Raw Execution (Escape
+ // Hatch)"), and the guard cannot classify a raw command as read-vs-write,
+ // so the row LANDS — that is the documented behaviour, not the defect.
+ // The defect was the SILENT half: before this case's fix, the same run
+ // printed "a plan writes nothing" and a refusal list that looked
+ // complete. Now the notes name the forwarded call and drop the claim.
+ const rawWritingPlugin: any = {
+ name: 'com.example.raw-execute-from-init',
+ version: '1.0.0',
+ init: async (ctx: any) => {
+ ctx.hook('kernel:ready', async () => {
+ const entry = [...ctx.getServices().entries()]
+ .find(([n]: [string, unknown]) => n.startsWith('driver.'));
+ if (!entry) return;
+ const driver = entry[1];
+ // In-run control: the guarded surface refuses this one.
+ await driver.create('sys_metadata', {
+ id: 'os14053-create-probe',
+ name: 'os14053-create-probe',
+ type: 'os14053_create_probe',
+ });
+ // The escape hatch: forwarded, so this one LANDS.
+ await driver.execute(
+ "INSERT INTO sys_metadata (id, name, type) VALUES "
+ + "('os14053-exec-probe', 'os14053-exec-probe', 'os14053_exec_probe')",
+ );
+ });
+ },
+ };
+
+ const stack = await bootSchemaStack({
+ jsonOutput: false,
+ databaseUrl: `file:${dbFile}`,
+ deferSchemaDdl: true,
+ composeHostStack: true,
+ extraPlugins: [rawWritingPlugin],
+ projectRoot: dir,
+ });
+ try {
+ const countByType = async (type: string) => {
+ const rows: any = await (stack.driver as any).knex('sys_metadata')
+ .where({ type }).count({ c: '*' });
+ return Number((Array.isArray(rows) ? rows[0] : rows)?.c ?? -1);
+ };
+ // The control half: the contract write was refused.
+ expect(await countByType('os14053_create_probe')).toBe(0);
+ // The escape hatch half: the raw INSERT landed — forwarded on purpose.
+ expect(await countByType('os14053_exec_probe')).toBe(1);
+
+ // …and the run SAYS so. The refusal line drops the flat claim (the
+ // colon directly after "boot" is the dropped phrase), the forwarded
+ // call is named with its count, and no note in the run claims the
+ // plan wrote nothing. 4 refusals: the host config's plugin on three
+ // phases, plus this fixture's in-run control.
+ const notes = stack.composition.notes.join(' ');
+ expect(notes).toContain('Refused 4 write(s) during the declaration boot:');
+ expect(notes).toContain('Raw execute() was called 1 time(s) during the declaration boot');
+ expect(notes).not.toContain('a plan writes nothing');
+
+ // The guard's structural surface carries it too, for `--json` consumers.
+ expect(stack.composition.writeGuard?.rawExecutions).toEqual([
+ expect.objectContaining({ count: 1 }),
+ ]);
+ } finally {
+ await stack.shutdown();
+ }
+ }, 60_000);
+});

packages/cli/src/utils/schema-migrate.ts

@@ -350,6 +350,18 @@ export async function bootSchemaStack(
  }
  await runtime.start();
 
+ // #13332 — the kernel bootstrap is over, and with it the window the
+ // declaration boot's write guard covers. `composeForDeclarations` suppresses
+ // a host plugin's `start()`, but `kernel.ts` fires `kernel:ready`,
+ // `kernel:bootstrapped` and `kernel:listening` unconditionally afterwards, so
+ // a hook REGISTERED from `init()` runs on a plan; the guard refuses those
+ // writes at the driver instead of at a list of phase names. Everything from
+ // this line on is work the command was ASKED for — `apply`'s confirmed DDL
+ // flush, the #13028 coverage pass — so the guard comes off here and reports
+ // whatever it refused, which the plan prints and `--json` carries.
+ const refusalNote = composition.writeGuard?.disarm() ?? null;
+ if (refusalNote) composition.notes.push(refusalNote);
+
  const driver = findSqlDriver(kernel);
 
  // #13028 — the composed host declared its objects in `init()`; the pass that

.changeset/declaration-boot-write-suppression.md

@@ -0,0 +1,73 @@
+---
+"@objectstack/cli": minor
+---
+
+fix(cli): make `os migrate plan`'s "writes nothing" a property of the mechanism, not of an unwritten host convention (#13332)
+
+`composeForDeclarations` documented the plan path's guarantee in its own words —
+*"(init runs, start does not — a plan writes nothing)"* — and implemented it as a
+Proxy whose only override is `start`. `packages/core/src/kernel.ts` then fires
+three phases unconditionally after the suppressed start pass: `kernel:ready`
+(Phase 3), `kernel:bootstrapped` (Phase 3.5) and `kernel:listening` (Phase 4). A
+writing hook **registered from `init()`** survives the suppression and executes
+on all three. The guarantee was therefore a property of plugins that happen to
+seed from `start()` — the shape of the one plugin that had been measured — and
+not of the plan path.
+
+Measured, twice. The module header records 14 `Insert operation failed` rows
+against `sys_permission_set` from a deferred `plan` boot, and notes that on a
+database whose tables already exist those inserts **succeed**: a command
+documented as writing nothing seeds rows into an operator's production control
+plane. Downstream, a control plane hit exactly this on the `apply=false` run
+that is its mandatory human review gate before a production schema apply
+(`driver.create` / `driver.update` on `sys_ai_model`, from an
+`init()`-registered `kernel:ready` hook).
+
+**What changed.** For the length of the kernel bootstrap, `os migrate plan` /
+`os migrate apply` now refuse the row-write members of the data-driver contract
+(`IDataDriver`: `create`, `update`, `upsert`, `delete`, `bulkCreate`,
+`bulkUpdate`, `bulkDelete`, `updateMany`, `deleteMany`) on every `driver.*`
+instance the kernel publishes. The refusal sits at the driver, not at a list of
+lifecycle phase names: it is phase-agnostic (a phase added tomorrow is covered
+on the day it ships), it covers writes that arrive through the ObjectQL engine
+as well as direct `driver.*` calls (the engine holds the same instance), and
+read/log-only hooks still run — which is what an operator reading a plan before
+a production apply needs them to do. A refused write returns a contract-shaped
+value rather than throwing (boot hooks dispatch propagating, so throwing would
+abort the bootstrap and leave the operator with no plan at all), and every
+refusal is reported: one warning on stderr per driver/method/object triple,
+plus a line in the composition notes the plan prints and `--json` carries.
+
+The contract's raw-execution escape hatch — `IDataDriver.execute()`, a required
+member on every driver — is FORWARDED and REPORTED rather than refused: a raw
+command is `unknown` by contract ("SQL string, shell command, or API payload"),
+and SQL text cannot be classified as read-vs-write reliably, so refusing would
+break boot-legitimate reads and the framework's own index DDL on a guess. A
+boot-window `execute()` is counted per driver, warned once per driver on
+stderr, and named in the composition notes — and on such a run the notes do
+NOT claim the plan wrote nothing, because the guard cannot verify it.
+
+The guard is disarmed the moment the bootstrap returns, so `os migrate apply`'s
+confirmed DDL flush and the coverage measurement are untouched.
+
+**Who this affects.** A host whose plugins write during a `plan`/`apply` boot
+from anywhere other than a suppressed `start()`. Contract row writes previously
+landed and now do not; the run says so. A host whose plugins call raw
+`execute()` during the boot keeps its behaviour (the call is forwarded) and
+now sees it reported. A host that did neither sees no change at all — no
+disarm note is emitted when nothing was refused and no raw command went
+through.
+
+Boundaries stated rather than hidden: `execute()` is reported, never refused
+(above); `getKnex()` (a driver-sql extension, genuinely off-contract) is not
+intercepted. DDL splits: `deferSchemaDdl` holds back the
+`initObjects`/`syncSchema` path (flushed on purpose by `apply` once the
+operator confirms), while `dropTable`/`rotateShards` are NOT held back by that
+deferral — they are gated only by `assertSchemaMutable`
+(schemaMode/dialect) and stay a genuinely open boundary during the boot.
+Drivers the engine holds for a NON-default datasource are never published as
+`driver.*` (`DatasourceConnectionService.connect()` hands them to
+`engine.registerDriver` directly), so they are invisible to the guard's scan
+and objectql-mediated writes to objects bound to them would land. The guard
+also does not cover writes a plugin makes outside the database, or work a hook
+defers past the end of the bootstrap.

packages/cli/src/utils/schema-migrate.host-composition.integration.test.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
 
 import { describe, it, expect, beforeAll, afterAll } from 'vitest';
-import { mkdtempSync, mkdirSync, writeFileSync, symlinkSync, rmSync } from 'node:fs';
+import { mkdtempSync, mkdirSync, writeFileSync, appendFileSync, readFileSync, symlinkSync, rmSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { tmpdir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
@@ -494,3 +494,295 @@ describe('a host that brings its OWN ObjectQL engine (#13028 — cloud\'s measur
  }
  }, 60_000);
 });
+
+/**
+ * #13332 — the same guarantee, end to end, against a real SQL driver.
+ *
+ * The unit half
+ * (`schema-migration-plugins.declaration-boot-write-guard.test.ts`) pins the
+ * mechanism on a recording driver. This half proves the property the operator
+ * actually depends on: `os migrate plan`'s boot, with a host plugin that
+ * registers a writing hook from `init()`, leaves the DATABASE unchanged — on a
+ * database whose tables already exist, which is the condition under which the
+ * measured inserts SUCCEED instead of failing.
+ *
+ * The positive control comes first and is load-bearing. The identical plugin,
+ * on a boot that composes no host stack (so no declaration composition and no
+ * write guard), lands its rows. Without that leg the assertion below would be
+ * green over a fixture that could not have written.
+ */
+describe('a plan writes nothing even when the host writes from init() (#13332)', () => {
+ let dir: string;
+ let dbFile: string;
+ let hookLog: string;
+ const savedEnv: Record<string, string | undefined> = {};
+
+ const PHASES = ['kernel:ready', 'kernel:bootstrapped', 'kernel:listening'] as const;
+
+ /**
+ * cloud's measured shape, as a plugin this file can hand to either boot: the
+ * writing hooks are registered from `init()`, so `composeForDeclarations`'s
+ * `start()` suppression never sees them, and they fire on each of the three
+ * phases `kernel.ts` triggers unconditionally after the suppressed pass.
+ *
+ * The driver is found by scanning `driver.*` — the same surface
+ * `ObjectQLPlugin`'s discovery loop reads — rather than by naming one, so the
+ * fixture does not depend on what the standalone stack calls its default.
+ */
+ const initWritingPlugin = (tag: string): any => ({
+ name: `com.example.writes-from-init.${tag}`,
+ version: '1.0.0',
+ init: async (ctx: any) => {
+ for (const phase of PHASES) {
+ ctx.hook(phase, async () => {
+ appendFileSync(hookLog, `${tag}|log-only|${phase}\n`);
+ });
+ ctx.hook(phase, async () => {
+ const services: Map<string, any> = ctx.getServices();
+ const entry = [...services.entries()].find(([n]) => n.startsWith('driver.'));
+ if (!entry) return;
+ await entry[1].create('sys_metadata', {
+ id: `os13332-${tag}-${phase}`,
+ name: `os13332-${tag}-${phase}`,
+ type: 'os13332_probe',
+ });
+ appendFileSync(hookLog, `${tag}|write|${phase}\n`);
+ });
+ }
+ },
+ });
+
+ const probeRows = async (driver: any): Promise<number> => {
+ const rows: any = await driver.knex('sys_metadata')
+ .where({ type: 'os13332_probe' })
+ .count({ c: '*' });
+ return Number((Array.isArray(rows) ? rows[0] : rows)?.c ?? -1);
+ };
+
+ beforeAll(async () => {
+ dir = mkdtempSync(join(tmpdir(), 'os-13332-'));
+ dbFile = join(dir, 'control.db');
+ hookLog = join(dir, 'hooks.log');
+ writeFileSync(hookLog, '');
+
+ savedEnv.NODE_ENV = process.env.NODE_ENV;
+ savedEnv.OS_ARTIFACT_PATH = process.env.OS_ARTIFACT_PATH;
+ process.env.NODE_ENV = 'production';
+ process.env.OS_ARTIFACT_PATH = join(dir, 'dist', 'objectstack.json');
+
+ // Materialize `sys_metadata` FIRST, with no host config on disk yet. The
+ // measured defect is precisely that on a database whose tables EXIST the
+ // inserts succeed rather than fail, so neither case below may run against
+ // an empty schema — and the fixture must not depend on the fix to build
+ // itself: with the guard ablated, a writing hook against a table that does
+ // not exist yet THROWS, and boot hooks dispatch propagating, so the whole
+ // bootstrap dies. Setting the schema up before the writer exists keeps an
+ // ablation landing on the assertions below instead of on this hook.
+ const boot = await bootSchemaStack({
+ jsonOutput: false,
+ databaseUrl: `file:${dbFile}`,
+ deferSchemaDdl: true,
+ composeHostStack: false,
+ projectRoot: dir,
+ });
+ try {
+ await boot.flushSchemaDdl();
+ } finally {
+ await boot.shutdown();
+ }
+
+ // A host config carrying the SAME plugin shape, so the composed path is
+ // exercised as an operator would hit it — the plugin comes out of
+ // `objectstack.config.ts`, through `composeForDeclarations`.
+ writeFileSync(
+ join(dir, 'objectstack.config.ts'),
+ [
+ "import { appendFileSync } from 'node:fs';",
+ '',
+ `const LOG = ${JSON.stringify(hookLog)};`,
+ "const PHASES = ['kernel:ready', 'kernel:bootstrapped', 'kernel:listening'];",
+ '',
+ 'export default {',
+ ' plugins: [{',
+ " name: 'com.example.host-writes-from-init',",
+ " version: '1.0.0',",
+ ' init: async (ctx: any) => {',
+ ' for (const phase of PHASES) {',
+ " ctx.hook(phase, async () => { appendFileSync(LOG, `host|log-only|${phase}\\n`); });",
+ ' ctx.hook(phase, async () => {',
+ ' const entry = [...ctx.getServices().entries()]',
+ " .find(([n]: [string, unknown]) => n.startsWith('driver.'));",
+ ' if (!entry) return;',
+ " await entry[1].create('sys_metadata', {",
+ ' id: `os13332-host-${phase}`,',
+ ' name: `os13332-host-${phase}`,',
+ " type: 'os13332_probe',",
+ ' });',
+ " appendFileSync(LOG, `host|write|${phase}\\n`);",
+ ' });',
+ ' }',
+ ' },',
+ ' }],',
+ '};',
+ '',
+ ].join('\n'),
+ );
+
+ writeFileSync(hookLog, '');
+ }, 60_000);
+
+ afterAll(() => {
+ if (savedEnv.NODE_ENV === undefined) delete process.env.NODE_ENV;
+ else process.env.NODE_ENV = savedEnv.NODE_ENV;
+ if (savedEnv.OS_ARTIFACT_PATH === undefined) delete process.env.OS_ARTIFACT_PATH;
+ else process.env.OS_ARTIFACT_PATH = savedEnv.OS_ARTIFACT_PATH;
+ try { rmSync(dir, { recursive: true, force: true }); } catch { /* ignore */ }
+ });
+
+ it('POSITIVE CONTROL: the same plugin lands three rows on a boot with no declaration composition', async () => {
+ const stack = await bootSchemaStack({
+ jsonOutput: false,
+ databaseUrl: `file:${dbFile}`,
+ deferSchemaDdl: true,
+ // No host composition ⇒ no declaration wrapper and no write guard. This
+ // is the leg that proves the fixture can write at all.
+ composeHostStack: false,
+ extraPlugins: [initWritingPlugin('control')],
+ projectRoot: dir,
+ });
+ try {
+ expect(await probeRows(stack.driver)).toBe(3);
+ const log = readFileSync(hookLog, 'utf8');
+ for (const phase of PHASES) expect(log).toContain(`control|write|${phase}`);
+ } finally {
+ await stack.shutdown();
+ }
+ }, 60_000);
+
+ it('THE FIX: the declaration boot lands none of them — from the host config or from anywhere else', async () => {
+ const before = await (async () => {
+ const s = await bootSchemaStack({
+ jsonOutput: false,
+ databaseUrl: `file:${dbFile}`,
+ deferSchemaDdl: true,
+ composeHostStack: false,
+ projectRoot: dir,
+ });
+ try { return await probeRows(s.driver); } finally { await s.shutdown(); }
+ })();
+ // The control's three rows are still there — this case measures a DELTA,
+ // not an empty table, so a fixture that silently stopped writing cannot
+ // pass it.
+ expect(before).toBe(3);
+
+ writeFileSync(hookLog, '');
+ const stack = await bootSchemaStack({
+ jsonOutput: false,
+ databaseUrl: `file:${dbFile}`,
+ deferSchemaDdl: true,
+ composeHostStack: true,
+ // Both routes at once: the host config's own plugin (composed through
+ // `composeForDeclarations`) and one handed straight to the kernel. The
+ // guard sits at the driver, so neither reaches the database.
+ extraPlugins: [initWritingPlugin('extra')],
+ projectRoot: dir,
+ });
+ try {
+ expect(await probeRows(stack.driver)).toBe(before);
+
+ const log = readFileSync(hookLog, 'utf8');
+
+ // The property (b) was chosen for: the hooks RAN — the log-only ones
+ // included — on the path an operator reads before a production apply.
+ for (const phase of PHASES) {
+ expect(log).toContain(`host|log-only|${phase}`);
+ expect(log).toContain(`extra|log-only|${phase}`);
+ // …and the writing hooks got all the way to their `create()` call,
+ // which returned instead of throwing: the line after it was reached.
+ expect(log).toContain(`host|write|${phase}`);
+ expect(log).toContain(`extra|write|${phase}`);
+ }
+
+ // The refusals are REPORTED, not swallowed — this is the line the plan
+ // prints and `--json` carries. No raw execute() went through on this
+ // boot, so the outcome claim HELD and is printed with the report.
+ const notes = stack.composition.notes.join(' ');
+ expect(notes).toContain('Refused 6 write(s) during the declaration boot — a plan writes nothing');
+ expect(notes).toContain('create() on sys_metadata');
+ } finally {
+ await stack.shutdown();
+ }
+ }, 60_000);
+
+ it('R1 (#14053): a raw execute() is FORWARDED — the row lands — and the run reports it instead of claiming it wrote nothing', async () => {
+ // The at-tier review's own control shape, pinned: in one guarded boot, a
+ // hook issues a contract write (refused — the in-run control) and a raw
+ // `execute("INSERT …")`. `execute()` is a REQUIRED member of `IDataDriver`
+ // (`packages/spec/src/contracts/data-driver.ts`, "Raw Execution (Escape
+ // Hatch)"), and the guard cannot classify a raw command as read-vs-write,
+ // so the row LANDS — that is the documented behaviour, not the defect.
+ // The defect was the SILENT half: before this case's fix, the same run
+ // printed "a plan writes nothing" and a refusal list that looked
+ // complete. Now the notes name the forwarded call and drop the claim.
+ const rawWritingPlugin: any = {
+ name: 'com.example.raw-execute-from-init',
+ version: '1.0.0',
+ init: async (ctx: any) => {
+ ctx.hook('kernel:ready', async () => {
+ const entry = [...ctx.getServices().entries()]
+ .find(([n]: [string, unknown]) => n.startsWith('driver.'));
+ if (!entry) return;
+ const driver = entry[1];
+ // In-run control: the guarded surface refuses this one.
+ await driver.create('sys_metadata', {
+ id: 'os14053-create-probe',
+ name: 'os14053-create-probe',
+ type: 'os14053_create_probe',
+ });
+ // The escape hatch: forwarded, so this one LANDS.
+ await driver.execute(
+ "INSERT INTO sys_metadata (id, name, type) VALUES "
+ + "('os14053-exec-probe', 'os14053-exec-probe', 'os14053_exec_probe')",
+ );
+ });
+ },
+ };
+
+ const stack = await bootSchemaStack({
+ jsonOutput: false,
+ databaseUrl: `file:${dbFile}`,
+ deferSchemaDdl: true,
+ composeHostStack: true,
+ extraPlugins: [rawWritingPlugin],
+ projectRoot: dir,
+ });
+ try {
+ const countByType = async (type: string) => {
+ const rows: any = await (stack.driver as any).knex('sys_metadata')
+ .where({ type }).count({ c: '*' });
+ return Number((Array.isArray(rows) ? rows[0] : rows)?.c ?? -1);
+ };
+ // The control half: the contract write was refused.
+ expect(await countByType('os14053_create_probe')).toBe(0);
+ // The escape hatch half: the raw INSERT landed — forwarded on purpose.
+ expect(await countByType('os14053_exec_probe')).toBe(1);
+
+ // …and the run SAYS so. The refusal line drops the flat claim (the
+ // colon directly after "boot" is the dropped phrase), the forwarded
+ // call is named with its count, and no note in the run claims the
+ // plan wrote nothing. 4 refusals: the host config's plugin on three
+ // phases, plus this fixture's in-run control.
+ const notes = stack.composition.notes.join(' ');
+ expect(notes).toContain('Refused 4 write(s) during the declaration boot:');
+ expect(notes).toContain('Raw execute() was called 1 time(s) during the declaration boot');
+ expect(notes).not.toContain('a plan writes nothing');
+
+ // The guard's structural surface carries it too, for `--json` consumers.
+ expect(stack.composition.writeGuard?.rawExecutions).toEqual([
+ expect.objectContaining({ count: 1 }),
+ ]);
+ } finally {
+ await stack.shutdown();
+ }
+ }, 60_000);
+});

packages/cli/src/utils/schema-migrate.ts

@@ -350,6 +350,18 @@ export async function bootSchemaStack(
  }
  await runtime.start();
 
+ // #13332 — the kernel bootstrap is over, and with it the window the
+ // declaration boot's write guard covers. `composeForDeclarations` suppresses
+ // a host plugin's `start()`, but `kernel.ts` fires `kernel:ready`,
+ // `kernel:bootstrapped` and `kernel:listening` unconditionally afterwards, so
+ // a hook REGISTERED from `init()` runs on a plan; the guard refuses those
+ // writes at the driver instead of at a list of phase names. Everything from
+ // this line on is work the command was ASKED for — `apply`'s confirmed DDL
+ // flush, the #13028 coverage pass — so the guard comes off here and reports
+ // whatever it refused, which the plan prints and `--json` carries.
+ const refusalNote = composition.writeGuard?.disarm() ?? null;
+ if (refusalNote) composition.notes.push(refusalNote);
+
  const driver = findSqlDriver(kernel);
 
  // #13028 — the composed host declared its objects in `init()`; the pass that

.changeset/declaration-boot-write-suppression.md

@@ -0,0 +1,73 @@
+---
+"@objectstack/cli": minor
+---
+
+fix(cli): make `os migrate plan`'s "writes nothing" a property of the mechanism, not of an unwritten host convention (#13332)
+
+`composeForDeclarations` documented the plan path's guarantee in its own words —
+*"(init runs, start does not — a plan writes nothing)"* — and implemented it as a
+Proxy whose only override is `start`. `packages/core/src/kernel.ts` then fires
+three phases unconditionally after the suppressed start pass: `kernel:ready`
+(Phase 3), `kernel:bootstrapped` (Phase 3.5) and `kernel:listening` (Phase 4). A
+writing hook **registered from `init()`** survives the suppression and executes
+on all three. The guarantee was therefore a property of plugins that happen to
+seed from `start()` — the shape of the one plugin that had been measured — and
+not of the plan path.
+
+Measured, twice. The module header records 14 `Insert operation failed` rows
+against `sys_permission_set` from a deferred `plan` boot, and notes that on a
+database whose tables already exist those inserts **succeed**: a command
+documented as writing nothing seeds rows into an operator's production control
+plane. Downstream, a control plane hit exactly this on the `apply=false` run
+that is its mandatory human review gate before a production schema apply
+(`driver.create` / `driver.update` on `sys_ai_model`, from an
+`init()`-registered `kernel:ready` hook).
+
+**What changed.** For the length of the kernel bootstrap, `os migrate plan` /
+`os migrate apply` now refuse the row-write members of the data-driver contract
+(`IDataDriver`: `create`, `update`, `upsert`, `delete`, `bulkCreate`,
+`bulkUpdate`, `bulkDelete`, `updateMany`, `deleteMany`) on every `driver.*`
+instance the kernel publishes. The refusal sits at the driver, not at a list of
+lifecycle phase names: it is phase-agnostic (a phase added tomorrow is covered
+on the day it ships), it covers writes that arrive through the ObjectQL engine
+as well as direct `driver.*` calls (the engine holds the same instance), and
+read/log-only hooks still run — which is what an operator reading a plan before
+a production apply needs them to do. A refused write returns a contract-shaped
+value rather than throwing (boot hooks dispatch propagating, so throwing would
+abort the bootstrap and leave the operator with no plan at all), and every
+refusal is reported: one warning on stderr per driver/method/object triple,
+plus a line in the composition notes the plan prints and `--json` carries.
+
+The contract's raw-execution escape hatch — `IDataDriver.execute()`, a required
+member on every driver — is FORWARDED and REPORTED rather than refused: a raw
+command is `unknown` by contract ("SQL string, shell command, or API payload"),
+and SQL text cannot be classified as read-vs-write reliably, so refusing would
+break boot-legitimate reads and the framework's own index DDL on a guess. A
+boot-window `execute()` is counted per driver, warned once per driver on
+stderr, and named in the composition notes — and on such a run the notes do
+NOT claim the plan wrote nothing, because the guard cannot verify it.
+
+The guard is disarmed the moment the bootstrap returns, so `os migrate apply`'s
+confirmed DDL flush and the coverage measurement are untouched.
+
+**Who this affects.** A host whose plugins write during a `plan`/`apply` boot
+from anywhere other than a suppressed `start()`. Contract row writes previously
+landed and now do not; the run says so. A host whose plugins call raw
+`execute()` during the boot keeps its behaviour (the call is forwarded) and
+now sees it reported. A host that did neither sees no change at all — no
+disarm note is emitted when nothing was refused and no raw command went
+through.
+
+Boundaries stated rather than hidden: `execute()` is reported, never refused
+(above); `getKnex()` (a driver-sql extension, genuinely off-contract) is not
+intercepted. DDL splits: `deferSchemaDdl` holds back the
+`initObjects`/`syncSchema` path (flushed on purpose by `apply` once the
+operator confirms), while `dropTable`/`rotateShards` are NOT held back by that
+deferral — they are gated only by `assertSchemaMutable`
+(schemaMode/dialect) and stay a genuinely open boundary during the boot.
+Drivers the engine holds for a NON-default datasource are never published as
+`driver.*` (`DatasourceConnectionService.connect()` hands them to
+`engine.registerDriver` directly), so they are invisible to the guard's scan
+and objectql-mediated writes to objects bound to them would land. The guard
+also does not cover writes a plugin makes outside the database, or work a hook
+defers past the end of the bootstrap.

packages/cli/src/utils/schema-migrate.host-composition.integration.test.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
 
 import { describe, it, expect, beforeAll, afterAll } from 'vitest';
-import { mkdtempSync, mkdirSync, writeFileSync, symlinkSync, rmSync } from 'node:fs';
+import { mkdtempSync, mkdirSync, writeFileSync, appendFileSync, readFileSync, symlinkSync, rmSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { tmpdir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
@@ -494,3 +494,295 @@ describe('a host that brings its OWN ObjectQL engine (#13028 — cloud\'s measur
  }
  }, 60_000);
 });
+
+/**
+ * #13332 — the same guarantee, end to end, against a real SQL driver.
+ *
+ * The unit half
+ * (`schema-migration-plugins.declaration-boot-write-guard.test.ts`) pins the
+ * mechanism on a recording driver. This half proves the property the operator
+ * actually depends on: `os migrate plan`'s boot, with a host plugin that
+ * registers a writing hook from `init()`, leaves the DATABASE unchanged — on a
+ * database whose tables already exist, which is the condition under which the
+ * measured inserts SUCCEED instead of failing.
+ *
+ * The positive control comes first and is load-bearing. The identical plugin,
+ * on a boot that composes no host stack (so no declaration composition and no
+ * write guard), lands its rows. Without that leg the assertion below would be
+ * green over a fixture that could not have written.
+ */
+describe('a plan writes nothing even when the host writes from init() (#13332)', () => {
+ let dir: string;
+ let dbFile: string;
+ let hookLog: string;
+ const savedEnv: Record<string, string | undefined> = {};
+
+ const PHASES = ['kernel:ready', 'kernel:bootstrapped', 'kernel:listening'] as const;
+
+ /**
+ * cloud's measured shape, as a plugin this file can hand to either boot: the
+ * writing hooks are registered from `init()`, so `composeForDeclarations`'s
+ * `start()` suppression never sees them, and they fire on each of the three
+ * phases `kernel.ts` triggers unconditionally after the suppressed pass.
+ *
+ * The driver is found by scanning `driver.*` — the same surface
+ * `ObjectQLPlugin`'s discovery loop reads — rather than by naming one, so the
+ * fixture does not depend on what the standalone stack calls its default.
+ */
+ const initWritingPlugin = (tag: string): any => ({
+ name: `com.example.writes-from-init.${tag}`,
+ version: '1.0.0',
+ init: async (ctx: any) => {
+ for (const phase of PHASES) {
+ ctx.hook(phase, async () => {
+ appendFileSync(hookLog, `${tag}|log-only|${phase}\n`);
+ });
+ ctx.hook(phase, async () => {
+ const services: Map<string, any> = ctx.getServices();
+ const entry = [...services.entries()].find(([n]) => n.startsWith('driver.'));
+ if (!entry) return;
+ await entry[1].create('sys_metadata', {
+ id: `os13332-${tag}-${phase}`,
+ name: `os13332-${tag}-${phase}`,
+ type: 'os13332_probe',
+ });
+ appendFileSync(hookLog, `${tag}|write|${phase}\n`);
+ });
+ }
+ },
+ });
+
+ const probeRows = async (driver: any): Promise<number> => {
+ const rows: any = await driver.knex('sys_metadata')
+ .where({ type: 'os13332_probe' })
+ .count({ c: '*' });
+ return Number((Array.isArray(rows) ? rows[0] : rows)?.c ?? -1);
+ };
+
+ beforeAll(async () => {
+ dir = mkdtempSync(join(tmpdir(), 'os-13332-'));
+ dbFile = join(dir, 'control.db');
+ hookLog = join(dir, 'hooks.log');
+ writeFileSync(hookLog, '');
+
+ savedEnv.NODE_ENV = process.env.NODE_ENV;
+ savedEnv.OS_ARTIFACT_PATH = process.env.OS_ARTIFACT_PATH;
+ process.env.NODE_ENV = 'production';
+ process.env.OS_ARTIFACT_PATH = join(dir, 'dist', 'objectstack.json');
+
+ // Materialize `sys_metadata` FIRST, with no host config on disk yet. The
+ // measured defect is precisely that on a database whose tables EXIST the
+ // inserts succeed rather than fail, so neither case below may run against
+ // an empty schema — and the fixture must not depend on the fix to build
+ // itself: with the guard ablated, a writing hook against a table that does
+ // not exist yet THROWS, and boot hooks dispatch propagating, so the whole
+ // bootstrap dies. Setting the schema up before the writer exists keeps an
+ // ablation landing on the assertions below instead of on this hook.
+ const boot = await bootSchemaStack({
+ jsonOutput: false,
+ databaseUrl: `file:${dbFile}`,
+ deferSchemaDdl: true,
+ composeHostStack: false,
+ projectRoot: dir,
+ });
+ try {
+ await boot.flushSchemaDdl();
+ } finally {
+ await boot.shutdown();
+ }
+
+ // A host config carrying the SAME plugin shape, so the composed path is
+ // exercised as an operator would hit it — the plugin comes out of
+ // `objectstack.config.ts`, through `composeForDeclarations`.
+ writeFileSync(
+ join(dir, 'objectstack.config.ts'),
+ [
+ "import { appendFileSync } from 'node:fs';",
+ '',
+ `const LOG = ${JSON.stringify(hookLog)};`,
+ "const PHASES = ['kernel:ready', 'kernel:bootstrapped', 'kernel:listening'];",
+ '',
+ 'export default {',
+ ' plugins: [{',
+ " name: 'com.example.host-writes-from-init',",
+ " version: '1.0.0',",
+ ' init: async (ctx: any) => {',
+ ' for (const phase of PHASES) {',
+ " ctx.hook(phase, async () => { appendFileSync(LOG, `host|log-only|${phase}\\n`); });",
+ ' ctx.hook(phase, async () => {',
+ ' const entry = [...ctx.getServices().entries()]',
+ " .find(([n]: [string, unknown]) => n.startsWith('driver.'));",
+ ' if (!entry) return;',
+ " await entry[1].create('sys_metadata', {",
+ ' id: `os13332-host-${phase}`,',
+ ' name: `os13332-host-${phase}`,',
+ " type: 'os13332_probe',",
+ ' });',
+ " appendFileSync(LOG, `host|write|${phase}\\n`);",
+ ' });',
+ ' }',
+ ' },',
+ ' }],',
+ '};',
+ '',
+ ].join('\n'),
+ );
+
+ writeFileSync(hookLog, '');
+ }, 60_000);
+
+ afterAll(() => {
+ if (savedEnv.NODE_ENV === undefined) delete process.env.NODE_ENV;
+ else process.env.NODE_ENV = savedEnv.NODE_ENV;
+ if (savedEnv.OS_ARTIFACT_PATH === undefined) delete process.env.OS_ARTIFACT_PATH;
+ else process.env.OS_ARTIFACT_PATH = savedEnv.OS_ARTIFACT_PATH;
+ try { rmSync(dir, { recursive: true, force: true }); } catch { /* ignore */ }
+ });
+
+ it('POSITIVE CONTROL: the same plugin lands three rows on a boot with no declaration composition', async () => {
+ const stack = await bootSchemaStack({
+ jsonOutput: false,
+ databaseUrl: `file:${dbFile}`,
+ deferSchemaDdl: true,
+ // No host composition ⇒ no declaration wrapper and no write guard. This
+ // is the leg that proves the fixture can write at all.
+ composeHostStack: false,
+ extraPlugins: [initWritingPlugin('control')],
+ projectRoot: dir,
+ });
+ try {
+ expect(await probeRows(stack.driver)).toBe(3);
+ const log = readFileSync(hookLog, 'utf8');
+ for (const phase of PHASES) expect(log).toContain(`control|write|${phase}`);
+ } finally {
+ await stack.shutdown();
+ }
+ }, 60_000);
+
+ it('THE FIX: the declaration boot lands none of them — from the host config or from anywhere else', async () => {
+ const before = await (async () => {
+ const s = await bootSchemaStack({
+ jsonOutput: false,
+ databaseUrl: `file:${dbFile}`,
+ deferSchemaDdl: true,
+ composeHostStack: false,
+ projectRoot: dir,
+ });
+ try { return await probeRows(s.driver); } finally { await s.shutdown(); }
+ })();
+ // The control's three rows are still there — this case measures a DELTA,
+ // not an empty table, so a fixture that silently stopped writing cannot
+ // pass it.
+ expect(before).toBe(3);
+
+ writeFileSync(hookLog, '');
+ const stack = await bootSchemaStack({
+ jsonOutput: false,
+ databaseUrl: `file:${dbFile}`,
+ deferSchemaDdl: true,
+ composeHostStack: true,
+ // Both routes at once: the host config's own plugin (composed through
+ // `composeForDeclarations`) and one handed straight to the kernel. The
+ // guard sits at the driver, so neither reaches the database.
+ extraPlugins: [initWritingPlugin('extra')],
+ projectRoot: dir,
+ });
+ try {
+ expect(await probeRows(stack.driver)).toBe(before);
+
+ const log = readFileSync(hookLog, 'utf8');
+
+ // The property (b) was chosen for: the hooks RAN — the log-only ones
+ // included — on the path an operator reads before a production apply.
+ for (const phase of PHASES) {
+ expect(log).toContain(`host|log-only|${phase}`);
+ expect(log).toContain(`extra|log-only|${phase}`);
+ // …and the writing hooks got all the way to their `create()` call,
+ // which returned instead of throwing: the line after it was reached.
+ expect(log).toContain(`host|write|${phase}`);
+ expect(log).toContain(`extra|write|${phase}`);
+ }
+
+ // The refusals are REPORTED, not swallowed — this is the line the plan
+ // prints and `--json` carries. No raw execute() went through on this
+ // boot, so the outcome claim HELD and is printed with the report.
+ const notes = stack.composition.notes.join(' ');
+ expect(notes).toContain('Refused 6 write(s) during the declaration boot — a plan writes nothing');
+ expect(notes).toContain('create() on sys_metadata');
+ } finally {
+ await stack.shutdown();
+ }
+ }, 60_000);
+
+ it('R1 (#14053): a raw execute() is FORWARDED — the row lands — and the run reports it instead of claiming it wrote nothing', async () => {
+ // The at-tier review's own control shape, pinned: in one guarded boot, a
+ // hook issues a contract write (refused — the in-run control) and a raw
+ // `execute("INSERT …")`. `execute()` is a REQUIRED member of `IDataDriver`
+ // (`packages/spec/src/contracts/data-driver.ts`, "Raw Execution (Escape
+ // Hatch)"), and the guard cannot classify a raw command as read-vs-write,
+ // so the row LANDS — that is the documented behaviour, not the defect.
+ // The defect was the SILENT half: before this case's fix, the same run
+ // printed "a plan writes nothing" and a refusal list that looked
+ // complete. Now the notes name the forwarded call and drop the claim.
+ const rawWritingPlugin: any = {
+ name: 'com.example.raw-execute-from-init',
+ version: '1.0.0',
+ init: async (ctx: any) => {
+ ctx.hook('kernel:ready', async () => {
+ const entry = [...ctx.getServices().entries()]
+ .find(([n]: [string, unknown]) => n.startsWith('driver.'));
+ if (!entry) return;
+ const driver = entry[1];
+ // In-run control: the guarded surface refuses this one.
+ await driver.create('sys_metadata', {
+ id: 'os14053-create-probe',
+ name: 'os14053-create-probe',
+ type: 'os14053_create_probe',
+ });
+ // The escape hatch: forwarded, so this one LANDS.
+ await driver.execute(
+ "INSERT INTO sys_metadata (id, name, type) VALUES "
+ + "('os14053-exec-probe', 'os14053-exec-probe', 'os14053_exec_probe')",
+ );
+ });
+ },
+ };
+
+ const stack = await bootSchemaStack({
+ jsonOutput: false,
+ databaseUrl: `file:${dbFile}`,
+ deferSchemaDdl: true,
+ composeHostStack: true,
+ extraPlugins: [rawWritingPlugin],
+ projectRoot: dir,
+ });
+ try {
+ const countByType = async (type: string) => {
+ const rows: any = await (stack.driver as any).knex('sys_metadata')
+ .where({ type }).count({ c: '*' });
+ return Number((Array.isArray(rows) ? rows[0] : rows)?.c ?? -1);
+ };
+ // The control half: the contract write was refused.
+ expect(await countByType('os14053_create_probe')).toBe(0);
+ // The escape hatch half: the raw INSERT landed — forwarded on purpose.
+ expect(await countByType('os14053_exec_probe')).toBe(1);
+
+ // …and the run SAYS so. The refusal line drops the flat claim (the
+ // colon directly after "boot" is the dropped phrase), the forwarded
+ // call is named with its count, and no note in the run claims the
+ // plan wrote nothing. 4 refusals: the host config's plugin on three
+ // phases, plus this fixture's in-run control.
+ const notes = stack.composition.notes.join(' ');
+ expect(notes).toContain('Refused 4 write(s) during the declaration boot:');
+ expect(notes).toContain('Raw execute() was called 1 time(s) during the declaration boot');
+ expect(notes).not.toContain('a plan writes nothing');
+
+ // The guard's structural surface carries it too, for `--json` consumers.
+ expect(stack.composition.writeGuard?.rawExecutions).toEqual([
+ expect.objectContaining({ count: 1 }),
+ ]);
+ } finally {
+ await stack.shutdown();
+ }
+ }, 60_000);
+});

packages/cli/src/utils/schema-migrate.ts

@@ -350,6 +350,18 @@ export async function bootSchemaStack(
  }
  await runtime.start();
 
+ // #13332 — the kernel bootstrap is over, and with it the window the
+ // declaration boot's write guard covers. `composeForDeclarations` suppresses
+ // a host plugin's `start()`, but `kernel.ts` fires `kernel:ready`,
+ // `kernel:bootstrapped` and `kernel:listening` unconditionally afterwards, so
+ // a hook REGISTERED from `init()` runs on a plan; the guard refuses those
+ // writes at the driver instead of at a list of phase names. Everything from
+ // this line on is work the command was ASKED for — `apply`'s confirmed DDL
+ // flush, the #13028 coverage pass — so the guard comes off here and reports
+ // whatever it refused, which the plan prints and `--json` carries.
+ const refusalNote = composition.writeGuard?.disarm() ?? null;
+ if (refusalNote) composition.notes.push(refusalNote);
+
  const driver = findSqlDriver(kernel);
 
  // #13028 — the composed host declared its objects in `init()`; the pass that

.changeset/declaration-boot-write-suppression.md

@@ -0,0 +1,73 @@
+---
+"@objectstack/cli": minor
+---
+
+fix(cli): make `os migrate plan`'s "writes nothing" a property of the mechanism, not of an unwritten host convention (#13332)
+
+`composeForDeclarations` documented the plan path's guarantee in its own words —
+*"(init runs, start does not — a plan writes nothing)"* — and implemented it as a
+Proxy whose only override is `start`. `packages/core/src/kernel.ts` then fires
+three phases unconditionally after the suppressed start pass: `kernel:ready`
+(Phase 3), `kernel:bootstrapped` (Phase 3.5) and `kernel:listening` (Phase 4). A
+writing hook **registered from `init()`** survives the suppression and executes
+on all three. The guarantee was therefore a property of plugins that happen to
+seed from `start()` — the shape of the one plugin that had been measured — and
+not of the plan path.
+
+Measured, twice. The module header records 14 `Insert operation failed` rows
+against `sys_permission_set` from a deferred `plan` boot, and notes that on a
+database whose tables already exist those inserts **succeed**: a command
+documented as writing nothing seeds rows into an operator's production control
+plane. Downstream, a control plane hit exactly this on the `apply=false` run
+that is its mandatory human review gate before a production schema apply
+(`driver.create` / `driver.update` on `sys_ai_model`, from an
+`init()`-registered `kernel:ready` hook).
+
+**What changed.** For the length of the kernel bootstrap, `os migrate plan` /
+`os migrate apply` now refuse the row-write members of the data-driver contract
+(`IDataDriver`: `create`, `update`, `upsert`, `delete`, `bulkCreate`,
+`bulkUpdate`, `bulkDelete`, `updateMany`, `deleteMany`) on every `driver.*`
+instance the kernel publishes. The refusal sits at the driver, not at a list of
+lifecycle phase names: it is phase-agnostic (a phase added tomorrow is covered
+on the day it ships), it covers writes that arrive through the ObjectQL engine
+as well as direct `driver.*` calls (the engine holds the same instance), and
+read/log-only hooks still run — which is what an operator reading a plan before
+a production apply needs them to do. A refused write returns a contract-shaped
+value rather than throwing (boot hooks dispatch propagating, so throwing would
+abort the bootstrap and leave the operator with no plan at all), and every
+refusal is reported: one warning on stderr per driver/method/object triple,
+plus a line in the composition notes the plan prints and `--json` carries.
+
+The contract's raw-execution escape hatch — `IDataDriver.execute()`, a required
+member on every driver — is FORWARDED and REPORTED rather than refused: a raw
+command is `unknown` by contract ("SQL string, shell command, or API payload"),
+and SQL text cannot be classified as read-vs-write reliably, so refusing would
+break boot-legitimate reads and the framework's own index DDL on a guess. A
+boot-window `execute()` is counted per driver, warned once per driver on
+stderr, and named in the composition notes — and on such a run the notes do
+NOT claim the plan wrote nothing, because the guard cannot verify it.
+
+The guard is disarmed the moment the bootstrap returns, so `os migrate apply`'s
+confirmed DDL flush and the coverage measurement are untouched.
+
+**Who this affects.** A host whose plugins write during a `plan`/`apply` boot
+from anywhere other than a suppressed `start()`. Contract row writes previously
+landed and now do not; the run says so. A host whose plugins call raw
+`execute()` during the boot keeps its behaviour (the call is forwarded) and
+now sees it reported. A host that did neither sees no change at all — no
+disarm note is emitted when nothing was refused and no raw command went
+through.
+
+Boundaries stated rather than hidden: `execute()` is reported, never refused
+(above); `getKnex()` (a driver-sql extension, genuinely off-contract) is not
+intercepted. DDL splits: `deferSchemaDdl` holds back the
+`initObjects`/`syncSchema` path (flushed on purpose by `apply` once the
+operator confirms), while `dropTable`/`rotateShards` are NOT held back by that
+deferral — they are gated only by `assertSchemaMutable`
+(schemaMode/dialect) and stay a genuinely open boundary during the boot.
+Drivers the engine holds for a NON-default datasource are never published as
+`driver.*` (`DatasourceConnectionService.connect()` hands them to
+`engine.registerDriver` directly), so they are invisible to the guard's scan
+and objectql-mediated writes to objects bound to them would land. The guard
+also does not cover writes a plugin makes outside the database, or work a hook
+defers past the end of the bootstrap.

packages/cli/src/utils/schema-migrate.host-composition.integration.test.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
 
 import { describe, it, expect, beforeAll, afterAll } from 'vitest';
-import { mkdtempSync, mkdirSync, writeFileSync, symlinkSync, rmSync } from 'node:fs';
+import { mkdtempSync, mkdirSync, writeFileSync, appendFileSync, readFileSync, symlinkSync, rmSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { tmpdir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
@@ -494,3 +494,295 @@ describe('a host that brings its OWN ObjectQL engine (#13028 — cloud\'s measur
  }
  }, 60_000);
 });
+
+/**
+ * #13332 — the same guarantee, end to end, against a real SQL driver.
+ *
+ * The unit half
+ * (`schema-migration-plugins.declaration-boot-write-guard.test.ts`) pins the
+ * mechanism on a recording driver. This half proves the property the operator
+ * actually depends on: `os migrate plan`'s boot, with a host plugin that
+ * registers a writing hook from `init()`, leaves the DATABASE unchanged — on a
+ * database whose tables already exist, which is the condition under which the
+ * measured inserts SUCCEED instead of failing.
+ *
+ * The positive control comes first and is load-bearing. The identical plugin,
+ * on a boot that composes no host stack (so no declaration composition and no
+ * write guard), lands its rows. Without that leg the assertion below would be
+ * green over a fixture that could not have written.
+ */
+describe('a plan writes nothing even when the host writes from init() (#13332)', () => {
+ let dir: string;
+ let dbFile: string;
+ let hookLog: string;
+ const savedEnv: Record<string, string | undefined> = {};
+
+ const PHASES = ['kernel:ready', 'kernel:bootstrapped', 'kernel:listening'] as const;
+
+ /**
+ * cloud's measured shape, as a plugin this file can hand to either boot: the
+ * writing hooks are registered from `init()`, so `composeForDeclarations`'s
+ * `start()` suppression never sees them, and they fire on each of the three
+ * phases `kernel.ts` triggers unconditionally after the suppressed pass.
+ *
+ * The driver is found by scanning `driver.*` — the same surface
+ * `ObjectQLPlugin`'s discovery loop reads — rather than by naming one, so the
+ * fixture does not depend on what the standalone stack calls its default.
+ */
+ const initWritingPlugin = (tag: string): any => ({
+ name: `com.example.writes-from-init.${tag}`,
+ version: '1.0.0',
+ init: async (ctx: any) => {
+ for (const phase of PHASES) {
+ ctx.hook(phase, async () => {
+ appendFileSync(hookLog, `${tag}|log-only|${phase}\n`);
+ });
+ ctx.hook(phase, async () => {
+ const services: Map<string, any> = ctx.getServices();
+ const entry = [...services.entries()].find(([n]) => n.startsWith('driver.'));
+ if (!entry) return;
+ await entry[1].create('sys_metadata', {
+ id: `os13332-${tag}-${phase}`,
+ name: `os13332-${tag}-${phase}`,
+ type: 'os13332_probe',
+ });
+ appendFileSync(hookLog, `${tag}|write|${phase}\n`);
+ });
+ }
+ },
+ });
+
+ const probeRows = async (driver: any): Promise<number> => {
+ const rows: any = await driver.knex('sys_metadata')
+ .where({ type: 'os13332_probe' })
+ .count({ c: '*' });
+ return Number((Array.isArray(rows) ? rows[0] : rows)?.c ?? -1);
+ };
+
+ beforeAll(async () => {
+ dir = mkdtempSync(join(tmpdir(), 'os-13332-'));
+ dbFile = join(dir, 'control.db');
+ hookLog = join(dir, 'hooks.log');
+ writeFileSync(hookLog, '');
+
+ savedEnv.NODE_ENV = process.env.NODE_ENV;
+ savedEnv.OS_ARTIFACT_PATH = process.env.OS_ARTIFACT_PATH;
+ process.env.NODE_ENV = 'production';
+ process.env.OS_ARTIFACT_PATH = join(dir, 'dist', 'objectstack.json');
+
+ // Materialize `sys_metadata` FIRST, with no host config on disk yet. The
+ // measured defect is precisely that on a database whose tables EXIST the
+ // inserts succeed rather than fail, so neither case below may run against
+ // an empty schema — and the fixture must not depend on the fix to build
+ // itself: with the guard ablated, a writing hook against a table that does
+ // not exist yet THROWS, and boot hooks dispatch propagating, so the whole
+ // bootstrap dies. Setting the schema up before the writer exists keeps an
+ // ablation landing on the assertions below instead of on this hook.
+ const boot = await bootSchemaStack({
+ jsonOutput: false,
+ databaseUrl: `file:${dbFile}`,
+ deferSchemaDdl: true,
+ composeHostStack: false,
+ projectRoot: dir,
+ });
+ try {
+ await boot.flushSchemaDdl();
+ } finally {
+ await boot.shutdown();
+ }
+
+ // A host config carrying the SAME plugin shape, so the composed path is
+ // exercised as an operator would hit it — the plugin comes out of
+ // `objectstack.config.ts`, through `composeForDeclarations`.
+ writeFileSync(
+ join(dir, 'objectstack.config.ts'),
+ [
+ "import { appendFileSync } from 'node:fs';",
+ '',
+ `const LOG = ${JSON.stringify(hookLog)};`,
+ "const PHASES = ['kernel:ready', 'kernel:bootstrapped', 'kernel:listening'];",
+ '',
+ 'export default {',
+ ' plugins: [{',
+ " name: 'com.example.host-writes-from-init',",
+ " version: '1.0.0',",
+ ' init: async (ctx: any) => {',
+ ' for (const phase of PHASES) {',
+ " ctx.hook(phase, async () => { appendFileSync(LOG, `host|log-only|${phase}\\n`); });",
+ ' ctx.hook(phase, async () => {',
+ ' const entry = [...ctx.getServices().entries()]',
+ " .find(([n]: [string, unknown]) => n.startsWith('driver.'));",
+ ' if (!entry) return;',
+ " await entry[1].create('sys_metadata', {",
+ ' id: `os13332-host-${phase}`,',
+ ' name: `os13332-host-${phase}`,',
+ " type: 'os13332_probe',",
+ ' });',
+ " appendFileSync(LOG, `host|write|${phase}\\n`);",
+ ' });',
+ ' }',
+ ' },',
+ ' }],',
+ '};',
+ '',
+ ].join('\n'),
+ );
+
+ writeFileSync(hookLog, '');
+ }, 60_000);
+
+ afterAll(() => {
+ if (savedEnv.NODE_ENV === undefined) delete process.env.NODE_ENV;
+ else process.env.NODE_ENV = savedEnv.NODE_ENV;
+ if (savedEnv.OS_ARTIFACT_PATH === undefined) delete process.env.OS_ARTIFACT_PATH;
+ else process.env.OS_ARTIFACT_PATH = savedEnv.OS_ARTIFACT_PATH;
+ try { rmSync(dir, { recursive: true, force: true }); } catch { /* ignore */ }
+ });
+
+ it('POSITIVE CONTROL: the same plugin lands three rows on a boot with no declaration composition', async () => {
+ const stack = await bootSchemaStack({
+ jsonOutput: false,
+ databaseUrl: `file:${dbFile}`,
+ deferSchemaDdl: true,
+ // No host composition ⇒ no declaration wrapper and no write guard. This
+ // is the leg that proves the fixture can write at all.
+ composeHostStack: false,
+ extraPlugins: [initWritingPlugin('control')],
+ projectRoot: dir,
+ });
+ try {
+ expect(await probeRows(stack.driver)).toBe(3);
+ const log = readFileSync(hookLog, 'utf8');
+ for (const phase of PHASES) expect(log).toContain(`control|write|${phase}`);
+ } finally {
+ await stack.shutdown();
+ }
+ }, 60_000);
+
+ it('THE FIX: the declaration boot lands none of them — from the host config or from anywhere else', async () => {
+ const before = await (async () => {
+ const s = await bootSchemaStack({
+ jsonOutput: false,
+ databaseUrl: `file:${dbFile}`,
+ deferSchemaDdl: true,
+ composeHostStack: false,
+ projectRoot: dir,
+ });
+ try { return await probeRows(s.driver); } finally { await s.shutdown(); }
+ })();
+ // The control's three rows are still there — this case measures a DELTA,
+ // not an empty table, so a fixture that silently stopped writing cannot
+ // pass it.
+ expect(before).toBe(3);
+
+ writeFileSync(hookLog, '');
+ const stack = await bootSchemaStack({
+ jsonOutput: false,
+ databaseUrl: `file:${dbFile}`,
+ deferSchemaDdl: true,
+ composeHostStack: true,
+ // Both routes at once: the host config's own plugin (composed through
+ // `composeForDeclarations`) and one handed straight to the kernel. The
+ // guard sits at the driver, so neither reaches the database.
+ extraPlugins: [initWritingPlugin('extra')],
+ projectRoot: dir,
+ });
+ try {
+ expect(await probeRows(stack.driver)).toBe(before);
+
+ const log = readFileSync(hookLog, 'utf8');
+
+ // The property (b) was chosen for: the hooks RAN — the log-only ones
+ // included — on the path an operator reads before a production apply.
+ for (const phase of PHASES) {
+ expect(log).toContain(`host|log-only|${phase}`);
+ expect(log).toContain(`extra|log-only|${phase}`);
+ // …and the writing hooks got all the way to their `create()` call,
+ // which returned instead of throwing: the line after it was reached.
+ expect(log).toContain(`host|write|${phase}`);
+ expect(log).toContain(`extra|write|${phase}`);
+ }
+
+ // The refusals are REPORTED, not swallowed — this is the line the plan
+ // prints and `--json` carries. No raw execute() went through on this
+ // boot, so the outcome claim HELD and is printed with the report.
+ const notes = stack.composition.notes.join(' ');
+ expect(notes).toContain('Refused 6 write(s) during the declaration boot — a plan writes nothing');
+ expect(notes).toContain('create() on sys_metadata');
+ } finally {
+ await stack.shutdown();
+ }
+ }, 60_000);
+
+ it('R1 (#14053): a raw execute() is FORWARDED — the row lands — and the run reports it instead of claiming it wrote nothing', async () => {
+ // The at-tier review's own control shape, pinned: in one guarded boot, a
+ // hook issues a contract write (refused — the in-run control) and a raw
+ // `execute("INSERT …")`. `execute()` is a REQUIRED member of `IDataDriver`
+ // (`packages/spec/src/contracts/data-driver.ts`, "Raw Execution (Escape
+ // Hatch)"), and the guard cannot classify a raw command as read-vs-write,
+ // so the row LANDS — that is the documented behaviour, not the defect.
+ // The defect was the SILENT half: before this case's fix, the same run
+ // printed "a plan writes nothing" and a refusal list that looked
+ // complete. Now the notes name the forwarded call and drop the claim.
+ const rawWritingPlugin: any = {
+ name: 'com.example.raw-execute-from-init',
+ version: '1.0.0',
+ init: async (ctx: any) => {
+ ctx.hook('kernel:ready', async () => {
+ const entry = [...ctx.getServices().entries()]
+ .find(([n]: [string, unknown]) => n.startsWith('driver.'));
+ if (!entry) return;
+ const driver = entry[1];
+ // In-run control: the guarded surface refuses this one.
+ await driver.create('sys_metadata', {
+ id: 'os14053-create-probe',
+ name: 'os14053-create-probe',
+ type: 'os14053_create_probe',
+ });
+ // The escape hatch: forwarded, so this one LANDS.
+ await driver.execute(
+ "INSERT INTO sys_metadata (id, name, type) VALUES "
+ + "('os14053-exec-probe', 'os14053-exec-probe', 'os14053_exec_probe')",
+ );
+ });
+ },
+ };
+
+ const stack = await bootSchemaStack({
+ jsonOutput: false,
+ databaseUrl: `file:${dbFile}`,
+ deferSchemaDdl: true,
+ composeHostStack: true,
+ extraPlugins: [rawWritingPlugin],
+ projectRoot: dir,
+ });
+ try {
+ const countByType = async (type: string) => {
+ const rows: any = await (stack.driver as any).knex('sys_metadata')
+ .where({ type }).count({ c: '*' });
+ return Number((Array.isArray(rows) ? rows[0] : rows)?.c ?? -1);
+ };
+ // The control half: the contract write was refused.
+ expect(await countByType('os14053_create_probe')).toBe(0);
+ // The escape hatch half: the raw INSERT landed — forwarded on purpose.
+ expect(await countByType('os14053_exec_probe')).toBe(1);
+
+ // …and the run SAYS so. The refusal line drops the flat claim (the
+ // colon directly after "boot" is the dropped phrase), the forwarded
+ // call is named with its count, and no note in the run claims the
+ // plan wrote nothing. 4 refusals: the host config's plugin on three
+ // phases, plus this fixture's in-run control.
+ const notes = stack.composition.notes.join(' ');
+ expect(notes).toContain('Refused 4 write(s) during the declaration boot:');
+ expect(notes).toContain('Raw execute() was called 1 time(s) during the declaration boot');
+ expect(notes).not.toContain('a plan writes nothing');
+
+ // The guard's structural surface carries it too, for `--json` consumers.
+ expect(stack.composition.writeGuard?.rawExecutions).toEqual([
+ expect.objectContaining({ count: 1 }),
+ ]);
+ } finally {
+ await stack.shutdown();
+ }
+ }, 60_000);
+});

packages/cli/src/utils/schema-migrate.ts

@@ -350,6 +350,18 @@ export async function bootSchemaStack(
  }
  await runtime.start();
 
+ // #13332 — the kernel bootstrap is over, and with it the window the
+ // declaration boot's write guard covers. `composeForDeclarations` suppresses
+ // a host plugin's `start()`, but `kernel.ts` fires `kernel:ready`,
+ // `kernel:bootstrapped` and `kernel:listening` unconditionally afterwards, so
+ // a hook REGISTERED from `init()` runs on a plan; the guard refuses those
+ // writes at the driver instead of at a list of phase names. Everything from
+ // this line on is work the command was ASKED for — `apply`'s confirmed DDL
+ // flush, the #13028 coverage pass — so the guard comes off here and reports
+ // whatever it refused, which the plan prints and `--json` carries.
+ const refusalNote = composition.writeGuard?.disarm() ?? null;
+ if (refusalNote) composition.notes.push(refusalNote);
+
  const driver = findSqlDriver(kernel);
 
  // #13028 — the composed host declared its objects in `init()`; the pass that