resplite 1.0.2 → 1.0.6

package/src/cli/resplite-dirty-tracker.js

@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+/**
+ * resplite-dirty-tracker (SPEC_F §F.6): subscribe to Redis keyspace notifications, record dirty keys in SQLite.
+ * Usage: resplite-dirty-tracker start|stop [options]
+ */
+
+import { createClient } from 'redis';
+import { fileURLToPath } from 'node:url';
+import { openDb } from '../storage/sqlite/db.js';
+import { createRun, getRun, setRunStatus, upsertDirtyKey, logError, RUN_STATUS } from '../migration/registry.js';
+
+function parseArgs(argv = process.argv.slice(2)) {
+  const args = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--from' && argv[i + 1]) args.from = argv[++i];
+    else if (arg === '--to' && argv[i + 1]) args.to = argv[++i];
+    else if (arg === '--run-id' && argv[i + 1]) args.runId = argv[++i];
+    else if (arg === '--channels' && argv[i + 1]) args.channels = argv[++i];
+    else if (arg === '--pragma-template' && argv[i + 1]) args.pragmaTemplate = argv[++i];
+    else if (!arg.startsWith('--')) args._.push(arg);
+  }
+  return args;
+}
+
+async function checkKeyspaceNotifications(client) {
+  let val = null;
+  try {
+    const config = await client.configGet('notify-keyspace-events');
+    val = config && typeof config === 'object' ? config['notify-keyspace-events'] : null;
+  } catch (_) {}
+  if (!val || val === '') {
+    throw new Error('Redis notify-keyspace-events is not set. Enable it (e.g. CONFIG SET notify-keyspace-events Kgxe) for the dirty-key tracker.');
+  }
+  return val;
+}
+
+async function startTracker(args) {
+  const redisUrl = args.from || process.env.RESPLITE_IMPORT_FROM || 'redis://127.0.0.1:6379';
+  const dbPath = args.to;
+  const runId = args.runId || process.env.RESPLITE_RUN_ID;
+  if (!dbPath || !runId) {
+    console.error('Usage: resplite-dirty-tracker start --run-id <id> --to <db-path> [--from <redis-url>] [--channels keyevent]');
+    process.exit(1);
+  }
+
+  const db = openDb(dbPath, { pragmaTemplate: args.pragmaTemplate || 'default' });
+  createRun(db, runId, redisUrl);
+
+  const mainClient = createClient({ url: redisUrl });
+  mainClient.on('error', (e) => console.error('Redis (main):', e.message));
+  await mainClient.connect();
+  await checkKeyspaceNotifications(mainClient);
+
+  const subClient = mainClient.duplicate();
+  subClient.on('error', (e) => {
+    console.error('Redis (sub):', e.message);
+    logError(db, runId, 'dirty_apply', 'Tracker disconnect: ' + e.message, null);
+  });
+  await subClient.connect();
+
+  const pattern = '__keyevent@0__:*';
+  console.log('Subscribing to', pattern, '...');
+
+  await subClient.pSubscribe(pattern, (message, channel) => {
+    const event = typeof channel === 'string' ? channel.split(':').pop() : (channel && channel.toString?.())?.split(':').pop() || 'unknown';
+    const key = message;
+    try {
+      upsertDirtyKey(db, runId, key, event);
+    } catch (err) {
+      logError(db, runId, 'dirty_apply', err.message, key);
+    }
+  });
+
+  const shutdown = async () => {
+    console.log('Stopping dirty tracker...');
+    await subClient.pUnsubscribe(pattern);
+    await subClient.quit();
+    await mainClient.quit();
+    process.exit(0);
+  };
+
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
+  console.log('Dirty tracker running. Ctrl+C to stop.');
+}
+
+async function stopTracker(args) {
+  const dbPath = args.to;
+  const runId = args.runId || process.env.RESPLITE_RUN_ID;
+  if (!dbPath || !runId) {
+    console.error('Usage: resplite-dirty-tracker stop --run-id <id> --to <db-path>');
+    process.exit(1);
+  }
+  const db = openDb(dbPath, { pragmaTemplate: args.pragmaTemplate || 'default' });
+  const run = getRun(db, runId);
+  if (run && run.status === RUN_STATUS.RUNNING) {
+    setRunStatus(db, runId, RUN_STATUS.PAUSED);
+    console.log('Run', runId, 'status set to paused. Tracker process must be stopped with Ctrl+C if still running.');
+  } else {
+    console.log('Run', runId, 'status:', run?.status ?? 'not found');
+  }
+}
+
+async function main() {
+  const args = parseArgs();
+  const sub = args._[0];
+  if (sub === 'start') await startTracker(args);
+  else if (sub === 'stop') await stopTracker(args);
+  else {
+    console.error('Usage: resplite-dirty-tracker <start|stop> --run-id <id> --to <db-path> [--from <redis-url>]');
+    process.exit(1);
+  }
+}
+
+const isMain = process.argv[1] === fileURLToPath(import.meta.url) || process.argv[1]?.endsWith('resplite-dirty-tracker.js');
+if (isMain) {
+  main().catch((e) => {
+    console.error(e);
+    process.exit(1);
+  });
+}
+
+export { parseArgs, startTracker, stopTracker };

package/src/cli/resplite-import.js

@@ -0,0 +1,237 @@
+#!/usr/bin/env node
+/**
+ * resplite-import CLI (SPEC_F §F.9): preflight, bulk, status, apply-dirty, verify.
+ * Usage: resplite-import <preflight|bulk|status|apply-dirty|verify> [options]
+ */
+
+import { createClient } from 'redis';
+import { fileURLToPath } from 'node:url';
+import { openDb } from '../storage/sqlite/db.js';
+import { runPreflight } from '../migration/preflight.js';
+import { runBulkImport } from '../migration/bulk.js';
+import { runApplyDirty } from '../migration/apply-dirty.js';
+import { runVerify } from '../migration/verify.js';
+import { getRun, getDirtyCounts } from '../migration/registry.js';
+
+const SUBCOMMANDS = ['preflight', 'bulk', 'status', 'apply-dirty', 'verify'];
+
+function parseArgs(argv = process.argv.slice(2)) {
+  const args = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--from' && argv[i + 1]) {
+      args.from = argv[++i];
+    } else if (arg === '--to' && argv[i + 1]) {
+      args.to = argv[++i];
+    } else if (arg === '--run-id' && argv[i + 1]) {
+      args.runId = argv[++i];
+    } else if (arg === '--scan-count' && argv[i + 1]) {
+      args.scanCount = parseInt(argv[++i], 10);
+    } else if (arg === '--max-concurrency' && argv[i + 1]) {
+      args.maxConcurrency = parseInt(argv[++i], 10);
+    } else if (arg === '--max-rps' && argv[i + 1]) {
+      args.maxRps = parseInt(argv[++i], 10);
+    } else if (arg === '--batch-keys' && argv[i + 1]) {
+      args.batchKeys = parseInt(argv[++i], 10);
+    } else if (arg === '--batch-bytes' && argv[i + 1]) {
+      const v = argv[++i];
+      const match = v.match(/^(\d+)(MB|KB|GB)?$/i);
+      if (match) {
+        let n = parseInt(match[1], 10);
+        if (match[2]) {
+          if (match[2].toUpperCase() === 'KB') n *= 1024;
+          else if (match[2].toUpperCase() === 'MB') n *= 1024 * 1024;
+          else if (match[2].toUpperCase() === 'GB') n *= 1024 * 1024 * 1024;
+        }
+        args.batchBytes = n;
+      }
+    } else if (arg === '--resume') {
+      args.resume = true;
+    } else if (arg === '--pragma-template' && argv[i + 1]) {
+      args.pragmaTemplate = argv[++i];
+    } else if (arg === '--sample' && argv[i + 1]) {
+      args.sample = argv[++i];
+    } else if (arg.startsWith('--')) {
+      args[arg.slice(2).replace(/-/g, '')] = argv[i + 1] ?? true;
+      if (argv[i + 1] && !argv[i + 1].startsWith('--')) i++;
+    } else {
+      args._.push(arg);
+    }
+  }
+  return args;
+}
+
+function getRedisUrl(args) {
+  return args.from || process.env.RESPLITE_IMPORT_FROM || 'redis://127.0.0.1:6379';
+}
+
+function getDbPath(args) {
+  if (!args.to) {
+    console.error('Missing --to <db-path>');
+    process.exit(1);
+  }
+  return args.to;
+}
+
+function getRunId(args, required = false) {
+  const id = args.runId || process.env.RESPLITE_RUN_ID;
+  if (required && !id) {
+    console.error('Missing --run-id <id>');
+    process.exit(1);
+  }
+  return id;
+}
+
+async function cmdPreflight(args) {
+  const redisUrl = getRedisUrl(args);
+  const client = createClient({ url: redisUrl });
+  client.on('error', (e) => console.error('Redis:', e.message));
+  await client.connect();
+  try {
+    const result = await runPreflight(client);
+    console.log('Preflight:');
+    console.log('  Key count (estimate):', result.keyCountEstimate);
+    console.log('  Type distribution (sample):', result.typeDistribution);
+    console.log('  notify-keyspace-events:', result.notifyKeyspaceEvents ?? '(not set or not readable)');
+    if (!result.notifyKeyspaceEvents || result.notifyKeyspaceEvents === '') {
+      console.warn('  WARNING: Keyspace notifications disabled. Enable for dirty-key tracker (e.g. "Kgxe").');
+    }
+    console.log('  Recommended:');
+    console.log('    --scan-count', result.recommended.scan_count);
+    console.log('    --max-concurrency', result.recommended.max_concurrency);
+    console.log('    --max-rps', result.recommended.max_rps);
+  } finally {
+    await client.quit();
+  }
+}
+
+async function cmdBulk(args) {
+  const redisUrl = getRedisUrl(args);
+  const dbPath = getDbPath(args);
+  const runId = getRunId(args, true);
+  const client = createClient({ url: redisUrl });
+  client.on('error', (e) => console.error('Redis:', e.message));
+  await client.connect();
+  try {
+    const run = await runBulkImport(client, dbPath, runId, {
+      sourceUri: redisUrl,
+      pragmaTemplate: args.pragmaTemplate || 'default',
+      scan_count: args.scanCount || 1000,
+      max_rps: args.maxRps || 0,
+      batch_keys: args.batchKeys || 200,
+      batch_bytes: args.batchBytes || 64 * 1024 * 1024,
+      resume: !!args.resume,
+      onProgress: (r) => {
+        console.log(`  scanned=${r.scanned_keys} migrated=${r.migrated_keys} skipped=${r.skipped_keys} errors=${r.error_keys} cursor=${r.scan_cursor}`);
+      },
+    });
+    console.log('Bulk complete:', run);
+  } finally {
+    await client.quit();
+  }
+}
+
+async function cmdStatus(args) {
+  const dbPath = getDbPath(args);
+  const runId = getRunId(args, true);
+  const db = openDb(dbPath, { pragmaTemplate: args.pragmaTemplate || 'default' });
+  const run = getRun(db, runId);
+  if (!run) {
+    console.error('Run not found:', runId);
+    process.exit(1);
+  }
+  const dirty = getDirtyCounts(db, runId);
+  console.log('Run:', runId);
+  console.log('  status:', run.status);
+  console.log('  source:', run.source_uri);
+  console.log('  scan_cursor:', run.scan_cursor);
+  console.log('  scanned_keys:', run.scanned_keys, 'migrated_keys:', run.migrated_keys, 'skipped_keys:', run.skipped_keys, 'error_keys:', run.error_keys);
+  console.log('  migrated_bytes:', run.migrated_bytes);
+  console.log('  dirty_keys: seen=', run.dirty_keys_seen, 'applied=', run.dirty_keys_applied, 'deleted=', run.dirty_keys_deleted);
+  console.log('  dirty by state:', dirty);
+  if (run.last_error) console.log('  last_error:', run.last_error);
+}
+
+async function cmdApplyDirty(args) {
+  const redisUrl = getRedisUrl(args);
+  const dbPath = getDbPath(args);
+  const runId = getRunId(args, true);
+  const client = createClient({ url: redisUrl });
+  client.on('error', (e) => console.error('Redis:', e.message));
+  await client.connect();
+  try {
+    const run = await runApplyDirty(client, dbPath, runId, {
+      pragmaTemplate: args.pragmaTemplate || 'default',
+      batch_keys: args.batchKeys || 200,
+      max_rps: args.maxRps || 0,
+    });
+    console.log('Apply-dirty complete:', run);
+  } finally {
+    await client.quit();
+  }
+}
+
+async function cmdVerify(args) {
+  const redisUrl = getRedisUrl(args);
+  const dbPath = getDbPath(args);
+  const client = createClient({ url: redisUrl });
+  client.on('error', (e) => console.error('Redis:', e.message));
+  await client.connect();
+  try {
+    let samplePct = 0.5;
+    if (args.sample) {
+      const m = args.sample.match(/^(\d*\.?\d+)\s*%?$/);
+      if (m) samplePct = parseFloat(m[1]);
+    }
+    const result = await runVerify(client, dbPath, {
+      pragmaTemplate: args.pragmaTemplate || 'default',
+      samplePct,
+      maxSample: 10000,
+    });
+    console.log('Verify: sampled=', result.sampled, 'matched=', result.matched, 'mismatches=', result.mismatches.length);
+    if (result.mismatches.length) {
+      result.mismatches.slice(0, 20).forEach((m) => console.log('  ', m.key, m.reason));
+      if (result.mismatches.length > 20) console.log('  ... and', result.mismatches.length - 20, 'more');
+    }
+  } finally {
+    await client.quit();
+  }
+}
+
+async function main() {
+  const args = parseArgs();
+  const sub = args._[0];
+  if (!SUBCOMMANDS.includes(sub)) {
+    console.error('Usage: resplite-import <preflight|bulk|status|apply-dirty|verify> [options]');
+    console.error('  --from <redis-url>   (default: redis://127.0.0.1:6379)');
+    console.error('  --to <db-path>       (required for bulk, status, apply-dirty, verify)');
+    console.error('  --run-id <id>        (required for bulk, status, apply-dirty)');
+    console.error('  --scan-count N       (bulk, default 1000)');
+    console.error('  --max-rps N          (bulk, apply-dirty)');
+    console.error('  --batch-keys N       (default 200)');
+    console.error('  --batch-bytes N[MB|KB|GB] (default 64MB)');
+    console.error('  --resume             (bulk: resume from checkpoint)');
+    console.error('  --sample 0.5%        (verify, default 0.5%)');
+    process.exit(1);
+  }
+  try {
+    if (sub === 'preflight') await cmdPreflight(args);
+    else if (sub === 'bulk') await cmdBulk(args);
+    else if (sub === 'status') await cmdStatus(args);
+    else if (sub === 'apply-dirty') await cmdApplyDirty(args);
+    else if (sub === 'verify') await cmdVerify(args);
+  } catch (err) {
+    console.error(err);
+    process.exit(1);
+  }
+}
+
+const isMain = process.argv[1] === fileURLToPath(import.meta.url) || process.argv[1]?.endsWith('resplite-import.js');
+if (isMain) {
+  main().catch((e) => {
+    console.error(e);
+    process.exit(1);
+  });
+}
+
+export { parseArgs, cmdPreflight, cmdBulk, cmdStatus, cmdApplyDirty, cmdVerify };

package/src/commands/blpop.js

@@ -0,0 +1,50 @@
+/**
+ * BLPOP key [key ...] timeout
+ * Block until one of the keys has an element, or timeout (seconds). timeout 0 = block indefinitely.
+ * Returns [key, element] on success, nil on timeout.
+ */
+
+import { ERRORS } from '../engine/errors.js';
+
+function parseTimeout(arg) {
+  if (arg == null || arg === '') return null;
+  const s = Buffer.isBuffer(arg) ? arg.toString('utf8') : String(arg);
+  const n = parseInt(s, 10);
+  if (Number.isNaN(n) || s.trim() === '' || String(n) !== s.trim()) return null;
+  return n;
+}
+
+export function handleBlpop(engine, args, context) {
+  if (!args || args.length < 2) {
+    return { error: 'ERR wrong number of arguments for \'BLPOP\' command' };
+  }
+  const timeoutArg = args[args.length - 1];
+  const timeoutSeconds = parseTimeout(timeoutArg);
+  if (timeoutSeconds === null || timeoutSeconds < 0) {
+    return { error: 'ERR timeout is not an integer or out of range' };
+  }
+  const keys = args.slice(0, -1);
+
+  try {
+    for (const key of keys) {
+      const t = engine.type(key);
+      if (t !== 'none' && t !== 'list') {
+        return { error: ERRORS.WRONGTYPE };
+      }
+    }
+    for (const key of keys) {
+      const val = engine.lpop(key, null);
+      if (val != null) {
+        return [key, val];
+      }
+    }
+  } catch (e) {
+    const msg = e && e.message ? e.message : String(e);
+    return { error: msg.startsWith('ERR ') ? msg : msg.startsWith('WRONGTYPE') ? msg : 'ERR ' + msg };
+  }
+
+  if (!context) {
+    return { error: 'ERR blocking not supported in this context' };
+  }
+  return { block: { keys, kind: 'BLPOP', timeoutSeconds } };
+}

package/src/commands/brpop.js

@@ -0,0 +1,50 @@
+/**
+ * BRPOP key [key ...] timeout
+ * Block until one of the keys has an element (pop from right), or timeout (seconds). timeout 0 = block indefinitely.
+ * Returns [key, element] on success, nil on timeout.
+ */
+
+import { ERRORS } from '../engine/errors.js';
+
+function parseTimeout(arg) {
+  if (arg == null || arg === '') return null;
+  const s = Buffer.isBuffer(arg) ? arg.toString('utf8') : String(arg);
+  const n = parseInt(s, 10);
+  if (Number.isNaN(n) || s.trim() === '' || String(n) !== s.trim()) return null;
+  return n;
+}
+
+export function handleBrpop(engine, args, context) {
+  if (!args || args.length < 2) {
+    return { error: 'ERR wrong number of arguments for \'BRPOP\' command' };
+  }
+  const timeoutArg = args[args.length - 1];
+  const timeoutSeconds = parseTimeout(timeoutArg);
+  if (timeoutSeconds === null || timeoutSeconds < 0) {
+    return { error: 'ERR timeout is not an integer or out of range' };
+  }
+  const keys = args.slice(0, -1);
+
+  try {
+    for (const key of keys) {
+      const t = engine.type(key);
+      if (t !== 'none' && t !== 'list') {
+        return { error: ERRORS.WRONGTYPE };
+      }
+    }
+    for (const key of keys) {
+      const val = engine.rpop(key, null);
+      if (val != null) {
+        return [key, val];
+      }
+    }
+  } catch (e) {
+    const msg = e && e.message ? e.message : String(e);
+    return { error: msg.startsWith('ERR ') ? msg : msg.startsWith('WRONGTYPE') ? msg : 'ERR ' + msg };
+  }
+
+  if (!context) {
+    return { error: 'ERR blocking not supported in this context' };
+  }
+  return { block: { keys, kind: 'BRPOP', timeoutSeconds } };
+}

package/src/commands/registry.js

@@ -41,6 +41,8 @@ import * as lrange from './lrange.js';
 import * as lindex from './lindex.js';
 import * as lpop from './lpop.js';
 import * as rpop from './rpop.js';
+import * as blpop from './blpop.js';
+import * as brpop from './brpop.js';
 import * as scan from './scan.js';
 import * as zadd from './zadd.js';
 import * as zrem from './zrem.js';
@@ -97,8 +99,10 @@ const HANDLERS = new Map([
   ['LLEN', (e, a) => llen.handleLlen(e, a)],
   ['LRANGE', (e, a) => lrange.handleLrange(e, a)],
   ['LINDEX', (e, a) => lindex.handleLindex(e, a)],
-  ['LPOP', (e, a) => lpop.handleLpop(e, a)],
-  ['RPOP', (e, a) => rpop.handleRpop(e, a)],
+  ['LPOP', (e, a, ctx) => lpop.handleLpop(e, a)],
+  ['RPOP', (e, a, ctx) => rpop.handleRpop(e, a)],
+  ['BLPOP', (e, a, ctx) => blpop.handleBlpop(e, a, ctx)],
+  ['BRPOP', (e, a, ctx) => brpop.handleBrpop(e, a, ctx)],
   ['SCAN', (e, a) => scan.handleScan(e, a)],
   ['ZADD', (e, a) => zadd.handleZadd(e, a)],
   ['ZREM', (e, a) => zrem.handleZrem(e, a)],
@@ -123,9 +127,10 @@ const HANDLERS = new Map([
  * Dispatch command. Full argv: [commandNameBuf, ...argBuffers].
  * @param {object} engine
  * @param {Buffer[]} argv - first element is command name, rest are arguments
- * @returns {{ result: unknown } | { error: string } | { quit: true }}
+ * @param {object} [context] - optional connection context (connectionId, writeResponse) for blocking commands
+ * @returns {{ result: unknown } | { error: string } | { quit: true } | { block: object }}
  */
-export function dispatch(engine, argv) {
+export function dispatch(engine, argv, context) {
   if (!argv || argv.length === 0) {
     return { error: 'ERR wrong number of arguments' };
   }
@@ -136,9 +141,10 @@ export function dispatch(engine, argv) {
     return { error: unsupported() };
   }
   try {
-    const result = handler(engine, args);
+    const result = handler(engine, args, context);
     if (result && result.quit) return result;
     if (result && result.error) return result;
+    if (result && result.block) return result;
     return { result };
   } catch (err) {
     const msg = err && err.message ? err.message : String(err);

package/src/engine/engine.js

@@ -9,6 +9,7 @@ import { createHashesStorage } from '../storage/sqlite/hashes.js';
 import { createSetsStorage } from '../storage/sqlite/sets.js';
 import { createListsStorage } from '../storage/sqlite/lists.js';
 import { createZsetsStorage } from '../storage/sqlite/zsets.js';
+import { createBlockingManager } from '../blocking/manager.js';
 import { expectString, expectHash, expectSet, expectList, expectZset, typeName } from './validate.js';
 import { asKey, asValue } from '../util/buffers.js';
 
@@ -45,7 +46,7 @@ export function createEngine(opts = {}) {
     return meta;
   }
 
-  return {
+  const engine = {
     get(key) {
       const k = asKey(key);
       const meta = getKeyMeta(key);
@@ -262,14 +263,18 @@ export function createEngine(opts = {}) {
       const k = asKey(key);
       getKeyMeta(key);
       const buf = values.map((v) => (Buffer.isBuffer(v) ? v : asValue(v)));
-      return lists.lpush(k, buf);
+      const n = lists.lpush(k, buf);
+      if (this._blockingManager) this._blockingManager.wakeup(k);
+      return n;
     },
 
     rpush(key, ...values) {
       const k = asKey(key);
       getKeyMeta(key);
       const buf = values.map((v) => (Buffer.isBuffer(v) ? v : asValue(v)));
-      return lists.rpush(k, buf);
+      const n = lists.rpush(k, buf);
+      if (this._blockingManager) this._blockingManager.wakeup(k);
+      return n;
     },
 
     llen(key) {
@@ -398,7 +403,10 @@ export function createEngine(opts = {}) {
     _lists: lists,
     _zsets: zsets,
     _clock: clock,
+    _blockingManager: null,
   };
+  engine._blockingManager = createBlockingManager(engine, { clock });
+  return engine;
 }
 
 export { KEY_TYPES };

package/src/migration/apply-dirty.js

@@ -0,0 +1,97 @@
+/**
+ * Delta apply: reimport or delete keys from dirty registry (SPEC_F §F.8).
+ */
+
+import { openDb } from '../storage/sqlite/db.js';
+import { createKeysStorage } from '../storage/sqlite/keys.js';
+import { createStringsStorage } from '../storage/sqlite/strings.js';
+import { createHashesStorage } from '../storage/sqlite/hashes.js';
+import { createSetsStorage } from '../storage/sqlite/sets.js';
+import { createListsStorage } from '../storage/sqlite/lists.js';
+import { createZsetsStorage } from '../storage/sqlite/zsets.js';
+import { getRun, getDirtyBatch, markDirtyState, logError, RUN_STATUS } from './registry.js';
+import { importKeyFromRedis } from './import-one.js';
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Apply dirty keys: for each key in registry with state=dirty, reimport from Redis or delete in destination.
+ * @param {import('redis').RedisClientType} redisClient
+ * @param {string} dbPath
+ * @param {string} runId
+ * @param {object} options
+ * @param {string} [options.pragmaTemplate='default']
+ * @param {number} [options.batch_keys=200]
+ * @param {number} [options.max_rps=0]
+ */
+export async function runApplyDirty(redisClient, dbPath, runId, options = {}) {
+  const { pragmaTemplate = 'default', batch_keys = 200, max_rps = 0 } = options;
+
+  const db = openDb(dbPath, { pragmaTemplate });
+  const run = getRun(db, runId);
+  if (!run) throw new Error(`Run ${runId} not found`);
+
+  const keys = createKeysStorage(db);
+  const strings = createStringsStorage(db, keys);
+  const hashes = createHashesStorage(db, keys);
+  const sets = createSetsStorage(db, keys);
+  const lists = createListsStorage(db, keys);
+  const zsets = createZsetsStorage(db, keys);
+  const storages = { keys, strings, hashes, sets, lists, zsets };
+
+  const minIntervalMs = max_rps > 0 ? 1000 / max_rps : 0;
+  let lastKeyTime = 0;
+
+  for (;;) {
+    let r = getRun(db, runId);
+    if (r && r.status === RUN_STATUS.ABORTED) break;
+    while (r && r.status === RUN_STATUS.PAUSED) {
+      await sleep(2000);
+      r = getRun(db, runId);
+    }
+
+    const batch = getDirtyBatch(db, runId, 'dirty', batch_keys);
+    if (batch.length === 0) break;
+
+    for (const { key: keyBuf } of batch) {
+      r = getRun(db, runId);
+      if (r && r.status === RUN_STATUS.ABORTED) break;
+      while (r && r.status === RUN_STATUS.PAUSED) {
+        await sleep(2000);
+        r = getRun(db, runId);
+      }
+
+      if (minIntervalMs > 0) {
+        const elapsed = Date.now() - lastKeyTime;
+        if (elapsed < minIntervalMs) await sleep(minIntervalMs - elapsed);
+        lastKeyTime = Date.now();
+      }
+
+      const keyName = keyBuf.toString('utf8');
+      try {
+        const type = (await redisClient.type(keyName)).toLowerCase();
+        if (type === 'none' || !type) {
+          keys.delete(keyBuf);
+          markDirtyState(db, runId, keyBuf, 'deleted');
+        } else {
+          const outcome = await importKeyFromRedis(redisClient, keyName, storages, {});
+          if (outcome.ok) {
+            markDirtyState(db, runId, keyBuf, 'applied');
+          } else if (outcome.skipped) {
+            markDirtyState(db, runId, keyBuf, 'skipped');
+          } else {
+            logError(db, runId, 'dirty_apply', outcome.error ? 'Import failed' : 'Skipped', keyName);
+            markDirtyState(db, runId, keyBuf, 'error');
+          }
+        }
+      } catch (err) {
+        logError(db, runId, 'dirty_apply', err.message, keyBuf);
+        markDirtyState(db, runId, keyBuf, 'error');
+      }
+    }
+  }
+
+  return getRun(db, runId);
+}