resplite 1.3.2 → 1.3.4

package/README.md

@@ -107,6 +107,7 @@ const m = createMigration({
   batchKeys:      1000,
   batchBytes:     64 * 1024 * 1024,  // 64 MB
   maxRps:         0,                  // 0 = unlimited
+  redisCommandTimeoutMs: 30000,       // fail a stuck Redis command instead of waiting forever
 
   // If your Redis deployment renamed CONFIG for security:
   // configCommand: 'MYCONFIG',
@@ -189,10 +190,10 @@ await m.close();
 `resume` defaults to `true`. It doesn't matter whether it's the first run or a resume: the same script works for both starting and continuing. The first run starts from cursor 0; if the process is interrupted (Ctrl+C, crash, etc.), running the script again continues from the last checkpoint. You don't need to pass `resume: false` on the first run or change anything to resume.
 
 **Graceful shutdown**  
-On SIGINT (Ctrl+C) or SIGTERM, the bulk importer checkpoints progress, sets the run status to `aborted`, closes the SQLite database cleanly (so WAL is checkpointed and the file is not left open), then exits. You can safely interrupt a long-running bulk and resume later. The same applies to **apply-dirty**: Ctrl+C stops the delta apply, sets the run to `aborted`, and exits so you can inspect and retry.
+On SIGINT (Ctrl+C) or SIGTERM, the bulk importer checkpoints progress, sets the run status to `aborted`, closes the SQLite database cleanly (so WAL is checkpointed and the file is not left open), and tears down the Redis client so a stuck command does not trap the process forever. You can safely interrupt a long-running bulk and resume later. The same applies to **apply-dirty**: Ctrl+C stops the delta apply, sets the run to `aborted`, and exits so you can inspect and retry.
 
 **Errors and stalls**  
-Use `onProgress` to see progress and detect problems. The callback receives the run row (e.g. `scanned_keys`, `migrated_keys`, `dirty_keys_applied`, `last_error`). If progress stops for a long time (e.g. Redis hang or network issue), you may see `_stallWarning: true` and `_stallMessage` in the progress object every 15 seconds. When a key fails to import, the error is logged to `migration_errors` and the run’s `last_error` is set; the real error message is included so you can diagnose. After any failure, check `m.status()` and query `migration_errors` in the DB if needed.
+Use `onProgress` to see progress and detect problems. The callback receives the run row (e.g. `scanned_keys`, `migrated_keys`, `dirty_keys_applied`, `last_error`) plus transient fields like `_activeStage`, `_activeKey`, `_activeForMs`, `_stallWarning`, and `_stallMessage` when the importer is waiting on Redis. Each Redis command is also protected by `redisCommandTimeoutMs` (30s by default), so a dead connection or pathological key fails with the active stage/key in the error instead of silently hanging forever. When a key fails to import, the error is logged to `migration_errors` and the run’s `last_error` is set; the real error message is included so you can diagnose. After any failure, check `m.status()` and query `migration_errors` in the DB if needed.
 
 The JS API can run the dirty-key tracker in-process via `m.startDirtyTracker()` / `m.stopDirtyTracker()`, so the full flow stays inside a single script.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "resplite",
-  "version": "1.3.2",
+  "version": "1.3.4",
   "description": "A RESP2 server with practical Redis compatibility, backed by SQLite",
   "type": "module",
   "main": "src/index.js",

package/src/migration/apply-dirty.js

@@ -11,6 +11,7 @@ import { createListsStorage } from '../storage/sqlite/lists.js';
 import { createZsetsStorage } from '../storage/sqlite/zsets.js';
 import { getRun, getDirtyBatch, markDirtyState, logError, setRunStatus, updateBulkProgress, RUN_STATUS } from './registry.js';
 import { importKeyFromRedis } from './import-one.js';
+import { createRedisCommandGuard, isFatalRedisCommandError } from './redis-guard.js';
 
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
@@ -30,28 +31,69 @@ const STALL_WARNING_MS = 60000;
  * @param {string} [options.pragmaTemplate='default']
  * @param {number} [options.batch_keys=200]
  * @param {number} [options.max_rps=0]
+ * @param {number} [options.redis_command_timeout_ms=30000]
  * @param {(run: object) => void | Promise<void>} [options.onProgress] - Called after each batch and on heartbeat; may receive _stallWarning if no progress for 60s.
  */
 export async function runApplyDirty(redisClient, dbPath, runId, options = {}) {
-  const { pragmaTemplate = 'default', batch_keys = 200, max_rps = 0, onProgress } = options;
+  const { pragmaTemplate = 'default', batch_keys = 200, max_rps = 0, redis_command_timeout_ms = 30000, onProgress } = options;
 
   const db = openDb(dbPath, { pragmaTemplate });
+  const redisGuard = createRedisCommandGuard({
+    redisClient,
+    timeoutMs: redis_command_timeout_ms,
+  });
   let abortRequested = false;
   const onSignal = () => {
     abortRequested = true;
+    redisGuard.signalAbort('Apply dirty interrupted by signal (SIGINT/SIGTERM)', 'APPLY_DIRTY_ABORTED');
   };
   process.on('SIGINT', onSignal);
   process.on('SIGTERM', onSignal);
 
+  function enrichProgress(run) {
+    const active = redisGuard.snapshot();
+    if (!active) return run;
+
+    return {
+      ...run,
+      _activeStage: active.stage,
+      _activeKey: active.key,
+      _activeSince: active.startedAt,
+      _activeForMs: active.activeForMs,
+    };
+  }
+
+  function withStallContext(run) {
+    const active = redisGuard.snapshot();
+    let payload = enrichProgress(run);
+    if (run.updated_at && Date.now() - run.updated_at > STALL_WARNING_MS) {
+      const detail = active
+        ? ` Active operation: ${active.stage}${active.key ? ` key=${active.key}` : ''}.`
+        : '';
+      payload = {
+        ...payload,
+        _stallWarning: true,
+        _stallMessage: `No progress for 60s — possible hang or Redis timeout.${detail}`,
+      };
+    }
+    return payload;
+  }
+
+  let abortHandled = false;
+  function markAborted() {
+    if (abortHandled) return getRun(db, runId);
+    abortHandled = true;
+    setRunStatus(db, runId, RUN_STATUS.ABORTED);
+    updateBulkProgress(db, runId, { last_error: 'Interrupted by SIGINT/SIGTERM' });
+    return getRun(db, runId);
+  }
+
   let heartbeatTimer = null;
   if (onProgress) {
     heartbeatTimer = setInterval(() => {
       const run = getRun(db, runId);
       if (!run) return;
-      let payload = run;
-      if (run.updated_at && Date.now() - run.updated_at > STALL_WARNING_MS) {
-        payload = { ...run, _stallWarning: true, _stallMessage: 'No progress for 60s — possible hang or Redis timeout' };
-      }
+      const payload = withStallContext(run);
       Promise.resolve(onProgress(payload)).catch(() => {});
     }, HEARTBEAT_INTERVAL_MS);
   }
@@ -104,12 +146,18 @@ export async function runApplyDirty(redisClient, dbPath, runId, options = {}) {
 
       const keyName = keyBuf.toString('utf8');
       try {
-        const type = (await redisClient.type(keyName)).toLowerCase();
+        const type = (await redisGuard.run(
+          () => redisClient.type(keyName),
+          { stage: 'apply-dirty.type', key: keyName }
+        )).toLowerCase();
         if (type === 'none' || !type) {
           keys.delete(keyBuf);
           markDirtyState(db, runId, keyBuf, 'deleted');
         } else {
-          const outcome = await importKeyFromRedis(redisClient, keyName, storages, {});
+          const outcome = await importKeyFromRedis(redisClient, keyName, storages, {
+            redisGuard,
+            knownType: type,
+          });
           if (outcome.ok) {
             markDirtyState(db, runId, keyBuf, 'applied');
           } else if (outcome.skipped) {
@@ -120,6 +168,7 @@ export async function runApplyDirty(redisClient, dbPath, runId, options = {}) {
           }
         }
       } catch (err) {
+        if (isFatalRedisCommandError(err)) throw err;
         logError(db, runId, 'dirty_apply', err.message, keyBuf);
         markDirtyState(db, runId, keyBuf, 'error');
       }
@@ -156,15 +205,13 @@ export async function runApplyDirty(redisClient, dbPath, runId, options = {}) {
     }
     if (batchSize > 0 && onProgress) {
       const run = getRun(db, runId);
-      if (run) Promise.resolve(onProgress(run)).catch(() => {});
+      if (run) Promise.resolve(onProgress(enrichProgress(run))).catch(() => {});
     }
   }
 
   if (abortRequested) {
-    setRunStatus(db, runId, RUN_STATUS.ABORTED);
-    updateBulkProgress(db, runId, { last_error: 'Interrupted by SIGINT/SIGTERM' });
-    const run = getRun(db, runId);
-    if (onProgress && run) Promise.resolve(onProgress(run)).catch(() => {});
+    const run = markAborted();
+    if (onProgress && run) Promise.resolve(onProgress(enrichProgress(run))).catch(() => {});
     const err = new Error('Apply dirty interrupted by signal (SIGINT/SIGTERM)');
     err.code = 'APPLY_DIRTY_ABORTED';
     throw err;
@@ -172,7 +219,10 @@ export async function runApplyDirty(redisClient, dbPath, runId, options = {}) {
 
   return getRun(db, runId);
   } catch (err) {
-    if (err.code !== 'APPLY_DIRTY_ABORTED') {
+    if (err.code === 'APPLY_DIRTY_ABORTED') {
+      const run = markAborted();
+      if (onProgress && run) Promise.resolve(onProgress(enrichProgress(run))).catch(() => {});
+    } else {
       setRunStatus(db, runId, RUN_STATUS.FAILED);
       updateBulkProgress(db, runId, { last_error: err.message });
       logError(db, runId, 'dirty_apply', err.message, null);

package/src/migration/bulk.js

@@ -18,6 +18,7 @@ import {
   RUN_STATUS,
 } from './registry.js';
 import { importKeyFromRedis } from './import-one.js';
+import { createRedisCommandGuard } from './redis-guard.js';
 
 function parseScanResult(result) {
   if (Array.isArray(result)) {
@@ -54,6 +55,7 @@ const STALL_WARNING_MS = 60000;
  * @param {number} [options.batch_keys=200]
  * @param {number} [options.batch_bytes=64*1024*1024] - 64MB
  * @param {number} [options.checkpoint_interval_sec=30]
+ * @param {number} [options.redis_command_timeout_ms=30000]
  * @param {boolean} [options.resume=true] - true: start from 0 or continue from checkpoint; false: always start from 0
  * @param {function(run): void} [options.onProgress] - called after checkpoint and on heartbeat; may receive _stallWarning if no progress for 60s
  */
@@ -66,31 +68,86 @@ export async function runBulkImport(redisClient, dbPath, runId, options = {}) {
     batch_keys = 200,
     batch_bytes = 64 * 1024 * 1024,
     checkpoint_interval_sec = 30,
+    redis_command_timeout_ms = 30000,
     resume = true,
     onProgress,
   } = options;
 
   const db = openDb(dbPath, { pragmaTemplate });
+  const redisGuard = createRedisCommandGuard({
+    redisClient,
+    timeoutMs: redis_command_timeout_ms,
+  });
   let abortRequested = false;
   const onSignal = () => {
     abortRequested = true;
+    redisGuard.signalAbort('Bulk import interrupted by signal (SIGINT/SIGTERM)', 'BULK_ABORTED');
   };
   process.on('SIGINT', onSignal);
   process.on('SIGTERM', onSignal);
 
+  function enrichProgress(run) {
+    const active = redisGuard.snapshot();
+    if (!active) return run;
+
+    return {
+      ...run,
+      _activeStage: active.stage,
+      _activeKey: active.key,
+      _activeSince: active.startedAt,
+      _activeForMs: active.activeForMs,
+    };
+  }
+
+  function withStallContext(run) {
+    const active = redisGuard.snapshot();
+    let payload = enrichProgress(run);
+    if (run.updated_at && Date.now() - run.updated_at > STALL_WARNING_MS) {
+      const detail = active
+        ? ` Active operation: ${active.stage}${active.key ? ` key=${active.key}` : ''}.`
+        : '';
+      payload = {
+        ...payload,
+        _stallWarning: true,
+        _stallMessage: `No progress for 60s — possible hang or Redis timeout.${detail}`,
+      };
+    }
+    return payload;
+  }
+
   let heartbeatTimer = null;
   if (onProgress) {
     heartbeatTimer = setInterval(() => {
       const run = getRun(db, runId);
       if (!run) return;
-      let payload = run;
-      if (run.updated_at && Date.now() - run.updated_at > STALL_WARNING_MS) {
-        payload = { ...run, _stallWarning: true, _stallMessage: 'No progress for 60s — possible hang or Redis timeout' };
-      }
+      const payload = withStallContext(run);
       Promise.resolve(onProgress(payload)).catch(() => {});
     }, HEARTBEAT_INTERVAL_MS);
   }
 
+  let cursor = 0;
+  let scanned_keys = 0;
+  let migrated_keys = 0;
+  let skipped_keys = 0;
+  let error_keys = 0;
+  let migrated_bytes = 0;
+  let abortHandled = false;
+  function markAborted() {
+    if (abortHandled) return getRun(db, runId);
+    abortHandled = true;
+    updateBulkProgress(db, runId, {
+      scan_cursor: String(cursor),
+      scanned_keys,
+      migrated_keys,
+      skipped_keys,
+      error_keys,
+      migrated_bytes,
+      last_error: 'Interrupted by SIGINT/SIGTERM',
+    });
+    setRunStatus(db, runId, RUN_STATUS.ABORTED);
+    return getRun(db, runId);
+  }
+
   try {
     const keys = createKeysStorage(db);
     const strings = createStringsStorage(db, keys);
@@ -104,12 +161,12 @@ export async function runBulkImport(redisClient, dbPath, runId, options = {}) {
     let run = getRun(db, runId);
     if (!run) throw new Error(`Run ${runId} not found`);
 
-    let cursor = resume && run.scan_cursor !== undefined ? parseInt(String(run.scan_cursor), 10) : 0;
-    let scanned_keys = resume ? (run.scanned_keys || 0) : 0;
-    let migrated_keys = resume ? (run.migrated_keys || 0) : 0;
-    let skipped_keys = resume ? (run.skipped_keys || 0) : 0;
-    let error_keys = resume ? (run.error_keys || 0) : 0;
-    let migrated_bytes = resume ? (run.migrated_bytes || 0) : 0;
+    cursor = resume && run.scan_cursor !== undefined ? parseInt(String(run.scan_cursor), 10) : 0;
+    scanned_keys = resume ? (run.scanned_keys || 0) : 0;
+    migrated_keys = resume ? (run.migrated_keys || 0) : 0;
+    skipped_keys = resume ? (run.skipped_keys || 0) : 0;
+    error_keys = resume ? (run.error_keys || 0) : 0;
+    migrated_bytes = resume ? (run.migrated_bytes || 0) : 0;
 
     if (!resume) {
       updateBulkProgress(db, runId, { scan_cursor: String(cursor), scanned_keys, migrated_keys, skipped_keys, error_keys, migrated_bytes });
@@ -130,7 +187,10 @@ export async function runBulkImport(redisClient, dbPath, runId, options = {}) {
         run = getRun(db, runId);
       }
 
-      const result = await redisClient.scan(cursor, { COUNT: scan_count });
+      const result = await redisGuard.run(
+        () => redisClient.scan(cursor, { COUNT: scan_count }),
+        { stage: 'bulk.scan' }
+      );
       const parsed = parseScanResult(result);
       cursor = parsed.cursor;
       const keyList = parsed.keys || [];
@@ -152,7 +212,10 @@ export async function runBulkImport(redisClient, dbPath, runId, options = {}) {
         }
 
         const now = Date.now();
-        const outcome = await importKeyFromRedis(redisClient, keyName, storages, { now });
+        const outcome = await importKeyFromRedis(redisClient, keyName, storages, {
+          now,
+          redisGuard,
+        });
         if (outcome.ok) {
           migrated_keys++;
           migrated_bytes += outcome.bytes || 0;
@@ -183,7 +246,7 @@ export async function runBulkImport(redisClient, dbPath, runId, options = {}) {
           batchScanned = 0;
           batchBytes = 0;
           run = getRun(db, runId);
-          if (onProgress && run) onProgress(run);
+          if (onProgress && run) onProgress(enrichProgress(run));
         }
       }
     } while (cursor !== 0);
@@ -197,9 +260,8 @@ export async function runBulkImport(redisClient, dbPath, runId, options = {}) {
         error_keys,
         migrated_bytes,
       });
-      setRunStatus(db, runId, RUN_STATUS.ABORTED);
-      run = getRun(db, runId);
-      if (onProgress && run) onProgress(run);
+      run = markAborted();
+      if (onProgress && run) onProgress(enrichProgress(run));
       const err = new Error('Bulk import interrupted by signal (SIGINT/SIGTERM)');
       err.code = 'BULK_ABORTED';
       throw err;
@@ -216,7 +278,10 @@ export async function runBulkImport(redisClient, dbPath, runId, options = {}) {
     setRunStatus(db, runId, RUN_STATUS.COMPLETED);
     return getRun(db, runId);
   } catch (err) {
-    if (err.code !== 'BULK_ABORTED') {
+    if (err.code === 'BULK_ABORTED') {
+      const run = markAborted();
+      if (onProgress && run) onProgress(enrichProgress(run));
+    } else {
       setRunStatus(db, runId, RUN_STATUS.FAILED);
       updateBulkProgress(db, runId, { last_error: err.message });
       logError(db, runId, 'bulk', err.message, null);

package/src/migration/import-one.js

@@ -4,6 +4,7 @@
  */
 
 import { asKey, asValue } from '../util/buffers.js';
+import { isFatalRedisCommandError } from './redis-guard.js';
 
 const SUPPORTED_TYPES = new Set(['string', 'hash', 'set', 'list', 'zset']);
 
@@ -19,20 +20,27 @@ function toBuffer(value) {
  * @param {import('redis').RedisClientType} redisClient
  * @param {string} keyName
  * @param {{ keys: import('../storage/sqlite/keys.js').ReturnType<import('../storage/sqlite/keys.js').createKeysStorage>; strings: ReturnType<import('../storage/sqlite/strings.js').createStringsStorage>; hashes: ReturnType<import('../storage/sqlite/hashes.js').createHashesStorage>; sets: ReturnType<import('../storage/sqlite/sets.js').createSetsStorage>; lists: ReturnType<import('../storage/sqlite/lists.js').createListsStorage>; zsets: ReturnType<import('../storage/sqlite/zsets.js').createZsetsStorage> }} storages
- * @param {{ now?: number }} options
+ * @param {{ now?: number; knownType?: string; redisGuard?: { run(fn: Function, options: { stage: string, key?: string | null }): Promise<any> } }} options
  * @returns {Promise<{ ok: boolean; skipped?: boolean; error?: boolean; errorMessage?: string; bytes?: number }>}
  */
 export async function importKeyFromRedis(redisClient, keyName, storages, options = {}) {
   const now = options.now ?? Date.now();
+  const knownType = options.knownType ? String(options.knownType).toLowerCase() : null;
+  const redisGuard = options.redisGuard ?? null;
   const { keys, strings, hashes, sets, lists, zsets } = storages;
+  const runRedis = (stage, fn) => (
+    redisGuard
+      ? redisGuard.run(fn, { stage, key: keyName })
+      : Promise.resolve().then(fn)
+  );
 
   try {
-    const type = (await redisClient.type(keyName)).toLowerCase();
+    const type = knownType || (await runRedis('import.type', () => redisClient.type(keyName))).toLowerCase();
     if (!SUPPORTED_TYPES.has(type)) {
       return { ok: false, skipped: true };
     }
 
-    let pttl = await redisClient.pTTL(keyName);
+    let pttl = await runRedis('import.pttl', () => redisClient.pTTL(keyName));
     if (pttl === -2) pttl = -1;
     const expiresAt = pttl > 0 ? now + pttl : null;
     const keyBuf = asKey(keyName);
@@ -40,7 +48,7 @@ export async function importKeyFromRedis(redisClient, keyName, storages, options
     let bytes = keyBuf.length;
 
     if (type === 'string') {
-      const value = await redisClient.get(keyName);
+      const value = await runRedis('import.string.get', () => redisClient.get(keyName));
       if (value === undefined || value === null) return { ok: false, skipped: true };
       const valBuf = asValue(value);
       bytes += valBuf.length;
@@ -49,7 +57,7 @@ export async function importKeyFromRedis(redisClient, keyName, storages, options
     }
 
     if (type === 'hash') {
-      const obj = await redisClient.hGetAll(keyName);
+      const obj = await runRedis('import.hash.hGetAll', () => redisClient.hGetAll(keyName));
       if (!obj || typeof obj !== 'object') return { ok: false, skipped: true };
       const pairs = [];
       for (const [f, v] of Object.entries(obj)) {
@@ -65,7 +73,7 @@ export async function importKeyFromRedis(redisClient, keyName, storages, options
     }
 
     if (type === 'set') {
-      const members = await redisClient.sMembers(keyName);
+      const members = await runRedis('import.set.sMembers', () => redisClient.sMembers(keyName));
       if (!members || !members.length) return { ok: false, skipped: true };
       const memberBuffers = members.map((m) => toBuffer(m));
       for (const b of memberBuffers) bytes += b.length;
@@ -75,7 +83,7 @@ export async function importKeyFromRedis(redisClient, keyName, storages, options
     }
 
     if (type === 'list') {
-      const elements = await redisClient.lRange(keyName, 0, -1);
+      const elements = await runRedis('import.list.lRange', () => redisClient.lRange(keyName, 0, -1));
       if (!elements || !elements.length) return { ok: false, skipped: true };
       const valueBuffers = elements.map((e) => toBuffer(e));
       for (const b of valueBuffers) bytes += b.length;
@@ -85,7 +93,7 @@ export async function importKeyFromRedis(redisClient, keyName, storages, options
     }
 
     if (type === 'zset') {
-      const withScores = await redisClient.zRangeWithScores(keyName, 0, -1);
+      const withScores = await runRedis('import.zset.zRangeWithScores', () => redisClient.zRangeWithScores(keyName, 0, -1));
       if (!withScores || !withScores.length) return { ok: false, skipped: true };
       const pairs = withScores.map((item) => ({
         member: toBuffer(item.value),
@@ -99,6 +107,7 @@ export async function importKeyFromRedis(redisClient, keyName, storages, options
 
     return { ok: false, skipped: true };
   } catch (err) {
+    if (isFatalRedisCommandError(err)) throw err;
     return { ok: false, error: true, errorMessage: err.message };
   }
 }

package/src/migration/index.js

@@ -38,6 +38,7 @@ import { startDirtyTracker as startDirtyTrackerProcess } from './tracker.js';
  * @property {number} [maxRps=0]                      - Max requests/s (0 = unlimited).
  * @property {number} [batchKeys=200]
  * @property {number} [batchBytes=67108864]           - 64 MB default.
+ * @property {number} [redisCommandTimeoutMs=30000]   - Fail a stuck Redis command instead of waiting forever.
  * @property {string} [configCommand='CONFIG']        - Redis CONFIG command name. Override if renamed for security.
  */
 
@@ -67,6 +68,7 @@ export function createMigration({
   maxRps = 0,
   batchKeys = 200,
   batchBytes = 64 * 1024 * 1024,
+  redisCommandTimeoutMs = 30000,
   configCommand = 'CONFIG',
 } = {}) {
   if (!to) throw new Error('createMigration: "to" (db path) is required');
@@ -168,6 +170,7 @@ export function createMigration({
         max_rps: maxRps,
         batch_keys: batchKeys,
         batch_bytes: batchBytes,
+        redis_command_timeout_ms: redisCommandTimeoutMs,
         resume,
         onProgress,
       });
@@ -200,6 +203,7 @@ export function createMigration({
         pragmaTemplate,
         batch_keys: bk,
         max_rps: rps,
+        redis_command_timeout_ms: redisCommandTimeoutMs,
         onProgress,
       });
     },

package/src/migration/redis-guard.js

@@ -0,0 +1,174 @@
+/**
+ * Guard Redis migration commands with timeouts and abort-aware progress context.
+ */
+
+const FATAL_CODES = new Set([
+  'REDIS_COMMAND_TIMEOUT',
+  'BULK_ABORTED',
+  'APPLY_DIRTY_ABORTED',
+  'MIGRATION_ABORTED',
+]);
+
+function normalizeKey(key) {
+  if (key == null) return null;
+  if (Buffer.isBuffer(key)) return key.toString('utf8');
+  return String(key);
+}
+
+function attachContext(err, snapshot) {
+  if (!snapshot || !err || typeof err !== 'object') return err;
+  if (!('migrationStage' in err)) err.migrationStage = snapshot.stage;
+  if (!('migrationKey' in err)) err.migrationKey = snapshot.key;
+  if (!('migrationActiveSince' in err)) err.migrationActiveSince = snapshot.startedAt;
+  return err;
+}
+
+function formatContext(message, snapshot) {
+  if (!snapshot) return message;
+  const parts = [message, `during ${snapshot.stage}`];
+  if (snapshot.key) parts.push(`for key "${snapshot.key}"`);
+  return parts.join(' ');
+}
+
+function abortRedisTransport(redisClient) {
+  if (!redisClient) return;
+
+  for (const methodName of ['disconnect', 'destroy']) {
+    if (typeof redisClient[methodName] !== 'function') continue;
+    try {
+      const result = redisClient[methodName]();
+      if (result && typeof result.catch === 'function') {
+        result.catch(() => {});
+      }
+    } catch (_) {
+      // Best effort: we're already aborting because the client is unhealthy.
+    }
+    return;
+  }
+}
+
+export function isFatalRedisCommandError(err) {
+  return !!(err && typeof err === 'object' && FATAL_CODES.has(err.code));
+}
+
+export function createRedisCommandGuard({ redisClient, timeoutMs = 30000 } = {}) {
+  const abortListeners = new Set();
+  let active = null;
+  let terminalError = null;
+  let transportAborted = false;
+
+  function snapshot() {
+    if (!active) return null;
+    return {
+      stage: active.stage,
+      key: active.key,
+      startedAt: active.startedAt,
+      activeForMs: Date.now() - active.startedAt,
+    };
+  }
+
+  function notifyAbort(err) {
+    for (const listener of abortListeners) {
+      try {
+        listener(err);
+      } catch (_) {
+        // Ignore listener failures while aborting.
+      }
+    }
+  }
+
+  function abortTransport() {
+    if (transportAborted) return;
+    transportAborted = true;
+    abortRedisTransport(redisClient);
+  }
+
+  function signalAbort(message, code = 'MIGRATION_ABORTED') {
+    if (terminalError) return terminalError;
+    const current = snapshot();
+    const err = attachContext(new Error(formatContext(message, current)), current);
+    err.code = code;
+    terminalError = err;
+    abortTransport();
+    notifyAbort(err);
+    return err;
+  }
+
+  async function run(fn, { stage, key = null, timeoutMs: overrideTimeoutMs } = {}) {
+    if (terminalError) throw terminalError;
+
+    const opTimeoutMs = overrideTimeoutMs ?? timeoutMs;
+    const opKey = normalizeKey(key);
+    const opState = {
+      stage,
+      key: opKey,
+      startedAt: Date.now(),
+    };
+    active = opState;
+
+    return await new Promise((resolve, reject) => {
+      let settled = false;
+      let timeoutId = null;
+
+      const cleanup = () => {
+        abortListeners.delete(onAbort);
+        if (timeoutId) clearTimeout(timeoutId);
+        if (active === opState) active = null;
+      };
+
+      const finishResolve = (value) => {
+        if (settled) return;
+        settled = true;
+        cleanup();
+        resolve(value);
+      };
+
+      const finishReject = (err) => {
+        if (settled) return;
+        settled = true;
+        cleanup();
+        reject(err);
+      };
+
+      const onAbort = (err) => {
+        finishReject(err);
+      };
+
+      abortListeners.add(onAbort);
+
+      if (Number.isFinite(opTimeoutMs) && opTimeoutMs > 0) {
+        timeoutId = setTimeout(() => {
+          const current = snapshot() ?? {
+            stage,
+            key: opKey,
+            startedAt: opState.startedAt,
+            activeForMs: Date.now() - opState.startedAt,
+          };
+          const err = attachContext(
+            new Error(formatContext(`Redis command timed out after ${opTimeoutMs}ms`, current)),
+            current
+          );
+          err.code = 'REDIS_COMMAND_TIMEOUT';
+          terminalError = err;
+          abortTransport();
+          notifyAbort(err);
+          finishReject(err);
+        }, opTimeoutMs);
+      }
+
+      Promise.resolve()
+        .then(fn)
+        .then(
+          (value) => finishResolve(value),
+          (err) => finishReject(attachContext(err, snapshot() ?? opState))
+        );
+    });
+  }
+
+  return {
+    run,
+    snapshot,
+    signalAbort,
+    abortTransport,
+  };
+}

package/test/unit/migration-timeouts.test.js

@@ -0,0 +1,122 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { runBulkImport } from '../../src/migration/bulk.js';
+import { runApplyDirty } from '../../src/migration/apply-dirty.js';
+import { createRedisCommandGuard } from '../../src/migration/redis-guard.js';
+import { openDb } from '../../src/storage/sqlite/db.js';
+import { createRun, getRun, upsertDirtyKey } from '../../src/migration/registry.js';
+import { tmpDbPath } from '../helpers/tmp.js';
+
+function never() {
+  return new Promise(() => {});
+}
+
+describe('migration Redis timeouts', () => {
+  it('runBulkImport fails a stuck scan with timeout context', async () => {
+    const dbPath = tmpDbPath();
+    let disconnectCalls = 0;
+    const redisClient = {
+      scan: () => never(),
+      disconnect() {
+        disconnectCalls += 1;
+      },
+    };
+
+    await assert.rejects(
+      () => runBulkImport(redisClient, dbPath, 'bulk-timeout', {
+        sourceUri: 'redis://example.test:6379',
+        pragmaTemplate: 'minimal',
+        redis_command_timeout_ms: 20,
+      }),
+      (err) => {
+        assert.equal(err.code, 'REDIS_COMMAND_TIMEOUT');
+        assert.match(err.message, /bulk\.scan/);
+        return true;
+      }
+    );
+
+    const db = openDb(dbPath, { pragmaTemplate: 'minimal' });
+    try {
+      const run = getRun(db, 'bulk-timeout');
+      assert.equal(run.status, 'failed');
+      assert.match(run.last_error, /bulk\.scan/);
+    } finally {
+      db.close();
+    }
+
+    assert.equal(disconnectCalls, 1);
+  });
+
+  it('runApplyDirty fails a stuck key lookup with key context', async () => {
+    const dbPath = tmpDbPath();
+    const db = openDb(dbPath, { pragmaTemplate: 'minimal' });
+    try {
+      createRun(db, 'apply-timeout', 'redis://example.test:6379');
+      upsertDirtyKey(db, 'apply-timeout', 'stuck:key', 'set');
+    } finally {
+      db.close();
+    }
+
+    let disconnectCalls = 0;
+    const redisClient = {
+      type: () => never(),
+      disconnect() {
+        disconnectCalls += 1;
+      },
+    };
+
+    await assert.rejects(
+      () => runApplyDirty(redisClient, dbPath, 'apply-timeout', {
+        pragmaTemplate: 'minimal',
+        redis_command_timeout_ms: 20,
+      }),
+      (err) => {
+        assert.equal(err.code, 'REDIS_COMMAND_TIMEOUT');
+        assert.match(err.message, /apply-dirty\.type/);
+        assert.match(err.message, /stuck:key/);
+        return true;
+      }
+    );
+
+    const verifyDb = openDb(dbPath, { pragmaTemplate: 'minimal' });
+    try {
+      const run = getRun(verifyDb, 'apply-timeout');
+      assert.equal(run.status, 'failed');
+      assert.match(run.last_error, /apply-dirty\.type/);
+      const row = verifyDb.prepare('SELECT message FROM migration_errors WHERE run_id = ? ORDER BY rowid DESC LIMIT 1').get('apply-timeout');
+      assert.match(row.message, /stuck:key/);
+    } finally {
+      verifyDb.close();
+    }
+
+    assert.equal(disconnectCalls, 1);
+  });
+
+  it('redis guard aborts a pending command immediately', async () => {
+    let disconnectCalls = 0;
+    const guard = createRedisCommandGuard({
+      redisClient: {
+        disconnect() {
+          disconnectCalls += 1;
+        },
+      },
+      timeoutMs: 1000,
+    });
+
+    const pending = guard.run(() => never(), { stage: 'bulk.scan' });
+    queueMicrotask(() => {
+      guard.signalAbort('Bulk import interrupted by signal (SIGINT/SIGTERM)', 'BULK_ABORTED');
+    });
+
+    await assert.rejects(
+      () => pending,
+      (err) => {
+        assert.equal(err.code, 'BULK_ABORTED');
+        assert.match(err.message, /bulk\.scan/);
+        return true;
+      }
+    );
+
+    assert.equal(disconnectCalls, 1);
+  });
+});