@ancleto/spec 0.15.3 → 0.16.0

package/README.md

@@ -401,8 +401,14 @@ ancleto memory list [--type rule|decision] [--scope project|feature|task] [--all
                           # Lista los nodos de memoria (read-only: no toca la base)
 
 ancleto memory doctor [--rebuild]
-                          # Diagnostica la base de memoria, reconstruye el índice FTS5 y
-                          # fusiona el WAL en el .db (deja la base segura para copiar)
+                          # Diagnostica la base de memoria (read-only por defecto);
+                          # --rebuild es el único camino que escribe y reconstruye el índice FTS5
+
+ancleto memory snapshot --out <archivo.db> [--force] [--json]
+                          # Copia consistente de la base vía VACUUM INTO
+
+ancleto memory merge --target <key> --sources <k1,k2,...> [--dry-run] [--json]
+                          # Fusiona nodos fuente en el target y supersede los sources
 
 ancleto mcp               # Servidor MCP de memoria propia (stdio): lo consume tu IDE
 
@@ -422,7 +428,7 @@ Funciona en tres piezas que comparten el mismo archivo:
 |---|---|
 | **Almacenamiento** | Reglas y decisiones con supersesión atómica por `memory_key` (una sola activa por clave). |
 | **Tools del LLM** (`ancleto mcp`) | Servidor MCP local, sin dependencias, que expone tres herramientas a tu IDE. |
-| **CLI** | `ancleto memory context` materializa el bloque `<ProjectMemoryRules>`, `ancleto memory list` permite inspeccionar los nodos sin escribir, y `ancleto memory doctor` verifica integridad, reconstruye el índice FTS5 y fusiona el WAL. |
+| **CLI** | `ancleto memory context` materializa el bloque `<ProjectMemoryRules>`, `ancleto memory list` permite inspeccionar los nodos sin escribir, y `ancleto memory doctor` verifica integridad (read-only por defecto; `--rebuild` reconstruye el índice FTS5). |
 
 | Herramienta | Función |
 |---|---|

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ancleto/spec",
-  "version": "0.15.3",
+  "version": "0.16.0",
   "description": "Orquestador SDD liviano con subagentes optimizados para costo/tokens",
   "type": "module",
   "bin": {

package/src/cli/index.js

@@ -9,8 +9,9 @@ import { join, dirname, resolve, basename, relative, isAbsolute } from 'node:pat
 import { fileURLToPath } from 'node:url'
 import { homedir, tmpdir } from 'node:os'
 import { createMemoryEngine, createReadonlyMemoryEngine, defaultMemoryDbPath } from '../core/memory/engine.js'
+import { snapshotDatabase } from '../core/memory/snapshot.js'
 import { adaptFrontmatter, parseFrontmatter } from '../core/adapters/frontmatter.js'
-import { writeWorkingContext, writeWorkingContextBlock, renderWorkingContextBlock, resolveMemoryProjectRoot, checkWorkingContextFreshness, refreshWorkingContextOnWrite } from '../core/memory/working-context.js'
+import { writeWorkingContext, writeWorkingContextBlock, workingContextPath, renderWorkingContextBlock, resolveMemoryProjectRoot, checkWorkingContextFreshness, refreshWorkingContextOnWrite } from '../core/memory/working-context.js'
 import { materializeMachineEnv, checkMachineEnvTracked } from '../core/machine-env.js'
 import { memoryDoctor } from '../core/memory/doctor.js'
 import { serveMemoryMcp } from '../core/memory/mcp-server.js'
@@ -91,6 +92,10 @@ ancleto memory doctor [--rebuild] Diagnostica .ancleto/memory.db (integridad, FT
   ancleto memory export [--out <archivo>]  Exporta nodos activos a JSON (stdout o archivo)
   ancleto memory import <archivo>          Importa nodos desde JSON (upsert por memory_key, idempotente)
   ancleto memory gc [--dry-run] [--days N] Purga superseded con antiguedad > N dias (default 30)
+  ancleto memory snapshot --out <archivo.db> [--force] [--json]
+                                   Copia consistente de la memoria (incluye historial; --force sobrescribe)
+  ancleto memory merge --target <key> --sources <k1,k2,...> [--dry-run] [--json]
+                                   Supersede cada source activa hacia el target (sin crear nodos)
   ancleto mcp                           Servidor MCP de memoria propia (stdio) para tu IDE
                                         expone searchMemory, recordRule y recordDecision
   ancleto check                         Verifica integridad de archivos instalados vs manifiesto
@@ -2240,7 +2245,7 @@ async function memoryDoctorCmd(flags) {
   const { checks, healthy, rebuilt } = memoryDoctor(dbPath, { rebuild })
   if (rebuilt) console.log('ancleto: indice FTS5 reconstruido')
   for (const c of checks) {
-    console.log(`  ${c.ok ? '✔' : '✖'} ${c.name}: ${c.detail}`)
+    console.log(`  ${c.skipped ? '−' : c.ok ? '✔' : '✖'} ${c.name}: ${c.detail}`)
   }
   // Frescura del working-context: advisory, no afecta el exit code (que sigue midiendo
   // la integridad de la DB). Read-only: no reescribe el artefacto.
@@ -2393,6 +2398,103 @@ async function memoryGc(flags) {
   }
 }
 
+// `flagValue` devuelve el token siguiente sin mirar si es otro flag. En los
+// comandos con flags obligatorios, un valor vacio o que empieza con `--` cuenta
+// como flag faltante (sin cambiar el helper global que usan otros comandos).
+function requiredMemoryFlag(flags, flag) {
+  const value = flagValue(flags, flag)
+  return value && !value.startsWith('--') ? value : null
+}
+
+async function memorySnapshot(flags) {
+  const out = requiredMemoryFlag(flags, '--out')
+  if (!out) {
+    console.error('ancleto: uso: ancleto memory snapshot --out <archivo.db> [--force] [--json]')
+    process.exitCode = 1
+    return
+  }
+  const dbPath = defaultMemoryDbPath()
+  if (!(await exists(dbPath))) {
+    console.error(`ancleto: no hay memoria en este repo (${dbPath})`)
+    process.exitCode = 1
+    return
+  }
+  let result
+  try {
+    result = snapshotDatabase(dbPath, resolve(out), { overwrite: flags.includes('--force') })
+  } catch (err) {
+    console.error(`ancleto: no se pudo crear el snapshot: ${err.message}`)
+    process.exitCode = 1
+    return
+  }
+  if (flags.includes('--json')) {
+    console.log(JSON.stringify({ out: result.out, bytes: result.bytes }))
+  } else {
+    console.log(`ancleto: snapshot escrito en ${result.out} (${result.bytes} bytes)`)
+  }
+}
+
+async function memoryMerge(flags) {
+  const target = requiredMemoryFlag(flags, '--target')
+  const sourcesRaw = requiredMemoryFlag(flags, '--sources')
+  if (!target || !sourcesRaw) {
+    console.error('ancleto: uso: ancleto memory merge --target <key> --sources <k1,k2,...> [--dry-run] [--json]')
+    process.exitCode = 1
+    return
+  }
+  const sources = sourcesRaw.split(',').map((s) => s.trim()).filter(Boolean)
+  if (sources.length === 0) {
+    console.error('ancleto: uso: ancleto memory merge --target <key> --sources <k1,k2,...> [--dry-run] [--json]')
+    process.exitCode = 1
+    return
+  }
+  const dryRun = flags.includes('--dry-run')
+  const dbPath = defaultMemoryDbPath()
+  if (!(await exists(dbPath))) {
+    console.error(`ancleto: no hay memoria en este repo (${dbPath})`)
+    process.exitCode = 1
+    return
+  }
+  // `createMemoryEngine` aplica `PRAGMA journal_mode=WAL` y migraciones al abrir;
+  // un dry-run no debe escribir ni la base ni sus sidecars, asi que usa la
+  // conexion read-only (su `merge` solo acepta `dryRun: true`).
+  const engine = dryRun ? createReadonlyMemoryEngine(dbPath) : createMemoryEngine(dbPath)
+  try {
+    let result
+    try {
+      result = engine.merge({ target, sources, dryRun })
+    } catch (err) {
+      console.error(`ancleto: merge rechazado: ${err.message}`)
+      process.exitCode = 1
+      return
+    }
+    if (result.dryRun) {
+      if (flags.includes('--json')) console.log(JSON.stringify(result))
+      else console.log(`ancleto: merge --dry-run -> target ${result.target}; sources ${result.sources.join(', ')}; ${result.superseded} nodo(s) a superseder`)
+      return
+    }
+    // Mismo render que el refresh on-write de `import`; la raiz se deriva del
+    // directorio de la DB, no de process.cwd() (aisla fixtures en tmpdir).
+    const projectRoot = resolveMemoryProjectRoot(dbPath)
+    try {
+      refreshWorkingContextOnWrite(engine, projectRoot)
+    } catch (err) {
+      // El merge ya quedo commiteado en la base: no se revierte. Reportar exito
+      // sobre un bloque derivado desactualizado seria mentir; salir != 0 y decir
+      // exactamente que si se aplico, que quedo viejo y como regenerarlo.
+      const ctxPath = workingContextPath(projectRoot)
+      console.error(`ancleto: el merge SI se aplico en la base (${result.superseded} nodo(s) superseded hacia ${result.target}), pero el bloque derivado ${ctxPath} quedo desactualizado: ${err.message}`)
+      console.error(`ancleto: regenera el bloque con: ancleto memory context --out ${ctxPath}`)
+      process.exitCode = 1
+      return
+    }
+    if (flags.includes('--json')) console.log(JSON.stringify(result))
+    else console.log(`ancleto: merge OK -> ${result.superseded} nodo(s) superseded hacia ${result.target}`)
+  } finally {
+    engine.close()
+  }
+}
+
 async function memoryCmd(args) {
   const [sub, ...flags] = args
   if (sub === 'context') {
@@ -2419,6 +2521,14 @@ async function memoryCmd(args) {
     await memoryGc(flags)
     return
   }
+  if (sub === 'snapshot') {
+    await memorySnapshot(flags)
+    return
+  }
+  if (sub === 'merge') {
+    await memoryMerge(flags)
+    return
+  }
   console.error(`ancleto: subcomando de memory desconocido: ${sub || '(ninguno)'}`)
   console.error('ancleto: uso: ancleto memory context [--scope X] [--out file]')
   console.error('ancleto: uso: ancleto memory list [--type X] [--scope X] [--all] [--json]')
@@ -2426,6 +2536,8 @@ async function memoryCmd(args) {
   console.error('ancleto: uso: ancleto memory export [--out <archivo>]')
   console.error('ancleto: uso: ancleto memory import <archivo>')
   console.error('ancleto: uso: ancleto memory gc [--dry-run] [--days <n>]')
+  console.error('ancleto: uso: ancleto memory snapshot --out <archivo.db> [--force] [--json]')
+  console.error('ancleto: uso: ancleto memory merge --target <key> --sources <k1,k2,...> [--dry-run] [--json]')
   process.exit(1)
 }
 

package/src/core/memory/doctor.js

@@ -1,15 +1,47 @@
+import { statSync } from 'node:fs'
 import { openDatabase, checkpointDatabase } from './database.js'
 
+// Estado observable del WAL sin ejecutar checkpoint ni ningun pragma mutante:
+// solo se mira el tamano del archivo `-wal` que ya existe en disco.
+function observeWal(dbPath) {
+  try {
+    return `-wal presente (${statSync(`${dbPath}-wal`).size} bytes)`
+  } catch {
+    return 'sin -wal'
+  }
+}
+
 export function memoryDoctor(dbPath, { rebuild = false } = {}) {
-  const db = openDatabase(dbPath, { migrate: false })
+  // Default estrictamente read-only: sin migraciones, sin pragmas mutantes y sin
+  // checkpoint. `--rebuild` es el unico camino que abre en escritura.
+  const db = openDatabase(dbPath, rebuild ? { migrate: false } : { migrate: false, readonly: true })
+  let rebuilt = false
   try {
     const checks = []
 
     const hasSchema = db.prepare(`SELECT count(*) AS n FROM sqlite_master WHERE name = 'memory_nodes'`).get().n > 0
     if (!hasSchema) {
-      return { checks: [{ name: 'Integridad DB', ok: false, detail: 'esquema no inicializado' }], healthy: false, rebuilt: false }
+      // Error path: los cuatro nombres se conservan y cada check no ejecutable
+      // se reporta como falla con su motivo (nunca se omite del array).
+      const detail = 'esquema no inicializado'
+      return {
+        checks: [
+          { name: 'Integridad DB', ok: false, detail },
+          { name: 'Indice FTS5', ok: false, detail: `no verificable: ${detail}` },
+          { name: 'Reglas activas (unicidad)', ok: false, detail: `no verificable: ${detail}` },
+          { name: 'Checkpoint WAL', ok: false, detail: `no verificable: ${detail}` }
+        ],
+        healthy: false,
+        rebuilt: false
+      }
     }
 
+    // La existencia del indice se verifica aparte del conteo: sin `memory_fts`
+    // la busqueda no funciona (esquema parcial/legacy) y no es un chequeo
+    // omitido. La tabla sombra `memory_fts_docsize` solo existe si FTS5 se creo
+    // con el default `columnsize=1`.
+    const hasFts = db.prepare(`SELECT count(*) AS n FROM sqlite_master WHERE type = 'table' AND name = 'memory_fts'`).get().n > 0
+
     const quick = db.prepare('PRAGMA quick_check').get()
     const integrityOk = quick && quick.quick_check === 'ok'
     checks.push({
@@ -27,19 +59,45 @@ export function memoryDoctor(dbPath, { rebuild = false } = {}) {
       }
     }
 
-    let fts = runIntegrity()
-    let rebuilt = false
-    if (rebuild) {
-      db.exec(`INSERT INTO memory_fts(memory_fts) VALUES('rebuild')`)
-      rebuilt = true
-      const after = runIntegrity()
-      fts = { ok: after.ok, detail: after.ok ? 'indice reconstruido y consistente' : `reconstruccion sin exito: ${after.detail}` }
+    let fts
+    if (!hasFts) {
+      // Estado 1: el indice no existe. Aunque `memory_nodes` exista, la busqueda
+      // esta rota; se reporta como falla (nunca `skipped`) y baja `healthy`.
+      fts = { ok: false, detail: 'indice FTS5 ausente; la busqueda no funciona' }
+    } else if (rebuild) {
+      try {
+        db.exec(`INSERT INTO memory_fts(memory_fts) VALUES('rebuild')`)
+        rebuilt = true
+        const after = runIntegrity()
+        fts = { ok: after.ok, detail: after.ok ? 'indice reconstruido y consistente' : `reconstruccion sin exito: ${after.detail}` }
+      } catch (err) {
+        fts = { ok: false, detail: `reconstruccion fallo: ${err.message}` }
+      }
+    } else {
+      // Chequeo no mutante de alineacion. `count(*)` sobre `memory_fts` (external
+      // content) NO sirve: FTS5 lo resuelve contra `memory_nodes`, asi que un nodo
+      // sin indexar igual se cuenta. La tabla sombra `%_docsize` (default
+      // columnsize=1) tiene una fila por documento efectivamente indexado, y su
+      // conteo equivale a "filas indexadas". El integrity-check completo (INSERT
+      // de control) escribe y queda solo para `--rebuild`.
+      try {
+        const indexed = db.prepare('SELECT count(*) AS n FROM memory_fts_docsize').get().n
+        const total = db.prepare('SELECT count(*) AS n FROM memory_nodes').get().n
+        fts = indexed === total
+          ? { ok: true, detail: `${indexed} filas indexadas, coincide con memory_nodes (${total} nodos); integridad completa no verificable en read-only` }
+          : { ok: false, detail: `${indexed} filas indexadas vs ${total} nodos; indice desalineado, usar --rebuild` }
+      } catch (err) {
+        // No poder verificar no es una falla (D2): p. ej. un FTS5 creado con
+        // `columnsize=0` no materializa la tabla sombra `memory_fts_docsize`.
+        // El check se reporta omitido y no baja `healthy` ni el exit code.
+        fts = {
+          ok: true,
+          skipped: true,
+          detail: `omitido: alineacion de FTS no verificable (${err.message}); integridad completa no verificable en read-only`
+        }
+      }
     }
-    checks.push({
-      name: rebuilt ? 'Indice FTS5 (post-rebuild)' : 'Indice FTS5',
-      ok: fts.ok,
-      detail: fts.detail
-    })
+    checks.push({ name: 'Indice FTS5', ok: fts.ok, ...(fts.skipped ? { skipped: true } : {}), detail: fts.detail })
 
     const dups = db.prepare(`SELECT memory_key, COUNT(*) AS n FROM memory_nodes
       WHERE status = 'active' GROUP BY memory_key HAVING n > 1`).all()
@@ -49,13 +107,21 @@ export function memoryDoctor(dbPath, { rebuild = false } = {}) {
       detail: dups.length === 0 ? 'una sola activa por memory_key' : dups.map((d) => `${d.memory_key} x${d.n}`).join(', ')
     })
 
-    // Deja el WAL fusionado en el .db: una copia del archivo no pierde datos.
-    const checkpointed = checkpointDatabase(db)
-    checks.push({
-      name: 'Checkpoint WAL',
-      ok: checkpointed,
-      detail: checkpointed ? 'WAL fusionado en el .db (seguro para copiar)' : 'no se pudo checkpointear (DB en uso por otro proceso)'
-    })
+    if (rebuild) {
+      const checkpointed = checkpointDatabase(db)
+      checks.push({
+        name: 'Checkpoint WAL',
+        ok: checkpointed,
+        detail: checkpointed ? 'WAL fusionado en el .db (seguro para copiar)' : 'no se pudo checkpointear (DB en uso por otro proceso)'
+      })
+    } else {
+      checks.push({
+        name: 'Checkpoint WAL',
+        ok: true,
+        skipped: true,
+        detail: `omitido: no verificable en modo read-only; ${observeWal(dbPath)}`
+      })
+    }
 
     return { checks, healthy: checks.every((c) => c.ok), rebuilt }
   } finally {

package/src/core/memory/engine.js

@@ -91,13 +91,28 @@ export function createMemoryEngine(dbPath = defaultMemoryDbPath()) {
 // Apertura read-only: sin migraciones ni escrituras. Pensada para inspeccionar
 // la memoria sin tocar el WAL ni modificar archivos.
 export function createReadonlyMemoryEngine(dbPath = defaultMemoryDbPath()) {
-  return buildEngine(openDatabase(dbPath, { migrate: false, readonly: true }))
+  return buildReadonlyEngine(openDatabase(dbPath, { migrate: false, readonly: true }))
+}
+
+// Misma superficie que el engine de escritura. `merge` solo puede planificar:
+// una corrida real se rechaza antes de tocar la conexion read-only, y el plan
+// sale de la validacion compartida (`validateMerge`), identico al de escritura.
+function buildReadonlyEngine(db) {
+  const engine = buildEngine(db)
+  return {
+    ...engine,
+    merge({ target, sources, dryRun = false } = {}) {
+      if (!dryRun) throw new Error('merge: la conexion es read-only')
+      return engine.merge({ target, sources, dryRun: true })
+    }
+  }
 }
 
 function buildEngine(db) {
 
-  const findActive = db.prepare(`SELECT id FROM memory_nodes WHERE memory_key = ? AND status = 'active'`)
+  const findActive = db.prepare(`SELECT id, type FROM memory_nodes WHERE memory_key = ? AND status = 'active'`)
   const findActiveRow = db.prepare(`SELECT id, created_at FROM memory_nodes WHERE memory_key = ? AND status = 'active'`)
+  const findLatestStatus = db.prepare(`SELECT status FROM memory_nodes WHERE memory_key = ? ORDER BY rowid DESC LIMIT 1`)
   const countSuperseded = db.prepare(`SELECT COUNT(*) AS c FROM memory_nodes WHERE memory_key = ? AND status = 'superseded'`)
   const supersede = db.prepare(`UPDATE memory_nodes SET status = 'superseded', superseded_by = ? WHERE id = ? AND status = 'active'`)
   const insertNode = db.prepare(
@@ -372,9 +387,82 @@ function buildEngine(db) {
     return checkpointDatabase(db)
   }
 
+  // Validacion compartida por el engine de escritura y el read-only: deja el
+  // plan listo y falla cerrado (target activo, sources activas, sin repetidas y
+  // con `type` identico) antes de abrir cualquier transaccion.
+  function validateMerge({ target, sources } = {}) {
+    const targetKey = String(target || '').trim()
+    if (!targetKey) throw new Error('merge: target es obligatorio')
+    if (!Array.isArray(sources) || sources.length === 0) throw new Error('merge: sources debe ser una lista no vacia')
+
+    const sourceKeys = sources.map((s) => String(s || '').trim())
+    const seen = new Set()
+    for (const key of sourceKeys) {
+      if (!key) throw new Error('merge: memory_key vacia en sources')
+      if (seen.has(key)) throw new Error(`merge: source repetida: ${key}`)
+      seen.add(key)
+    }
+
+    const targetRow = findActive.get(targetKey)
+    if (!targetRow) throw new Error(`merge: target "${targetKey}" no es un nodo activo existente`)
+
+    const sourceIds = []
+    for (const key of sourceKeys) {
+      if (key === targetKey) throw new Error(`merge: source "${key}" es igual al target`)
+      const row = findActive.get(key)
+      if (!row) {
+        const latest = findLatestStatus.get(key)
+        if (latest) throw new Error(`merge: source "${key}" no esta activa (status: ${latest.status})`)
+        throw new Error(`merge: source "${key}" no existe`)
+      }
+      if (row.type !== targetRow.type) {
+        throw new Error(`merge: type incompatible entre target "${targetKey}" (${targetRow.type}) y source "${key}" (${row.type})`)
+      }
+      sourceIds.push(row.id)
+    }
+
+    return { targetKey, sourceKeys, sourceIds }
+  }
+
+  // Consolida duplicados supersediendo cada source activa hacia un target activo,
+  // sin insertar nodos ni aceptar contenido. Valida todo antes de escribir y usa
+  // una unica transaccion: cualquier violacion deja la base intacta. `dryRun` no
+  // abre transaccion ni escribe.
+  function merge({ target, sources, dryRun = false } = {}) {
+    const { targetKey, sourceKeys, sourceIds } = validateMerge({ target, sources })
+    const plan = { target: targetKey, sources: sourceKeys, superseded: sourceIds.length }
+    if (dryRun) return { dryRun: true, ...plan }
+
+    db.exec('BEGIN IMMEDIATE')
+    let superseded = 0
+    try {
+      // Revalidacion bajo lock: el target pudo quedar superseded entre la
+      // validacion previa y la transaccion, y las sources quedarian enlazadas a
+      // un nodo inactivo.
+      const lockedTarget = findActive.get(targetKey)
+      if (!lockedTarget) {
+        throw new Error(`merge: el target "${targetKey}" dejo de estar activo durante la transaccion`)
+      }
+      for (const id of sourceIds) {
+        const result = supersede.run(lockedTarget.id, id)
+        superseded += Number(result.changes || 0)
+      }
+      // Si una source dejo de estar activa entre la validacion y el UPDATE,
+      // `changes` es 0: se aborta y se revierte todo.
+      if (superseded !== sourceIds.length) {
+        throw new Error('merge: una source dejo de estar activa durante la transaccion')
+      }
+      db.exec('COMMIT')
+    } catch (err) {
+      db.exec('ROLLBACK')
+      throw err
+    }
+    return { dryRun: false, ...plan }
+  }
+
   function close() {
     db.close()
   }
 
-  return { buildWorkingContext, searchMemory, recordNode, listNodes, exportActive, importNodes, gcSuperseded, checkpoint, close }
+  return { buildWorkingContext, searchMemory, recordNode, listNodes, exportActive, importNodes, gcSuperseded, merge, checkpoint, close }
 }

package/src/core/memory/snapshot.js

@@ -0,0 +1,126 @@
+import { existsSync, mkdirSync, realpathSync, renameSync, rmSync, statSync } from 'node:fs'
+import { randomUUID } from 'node:crypto'
+import { basename, dirname, join, resolve } from 'node:path'
+import { DatabaseSync } from 'node:sqlite'
+
+// Copia consistente de la base de memoria con historial (incluye superseded y
+// superseded_by, a diferencia de `memory export`). No usa `openDatabase`: ese
+// helper fija `PRAGMA journal_mode=WAL` y mutaria la fuente. Se abre una conexion
+// directa read-only, sin pragmas ni migraciones: `VACUUM INTO` lee el estado
+// commiteado (incluido el WAL) sin escribir la fuente.
+// Identidad de archivo, no identidad de string: `path.resolve()` no normaliza
+// mayusculas en Windows ni resuelve symlinks/junctions. Para una ruta que todavia
+// no existe se resuelve el ancestro existente mas cercano y se recompone el resto.
+function realpathish(p) {
+  const abs = resolve(p)
+  if (existsSync(abs)) return realpathSync.native(abs)
+  const tail = []
+  let cur = abs
+  for (;;) {
+    const parent = dirname(cur)
+    if (parent === cur) return abs
+    if (existsSync(parent)) {
+      return join(realpathSync.native(parent), basename(cur), ...tail.reverse())
+    }
+    tail.push(basename(cur))
+    cur = parent
+  }
+}
+
+function sameFile(a, b) {
+  let ca = realpathish(a)
+  let cb = realpathish(b)
+  if (process.platform === 'win32') {
+    ca = ca.toLowerCase()
+    cb = cb.toLowerCase()
+  }
+  return ca === cb
+}
+
+function vacuumInto(sourcePath, targetPath) {
+  const db = new DatabaseSync(sourcePath, { readOnly: true })
+  try {
+    // `VACUUM INTO` acepta una expresion SQL: el destino viaja como parametro
+    // vinculado, sin interpolar la ruta en el texto de la sentencia.
+    db.prepare('VACUUM INTO ?').run(targetPath)
+  } catch (err) {
+    throw new Error(`snapshot: VACUUM INTO fallo sobre la fuente read-only: ${err.message}`)
+  } finally {
+    db.close()
+  }
+}
+
+function verifySnapshot(targetPath) {
+  const check = new DatabaseSync(targetPath, { readOnly: true })
+  try {
+    const row = check.prepare('PRAGMA quick_check').get()
+    if (!row || row.quick_check !== 'ok') {
+      throw new Error(`snapshot: la verificacion quick_check fallo para ${targetPath}`)
+    }
+  } finally {
+    check.close()
+  }
+}
+
+// Reemplaza el destino recien despues de tener una copia verificada en el
+// temporal (mismo directorio = mismo volumen). En Windows `rename` no reemplaza
+// un destino existente: se aparta el viejo a un backup, se mueve la copia nueva
+// y solo entonces se borra el backup. Si el movimiento final falla, se restaura
+// el backup: en ningun camino de error se pierden a la vez el destino previo y
+// la copia nueva.
+function replaceDestination(tempPath, targetPath) {
+  if (!existsSync(targetPath)) {
+    renameSync(tempPath, targetPath)
+    return
+  }
+  const backup = `${targetPath}.bak-${randomUUID()}`
+  renameSync(targetPath, backup)
+  try {
+    renameSync(tempPath, targetPath)
+  } catch (err) {
+    try {
+      renameSync(backup, targetPath)
+    } catch {
+      // restauracion best-effort: se propaga el error original
+    }
+    throw err
+  }
+  try {
+    rmSync(backup, { force: true })
+  } catch {
+    // el snapshot ya quedo en su lugar: un .bak remanente no invalida la copia
+  }
+}
+
+export function snapshotDatabase(dbPath, outPath, { overwrite = false } = {}) {
+  if (!dbPath || !outPath) throw new Error('snapshot: se requieren la base fuente y la ruta destino')
+  const source = resolve(dbPath)
+  const out = resolve(outPath)
+  if (sameFile(source, out)) {
+    throw new Error(`snapshot: el destino no puede ser la fuente (${out})`)
+  }
+  if (!existsSync(source)) {
+    throw new Error(`snapshot: no existe la base fuente (${source})`)
+  }
+  if (existsSync(out) && !overwrite) {
+    throw new Error(`snapshot: el destino ya existe (${out}); usar overwrite/--force para reemplazarlo`)
+  }
+
+  mkdirSync(dirname(out), { recursive: true })
+  const temp = join(dirname(out), `.${basename(out)}.${process.pid}-${randomUUID()}.tmp`)
+  try {
+    vacuumInto(source, temp)
+    verifySnapshot(temp)
+    replaceDestination(temp, out)
+    return { out, bytes: statSync(out).size }
+  } catch (err) {
+    // La limpieza del temporal nunca debe reemplazar el error original. SQLite
+    // puede haber creado sidecars para el archivo temporal: se borran los tres.
+    try {
+      for (const file of [temp, `${temp}-wal`, `${temp}-shm`]) rmSync(file, { force: true })
+    } catch {
+      // best effort: el temporal queda huerfano pero el error original se propaga
+    }
+    throw err
+  }
+}