resplite 1.0.4 → 1.1.2

package/README.md

@@ -35,6 +35,24 @@ OK
 "bar"
 ```
 
+### Standalone server script (fixed port)
+
+Run this as a persistent background process (`node server.js`). RESPLite will listen on port 6380 and stay up until the process is killed.
+
+```javascript
+// server.js
+import { createRESPlite } from 'resplite/embed';
+
+const srv = await createRESPlite({ port: 6380, db: './data.db' });
+console.log(`RESPLite listening on ${srv.host}:${srv.port}`);
+```
+
+Then connect from any other script or process:
+
+```bash
+redis-cli -p 6380 PING
+```
+
 ### Environment variables
 
 | Variable | Default | Description |
@@ -296,9 +314,45 @@ npm run import-from-redis -- --db ./migrated.db --host 127.0.0.1 --port 6379
 npm run import-from-redis -- --db ./migrated.db --pragma-template performance
 ```
 
+### Redis with authentication
+
+Migration supports Redis instances protected by a password. Use a Redis URL that includes the password (or username and password for Redis 6+ ACL):
+
+- **Password only:** `redis://:PASSWORD@host:port`
+- **Username and password:** `redis://username:PASSWORD@host:port`
+
+Examples:
+
+```bash
+# One-shot import from authenticated Redis
+npm run import-from-redis -- --db ./migrated.db --redis-url "redis://:mysecret@127.0.0.1:6379"
+
+# SPEC_F flow: use --from with the full URL (or set RESPLITE_IMPORT_FROM)
+npx resplite-import preflight --from "redis://:mysecret@10.0.0.10:6379" --to ./resplite.db
+npx resplite-dirty-tracker start --run-id run_001 --from "redis://:mysecret@10.0.0.10:6379" --to ./resplite.db
+```
+
+For one-shot import, authentication is only available when using `--redis-url`; the `--host` / `--port` options do not support a password.
+
 ### Minimal-downtime migration (SPEC_F)
 
-For large datasets (~30 GB), use the Dirty Key Registry flow so the bulk of the migration runs online and only a short cutover is needed:
+For large datasets (~30 GB), use the Dirty Key Registry flow so the bulk of the migration runs online and only a short cutover is needed.
+
+**Enable keyspace notifications in Redis** (required for the dirty-key tracker). Either run at runtime:
+
+```bash
+redis-cli CONFIG SET notify-keyspace-events KEA
+```
+
+Or add to `redis.conf` and restart Redis:
+
+```
+notify-keyspace-events KEA
+```
+
+(`K` = keyspace prefix, `E` = keyevent prefix, `A` = all event types — lets the tracker see every key change and expiration.)
+
+> **Renamed CONFIG command?** Some Redis deployments rename `CONFIG` for security. Pass `--config-command <name>` to the CLI tools, or the `configCommand` option to the JS API — see below.
 
 1. **Preflight** – Check Redis, key count, type distribution, and that keyspace notifications are enabled:
    ```bash
@@ -308,6 +362,8 @@ For large datasets (~30 GB), use the Dirty Key Registry flow so the bulk of the
 2. **Start dirty-key tracker** – Captures keys modified during bulk (requires `notify-keyspace-events` in Redis):
    ```bash
    npx resplite-dirty-tracker start --run-id run_001 --from redis://10.0.0.10:6379 --to ./resplite.db
+   # If CONFIG was renamed:
+   npx resplite-dirty-tracker start --run-id run_001 --from redis://10.0.0.10:6379 --to ./resplite.db --config-command MYCONFIG
    ```
 
 3. **Bulk import** – SCAN and copy all keys; progress is checkpointed and resumable:
@@ -338,6 +394,106 @@ For large datasets (~30 GB), use the Dirty Key Registry flow so the bulk of the
 
 Then start RespLite with the migrated DB: `RESPLITE_DB=./resplite.db npm start`.
 
+### Programmatic migration API
+
+As an alternative to the CLI, the full migration flow is available as a JavaScript API via `resplite/migration`. Useful for embedding the migration inside your own scripts or automation pipelines.
+
+```javascript
+import { createMigration } from 'resplite/migration';
+
+const m = createMigration({
+  from:  'redis://127.0.0.1:6379',  // source Redis URL (default)
+  to:    './resplite.db',           // destination SQLite DB path (required)
+  runId: 'my-migration-1',          // unique run ID (required for bulk/status/applyDirty)
+
+  // optional — same defaults as the CLI:
+  scanCount:      1000,
+  batchKeys:      200,
+  batchBytes:     64 * 1024 * 1024,  // 64 MB
+  maxRps:         0,                  // 0 = unlimited
+  pragmaTemplate: 'default',
+
+  // If your Redis deployment renamed CONFIG for security:
+  // configCommand: 'MYCONFIG',
+});
+
+// Step 0 — Preflight: inspect Redis before starting
+const info = await m.preflight();
+console.log('keys (estimate):', info.keyCountEstimate);
+console.log('type distribution:', info.typeDistribution);
+console.log('notify-keyspace-events:', info.notifyKeyspaceEvents);
+console.log('CONFIG available:', info.configCommandAvailable);  // false if renamed
+console.log('recommended params:', info.recommended);
+
+// Step 0b — Enable keyspace notifications (required for dirty-key tracking)
+// Reads the current value and merges the new flags — existing flags are preserved.
+const ks = await m.enableKeyspaceNotifications();
+// → { ok: true, previous: '', applied: 'KEA' }
+// If CONFIG is renamed and configCommand was not set, ok=false and error explains how to fix it.
+
+// Step 1 — Bulk import (checkpointed, resumable)
+await m.bulk({
+  resume: false,                            // true to resume a previous run
+  onProgress: (r) => console.log(
+    `scanned=${r.scanned_keys} migrated=${r.migrated_keys} errors=${r.error_keys}`
+  ),
+});
+
+// Check status at any point (synchronous, no Redis needed)
+const { run, dirty } = m.status();
+console.log('bulk status:', run.status, '— dirty counts:', dirty);
+
+// Step 2 — Apply dirty keys that changed in Redis during bulk
+await m.applyDirty();
+
+// Step 3 — Verify a sample of keys match between Redis and the destination
+const result = await m.verify({ samplePct: 0.5, maxSample: 10000 });
+console.log(`verified ${result.sampled} keys — mismatches: ${result.mismatches.length}`);
+
+// Disconnect Redis when done
+await m.close();
+```
+
+The dirty-key tracker (to capture writes during bulk) still runs as a separate process via `npx resplite-dirty-tracker`. The API above handles everything else in a single script.
+
+#### Renamed CONFIG command
+
+If your Redis instance has the `CONFIG` command renamed (a common hardening practice), pass the new name to `createMigration`:
+
+```javascript
+const m = createMigration({
+  from: 'redis://10.0.0.10:6379',
+  to:   './resplite.db',
+  runId: 'run_001',
+  configCommand: 'MYCONFIG',  // the renamed command
+});
+
+// preflight will use MYCONFIG GET notify-keyspace-events
+const info = await m.preflight();
+// info.configCommandAvailable → false if the name is wrong
+
+// enableKeyspaceNotifications will use MYCONFIG SET notify-keyspace-events KEA
+const result = await m.enableKeyspaceNotifications({ value: 'KEA' });
+```
+
+The same flag is available in the CLI:
+
+```bash
+npx resplite-dirty-tracker start --run-id run_001 --to ./resplite.db \
+  --from redis://10.0.0.10:6379 --config-command MYCONFIG
+```
+
+#### Low-level re-exports
+
+If you need more control, the individual functions and registry helpers are also exported:
+
+```javascript
+import {
+  runPreflight, runBulkImport, runApplyDirty, runVerify,
+  getRun, getDirtyCounts, createRun, setRunStatus, logError,
+} from 'resplite/migration';
+```
+
 ## Benchmark (Redis vs RESPLite)
 
 Compare throughput of local Redis and RESPLite with the same workload (PING, SET/GET, hashes, sets, lists, zsets, etc.):

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "resplite",
-  "version": "1.0.4",
+  "version": "1.1.2",
   "description": "A RESP2 server with practical Redis compatibility, backed by SQLite",
   "type": "module",
   "main": "src/index.js",
@@ -10,7 +10,8 @@
   },
   "exports": {
     ".": "./src/index.js",
-    "./embed": "./src/embed.js"
+    "./embed": "./src/embed.js",
+    "./migration": "./src/migration/index.js"
   },
   "scripts": {
     "start": "node src/index.js",

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

@@ -4,10 +4,10 @@
  * 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';
+import { getRun, setRunStatus, RUN_STATUS } from '../migration/registry.js';
+import { startDirtyTracker } from '../migration/tracker.js';
 
 function parseArgs(argv = process.argv.slice(2)) {
   const args = { _: [] };
@@ -18,71 +18,39 @@ function parseArgs(argv = process.argv.slice(2)) {
     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 === '--config-command' && argv[i + 1]) args.configCommand = 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) {
+async function startTrackerCli(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]');
+    console.error('Usage: resplite-dirty-tracker start --run-id <id> --to <db-path> [--from <redis-url>] [--config-command <name>]');
     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);
+  const tracker = await startDirtyTracker({
+    from: redisUrl,
+    to: dbPath,
+    runId,
+    pragmaTemplate: args.pragmaTemplate || 'default',
+    configCommand: args.configCommand || 'CONFIG',
   });
-  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);
-    }
-  });
+  console.log('Subscribed to __keyevent@0__:* — dirty tracker running. Ctrl+C to stop.');
 
   const shutdown = async () => {
     console.log('Stopping dirty tracker...');
-    await subClient.pUnsubscribe(pattern);
-    await subClient.quit();
-    await mainClient.quit();
+    await tracker.stop();
     process.exit(0);
   };
 
   process.on('SIGINT', shutdown);
   process.on('SIGTERM', shutdown);
-  console.log('Dirty tracker running. Ctrl+C to stop.');
 }
 
 async function stopTracker(args) {
@@ -105,7 +73,7 @@ async function stopTracker(args) {
 async function main() {
   const args = parseArgs();
   const sub = args._[0];
-  if (sub === 'start') await startTracker(args);
+  if (sub === 'start') await startTrackerCli(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>]');
@@ -121,4 +89,4 @@ if (isMain) {
   });
 }
 
-export { parseArgs, startTracker, stopTracker };
+export { parseArgs, stopTracker };

package/src/migration/apply-dirty.js

@@ -52,10 +52,12 @@ export async function runApplyDirty(redisClient, dbPath, runId, options = {}) {
       r = getRun(db, runId);
     }
 
-    const batch = getDirtyBatch(db, runId, 'dirty', batch_keys);
-    if (batch.length === 0) break;
+    const dirtyBatch   = getDirtyBatch(db, runId, 'dirty',   batch_keys);
+    const deletedBatch = getDirtyBatch(db, runId, 'deleted', batch_keys);
+    if (dirtyBatch.length === 0 && deletedBatch.length === 0) break;
 
-    for (const { key: keyBuf } of batch) {
+    // ── Re-import (or remove) keys that changed while bulk was running ──
+    for (const { key: keyBuf } of dirtyBatch) {
       r = getRun(db, runId);
       if (r && r.status === RUN_STATUS.ABORTED) break;
       while (r && r.status === RUN_STATUS.PAUSED) {
@@ -91,6 +93,35 @@ export async function runApplyDirty(redisClient, dbPath, runId, options = {}) {
         markDirtyState(db, runId, keyBuf, 'error');
       }
     }
+
+    // ── Apply deletions recorded by the tracker (del / expired events) ──
+    // The tracker already determined these keys are gone; delete from destination.
+    // Marked as 'deleted' in the run counter; state changed away from 'deleted'
+    // so the next getDirtyBatch call won't return them again (avoiding infinite loop).
+    for (const { key: keyBuf } of deletedBatch) {
+      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);
+      }
+
+      try {
+        keys.delete(keyBuf);
+        // Increment dirty_keys_deleted counter and transition state out of 'deleted'
+        // so this key is not re-processed in the next batch iteration.
+        const now = Date.now();
+        db.prepare(
+          `UPDATE migration_dirty_keys SET state = 'applied', last_seen_at = ? WHERE run_id = ? AND key = ?`
+        ).run(now, runId, keyBuf);
+        db.prepare(
+          `UPDATE migration_runs SET dirty_keys_deleted = dirty_keys_deleted + 1, updated_at = ? WHERE run_id = ?`
+        ).run(now, runId);
+      } catch (err) {
+        logError(db, runId, 'dirty_apply', err.message, keyBuf);
+        markDirtyState(db, runId, keyBuf, 'error');
+      }
+    }
   }
 
   return getRun(db, runId);

package/src/migration/index.js

@@ -0,0 +1,190 @@
+/**
+ * Programmatic migration API (SPEC_F §F.9).
+ *
+ * Usage:
+ *   import { createMigration } from 'resplite/migration';
+ *
+ *   const m = createMigration({
+ *     from: 'redis://127.0.0.1:6379',
+ *     to:   './data.db',
+ *     runId: 'my-migration-1',
+ *   });
+ *
+ *   const info   = await m.preflight();
+ *   await m.bulk({ onProgress: console.log });
+ *   const status = m.status();
+ *   await m.applyDirty();
+ *   const result = await m.verify();
+ *   await m.close();
+ */
+
+import { createClient } from 'redis';
+import { openDb } from '../storage/sqlite/db.js';
+import { runPreflight, readKeyspaceEvents, setKeyspaceEvents } from './preflight.js';
+import { runBulkImport } from './bulk.js';
+import { runApplyDirty } from './apply-dirty.js';
+import { runVerify } from './verify.js';
+import { getRun, getDirtyCounts } from './registry.js';
+
+/**
+ * @typedef {object} MigrationOptions
+ * @property {string} [from='redis://127.0.0.1:6379'] - Source Redis URL.
+ * @property {string} to                              - Destination SQLite DB path.
+ * @property {string} [runId]                         - Unique run identifier (required for bulk/status/applyDirty).
+ * @property {string} [pragmaTemplate='default']      - PRAGMA preset.
+ * @property {number} [scanCount=1000]
+ * @property {number} [maxRps=0]                      - Max requests/s (0 = unlimited).
+ * @property {number} [batchKeys=200]
+ * @property {number} [batchBytes=67108864]           - 64 MB default.
+ * @property {string} [configCommand='CONFIG']        - Redis CONFIG command name. Override if renamed for security.
+ */
+
+/**
+ * Create a migration controller bound to a source Redis and destination DB.
+ *
+ * @param {MigrationOptions} options
+ * @returns {{
+ *   preflight(): Promise<object>,
+ *   enableKeyspaceNotifications(opts?: { value?: string, merge?: boolean }): Promise<{ ok: boolean, previous: string|null, applied: string, error?: string }>,
+ *   bulk(opts?: { resume?: boolean, onProgress?: function }): Promise<object>,
+ *   status(): { run: object, dirty: object } | null,
+ *   applyDirty(opts?: { batchKeys?: number, maxRps?: number }): Promise<object>,
+ *   verify(opts?: { samplePct?: number, maxSample?: number }): Promise<object>,
+ *   close(): Promise<void>,
+ * }}
+ */
+export function createMigration({
+  from = 'redis://127.0.0.1:6379',
+  to,
+  runId,
+  pragmaTemplate = 'default',
+  scanCount = 1000,
+  maxRps = 0,
+  batchKeys = 200,
+  batchBytes = 64 * 1024 * 1024,
+  configCommand = 'CONFIG',
+} = {}) {
+  if (!to) throw new Error('createMigration: "to" (db path) is required');
+
+  let _client = null;
+
+  async function getClient() {
+    if (_client) return _client;
+    _client = createClient({ url: from });
+    _client.on('error', (err) => {
+      /* non-fatal connection errors; callers surface them on next await */
+      void err;
+    });
+    await _client.connect();
+    return _client;
+  }
+
+  function requireRunId() {
+    if (!runId) throw new Error('createMigration: "runId" is required for this operation');
+    return runId;
+  }
+
+  return {
+    /**
+     * Step 0 — Preflight: inspect the source Redis instance.
+     * Returns key count estimate, type distribution, keyspace-events config,
+     * `configCommandAvailable` (false when CONFIG is renamed/disabled),
+     * and recommended import parameters.
+     */
+    async preflight() {
+      const client = await getClient();
+      return runPreflight(client, { configCommand });
+    },
+
+    /**
+     * Enable keyspace notifications on the source Redis (required for the dirty-key tracker).
+     * Reads the current value and merges the requested flags so existing flags are preserved.
+     * If the CONFIG command has been renamed, pass `configCommand` to `createMigration`.
+     *
+     * @param {{ value?: string, merge?: boolean }} [opts]
+     *   - `value`  Flags to apply. Defaults to `'KEA'` (keyevent + keyspace + all event types).
+     *   - `merge`  If true (default), merges flags into the existing value instead of overwriting.
+     * @returns {Promise<{ ok: boolean, previous: string|null, applied: string, error?: string }>}
+     */
+    async enableKeyspaceNotifications({ value = 'KEA', merge = true } = {}) {
+      const client = await getClient();
+      return setKeyspaceEvents(client, value, { configCommand, merge });
+    },
+
+    /**
+     * Step 1 — Bulk import: SCAN all keys from Redis into the destination DB.
+     * Supports resume (checkpoint-based) and optional progress callback.
+     *
+     * @param {{ resume?: boolean, onProgress?: (run: object) => void }} [opts]
+     */
+    async bulk({ resume = false, onProgress } = {}) {
+      const id = requireRunId();
+      const client = await getClient();
+      return runBulkImport(client, to, id, {
+        sourceUri: from,
+        pragmaTemplate,
+        scan_count: scanCount,
+        max_rps: maxRps,
+        batch_keys: batchKeys,
+        batch_bytes: batchBytes,
+        resume,
+        onProgress,
+      });
+    },
+
+    /**
+     * Step 2 — Status: read run metadata and dirty-key counts from the DB.
+     * Synchronous — no Redis connection needed.
+     *
+     * @returns {{ run: object, dirty: object } | null}
+     */
+    status() {
+      const id = requireRunId();
+      const db = openDb(to, { pragmaTemplate });
+      const run = getRun(db, id);
+      if (!run) return null;
+      const dirty = getDirtyCounts(db, id);
+      return { run, dirty };
+    },
+
+    /**
+     * Step 3 — Apply dirty: reconcile keys that changed in Redis during bulk import.
+     *
+     * @param {{ batchKeys?: number, maxRps?: number }} [opts]
+     */
+    async applyDirty({ batchKeys: bk = batchKeys, maxRps: rps = maxRps } = {}) {
+      const id = requireRunId();
+      const client = await getClient();
+      return runApplyDirty(client, to, id, {
+        pragmaTemplate,
+        batch_keys: bk,
+        max_rps: rps,
+      });
+    },
+
+    /**
+     * Step 4 — Verify: sample keys from Redis and compare with the destination DB.
+     *
+     * @param {{ samplePct?: number, maxSample?: number }} [opts]
+     * @returns {Promise<{ sampled: number, matched: number, mismatches: Array<{ key: string, reason: string }> }>}
+     */
+    async verify({ samplePct = 0.5, maxSample = 10000 } = {}) {
+      const client = await getClient();
+      return runVerify(client, to, { pragmaTemplate, samplePct, maxSample });
+    },
+
+    /**
+     * Disconnect from Redis. Call when done with all migration operations.
+     */
+    async close() {
+      if (_client) {
+        await _client.quit().catch(() => {});
+        _client = null;
+      }
+    },
+  };
+}
+
+export { runPreflight, readKeyspaceEvents, setKeyspaceEvents, runBulkImport, runApplyDirty, runVerify };
+export { startDirtyTracker } from './tracker.js';
+export { getRun, getDirtyCounts, createRun, setRunStatus, logError } from './registry.js';

package/src/migration/preflight.js

@@ -2,11 +2,86 @@
  * Preflight check: estimate key count, type distribution, notify-keyspace-events (SPEC_F §F.9 Step 0).
  */
 
+const KEYSPACE_PARAM = 'notify-keyspace-events';
+
+/**
+ * Read the current `notify-keyspace-events` value from Redis.
+ * Uses raw sendCommand so it works even if the CONFIG command has been renamed.
+ *
+ * @param {import('redis').RedisClientType} redisClient
+ * @param {string} [configCommand='CONFIG']
+ * @returns {Promise<{ value: string | null; available: boolean }>}
+ *   `available: false` when the command is disabled or renamed and the default name fails.
+ */
+export async function readKeyspaceEvents(redisClient, configCommand = 'CONFIG') {
+  try {
+    const raw = await redisClient.sendCommand([configCommand, 'GET', KEYSPACE_PARAM]);
+    // Redis returns a flat array ['notify-keyspace-events', '<value>']
+    if (Array.isArray(raw) && raw.length >= 2) {
+      return { value: String(raw[1] ?? ''), available: true };
+    }
+    // redis@4 may return an object { 'notify-keyspace-events': '<value>' }
+    if (raw && typeof raw === 'object' && !Array.isArray(raw)) {
+      const v = raw[KEYSPACE_PARAM];
+      return { value: typeof v === 'string' ? v : null, available: true };
+    }
+    return { value: null, available: true };
+  } catch (_) {
+    return { value: null, available: false };
+  }
+}
+
 /**
+ * Set `notify-keyspace-events` to `value` on Redis.
+ * Optionally merges the new flags into the existing value instead of overwriting.
+ *
  * @param {import('redis').RedisClientType} redisClient
- * @returns {Promise<{ keyCountEstimate: number; typeDistribution: Record<string, number>; notifyKeyspaceEvents: string | null; recommended: { scan_count: number; max_concurrency: number; max_rps: number } }>}
+ * @param {string} value - Flags to apply (e.g. `'Kgxe'`).
+ * @param {{ configCommand?: string; merge?: boolean }} [options]
+ * @returns {Promise<{ ok: boolean; previous: string | null; applied: string; error?: string }>}
  */
-export async function runPreflight(redisClient) {
+export async function setKeyspaceEvents(redisClient, value, { configCommand = 'CONFIG', merge = true } = {}) {
+  const { value: previous, available } = await readKeyspaceEvents(redisClient, configCommand);
+
+  if (!available) {
+    return {
+      ok: false,
+      previous: null,
+      applied: value,
+      error: `CONFIG command not available (it may have been renamed). ` +
+             `Use the configCommand option to supply the correct name, ` +
+             `or set notify-keyspace-events manually: ${configCommand} SET ${KEYSPACE_PARAM} ${value}`,
+    };
+  }
+
+  const applied = merge && previous ? mergeFlags(previous, value) : value;
+
+  try {
+    await redisClient.sendCommand([configCommand, 'SET', KEYSPACE_PARAM, applied]);
+    return { ok: true, previous, applied };
+  } catch (err) {
+    return { ok: false, previous, applied, error: err.message };
+  }
+}
+
+/**
+ * Merge two Redis notify-keyspace-events flag strings.
+ * Preserves all flags from both; result is sorted for readability.
+ * @param {string} existing
+ * @param {string} required
+ * @returns {string}
+ */
+function mergeFlags(existing, required) {
+  const merged = new Set([...existing, ...required]);
+  return [...merged].sort().join('');
+}
+
+/**
+ * @param {import('redis').RedisClientType} redisClient
+ * @param {{ configCommand?: string }} [options]
+ * @returns {Promise<{ keyCountEstimate: number; typeDistribution: Record<string, number>; notifyKeyspaceEvents: string | null; configCommandAvailable: boolean; recommended: { scan_count: number; max_concurrency: number; max_rps: number } }>}
+ */
+export async function runPreflight(redisClient, { configCommand = 'CONFIG' } = {}) {
   let keyCountEstimate = 0;
   try {
     keyCountEstimate = await redisClient.dbSize();
@@ -38,14 +113,8 @@ export async function runPreflight(redisClient) {
     } while (cursor !== 0);
   }
 
-  let notifyKeyspaceEvents = null;
-  try {
-    const config = await redisClient.configGet('notify-keyspace-events');
-    notifyKeyspaceEvents = config && typeof config === 'object' ? config['notify-keyspace-events'] : null;
-    if (typeof notifyKeyspaceEvents !== 'string') notifyKeyspaceEvents = null;
-  } catch (_) {
-    notifyKeyspaceEvents = null;
-  }
+  const { value: notifyKeyspaceEvents, available: configCommandAvailable } =
+    await readKeyspaceEvents(redisClient, configCommand);
 
   const recommended = {
     scan_count: 1000,
@@ -57,6 +126,7 @@ export async function runPreflight(redisClient) {
     keyCountEstimate,
     typeDistribution,
     notifyKeyspaceEvents,
+    configCommandAvailable,
     recommended,
   };
 }

package/src/migration/tracker.js

@@ -0,0 +1,90 @@
+/**
+ * Dirty-key tracker: subscribe to Redis keyspace notifications and record
+ * modified/deleted keys in the migration registry (SPEC_F §F.6).
+ *
+ * Programmatic API:
+ *   const tracker = await startDirtyTracker({ from, to, runId });
+ *   // ... run bulk import and other Redis writes ...
+ *   await tracker.stop();
+ */
+
+import { createClient } from 'redis';
+import { openDb } from '../storage/sqlite/db.js';
+import { createRun, upsertDirtyKey, logError } from './registry.js';
+import { readKeyspaceEvents } from './preflight.js';
+
+const KEYEVENT_PATTERN = '__keyevent@0__:*';
+
+/**
+ * Start the dirty-key tracker: connect a subscriber client and record every
+ * keyspace event into the migration registry.
+ *
+ * Resolves once the subscription is active. Call `stop()` to disconnect.
+ *
+ * @param {object} options
+ * @param {string} [options.from='redis://127.0.0.1:6379'] - Source Redis URL.
+ * @param {string} options.to                              - SQLite DB path (must already exist or be created by bulk).
+ * @param {string} options.runId                           - Migration run identifier.
+ * @param {string} [options.pragmaTemplate='default']
+ * @param {string} [options.configCommand='CONFIG']        - CONFIG command name (in case it was renamed).
+ * @returns {Promise<{ stop(): Promise<void> }>}
+ * @throws {Error} If keyspace notifications are not enabled on Redis.
+ */
+export async function startDirtyTracker({
+  from = 'redis://127.0.0.1:6379',
+  to,
+  runId,
+  pragmaTemplate = 'default',
+  configCommand = 'CONFIG',
+} = {}) {
+  if (!to) throw new Error('startDirtyTracker: "to" (db path) is required');
+  if (!runId) throw new Error('startDirtyTracker: "runId" is required');
+
+  const db = openDb(to, { pragmaTemplate });
+  createRun(db, runId, from); // idempotent — safe to call even if bulk already created the run
+
+  const mainClient = createClient({ url: from });
+  mainClient.on('error', (err) =>
+    logError(db, runId, 'dirty_apply', 'Tracker connection error: ' + err.message, null)
+  );
+  await mainClient.connect();
+
+  // Validate keyspace notifications before subscribing
+  const { value: eventsValue, available } = await readKeyspaceEvents(mainClient, configCommand);
+  if (!available || !eventsValue || eventsValue === '') {
+    await mainClient.quit().catch(() => {});
+    throw new Error(
+      `Redis notify-keyspace-events is not set. ` +
+      `Enable it first: ${configCommand} SET notify-keyspace-events KEA\n` +
+      `Or call m.enableKeyspaceNotifications() from the programmatic API.`
+    );
+  }
+
+  const subClient = mainClient.duplicate();
+  subClient.on('error', (err) =>
+    logError(db, runId, 'dirty_apply', 'Tracker subscriber error: ' + err.message, null)
+  );
+  await subClient.connect();
+
+  await subClient.pSubscribe(KEYEVENT_PATTERN, (message, channel) => {
+    const event = typeof channel === 'string'
+      ? channel.split(':').pop()
+      : String(channel ?? '').split(':').pop() || 'unknown';
+    try {
+      upsertDirtyKey(db, runId, message, event);
+    } catch (err) {
+      logError(db, runId, 'dirty_apply', err.message, message);
+    }
+  });
+
+  return {
+    /**
+     * Unsubscribe and disconnect. Safe to call multiple times.
+     */
+    async stop() {
+      await subClient.pUnsubscribe(KEYEVENT_PATTERN).catch(() => {});
+      await subClient.quit().catch(() => {});
+      await mainClient.quit().catch(() => {});
+    },
+  };
+}

package/test/integration/migration-dirty-tracker.test.js

@@ -0,0 +1,201 @@
+/**
+ * Integration test: dirty-key tracker + full migration flow.
+ *
+ * Requires a local Redis instance on redis://127.0.0.1:6379.
+ * The test is skipped automatically if Redis is unavailable or
+ * if keyspace notifications cannot be enabled.
+ *
+ * Flow being tested:
+ *   1. Write initial keys to Redis
+ *   2. Enable keyspace notifications
+ *   3. Start dirty tracker
+ *   4. Run bulk import  (captures snapshot at T=0)
+ *   5. Modify keys in Redis after bulk  (tracker records them as dirty)
+ *   6. Stop tracker
+ *   7. Apply-dirty  (reconciles post-bulk changes into destination)
+ *   8. Verify  (destination matches Redis)
+ */
+
+import { describe, it, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { createClient } from 'redis';
+import { createMigration, startDirtyTracker } from '../../src/migration/index.js';
+import { tmpDbPath } from '../helpers/tmp.js';
+
+const REDIS_URL = 'redis://127.0.0.1:6379';
+const PREFIX    = `__resplite_tracker_test_${process.pid}__`;
+
+/** Connect to local Redis; return null if unavailable. */
+async function tryConnectRedis() {
+  const client = createClient({ url: REDIS_URL });
+  try {
+    await client.connect();
+    await client.ping();
+    return client;
+  } catch {
+    await client.quit().catch(() => {});
+    return null;
+  }
+}
+
+/** Delete all keys under PREFIX. */
+async function cleanup(redis) {
+  let cursor = 0;
+  do {
+    const result = await redis.scan(cursor, { MATCH: `${PREFIX}:*`, COUNT: 200 });
+    cursor  = typeof result.cursor === 'number' ? result.cursor : parseInt(result.cursor, 10);
+    const keys = result.keys ?? [];
+    if (keys.length) await redis.del(keys);
+  } while (cursor !== 0);
+}
+
+describe('dirty tracker integration', { timeout: 30_000 }, () => {
+  let redis = null;
+  let originalEventsValue = '';
+
+  before(async () => {
+    redis = await tryConnectRedis();
+    if (!redis) return; // tests will skip inside each `it`
+
+    // Save existing notify-keyspace-events so we can restore it after
+    const raw = await redis.sendCommand(['CONFIG', 'GET', 'notify-keyspace-events']);
+    originalEventsValue = Array.isArray(raw) ? (raw[1] ?? '') : '';
+
+    await cleanup(redis);
+  });
+
+  after(async () => {
+    if (!redis) return;
+    // Restore original keyspace events value
+    await redis.sendCommand(['CONFIG', 'SET', 'notify-keyspace-events', originalEventsValue]);
+    await cleanup(redis);
+    await redis.quit();
+  });
+
+  it('bulk + tracker + apply-dirty produces a fully reconciled destination', async (t) => {
+    if (!redis) {
+      t.skip('local Redis not available');
+      return;
+    }
+
+    // ── Seed: write initial keys ─────────────────────────────────────────
+    const keys = {
+      string:  `${PREFIX}:str`,
+      hash:    `${PREFIX}:hash`,
+      set:     `${PREFIX}:set`,
+      list:    `${PREFIX}:list`,
+      toDelete: `${PREFIX}:will-delete`,
+      toModify: `${PREFIX}:will-modify`,
+    };
+
+    await redis.set(keys.string,   'hello');
+    await redis.hSet(keys.hash,    { field1: 'v1', field2: 'v2' });
+    await redis.sAdd(keys.set,     ['a', 'b', 'c']);
+    await redis.rPush(keys.list,   ['x', 'y', 'z']);
+    await redis.set(keys.toDelete, 'delete-me');
+    await redis.set(keys.toModify, 'original');
+
+    // ── Setup: enable keyspace notifications ────────────────────────────
+    const dbPath = tmpDbPath();
+    const runId  = `tracker-test-${Date.now()}`;
+
+    const m = createMigration({ from: REDIS_URL, to: dbPath, runId });
+
+    const ks = await m.enableKeyspaceNotifications({ value: 'KEA' });
+    assert.ok(ks.ok, `Failed to enable keyspace notifications: ${ks.error}`);
+
+    // ── Start tracker BEFORE bulk ────────────────────────────────────────
+    const tracker = await startDirtyTracker({ from: REDIS_URL, to: dbPath, runId });
+
+    try {
+      // ── Bulk import (captures the initial snapshot) ──────────────────
+      const run = await m.bulk();
+      assert.equal(run.status, 'completed');
+      assert.ok(run.migrated_keys >= 6, `Expected ≥6 migrated keys, got ${run.migrated_keys}`);
+
+      // ── Post-bulk mutations (tracker will record these) ──────────────
+      await redis.set(keys.toModify, 'modified-after-bulk');
+      await redis.del(keys.toDelete);
+      await redis.set(`${PREFIX}:new-key`, 'added-after-bulk');
+
+      // Give the tracker time to process the keyspace events
+      await new Promise((r) => setTimeout(r, 600));
+    } finally {
+      await tracker.stop();
+    }
+
+    // ── Verify dirty keys were captured ─────────────────────────────────
+    const { dirty } = m.status();
+    assert.ok(
+      dirty.dirty + dirty.deleted >= 3,
+      `Expected ≥3 dirty/deleted keys, got dirty=${dirty.dirty} deleted=${dirty.deleted}`
+    );
+
+    // ── Apply-dirty: reconcile post-bulk changes ─────────────────────────
+    const afterApply = await m.applyDirty();
+    const totalReconciled = afterApply.dirty_keys_applied + afterApply.dirty_keys_deleted;
+    assert.ok(totalReconciled >= 3, `Expected ≥3 reconciled keys, got ${totalReconciled}`);
+
+    // ── Verify: destination should now match Redis for our test prefix ───
+    const result = await m.verify({ samplePct: 100, maxSample: 5000 });
+
+    // Filter mismatches to only those under our test prefix
+    const ourMismatches = result.mismatches.filter((mm) => mm.key.startsWith(PREFIX));
+    assert.equal(
+      ourMismatches.length,
+      0,
+      `Unexpected mismatches in test keys:\n${JSON.stringify(ourMismatches, null, 2)}`
+    );
+
+    await m.close();
+  });
+
+  it('startDirtyTracker throws when keyspace notifications are disabled', async (t) => {
+    if (!redis) {
+      t.skip('local Redis not available');
+      return;
+    }
+
+    // Disable keyspace notifications
+    await redis.sendCommand(['CONFIG', 'SET', 'notify-keyspace-events', '']);
+
+    const dbPath = tmpDbPath();
+    const runId  = `tracker-noevents-${Date.now()}`;
+
+    await assert.rejects(
+      () => startDirtyTracker({ from: REDIS_URL, to: dbPath, runId }),
+      /notify-keyspace-events/
+    );
+
+    // Re-enable for subsequent tests
+    await redis.sendCommand(['CONFIG', 'SET', 'notify-keyspace-events', 'KEA']);
+  });
+
+  it('enableKeyspaceNotifications merges flags without overwriting existing ones', async (t) => {
+    if (!redis) {
+      t.skip('local Redis not available');
+      return;
+    }
+
+    const dbPath = tmpDbPath();
+    const m = createMigration({ from: REDIS_URL, to: dbPath, runId: `ks-merge-${Date.now()}` });
+
+    // Set a partial value first
+    await redis.sendCommand(['CONFIG', 'SET', 'notify-keyspace-events', 'Kg']);
+
+    const result = await m.enableKeyspaceNotifications({ value: 'KEA', merge: true });
+    assert.ok(result.ok, `Expected ok=true: ${result.error}`);
+    // Redis may reorder flags (e.g. 'Kg' → 'gK'); only check flag membership
+    assert.ok(typeof result.previous === 'string', 'previous should be a string');
+    assert.ok(result.previous.includes('K'), `Missing K in previous="${result.previous}"`);
+    assert.ok(result.previous.includes('g'), `Missing g in previous="${result.previous}"`);
+
+    // Applied value must contain K, E, A and the original g
+    const applied = result.applied;
+    assert.ok(applied.includes('K'), `Missing K in applied="${applied}"`);
+    assert.ok(applied.includes('E'), `Missing E in applied="${applied}"`);
+    assert.ok(applied.includes('A'), `Missing A in applied="${applied}"`);
+
+    await m.close();
+  });
+});