@vellumai/assistant 0.10.0 → 0.10.1-staging.1

package/src/memory/migrations/298-move-memory-jobs-to-memory-db.ts

@@ -0,0 +1,128 @@
+import type { Database } from "bun:sqlite";
+
+import { getMemoryDbPath } from "../../util/memory-db-path.js";
+import {
+  type DrizzleDb,
+  getMemorySqlite,
+  getSqliteFrom,
+} from "../db-connection.js";
+import {
+  drainStagedTable,
+  type RelocationSpec,
+  stageTableForRelocation,
+} from "./helpers/relocation.js";
+
+/**
+ * How to drain `memory_jobs` from `main` into the memory DB. Only
+ * `pending`/`running` jobs are worth keeping; the terminal (`completed`/`failed`)
+ * rows that make up the bulk of a runaway queue are purged without copying.
+ *
+ * A `running` job is copied as `pending`: the worker's startup
+ * `resetRunningJobsToPending()` runs against the (empty) new table before this
+ * drain copies rows over, so a row left `running` would never be re-claimed.
+ * Resetting it here makes the relocated job re-claimable in its new home.
+ */
+export const MEMORY_JOBS_RELOCATION: RelocationSpec = {
+  table: "memory_jobs",
+  targetDbPath: getMemoryDbPath,
+  columns: [
+    "id",
+    "type",
+    "payload",
+    "status",
+    "attempts",
+    "deferrals",
+    "run_after",
+    "last_error",
+    "started_at",
+    "created_at",
+    "updated_at",
+  ],
+  copyWhere: "status IN ('pending','running')",
+  columnExpr: {
+    status: "CASE WHEN status = 'running' THEN 'pending' ELSE status END",
+  },
+};
+
+const CREATE_TABLE = /*sql*/ `
+  CREATE TABLE IF NOT EXISTS memory_jobs (
+    id TEXT PRIMARY KEY,
+    type TEXT NOT NULL,
+    payload TEXT NOT NULL,
+    status TEXT NOT NULL,
+    attempts INTEGER NOT NULL DEFAULT 0,
+    deferrals INTEGER NOT NULL DEFAULT 0,
+    run_after INTEGER NOT NULL,
+    last_error TEXT,
+    started_at INTEGER,
+    created_at INTEGER NOT NULL,
+    updated_at INTEGER NOT NULL
+  )
+`;
+
+/**
+ * Create the `memory_jobs` table and its indexes on the memory connection.
+ * Idempotent (`IF NOT EXISTS`) — the dedicated connection itself performs no DDL
+ * on open, so this migration owns the schema.
+ */
+function ensureMemoryJobsSchema(memoryRaw: Database): void {
+  memoryRaw.exec(CREATE_TABLE);
+  createIndexes(memoryRaw);
+}
+
+/** Create the two `memory_jobs` indexes on the memory connection. */
+function createIndexes(raw: Database) {
+  raw.exec(
+    `CREATE INDEX IF NOT EXISTS idx_memory_jobs_status_run_after ON memory_jobs(status, run_after)`,
+  );
+  raw.exec(/*sql*/ `
+    CREATE INDEX IF NOT EXISTS idx_memory_jobs_conflict_resolve_dedupe
+    ON memory_jobs(
+      type,
+      status,
+      json_extract(payload, '$.messageId'),
+      COALESCE(json_extract(payload, '$.scopeId'), 'default')
+    )
+  `);
+}
+
+/**
+ * Move the `memory_jobs` work queue into its own database
+ * (`assistant-memory.db`). The queue is the heaviest, highest-churn table —
+ * left in the main DB a runaway backlog bloats it (and its WAL) to many GB.
+ * Splitting it out lets the queue grow, VACUUM, and checkpoint independently.
+ * The jobs store reads/writes the queue over the dedicated memory connection
+ * (see `getMemoryDb()`).
+ *
+ * Like the `llm_request_logs` move (migration 297) this is incremental: create
+ * the table (and indexes) on the memory connection, rename any populated
+ * `main.memory_jobs` aside to `memory_jobs__relocating`, then drain it in
+ * awaited batches (see `helpers/relocation.ts`) per {@link MEMORY_JOBS_RELOCATION}.
+ *
+ * Because the drain is awaited as part of this step, the pending/running jobs
+ * are in their new home before the memory jobs worker starts later in daemon
+ * startup — the worker never observes a transiently empty queue.
+ *
+ * Throws (rather than returning) if the memory database cannot be opened, so
+ * the runner records the step as failed instead of applied and retries it on a
+ * later boot — never renaming the source aside without a target to write to,
+ * and never marking the relocation done while it has not happened. The throw is
+ * caught per-step by the runner, so startup is not aborted.
+ */
+export async function migrateMoveMemoryJobsToMemoryDb(
+  database: DrizzleDb,
+): Promise<void> {
+  const memoryRaw = getMemorySqlite();
+  if (!memoryRaw) {
+    throw new Error(
+      "memory database unavailable — deferring memory_jobs relocation",
+    );
+  }
+
+  ensureMemoryJobsSchema(memoryRaw);
+
+  const raw = getSqliteFrom(database);
+  const needsDrain = stageTableForRelocation(raw, MEMORY_JOBS_RELOCATION.table);
+
+  if (needsDrain) await drainStagedTable(raw, MEMORY_JOBS_RELOCATION);
+}

package/src/memory/migrations/299-canonical-guardian-deliveries-conversation-index.ts

@@ -0,0 +1,19 @@
+import type { DrizzleDb } from "../db-connection.js";
+
+/**
+ * Add index on canonical_guardian_deliveries(destination_conversation_id).
+ *
+ * Guardian cards record their associated internal conversation on every
+ * delivery — channel cards as well as in-app — and the conversation-scope
+ * readers (candidate enrichment, decision gate, reply-routing seed) look up
+ * pending requests by destination_conversation_id. Candidate enrichment runs on
+ * the per-notification routing path, so without this index those lookups
+ * degrade to full table scans as delivery history grows.
+ */
+export function migrateCanonicalGuardianDeliveriesConversationIndex(
+  database: DrizzleDb,
+): void {
+  database.run(
+    /*sql*/ `CREATE INDEX IF NOT EXISTS idx_canonical_guardian_deliveries_dest_conversation ON canonical_guardian_deliveries(destination_conversation_id)`,
+  );
+}

package/src/memory/migrations/__tests__/297-move-llm-request-logs.test.ts

@@ -0,0 +1,180 @@
+/**
+ * Tests for migration 297 — housing `llm_request_logs` in the dedicated
+ * `logs` database connection.
+ *
+ * Covers:
+ *   1. End state after a full initializeDb(): the table lives in the logs
+ *      connection, not `main`, and the Drizzle store round-trips against it.
+ *   2. The relocation itself: rows in a `main.llm_request_logs` are copied into
+ *      the logs connection and the main-DB copy is dropped, with indexes built
+ *      in the logs connection.
+ *   3. A legacy base-only `main` table (predating the newer columns) is copied
+ *      without error, NULL-filling the absent columns.
+ *
+ * The step is idempotent and not checkpoint-gated, so each test can drive it
+ * directly without clearing any checkpoint.
+ */
+import { describe, expect, test } from "bun:test";
+
+const { getDb, getSqlite, getLogsSqlite } =
+  await import("../../db-connection.js");
+const { initializeDb } = await import("../../db-init.js");
+const { migrateMoveLlmRequestLogsToLogsDb } =
+  await import("../297-move-llm-request-logs-to-logs-db.js");
+const { recordRequestLog, getRequestLogById } =
+  await import("../../llm-request-log-store.js");
+
+await initializeDb();
+
+function existsInMain(name: string): boolean {
+  return (
+    getSqlite()
+      .query(
+        `SELECT name FROM main.sqlite_master WHERE type='table' AND name = ?`,
+      )
+      .get(name) != null
+  );
+}
+
+function existsInLogs(name: string): boolean {
+  return (
+    getLogsSqlite()!
+      .query(`SELECT name FROM sqlite_master WHERE type='table' AND name = ?`)
+      .get(name) != null
+  );
+}
+
+function stagingExists(table: string): boolean {
+  return existsInMain(`${table}__relocating`);
+}
+
+describe("migration 297 — llm_request_logs lives in the logs database", () => {
+  test("after init, the table is in logs and not in main", () => {
+    expect(existsInLogs("llm_request_logs")).toBe(true);
+    expect(existsInMain("llm_request_logs")).toBe(false);
+  });
+
+  test("the store round-trips against the relocated table", () => {
+    const id = recordRequestLog(
+      "conv-297",
+      JSON.stringify({ req: 1 }),
+      JSON.stringify({ res: 1 }),
+      "msg-297",
+      "anthropic",
+      "mainAgent",
+    );
+    const row = getRequestLogById(id);
+    expect(row?.conversationId).toBe("conv-297");
+    expect(row?.messageId).toBe("msg-297");
+    expect(row?.provider).toBe("anthropic");
+    expect(row?.callSite).toBe("mainAgent");
+
+    // The written row physically lives in the logs database.
+    const inLogs = getLogsSqlite()!
+      .query<
+        { c: number },
+        [string]
+      >(`SELECT COUNT(*) AS c FROM llm_request_logs WHERE id = ?`)
+      .get(id);
+    expect(inLogs?.c).toBe(1);
+  });
+
+  test("relocates rows from a main-DB table and drops it", async () => {
+    const sqlite = getSqlite();
+    const logs = getLogsSqlite()!;
+
+    // Simulate a populated pre-relocation main-DB table alongside the logs copy.
+    logs.exec(`DROP TABLE IF EXISTS llm_request_logs`);
+    sqlite.exec(`DROP TABLE IF EXISTS main.llm_request_logs__relocating`);
+    sqlite.exec(`
+      CREATE TABLE main.llm_request_logs (
+        id TEXT PRIMARY KEY,
+        conversation_id TEXT NOT NULL,
+        message_id TEXT,
+        provider TEXT,
+        request_payload TEXT NOT NULL,
+        response_payload TEXT NOT NULL,
+        created_at INTEGER NOT NULL,
+        agent_loop_exit_reason TEXT,
+        call_site TEXT
+      )
+    `);
+    sqlite.exec(
+      `INSERT INTO main.llm_request_logs (id, conversation_id, request_payload, response_payload, created_at, provider) VALUES ('legacy-1', 'conv-legacy', '{}', '{}', 123, 'openai')`,
+    );
+
+    // The migration stages the populated table aside and drains it inline,
+    // copying the rows into logs and dropping the staging table before it
+    // resolves.
+    await migrateMoveLlmRequestLogsToLogsDb(getDb());
+
+    expect(existsInLogs("llm_request_logs")).toBe(true);
+    expect(existsInMain("llm_request_logs")).toBe(false);
+    expect(stagingExists("llm_request_logs")).toBe(false);
+    const moved = logs
+      .query<
+        { conversation_id: string; provider: string },
+        []
+      >(`SELECT conversation_id, provider FROM llm_request_logs WHERE id = 'legacy-1'`)
+      .get();
+    expect(moved?.conversation_id).toBe("conv-legacy");
+    expect(moved?.provider).toBe("openai");
+
+    // Indexes were created in the logs database.
+    const indexes = logs
+      .query<{ name: string }, []>(
+        `SELECT name FROM sqlite_master WHERE type='index' AND tbl_name='llm_request_logs'`,
+      )
+      .all()
+      .map((r) => r.name);
+    expect(indexes).toContain("idx_llm_request_logs_message_id");
+    expect(indexes).toContain("idx_llm_request_logs_created_at");
+    expect(indexes).toContain("idx_llm_request_logs_conv_created");
+  });
+
+  test("copies a legacy base-only table, NULL-filling newer columns", async () => {
+    const sqlite = getSqlite();
+    const logs = getLogsSqlite()!;
+
+    // A workspace upgrading from a build that predates the
+    // message_id/provider/agent_loop_exit_reason/call_site columns: the main
+    // table has only the original base columns.
+    logs.exec(`DROP TABLE IF EXISTS llm_request_logs`);
+    sqlite.exec(`DROP TABLE IF EXISTS main.llm_request_logs__relocating`);
+    sqlite.exec(`
+      CREATE TABLE main.llm_request_logs (
+        id TEXT PRIMARY KEY,
+        conversation_id TEXT NOT NULL,
+        request_payload TEXT NOT NULL,
+        response_payload TEXT NOT NULL,
+        created_at INTEGER NOT NULL
+      )
+    `);
+    sqlite.exec(
+      `INSERT INTO main.llm_request_logs (id, conversation_id, request_payload, response_payload, created_at) VALUES ('base-1', 'conv-base', '{}', '{}', 7)`,
+    );
+
+    // Must not throw on the absent columns: the drain NULL-fills them.
+    await migrateMoveLlmRequestLogsToLogsDb(getDb());
+
+    expect(existsInLogs("llm_request_logs")).toBe(true);
+    expect(existsInMain("llm_request_logs")).toBe(false);
+    const moved = logs
+      .query<
+        {
+          conversation_id: string;
+          message_id: string | null;
+          provider: string | null;
+          call_site: string | null;
+        },
+        []
+      >(
+        `SELECT conversation_id, message_id, provider, call_site FROM llm_request_logs WHERE id = 'base-1'`,
+      )
+      .get();
+    expect(moved?.conversation_id).toBe("conv-base");
+    expect(moved?.message_id).toBeNull();
+    expect(moved?.provider).toBeNull();
+    expect(moved?.call_site).toBeNull();
+  });
+});

package/src/memory/migrations/__tests__/run-migrations.test.ts

@@ -3,8 +3,13 @@ import { describe, expect, test } from "bun:test";
 
 import { drizzle } from "drizzle-orm/bun-sqlite";
 
+import { getSqliteFrom } from "../../db-connection.js";
 import * as schema from "../../schema.js";
-import { type MigrationStep, runMigrationSteps } from "../run-migrations.js";
+import {
+  clearMigrationStepCheckpoints,
+  type MigrationStep,
+  runMigrationSteps,
+} from "../run-migrations.js";
 
 function createTestDb() {
   const sqlite = new Database(":memory:");
@@ -14,10 +19,7 @@ function createTestDb() {
 }
 
 describe("runMigrationSteps — checkpointing", () => {
-  // Skipped: documents the post-checkpointing contract and fails against the
-  // current behavior, which re-runs every forward step on every boot. Promote
-  // to `test` when true checkpointing of initial migrations lands.
-  test.skip("does not re-execute a step that was already applied on a prior run", () => {
+  test("does not re-execute a step that was already applied on a prior run", async () => {
     /**
      * Booting an already-migrated database must not re-run forward migration
      * steps. With true checkpointing each step's body executes at most once
@@ -41,12 +43,336 @@ describe("runMigrationSteps — checkpointing", () => {
 
     // AND a database that has already been migrated once
     const db = createTestDb();
-    runMigrationSteps(db, steps);
+    await runMigrationSteps(db, steps);
 
     // WHEN the same steps run again against the already-migrated database
-    runMigrationSteps(db, steps);
+    await runMigrationSteps(db, steps);
 
     // THEN no step body executes a second time
     expect(calls).toEqual({ a: 1, b: 1, c: 1 });
   });
+
+  test("records step completions in the shared memory_checkpoints ledger", async () => {
+    /**
+     * Step bookkeeping lives in the same memory_checkpoints table the registry
+     * uses, under the `step:` namespace — one ledger for all applied state.
+     */
+
+    // GIVEN a single named step
+    const db = createTestDb();
+    await runMigrationSteps(db, [
+      function dummyMigrationA() {
+        // no-op
+      },
+    ]);
+
+    // THEN its completion is recorded under the step: namespace in memory_checkpoints
+    const row = getSqliteFrom(db)
+      .query(
+        `SELECT value FROM memory_checkpoints WHERE key = 'step:dummyMigrationA'`,
+      )
+      .get() as { value: string } | null;
+    expect(row?.value).toBe("1");
+  });
+
+  test("runs a newly appended step on a later boot while skipping applied ones", async () => {
+    /**
+     * Checkpointing must not block migrations added in a later release: an
+     * already-applied step is skipped, but a brand-new step still runs.
+     */
+
+    // GIVEN a database already migrated with two steps
+    const calls = { a: 0, b: 0, c: 0 };
+    const stepA: MigrationStep = function dummyMigrationA() {
+      calls.a++;
+    };
+    const stepB: MigrationStep = function dummyMigrationB() {
+      calls.b++;
+    };
+    const db = createTestDb();
+    await runMigrationSteps(db, [stepA, stepB]);
+
+    // AND a third step appended to the list
+    const stepC: MigrationStep = function dummyMigrationC() {
+      calls.c++;
+    };
+
+    // WHEN the expanded list runs against the already-migrated database
+    await runMigrationSteps(db, [stepA, stepB, stepC]);
+
+    // THEN only the newly appended step executes
+    expect(calls).toEqual({ a: 1, b: 1, c: 1 });
+  });
+
+  test("recovers crashed migrations before running steps", async () => {
+    /**
+     * runMigrationSteps clears stalled `started`/`rolling_back` checkpoints
+     * before the loop so a migration interrupted mid-flight re-runs this boot.
+     */
+
+    // GIVEN a database with a stalled registry checkpoint left by a crash
+    const db = createTestDb();
+    const raw = getSqliteFrom(db);
+    raw.run(
+      `CREATE TABLE IF NOT EXISTS memory_checkpoints (key TEXT PRIMARY KEY, value TEXT NOT NULL, updated_at INTEGER NOT NULL)`,
+    );
+    raw.run(
+      `INSERT INTO memory_checkpoints (key, value, updated_at) VALUES ('migration_stalled_v1', 'started', 0)`,
+    );
+
+    // WHEN the runner executes
+    await runMigrationSteps(db, [
+      function dummyMigrationA() {
+        // no-op
+      },
+    ]);
+
+    // THEN the stalled checkpoint has been cleared so its migration can re-run
+    const row = raw
+      .query(
+        `SELECT 1 FROM memory_checkpoints WHERE key = 'migration_stalled_v1'`,
+      )
+      .get();
+    expect(row).toBeNull();
+  });
+
+  test("does not checkpoint a failed step so it retries on the next boot", async () => {
+    /**
+     * A step whose body throws is reported in `failed` and left uncheckpointed,
+     * so the next boot retries it instead of silently skipping it.
+     */
+
+    // GIVEN a step that throws on its first run and succeeds afterwards
+    const calls = { flaky: 0 };
+    const steps: MigrationStep[] = [
+      function flakyStep() {
+        calls.flaky++;
+        if (calls.flaky === 1) {
+          throw new Error("transient failure");
+        }
+      },
+    ];
+    const db = createTestDb();
+    const first = await runMigrationSteps(db, steps);
+
+    // AND the first run reports the failure
+    expect(first.failed).toEqual(["flakyStep"]);
+
+    // WHEN the step runs again on the next boot
+    const second = await runMigrationSteps(db, steps);
+
+    // THEN it retries, succeeds, and is then checkpointed
+    expect(calls.flaky).toBe(2);
+    expect(second.failed).toEqual([]);
+    expect((await runMigrationSteps(db, steps)).skipped).toEqual(["flakyStep"]);
+  });
+
+  test("clearMigrationStepCheckpoints forces every step to re-run", async () => {
+    /**
+     * Clearing the step namespace (as rollback does) makes the next run
+     * re-execute and re-record all steps.
+     */
+
+    // GIVEN a database migrated once
+    const calls = { a: 0 };
+    const steps: MigrationStep[] = [
+      function dummyMigrationA() {
+        calls.a++;
+      },
+    ];
+    const db = createTestDb();
+    await runMigrationSteps(db, steps);
+    expect(calls.a).toBe(1);
+
+    // WHEN the step checkpoints are cleared
+    clearMigrationStepCheckpoints(db);
+
+    // THEN the next run re-executes the step
+    await runMigrationSteps(db, steps);
+    expect(calls.a).toBe(2);
+  });
+
+  test("awaits an async step to completion before running or checkpointing the next", async () => {
+    /**
+     * An async step must be fully drained before the runner advances: ordering
+     * is the invariant later migrations rely on (step N+1 may assume N's result
+     * is true), and the step is checkpointed only after its promise resolves so
+     * a crash mid-drain leaves it uncheckpointed and retryable rather than
+     * recorded as done.
+     */
+
+    // GIVEN an async step that records its completion order only after yielding,
+    // followed by a sync step that records when it starts
+    const order: string[] = [];
+    const steps: MigrationStep[] = [
+      async function asyncDrainStep() {
+        await Promise.resolve();
+        order.push("async-done");
+      },
+      function followingStep() {
+        order.push("following-start");
+      },
+    ];
+    const db = createTestDb();
+
+    // WHEN the runner executes both steps
+    const result = await runMigrationSteps(db, steps);
+
+    // THEN the async step finishes before the next step starts
+    expect(order).toEqual(["async-done", "following-start"]);
+
+    // AND both steps are checkpointed, so a later boot skips them
+    expect(result.failed).toEqual([]);
+    expect((await runMigrationSteps(db, steps)).skipped).toEqual([
+      "asyncDrainStep",
+      "followingStep",
+    ]);
+  });
+
+  test("a rejected async step is reported failed and left uncheckpointed", async () => {
+    /**
+     * A step whose promise rejects must be treated exactly like a synchronous
+     * throw: reported in `failed`, not checkpointed, and retried next boot.
+     */
+
+    // GIVEN an async step that rejects on its first run and resolves afterwards
+    const calls = { flaky: 0 };
+    const steps: MigrationStep[] = [
+      async function flakyAsyncStep() {
+        calls.flaky++;
+        await Promise.resolve();
+        if (calls.flaky === 1) {
+          throw new Error("transient async failure");
+        }
+      },
+    ];
+    const db = createTestDb();
+
+    // WHEN it runs and rejects
+    const first = await runMigrationSteps(db, steps);
+
+    // THEN the rejection is reported and the step is not checkpointed
+    expect(first.failed).toEqual(["flakyAsyncStep"]);
+
+    // WHEN it runs again on the next boot
+    const second = await runMigrationSteps(db, steps);
+
+    // THEN it retries, resolves, and is then checkpointed
+    expect(calls.flaky).toBe(2);
+    expect(second.failed).toEqual([]);
+    expect((await runMigrationSteps(db, steps)).skipped).toEqual([
+      "flakyAsyncStep",
+    ]);
+  });
+
+  test("detects and recovers step-level 'started' markers from a prior crash", async () => {
+    /**
+     * If the process crashes mid-step, the runner leaves a `step:<name>` =
+     * 'started' checkpoint. On the next boot, recoverCrashedMigrations
+     * detects it, clears it, and the step re-runs.
+     */
+
+    // GIVEN a database with a stalled step: checkpoint left by a crash
+    const db = createTestDb();
+    const raw = getSqliteFrom(db);
+    raw.run(
+      `CREATE TABLE IF NOT EXISTS memory_checkpoints (key TEXT PRIMARY KEY, value TEXT NOT NULL, updated_at INTEGER NOT NULL)`,
+    );
+    raw.run(
+      `INSERT INTO memory_checkpoints (key, value, updated_at) VALUES ('step:crashedStep', 'started', 0)`,
+    );
+
+    let ran = false;
+    const steps: MigrationStep[] = [
+      function crashedStep() {
+        ran = true;
+      },
+    ];
+
+    // WHEN the runner executes — recoverCrashedMigrations should clear
+    // the 'started' marker and let the step run.
+    await runMigrationSteps(db, steps);
+
+    // THEN the stalled checkpoint was cleared and the step ran
+    expect(ran).toBe(true);
+    const stalled = raw
+      .query(
+        `SELECT 1 FROM memory_checkpoints WHERE key = 'step:crashedStep' AND value = 'started'`,
+      )
+      .get();
+    expect(stalled).toBeNull();
+    // And the step was checkpointed as '1' (completed)
+    const completed = raw
+      .query(
+        `SELECT 1 FROM memory_checkpoints WHERE key = 'step:crashedStep' AND value = '1'`,
+      )
+      .get();
+    expect(completed).not.toBeNull();
+  });
+
+  test("does not skip a step whose only checkpoint is 'started' (not '1')", async () => {
+    /**
+     * The skip query filters for value = '1', so a 'started' marker
+     * alone must not cause a step to be skipped — the step should run.
+     * (recoverCrashedMigrations clears 'started' markers first, but
+     * even if it didn't, the skip logic is independent and correct.)
+     */
+
+    const db = createTestDb();
+    const raw = getSqliteFrom(db);
+    raw.run(
+      `CREATE TABLE IF NOT EXISTS memory_checkpoints (key TEXT PRIMARY KEY, value TEXT NOT NULL, updated_at INTEGER NOT NULL)`,
+    );
+    // Insert a 'started' marker without running recoverCrashedMigrations.
+    // We simulate this by inserting directly and checking the applied set.
+    raw.run(
+      `INSERT INTO memory_checkpoints (key, value, updated_at) VALUES ('step:someStep', 'started', 0)`,
+    );
+
+    let ran = false;
+    const steps: MigrationStep[] = [
+      function someStep() {
+        ran = true;
+      },
+    ];
+
+    // WHEN the runner executes, recoverCrashedMigrations clears the
+    // 'started' marker, so the step is not in the applied set and runs.
+    const result = await runMigrationSteps(db, steps);
+
+    // THEN the step ran (was not skipped)
+    expect(ran).toBe(true);
+    expect(result.applied).toEqual(["someStep"]);
+    expect(result.skipped).toEqual([]);
+  });
+
+  test("writes 'started' marker before running each step", async () => {
+    const db = createTestDb();
+    const raw = getSqliteFrom(db);
+
+    const seen: { marker: string | null } = { marker: null };
+    const steps: MigrationStep[] = [
+      async function asyncWithInspection() {
+        const row = raw
+          .query<{ value: string }, []>(
+            `SELECT value FROM memory_checkpoints WHERE key = 'step:asyncWithInspection'`,
+          )
+          .get();
+        seen.marker = row?.value ?? null;
+        await Promise.resolve();
+      },
+    ];
+
+    await runMigrationSteps(db, steps);
+
+    // The 'started' marker was visible during the async step's execution
+    expect(seen.marker).toBe("started");
+
+    const final = raw
+      .query<{ value: string }, []>(
+        `SELECT value FROM memory_checkpoints WHERE key = 'step:asyncWithInspection'`,
+      )
+      .get();
+    expect(final?.value).toBe("1");
+  });
 });