routstrd 0.4.0 → 0.4.1

package/src/daemon/wallet/receive-dedup.test.ts

@@ -0,0 +1,238 @@
+import { describe, expect, it } from "bun:test";
+import type { ReceiveOperation } from "@cashu/coco-core";
+import { Database } from "bun:sqlite";
+import {
+  clearInterruptedReceiveReservations,
+  deleteReceiveTokenReservation,
+  groupExecutingReceives,
+  hashReceiveToken,
+  initReceiveDedupSchema,
+  listProcessingReceiveTokens,
+  reconcileExecutingReceives,
+  reserveReceiveToken,
+  updateReceiveToken,
+  type ReceiveReconcileSource,
+} from "./receive-dedup";
+
+function operation(
+  id: string,
+  secret: string,
+  outputB: string,
+  createdAt = 1,
+): Extract<ReceiveOperation, { state: "executing" }> {
+  return {
+    id,
+    mintUrl: "https://mint.example",
+    unit: "sat",
+    amount: 1,
+    state: "executing",
+    createdAt,
+    updatedAt: createdAt,
+    fee: 0,
+    inputProofs: [{ amount: 1, id: "keyset", secret, C: "02" }],
+    outputData: {
+      keep: [
+        {
+          blindedMessage: { amount: 1, id: "keyset", B_: outputB },
+          blindingFactor: "1",
+          secret: "00",
+        },
+      ],
+      send: [],
+    },
+  };
+}
+
+function source(options: {
+  operations: ReceiveOperation[];
+  states?: string[];
+  restored?: string[];
+  saved?: string[];
+}) {
+  const rolledBack: Array<{ id: string; reason: string }> = [];
+  let stateChecks = 0;
+  let restoreChecks = 0;
+  const reconcileSource: ReceiveReconcileSource = {
+    listExecuting: async () => options.operations,
+    checkProofStates: async (op) => {
+      stateChecks++;
+      return (options.states ?? op.inputProofs.map(() => "SPENT")).map((state) => ({ state }));
+    },
+    restoreOutputs: async (_mintUrl, outputs) => {
+      restoreChecks++;
+      const restored = new Set(options.restored ?? []);
+      return outputs.filter((output) => restored.has(output.B_));
+    },
+    hasSavedOutputs: async (op) => (options.saved ?? []).includes(op.id),
+    rollBack: async (op, reason) => {
+      rolledBack.push({ id: op.id, reason });
+    },
+  };
+  return {
+    source: reconcileSource,
+    rolledBack,
+    stateChecks: () => stateChecks,
+    restoreChecks: () => restoreChecks,
+  };
+}
+
+describe("receive token hashing and reservation", () => {
+  it("hashes the exact encoded token deterministically", () => {
+    expect(hashReceiveToken("cashuA")).toBe(hashReceiveToken("cashuA"));
+    expect(hashReceiveToken("cashuA")).not.toBe(hashReceiveToken("cashuB"));
+  });
+
+  it("atomically reserves an exact token once", () => {
+    const database = new Database(":memory:");
+    initReceiveDedupSchema(database);
+    const first = reserveReceiveToken(database, "cashuA");
+    const second = reserveReceiveToken(database, "cashuA");
+    expect(first.acquired).toBe(true);
+    expect(second).toMatchObject({
+      acquired: false,
+      existing: { state: "processing", operationId: null },
+    });
+    database.close();
+  });
+
+  it("persists successful status and releases retryable reservations", () => {
+    const database = new Database(":memory:");
+    initReceiveDedupSchema(database);
+    const reservation = reserveReceiveToken(database, "cashuA");
+    updateReceiveToken(database, reservation.tokenHash, {
+      state: "succeeded",
+      operationId: "receive-1",
+    });
+    expect(reserveReceiveToken(database, "cashuA").existing).toMatchObject({
+      state: "succeeded",
+      operationId: "receive-1",
+    });
+    deleteReceiveTokenReservation(database, reservation.tokenHash);
+    expect(reserveReceiveToken(database, "cashuA").acquired).toBe(true);
+    database.close();
+  });
+
+  it("clears only interrupted reservations without Coco operation ids", () => {
+    const database = new Database(":memory:");
+    initReceiveDedupSchema(database);
+    const orphan = reserveReceiveToken(database, "orphan");
+    const linked = reserveReceiveToken(database, "linked");
+    updateReceiveToken(database, linked.tokenHash, {
+      state: "processing",
+      operationId: "receive-1",
+    });
+    expect(clearInterruptedReceiveReservations(database)).toBe(1);
+    expect(listProcessingReceiveTokens(database)).toEqual([
+      expect.objectContaining({ tokenHash: linked.tokenHash, operationId: "receive-1" }),
+    ]);
+    expect(reserveReceiveToken(database, "orphan").tokenHash).toBe(orphan.tokenHash);
+    database.close();
+  });
+});
+
+describe("legacy receive grouping", () => {
+  it("groups identical input proofs independent of operation id", () => {
+    const groups = groupExecutingReceives([
+      operation("one", "same", "B1"),
+      operation("two", "same", "B2"),
+      operation("three", "different", "B3"),
+    ]);
+    expect(groups.map((group) => group.map((op) => op.id))).toEqual([
+      ["one", "two"],
+      ["three"],
+    ]);
+  });
+
+  it("checks an unspent duplicate group once and retains one operation", async () => {
+    const mock = source({
+      operations: [operation("one", "same", "B1", 1), operation("two", "same", "B2", 2)],
+      states: ["UNSPENT"],
+    });
+    const result = await reconcileExecutingReceives(mock.source);
+    expect(mock.stateChecks()).toBe(1);
+    expect(mock.restoreChecks()).toBe(0);
+    expect(mock.rolledBack.map((entry) => entry.id)).toEqual(["two"]);
+    expect(result).toMatchObject({ rolledBack: 1, retained: 1, unresolved: 0 });
+  });
+
+  it("rolls back all spent duplicates when restore finds no outputs", async () => {
+    const mock = source({
+      operations: [operation("one", "same", "B1"), operation("two", "same", "B2")],
+      states: ["SPENT"],
+      restored: [],
+    });
+    const result = await reconcileExecutingReceives(mock.source);
+    expect(mock.stateChecks()).toBe(1);
+    expect(mock.restoreChecks()).toBe(1);
+    expect(mock.rolledBack.map((entry) => entry.id)).toEqual(["one", "two"]);
+    expect(result.rolledBack).toBe(2);
+  });
+
+  it("retains the operation whose output the mint can restore", async () => {
+    const mock = source({
+      operations: [operation("one", "same", "B1"), operation("two", "same", "B2")],
+      states: ["SPENT"],
+      restored: ["B2"],
+    });
+    const result = await reconcileExecutingReceives(mock.source);
+    expect(mock.rolledBack.map((entry) => entry.id)).toEqual(["one"]);
+    expect(result).toMatchObject({ rolledBack: 1, retained: 1 });
+  });
+
+  it("leaves a group untouched when the mint returns incomplete states", async () => {
+    const first = operation("one", "same", "B1");
+    first.inputProofs.push({ amount: 1, id: "keyset", secret: "other", C: "03" });
+    const second = operation("two", "same", "B2");
+    second.inputProofs.push({ amount: 1, id: "keyset", secret: "other", C: "03" });
+    const mock = source({
+      operations: [first, second],
+      states: ["SPENT"],
+    });
+    const result = await reconcileExecutingReceives(mock.source);
+    expect(mock.rolledBack).toEqual([]);
+    expect(mock.restoreChecks()).toBe(0);
+    expect(result.unresolved).toBe(2);
+  });
+
+  it("leaves a group untouched when proof states are mixed", async () => {
+    const first = operation("one", "same", "B1");
+    first.inputProofs.push({ amount: 1, id: "keyset", secret: "other", C: "03" });
+    const second = operation("two", "same", "B2");
+    second.inputProofs.push({ amount: 1, id: "keyset", secret: "other", C: "03" });
+    const mock = source({
+      operations: [first, second],
+      states: ["SPENT", "UNSPENT"],
+    });
+    const result = await reconcileExecutingReceives(mock.source);
+    expect(mock.rolledBack).toEqual([]);
+    expect(result.unresolved).toBe(2);
+  });
+
+  it("scales mint checks with unique input groups rather than row count", async () => {
+    const operations: ReceiveOperation[] = [];
+    for (let group = 0; group < 47; group++) {
+      const repeats = group < 44 ? 41 : 40; // 1,924 rows total
+      for (let index = 0; index < repeats; index++) {
+        operations.push(
+          operation(
+            `operation-${group}-${index}`,
+            `secret-${group}`,
+            `B-${group}-${index}`,
+            index,
+          ),
+        );
+      }
+    }
+    expect(operations).toHaveLength(1924);
+    const mock = source({ operations, states: ["SPENT"], restored: [] });
+    const result = await reconcileExecutingReceives(mock.source);
+    expect(mock.stateChecks()).toBe(47);
+    expect(mock.restoreChecks()).toBe(47);
+    expect(result).toMatchObject({
+      executing: 1924,
+      uniqueGroups: 47,
+      rolledBack: 1924,
+      unresolved: 0,
+    });
+  });
+});

package/src/daemon/wallet/receive-dedup.ts

@@ -0,0 +1,384 @@
+import { createHash } from "crypto";
+import type { ReceiveOperation } from "@cashu/coco-core";
+import type { Database } from "bun:sqlite";
+
+const TOKEN_TABLE = "routstrd_receive_tokens";
+const MAINTENANCE_TABLE = "routstrd_wallet_maintenance";
+const RECONCILE_BACKUP_KEY = "receive_reconcile_v1_backup";
+
+export type StoredReceiveTokenState = "processing" | "succeeded" | "failed";
+
+export interface StoredReceiveTokenRow {
+  tokenHash: string;
+  state: StoredReceiveTokenState;
+  operationId: string | null;
+  error: string | null;
+}
+
+export interface ReceiveTokenReservation {
+  acquired: boolean;
+  tokenHash: string;
+  existing?: StoredReceiveTokenRow;
+}
+
+export interface ReceiveReconcileResult {
+  executing: number;
+  uniqueGroups: number;
+  rolledBack: number;
+  retained: number;
+  unresolved: number;
+  recoveryOperationIds: string[];
+  backupPath?: string;
+}
+
+interface SerializedBlindedMessageLike {
+  amount: number;
+  id: string;
+  B_: string;
+}
+
+interface SerializedOutput {
+  blindedMessage: SerializedBlindedMessageLike;
+  secret: string;
+}
+
+interface SerializedOutputDataLike {
+  keep: SerializedOutput[];
+  send: SerializedOutput[];
+}
+
+type ExecutingReceive = Extract<ReceiveOperation, { state: "executing" }>;
+
+export interface ReceiveReconcileSource {
+  listExecuting(): Promise<ReceiveOperation[]>;
+  checkProofStates(operation: ExecutingReceive): Promise<Array<{ state: string }>>;
+  restoreOutputs(
+    mintUrl: string,
+    outputs: SerializedBlindedMessageLike[],
+  ): Promise<Array<{ B_: string }>>;
+  hasSavedOutputs(operation: ExecutingReceive): Promise<boolean>;
+  rollBack(operation: ExecutingReceive, reason: string): Promise<void>;
+}
+
+export function hashReceiveToken(token: string): string {
+  return createHash("sha256").update(token).digest("hex");
+}
+
+export function initReceiveDedupSchema(database: Database): void {
+  database.exec(`
+    CREATE TABLE IF NOT EXISTS ${TOKEN_TABLE} (
+      tokenHash TEXT PRIMARY KEY,
+      state TEXT NOT NULL CHECK (state IN ('processing', 'succeeded', 'failed')),
+      operationId TEXT,
+      error TEXT,
+      createdAt INTEGER NOT NULL,
+      updatedAt INTEGER NOT NULL
+    );
+    CREATE TABLE IF NOT EXISTS ${MAINTENANCE_TABLE} (
+      key TEXT PRIMARY KEY,
+      value TEXT NOT NULL,
+      updatedAt INTEGER NOT NULL
+    );
+  `);
+}
+
+export function listProcessingReceiveTokens(database: Database): StoredReceiveTokenRow[] {
+  return database
+    .query(
+      `SELECT tokenHash, state, operationId, error
+       FROM ${TOKEN_TABLE} WHERE state = 'processing'`,
+    )
+    .all() as StoredReceiveTokenRow[];
+}
+
+export function deleteReceiveTokenReservation(database: Database, tokenHash: string): void {
+  database.query(`DELETE FROM ${TOKEN_TABLE} WHERE tokenHash = ?`).run(tokenHash);
+}
+
+export function clearInterruptedReceiveReservations(database: Database): number {
+  const result = database
+    .query(
+      `DELETE FROM ${TOKEN_TABLE}
+       WHERE state = 'processing' AND operationId IS NULL`,
+    )
+    .run();
+  return result.changes;
+}
+
+export function reserveReceiveToken(database: Database, token: string): ReceiveTokenReservation {
+  const tokenHash = hashReceiveToken(token);
+  const now = Math.floor(Date.now() / 1000);
+  const result = database
+    .query(
+      `INSERT OR IGNORE INTO ${TOKEN_TABLE}
+       (tokenHash, state, operationId, error, createdAt, updatedAt)
+       VALUES (?, 'processing', NULL, NULL, ?, ?)`,
+    )
+    .run(tokenHash, now, now);
+
+  if (result.changes > 0) return { acquired: true, tokenHash };
+
+  const existing = database
+    .query(
+      `SELECT tokenHash, state, operationId, error
+       FROM ${TOKEN_TABLE} WHERE tokenHash = ?`,
+    )
+    .get(tokenHash) as StoredReceiveTokenRow | null;
+  return { acquired: false, tokenHash, ...(existing ? { existing } : {}) };
+}
+
+export function releaseReceiveToken(database: Database, tokenHash: string): void {
+  database
+    .query(`DELETE FROM ${TOKEN_TABLE} WHERE tokenHash = ? AND operationId IS NULL`)
+    .run(tokenHash);
+}
+
+export function updateReceiveToken(
+  database: Database,
+  tokenHash: string,
+  update: { state: StoredReceiveTokenState; operationId?: string; error?: string },
+): void {
+  database
+    .query(
+      `UPDATE ${TOKEN_TABLE}
+       SET state = ?, operationId = COALESCE(?, operationId), error = ?, updatedAt = ?
+       WHERE tokenHash = ?`,
+    )
+    .run(
+      update.state,
+      update.operationId ?? null,
+      update.error ?? null,
+      Math.floor(Date.now() / 1000),
+      tokenHash,
+    );
+}
+
+export function receiveInputFingerprint(operation: ReceiveOperation): string {
+  // Legacy cleanup is intentionally stricter than new-request token hashing:
+  // only operations with the exact same proof material are grouped. A shared
+  // secret alone is not enough evidence to discard an operation.
+  const proofs = operation.inputProofs
+    .map((proof) => ({
+      amount: proof.amount,
+      id: proof.id,
+      secret: proof.secret,
+      C: proof.C,
+      witness: proof.witness ?? null,
+    }))
+    .sort((left, right) =>
+      JSON.stringify(left).localeCompare(JSON.stringify(right)),
+    );
+  return createHash("sha256")
+    .update(JSON.stringify([operation.mintUrl, operation.unit, proofs]))
+    .digest("hex");
+}
+
+export function groupExecutingReceives(
+  operations: ReceiveOperation[],
+): ExecutingReceive[][] {
+  const groups = new Map<string, ExecutingReceive[]>();
+  for (const operation of operations) {
+    if (operation.state !== "executing") continue;
+    const key = receiveInputFingerprint(operation);
+    const group = groups.get(key) ?? [];
+    group.push(operation);
+    groups.set(key, group);
+  }
+  return [...groups.values()].map((group) =>
+    group.sort((left, right) => left.createdAt - right.createdAt || left.id.localeCompare(right.id)),
+  );
+}
+
+function outputData(operation: ExecutingReceive): SerializedOutputDataLike | null {
+  const value = operation.outputData as unknown;
+  if (!value || typeof value !== "object") return null;
+  const candidate = value as Partial<SerializedOutputDataLike>;
+  if (!Array.isArray(candidate.keep) || !Array.isArray(candidate.send)) return null;
+  return { keep: candidate.keep, send: candidate.send };
+}
+
+function outputBlindedMessages(operation: ExecutingReceive): SerializedBlindedMessageLike[] {
+  const data = outputData(operation);
+  if (!data) return [];
+  return [...data.keep, ...data.send]
+    .map((entry) => entry?.blindedMessage)
+    .filter((message): message is SerializedBlindedMessageLike =>
+      Boolean(
+        message &&
+          typeof message.B_ === "string" &&
+          message.B_ &&
+          typeof message.id === "string" &&
+          Number.isFinite(message.amount),
+      ),
+    );
+}
+
+async function rollBackOthers(
+  source: ReceiveReconcileSource,
+  group: ExecutingReceive[],
+  retainedIds: Set<string>,
+  reason: string,
+): Promise<number> {
+  let count = 0;
+  for (const operation of group) {
+    if (retainedIds.has(operation.id)) continue;
+    await source.rollBack(operation, reason);
+    count++;
+  }
+  return count;
+}
+
+/**
+ * Reduce legacy executing receives before coco-core's per-operation recovery.
+ *
+ * No state is changed unless the evidence is conclusive:
+ * - saved local outputs identify the successful operation;
+ * - all inputs are unspent, so one deterministic retry is sufficient; or
+ * - all inputs are spent and restore identifies an output owner (or confirms
+ *   that none of the stored deterministic outputs exist).
+ *
+ * Unreachable mints, malformed output data, partial restore ownership, and
+ * mixed proof states are left untouched for normal recovery/manual review.
+ */
+export async function reconcileExecutingReceives(
+  source: ReceiveReconcileSource,
+): Promise<ReceiveReconcileResult> {
+  const executing = (await source.listExecuting()).filter(
+    (operation): operation is ExecutingReceive => operation.state === "executing",
+  );
+  const groups = groupExecutingReceives(executing);
+  const result: ReceiveReconcileResult = {
+    executing: executing.length,
+    uniqueGroups: groups.length,
+    rolledBack: 0,
+    retained: 0,
+    unresolved: 0,
+    recoveryOperationIds: [],
+  };
+
+  for (const group of groups) {
+    try {
+      const savedOwners = new Set<string>();
+      for (const operation of group) {
+        if (await source.hasSavedOutputs(operation)) savedOwners.add(operation.id);
+      }
+      if (savedOwners.size > 0) {
+        result.rolledBack += await rollBackOthers(
+          source,
+          group,
+          savedOwners,
+          "Duplicate receive: outputs already persisted by another operation",
+        );
+        result.retained += savedOwners.size;
+        result.recoveryOperationIds.push(...savedOwners);
+        continue;
+      }
+
+      const states = await source.checkProofStates(group[0]!);
+      const completeStates = states.length === group[0]!.inputProofs.length;
+      const allUnspent = completeStates && states.every((state) => state.state === "UNSPENT");
+      const allSpent = completeStates && states.every((state) => state.state === "SPENT");
+
+      if (allUnspent) {
+        const canonical = group.find((operation) => outputBlindedMessages(operation).length > 0);
+        if (!canonical) {
+          result.unresolved += group.length;
+          continue;
+        }
+        result.rolledBack += await rollBackOthers(
+          source,
+          group,
+          new Set([canonical.id]),
+          "Duplicate receive: identical inputs retained by canonical operation",
+        );
+        result.retained++;
+        result.recoveryOperationIds.push(canonical.id);
+        continue;
+      }
+
+      if (!allSpent) {
+        result.unresolved += group.length;
+        continue;
+      }
+
+      const outputOwners = new Map<
+        string,
+        { message: SerializedBlindedMessageLike; owners: Set<string> }
+      >();
+      let malformed = false;
+      for (const operation of group) {
+        const outputs = outputBlindedMessages(operation);
+        if (outputs.length === 0) {
+          malformed = true;
+          continue;
+        }
+        for (const output of outputs) {
+          const entry = outputOwners.get(output.B_) ?? {
+            message: output,
+            owners: new Set<string>(),
+          };
+          entry.owners.add(operation.id);
+          outputOwners.set(output.B_, entry);
+        }
+      }
+      if (malformed || outputOwners.size === 0) {
+        result.unresolved += group.length;
+        continue;
+      }
+
+      const restored = await source.restoreOutputs(
+        group[0]!.mintUrl,
+        [...outputOwners.values()].map((entry) => entry.message),
+      );
+      const restoredOwners = new Set<string>();
+      for (const output of restored) {
+        for (const owner of outputOwners.get(output.B_)?.owners ?? []) {
+          restoredOwners.add(owner);
+        }
+      }
+
+      if (restoredOwners.size === 0) {
+        for (const operation of group) {
+          await source.rollBack(
+            operation,
+            "Recovered: input proofs spent without recoverable outputs",
+          );
+          result.rolledBack++;
+        }
+        continue;
+      }
+
+      result.rolledBack += await rollBackOthers(
+        source,
+        group,
+        restoredOwners,
+        "Duplicate receive: recoverable outputs belong to another operation",
+      );
+      result.retained += restoredOwners.size;
+      result.recoveryOperationIds.push(...restoredOwners);
+    } catch {
+      // A network, parsing, or persistence failure is not evidence that an
+      // operation is safe to abandon. Leave the complete group untouched.
+      result.unresolved += group.length;
+    }
+  }
+
+  return result;
+}
+
+export function getReceiveReconcileBackup(database: Database): string | null {
+  const row = database
+    .query(`SELECT value FROM ${MAINTENANCE_TABLE} WHERE key = ?`)
+    .get(RECONCILE_BACKUP_KEY) as { value: string } | null;
+  return row?.value ?? null;
+}
+
+export function setReceiveReconcileBackup(database: Database, path: string): void {
+  database
+    .query(
+      `INSERT INTO ${MAINTENANCE_TABLE} (key, value, updatedAt)
+       VALUES (?, ?, ?)
+       ON CONFLICT(key) DO UPDATE SET value = excluded.value, updatedAt = excluded.updatedAt`,
+    )
+    .run(RECONCILE_BACKUP_KEY, path, Math.floor(Date.now() / 1000));
+}

package/src/daemon/wallet/wallet-state.ts

@@ -0,0 +1,75 @@
+import { existsSync, readFileSync, statSync } from "fs";
+import { join } from "path";
+
+/**
+ * Pure wallet-migration state detection, shared by the actual migration and by
+ * the doctor diagnostics so the two cannot disagree about startup behavior.
+ */
+
+export type WalletState = "absent" | "database-only" | "initialized";
+
+export function walletState(configPath: string, dbPath: string): WalletState {
+  const hasConfig = existsSync(configPath);
+  const hasDb = existsSync(dbPath);
+  if (hasConfig) return "initialized";
+  if (hasDb) return "database-only";
+  return "absent";
+}
+
+export function filesEqual(left: string, right: string): boolean {
+  if (!existsSync(left) || !existsSync(right)) return false;
+  if (statSync(left).size !== statSync(right).size) return false;
+  return readFileSync(left).equals(readFileSync(right));
+}
+
+export type WalletMigrationClass =
+  | { kind: "fresh" }
+  | { kind: "already-current" }
+  | { kind: "migrate" }
+  | { kind: "conflict" }
+  | { kind: "database-only"; targetState: WalletState; sourceState: WalletState }
+  | { kind: "orphaned-sidecars" };
+
+/**
+ * Classify the two wallet locations exactly the way `migrateLegacyWallet`
+ * decides what to do. This is the single source of truth for startup behavior;
+ * `migrateLegacyWallet` maps it onto actions/errors and the doctor maps it onto
+ * verdict text.
+ */
+export function classifyWalletMigration(
+  targetDir: string,
+  sourceDir: string,
+): WalletMigrationClass {
+  const targetConfig = join(targetDir, "config.json");
+  const targetDb = join(targetDir, "coco.db");
+  const sourceConfig = join(sourceDir, "config.json");
+  const sourceDb = join(sourceDir, "coco.db");
+  const sourceWal = `${sourceDb}-wal`;
+  const sourceShm = `${sourceDb}-shm`;
+
+  const targetState = walletState(targetConfig, targetDb);
+  const sourceState = walletState(sourceConfig, sourceDb);
+
+  // config.json is sufficient for a newly initialized wallet; coco.db is
+  // created on first open. A database without its mnemonic is never usable.
+  if (targetState === "initialized" && sourceState === "initialized") {
+    // A prior migration may have committed successfully but failed to remove
+    // its source files. Identical leftovers are safe; divergent wallets are not.
+    const configsMatch = filesEqual(targetConfig, sourceConfig);
+    const databasesMatch =
+      !existsSync(targetDb) && !existsSync(sourceDb)
+        ? true
+        : filesEqual(targetDb, sourceDb);
+    if (configsMatch && databasesMatch) return { kind: "already-current" };
+    return { kind: "conflict" };
+  }
+  if (targetState === "initialized") return { kind: "already-current" };
+  if (!existsSync(sourceDb) && (existsSync(sourceWal) || existsSync(sourceShm))) {
+    return { kind: "orphaned-sidecars" };
+  }
+  if (targetState === "database-only" || sourceState === "database-only") {
+    return { kind: "database-only", targetState, sourceState };
+  }
+  if (sourceState === "absent") return { kind: "fresh" };
+  return { kind: "migrate" };
+}