fix(cli): close the declaration-boot write guard's two named boundaries — engine-held drivers and immediate DDL

.changeset/declaration-boot-guard-boundaries.md

@@ -0,0 +1,12 @@
+---
+"@objectstack/cli": patch
+---
+
+fix(cli): close the declaration-boot write guard's two named boundaries — engine-held drivers and immediate DDL (#14126)
+
+`os migrate plan` / `os migrate apply` boot host plugins for their declarations behind a guard that refuses the contract's row writes and, since #13332 / #14053, prints "a plan writes nothing" only when that held. Two boundaries were left open and named in the guard's own census; both are now covered, under ONE outcome-line rule:
+
+- **Engine-held drivers.** Only the default datasource is published as `driver.*`; every other driver reaches the engine through `engine.registerDriver` alone (`DatasourceConnectionService.connect()`, `AppPlugin`'s `drivers.register`, `ObjectQL.create`), so a hook writing to an object bound to a second datasource landed during a plan. The guard now shadows `registerDriver` on the engine instance the kernel publishes (`objectql` / `data`) for the length of the boot, arms each driver instance in place as it is registered — forwarding the SAME instance, never a wrapper, never a second registration under a held name — reaches drivers the engine already held through its public accessors, and restores the engine on `disarm()`. Such a write is now refused and reported as `via engine.<datasource>`.
+- **Immediate DDL.** `dropTable()` / `rotateShards()` are not held back by the schema deferral and execute immediately. They are still not refused (refusing DDL an operator's own hook asked for is out of this guard's scope) — but they now get `execute()`'s treatment: forwarded, counted per driver/method/object, warned once per driver on stderr, named in the notes, and the run no longer claims "a plan writes nothing".
+
+The rule, decided once: the claim prints only when it held across everything the guard can see — every write refused, nothing forwarded (raw `execute()`, immediate DDL), and no instance that refused the override (a frozen driver, an engine that could not be shadowed). Each of those is named in the notes and withholds the line. An embedder with no data plane, and read/log-only hooks, are untouched: a quiet boot still renders byte-identically.

packages/cli/src/utils/schema-migrate.deferred-ddl.integration.test.ts

@@ -18,7 +18,9 @@ import { mkdtempSync, writeFileSync, mkdirSync, rmSync, existsSync, statSync } f
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { SqlDriver } from '@objectstack/driver-sql';
+import type { Plugin, PluginContext } from '@objectstack/core';
 import { bootSchemaStack } from './schema-migrate.js';
+import { composeForDeclarations } from './schema-migration-plugins.js';
 
 const ARTIFACT = {
  // #8687: manifest fields under `manifest:` — the flat spelling is refused.
@@ -166,4 +168,62 @@ describe('bootSchemaStack({ deferSchemaDdl }) — the boot writes nothing (#3917
  await stack.shutdown();
  }
  }, 60_000);
+
+ it('a hook that drops a table during the declaration boot: the DDL EXECUTES (forwarded), and the notes say so instead of claiming the boot wrote nothing (#14126)', async () => {
+ // The guard's census names `dropTable()` as immediate DDL: it runs
+ // `assertSchemaMutable`, not the deferral, and executes. Measured here on
+ // the real driver over the real file — the deferral held back every
+ // CREATE/ALTER of the two cases above, and this DROP goes straight
+ // through. What #14126 changes is not the execution but its silence: the
+ // call is counted and named, and the run does not print "a plan writes
+ // nothing" over a table it dropped.
+ const before = await inspect();
+ expect(before.tables).toEqual(['defer_widget']);
+
+ let via = '';
+ const dropsATable: Plugin = {
+ name: 'com.example.drops-a-table-from-a-hook',
+ version: '1.0.0',
+ init: async (ctx: PluginContext) => {
+ ctx.hook('kernel:ready', async () => {
+ for (const [name, service] of ctx.getServices().entries()) {
+ if (name.startsWith('driver.') && typeof service?.dropTable === 'function') {
+ via = name;
+ await service.dropTable('defer_widget');
+ return;
+ }
+ }
+ throw new Error('no driver.* service with dropTable() to drop through');
+ });
+ },
+ };
+
+ const stack = await bootSchemaStack({
+ jsonOutput: false,
+ databaseUrl: `file:${dbFile}`,
+ deferSchemaDdl: true,
+ projectRoot: dir,
+ // The artifact makes this a COMPOSED boot, which is what arms the guard.
+ composeHostStack: true,
+ extraPlugins: [composeForDeclarations(dropsATable)],
+ });
+ try {
+ const after = await inspect();
+ expect(via).not.toBe('');
+ // FORWARDED: the table is really gone.
+ expect(after.tables).not.toContain('defer_widget');
+ // COUNTED, on the guard's own surface…
+ expect(stack.composition.writeGuard?.immediateDdl).toEqual([
+ { driver: via, method: 'dropTable', object: 'defer_widget', count: 1 },
+ ]);
+ // …and REPORTED in the notes the plan prints, with the claim withheld.
+ const notes = stack.composition.notes.join('\n');
+ expect(notes).toContain(
+ `Immediate DDL was called 1 time(s) during the declaration boot (dropTable() on defer_widget via ${via})`,
+ );
+ expect(notes).not.toContain('a plan writes nothing');
+ } finally {
+ await stack.shutdown();
+ }
+ }, 60_000);
 });

.changeset/declaration-boot-guard-boundaries.md

@@ -0,0 +1,12 @@
+---
+"@objectstack/cli": patch
+---
+
+fix(cli): close the declaration-boot write guard's two named boundaries — engine-held drivers and immediate DDL (#14126)
+
+`os migrate plan` / `os migrate apply` boot host plugins for their declarations behind a guard that refuses the contract's row writes and, since #13332 / #14053, prints "a plan writes nothing" only when that held. Two boundaries were left open and named in the guard's own census; both are now covered, under ONE outcome-line rule:
+
+- **Engine-held drivers.** Only the default datasource is published as `driver.*`; every other driver reaches the engine through `engine.registerDriver` alone (`DatasourceConnectionService.connect()`, `AppPlugin`'s `drivers.register`, `ObjectQL.create`), so a hook writing to an object bound to a second datasource landed during a plan. The guard now shadows `registerDriver` on the engine instance the kernel publishes (`objectql` / `data`) for the length of the boot, arms each driver instance in place as it is registered — forwarding the SAME instance, never a wrapper, never a second registration under a held name — reaches drivers the engine already held through its public accessors, and restores the engine on `disarm()`. Such a write is now refused and reported as `via engine.<datasource>`.
+- **Immediate DDL.** `dropTable()` / `rotateShards()` are not held back by the schema deferral and execute immediately. They are still not refused (refusing DDL an operator's own hook asked for is out of this guard's scope) — but they now get `execute()`'s treatment: forwarded, counted per driver/method/object, warned once per driver on stderr, named in the notes, and the run no longer claims "a plan writes nothing".
+
+The rule, decided once: the claim prints only when it held across everything the guard can see — every write refused, nothing forwarded (raw `execute()`, immediate DDL), and no instance that refused the override (a frozen driver, an engine that could not be shadowed). Each of those is named in the notes and withholds the line. An embedder with no data plane, and read/log-only hooks, are untouched: a quiet boot still renders byte-identically.

packages/cli/src/utils/schema-migrate.deferred-ddl.integration.test.ts

@@ -18,7 +18,9 @@ import { mkdtempSync, writeFileSync, mkdirSync, rmSync, existsSync, statSync } f
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { SqlDriver } from '@objectstack/driver-sql';
+import type { Plugin, PluginContext } from '@objectstack/core';
 import { bootSchemaStack } from './schema-migrate.js';
+import { composeForDeclarations } from './schema-migration-plugins.js';
 
 const ARTIFACT = {
  // #8687: manifest fields under `manifest:` — the flat spelling is refused.
@@ -166,4 +168,62 @@ describe('bootSchemaStack({ deferSchemaDdl }) — the boot writes nothing (#3917
  await stack.shutdown();
  }
  }, 60_000);
+
+ it('a hook that drops a table during the declaration boot: the DDL EXECUTES (forwarded), and the notes say so instead of claiming the boot wrote nothing (#14126)', async () => {
+ // The guard's census names `dropTable()` as immediate DDL: it runs
+ // `assertSchemaMutable`, not the deferral, and executes. Measured here on
+ // the real driver over the real file — the deferral held back every
+ // CREATE/ALTER of the two cases above, and this DROP goes straight
+ // through. What #14126 changes is not the execution but its silence: the
+ // call is counted and named, and the run does not print "a plan writes
+ // nothing" over a table it dropped.
+ const before = await inspect();
+ expect(before.tables).toEqual(['defer_widget']);
+
+ let via = '';
+ const dropsATable: Plugin = {
+ name: 'com.example.drops-a-table-from-a-hook',
+ version: '1.0.0',
+ init: async (ctx: PluginContext) => {
+ ctx.hook('kernel:ready', async () => {
+ for (const [name, service] of ctx.getServices().entries()) {
+ if (name.startsWith('driver.') && typeof service?.dropTable === 'function') {
+ via = name;
+ await service.dropTable('defer_widget');
+ return;
+ }
+ }
+ throw new Error('no driver.* service with dropTable() to drop through');
+ });
+ },
+ };
+
+ const stack = await bootSchemaStack({
+ jsonOutput: false,
+ databaseUrl: `file:${dbFile}`,
+ deferSchemaDdl: true,
+ projectRoot: dir,
+ // The artifact makes this a COMPOSED boot, which is what arms the guard.
+ composeHostStack: true,
+ extraPlugins: [composeForDeclarations(dropsATable)],
+ });
+ try {
+ const after = await inspect();
+ expect(via).not.toBe('');
+ // FORWARDED: the table is really gone.
+ expect(after.tables).not.toContain('defer_widget');
+ // COUNTED, on the guard's own surface…
+ expect(stack.composition.writeGuard?.immediateDdl).toEqual([
+ { driver: via, method: 'dropTable', object: 'defer_widget', count: 1 },
+ ]);
+ // …and REPORTED in the notes the plan prints, with the claim withheld.
+ const notes = stack.composition.notes.join('\n');
+ expect(notes).toContain(
+ `Immediate DDL was called 1 time(s) during the declaration boot (dropTable() on defer_widget via ${via})`,
+ );
+ expect(notes).not.toContain('a plan writes nothing');
+ } finally {
+ await stack.shutdown();
+ }
+ }, 60_000);
 });

.changeset/declaration-boot-guard-boundaries.md

@@ -0,0 +1,12 @@
+---
+"@objectstack/cli": patch
+---
+
+fix(cli): close the declaration-boot write guard's two named boundaries — engine-held drivers and immediate DDL (#14126)
+
+`os migrate plan` / `os migrate apply` boot host plugins for their declarations behind a guard that refuses the contract's row writes and, since #13332 / #14053, prints "a plan writes nothing" only when that held. Two boundaries were left open and named in the guard's own census; both are now covered, under ONE outcome-line rule:
+
+- **Engine-held drivers.** Only the default datasource is published as `driver.*`; every other driver reaches the engine through `engine.registerDriver` alone (`DatasourceConnectionService.connect()`, `AppPlugin`'s `drivers.register`, `ObjectQL.create`), so a hook writing to an object bound to a second datasource landed during a plan. The guard now shadows `registerDriver` on the engine instance the kernel publishes (`objectql` / `data`) for the length of the boot, arms each driver instance in place as it is registered — forwarding the SAME instance, never a wrapper, never a second registration under a held name — reaches drivers the engine already held through its public accessors, and restores the engine on `disarm()`. Such a write is now refused and reported as `via engine.<datasource>`.
+- **Immediate DDL.** `dropTable()` / `rotateShards()` are not held back by the schema deferral and execute immediately. They are still not refused (refusing DDL an operator's own hook asked for is out of this guard's scope) — but they now get `execute()`'s treatment: forwarded, counted per driver/method/object, warned once per driver on stderr, named in the notes, and the run no longer claims "a plan writes nothing".
+
+The rule, decided once: the claim prints only when it held across everything the guard can see — every write refused, nothing forwarded (raw `execute()`, immediate DDL), and no instance that refused the override (a frozen driver, an engine that could not be shadowed). Each of those is named in the notes and withholds the line. An embedder with no data plane, and read/log-only hooks, are untouched: a quiet boot still renders byte-identically.

packages/cli/src/utils/schema-migrate.deferred-ddl.integration.test.ts

@@ -18,7 +18,9 @@ import { mkdtempSync, writeFileSync, mkdirSync, rmSync, existsSync, statSync } f
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { SqlDriver } from '@objectstack/driver-sql';
+import type { Plugin, PluginContext } from '@objectstack/core';
 import { bootSchemaStack } from './schema-migrate.js';
+import { composeForDeclarations } from './schema-migration-plugins.js';
 
 const ARTIFACT = {
  // #8687: manifest fields under `manifest:` — the flat spelling is refused.
@@ -166,4 +168,62 @@ describe('bootSchemaStack({ deferSchemaDdl }) — the boot writes nothing (#3917
  await stack.shutdown();
  }
  }, 60_000);
+
+ it('a hook that drops a table during the declaration boot: the DDL EXECUTES (forwarded), and the notes say so instead of claiming the boot wrote nothing (#14126)', async () => {
+ // The guard's census names `dropTable()` as immediate DDL: it runs
+ // `assertSchemaMutable`, not the deferral, and executes. Measured here on
+ // the real driver over the real file — the deferral held back every
+ // CREATE/ALTER of the two cases above, and this DROP goes straight
+ // through. What #14126 changes is not the execution but its silence: the
+ // call is counted and named, and the run does not print "a plan writes
+ // nothing" over a table it dropped.
+ const before = await inspect();
+ expect(before.tables).toEqual(['defer_widget']);
+
+ let via = '';
+ const dropsATable: Plugin = {
+ name: 'com.example.drops-a-table-from-a-hook',
+ version: '1.0.0',
+ init: async (ctx: PluginContext) => {
+ ctx.hook('kernel:ready', async () => {
+ for (const [name, service] of ctx.getServices().entries()) {
+ if (name.startsWith('driver.') && typeof service?.dropTable === 'function') {
+ via = name;
+ await service.dropTable('defer_widget');
+ return;
+ }
+ }
+ throw new Error('no driver.* service with dropTable() to drop through');
+ });
+ },
+ };
+
+ const stack = await bootSchemaStack({
+ jsonOutput: false,
+ databaseUrl: `file:${dbFile}`,
+ deferSchemaDdl: true,
+ projectRoot: dir,
+ // The artifact makes this a COMPOSED boot, which is what arms the guard.
+ composeHostStack: true,
+ extraPlugins: [composeForDeclarations(dropsATable)],
+ });
+ try {
+ const after = await inspect();
+ expect(via).not.toBe('');
+ // FORWARDED: the table is really gone.
+ expect(after.tables).not.toContain('defer_widget');
+ // COUNTED, on the guard's own surface…
+ expect(stack.composition.writeGuard?.immediateDdl).toEqual([
+ { driver: via, method: 'dropTable', object: 'defer_widget', count: 1 },
+ ]);
+ // …and REPORTED in the notes the plan prints, with the claim withheld.
+ const notes = stack.composition.notes.join('\n');
+ expect(notes).toContain(
+ `Immediate DDL was called 1 time(s) during the declaration boot (dropTable() on defer_widget via ${via})`,
+ );
+ expect(notes).not.toContain('a plan writes nothing');
+ } finally {
+ await stack.shutdown();
+ }
+ }, 60_000);
 });

.changeset/declaration-boot-guard-boundaries.md

@@ -0,0 +1,12 @@
+---
+"@objectstack/cli": patch
+---
+
+fix(cli): close the declaration-boot write guard's two named boundaries — engine-held drivers and immediate DDL (#14126)
+
+`os migrate plan` / `os migrate apply` boot host plugins for their declarations behind a guard that refuses the contract's row writes and, since #13332 / #14053, prints "a plan writes nothing" only when that held. Two boundaries were left open and named in the guard's own census; both are now covered, under ONE outcome-line rule:
+
+- **Engine-held drivers.** Only the default datasource is published as `driver.*`; every other driver reaches the engine through `engine.registerDriver` alone (`DatasourceConnectionService.connect()`, `AppPlugin`'s `drivers.register`, `ObjectQL.create`), so a hook writing to an object bound to a second datasource landed during a plan. The guard now shadows `registerDriver` on the engine instance the kernel publishes (`objectql` / `data`) for the length of the boot, arms each driver instance in place as it is registered — forwarding the SAME instance, never a wrapper, never a second registration under a held name — reaches drivers the engine already held through its public accessors, and restores the engine on `disarm()`. Such a write is now refused and reported as `via engine.<datasource>`.
+- **Immediate DDL.** `dropTable()` / `rotateShards()` are not held back by the schema deferral and execute immediately. They are still not refused (refusing DDL an operator's own hook asked for is out of this guard's scope) — but they now get `execute()`'s treatment: forwarded, counted per driver/method/object, warned once per driver on stderr, named in the notes, and the run no longer claims "a plan writes nothing".
+
+The rule, decided once: the claim prints only when it held across everything the guard can see — every write refused, nothing forwarded (raw `execute()`, immediate DDL), and no instance that refused the override (a frozen driver, an engine that could not be shadowed). Each of those is named in the notes and withholds the line. An embedder with no data plane, and read/log-only hooks, are untouched: a quiet boot still renders byte-identically.

packages/cli/src/utils/schema-migrate.deferred-ddl.integration.test.ts

@@ -18,7 +18,9 @@ import { mkdtempSync, writeFileSync, mkdirSync, rmSync, existsSync, statSync } f
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { SqlDriver } from '@objectstack/driver-sql';
+import type { Plugin, PluginContext } from '@objectstack/core';
 import { bootSchemaStack } from './schema-migrate.js';
+import { composeForDeclarations } from './schema-migration-plugins.js';
 
 const ARTIFACT = {
  // #8687: manifest fields under `manifest:` — the flat spelling is refused.
@@ -166,4 +168,62 @@ describe('bootSchemaStack({ deferSchemaDdl }) — the boot writes nothing (#3917
  await stack.shutdown();
  }
  }, 60_000);
+
+ it('a hook that drops a table during the declaration boot: the DDL EXECUTES (forwarded), and the notes say so instead of claiming the boot wrote nothing (#14126)', async () => {
+ // The guard's census names `dropTable()` as immediate DDL: it runs
+ // `assertSchemaMutable`, not the deferral, and executes. Measured here on
+ // the real driver over the real file — the deferral held back every
+ // CREATE/ALTER of the two cases above, and this DROP goes straight
+ // through. What #14126 changes is not the execution but its silence: the
+ // call is counted and named, and the run does not print "a plan writes
+ // nothing" over a table it dropped.
+ const before = await inspect();
+ expect(before.tables).toEqual(['defer_widget']);
+
+ let via = '';
+ const dropsATable: Plugin = {
+ name: 'com.example.drops-a-table-from-a-hook',
+ version: '1.0.0',
+ init: async (ctx: PluginContext) => {
+ ctx.hook('kernel:ready', async () => {
+ for (const [name, service] of ctx.getServices().entries()) {
+ if (name.startsWith('driver.') && typeof service?.dropTable === 'function') {
+ via = name;
+ await service.dropTable('defer_widget');
+ return;
+ }
+ }
+ throw new Error('no driver.* service with dropTable() to drop through');
+ });
+ },
+ };
+
+ const stack = await bootSchemaStack({
+ jsonOutput: false,
+ databaseUrl: `file:${dbFile}`,
+ deferSchemaDdl: true,
+ projectRoot: dir,
+ // The artifact makes this a COMPOSED boot, which is what arms the guard.
+ composeHostStack: true,
+ extraPlugins: [composeForDeclarations(dropsATable)],
+ });
+ try {
+ const after = await inspect();
+ expect(via).not.toBe('');
+ // FORWARDED: the table is really gone.
+ expect(after.tables).not.toContain('defer_widget');
+ // COUNTED, on the guard's own surface…
+ expect(stack.composition.writeGuard?.immediateDdl).toEqual([
+ { driver: via, method: 'dropTable', object: 'defer_widget', count: 1 },
+ ]);
+ // …and REPORTED in the notes the plan prints, with the claim withheld.
+ const notes = stack.composition.notes.join('\n');
+ expect(notes).toContain(
+ `Immediate DDL was called 1 time(s) during the declaration boot (dropTable() on defer_widget via ${via})`,
+ );
+ expect(notes).not.toContain('a plan writes nothing');
+ } finally {
+ await stack.shutdown();
+ }
+ }, 60_000);
 });

.changeset/declaration-boot-guard-boundaries.md

@@ -0,0 +1,12 @@
+---
+"@objectstack/cli": patch
+---
+
+fix(cli): close the declaration-boot write guard's two named boundaries — engine-held drivers and immediate DDL (#14126)
+
+`os migrate plan` / `os migrate apply` boot host plugins for their declarations behind a guard that refuses the contract's row writes and, since #13332 / #14053, prints "a plan writes nothing" only when that held. Two boundaries were left open and named in the guard's own census; both are now covered, under ONE outcome-line rule:
+
+- **Engine-held drivers.** Only the default datasource is published as `driver.*`; every other driver reaches the engine through `engine.registerDriver` alone (`DatasourceConnectionService.connect()`, `AppPlugin`'s `drivers.register`, `ObjectQL.create`), so a hook writing to an object bound to a second datasource landed during a plan. The guard now shadows `registerDriver` on the engine instance the kernel publishes (`objectql` / `data`) for the length of the boot, arms each driver instance in place as it is registered — forwarding the SAME instance, never a wrapper, never a second registration under a held name — reaches drivers the engine already held through its public accessors, and restores the engine on `disarm()`. Such a write is now refused and reported as `via engine.<datasource>`.
+- **Immediate DDL.** `dropTable()` / `rotateShards()` are not held back by the schema deferral and execute immediately. They are still not refused (refusing DDL an operator's own hook asked for is out of this guard's scope) — but they now get `execute()`'s treatment: forwarded, counted per driver/method/object, warned once per driver on stderr, named in the notes, and the run no longer claims "a plan writes nothing".
+
+The rule, decided once: the claim prints only when it held across everything the guard can see — every write refused, nothing forwarded (raw `execute()`, immediate DDL), and no instance that refused the override (a frozen driver, an engine that could not be shadowed). Each of those is named in the notes and withholds the line. An embedder with no data plane, and read/log-only hooks, are untouched: a quiet boot still renders byte-identically.

packages/cli/src/utils/schema-migrate.deferred-ddl.integration.test.ts

@@ -18,7 +18,9 @@ import { mkdtempSync, writeFileSync, mkdirSync, rmSync, existsSync, statSync } f
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { SqlDriver } from '@objectstack/driver-sql';
+import type { Plugin, PluginContext } from '@objectstack/core';
 import { bootSchemaStack } from './schema-migrate.js';
+import { composeForDeclarations } from './schema-migration-plugins.js';
 
 const ARTIFACT = {
  // #8687: manifest fields under `manifest:` — the flat spelling is refused.
@@ -166,4 +168,62 @@ describe('bootSchemaStack({ deferSchemaDdl }) — the boot writes nothing (#3917
  await stack.shutdown();
  }
  }, 60_000);
+
+ it('a hook that drops a table during the declaration boot: the DDL EXECUTES (forwarded), and the notes say so instead of claiming the boot wrote nothing (#14126)', async () => {
+ // The guard's census names `dropTable()` as immediate DDL: it runs
+ // `assertSchemaMutable`, not the deferral, and executes. Measured here on
+ // the real driver over the real file — the deferral held back every
+ // CREATE/ALTER of the two cases above, and this DROP goes straight
+ // through. What #14126 changes is not the execution but its silence: the
+ // call is counted and named, and the run does not print "a plan writes
+ // nothing" over a table it dropped.
+ const before = await inspect();
+ expect(before.tables).toEqual(['defer_widget']);
+
+ let via = '';
+ const dropsATable: Plugin = {
+ name: 'com.example.drops-a-table-from-a-hook',
+ version: '1.0.0',
+ init: async (ctx: PluginContext) => {
+ ctx.hook('kernel:ready', async () => {
+ for (const [name, service] of ctx.getServices().entries()) {
+ if (name.startsWith('driver.') && typeof service?.dropTable === 'function') {
+ via = name;
+ await service.dropTable('defer_widget');
+ return;
+ }
+ }
+ throw new Error('no driver.* service with dropTable() to drop through');
+ });
+ },
+ };
+
+ const stack = await bootSchemaStack({
+ jsonOutput: false,
+ databaseUrl: `file:${dbFile}`,
+ deferSchemaDdl: true,
+ projectRoot: dir,
+ // The artifact makes this a COMPOSED boot, which is what arms the guard.
+ composeHostStack: true,
+ extraPlugins: [composeForDeclarations(dropsATable)],
+ });
+ try {
+ const after = await inspect();
+ expect(via).not.toBe('');
+ // FORWARDED: the table is really gone.
+ expect(after.tables).not.toContain('defer_widget');
+ // COUNTED, on the guard's own surface…
+ expect(stack.composition.writeGuard?.immediateDdl).toEqual([
+ { driver: via, method: 'dropTable', object: 'defer_widget', count: 1 },
+ ]);
+ // …and REPORTED in the notes the plan prints, with the claim withheld.
+ const notes = stack.composition.notes.join('\n');
+ expect(notes).toContain(
+ `Immediate DDL was called 1 time(s) during the declaration boot (dropTable() on defer_widget via ${via})`,
+ );
+ expect(notes).not.toContain('a plan writes nothing');
+ } finally {
+ await stack.shutdown();
+ }
+ }, 60_000);
 });

.changeset/declaration-boot-guard-boundaries.md

@@ -0,0 +1,12 @@
+---
+"@objectstack/cli": patch
+---
+
+fix(cli): close the declaration-boot write guard's two named boundaries — engine-held drivers and immediate DDL (#14126)
+
+`os migrate plan` / `os migrate apply` boot host plugins for their declarations behind a guard that refuses the contract's row writes and, since #13332 / #14053, prints "a plan writes nothing" only when that held. Two boundaries were left open and named in the guard's own census; both are now covered, under ONE outcome-line rule:
+
+- **Engine-held drivers.** Only the default datasource is published as `driver.*`; every other driver reaches the engine through `engine.registerDriver` alone (`DatasourceConnectionService.connect()`, `AppPlugin`'s `drivers.register`, `ObjectQL.create`), so a hook writing to an object bound to a second datasource landed during a plan. The guard now shadows `registerDriver` on the engine instance the kernel publishes (`objectql` / `data`) for the length of the boot, arms each driver instance in place as it is registered — forwarding the SAME instance, never a wrapper, never a second registration under a held name — reaches drivers the engine already held through its public accessors, and restores the engine on `disarm()`. Such a write is now refused and reported as `via engine.<datasource>`.
+- **Immediate DDL.** `dropTable()` / `rotateShards()` are not held back by the schema deferral and execute immediately. They are still not refused (refusing DDL an operator's own hook asked for is out of this guard's scope) — but they now get `execute()`'s treatment: forwarded, counted per driver/method/object, warned once per driver on stderr, named in the notes, and the run no longer claims "a plan writes nothing".
+
+The rule, decided once: the claim prints only when it held across everything the guard can see — every write refused, nothing forwarded (raw `execute()`, immediate DDL), and no instance that refused the override (a frozen driver, an engine that could not be shadowed). Each of those is named in the notes and withholds the line. An embedder with no data plane, and read/log-only hooks, are untouched: a quiet boot still renders byte-identically.

packages/cli/src/utils/schema-migrate.deferred-ddl.integration.test.ts

@@ -18,7 +18,9 @@ import { mkdtempSync, writeFileSync, mkdirSync, rmSync, existsSync, statSync } f
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { SqlDriver } from '@objectstack/driver-sql';
+import type { Plugin, PluginContext } from '@objectstack/core';
 import { bootSchemaStack } from './schema-migrate.js';
+import { composeForDeclarations } from './schema-migration-plugins.js';
 
 const ARTIFACT = {
  // #8687: manifest fields under `manifest:` — the flat spelling is refused.
@@ -166,4 +168,62 @@ describe('bootSchemaStack({ deferSchemaDdl }) — the boot writes nothing (#3917
  await stack.shutdown();
  }
  }, 60_000);
+
+ it('a hook that drops a table during the declaration boot: the DDL EXECUTES (forwarded), and the notes say so instead of claiming the boot wrote nothing (#14126)', async () => {
+ // The guard's census names `dropTable()` as immediate DDL: it runs
+ // `assertSchemaMutable`, not the deferral, and executes. Measured here on
+ // the real driver over the real file — the deferral held back every
+ // CREATE/ALTER of the two cases above, and this DROP goes straight
+ // through. What #14126 changes is not the execution but its silence: the
+ // call is counted and named, and the run does not print "a plan writes
+ // nothing" over a table it dropped.
+ const before = await inspect();
+ expect(before.tables).toEqual(['defer_widget']);
+
+ let via = '';
+ const dropsATable: Plugin = {
+ name: 'com.example.drops-a-table-from-a-hook',
+ version: '1.0.0',
+ init: async (ctx: PluginContext) => {
+ ctx.hook('kernel:ready', async () => {
+ for (const [name, service] of ctx.getServices().entries()) {
+ if (name.startsWith('driver.') && typeof service?.dropTable === 'function') {
+ via = name;
+ await service.dropTable('defer_widget');
+ return;
+ }
+ }
+ throw new Error('no driver.* service with dropTable() to drop through');
+ });
+ },
+ };
+
+ const stack = await bootSchemaStack({
+ jsonOutput: false,
+ databaseUrl: `file:${dbFile}`,
+ deferSchemaDdl: true,
+ projectRoot: dir,
+ // The artifact makes this a COMPOSED boot, which is what arms the guard.
+ composeHostStack: true,
+ extraPlugins: [composeForDeclarations(dropsATable)],
+ });
+ try {
+ const after = await inspect();
+ expect(via).not.toBe('');
+ // FORWARDED: the table is really gone.
+ expect(after.tables).not.toContain('defer_widget');
+ // COUNTED, on the guard's own surface…
+ expect(stack.composition.writeGuard?.immediateDdl).toEqual([
+ { driver: via, method: 'dropTable', object: 'defer_widget', count: 1 },
+ ]);
+ // …and REPORTED in the notes the plan prints, with the claim withheld.
+ const notes = stack.composition.notes.join('\n');
+ expect(notes).toContain(
+ `Immediate DDL was called 1 time(s) during the declaration boot (dropTable() on defer_widget via ${via})`,
+ );
+ expect(notes).not.toContain('a plan writes nothing');
+ } finally {
+ await stack.shutdown();
+ }
+ }, 60_000);
 });

.changeset/declaration-boot-guard-boundaries.md

@@ -0,0 +1,12 @@
+---
+"@objectstack/cli": patch
+---
+
+fix(cli): close the declaration-boot write guard's two named boundaries — engine-held drivers and immediate DDL (#14126)
+
+`os migrate plan` / `os migrate apply` boot host plugins for their declarations behind a guard that refuses the contract's row writes and, since #13332 / #14053, prints "a plan writes nothing" only when that held. Two boundaries were left open and named in the guard's own census; both are now covered, under ONE outcome-line rule:
+
+- **Engine-held drivers.** Only the default datasource is published as `driver.*`; every other driver reaches the engine through `engine.registerDriver` alone (`DatasourceConnectionService.connect()`, `AppPlugin`'s `drivers.register`, `ObjectQL.create`), so a hook writing to an object bound to a second datasource landed during a plan. The guard now shadows `registerDriver` on the engine instance the kernel publishes (`objectql` / `data`) for the length of the boot, arms each driver instance in place as it is registered — forwarding the SAME instance, never a wrapper, never a second registration under a held name — reaches drivers the engine already held through its public accessors, and restores the engine on `disarm()`. Such a write is now refused and reported as `via engine.<datasource>`.
+- **Immediate DDL.** `dropTable()` / `rotateShards()` are not held back by the schema deferral and execute immediately. They are still not refused (refusing DDL an operator's own hook asked for is out of this guard's scope) — but they now get `execute()`'s treatment: forwarded, counted per driver/method/object, warned once per driver on stderr, named in the notes, and the run no longer claims "a plan writes nothing".
+
+The rule, decided once: the claim prints only when it held across everything the guard can see — every write refused, nothing forwarded (raw `execute()`, immediate DDL), and no instance that refused the override (a frozen driver, an engine that could not be shadowed). Each of those is named in the notes and withholds the line. An embedder with no data plane, and read/log-only hooks, are untouched: a quiet boot still renders byte-identically.

packages/cli/src/utils/schema-migrate.deferred-ddl.integration.test.ts

@@ -18,7 +18,9 @@ import { mkdtempSync, writeFileSync, mkdirSync, rmSync, existsSync, statSync } f
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { SqlDriver } from '@objectstack/driver-sql';
+import type { Plugin, PluginContext } from '@objectstack/core';
 import { bootSchemaStack } from './schema-migrate.js';
+import { composeForDeclarations } from './schema-migration-plugins.js';
 
 const ARTIFACT = {
  // #8687: manifest fields under `manifest:` — the flat spelling is refused.
@@ -166,4 +168,62 @@ describe('bootSchemaStack({ deferSchemaDdl }) — the boot writes nothing (#3917
  await stack.shutdown();
  }
  }, 60_000);
+
+ it('a hook that drops a table during the declaration boot: the DDL EXECUTES (forwarded), and the notes say so instead of claiming the boot wrote nothing (#14126)', async () => {
+ // The guard's census names `dropTable()` as immediate DDL: it runs
+ // `assertSchemaMutable`, not the deferral, and executes. Measured here on
+ // the real driver over the real file — the deferral held back every
+ // CREATE/ALTER of the two cases above, and this DROP goes straight
+ // through. What #14126 changes is not the execution but its silence: the
+ // call is counted and named, and the run does not print "a plan writes
+ // nothing" over a table it dropped.
+ const before = await inspect();
+ expect(before.tables).toEqual(['defer_widget']);
+
+ let via = '';
+ const dropsATable: Plugin = {
+ name: 'com.example.drops-a-table-from-a-hook',
+ version: '1.0.0',
+ init: async (ctx: PluginContext) => {
+ ctx.hook('kernel:ready', async () => {
+ for (const [name, service] of ctx.getServices().entries()) {
+ if (name.startsWith('driver.') && typeof service?.dropTable === 'function') {
+ via = name;
+ await service.dropTable('defer_widget');
+ return;
+ }
+ }
+ throw new Error('no driver.* service with dropTable() to drop through');
+ });
+ },
+ };
+
+ const stack = await bootSchemaStack({
+ jsonOutput: false,
+ databaseUrl: `file:${dbFile}`,
+ deferSchemaDdl: true,
+ projectRoot: dir,
+ // The artifact makes this a COMPOSED boot, which is what arms the guard.
+ composeHostStack: true,
+ extraPlugins: [composeForDeclarations(dropsATable)],
+ });
+ try {
+ const after = await inspect();
+ expect(via).not.toBe('');
+ // FORWARDED: the table is really gone.
+ expect(after.tables).not.toContain('defer_widget');
+ // COUNTED, on the guard's own surface…
+ expect(stack.composition.writeGuard?.immediateDdl).toEqual([
+ { driver: via, method: 'dropTable', object: 'defer_widget', count: 1 },
+ ]);
+ // …and REPORTED in the notes the plan prints, with the claim withheld.
+ const notes = stack.composition.notes.join('\n');
+ expect(notes).toContain(
+ `Immediate DDL was called 1 time(s) during the declaration boot (dropTable() on defer_widget via ${via})`,
+ );
+ expect(notes).not.toContain('a plan writes nothing');
+ } finally {
+ await stack.shutdown();
+ }
+ }, 60_000);
 });

.changeset/declaration-boot-guard-boundaries.md

@@ -0,0 +1,12 @@
+---
+"@objectstack/cli": patch
+---
+
+fix(cli): close the declaration-boot write guard's two named boundaries — engine-held drivers and immediate DDL (#14126)
+
+`os migrate plan` / `os migrate apply` boot host plugins for their declarations behind a guard that refuses the contract's row writes and, since #13332 / #14053, prints "a plan writes nothing" only when that held. Two boundaries were left open and named in the guard's own census; both are now covered, under ONE outcome-line rule:
+
+- **Engine-held drivers.** Only the default datasource is published as `driver.*`; every other driver reaches the engine through `engine.registerDriver` alone (`DatasourceConnectionService.connect()`, `AppPlugin`'s `drivers.register`, `ObjectQL.create`), so a hook writing to an object bound to a second datasource landed during a plan. The guard now shadows `registerDriver` on the engine instance the kernel publishes (`objectql` / `data`) for the length of the boot, arms each driver instance in place as it is registered — forwarding the SAME instance, never a wrapper, never a second registration under a held name — reaches drivers the engine already held through its public accessors, and restores the engine on `disarm()`. Such a write is now refused and reported as `via engine.<datasource>`.
+- **Immediate DDL.** `dropTable()` / `rotateShards()` are not held back by the schema deferral and execute immediately. They are still not refused (refusing DDL an operator's own hook asked for is out of this guard's scope) — but they now get `execute()`'s treatment: forwarded, counted per driver/method/object, warned once per driver on stderr, named in the notes, and the run no longer claims "a plan writes nothing".
+
+The rule, decided once: the claim prints only when it held across everything the guard can see — every write refused, nothing forwarded (raw `execute()`, immediate DDL), and no instance that refused the override (a frozen driver, an engine that could not be shadowed). Each of those is named in the notes and withholds the line. An embedder with no data plane, and read/log-only hooks, are untouched: a quiet boot still renders byte-identically.

packages/cli/src/utils/schema-migrate.deferred-ddl.integration.test.ts

@@ -18,7 +18,9 @@ import { mkdtempSync, writeFileSync, mkdirSync, rmSync, existsSync, statSync } f
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { SqlDriver } from '@objectstack/driver-sql';
+import type { Plugin, PluginContext } from '@objectstack/core';
 import { bootSchemaStack } from './schema-migrate.js';
+import { composeForDeclarations } from './schema-migration-plugins.js';
 
 const ARTIFACT = {
  // #8687: manifest fields under `manifest:` — the flat spelling is refused.
@@ -166,4 +168,62 @@ describe('bootSchemaStack({ deferSchemaDdl }) — the boot writes nothing (#3917
  await stack.shutdown();
  }
  }, 60_000);
+
+ it('a hook that drops a table during the declaration boot: the DDL EXECUTES (forwarded), and the notes say so instead of claiming the boot wrote nothing (#14126)', async () => {
+ // The guard's census names `dropTable()` as immediate DDL: it runs
+ // `assertSchemaMutable`, not the deferral, and executes. Measured here on
+ // the real driver over the real file — the deferral held back every
+ // CREATE/ALTER of the two cases above, and this DROP goes straight
+ // through. What #14126 changes is not the execution but its silence: the
+ // call is counted and named, and the run does not print "a plan writes
+ // nothing" over a table it dropped.
+ const before = await inspect();
+ expect(before.tables).toEqual(['defer_widget']);
+
+ let via = '';
+ const dropsATable: Plugin = {
+ name: 'com.example.drops-a-table-from-a-hook',
+ version: '1.0.0',
+ init: async (ctx: PluginContext) => {
+ ctx.hook('kernel:ready', async () => {
+ for (const [name, service] of ctx.getServices().entries()) {
+ if (name.startsWith('driver.') && typeof service?.dropTable === 'function') {
+ via = name;
+ await service.dropTable('defer_widget');
+ return;
+ }
+ }
+ throw new Error('no driver.* service with dropTable() to drop through');
+ });
+ },
+ };
+
+ const stack = await bootSchemaStack({
+ jsonOutput: false,
+ databaseUrl: `file:${dbFile}`,
+ deferSchemaDdl: true,
+ projectRoot: dir,
+ // The artifact makes this a COMPOSED boot, which is what arms the guard.
+ composeHostStack: true,
+ extraPlugins: [composeForDeclarations(dropsATable)],
+ });
+ try {
+ const after = await inspect();
+ expect(via).not.toBe('');
+ // FORWARDED: the table is really gone.
+ expect(after.tables).not.toContain('defer_widget');
+ // COUNTED, on the guard's own surface…
+ expect(stack.composition.writeGuard?.immediateDdl).toEqual([
+ { driver: via, method: 'dropTable', object: 'defer_widget', count: 1 },
+ ]);
+ // …and REPORTED in the notes the plan prints, with the claim withheld.
+ const notes = stack.composition.notes.join('\n');
+ expect(notes).toContain(
+ `Immediate DDL was called 1 time(s) during the declaration boot (dropTable() on defer_widget via ${via})`,
+ );
+ expect(notes).not.toContain('a plan writes nothing');
+ } finally {
+ await stack.shutdown();
+ }
+ }, 60_000);
 });