resplite 1.0.6 → 1.1.2

package/README.md

@@ -341,16 +341,18 @@ For large datasets (~30 GB), use the Dirty Key Registry flow so the bulk of the
 **Enable keyspace notifications in Redis** (required for the dirty-key tracker). Either run at runtime:
 
 ```bash
-redis-cli CONFIG SET notify-keyspace-events Kgxe
+redis-cli CONFIG SET notify-keyspace-events KEA
 ```
 
 Or add to `redis.conf` and restart Redis:
 
 ```
-notify-keyspace-events Kgxe
+notify-keyspace-events KEA
 ```
 
-(`K` = keyspace, `g` = generic, `x` = expired; `e` = keyevent. This lets the tracker see key changes and expirations.)
+(`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
@@ -360,6 +362,8 @@ notify-keyspace-events Kgxe
 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:
@@ -408,14 +412,25 @@ const m = createMigration({
   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
@@ -441,6 +456,33 @@ 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:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "resplite",
-  "version": "1.0.6",
+  "version": "1.1.2",
   "description": "A RESP2 server with practical Redis compatibility, backed by SQLite",
   "type": "module",
   "main": "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

@@ -20,7 +20,7 @@
 
 import { createClient } from 'redis';
 import { openDb } from '../storage/sqlite/db.js';
-import { runPreflight } from './preflight.js';
+import { runPreflight, readKeyspaceEvents, setKeyspaceEvents } from './preflight.js';
 import { runBulkImport } from './bulk.js';
 import { runApplyDirty } from './apply-dirty.js';
 import { runVerify } from './verify.js';
@@ -36,6 +36,7 @@ import { getRun, getDirtyCounts } from './registry.js';
  * @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.
  */
 
 /**
@@ -43,7 +44,8 @@ import { getRun, getDirtyCounts } from './registry.js';
  *
  * @param {MigrationOptions} options
  * @returns {{
- *   preflight(): Promise<import('./preflight.js').PreflightResult>,
+ *   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>,
@@ -60,6 +62,7 @@ export function createMigration({
   maxRps = 0,
   batchKeys = 200,
   batchBytes = 64 * 1024 * 1024,
+  configCommand = 'CONFIG',
 } = {}) {
   if (!to) throw new Error('createMigration: "to" (db path) is required');
 
@@ -85,11 +88,27 @@ export function createMigration({
     /**
      * 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);
+      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 });
     },
 
     /**
@@ -166,5 +185,6 @@ export function createMigration({
   };
 }
 
-export { runPreflight, runBulkImport, runApplyDirty, runVerify };
+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();
+  });
+});