resplite 1.0.0 → 1.0.4

package/src/migration/registry.js

@@ -0,0 +1,222 @@
+/**
+ * Migration registry access (SPEC_F §F.5).
+ * Run metadata, dirty key tracking, and error logging.
+ */
+
+const RUN_STATUS = {
+  RUNNING: 'running',
+  PAUSED: 'paused',
+  COMPLETED: 'completed',
+  FAILED: 'failed',
+  ABORTED: 'aborted',
+};
+
+/**
+ * @param {Buffer|string} key
+ * @returns {Buffer}
+ */
+function asBlob(key) {
+  if (Buffer.isBuffer(key)) return key;
+  return Buffer.from(String(key), 'utf8');
+}
+
+/**
+ * Create a new migration run. Idempotent: if run_id exists, return it.
+ * @param {import('better-sqlite3').Database} db
+ * @param {string} runId
+ * @param {string} sourceUri
+ * @param {object} [options] - scan_count_hint
+ * @returns {{ run_id: string, created: boolean }}
+ */
+export function createRun(db, runId, sourceUri, options = {}) {
+  const { scan_count_hint = 1000 } = options;
+  const now = Date.now();
+  const stmt = db.prepare(`
+    INSERT INTO migration_runs (
+      run_id, source_uri, started_at, updated_at, status,
+      scan_cursor, scan_count_hint,
+      scanned_keys, migrated_keys, skipped_keys, error_keys, migrated_bytes,
+      dirty_keys_seen, dirty_keys_applied, dirty_keys_deleted
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, 0, 0, 0, 0, 0, 0, 0, 0)
+    ON CONFLICT(run_id) DO NOTHING
+  `);
+  stmt.run(runId, sourceUri, now, now, RUN_STATUS.RUNNING, '0', scan_count_hint);
+  const created = db.prepare('SELECT changes() as n').get().n > 0;
+  if (created) {
+    db.prepare('UPDATE migration_runs SET updated_at = ? WHERE run_id = ?').run(now, runId);
+  }
+  return { run_id: runId, created };
+}
+
+/**
+ * @param {import('better-sqlite3').Database} db
+ * @param {string} runId
+ * @returns {Record<string, unknown> | undefined}
+ */
+export function getRun(db, runId) {
+  const row = db.prepare('SELECT * FROM migration_runs WHERE run_id = ?').get(runId);
+  return row ? (row instanceof Object ? row : undefined) : undefined;
+}
+
+/**
+ * @param {import('better-sqlite3').Database} db
+ * @param {string} runId
+ * @param {'running'|'paused'|'completed'|'failed'|'aborted'} status
+ */
+export function setRunStatus(db, runId, status) {
+  const now = Date.now();
+  db.prepare('UPDATE migration_runs SET status = ?, updated_at = ? WHERE run_id = ?').run(status, now, runId);
+}
+
+/**
+ * Update bulk import progress (cursor and counters).
+ * @param {import('better-sqlite3').Database} db
+ * @param {string} runId
+ * @param {{
+ *   scan_cursor?: string;
+ *   scanned_keys?: number;
+ *   migrated_keys?: number;
+ *   skipped_keys?: number;
+ *   error_keys?: number;
+ *   migrated_bytes?: number;
+ *   last_error?: string | null;
+ * }} updates
+ */
+export function updateBulkProgress(db, runId, updates) {
+  const now = Date.now();
+  const run = getRun(db, runId);
+  if (!run) return;
+
+  const cursor = updates.scan_cursor !== undefined ? String(updates.scan_cursor) : run.scan_cursor;
+  const scanned_keys = updates.scanned_keys !== undefined ? updates.scanned_keys : run.scanned_keys;
+  const migrated_keys = updates.migrated_keys !== undefined ? updates.migrated_keys : run.migrated_keys;
+  const skipped_keys = updates.skipped_keys !== undefined ? updates.skipped_keys : run.skipped_keys;
+  const error_keys = updates.error_keys !== undefined ? updates.error_keys : run.error_keys;
+  const migrated_bytes = updates.migrated_bytes !== undefined ? updates.migrated_bytes : run.migrated_bytes;
+  const last_error = updates.last_error !== undefined ? updates.last_error : run.last_error;
+
+  db.prepare(`
+    UPDATE migration_runs SET
+      scan_cursor = ?,
+      scanned_keys = ?,
+      migrated_keys = ?,
+      skipped_keys = ?,
+      error_keys = ?,
+      migrated_bytes = ?,
+      last_error = ?,
+      updated_at = ?
+    WHERE run_id = ?
+  `).run(cursor, scanned_keys, migrated_keys, skipped_keys, error_keys, migrated_bytes, last_error ?? null, now, runId);
+}
+
+/**
+ * Upsert a dirty key (tracker saw an event). State: dirty or deleted per event type (SPEC_F F.6.2, F.6.3).
+ * @param {import('better-sqlite3').Database} db
+ * @param {string} runId
+ * @param {Buffer|string} key
+ * @param {string} event - e.g. "set", "hset", "del", "expired"
+ */
+export function upsertDirtyKey(db, runId, key, event) {
+  const keyBlob = asBlob(key);
+  const now = Date.now();
+  const isDelete = event === 'del' || event === 'unlink' || event === 'expired';
+  const state = isDelete ? 'deleted' : 'dirty';
+
+  const existing = db.prepare('SELECT first_seen_at, state FROM migration_dirty_keys WHERE run_id = ? AND key = ?')
+    .get(runId, keyBlob);
+
+  if (existing) {
+    // If was deleted but we see a write again, revert to dirty (SPEC_F F.6.3)
+    const newState = existing.state === 'deleted' && !isDelete ? 'dirty' : (isDelete ? 'deleted' : 'dirty');
+    db.prepare(`
+      UPDATE migration_dirty_keys SET
+        last_seen_at = ?,
+        events_count = events_count + 1,
+        last_event = ?,
+        state = ?
+      WHERE run_id = ? AND key = ?
+    `).run(now, event, newState, runId, keyBlob);
+  } else {
+    db.prepare(`
+      INSERT INTO migration_dirty_keys (run_id, key, first_seen_at, last_seen_at, events_count, last_event, state)
+      VALUES (?, ?, ?, ?, 1, ?, ?)
+    `).run(runId, keyBlob, now, now, event, state);
+  }
+
+  db.prepare('UPDATE migration_runs SET dirty_keys_seen = dirty_keys_seen + 1, updated_at = ? WHERE run_id = ?')
+    .run(now, runId);
+}
+
+/**
+ * Get a batch of dirty keys for delta apply. ORDER BY last_seen_at ASC, LIMIT.
+ * @param {import('better-sqlite3').Database} db
+ * @param {string} runId
+ * @param {string} state - 'dirty'
+ * @param {number} limit
+ * @returns {{ key: Buffer }[]}
+ */
+export function getDirtyBatch(db, runId, state, limit) {
+  const rows = db.prepare(`
+    SELECT key FROM migration_dirty_keys
+    WHERE run_id = ? AND state = ?
+    ORDER BY last_seen_at ASC
+    LIMIT ?
+  `).all(runId, state, limit);
+  return rows.map((r) => ({ key: r.key instanceof Buffer ? r.key : Buffer.from(r.key) }));
+}
+
+/**
+ * Mark a dirty key as applied or deleted and update run counters.
+ * @param {import('better-sqlite3').Database} db
+ * @param {string} runId
+ * @param {Buffer|string} key
+ * @param {'applied'|'deleted'|'skipped'|'error'} state
+ */
+export function markDirtyState(db, runId, key, state) {
+  const keyBlob = asBlob(key);
+  const now = Date.now();
+  db.prepare('UPDATE migration_dirty_keys SET state = ? WHERE run_id = ? AND key = ?')
+    .run(state, runId, keyBlob);
+
+  if (state === 'applied') {
+    db.prepare('UPDATE migration_runs SET dirty_keys_applied = dirty_keys_applied + 1, updated_at = ? WHERE run_id = ?')
+      .run(now, runId);
+  } else if (state === 'deleted') {
+    db.prepare('UPDATE migration_runs SET dirty_keys_deleted = dirty_keys_deleted + 1, updated_at = ? WHERE run_id = ?')
+      .run(now, runId);
+  }
+}
+
+/**
+ * Log an error for the run (bounded table; consider retention in production).
+ * @param {import('better-sqlite3').Database} db
+ * @param {string} runId
+ * @param {string} stage - 'bulk' | 'dirty_apply' | 'verify'
+ * @param {string} message
+ * @param {Buffer|string|null} [key]
+ */
+export function logError(db, runId, stage, message, key = null) {
+  const now = Date.now();
+  const keyBlob = key != null ? asBlob(key) : null;
+  db.prepare('INSERT INTO migration_errors (run_id, at, key, stage, message) VALUES (?, ?, ?, ?, ?)')
+    .run(runId, now, keyBlob, stage, message);
+}
+
+/**
+ * Get count of dirty keys by state for a run.
+ * @param {import('better-sqlite3').Database} db
+ * @param {string} runId
+ * @returns {Record<string, number>}
+ */
+export function getDirtyCounts(db, runId) {
+  const rows = db.prepare(`
+    SELECT state, COUNT(*) as n FROM migration_dirty_keys WHERE run_id = ? GROUP BY state
+  `).all(runId);
+  const out = { dirty: 0, applied: 0, deleted: 0, skipped: 0, error: 0 };
+  for (const r of rows) {
+    out[r.state] = r.n;
+  }
+  return out;
+}
+
+export { RUN_STATUS };

package/src/migration/verify.js

@@ -0,0 +1,191 @@
+/**
+ * Verification: sample keys and compare Redis vs RespLite destination (SPEC_F §F.9 Step 7).
+ */
+
+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 { KEY_TYPES } from '../storage/sqlite/schema.js';
+import { asKey } from '../util/buffers.js';
+
+/**
+ * Get key type and value from destination DB for comparison.
+ * @param {object} storages
+ * @param {Buffer} keyBuf
+ * @returns {{ type: string; value?: unknown; ttl?: number } | null}
+ */
+function getKeyFromDestination(storages, keyBuf) {
+  const { keys, strings, hashes, sets, lists, zsets } = storages;
+  const meta = keys.get(keyBuf);
+  if (!meta) return null;
+
+  const typeNum = meta.type;
+  let type = 'unknown';
+  if (typeNum === KEY_TYPES.STRING) type = 'string';
+  else if (typeNum === KEY_TYPES.HASH) type = 'hash';
+  else if (typeNum === KEY_TYPES.SET) type = 'set';
+  else if (typeNum === KEY_TYPES.LIST) type = 'list';
+  else if (typeNum === KEY_TYPES.ZSET) type = 'zset';
+
+  let value;
+  if (typeNum === KEY_TYPES.STRING) {
+    const v = strings.get(keyBuf);
+    value = v ? v.toString('utf8') : null;
+  } else if (typeNum === KEY_TYPES.HASH) {
+    const flat = hashes.getAll(keyBuf);
+    const obj = {};
+    for (let i = 0; i < flat.length; i += 2) {
+      obj[flat[i].toString('utf8')] = flat[i + 1].toString('utf8');
+    }
+    value = obj;
+  } else if (typeNum === KEY_TYPES.SET) {
+    value = sets.members(keyBuf).map((b) => b.toString('utf8')).sort();
+  } else if (typeNum === KEY_TYPES.LIST) {
+    value = lists.lrange(keyBuf, 0, -1).map((b) => b.toString('utf8'));
+  } else if (typeNum === KEY_TYPES.ZSET) {
+    const flat = zsets.rangeByRank(keyBuf, 0, -1, { withScores: true });
+    value = [];
+    for (let i = 0; i < flat.length; i += 2) {
+      value.push({ member: flat[i].toString('utf8'), score: Number(flat[i + 1]) });
+    }
+  }
+
+  const now = Date.now();
+  const expiresAt = meta.expiresAt;
+  const ttl = expiresAt != null && expiresAt > now ? Math.floor((expiresAt - now) / 1000) : -1;
+
+  return { type, value, ttl };
+}
+
+/**
+ * Run verification: sample keys from Redis, compare with destination DB.
+ * @param {import('redis').RedisClientType} redisClient
+ * @param {string} dbPath
+ * @param {object} options
+ * @param {string} [options.pragmaTemplate='default']
+ * @param {number} [options.samplePct=0.5] - sample percentage (0.5 = 0.5%)
+ * @param {number} [options.maxSample=10000]
+ * @returns {Promise<{ sampled: number; matched: number; mismatches: Array<{ key: string; reason: string }> }>}
+ */
+export async function runVerify(redisClient, dbPath, options = {}) {
+  const { pragmaTemplate = 'default', samplePct = 0.5, maxSample = 10000 } = options;
+
+  const db = openDb(dbPath, { pragmaTemplate });
+  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 keyList = [];
+  let cursor = 0;
+  const takeEvery = Math.max(1, Math.floor(100 / samplePct));
+  let index = 0;
+
+  do {
+    const result = await redisClient.scan(cursor, { COUNT: 500 });
+    const keysBatch = Array.isArray(result) ? result[1] : (result?.keys || []);
+    cursor = Array.isArray(result) ? parseInt(result[0], 10) : (result?.cursor ?? 0);
+    for (const k of keysBatch) {
+      if (index++ % takeEvery === 0) keyList.push(k);
+      if (keyList.length >= maxSample) break;
+    }
+    if (keyList.length >= maxSample) break;
+  } while (cursor !== 0);
+
+  let matched = 0;
+  const mismatches = [];
+
+  for (const keyName of keyList) {
+    const keyBuf = asKey(keyName);
+    const dest = getKeyFromDestination(storages, keyBuf);
+    try {
+      const redisType = (await redisClient.type(keyName)).toLowerCase();
+      let redisTtl = await redisClient.pTTL(keyName);
+      if (redisTtl === -2) redisTtl = -1;
+      else if (redisTtl > 0) redisTtl = Math.floor(redisTtl / 1000);
+
+      if (!dest) {
+        mismatches.push({ key: keyName, reason: 'missing in destination' });
+        continue;
+      }
+      if (dest.type !== redisType) {
+        mismatches.push({ key: keyName, reason: `type mismatch: Redis=${redisType} dest=${dest.type}` });
+        continue;
+      }
+      if (dest.ttl !== undefined && redisTtl >= 0 && dest.ttl !== redisTtl) {
+        if (Math.abs(dest.ttl - redisTtl) > 1) {
+          mismatches.push({ key: keyName, reason: `TTL mismatch: Redis=${redisTtl}s dest=${dest.ttl}s` });
+          continue;
+        }
+      }
+
+      if (redisType === 'string') {
+        const redisVal = await redisClient.get(keyName);
+        const destVal = dest.value;
+        if (String(redisVal ?? '') !== String(destVal ?? '')) {
+          mismatches.push({ key: keyName, reason: 'value mismatch (string)' });
+          continue;
+        }
+      } else if (redisType === 'hash') {
+        const redisObj = await redisClient.hGetAll(keyName);
+        const destObj = dest.value || {};
+        const redisKeys = Object.keys(redisObj || {}).sort();
+        const destKeys = Object.keys(destObj).sort();
+        if (redisKeys.join(',') !== destKeys.join(',')) {
+          mismatches.push({ key: keyName, reason: 'hash field mismatch' });
+          continue;
+        }
+        for (const f of redisKeys) {
+          if (String((redisObj || {})[f]) !== String(destObj[f])) {
+            mismatches.push({ key: keyName, reason: `hash field '${f}' value mismatch` });
+            break;
+          }
+        }
+        if (mismatches[mismatches.length - 1]?.key === keyName) continue;
+      } else if (redisType === 'set') {
+        const redisMembers = (await redisClient.sMembers(keyName)).sort();
+        const destMembers = (dest.value || []).slice().sort();
+        if (redisMembers.length !== destMembers.length || redisMembers.join(',') !== destMembers.join(',')) {
+          mismatches.push({ key: keyName, reason: 'set members mismatch' });
+          continue;
+        }
+      } else if (redisType === 'list') {
+        const redisList = await redisClient.lRange(keyName, 0, -1);
+        const destList = dest.value || [];
+        if (redisList.length !== destList.length || redisList.join(',') !== destList.join(',')) {
+          mismatches.push({ key: keyName, reason: 'list elements mismatch' });
+          continue;
+        }
+      } else if (redisType === 'zset') {
+        const redisZ = await redisClient.zRangeWithScores(keyName, 0, -1);
+        const destZ = dest.value || [];
+        if (redisZ.length !== destZ.length) {
+          mismatches.push({ key: keyName, reason: 'zset cardinality mismatch' });
+          continue;
+        }
+        for (let i = 0; i < redisZ.length; i++) {
+          const r = redisZ[i];
+          const d = destZ[i];
+          if (r.value !== d.member || Number(r.score) !== Number(d.score)) {
+            mismatches.push({ key: keyName, reason: 'zset member/score mismatch' });
+            break;
+          }
+        }
+        if (mismatches[mismatches.length - 1]?.key === keyName) continue;
+      }
+
+      matched++;
+    } catch (err) {
+      mismatches.push({ key: keyName, reason: err.message });
+    }
+  }
+
+  return { sampled: keyList.length, matched, mismatches };
+}

package/src/server/connection.js

@@ -6,36 +6,78 @@ import { RESPReader } from '../resp/parser.js';
 import { dispatch } from '../commands/registry.js';
 import { encode, encodeSimpleString, encodeError } from '../resp/encoder.js';
 
+let nextConnectionId = 0;
+
 /**
  * @param {import('net').Socket} socket
  * @param {object} engine
  */
 export function handleConnection(socket, engine) {
   const reader = new RESPReader();
+  const connectionId = ++nextConnectionId;
+  const context = {
+    connectionId,
+    writeResponse(buf) {
+      if (socket.writable) socket.write(buf);
+    },
+  };
+
+  function writeResult(out) {
+    if (out.quit) {
+      socket.write(encodeSimpleString('OK'));
+      socket.end();
+      return true;
+    }
+    let buf;
+    if (out.error) {
+      buf = encodeError(out.error);
+    } else if (out.result && typeof out.result === 'object' && out.result.simple !== undefined) {
+      buf = encodeSimpleString(out.result.simple);
+    } else if (out.result && typeof out.result === 'object' && out.result.error !== undefined) {
+      buf = encodeError(out.result.error);
+    } else {
+      buf = encode(out.result);
+    }
+    socket.write(buf);
+    return false;
+  }
 
   socket.on('data', (chunk) => {
     reader.feed(chunk);
     const commands = reader.parseCommands();
     for (const argv of commands) {
-      const out = dispatch(engine, argv);
+      const out = dispatch(engine, argv, context);
       if (out.quit) {
-        socket.write(encodeSimpleString('OK'));
-        socket.end();
+        writeResult(out);
         return;
       }
-      let buf;
-      if (out.error) {
-        buf = encodeError(out.error);
-      } else if (out.result && typeof out.result === 'object' && out.result.simple !== undefined) {
-        buf = encodeSimpleString(out.result.simple);
-      } else if (out.result && typeof out.result === 'object' && out.result.error !== undefined) {
-        buf = encodeError(out.result.error);
-      } else {
-        buf = encode(out.result);
+      if (out.block) {
+        const { keys, kind, timeoutSeconds } = out.block;
+        const blockingManager = engine._blockingManager;
+        if (!blockingManager) {
+          socket.write(encodeError('ERR blocking not available'));
+          continue;
+        }
+        const resolve = (value) => {
+          const buf = value === null ? encode(null) : encode(value);
+          context.writeResponse(buf);
+          socket.resume();
+        };
+        const err = blockingManager.registerWaiter(keys, kind, timeoutSeconds, resolve, connectionId);
+        if (err.error) {
+          socket.write(encodeError(err.error));
+          continue;
+        }
+        socket.pause();
+        return;
       }
-      socket.write(buf);
+      if (writeResult(out)) return;
     }
   });
 
+  socket.on('close', () => {
+    if (engine._blockingManager) engine._blockingManager.cancel(connectionId);
+  });
+
   socket.on('error', () => {});
 }

package/src/storage/sqlite/db.js

@@ -5,6 +5,7 @@
 import Database from 'better-sqlite3';
 import { applyPragmas } from './pragmas.js';
 import { applySchema } from './schema.js';
+import { applyMigrationSchema } from './migration-schema.js';
 
 /**
  * @param {string} path - Database file path
@@ -16,5 +17,6 @@ export function openDb(path, options = {}) {
   const db = new Database(path, dbOptions);
   applyPragmas(db, pragmaTemplate);
   applySchema(db);
+  applyMigrationSchema(db);
   return db;
 }

package/src/storage/sqlite/migration-schema.js

@@ -0,0 +1,66 @@
+/**
+ * Migration registry schema (SPEC_F §F.5.1).
+ * Tables: migration_runs, migration_dirty_keys, migration_errors.
+ */
+
+export const MIGRATION_SCHEMA = `
+CREATE TABLE IF NOT EXISTS migration_runs (
+  run_id TEXT PRIMARY KEY,
+  source_uri TEXT NOT NULL,
+  started_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL,
+  status TEXT NOT NULL,
+
+  scan_cursor TEXT NOT NULL DEFAULT "0",
+  scan_count_hint INTEGER NOT NULL DEFAULT 1000,
+
+  scanned_keys INTEGER NOT NULL DEFAULT 0,
+  migrated_keys INTEGER NOT NULL DEFAULT 0,
+  skipped_keys INTEGER NOT NULL DEFAULT 0,
+  error_keys INTEGER NOT NULL DEFAULT 0,
+  migrated_bytes INTEGER NOT NULL DEFAULT 0,
+
+  dirty_keys_seen INTEGER NOT NULL DEFAULT 0,
+  dirty_keys_applied INTEGER NOT NULL DEFAULT 0,
+  dirty_keys_deleted INTEGER NOT NULL DEFAULT 0,
+
+  last_error TEXT
+);
+
+CREATE TABLE IF NOT EXISTS migration_dirty_keys (
+  run_id TEXT NOT NULL,
+  key BLOB NOT NULL,
+
+  first_seen_at INTEGER NOT NULL,
+  last_seen_at INTEGER NOT NULL,
+  events_count INTEGER NOT NULL DEFAULT 1,
+
+  last_event TEXT,
+  state TEXT NOT NULL DEFAULT "dirty",
+
+  PRIMARY KEY (run_id, key)
+);
+
+CREATE INDEX IF NOT EXISTS migration_dirty_keys_state_idx
+  ON migration_dirty_keys(run_id, state);
+
+CREATE INDEX IF NOT EXISTS migration_dirty_keys_last_seen_idx
+  ON migration_dirty_keys(run_id, last_seen_at);
+
+CREATE TABLE IF NOT EXISTS migration_errors (
+  run_id TEXT NOT NULL,
+  at INTEGER NOT NULL,
+  key BLOB,
+  stage TEXT NOT NULL,
+  message TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS migration_errors_at_idx ON migration_errors(run_id, at);
+`;
+
+/**
+ * Apply migration registry schema to database.
+ * @param {import('better-sqlite3').Database} db
+ */
+export function applyMigrationSchema(db) {
+  db.exec(MIGRATION_SCHEMA);
+}

package/tasks/todo.md

@@ -23,3 +23,22 @@
 ## Not in scope (SPEC §26.3)
 
 - RDB parsing, AOF parsing, mirror mode, dual-write
+
+---
+
+# Migration with Dirty Key Registry (SPEC_F)
+
+## Done
+
+- [x] Migration schema: `migration_runs`, `migration_dirty_keys`, `migration_errors` in `src/storage/sqlite/migration-schema.js`
+- [x] Registry layer: `src/migration/registry.js` (createRun, getRun, updateBulkProgress, upsertDirtyKey, getDirtyBatch, markDirtyState, logError, getDirtyCounts)
+- [x] Bulk importer: `src/migration/bulk.js` with run_id, checkpointing, resume, max_rps, batch_keys/batch_bytes, pause/abort via status
+- [x] Shared import-one: `src/migration/import-one.js` (fetch key from Redis + write to storages; used by bulk and apply-dirty)
+- [x] Delta apply: `src/migration/apply-dirty.js` (apply dirty keys from registry: reimport or delete in destination)
+- [x] Preflight: `src/migration/preflight.js` (key count, type distribution, notify-keyspace-events check, recommendations)
+- [x] Verify: `src/migration/verify.js` (sample keys, compare Redis vs RespLite)
+- [x] CLI `resplite-import`: `src/cli/resplite-import.js` (preflight, bulk, status, apply-dirty, verify)
+- [x] CLI `resplite-dirty-tracker`: `src/cli/resplite-dirty-tracker.js` (start = PSUBSCRIBE keyevent, stop = update run status)
+- [x] package.json `bin`: resplite-import, resplite-dirty-tracker
+- [x] Unit tests: `test/unit/migration-registry.test.js`
+- [x] README: minimal-downtime migration flow and commands