@@ -0,0 +1,13 @@
+---
+'@objectstack/driver-sql': patch
+'@objectstack/cli': patch
+---
+
+fix(driver-sql,cli): `os migrate plan` previews a `_id`-keyed table as apply treats it, and one refused table no longer stops `os migrate apply`
+
+Clause-②: yes (widening)
+Metadata-protocol: none
+
+An existing table keyed by `_id` with no `id` column is the one shape schema sync does not adopt by adding columns: it rebuilds it while it is empty and, since #30562, refuses it while it holds rows. `os migrate plan` listed it as a harmless `add_columns` step. The plan now lists it as `apply` treats it: a `rebuild_table` entry (in place) when the table is empty, and a `refuse_table` entry when it holds rows, naming the table, the `_id` column and the row count, with the refusal's own text (`refusal`, rendered by the same renderer the sync throws through). `isRefusedSchemaWork` is exported beside `isInPlaceSchemaWork`. For a driver-sql consumer this widens the published `PendingSchemaWorkKind` / `PendingSchemaWork`: a caller of `flushDeferredSchemaDdl()` must now treat a returned `refuse_table` entry (`isRefusedSchemaWork`) as a table that was refused and left as it is, not as performed work — where that call used to throw.
+
+`os migrate apply` used to hand every held-back object to one sync call, so one refused table stopped the batch: the tables after it got no DDL and the list of performed work was lost with the error. The refused table is now left out of that call and reported on its own: every other table gets its DDL, the run names the refused table with the refusal text, and ends PARTIAL with exit 1 (`--json`: `refused` beside `created`, `message: "partial"`).
@@ -26,6 +26,9 @@ import {
   summarizePendingSchemaWork,
   groupByCategory,
   SKIPPED_SCHEMA_SYNC_NOTE,
+  describeRefusedSchemaWork,
+  splitRefusedSchemaWork,
+  addRefusedTableLimits,
 } from '../../utils/schema-migrate.js';
 import type { ManagedDriftEntry } from '@objectstack/driver-sql';
 import { exitOneShotCommand } from '../../utils/one-shot-exit.js';
@@ -347,6 +350,8 @@ export default class MigrateApply extends Command {
       // the --json document, `notApplied`, PARTIAL and the exit code never read
       // it. Empty for a driver that declares nothing, which reads as it always has.
       const limits = flags.json ? new Map<ManagedDriftEntry, string>() : collectDriftApplyLimits(stack, drift);
+      // [#30636] …and every entry on a table the sync refuses (withheld below).
+      if (!flags.json) await addRefusedTableLimits(limits, drift, pending);
       // [#24958] Each drop gate below reads at most once per run: the listing
       // and the gate share that read, so they cannot answer differently.
       const gateReads = new DropGateReads();
@@ -680,8 +685,22 @@ export default class MigrateApply extends Command {
       // marker when it created the database from empty — the half this
       // deferred boot's birth plugin could not run — so the first `os serve`
       // admits it. A database that was not empty gets none.
-      const created = await stack.flushSchemaDdl();
-      const { applied, skipped } = await stack.applyMigrationEntries(drift, { allowDestructive });
+      // [#30636] A table the sync refused (`refuse_table`: keyed by `_id`, no
+      // `id`, holding rows) comes back beside the work performed, never in a
+      // throw: every other table still got its DDL. It is not performed work,
+      // so it is never counted in `created`; it is named, and the run is PARTIAL.
+      const { performed: created, refused } = await splitRefusedSchemaWork(await stack.flushSchemaDdl());
+      // …and no drift entry on a refused table reaches the driver either: its
+      // `_id` column reads as an orphaned column, and with --allow-destructive
+      // the driver would drop it from the table the sync just left alone.
+      // Those entries are reported as skipped, never as attempted.
+      const refusedTables = new Set(refused.map((p) => p.table));
+      const onRefused = drift.filter((d) => refusedTables.has(d.table));
+      const { applied, skipped: driverSkipped } = await stack.applyMigrationEntries(
+        onRefused.length === 0 ? drift : drift.filter((d) => !refusedTables.has(d.table)),
+        { allowDestructive },
+      );
+      const skipped = [...driverSkipped, ...onRefused];
 
       // ── [#23848] NAME WHAT THE DRIVER DID NOT APPLY ──────────────────
       //
@@ -701,9 +720,9 @@ export default class MigrateApply extends Command {
       // applies (`manual_column_type_change` and its siblings) have always
       // been skipped on every dialect, and still are.
       const held = new Set<ManagedDriftEntry>(deferred);
-      const notApplied = skipped.filter((d) => !held.has(d));
+      const notApplied = driverSkipped.filter((d) => !held.has(d));
       const unappliedDestructive = notApplied.filter((d) => d.category === 'destructive');
-      const partial = unappliedDestructive.length > 0;
+      const partial = unappliedDestructive.length > 0 || refused.length > 0;
 
       if (flags.json) {
         await emitJson({
@@ -712,6 +731,7 @@ export default class MigrateApply extends Command {
           applied,
           skipped,
           notApplied,
+          ...(refused.length > 0 ? { refused } : {}),
           ...(partial ? { message: 'partial' } : {}),
           ...compositionPayload,
           duration: timer.elapsed(),
@@ -729,7 +749,7 @@ export default class MigrateApply extends Command {
       // rest are named as drift it could not apply either. [#24958] While a
       // gate holds a drop, no re-run is offered: the lines before the prompt
       // name each gate's command.
-      const heldBackEntries = skipped.filter((d) => held.has(d));
+      const heldBackEntries = driverSkipped.filter((d) => held.has(d));
       const heldBack = heldBackEntries.filter((d) => !neverReRunnable(d)).length;
       const heldBackNotReRunnable = heldBackEntries.length - heldBack;
       if (heldBack > 0) {
@@ -752,11 +772,30 @@ export default class MigrateApply extends Command {
       }
       console.log(chalk.dim(`  ${timer.display()}`));
       console.log('');
-      if (partial) {
-        printError(
-          `PARTIAL apply: ${unappliedDestructive.length} destructive change(s) confirmed with --allow-destructive were `
-          + 'NOT applied (named above), so this database still differs from its metadata.',
+      // [#30636] Each refused table, with the refusal's own text, and the drift
+      // on it this run withheld.
+      for (const p of refused) {
+        printError(`REFUSED ${describeRefusedSchemaWork(p)}`);
+        if (p.refusal) console.log(chalk.dim(`      ${p.refusal}`));
+      }
+      if (onRefused.length > 0) {
+        printWarning(
+          `${onRefused.length} change(s) on the refused table(s) were NOT applied: a refused table is left exactly as it is.`,
         );
+      }
+      if (partial) {
+        if (unappliedDestructive.length > 0) {
+          printError(
+            `PARTIAL apply: ${unappliedDestructive.length} destructive change(s) confirmed with --allow-destructive were `
+            + 'NOT applied (named above), so this database still differs from its metadata.',
+          );
+        }
+        if (refused.length > 0) {
+          printError(
+            `PARTIAL apply: schema sync REFUSED ${refused.length} existing table(s) (named above) and left them exactly `
+            + 'as they were; every other table got its DDL.',
+          );
+        }
         this.exit(1);
       }
     } catch (error: any) {
 
@@ -15,6 +15,7 @@ import {
 } from '../../utils/format.js';
 import {
   bootSchemaStack,
+  addRefusedTableLimits,
   collectDriftApplyLimits,
   describeDatabaseSource,
   describeTelemetryDatabase,
@@ -469,6 +470,8 @@ export default class MigratePlan extends Command {
       // but a drop (it runs no SQLite table rebuild). Empty for a driver that
       // declares nothing, and then everything below reads as it always has.
       const limits = collectDriftApplyLimits(stack, drift);
+      // [#30636] …and every entry on a table the sync refuses: apply leaves it as it is.
+      await addRefusedTableLimits(limits, drift, pending);
       // [#24925, #24958] The drops `os migrate apply` refuses here, each with
       // the gate that refuses it: an `organization_id` drop until the
       // organization-ownership ceremony has verified, and the
 
@@ -14,6 +14,7 @@
 import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
 import {
   renderPendingSchemaWork,
+  splitRefusedSchemaWork,
   summarizePendingSchemaWork,
   type PendingSchemaWork,
 } from './schema-migrate.js';
@@ -113,3 +114,46 @@ describe('summarizePendingSchemaWork (#3954)', () => {
     expect(summary).toContain('~1,234,625 rows');
   });
 });
+
+/**
+ * [#30636] A table keyed by `_id` with no `id` column: the plan says what apply
+ * does with it — rebuilt while empty, refused while it holds rows — and a
+ * refusal is never listed as work, additive or in place.
+ */
+describe('the `_id`-keyed table: rebuild and refusal (#30636)', () => {
+  const REFUSAL_TEXT = "Schema sync REFUSED for the existing table 'legacy_items': the driver's own text";
+  const REFUSED: PendingSchemaWork = {
+    table: 'legacy_items', kind: 'refuse_table', columns: ['_id'], rows: 3, refusal: REFUSAL_TEXT,
+  };
+  const REBUILD: PendingSchemaWork = { table: 'empty_items', kind: 'rebuild_table', columns: ['title', 'qty'], rows: 0 };
+
+  it('lists a refused table under its own heading with the driver-rendered refusal, never as work', async () => {
+    await renderPendingSchemaWork([...ADDITIVE, REFUSED]);
+    expect(out()).toContain('Refused (left exactly as it is when you apply)');
+    expect(out()).toContain('legacy_items [refuse_table: _id — 3 row(s)]');
+    expect(out()).toContain(REFUSAL_TEXT);
+    // Not under either work heading: the additive section lists only the two
+    // additive entries, and no in-place heading appears at all.
+    expect(out()).not.toContain('In place');
+    expect(out()).not.toContain('add_columns: _id');
+  });
+
+  it('lists an empty `_id`-keyed table as a rebuild under the in-place heading', async () => {
+    await renderPendingSchemaWork([REBUILD]);
+    expect(out()).toContain('In place (existing rows converged when you apply)');
+    expect(out()).toContain('empty_items [rebuild_table: empty table dropped and recreated, 2 column(s)]');
+    expect(out()).not.toContain('New (additive');
+    expect(out()).not.toContain('Refused');
+  });
+
+  it('counts rebuilds and refusals in the summary, never as temporal columns', async () => {
+    const summary = await summarizePendingSchemaWork([...ADDITIVE, REBUILD, REFUSED]);
+    expect(summary).toBe('1 table(s) to create, 1 column(s) to add, 1 empty table(s) to rebuild, 1 table(s) REFUSED');
+  });
+
+  it('splits what a flush returned into performed work and refused tables', async () => {
+    const { performed, refused } = await splitRefusedSchemaWork([...ADDITIVE, REBUILD, REFUSED]);
+    expect(performed).toEqual([...ADDITIVE, REBUILD]);
+    expect(refused).toEqual([REFUSED]);
+  });
+});
@@ -1698,6 +1698,33 @@ async function loadIsInPlaceSchemaWork(): Promise<(kind: PendingSchemaWork['kind
   return isInPlaceSchemaWork;
 }
 
+/** [#30636] The driver's refusal classifier, loaded at the point of use for the reason above. */
+async function loadIsRefusedSchemaWork(): Promise<(kind: PendingSchemaWork['kind']) => boolean> {
+  const { isRefusedSchemaWork } = await import('@objectstack/driver-sql');
+  return isRefusedSchemaWork;
+}
+
+/**
+ * [#30636] Split what {@link SchemaStack.flushSchemaDdl} returned into the
+ * work it performed and the tables the sync refused and left as they were
+ * (`refuse_table`). A refusal is never performed work: `os migrate apply`
+ * names each one and ends PARTIAL.
+ */
+export async function splitRefusedSchemaWork(
+  work: PendingSchemaWork[],
+): Promise<{ performed: PendingSchemaWork[]; refused: PendingSchemaWork[] }> {
+  const isRefusedSchemaWork = await loadIsRefusedSchemaWork();
+  return {
+    performed: work.filter((w) => !isRefusedSchemaWork(w.kind)),
+    refused: work.filter((w) => isRefusedSchemaWork(w.kind)),
+  };
+}
+
+/** [#30636] One refused table, as the plan and `os migrate apply` name it. */
+export function describeRefusedSchemaWork(p: PendingSchemaWork): string {
+  return `${p.table} [${p.kind}: ${p.columns.join(', ')} — ${formatRows(p.rows)} row(s)]`;
+}
+
 const CATEGORY_ORDER: DriftCategory[] = ['safe', 'needs_confirm', 'destructive'];
 
 const CATEGORY_META: Record<DriftCategory, { label: string; color: (s: string) => string; icon: string }> = {
@@ -1764,6 +1791,30 @@ export function collectDriftApplyLimits(
   return limits;
 }
 
+/**
+ * [#30636] Mark every drift entry on a table the schema sync refuses
+ * (`refuse_table` in `work`) with that refusal as its apply limit, in place.
+ * `os migrate apply` applies no drift on a refused table — it is left exactly
+ * as it is — so the listing must not offer `--allow-destructive` for it (the
+ * `_id` column such a table carries reads as an orphaned column to drop).
+ * Read by `os migrate plan` and by the listing `os migrate apply` prints
+ * before its prompt; `apply` itself withholds those entries from the driver.
+ */
+export async function addRefusedTableLimits(
+  limits: Map<ManagedDriftEntry, string>,
+  drift: readonly ManagedDriftEntry[],
+  work: PendingSchemaWork[],
+): Promise<void> {
+  const { refused } = await splitRefusedSchemaWork(work);
+  if (refused.length === 0) return;
+  const tables = new Set(refused.map((p) => p.table));
+  for (const d of drift) {
+    if (tables.has(d.table)) {
+      limits.set(d, `the schema sync refuses the table '${d.table}' (listed under Refused) and leaves it exactly as it is`);
+    }
+  }
+}
+
 /**
  * [#23925] The {@link renderPlan} `describe` for those entries: the finding
  * without its `--allow-destructive` sentence, then the driver's limit, so the
@@ -1808,8 +1859,9 @@ export async function renderPendingSchemaWork(pending: PendingSchemaWork[]): Pro
   if (pending.length === 0) return;
 
   const isInPlaceSchemaWork = await loadIsInPlaceSchemaWork();
-  const additive = pending.filter((p) => !isInPlaceSchemaWork(p.kind));
-  const inPlace = pending.filter((p) => isInPlaceSchemaWork(p.kind));
+  const { performed: work, refused } = await splitRefusedSchemaWork(pending);
+  const additive = work.filter((p) => !isInPlaceSchemaWork(p.kind));
+  const inPlace = work.filter((p) => isInPlaceSchemaWork(p.kind));
 
   if (additive.length > 0) {
     console.log(`  ${chalk.bold('New (additive — created when you apply)')}`);
@@ -1827,6 +1879,15 @@ export async function renderPendingSchemaWork(pending: PendingSchemaWork[]): Pro
     for (const p of inPlace) {
       // A MySQL widen is `ALTER … MODIFY`, i.e. a full table rebuild holding a
       // metadata lock — worth saying outright, not just implying via the count.
+      // [#30636] An empty `_id`-keyed table is dropped and recreated: say so,
+      // rather than listing every declared column as if each were converged.
+      if (p.kind === 'rebuild_table') {
+        console.log(
+          `    ${chalk.yellow('~')} ${chalk.yellow(p.table)} ` +
+          `${chalk.dim(`[${p.kind}: empty table dropped and recreated, ${p.columns.length} column(s)]`)}`,
+        );
+        continue;
+      }
       const cost = p.kind === 'widen_datetime_columns' || p.kind === 'widen_time_columns'
         ? `${formatRows(p.rows)} row table rebuild`
         : `${formatRows(p.rows)} row update(s)`;
@@ -1837,6 +1898,17 @@ export async function renderPendingSchemaWork(pending: PendingSchemaWork[]): Pro
     }
     console.log('');
   }
+
+  // [#30636] Work the sync will NOT do: each table it refuses, with the
+  // refusal's own text (rendered by the driver, the text `apply` reports).
+  if (refused.length > 0) {
+    console.log(`  ${chalk.bold('Refused (left exactly as it is when you apply)')}`);
+    for (const p of refused) {
+      console.log(`    ${chalk.red('✗')} ${chalk.red(describeRefusedSchemaWork(p))}`);
+      if (p.refusal) console.log(`        ${chalk.dim(p.refusal)}`);
+    }
+    console.log('');
+  }
 }
 
 /** `rows` is optional on the type; an unmeasured count reads as unknown, not zero. */
@@ -1854,11 +1926,16 @@ export async function summarizePendingSchemaWork(pending: PendingSchemaWork[]):
   // Only mentioned when there is some, so the common in-sync summary is
   // unchanged — but never omitted when there is, which is the #3954 point.
   const isInPlaceSchemaWork = await loadIsInPlaceSchemaWork();
-  const inPlace = pending.filter((p) => isInPlaceSchemaWork(p.kind));
+  const inPlace = pending.filter((p) => isInPlaceSchemaWork(p.kind) && p.kind !== 'rebuild_table');
   if (inPlace.length > 0) {
     const cols = inPlace.reduce((n, p) => n + p.columns.length, 0);
     const rows = inPlace.reduce((n, p) => n + (p.rows ?? 0), 0);
     parts.push(`${cols} temporal column(s) to converge in place (~${formatRows(rows)} rows)`);
   }
+  // [#30636] Named only when there are some, like the in-place count above.
+  const rebuilds = pending.filter((p) => p.kind === 'rebuild_table').length;
+  if (rebuilds > 0) parts.push(`${rebuilds} empty table(s) to rebuild`);
+  const { refused } = await splitRefusedSchemaWork(pending);
+  if (refused.length > 0) parts.push(`${refused.length} table(s) REFUSED`);
   return parts.join(', ');
 }