snapshot of https://github.com/twentyhq/twenty.git (main, 2026-09-17; blobs > 131072B omitted)

packages/twenty-server/test/integration/upgrade/suites/sequence-runner/failing-sequence-runner.integration-spec.ts

@@ -0,0 +1,365 @@
+import {
+  type UpgradeStep,
+  type WorkspaceUpgradeStep,
+} from 'src/engine/core-modules/upgrade/services/upgrade-sequence-reader.service';
+import {
+  type IntegrationTestContext,
+  createUpgradeSequenceRunnerIntegrationTestModule,
+  DEFAULT_OPTIONS,
+  makeFastInstance,
+  makeSlowInstance,
+  makeStep,
+  makeWorkspace,
+  migrationRecordToKey,
+  resetSeedSequenceCounter,
+  restoreUpgradeMigrations,
+  seedInstanceMigration,
+  seedWorkspaceMigration,
+  setMockActiveWorkspaceIds,
+  snapshotUpgradeMigrations,
+  testGetExecutedMigrationsInOrder,
+  WS_1,
+  WS_2,
+} from 'test/integration/upgrade/utils/upgrade-sequence-runner-integration-test.util';
+
+const makeFailingFastInstance = (name: string, error: Error): UpgradeStep =>
+  ({
+    ...makeStep('fast-instance', name),
+    command: {
+      up: async () => {
+        throw error;
+      },
+      down: async () => {},
+    },
+  }) as unknown as UpgradeStep;
+
+const makeFailingWorkspace = (
+  name: string,
+  error: Error,
+): WorkspaceUpgradeStep =>
+  ({
+    ...makeStep('workspace', name),
+    command: {
+      runOnWorkspace: async () => {
+        throw error;
+      },
+    },
+  }) as unknown as WorkspaceUpgradeStep;
+
+const makeWorkspaceFailingForIds = (
+  name: string,
+  failingWorkspaceIds: Set<string>,
+  error: Error,
+): WorkspaceUpgradeStep =>
+  ({
+    ...makeStep('workspace', name),
+    command: {
+      runOnWorkspace: async ({ workspaceId }: { workspaceId: string }) => {
+        if (failingWorkspaceIds.has(workspaceId)) {
+          throw error;
+        }
+      },
+    },
+  }) as unknown as WorkspaceUpgradeStep;
+
+describe('UpgradeSequenceRunnerService — failing sequence (integration)', () => {
+  let context: IntegrationTestContext;
+  let savedUpgradeMigrations: Awaited<
+    ReturnType<typeof snapshotUpgradeMigrations>
+  >;
+
+  beforeAll(async () => {
+    context = await createUpgradeSequenceRunnerIntegrationTestModule();
+    savedUpgradeMigrations = await snapshotUpgradeMigrations(
+      context.dataSource,
+    );
+  }, 30000);
+
+  afterAll(async () => {
+    await restoreUpgradeMigrations(context.dataSource, savedUpgradeMigrations);
+    await context.module?.close();
+    await context.dataSource?.destroy();
+  }, 15000);
+
+  beforeEach(async () => {
+    await context.dataSource.query('DELETE FROM core."upgradeMigration"');
+    resetSeedSequenceCounter();
+    setMockActiveWorkspaceIds([]);
+    jest.restoreAllMocks();
+  });
+
+  it('should throw when no migration history exists', async () => {
+    const sequence = [makeFastInstance('Ic1')];
+
+    await expect(
+      context.runner.run({
+        sequence,
+        options: DEFAULT_OPTIONS,
+      }),
+    ).rejects.toThrow(
+      'No upgrade migration found — the database may not have been initialized',
+    );
+  });
+
+  it('should throw when cursor command is not found in the sequence', async () => {
+    const sequence = [makeFastInstance('Ic1'), makeFastInstance('Ic2')];
+
+    await seedInstanceMigration(context.dataSource, {
+      name: 'RemovedCommand',
+      status: 'completed',
+    });
+
+    await expect(
+      context.runner.run({
+        sequence,
+        options: DEFAULT_OPTIONS,
+      }),
+    ).rejects.toThrow(/Step "RemovedCommand" not found in upgrade sequence/);
+  });
+
+  it('should throw when workspace cursors are outside the current slice', async () => {
+    const sequence = [
+      makeWorkspace('Wc1'),
+      makeWorkspace('Wc2'),
+      makeFastInstance('Ic1'),
+      makeWorkspace('Wc3'),
+      makeWorkspace('Wc4'),
+    ];
+
+    setMockActiveWorkspaceIds([WS_1, WS_2]);
+
+    await seedWorkspaceMigration(context.dataSource, {
+      name: 'Wc1',
+      status: 'completed',
+      workspaceId: WS_1,
+    });
+    await seedWorkspaceMigration(context.dataSource, {
+      name: 'Wc2',
+      status: 'completed',
+      workspaceId: WS_1,
+    });
+    await seedWorkspaceMigration(context.dataSource, {
+      name: 'Wc1',
+      status: 'completed',
+      workspaceId: WS_2,
+    });
+    await seedInstanceMigration(context.dataSource, {
+      name: 'Ic1',
+      status: 'completed',
+      workspaceIds: [WS_1],
+    });
+    await seedWorkspaceMigration(context.dataSource, {
+      name: 'Wc3',
+      status: 'completed',
+      workspaceId: WS_1,
+    });
+    await seedWorkspaceMigration(context.dataSource, {
+      name: 'Wc4',
+      status: 'completed',
+      workspaceId: WS_1,
+    });
+
+    await expect(
+      context.runner.run({
+        sequence,
+        options: DEFAULT_OPTIONS,
+      }),
+    ).rejects.toThrow(
+      'workspace(s) have invalid cursors for workspace segment',
+    );
+  });
+
+  it('should throw when an active workspace has no migration history', async () => {
+    const sequence = [makeFastInstance('Ic1'), makeWorkspace('Wc1')];
+
+    setMockActiveWorkspaceIds([WS_1, WS_2]);
+
+    await seedWorkspaceMigration(context.dataSource, {
+      name: 'Wc1',
+      status: 'completed',
+      workspaceId: WS_1,
+    });
+
+    await expect(
+      context.runner.run({
+        sequence,
+        options: DEFAULT_OPTIONS,
+      }),
+    ).rejects.toThrow('No upgrade migration found for workspace(s)');
+  });
+
+  it('should record failure in DB when a fast instance command fails', async () => {
+    const error = new Error('fast command exploded');
+    const sequence = [
+      makeFastInstance('Ic1'),
+      makeFailingFastInstance('Ic2', error),
+    ];
+
+    await seedInstanceMigration(context.dataSource, {
+      name: 'Ic1',
+      status: 'completed',
+    });
+
+    await expect(
+      context.runner.run({
+        sequence,
+        options: DEFAULT_OPTIONS,
+      }),
+    ).rejects.toThrow('fast command exploded');
+
+    const executed = await testGetExecutedMigrationsInOrder(context.dataSource);
+
+    expect(executed.map(migrationRecordToKey)).toStrictEqual([
+      'Ic1:instance:completed:1',
+
+      // Ic2 attempted and failed
+      'Ic2:instance:failed:1',
+    ]);
+  });
+
+  it('should record failure in DB when a slow instance command fails', async () => {
+    const error = new Error('slow data migration exploded');
+    const sequence = [
+      makeFastInstance('Ic1'),
+      {
+        ...makeSlowInstance('Ic2'),
+        command: {
+          up: async () => {},
+          down: async () => {},
+          runDataMigration: async () => {
+            throw error;
+          },
+        },
+      } as unknown as UpgradeStep,
+    ];
+
+    setMockActiveWorkspaceIds([WS_1]);
+
+    await seedInstanceMigration(context.dataSource, {
+      name: 'Ic1',
+      status: 'completed',
+      workspaceIds: [WS_1],
+    });
+
+    await expect(
+      context.runner.run({
+        sequence,
+        options: DEFAULT_OPTIONS,
+      }),
+    ).rejects.toThrow('slow data migration exploded');
+
+    const executed = await testGetExecutedMigrationsInOrder(context.dataSource);
+
+    expect(executed.map(migrationRecordToKey)).toStrictEqual([
+      'Ic1:instance:completed:1',
+      `Ic1:${WS_1}:completed:1`,
+
+      // Ic2 attempted and failed
+      'Ic2:instance:failed:1',
+      `Ic2:${WS_1}:failed:1`,
+    ]);
+  });
+
+  it('should abort and report failures when workspace commands fail, without running subsequent instance steps', async () => {
+    const error = new Error('workspace command exploded');
+    const sequence = [
+      makeFailingWorkspace('Wc1', error),
+      makeFastInstance('Ic1'),
+    ];
+
+    setMockActiveWorkspaceIds([WS_1]);
+
+    await seedWorkspaceMigration(context.dataSource, {
+      name: 'Wc1',
+      status: 'failed',
+      workspaceId: WS_1,
+    });
+
+    const report = await context.runner.run({
+      sequence,
+      options: DEFAULT_OPTIONS,
+    });
+
+    expect(report.totalFailures).toBe(1);
+    expect(report.totalSuccesses).toBe(0);
+
+    const executed = await testGetExecutedMigrationsInOrder(context.dataSource);
+
+    expect(executed.map(migrationRecordToKey)).toStrictEqual([
+      `Wc1:${WS_1}:failed:1`,
+
+      // Runner retries Wc1, still fails — Ic1 never reached
+      `Wc1:${WS_1}:failed:2`,
+    ]);
+  });
+
+  it('should abort at workspace failure in a multi-segment sequence with two workspaces starting aligned', async () => {
+    const error = new Error('Wc2 exploded for WS_2');
+
+    const sequence = [
+      makeWorkspace('Wc0'),
+      makeFastInstance('Ic1'),
+      makeWorkspace('Wc1'),
+      makeWorkspaceFailingForIds('Wc2', new Set([WS_2]), error),
+      makeFastInstance('Ic2'),
+      makeWorkspace('Wc3'),
+    ];
+
+    setMockActiveWorkspaceIds([WS_1, WS_2]);
+
+    await seedWorkspaceMigration(context.dataSource, {
+      name: 'Wc0',
+      status: 'completed',
+      workspaceId: WS_1,
+    });
+    await seedWorkspaceMigration(context.dataSource, {
+      name: 'Wc0',
+      status: 'completed',
+      workspaceId: WS_2,
+    });
+    await seedInstanceMigration(context.dataSource, {
+      name: 'Ic1',
+      status: 'completed',
+      workspaceIds: [WS_1, WS_2],
+    });
+    await seedWorkspaceMigration(context.dataSource, {
+      name: 'Wc1',
+      status: 'completed',
+      workspaceId: WS_1,
+    });
+    await seedWorkspaceMigration(context.dataSource, {
+      name: 'Wc1',
+      status: 'completed',
+      workspaceId: WS_2,
+    });
+
+    const report = await context.runner.run({
+      sequence,
+      options: {
+        ...DEFAULT_OPTIONS,
+        workspaceIds: [WS_1, WS_2],
+      },
+    });
+
+    expect(report.totalSuccesses).toBe(1);
+    expect(report.totalFailures).toBe(1);
+
+    const executed = await testGetExecutedMigrationsInOrder(context.dataSource);
+
+    expect(executed.map(migrationRecordToKey)).toStrictEqual([
+      `Wc0:${WS_1}:completed:1`,
+      `Wc0:${WS_2}:completed:1`,
+      'Ic1:instance:completed:1',
+      `Ic1:${WS_1}:completed:1`,
+      `Ic1:${WS_2}:completed:1`,
+      `Wc1:${WS_1}:completed:1`,
+      `Wc1:${WS_2}:completed:1`,
+
+      // WS_1 succeeds Wc2, WS_2 fails Wc2
+      `Wc2:${WS_1}:completed:1`,
+      `Wc2:${WS_2}:failed:1`,
+
+      // Ic2 and Wc3 never reached — runner aborted at workspace failure
+    ]);
+  });
+});

packages/twenty-server/test/integration/upgrade/suites/sequence-runner/instance-completed-version.integration-spec.ts

@@ -0,0 +1,187 @@
+import { TWENTY_CROSS_UPGRADE_SUPPORTED_VERSIONS } from 'src/engine/core-modules/upgrade/constants/twenty-cross-upgrade-supported-version.constant';
+import { type UpgradeStep } from 'src/engine/core-modules/upgrade/services/upgrade-sequence-reader.service';
+
+import {
+  type IntegrationTestContext,
+  createUpgradeSequenceRunnerIntegrationTestModule,
+  DEFAULT_OPTIONS,
+  makeVersionedStep,
+  resetSeedSequenceCounter,
+  restoreUpgradeMigrations,
+  seedInstanceMigration,
+  setMockActiveWorkspaceIds,
+  snapshotUpgradeMigrations,
+  WS_1,
+} from 'test/integration/upgrade/utils/upgrade-sequence-runner-integration-test.util';
+
+// The sequence only ever covers supported versions, and the skip rule walks
+// that same list, so the fixture has to be built from real ones.
+const [OLDEST_VERSION, MIDDLE_VERSION, NEWEST_VERSION] =
+  TWENTY_CROSS_UPGRADE_SUPPORTED_VERSIONS.slice(-3);
+
+const OLDEST_INSTANCE_COMMAND = makeVersionedStep('fast-instance', {
+  version: OLDEST_VERSION,
+  label: 'OldestInstanceCommand',
+});
+const OLDEST_SLOW_INSTANCE_COMMAND = makeVersionedStep('slow-instance', {
+  version: OLDEST_VERSION,
+  label: 'OldestSlowInstanceCommand',
+});
+const MIDDLE_INSTANCE_COMMAND = makeVersionedStep('fast-instance', {
+  version: MIDDLE_VERSION,
+  label: 'MiddleInstanceCommand',
+});
+const NEWEST_INSTANCE_COMMAND = makeVersionedStep('fast-instance', {
+  version: NEWEST_VERSION,
+  label: 'NewestInstanceCommand',
+});
+const NEWEST_WORKSPACE_COMMAND = makeVersionedStep('workspace', {
+  version: NEWEST_VERSION,
+  label: 'NewestWorkspaceCommand',
+});
+
+describe('UpgradeStatusService — instance completed version (integration)', () => {
+  let context: IntegrationTestContext;
+  let savedUpgradeMigrations: Awaited<
+    ReturnType<typeof snapshotUpgradeMigrations>
+  >;
+
+  const mockSequence = (sequence: UpgradeStep[]) => {
+    jest
+      .spyOn(context.upgradeSequenceReaderService, 'getUpgradeSequence')
+      .mockReturnValue(sequence);
+  };
+
+  beforeAll(async () => {
+    context = await createUpgradeSequenceRunnerIntegrationTestModule();
+    savedUpgradeMigrations = await snapshotUpgradeMigrations(
+      context.dataSource,
+    );
+  }, 30000);
+
+  afterAll(async () => {
+    await restoreUpgradeMigrations(context.dataSource, savedUpgradeMigrations);
+    await context.module?.close();
+    await context.dataSource?.destroy();
+  }, 15000);
+
+  beforeEach(async () => {
+    await context.dataSource.query('DELETE FROM core."upgradeMigration"');
+    resetSeedSequenceCounter();
+    setMockActiveWorkspaceIds([]);
+    jest.restoreAllMocks();
+  });
+
+  it('should return null when no instance command has ever run', async () => {
+    mockSequence([OLDEST_INSTANCE_COMMAND, MIDDLE_INSTANCE_COMMAND]);
+
+    await expect(
+      context.upgradeStatusService.getInstanceCompletedVersion(),
+    ).resolves.toBeNull();
+  });
+
+  it('should reach a trailing version that ships no instance command', async () => {
+    mockSequence([MIDDLE_INSTANCE_COMMAND, NEWEST_WORKSPACE_COMMAND]);
+
+    await seedInstanceMigration(context.dataSource, {
+      name: MIDDLE_INSTANCE_COMMAND.name,
+      status: 'completed',
+    });
+
+    await expect(
+      context.upgradeStatusService.getInstanceCompletedVersion(),
+    ).resolves.toBe(NEWEST_VERSION);
+  });
+
+  it('should hold at the previous version while the trailing instance command has not run', async () => {
+    mockSequence([MIDDLE_INSTANCE_COMMAND, NEWEST_INSTANCE_COMMAND]);
+
+    await seedInstanceMigration(context.dataSource, {
+      name: MIDDLE_INSTANCE_COMMAND.name,
+      status: 'completed',
+    });
+
+    await expect(
+      context.upgradeStatusService.getInstanceCompletedVersion(),
+    ).resolves.toBe(MIDDLE_VERSION);
+  });
+
+  it('should not credit a version whose last instance command failed', async () => {
+    mockSequence([MIDDLE_INSTANCE_COMMAND, NEWEST_INSTANCE_COMMAND]);
+
+    await seedInstanceMigration(context.dataSource, {
+      name: MIDDLE_INSTANCE_COMMAND.name,
+      status: 'completed',
+    });
+    await seedInstanceMigration(context.dataSource, {
+      name: NEWEST_INSTANCE_COMMAND.name,
+      status: 'failed',
+    });
+
+    await expect(
+      context.upgradeStatusService.getInstanceCompletedVersion(),
+    ).resolves.toBe(MIDDLE_VERSION);
+  });
+
+  it('should credit a version once its failed command is retried successfully', async () => {
+    mockSequence([MIDDLE_INSTANCE_COMMAND, NEWEST_INSTANCE_COMMAND]);
+
+    await seedInstanceMigration(context.dataSource, {
+      name: MIDDLE_INSTANCE_COMMAND.name,
+      status: 'completed',
+    });
+    await seedInstanceMigration(context.dataSource, {
+      name: NEWEST_INSTANCE_COMMAND.name,
+      status: 'failed',
+    });
+    await seedInstanceMigration(context.dataSource, {
+      name: NEWEST_INSTANCE_COMMAND.name,
+      status: 'completed',
+      attempt: 2,
+    });
+
+    await expect(
+      context.upgradeStatusService.getInstanceCompletedVersion(),
+    ).resolves.toBe(NEWEST_VERSION);
+  });
+
+  it('should not credit a version while earlier instance commands of that version remain', async () => {
+    mockSequence([OLDEST_INSTANCE_COMMAND, OLDEST_SLOW_INSTANCE_COMMAND]);
+
+    await seedInstanceMigration(context.dataSource, {
+      name: OLDEST_INSTANCE_COMMAND.name,
+      status: 'completed',
+    });
+
+    await expect(
+      context.upgradeStatusService.getInstanceCompletedVersion(),
+    ).resolves.toBeNull();
+  });
+
+  it('should report the version reached after the runner executes the whole sequence', async () => {
+    const sequence = [
+      OLDEST_INSTANCE_COMMAND,
+      MIDDLE_INSTANCE_COMMAND,
+      NEWEST_WORKSPACE_COMMAND,
+    ];
+
+    mockSequence(sequence);
+    setMockActiveWorkspaceIds([WS_1]);
+
+    // The runner resumes from a cursor, so the sequence needs a starting point.
+    await seedInstanceMigration(context.dataSource, {
+      name: OLDEST_INSTANCE_COMMAND.name,
+      status: 'completed',
+      workspaceIds: [WS_1],
+    });
+
+    await context.runner.run({
+      sequence,
+      options: DEFAULT_OPTIONS,
+    });
+
+    await expect(
+      context.upgradeStatusService.getInstanceCompletedVersion(),
+    ).resolves.toBe(NEWEST_VERSION);
+  });
+});

packages/twenty-server/test/integration/upgrade/suites/sequence-runner/start-from-workspace-id.integration-spec.ts

@@ -0,0 +1,196 @@
+import {
+  type IntegrationTestContext,
+  createUpgradeSequenceRunnerIntegrationTestModule,
+  DEFAULT_OPTIONS,
+  makeFastInstance,
+  makeWorkspace,
+  migrationRecordToKey,
+  resetSeedSequenceCounter,
+  restoreUpgradeMigrations,
+  seedInstanceMigration,
+  setMockActiveWorkspaceIds,
+  snapshotUpgradeMigrations,
+  testGetExecutedMigrationsInOrder,
+  WS_1,
+  WS_2,
+  WS_3,
+  WS_4,
+} from 'test/integration/upgrade/utils/upgrade-sequence-runner-integration-test.util';
+
+// Sorted ASC: WS_1 < WS_2 < WS_3 < WS_4
+
+describe('UpgradeSequenceRunnerService — startFromWorkspaceId (integration)', () => {
+  let context: IntegrationTestContext;
+  let savedUpgradeMigrations: Awaited<
+    ReturnType<typeof snapshotUpgradeMigrations>
+  >;
+
+  beforeAll(async () => {
+    context = await createUpgradeSequenceRunnerIntegrationTestModule();
+    savedUpgradeMigrations = await snapshotUpgradeMigrations(
+      context.dataSource,
+    );
+  }, 30000);
+
+  afterAll(async () => {
+    await restoreUpgradeMigrations(context.dataSource, savedUpgradeMigrations);
+    await context.module?.close();
+    await context.dataSource?.destroy();
+  }, 15000);
+
+  beforeEach(async () => {
+    await context.dataSource.query('DELETE FROM core."upgradeMigration"');
+    resetSeedSequenceCounter();
+    setMockActiveWorkspaceIds([]);
+    jest.restoreAllMocks();
+  });
+
+  it('should only process workspaces whose id >= startFromWorkspaceId', async () => {
+    const sequence = [
+      makeFastInstance('Ic1'),
+      makeWorkspace('Wc1'),
+      makeWorkspace('Wc2'),
+      makeFastInstance('Ic2'),
+    ];
+
+    setMockActiveWorkspaceIds([WS_1, WS_2, WS_3]);
+
+    await seedInstanceMigration(context.dataSource, {
+      name: 'Ic1',
+      status: 'completed',
+      workspaceIds: [WS_1, WS_2, WS_3],
+    });
+
+    const report = await context.runner.run({
+      sequence,
+      options: {
+        ...DEFAULT_OPTIONS,
+        startFromWorkspaceId: WS_2,
+      },
+    });
+
+    expect(report.totalFailures).toBe(0);
+    expect(report.totalSuccesses).toBe(2);
+
+    const executed = await testGetExecutedMigrationsInOrder(context.dataSource);
+
+    expect(executed.map(migrationRecordToKey)).toStrictEqual([
+      'Ic1:instance:completed:1',
+      `Ic1:${WS_1}:completed:1`,
+      `Ic1:${WS_2}:completed:1`,
+      `Ic1:${WS_3}:completed:1`,
+
+      // Only WS_2 and WS_3 are processed (WS_1 skipped)
+      `Wc1:${WS_2}:completed:1`,
+      `Wc2:${WS_2}:completed:1`,
+      `Wc1:${WS_3}:completed:1`,
+      `Wc2:${WS_3}:completed:1`,
+    ]);
+  });
+
+  it('should respect workspaceCountLimit together with startFromWorkspaceId', async () => {
+    const sequence = [makeFastInstance('Ic1'), makeWorkspace('Wc1')];
+
+    setMockActiveWorkspaceIds([WS_1, WS_2, WS_3, WS_4]);
+
+    await seedInstanceMigration(context.dataSource, {
+      name: 'Ic1',
+      status: 'completed',
+      workspaceIds: [WS_1, WS_2, WS_3, WS_4],
+    });
+
+    const report = await context.runner.run({
+      sequence,
+      options: {
+        ...DEFAULT_OPTIONS,
+        startFromWorkspaceId: WS_2,
+        workspaceCountLimit: 1,
+      },
+    });
+
+    expect(report.totalFailures).toBe(0);
+    expect(report.totalSuccesses).toBe(1);
+
+    const executed = await testGetExecutedMigrationsInOrder(context.dataSource);
+
+    expect(executed.map(migrationRecordToKey)).toStrictEqual([
+      'Ic1:instance:completed:1',
+      `Ic1:${WS_1}:completed:1`,
+      `Ic1:${WS_2}:completed:1`,
+      `Ic1:${WS_3}:completed:1`,
+      `Ic1:${WS_4}:completed:1`,
+
+      // Only WS_2 processed (first after startFrom, limited to 1)
+      `Wc1:${WS_2}:completed:1`,
+    ]);
+  });
+
+  it('should stop before instance step when startFromWorkspaceId is set', async () => {
+    const sequence = [
+      makeFastInstance('Ic1'),
+      makeWorkspace('Wc1'),
+      makeWorkspace('Wc2'),
+      makeFastInstance('Ic2'),
+      makeWorkspace('Wc3'),
+    ];
+
+    setMockActiveWorkspaceIds([WS_1, WS_2, WS_3]);
+
+    await seedInstanceMigration(context.dataSource, {
+      name: 'Ic1',
+      status: 'completed',
+      workspaceIds: [WS_1, WS_2, WS_3],
+    });
+
+    const report = await context.runner.run({
+      sequence,
+      options: {
+        ...DEFAULT_OPTIONS,
+        startFromWorkspaceId: WS_2,
+      },
+    });
+
+    expect(report.totalFailures).toBe(0);
+    expect(report.totalSuccesses).toBe(2);
+
+    const executed = await testGetExecutedMigrationsInOrder(context.dataSource);
+
+    expect(executed.map(migrationRecordToKey)).toStrictEqual([
+      'Ic1:instance:completed:1',
+      `Ic1:${WS_1}:completed:1`,
+      `Ic1:${WS_2}:completed:1`,
+      `Ic1:${WS_3}:completed:1`,
+
+      // Workspace segment: only WS_2 and WS_3 run
+      `Wc1:${WS_2}:completed:1`,
+      `Wc2:${WS_2}:completed:1`,
+      `Wc1:${WS_3}:completed:1`,
+      `Wc2:${WS_3}:completed:1`,
+
+      // Ic2 and Wc3 never reached — runner stopped at instance step boundary
+    ]);
+  });
+
+  it('should process no workspaces when startFromWorkspaceId is greater than all ids', async () => {
+    const sequence = [makeFastInstance('Ic1'), makeWorkspace('Wc1')];
+
+    setMockActiveWorkspaceIds([WS_1, WS_2]);
+
+    await seedInstanceMigration(context.dataSource, {
+      name: 'Ic1',
+      status: 'completed',
+      workspaceIds: [WS_1, WS_2],
+    });
+
+    const report = await context.runner.run({
+      sequence,
+      options: {
+        ...DEFAULT_OPTIONS,
+        startFromWorkspaceId: 'ffffffff-ffff-ffff-ffff-ffffffffffff',
+      },
+    });
+
+    expect(report.totalFailures).toBe(0);
+    expect(report.totalSuccesses).toBe(0);
+  });
+});

packages/twenty-server/test/integration/upgrade/suites/sequence-runner/successful-sequence-runner.integration-spec.ts

@@ -0,0 +1,517 @@
+import { InstanceCommandRunnerService } from 'src/engine/core-modules/upgrade/services/instance-command-runner.service';
+
+import {
+  type IntegrationTestContext,
+  createUpgradeSequenceRunnerIntegrationTestModule,
+  DEFAULT_OPTIONS,
+  makeFastInstance,
+  makeSlowInstance,
+  makeWorkspace,
+  migrationRecordToKey,
+  resetSeedSequenceCounter,
+  restoreUpgradeMigrations,
+  seedInstanceMigration,
+  seedWorkspaceMigration,
+  setMockActiveWorkspaceIds,
+  snapshotUpgradeMigrations,
+  testGetExecutedMigrationsInOrder,
+  WS_1,
+  WS_2,
+} from 'test/integration/upgrade/utils/upgrade-sequence-runner-integration-test.util';
+
+describe('UpgradeSequenceRunnerService — execution (integration)', () => {
+  let context: IntegrationTestContext;
+  let savedUpgradeMigrations: Awaited<
+    ReturnType<typeof snapshotUpgradeMigrations>
+  >;
+
+  beforeAll(async () => {
+    context = await createUpgradeSequenceRunnerIntegrationTestModule();
+    savedUpgradeMigrations = await snapshotUpgradeMigrations(
+      context.dataSource,
+    );
+  }, 30000);
+
+  afterAll(async () => {
+    await restoreUpgradeMigrations(context.dataSource, savedUpgradeMigrations);
+    await context.module?.close();
+    await context.dataSource?.destroy();
+  }, 15000);
+
+  beforeEach(async () => {
+    await context.dataSource.query('DELETE FROM core."upgradeMigration"');
+    resetSeedSequenceCounter();
+    setMockActiveWorkspaceIds([]);
+    jest.restoreAllMocks();
+  });
+
+  it('should return zero counts for an empty sequence', async () => {
+    const report = await context.runner.run({
+      sequence: [],
+      options: DEFAULT_OPTIONS,
+    });
+
+    expect(report).toEqual({ totalSuccesses: 0, totalFailures: 0 });
+  });
+
+  it('should resume from a completed instance command and run remaining steps', async () => {
+    const sequence = [
+      makeFastInstance('Ic1'),
+      makeFastInstance('Ic2'),
+      makeSlowInstance('Ic3'),
+    ];
+
+    await seedInstanceMigration(context.dataSource, {
+      name: 'Ic1',
+      status: 'completed',
+    });
+    await seedInstanceMigration(context.dataSource, {
+      name: 'Ic2',
+      status: 'completed',
+    });
+
+    await context.runner.run({
+      sequence,
+      options: DEFAULT_OPTIONS,
+    });
+
+    const executed = await testGetExecutedMigrationsInOrder(context.dataSource);
+
+    expect(executed.map(migrationRecordToKey)).toStrictEqual([
+      'Ic1:instance:completed:1',
+      'Ic2:instance:completed:1',
+
+      // Runner resumes after Ic2, runs Ic3
+      'Ic3:instance:completed:1',
+    ]);
+  });
+
+  it('should retry a failed instance command', async () => {
+    const sequence = [makeFastInstance('Ic1'), makeFastInstance('Ic2')];
+
+    await seedInstanceMigration(context.dataSource, {
+      name: 'Ic1',
+      status: 'completed',
+    });
+    await seedInstanceMigration(context.dataSource, {
+      name: 'Ic2',
+      status: 'failed',
+    });
+
+    await context.runner.run({
+      sequence,
+      options: DEFAULT_OPTIONS,
+    });
+
+    const executed = await testGetExecutedMigrationsInOrder(context.dataSource);
+
+    expect(executed.map(migrationRecordToKey)).toStrictEqual([
+      'Ic1:instance:completed:1',
+      'Ic2:instance:failed:1',
+
+      // Runner retries Ic2
+      'Ic2:instance:completed:2',
+    ]);
+  });
+
+  it('should resume workspace commands from per-workspace cursors', async () => {
+    const sequence = [
+      makeFastInstance('Ic1'),
+      makeWorkspace('Wc1'),
+      makeWorkspace('Wc2'),
+    ];
+
+    setMockActiveWorkspaceIds([WS_1]);
+
+    await seedInstanceMigration(context.dataSource, {
+      name: 'Ic1',
+      status: 'completed',
+      workspaceIds: [WS_1],
+    });
+    await seedWorkspaceMigration(context.dataSource, {
+      name: 'Wc1',
+      status: 'completed',
+      workspaceId: WS_1,
+    });
+
+    await context.runner.run({
+      sequence,
+      options: DEFAULT_OPTIONS,
+    });
+
+    const executed = await testGetExecutedMigrationsInOrder(context.dataSource);
+
+    expect(executed.map(migrationRecordToKey)).toStrictEqual([
+      'Ic1:instance:completed:1',
+      `Ic1:${WS_1}:completed:1`,
+      `Wc1:${WS_1}:completed:1`,
+
+      // Runner resumes after Wc1, runs Wc2
+      `Wc2:${WS_1}:completed:1`,
+    ]);
+  });
+
+  it('should enforce workspace sync barrier before instance step', async () => {
+    const sequence = [makeWorkspace('Wc1'), makeFastInstance('Ic1')];
+
+    setMockActiveWorkspaceIds([WS_1]);
+
+    await seedWorkspaceMigration(context.dataSource, {
+      name: 'Wc1',
+      status: 'completed',
+      workspaceId: WS_1,
+    });
+
+    await context.runner.run({
+      sequence,
+      options: DEFAULT_OPTIONS,
+    });
+
+    const executed = await testGetExecutedMigrationsInOrder(context.dataSource);
+
+    expect(executed.map(migrationRecordToKey)).toStrictEqual([
+      `Wc1:${WS_1}:completed:1`,
+
+      // Barrier passes, runner executes Ic1
+      'Ic1:instance:completed:1',
+      `Ic1:${WS_1}:completed:1`,
+    ]);
+  });
+
+  it('should skip data migration for slow instance commands when no workspaces exist', async () => {
+    const sequence = [makeFastInstance('Ic1'), makeSlowInstance('Ic2')];
+
+    await seedInstanceMigration(context.dataSource, {
+      name: 'Ic1',
+      status: 'completed',
+    });
+
+    const instanceCommandRunnerService = context.module.get(
+      InstanceCommandRunnerService,
+    );
+    const spy = jest.spyOn(
+      instanceCommandRunnerService,
+      'runSlowInstanceCommand',
+    );
+
+    await context.runner.run({
+      sequence,
+      options: DEFAULT_OPTIONS,
+    });
+
+    expect(spy).toHaveBeenCalledWith(
+      expect.objectContaining({ skipDataMigration: true }),
+    );
+
+    const executed = await testGetExecutedMigrationsInOrder(context.dataSource);
+
+    expect(executed.map(migrationRecordToKey)).toStrictEqual([
+      'Ic1:instance:completed:1',
+
+      // Runner runs Ic2 (slow, no workspaces → skip data migration)
+      'Ic2:instance:completed:1',
+    ]);
+  });
+
+  it('should run data migration for slow instance commands when workspaces exist', async () => {
+    const sequence = [makeFastInstance('Ic0'), makeSlowInstance('Ic1')];
+
+    setMockActiveWorkspaceIds([WS_1]);
+
+    await seedInstanceMigration(context.dataSource, {
+      name: 'Ic0',
+      status: 'completed',
+      workspaceIds: [WS_1],
+    });
+
+    const instanceCommandRunnerService = context.module.get(
+      InstanceCommandRunnerService,
+    );
+    const spy = jest.spyOn(
+      instanceCommandRunnerService,
+      'runSlowInstanceCommand',
+    );
+
+    await context.runner.run({
+      sequence,
+      options: DEFAULT_OPTIONS,
+    });
+
+    expect(spy).toHaveBeenCalledWith(
+      expect.objectContaining({ skipDataMigration: false }),
+    );
+
+    const executed = await testGetExecutedMigrationsInOrder(context.dataSource);
+
+    expect(executed.map(migrationRecordToKey)).toStrictEqual([
+      'Ic0:instance:completed:1',
+      `Ic0:${WS_1}:completed:1`,
+
+      // Runner runs Ic1 (slow, workspaces exist → run data migration)
+      'Ic1:instance:completed:1',
+      `Ic1:${WS_1}:completed:1`,
+    ]);
+  });
+
+  it('should run workspace commands for multiple workspaces successfully', async () => {
+    const sequence = [
+      makeFastInstance('Ic1'),
+      makeWorkspace('Wc1'),
+      makeWorkspace('Wc2'),
+    ];
+
+    setMockActiveWorkspaceIds([WS_1, WS_2]);
+
+    await seedInstanceMigration(context.dataSource, {
+      name: 'Ic1',
+      status: 'completed',
+      workspaceIds: [WS_1, WS_2],
+    });
+    await seedWorkspaceMigration(context.dataSource, {
+      name: 'Wc1',
+      status: 'completed',
+      workspaceId: WS_1,
+    });
+    await seedWorkspaceMigration(context.dataSource, {
+      name: 'Wc1',
+      status: 'completed',
+      workspaceId: WS_2,
+    });
+
+    const report = await context.runner.run({
+      sequence,
+      options: {
+        ...DEFAULT_OPTIONS,
+        workspaceIds: [WS_1, WS_2],
+      },
+    });
+
+    expect(report).toEqual({ totalSuccesses: 2, totalFailures: 0 });
+
+    const executed = await testGetExecutedMigrationsInOrder(context.dataSource);
+
+    expect(executed.map(migrationRecordToKey)).toStrictEqual([
+      'Ic1:instance:completed:1',
+      `Ic1:${WS_1}:completed:1`,
+      `Ic1:${WS_2}:completed:1`,
+      `Wc1:${WS_1}:completed:1`,
+      `Wc1:${WS_2}:completed:1`,
+
+      // Both workspaces run Wc2
+      `Wc2:${WS_1}:completed:1`,
+      `Wc2:${WS_2}:completed:1`,
+    ]);
+  });
+
+  it('should execute the full sequence from the initial cursor on a fresh run', async () => {
+    const sequence = [
+      makeWorkspace('Wc0'),
+      makeFastInstance('Ic1'),
+      makeFastInstance('Ic2'),
+      makeWorkspace('Wc1'),
+    ];
+
+    setMockActiveWorkspaceIds([WS_1]);
+
+    await seedWorkspaceMigration(context.dataSource, {
+      name: 'Wc0',
+      status: 'completed',
+      workspaceId: WS_1,
+    });
+    await seedInstanceMigration(context.dataSource, {
+      name: 'Ic1',
+      status: 'completed',
+      workspaceIds: [WS_1],
+    });
+
+    await context.runner.run({
+      sequence,
+      options: DEFAULT_OPTIONS,
+    });
+
+    const executed = await testGetExecutedMigrationsInOrder(context.dataSource);
+
+    expect(executed.map(migrationRecordToKey)).toStrictEqual([
+      `Wc0:${WS_1}:completed:1`,
+      'Ic1:instance:completed:1',
+      `Ic1:${WS_1}:completed:1`,
+
+      // Runner resumes after Ic1, runs Ic2 then Wc1
+      'Ic2:instance:completed:1',
+      `Ic2:${WS_1}:completed:1`,
+      `Wc1:${WS_1}:completed:1`,
+    ]);
+  });
+
+  it('should retry a failed workspace command', async () => {
+    const sequence = [
+      makeFastInstance('Ic1'),
+      makeWorkspace('Wc1'),
+      makeWorkspace('Wc2'),
+    ];
+
+    setMockActiveWorkspaceIds([WS_1]);
+
+    await seedInstanceMigration(context.dataSource, {
+      name: 'Ic1',
+      status: 'completed',
+      workspaceIds: [WS_1],
+    });
+    await seedWorkspaceMigration(context.dataSource, {
+      name: 'Wc1',
+      status: 'failed',
+      workspaceId: WS_1,
+    });
+
+    const report = await context.runner.run({
+      sequence,
+      options: DEFAULT_OPTIONS,
+    });
+
+    expect(report.totalFailures).toBe(0);
+
+    const executed = await testGetExecutedMigrationsInOrder(context.dataSource);
+
+    expect(executed.map(migrationRecordToKey)).toStrictEqual([
+      'Ic1:instance:completed:1',
+      `Ic1:${WS_1}:completed:1`,
+      `Wc1:${WS_1}:failed:1`,
+
+      // Runner retries Wc1, then runs Wc2
+      `Wc1:${WS_1}:completed:2`,
+      `Wc2:${WS_1}:completed:1`,
+    ]);
+  });
+
+  it('should traverse a multi-segment sequence with sync barriers', async () => {
+    const sequence = [
+      makeFastInstance('Ic1'),
+      makeWorkspace('Wc1'),
+      makeFastInstance('Ic2'),
+      makeWorkspace('Wc2'),
+    ];
+
+    setMockActiveWorkspaceIds([WS_1]);
+
+    await seedInstanceMigration(context.dataSource, {
+      name: 'Ic1',
+      status: 'completed',
+      workspaceIds: [WS_1],
+    });
+    await seedWorkspaceMigration(context.dataSource, {
+      name: 'Wc1',
+      status: 'completed',
+      workspaceId: WS_1,
+    });
+
+    const report = await context.runner.run({
+      sequence,
+      options: DEFAULT_OPTIONS,
+    });
+
+    expect(report.totalFailures).toBe(0);
+
+    const executed = await testGetExecutedMigrationsInOrder(context.dataSource);
+
+    expect(executed.map(migrationRecordToKey)).toStrictEqual([
+      'Ic1:instance:completed:1',
+      `Ic1:${WS_1}:completed:1`,
+      `Wc1:${WS_1}:completed:1`,
+
+      // Sync barrier → Ic2, then Wc2
+      'Ic2:instance:completed:1',
+      `Ic2:${WS_1}:completed:1`,
+      `Wc2:${WS_1}:completed:1`,
+    ]);
+  });
+
+  it('should stop before the next instance step when running with workspace filter (-w)', async () => {
+    const sequence = [
+      makeFastInstance('Ic1'),
+      makeWorkspace('Wc1'),
+      makeWorkspace('Wc2'),
+      makeFastInstance('Ic2'),
+      makeWorkspace('Wc3'),
+    ];
+
+    setMockActiveWorkspaceIds([WS_1, WS_2]);
+
+    await seedInstanceMigration(context.dataSource, {
+      name: 'Ic1',
+      status: 'completed',
+      workspaceIds: [WS_1, WS_2],
+    });
+
+    const report = await context.runner.run({
+      sequence,
+      options: {
+        ...DEFAULT_OPTIONS,
+        workspaceIds: [WS_1],
+      },
+    });
+
+    expect(report.totalFailures).toBe(0);
+    expect(report.totalSuccesses).toBe(1);
+
+    const executed = await testGetExecutedMigrationsInOrder(context.dataSource);
+
+    expect(executed.map(migrationRecordToKey)).toStrictEqual([
+      'Ic1:instance:completed:1',
+      `Ic1:${WS_1}:completed:1`,
+      `Ic1:${WS_2}:completed:1`,
+
+      // Workspace segment: only WS_1 runs (filtered with -w)
+      `Wc1:${WS_1}:completed:1`,
+      `Wc2:${WS_1}:completed:1`,
+
+      // Ic2 and Wc3 never reached — runner stopped at instance step boundary
+    ]);
+  });
+
+  it('should ignore migration records from inactive workspaces when resolving the global cursor', async () => {
+    const sequence = [
+      makeFastInstance('Ic1'),
+      makeWorkspace('Wc1'),
+      makeWorkspace('Wc2'),
+    ];
+
+    setMockActiveWorkspaceIds([WS_1]);
+
+    await seedInstanceMigration(context.dataSource, {
+      name: 'Ic1',
+      status: 'completed',
+      workspaceIds: [WS_1],
+    });
+    await seedWorkspaceMigration(context.dataSource, {
+      name: 'Wc1',
+      status: 'completed',
+      workspaceId: WS_1,
+    });
+    // WS_2 is inactive — its record is more recent (seeded later)
+    // but should not influence the global cursor
+    await seedWorkspaceMigration(context.dataSource, {
+      name: 'Wc2',
+      status: 'completed',
+      workspaceId: WS_2,
+    });
+
+    const report = await context.runner.run({
+      sequence,
+      options: DEFAULT_OPTIONS,
+    });
+
+    expect(report.totalFailures).toBe(0);
+
+    const executed = await testGetExecutedMigrationsInOrder(context.dataSource);
+
+    expect(executed.map(migrationRecordToKey)).toStrictEqual([
+      'Ic1:instance:completed:1',
+      `Ic1:${WS_1}:completed:1`,
+      `Wc1:${WS_1}:completed:1`,
+      `Wc2:${WS_2}:completed:1`,
+
+      // WS_2 is inactive, runner only processes WS_1
+      `Wc2:${WS_1}:completed:1`,
+    ]);
+  });
+});

packages/twenty-server/test/integration/upgrade/suites/sequence-runner/workspace-segment-alignment.integration-spec.ts

@@ -0,0 +1,585 @@
+import {
+  type IntegrationTestContext,
+  createUpgradeSequenceRunnerIntegrationTestModule,
+  DEFAULT_OPTIONS,
+  makeFastInstance,
+  makeSlowInstance,
+  makeWorkspace,
+  migrationRecordToKey,
+  resetSeedSequenceCounter,
+  restoreUpgradeMigrations,
+  seedInstanceMigration,
+  seedWorkspaceMigration,
+  setMockActiveWorkspaceIds,
+  snapshotUpgradeMigrations,
+  testGetExecutedMigrationsInOrder,
+  WS_1,
+  WS_2,
+  WS_3,
+} from 'test/integration/upgrade/utils/upgrade-sequence-runner-integration-test.util';
+
+describe('UpgradeSequenceRunnerService — workspace segment alignment (integration)', () => {
+  let context: IntegrationTestContext;
+  let savedUpgradeMigrations: Awaited<
+    ReturnType<typeof snapshotUpgradeMigrations>
+  >;
+
+  beforeAll(async () => {
+    context = await createUpgradeSequenceRunnerIntegrationTestModule();
+    savedUpgradeMigrations = await snapshotUpgradeMigrations(
+      context.dataSource,
+    );
+  }, 30000);
+
+  afterAll(async () => {
+    await restoreUpgradeMigrations(context.dataSource, savedUpgradeMigrations);
+    await context.module?.close();
+    await context.dataSource?.destroy();
+  }, 15000);
+
+  beforeEach(async () => {
+    await context.dataSource.query('DELETE FROM core."upgradeMigration"');
+    resetSeedSequenceCounter();
+    setMockActiveWorkspaceIds([]);
+    jest.restoreAllMocks();
+  });
+
+  it('should upgrade all workspaces when they are in the same segment at different positions', async () => {
+    // Sequence: Ic0 → Wc0 → Wc1 → Wc2 → Ic1 → Ic2 → Wc3 → Wc4
+    const sequence = [
+      makeFastInstance('Ic0'),
+      makeWorkspace('Wc0'),
+      makeWorkspace('Wc1'),
+      makeWorkspace('Wc2'),
+      makeFastInstance('Ic1'),
+      makeSlowInstance('Ic2'),
+      makeWorkspace('Wc3'),
+      makeWorkspace('Wc4'),
+    ];
+
+    setMockActiveWorkspaceIds([WS_1, WS_2, WS_3]);
+
+    await seedInstanceMigration(context.dataSource, {
+      name: 'Ic0',
+      status: 'completed',
+      workspaceIds: [WS_1, WS_2, WS_3],
+    });
+
+    // WS_1: at Wc0, completed
+    await seedWorkspaceMigration(context.dataSource, {
+      name: 'Wc0',
+      status: 'completed',
+      workspaceId: WS_1,
+    });
+
+    // WS_2: at Wc1, failed (needs retry)
+    await seedWorkspaceMigration(context.dataSource, {
+      name: 'Wc0',
+      status: 'completed',
+      workspaceId: WS_2,
+    });
+    await seedWorkspaceMigration(context.dataSource, {
+      name: 'Wc1',
+      status: 'failed',
+      workspaceId: WS_2,
+    });
+
+    // WS_3: at Wc2, completed (most advanced in segment)
+    await seedWorkspaceMigration(context.dataSource, {
+      name: 'Wc0',
+      status: 'completed',
+      workspaceId: WS_3,
+    });
+    await seedWorkspaceMigration(context.dataSource, {
+      name: 'Wc1',
+      status: 'completed',
+      workspaceId: WS_3,
+    });
+    await seedWorkspaceMigration(context.dataSource, {
+      name: 'Wc2',
+      status: 'completed',
+      workspaceId: WS_3,
+    });
+
+    const report = await context.runner.run({
+      sequence,
+      options: DEFAULT_OPTIONS,
+    });
+
+    expect(report.totalFailures).toBe(0);
+
+    const executed = await testGetExecutedMigrationsInOrder(context.dataSource);
+
+    expect(executed.map(migrationRecordToKey)).toStrictEqual([
+      // Seeds (Ic0 global + workspace rows inserted at same timestamp)
+      'Ic0:instance:completed:1',
+      `Ic0:${WS_1}:completed:1`,
+      `Ic0:${WS_2}:completed:1`,
+      `Ic0:${WS_3}:completed:1`,
+      `Wc0:${WS_1}:completed:1`,
+      `Wc0:${WS_2}:completed:1`,
+      `Wc1:${WS_2}:failed:1`,
+      `Wc0:${WS_3}:completed:1`,
+      `Wc1:${WS_3}:completed:1`,
+      `Wc2:${WS_3}:completed:1`,
+
+      // Segment A: WS_1 runs Wc1, Wc2; WS_2 retries Wc1, runs Wc2; WS_3 already done
+      `Wc1:${WS_1}:completed:1`,
+      `Wc2:${WS_1}:completed:1`,
+      `Wc1:${WS_2}:completed:2`,
+      `Wc2:${WS_2}:completed:1`,
+
+      // Sync barrier → instance steps (with workspace-level rows)
+      'Ic1:instance:completed:1',
+      `Ic1:${WS_1}:completed:1`,
+      `Ic1:${WS_2}:completed:1`,
+      `Ic1:${WS_3}:completed:1`,
+      'Ic2:instance:completed:1',
+      `Ic2:${WS_1}:completed:1`,
+      `Ic2:${WS_2}:completed:1`,
+      `Ic2:${WS_3}:completed:1`,
+
+      // Segment B: all workspaces run Wc3, Wc4
+      `Wc3:${WS_1}:completed:1`,
+      `Wc4:${WS_1}:completed:1`,
+      `Wc3:${WS_2}:completed:1`,
+      `Wc4:${WS_2}:completed:1`,
+      `Wc3:${WS_3}:completed:1`,
+      `Wc4:${WS_3}:completed:1`,
+    ]);
+  });
+
+  it('should reject workspaces with cursors ahead of the current segment', async () => {
+    // Sequence: Ic0 → Wc0 → Wc1 → Ic1 → Wc2 → Wc3
+    const sequence = [
+      makeFastInstance('Ic0'),
+      makeWorkspace('Wc0'),
+      makeWorkspace('Wc1'),
+      makeFastInstance('Ic1'),
+      makeWorkspace('Wc2'),
+      makeWorkspace('Wc3'),
+    ];
+
+    setMockActiveWorkspaceIds([WS_1, WS_2]);
+
+    // WS_1 existed when Ic0 ran; WS_2 was created later (initial at Wc2)
+    await seedInstanceMigration(context.dataSource, {
+      name: 'Ic0',
+      status: 'completed',
+      workspaceIds: [WS_1],
+    });
+
+    // WS_1: at Wc0 (in segment A) - correct
+    await seedWorkspaceMigration(context.dataSource, {
+      name: 'Wc0',
+      status: 'completed',
+      workspaceId: WS_1,
+    });
+
+    // WS_2: at Wc2 (in segment B) - WRONG! Ahead of current segment
+    await seedWorkspaceMigration(context.dataSource, {
+      name: 'Wc2',
+      status: 'completed',
+      workspaceId: WS_2,
+      isInitial: true,
+    });
+
+    await expect(
+      context.runner.run({
+        sequence,
+        options: {
+          ...DEFAULT_OPTIONS,
+          workspaceIds: [WS_1, WS_2],
+        },
+      }),
+    ).rejects.toThrow(
+      /workspace\(s\) have invalid cursors for workspace segment/,
+    );
+  });
+
+  it('should reject workspaces with cursors behind the current segment', async () => {
+    // Sequence: Wc-1 → Ic0 → Wc0 → Wc1 → Ic1 → Wc2
+    const sequence = [
+      makeWorkspace('Wc-1'),
+      makeFastInstance('Ic0'),
+      makeWorkspace('Wc0'),
+      makeWorkspace('Wc1'),
+      makeFastInstance('Ic1'),
+      makeWorkspace('Wc2'),
+    ];
+
+    setMockActiveWorkspaceIds([WS_1, WS_2]);
+
+    await seedInstanceMigration(context.dataSource, {
+      name: 'Ic0',
+      status: 'completed',
+      workspaceIds: [WS_1, WS_2],
+    });
+
+    // WS_1: at Wc0 (in segment after Ic0) - correct
+    await seedWorkspaceMigration(context.dataSource, {
+      name: 'Wc0',
+      status: 'completed',
+      workspaceId: WS_1,
+    });
+
+    // WS_2: at Wc-1 (in segment before Ic0) - WRONG! Behind current segment
+    await seedWorkspaceMigration(context.dataSource, {
+      name: 'Wc-1',
+      status: 'completed',
+      workspaceId: WS_2,
+    });
+
+    await expect(
+      context.runner.run({
+        sequence,
+        options: {
+          ...DEFAULT_OPTIONS,
+          workspaceIds: [WS_1, WS_2],
+        },
+      }),
+    ).rejects.toThrow(
+      /workspace\(s\) have invalid cursors for workspace segment/,
+    );
+  });
+
+  it('should handle workspaces created at correct segment via isInitial', async () => {
+    // Sequence: Wc0 → Ic0 → Ic1 → Wc1 → Wc2
+    // WS_1 existed from the start, WS_2 was created after Ic1
+    const sequence = [
+      makeWorkspace('Wc0'),
+      makeFastInstance('Ic0'),
+      makeFastInstance('Ic1'),
+      makeWorkspace('Wc1'),
+      makeWorkspace('Wc2'),
+    ];
+
+    setMockActiveWorkspaceIds([WS_1, WS_2]);
+
+    await seedInstanceMigration(context.dataSource, {
+      name: 'Ic0',
+      status: 'completed',
+      workspaceIds: [WS_1],
+    });
+    await seedInstanceMigration(context.dataSource, {
+      name: 'Ic1',
+      status: 'completed',
+      workspaceIds: [WS_1],
+    });
+
+    // WS_1: at Wc1 (in correct segment after Ic1)
+    await seedWorkspaceMigration(context.dataSource, {
+      name: 'Wc1',
+      status: 'completed',
+      workspaceId: WS_1,
+    });
+
+    // WS_2: newly created with isInitial at Wc2 (correct segment after Ic1)
+    await seedWorkspaceMigration(context.dataSource, {
+      name: 'Wc2',
+      status: 'completed',
+      workspaceId: WS_2,
+      isInitial: true,
+    });
+
+    const report = await context.runner.run({
+      sequence,
+      options: {
+        ...DEFAULT_OPTIONS,
+        workspaceIds: [WS_1, WS_2],
+      },
+    });
+
+    expect(report.totalFailures).toBe(0);
+
+    const executed = await testGetExecutedMigrationsInOrder(context.dataSource);
+
+    expect(executed.map(migrationRecordToKey)).toStrictEqual([
+      // Seeds
+      'Ic0:instance:completed:1',
+      `Ic0:${WS_1}:completed:1`,
+      'Ic1:instance:completed:1',
+      `Ic1:${WS_1}:completed:1`,
+      `Wc1:${WS_1}:completed:1`,
+      `Wc2:${WS_2}:completed:1:initial`,
+
+      // WS_1 runs Wc2, WS_2 already at Wc2 (no new commands needed)
+      `Wc2:${WS_1}:completed:1`,
+    ]);
+  });
+
+  it('should accept workspaces at the preceding completed IC when others are in the WC segment (-w scenario)', async () => {
+    // Sequence: Ic0 → Ic1 → Wc0 → Wc1
+    // WS_1 was upgraded via -w and is at Wc1:completed
+    // WS_2 is still at Ic1:completed (preceding IC)
+    const sequence = [
+      makeFastInstance('Ic0'),
+      makeFastInstance('Ic1'),
+      makeWorkspace('Wc0'),
+      makeWorkspace('Wc1'),
+    ];
+
+    setMockActiveWorkspaceIds([WS_1, WS_2]);
+
+    await seedInstanceMigration(context.dataSource, {
+      name: 'Ic0',
+      status: 'completed',
+      workspaceIds: [WS_1, WS_2],
+    });
+    await seedInstanceMigration(context.dataSource, {
+      name: 'Ic1',
+      status: 'completed',
+      workspaceIds: [WS_1, WS_2],
+    });
+
+    // WS_1 was upgraded ahead via -w
+    await seedWorkspaceMigration(context.dataSource, {
+      name: 'Wc0',
+      status: 'completed',
+      workspaceId: WS_1,
+    });
+    await seedWorkspaceMigration(context.dataSource, {
+      name: 'Wc1',
+      status: 'completed',
+      workspaceId: WS_1,
+    });
+
+    const report = await context.runner.run({
+      sequence,
+      options: {
+        ...DEFAULT_OPTIONS,
+        workspaceIds: [WS_1, WS_2],
+      },
+    });
+
+    expect(report.totalFailures).toBe(0);
+
+    const executed = await testGetExecutedMigrationsInOrder(context.dataSource);
+
+    expect(executed.map(migrationRecordToKey)).toStrictEqual([
+      // Seeds
+      'Ic0:instance:completed:1',
+      `Ic0:${WS_1}:completed:1`,
+      `Ic0:${WS_2}:completed:1`,
+      'Ic1:instance:completed:1',
+      `Ic1:${WS_1}:completed:1`,
+      `Ic1:${WS_2}:completed:1`,
+      `Wc0:${WS_1}:completed:1`,
+      `Wc1:${WS_1}:completed:1`,
+
+      // WS_2 runs full segment, WS_1 already done
+      `Wc0:${WS_2}:completed:1`,
+      `Wc1:${WS_2}:completed:1`,
+    ]);
+  });
+
+  it('should reject workspace at preceding IC with failed status', async () => {
+    // Sequence: Ic0 → Wc0 → Wc1
+    // WS_1 is in the WC segment, WS_2 is at Ic0:failed
+    const sequence = [
+      makeFastInstance('Ic0'),
+      makeWorkspace('Wc0'),
+      makeWorkspace('Wc1'),
+    ];
+
+    setMockActiveWorkspaceIds([WS_1, WS_2]);
+
+    await seedInstanceMigration(context.dataSource, {
+      name: 'Ic0',
+      status: 'completed',
+      workspaceIds: [WS_1],
+    });
+
+    // WS_2 at Ic0:failed — should be rejected
+    await seedWorkspaceMigration(context.dataSource, {
+      name: 'Ic0',
+      status: 'failed',
+      workspaceId: WS_2,
+    });
+
+    await seedWorkspaceMigration(context.dataSource, {
+      name: 'Wc0',
+      status: 'completed',
+      workspaceId: WS_1,
+    });
+
+    await expect(
+      context.runner.run({
+        sequence,
+        options: {
+          ...DEFAULT_OPTIONS,
+          workspaceIds: [WS_1, WS_2],
+        },
+      }),
+    ).rejects.toThrow(
+      /workspace\(s\) have invalid cursors for workspace segment/,
+    );
+  });
+
+  it('should reject workspace stuck in a previous WC segment (corrupted state)', async () => {
+    // Sequence: Wc0 → Wc1 → Ic0 → Wc2 → Wc3
+    // WS_1 is in segment [Wc2..Wc3], WS_2 is stuck at Wc0 (previous WC segment)
+    const sequence = [
+      makeWorkspace('Wc0'),
+      makeWorkspace('Wc1'),
+      makeFastInstance('Ic0'),
+      makeWorkspace('Wc2'),
+      makeWorkspace('Wc3'),
+    ];
+
+    setMockActiveWorkspaceIds([WS_1, WS_2]);
+
+    await seedWorkspaceMigration(context.dataSource, {
+      name: 'Wc0',
+      status: 'completed',
+      workspaceId: WS_1,
+    });
+    await seedWorkspaceMigration(context.dataSource, {
+      name: 'Wc1',
+      status: 'completed',
+      workspaceId: WS_1,
+    });
+    await seedInstanceMigration(context.dataSource, {
+      name: 'Ic0',
+      status: 'completed',
+      workspaceIds: [WS_1],
+    });
+    await seedWorkspaceMigration(context.dataSource, {
+      name: 'Wc2',
+      status: 'completed',
+      workspaceId: WS_1,
+    });
+
+    // WS_2 stuck at Wc0 in previous WC segment — corrupted
+    await seedWorkspaceMigration(context.dataSource, {
+      name: 'Wc0',
+      status: 'completed',
+      workspaceId: WS_2,
+    });
+
+    await expect(
+      context.runner.run({
+        sequence,
+        options: {
+          ...DEFAULT_OPTIONS,
+          workspaceIds: [WS_1, WS_2],
+        },
+      }),
+    ).rejects.toThrow(
+      /workspace\(s\) have invalid cursors for workspace segment/,
+    );
+  });
+
+  it('should write workspace rows for IC failure, accept workspace created mid-failure, and succeed on restart', async () => {
+    // Sequence: Ic0 → Ic1 → Wc0 → Wc1
+    // First run: Ic1 fails → global + workspace rows written as failed
+    // WS_3 is created while Ic1 is failed → initial cursor at Ic1:failed
+    // Second run: Ic1 retries and succeeds → WC segment runs for all 3 workspaces
+    const failOnce = { shouldFail: true };
+
+    const ic1Command = {
+      up: async () => {
+        if (failOnce.shouldFail) {
+          failOnce.shouldFail = false;
+          throw new Error('Ic1 temporary failure');
+        }
+      },
+      down: async () => {},
+    };
+
+    const sequence = [
+      makeFastInstance('Ic0'),
+      {
+        ...makeFastInstance('Ic1'),
+        command: ic1Command,
+      } as unknown as ReturnType<typeof makeFastInstance>,
+      makeWorkspace('Wc0'),
+      makeWorkspace('Wc1'),
+    ];
+
+    setMockActiveWorkspaceIds([WS_1, WS_2]);
+
+    await seedInstanceMigration(context.dataSource, {
+      name: 'Ic0',
+      status: 'completed',
+      workspaceIds: [WS_1, WS_2],
+    });
+
+    // First run — Ic1 fails
+    await expect(
+      context.runner.run({
+        sequence,
+        options: DEFAULT_OPTIONS,
+      }),
+    ).rejects.toThrow('Ic1 temporary failure');
+
+    const afterFailure = await testGetExecutedMigrationsInOrder(
+      context.dataSource,
+    );
+
+    expect(afterFailure.map(migrationRecordToKey)).toStrictEqual([
+      // Seeds
+      'Ic0:instance:completed:1',
+      `Ic0:${WS_1}:completed:1`,
+      `Ic0:${WS_2}:completed:1`,
+
+      // Ic1 failed globally + workspace rows
+      'Ic1:instance:failed:1',
+      `Ic1:${WS_1}:failed:1`,
+      `Ic1:${WS_2}:failed:1`,
+    ]);
+
+    // WS_3 created while Ic1 is failed —
+    // getInitialCursorForNewWorkspace returns { name: 'Ic1', status: 'failed' }
+    await seedWorkspaceMigration(context.dataSource, {
+      name: 'Ic1',
+      status: 'failed',
+      workspaceId: WS_3,
+      isInitial: true,
+      useCurrentTimestamp: true,
+    });
+
+    setMockActiveWorkspaceIds([WS_1, WS_2, WS_3]);
+
+    // Second run — Ic1 retries and succeeds, then WC segment runs for all 3
+    const report = await context.runner.run({
+      sequence,
+      options: DEFAULT_OPTIONS,
+    });
+
+    expect(report.totalFailures).toBe(0);
+
+    const afterRetry = await testGetExecutedMigrationsInOrder(
+      context.dataSource,
+    );
+
+    expect(afterRetry.map(migrationRecordToKey)).toStrictEqual([
+      // Seeds
+      'Ic0:instance:completed:1',
+      `Ic0:${WS_1}:completed:1`,
+      `Ic0:${WS_2}:completed:1`,
+
+      // First run — Ic1 failed
+      'Ic1:instance:failed:1',
+      `Ic1:${WS_1}:failed:1`,
+      `Ic1:${WS_2}:failed:1`,
+
+      // WS_3 created after Ic1 failure, initial cursor at Ic1:failed
+      `Ic1:${WS_3}:failed:1:initial`,
+
+      // Second run — Ic1 retry succeeds
+      'Ic1:instance:completed:2',
+      `Ic1:${WS_1}:completed:2`,
+      `Ic1:${WS_2}:completed:2`,
+      `Ic1:${WS_3}:completed:2`,
+
+      // WC segment runs for all 3 workspaces
+      `Wc0:${WS_1}:completed:1`,
+      `Wc1:${WS_1}:completed:1`,
+      `Wc0:${WS_2}:completed:1`,
+      `Wc1:${WS_2}:completed:1`,
+      `Wc0:${WS_3}:completed:1`,
+      `Wc1:${WS_3}:completed:1`,
+    ]);
+  });
+});