test(cli): pin the remote posture without a database — the ceremony's two opt-ins, transportRefusesDeferredDdl and the primary exemption

Co-authored-by: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Lr3rg6qTp9r38exA5DHEEH

Author: claude

packages/cli/src/commands/migrate/organization-ownership.remote-posture.test.ts

@@ -0,0 +1,142 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * #23816 — `os migrate organization-ownership` declares, at both of its boots,
+ * that a datasource whose transport cannot defer DDL (the Turso REMOTE
+ * transport) boots with schema sync skipped instead
+ * (`deferredDdlUnsupported: 'skip-schema-sync'`), and the apply reads the
+ * ledger's presence from the catalog when its boot measured no table absent.
+ *
+ * Pinned on the command's own boot call, with `bootSchemaStack` stubbed: the
+ * posture itself is `schema-migrate.remote-posture.test.ts`'s, and the
+ * end-to-end run on a real `sqld` is
+ * `organization-ownership.remote-face.integration.test.ts` (opt-in, through
+ * `OS_TEST_SQLD_BIN`). Without these two opt-ins the plan stops at its boot on
+ * every hosted tenant again, and nothing else in CI would say so.
+ */
+
+import { afterEach, beforeAll, describe, expect, it, vi } from 'vitest';
+import { mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const boot = vi.hoisted(() => vi.fn(async (_opts: Record<string, unknown>): Promise<unknown> => {
+  throw new Error('the database was opened');
+}));
+vi.mock('../../utils/schema-migrate.js', () => ({ bootSchemaStack: boot }));
+// The occupancy gate is the siblings' stub (`organization-ownership.apply-flags.test.ts`).
+vi.mock('../../utils/migrate-occupancy-gate.js', () => ({
+  OCCUPANCY_STOP_HINT: 'occupancy hint',
+  probeMigrationTarget: vi.fn(async () => ({ status: 'free' })),
+}));
+
+type Command = (typeof import('./organization-ownership.js'))['default'];
+let MigrateOrganizationOwnership: Command;
+
+beforeAll(async () => {
+  ({ default: MigrateOrganizationOwnership } = await import('./organization-ownership.js'));
+}, 60_000);
+
+const CASE_TIMEOUT_MS = 60_000;
+const CLI_ROOT = fileURLToPath(new URL('../../..', import.meta.url));
+
+const PLAN_DIR = mkdtempSync(join(tmpdir(), 'os-23816-posture-'));
+const PLAN_FILE = join(PLAN_DIR, 'plan.json');
+writeFileSync(PLAN_FILE, JSON.stringify({
+  kind: 'organization-ownership-plan',
+  ceremony: 'ADR-0131 D10',
+  generatedAt: '2026-10-16T00:00:00Z',
+  database: 'libsql://tenant.example.turso.io',
+  inventoryDigest: 'f'.repeat(64),
+  posture: 'single',
+}));
+
+async function runJson(argv: string[]): Promise<{ payload: Record<string, unknown>; exitCode: unknown }> {
+  const chunks: string[] = [];
+  const savedExit = process.exitCode;
+  vi.spyOn(process.stdout, 'write').mockImplementation(((chunk: unknown, ...rest: unknown[]) => {
+    chunks.push(String(chunk));
+    const cb = rest.find((a) => typeof a === 'function') as (() => void) | undefined;
+    if (cb) cb();
+    return true;
+  }) as typeof process.stdout.write);
+  vi.spyOn(process.stderr, 'write').mockImplementation((() => true) as typeof process.stderr.write);
+  try {
+    await MigrateOrganizationOwnership.run(argv, { root: CLI_ROOT });
+  } catch (error) {
+    if ((error as { oclif?: unknown }).oclif === undefined) throw error;
+  }
+  const exitCode = process.exitCode;
+  process.exitCode = savedExit;
+  vi.restoreAllMocks();
+  return { payload: JSON.parse(chunks.join('').trim()) as Record<string, unknown>, exitCode };
+}
+
+afterEach(() => {
+  boot.mockReset();
+  boot.mockImplementation(async () => {
+    throw new Error('the database was opened');
+  });
+});
+
+const POSTURE = { deferSchemaDdl: true, deferredDdlUnsupported: 'skip-schema-sync' };
+
+describe('both ceremony boots declare the skip-schema-sync posture', () => {
+  it('the plan boot: deferred, read-only, and skip-schema-sync where deferral is refused', async () => {
+    await runJson(['--json', '--out', join(PLAN_DIR, 'never-written.json')]);
+    expect(boot).toHaveBeenCalledTimes(1);
+    expect(boot.mock.calls[0]![0]).toEqual(expect.objectContaining({ ...POSTURE, readOnlyProbe: true }));
+  }, CASE_TIMEOUT_MS);
+
+  it('the apply boot: deferred, the served composition, and skip-schema-sync where deferral is refused', async () => {
+    await runJson(['--apply', '--plan-file', PLAN_FILE, '--backup-taken', '--json', '--out', join(PLAN_DIR, 'never-report.json')]);
+    expect(boot).toHaveBeenCalledTimes(1);
+    expect(boot.mock.calls[0]![0]).toEqual(expect.objectContaining({ ...POSTURE, composeHostStack: true }));
+  }, CASE_TIMEOUT_MS);
+});
+
+describe('the apply reads the ledger from the catalog when its boot skipped schema sync', () => {
+  /** A booted stack as `bootSchemaStack` answers it, over a raw-SQL seam that answers `catalogRows`. */
+  function stackWith(schemaSync: 'skipped' | 'deferred', opts: { catalogRows: unknown[]; tableAbsent: boolean }) {
+    const execute = vi.fn(async (sql: string) => (/pragma_table_info/.test(sql) ? opts.catalogRows : []));
+    return {
+      execute,
+      stack: {
+        schemaSync,
+        driver: { name: 'com.objectstack.driver.turso', dialectName: 'sqlite', config: { client: 'better-sqlite3' }, execute },
+        dbLabel: 'libsql://tenant.example.turso.io',
+        tableAbsent: vi.fn(() => opts.tableAbsent),
+        kernel: { getService: () => { throw new Error('no kernel in this pin'); } },
+        composition: { securityPlugin: false },
+        allObjects: () => [],
+        shutdown: async () => {},
+      },
+    };
+  }
+  const apply = () => runJson(['--apply', '--plan-file', PLAN_FILE, '--backup-taken', '--json', '--out', join(PLAN_DIR, 'never-report.json')]);
+
+  it('skipped, and the catalog has no sys_migration: refused ledger-absent, whatever tableAbsent says', async () => {
+    const { stack, execute } = stackWith('skipped', { catalogRows: [], tableAbsent: false });
+    boot.mockImplementation(async () => stack);
+    const { payload } = await apply();
+    expect(payload).toMatchObject({ error: 'apply_refused', reason: 'ledger-absent', table: 'sys_migration' });
+    expect(execute).toHaveBeenCalledWith(expect.stringContaining('pragma_table_info'), ['sys_migration']);
+    expect(stack.tableAbsent).not.toHaveBeenCalled();
+  }, CASE_TIMEOUT_MS);
+
+  it('skipped, and the catalog has sys_migration: not refused for the ledger', async () => {
+    const { stack } = stackWith('skipped', { catalogRows: [{ column_name: 'id' }], tableAbsent: true });
+    boot.mockImplementation(async () => stack);
+    const { payload } = await apply();
+    expect(payload.reason).not.toBe('ledger-absent');
+  }, CASE_TIMEOUT_MS);
+
+  it('the control: a deferred boot answers from tableAbsent, without a catalog read', async () => {
+    const { stack, execute } = stackWith('deferred', { catalogRows: [{ column_name: 'id' }], tableAbsent: true });
+    boot.mockImplementation(async () => stack);
+    const { payload } = await apply();
+    expect(payload).toMatchObject({ error: 'apply_refused', reason: 'ledger-absent' });
+    expect(execute).not.toHaveBeenCalledWith(expect.stringContaining('pragma_table_info'), ['sys_migration']);
+  }, CASE_TIMEOUT_MS);
+});

packages/cli/src/utils/schema-migrate.remote-posture.test.ts

@@ -0,0 +1,133 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * #23816 — the two pieces of `bootSchemaStack`'s `deferredDdlUnsupported:
+ * 'skip-schema-sync'` posture that decide it, pinned without a database:
+ *
+ *  - `transportRefusesDeferredDdl` answers `true` exactly for the transport
+ *    whose driver refuses deferred DDL (a `turso` datasource whose URL
+ *    `TursoDriver.detectMode` reads as `remote`), asked of the driver package,
+ *    and `false` for every other resolved database;
+ *  - `DeferSchemaDdlPlugin({ exemptPrimary: true })` leaves the engine's
+ *    DEFAULT driver un-armed and arms every other driver — the ones it finds
+ *    at `init()` and the ones registered afterwards — exactly as without the
+ *    exemption; without it, a primary that refuses the arm fails the boot.
+ *
+ * The end-to-end case (a real `sqld`, the real command) is
+ * `organization-ownership.remote-face.integration.test.ts`, which runs only
+ * where `OS_TEST_SQLD_BIN` names a server binary; these hold the CLI half in
+ * every CI run.
+ */
+
+import { describe, expect, it, vi } from 'vitest';
+import { DeferSchemaDdlPlugin, transportRefusesDeferredDdl, type SqlDriverLike } from './schema-migrate.js';
+
+describe('transportRefusesDeferredDdl', () => {
+  it.each([
+    ['turso', 'libsql://tenant.example.turso.io', true],
+    ['turso', 'libsql://127.0.0.1:8080?tls=0', true],
+    ['turso', 'https://tenant.example.turso.io', true],
+    ['turso', 'file:/tmp/os-remote-posture.db', false],
+    ['turso', ':memory:', false],
+    ['sqlite', 'file:/tmp/os-remote-posture.db', false],
+    ['postgres', 'postgres://localhost/app', false],
+    ['mysql', 'mysql://localhost/app', false],
+  ] as const)('%s %s -> %s', async (driver, url, expected) => {
+    expect(await transportRefusesDeferredDdl({ driver, url })).toBe(expected);
+  });
+});
+
+/** A driver whose arm the remote face refuses, as `TursoDriver.setDeferredDdl` does there. */
+function refusingDriver(name: string) {
+  return {
+    name,
+    setDeferredDdl: vi.fn((deferred: boolean) => {
+      if (deferred) throw Object.assign(new Error('Deferred schema DDL is not supported by the Turso REMOTE transport'), { code: 'NOT_IMPLEMENTED', status: 501 });
+    }),
+    detectManagedDrift: vi.fn(async () => []),
+    applyMigrationEntries: vi.fn(async () => ({ applied: [], skipped: [] })),
+  };
+}
+/** A driver that defers. */
+function deferringDriver(name: string) {
+  return {
+    name,
+    setDeferredDdl: vi.fn(),
+    detectManagedDrift: vi.fn(async () => []),
+    applyMigrationEntries: vi.fn(async () => ({ applied: [], skipped: [] })),
+  };
+}
+
+/** A plugin ctx over `services`, with an engine whose default driver is `primary`. */
+function ctxWith(primary: unknown, others: Record<string, unknown>) {
+  const byName: Record<string, unknown> = { primary, ...others };
+  const engine = {
+    registerDriver: vi.fn(),
+    getDefaultDriverName: () => 'primary',
+    getDriverByName: (n: string) => byName[n],
+    getDriverForObject: () => primary,
+    registry: { getAllObjects: () => [{ name: 'sys_job' }] },
+  };
+  const services = new Map<string, unknown>([
+    ['objectql', engine],
+    ['driver.com.objectstack.driver.turso', primary],
+    ...Object.entries(others).map(([n, d]) => [`driver.${n}`, d] as [string, unknown]),
+  ]);
+  return {
+    engine,
+    ctx: {
+      getService: (name: string) => {
+        if (!services.has(name)) throw new Error(`no service ${name}`);
+        return services.get(name);
+      },
+      getServices: () => services,
+      logger: { debug: () => {} },
+    },
+  };
+}
+
+describe('DeferSchemaDdlPlugin — the primary exemption', () => {
+  it('exemptPrimary: the primary is left un-armed, every other driver is armed, at init and after', async () => {
+    const primary = refusingDriver('remote');
+    const other = deferringDriver('telemetry');
+    const later = deferringDriver('declared');
+    const { ctx, engine } = ctxWith(primary, { other });
+    const plugin = new DeferSchemaDdlPlugin({ exemptPrimary: true });
+
+    await plugin.init(ctx);
+
+    expect(primary.setDeferredDdl).not.toHaveBeenCalled();
+    expect(other.setDeferredDdl).toHaveBeenCalledWith(true);
+    expect(plugin.drivers).toEqual([other]);
+
+    // A driver handed to the engine afterwards is armed before the engine holds
+    // it; the primary handed again is still not.
+    (engine as unknown as { registerDriver: (d: unknown) => unknown }).registerDriver(later);
+    (engine as unknown as { registerDriver: (d: unknown) => unknown }).registerDriver(primary);
+    expect(later.setDeferredDdl).toHaveBeenCalledWith(true);
+    expect(primary.setDeferredDdl).not.toHaveBeenCalled();
+    expect(plugin.drivers).toEqual([other, later] as unknown as SqlDriverLike[]);
+    plugin.release();
+  });
+
+  it('the control: without the exemption, a primary that refuses the arm fails the boot', async () => {
+    const primary = refusingDriver('remote');
+    const { ctx } = ctxWith(primary, {});
+    const plugin = new DeferSchemaDdlPlugin();
+
+    await expect(plugin.init(ctx)).rejects.toThrow('Deferred schema DDL is not supported by the Turso REMOTE transport');
+    expect(primary.setDeferredDdl).toHaveBeenCalledWith(true);
+    plugin.release();
+  });
+
+  it('exemptPrimary exempts only the engine\'s default driver: another refusing driver still fails the boot', async () => {
+    const primary = deferringDriver('local');
+    const remoteSibling = refusingDriver('remote');
+    const { ctx } = ctxWith(primary, { remoteSibling });
+    const plugin = new DeferSchemaDdlPlugin({ exemptPrimary: true });
+
+    await expect(plugin.init(ctx)).rejects.toThrow('Deferred schema DDL is not supported by the Turso REMOTE transport');
+    expect(primary.setDeferredDdl).not.toHaveBeenCalled();
+    plugin.release();
+  });
+});

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

@@ -384,8 +384,11 @@ async function planPackageTable(
  * {@link drivers} keeps what was armed, so the stack can report every
  * datasource's held-back work and flush all of it on the operator's say-so.
  * No driver changes: each one keeps its own deferred set and its own flush.
+ *
+ * Exported for its unit pin (`schema-migrate.remote-posture.test.ts`, #23816),
+ * which holds the primary exemption without booting a kernel.
  */
-class DeferSchemaDdlPlugin {
+export class DeferSchemaDdlPlugin {
   name = 'com.objectstack.cli.defer-schema-ddl';
   version = '1.0.0';
   /** Ordering, not optionality: our init must follow the one that registers `driver.*`. */
@@ -530,8 +533,9 @@ function defaultDriverOf(ctx: { getService?: (name: string) => unknown }): unkno
  * Loaded lazily, as every driver is from this module (#5726). A package that
  * cannot be loaded answers `false`, and the boot then fails where it always
  * has, in `@objectstack/runtime`'s loader, naming the package to install.
+ * Exported for its unit pin (`schema-migrate.remote-posture.test.ts`).
  */
-async function transportRefusesDeferredDdl(resolved: { driver: string; url: string }): Promise<boolean> {
+export async function transportRefusesDeferredDdl(resolved: { driver: string; url: string }): Promise<boolean> {
   if (resolved.driver !== 'turso') return false;
   let detectMode: ((config: { url: string }) => string) | undefined;
   try {