@saulwade/swl-ses 2.6.1 → 2.8.0

package/scripts/lib/runtime-bundle-installer.js

@@ -0,0 +1,586 @@
+'use strict';
+
+/**
+ * Único writer para instalar, actualizar y desinstalar bundles Core-3
+ * (T03) dentro de un home de runtime (`baseDir`). Journal transaccional
+ * por operación — backup -> stage (temp + fsync) -> swap (rename + fsync
+ * de directorio) -> marca `swapped` — con recuperación idempotente ante
+ * una corrida interrumpida (crash, kill, fault inyectada).
+ *
+ * Nunca activa hooks, grants ni autenticación: solo copia bytes ya
+ * verificados por el bundle (T01-T03) hacia las rutas que su propio
+ * locator declara, y solo borra rutas que un install anterior de este
+ * mismo módulo dejó registradas en `install-state.json`.
+ *
+ * @module scripts/lib/runtime-bundle-installer
+ */
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { esRuntimeBundleCompilado, leerArtefactoRuntime } = require('./runtime-compiler');
+
+const ESTADO_DIRNAME = '.swl-runtime-state';
+const TRANSACTION_FILE = 'transaction.json';
+const STATE_FILE = 'install-state.json';
+const BACKUPS_DIRNAME = 'backups';
+const MODOS = new Set(['install', 'update', 'uninstall']);
+
+function sha256(bytes) {
+  return crypto.createHash('sha256').update(bytes).digest('hex');
+}
+
+function estadoDir(baseDir) {
+  return path.join(baseDir, ESTADO_DIRNAME);
+}
+
+function transactionPath(baseDir) {
+  return path.join(estadoDir(baseDir), TRANSACTION_FILE);
+}
+
+function statePath(baseDir) {
+  return path.join(estadoDir(baseDir), STATE_FILE);
+}
+
+function backupsTransaccionPath(baseDir, transactionId) {
+  return path.join(estadoDir(baseDir), BACKUPS_DIRNAME, transactionId);
+}
+
+function backupPath(baseDir, transactionId, rutaRelativa) {
+  return path.join(backupsTransaccionPath(baseDir, transactionId), rutaRelativa);
+}
+
+/** Los backups solo existen para revertir ESTA transacción; una vez cerrada (commit o rollback), sobran. */
+function borrarBackupsTransaccion(baseDir, transactionId) {
+  fs.rmSync(backupsTransaccionPath(baseDir, transactionId), { recursive: true, force: true });
+}
+
+/**
+ * Punto de fallo determinístico para tests, mismo patrón que
+ * integrity-ledger.js/single-use-store.js: fuera de NODE_ENV=test la
+ * variable es ruido ignorado en producción salvo que además coincida,
+ * en cuyo caso es un error de configuración explícito (nunca una falla
+ * silenciosa en producción).
+ */
+function hitFault(punto) {
+  const objetivo = process.env.SWL_RUNTIME_INSTALLER_FAULT;
+  if (objetivo !== punto) return;
+  if (process.env.NODE_ENV !== 'test') {
+    throw Object.assign(new Error('fault injection fuera de NODE_ENV=test'), { code: 'FAULT_CONFIG_INVALID' });
+  }
+  throw Object.assign(new Error(`FAULT_INJECTED: ${punto}`), { code: 'FAULT_INJECTED', punto });
+}
+
+// ---------------------------------------------------------------------------
+// Primitivas de filesystem — mismo patrón que scripts/generar-harness-ir.js.
+// ---------------------------------------------------------------------------
+
+function leerJSONOpcional(ruta) {
+  try {
+    return JSON.parse(fs.readFileSync(ruta, 'utf8'));
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+function escribirTemporalYFsync(ruta, contenido) {
+  fs.mkdirSync(path.dirname(ruta), { recursive: true });
+  const temporal = `${ruta}.tmp-${process.pid}-${crypto.randomBytes(4).toString('hex')}`;
+  fs.writeFileSync(temporal, contenido, { flag: 'wx', mode: 0o600 });
+  const fd = fs.openSync(temporal, 'r+');
+  try {
+    fs.fsyncSync(fd);
+  } finally {
+    fs.closeSync(fd);
+  }
+  return temporal;
+}
+
+function sincronizarDirectorio(directorio) {
+  const fd = fs.openSync(directorio, 'r');
+  try {
+    fs.fsyncSync(fd);
+  } catch (error) {
+    const noSoportado = process.platform === 'win32' && ['EPERM', 'EINVAL'].includes(error.code);
+    if (!noSoportado) throw error;
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+function limpiarSiExiste(ruta) {
+  try {
+    fs.unlinkSync(ruta);
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
+}
+
+/** Escritura atómica: temp + fsync + rename + fsync de directorio. */
+function publicarAtomico(destino, contenido) {
+  const temporal = escribirTemporalYFsync(destino, contenido);
+  fs.renameSync(temporal, destino);
+  sincronizarDirectorio(path.dirname(destino));
+}
+
+function adquirirLock(baseDir) {
+  fs.mkdirSync(estadoDir(baseDir), { recursive: true });
+  const lockPath = path.join(estadoDir(baseDir), 'transaction.lock');
+  let fd;
+  try {
+    hitFault('before-lock-open');
+    fd = fs.openSync(lockPath, 'wx', 0o600);
+  } catch (error) {
+    if (error.code === 'EEXIST') {
+      throw Object.assign(new Error('otra transacción del instalador está en curso'), { code: 'LOCK_HELD' });
+    }
+    throw error;
+  }
+  // El PID queda escrito en el lock ANTES de que otro proceso pueda observarlo
+  // (la creación exclusiva ya se resolvió arriba): es lo único que permite
+  // distinguir después un lock huérfano (proceso muerto) de uno legítimamente
+  // en uso — sin esto ningún reclamo puede ser seguro (hallazgo del checker).
+  fs.writeSync(fd, String(process.pid));
+  fs.fsyncSync(fd);
+  return { fd, lockPath };
+}
+
+function pidDelLock(lockPath) {
+  let contenido;
+  try {
+    contenido = fs.readFileSync(lockPath, 'utf8').trim();
+  } catch {
+    return null;
+  }
+  const pid = Number(contenido);
+  return Number.isInteger(pid) && pid > 0 ? pid : null;
+}
+
+function procesoVive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true; // no lanzó: el proceso existe y es señalable
+  } catch (error) {
+    return error.code === 'EPERM'; // ESRCH = no existe; EPERM = existe pero sin permiso (conservador: vivo)
+  }
+}
+
+/** Un lock sin PID legible (corrupto o de una versión anterior) se trata como huérfano recuperable. */
+function lockEstaVivo(lockPath) {
+  const pid = pidDelLock(lockPath);
+  return pid !== null && procesoVive(pid);
+}
+
+function liberarLock(lock) {
+  try {
+    hitFault('before-lock-close');
+    fs.closeSync(lock.fd);
+  } catch {
+    /* best effort: un fd ya cerrado no debe impedir liberar el archivo del lock */
+  }
+  limpiarSiExiste(lock.lockPath);
+}
+
+// ---------------------------------------------------------------------------
+// Journal.
+// ---------------------------------------------------------------------------
+
+function escribirJournal(baseDir, journal) {
+  publicarAtomico(transactionPath(baseDir), JSON.stringify(journal, null, 2));
+}
+
+function leerJournal(baseDir) {
+  return leerJSONOpcional(transactionPath(baseDir));
+}
+
+function borrarJournal(baseDir) {
+  limpiarSiExiste(transactionPath(baseDir));
+}
+
+function crearTransactionId() {
+  return `${Date.now()}-${crypto.randomBytes(4).toString('hex')}`;
+}
+
+// ---------------------------------------------------------------------------
+// Estado instalado (install-state.json) — "el estado conoce cada archivo".
+// ---------------------------------------------------------------------------
+
+function leerEstadoInstalado(baseDir) {
+  return leerJSONOpcional(statePath(baseDir)) || { schemaVersion: '1.0.0', runtimeId: null, files: [] };
+}
+
+function escribirEstadoInstalado(baseDir, estado) {
+  publicarAtomico(statePath(baseDir), JSON.stringify(estado, null, 2));
+}
+
+function aplicarOperacionesAlEstado(estadoPrevio, runtimeId, operaciones) {
+  const porPath = new Map(estadoPrevio.files.map((f) => [f.path, f]));
+  for (const op of operaciones) {
+    if (op.accion === 'write') porPath.set(op.path, { path: op.path, sha256: op.nuevoSha256, bytes: op.bytes });
+    else porPath.delete(op.path);
+  }
+  return {
+    schemaVersion: '1.0.0',
+    runtimeId,
+    installedAt: new Date().toISOString(),
+    files: [...porPath.values()].sort((a, b) => a.path.localeCompare(b.path)),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Confinamiento de destino — el locator ya valida rutas relativas seguras
+// (runtime-artifact-verifier.js), pero el instalador escribe a disco real:
+// defensa en profundidad contra traversal si esa garantía llegara a fallar.
+//
+// El prefijo de string por sí solo NO basta: si un componente intermedio
+// de baseDir ya existe como symlink/junction hacia fuera, `path.resolve`
+// nunca lo detecta y la escritura/borrado real aterriza fuera de baseDir
+// (hallazgo del checker independiente en la revisión de T08). Se camina
+// cada componente con lstat ANTES de escribir y se rechaza cualquier
+// enlace en la cadena; un componente que todavía no existe es seguro por
+// construcción (mkdir/rename lo crean real, nunca siguen un enlace que
+// no existe todavía).
+// ---------------------------------------------------------------------------
+
+function throwPathEscape(rutaRelativa, motivo) {
+  throw Object.assign(new Error(`${motivo}: ${rutaRelativa}`), { code: 'PATH_ESCAPE' });
+}
+
+function verificarSinEnlaces(raizReal, rutaRelativa) {
+  const segmentos = rutaRelativa.split('/');
+  let actual = raizReal;
+  for (let indice = 0; indice < segmentos.length; indice += 1) {
+    actual = path.join(actual, segmentos[indice]);
+    let stat;
+    try {
+      stat = fs.lstatSync(actual);
+    } catch {
+      return; // no existe aún: el resto de la ruta se crea fresca, sin enlaces que seguir
+    }
+    if (stat.isSymbolicLink()) throwPathEscape(rutaRelativa, 'ruta contiene un enlace simbólico');
+    const esUltimoSegmento = indice === segmentos.length - 1;
+    if (!esUltimoSegmento && !stat.isDirectory()) {
+      throwPathEscape(rutaRelativa, 'componente intermedio no es un directorio');
+    }
+  }
+}
+
+function resolverDestinoConfinado(baseDir, rutaRelativa) {
+  const raiz = path.resolve(baseDir);
+  const raizReal = fs.realpathSync(raiz); // baseDir siempre existe: el caller lo crea antes de instalar
+  verificarSinEnlaces(raizReal, rutaRelativa);
+  const destino = path.resolve(raizReal, rutaRelativa);
+  const prefijo = raizReal.endsWith(path.sep) ? raizReal : raizReal + path.sep;
+  // Exige un prefijo ESTRICTO: una ruta relativa válida siempre queda DENTRO
+  // de baseDir, nunca coincide con baseDir mismo (ese caso solo ocurre con
+  // "" o "." — entrada corrupta que jamás debe tratarse como archivo).
+  if (!destino.startsWith(prefijo)) throwPathEscape(rutaRelativa, 'ruta fuera de baseDir');
+  return destino;
+}
+
+function leerBytesDestino(destino) {
+  try {
+    const bytes = fs.readFileSync(destino);
+    return { existe: true, bytes, sha256: sha256(bytes) };
+  } catch (error) {
+    if (error.code === 'ENOENT') return { existe: false, bytes: null, sha256: null };
+    throw error;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Planificación (pura, sin I/O de escritura).
+// ---------------------------------------------------------------------------
+
+function planificarInstalacion(bundle, baseDir) {
+  const operaciones = [];
+  for (const entry of bundle.locator.entries) {
+    const destino = resolverDestinoConfinado(baseDir, entry.path);
+    const actual = leerBytesDestino(destino);
+    if (actual.existe && actual.sha256 === entry.sha256) continue;
+    operaciones.push({
+      path: entry.path, destino, accion: 'write',
+      hadPrior: actual.existe, nuevoSha256: entry.sha256, estado: 'pending',
+    });
+  }
+  return operaciones;
+}
+
+function planificarDesinstalacion(estadoInstalado, baseDir) {
+  return estadoInstalado.files.map((archivo) => ({
+    path: archivo.path,
+    destino: resolverDestinoConfinado(baseDir, archivo.path),
+    accion: 'delete',
+    hadPrior: true,
+    nuevoSha256: null,
+    estado: 'pending',
+  }));
+}
+
+// ---------------------------------------------------------------------------
+// Backup + stage + swap por operación.
+// ---------------------------------------------------------------------------
+
+function respaldarOperacion(baseDir, transactionId, op) {
+  if (!op.hadPrior) return;
+  const actual = leerBytesDestino(op.destino);
+  if (!actual.existe) return; // ya no existe (borrado manual entre plan y ejecución): nada que respaldar
+  publicarAtomico(backupPath(baseDir, transactionId, op.path), actual.bytes);
+}
+
+/**
+ * Escribe el temporal y persiste su nombre EXACTO en el journal antes del
+ * rename — la recuperación limpia exactamente ese archivo, nunca un patrón
+ * de prefijo sobre el directorio (un glob `${base}.tmp-*` puede coincidir
+ * con un archivo real del usuario, ej. `CLAUDE.md.tmp-notas-personales`;
+ * hallazgo del checker independiente).
+ */
+function aplicarEscritura(baseDir, journal, bundle, op) {
+  const bytes = leerArtefactoRuntime(bundle, op.path);
+  // Defensa final antes de tocar disco: si el bundle entregara bytes que no
+  // coinciden con el hash que el propio locator declaró para esa ruta, es
+  // preferible fallar cerrado (la transacción completa se revierte) a
+  // instalar contenido no verificado.
+  if (sha256(bytes) !== op.nuevoSha256) {
+    throw Object.assign(new Error(`bytes del bundle no coinciden con el locator: ${op.path}`), { code: 'HASH_MISMATCH' });
+  }
+  op.temporal = escribirTemporalYFsync(op.destino, bytes);
+  escribirJournal(baseDir, journal); // persiste el nombre del temporal ANTES del punto de falla simulado
+  hitFault('after-stage');
+  fs.renameSync(op.temporal, op.destino);
+  sincronizarDirectorio(path.dirname(op.destino));
+  op.temporal = null;
+}
+
+function aplicarBorrado(op) {
+  limpiarSiExiste(op.destino);
+  sincronizarDirectorio(path.dirname(op.destino));
+}
+
+function ejecutarOperacion(bundle, baseDir, journal, op) {
+  respaldarOperacion(baseDir, journal.transactionId, op);
+  hitFault('after-backup');
+  op.estado = 'backed-up';
+  op.temporal = null;
+  escribirJournal(baseDir, journal);
+
+  if (op.accion === 'write') aplicarEscritura(baseDir, journal, bundle, op);
+  else aplicarBorrado(op);
+  hitFault('after-swap');
+
+  op.estado = 'swapped';
+  escribirJournal(baseDir, journal);
+}
+
+// ---------------------------------------------------------------------------
+// Rollback — reversible desde cualquier estado por-operación intermedio.
+// ---------------------------------------------------------------------------
+
+function restaurarDesdeBackup(baseDir, transactionId, op) {
+  const respaldo = backupPath(baseDir, transactionId, op.path);
+  let bytes;
+  try {
+    bytes = fs.readFileSync(respaldo);
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+    // hadPrior=true se fijó en planificación, pero el archivo ya no existía
+    // al momento de ejecutar (respaldarOperacion no crea backup en ese
+    // caso): no hay nada que restaurar, así que la reversión segura es
+    // asegurar que el destino tampoco exista (Nemesis pass2, F-02). Sin
+    // esto, un ENOENT aquí bloqueaba el instalador para siempre — cada
+    // recuperar()/aplicarBundle() futuro repetía el mismo throw.
+    limpiarSiExiste(op.destino);
+    return;
+  }
+  publicarAtomico(op.destino, bytes);
+}
+
+function revertirOperacion(baseDir, transactionId, op) {
+  if (op.estado === 'pending') return;
+  if (op.estado === 'backed-up' || op.estado === 'swapped') {
+    if (op.hadPrior) restaurarDesdeBackup(baseDir, transactionId, op);
+    else limpiarSiExiste(op.destino);
+  }
+  if (op.temporal) limpiarSiExiste(op.temporal);
+}
+
+function revertirTransaccion(baseDir, journal) {
+  for (const op of journal.operaciones) revertirOperacion(baseDir, journal.transactionId, op);
+  journal.status = 'rolled-back';
+  escribirJournal(baseDir, journal);
+  borrarJournal(baseDir);
+  borrarBackupsTransaccion(baseDir, journal.transactionId);
+}
+
+// ---------------------------------------------------------------------------
+// Recuperación idempotente.
+// ---------------------------------------------------------------------------
+
+/**
+ * Retoma cualquier transacción que haya quedado pendiente en `baseDir`
+ * (crash, kill, fault inyectada). Sin journal pendiente es un no-op —
+ * llamarla repetidamente es seguro por diseño. `status: 'in-progress'`
+ * (operaciones a medias) se REVIERTE; `status: 'operations-done'`
+ * (operaciones completas, falta cerrar el libro) se TERMINA — nunca al
+ * revés, o los archivos ya correctos en disco se revertirían a un estado
+ * viejo mientras install-state.json quedaría con el valor nuevo (o
+ * viceversa en uninstall), divergencia permanente (Nemesis pass2, F-01).
+ */
+function recuperar(baseDir) {
+  const journal = leerJournal(baseDir);
+  if (!journal) return { recuperado: false };
+  if (journal.status === 'operations-done') {
+    const lock = adquirirLockToleranteAPropio(baseDir);
+    try {
+      finalizarTransaccion(baseDir, journal);
+    } finally {
+      liberarLock(lock);
+    }
+    return { recuperado: true, transactionId: journal.transactionId };
+  }
+  if (journal.status !== 'in-progress') return { recuperado: false };
+  const lock = adquirirLockToleranteAPropio(baseDir);
+  try {
+    revertirTransaccion(baseDir, journal);
+  } finally {
+    liberarLock(lock);
+  }
+  return { recuperado: true, transactionId: journal.transactionId };
+}
+
+/**
+ * `recuperar()` puede correr como parte de aplicarBundle() sobre un lock ya
+ * huérfano (el proceso que lo tomó murió sin liberarlo). Reclamar SOLO
+ * procede cuando el PID grabado en el lock ya no vive — un lock cuyo dueño
+ * sigue vivo debe seguir bloqueando (LOCK_HELD real), nunca robarse: sin
+ * esta verificación dos instalaciones concurrentes sobre el mismo baseDir
+ * corren en paralelo y corrompen el journal compartido (hallazgo del
+ * checker independiente).
+ */
+function adquirirLockToleranteAPropio(baseDir) {
+  try {
+    return adquirirLock(baseDir);
+  } catch (error) {
+    if (error.code !== 'LOCK_HELD') throw error;
+    const lockPath = path.join(estadoDir(baseDir), 'transaction.lock');
+    if (lockEstaVivo(lockPath)) throw error;
+    limpiarSiExiste(lockPath);
+    return adquirirLock(baseDir);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// API pública.
+// ---------------------------------------------------------------------------
+
+function validarOpciones(opciones) {
+  if (!opciones || typeof opciones.baseDir !== 'string' || opciones.baseDir.length === 0) {
+    throw new TypeError('opciones.baseDir es requerido');
+  }
+  if (!MODOS.has(opciones.modo)) {
+    throw new TypeError(`opciones.modo debe ser uno de: ${[...MODOS].join(', ')}`);
+  }
+}
+
+function planificar(bundle, opciones) {
+  if (opciones.modo === 'uninstall') {
+    return planificarDesinstalacion(leerEstadoInstalado(opciones.baseDir), opciones.baseDir);
+  }
+  if (!esRuntimeBundleCompilado(bundle)) throw new TypeError('se requiere bundle verificado (T03)');
+  return planificarInstalacion(bundle, opciones.baseDir);
+}
+
+function resolverRuntimeId(bundle, opciones) {
+  return opciones.modo === 'uninstall'
+    ? leerEstadoInstalado(opciones.baseDir).runtimeId
+    : bundle.runtimeId;
+}
+
+/**
+ * Cola de una transacción cuyas operaciones YA llegaron a 'swapped' (los
+ * archivos en disco son correctos): recalcula el estado instalado desde
+ * disco real y cierra el journal. Reejecutable sin efectos adicionales —
+ * `escribirEstadoInstalado`/`escribirJournal` son publicaciones atómicas
+ * idempotentes, así que llamarla dos veces sobre el mismo journal produce
+ * el mismo resultado (necesario para que `recuperar()` pueda retomarla
+ * tras un crash a mitad de esta cola, Nemesis pass2 F-01).
+ */
+function finalizarTransaccion(baseDir, journal) {
+  const estadoPrevio = leerEstadoInstalado(baseDir);
+  // El estado persistido refleja lo que REALMENTE quedó en disco (tamaño y
+  // hash recalculados del archivo ya swapped), no lo que el locator declaró
+  // — "el estado conoce cada archivo" exige verificar, no solo confiar.
+  const opsConBytes = journal.operaciones.map((op) => {
+    if (op.accion !== 'write') return op;
+    const bytesEnDisco = fs.readFileSync(op.destino);
+    return { ...op, bytes: bytesEnDisco.length, nuevoSha256: sha256(bytesEnDisco) };
+  });
+  escribirEstadoInstalado(baseDir, aplicarOperacionesAlEstado(estadoPrevio, journal.runtimeId, opsConBytes));
+
+  journal.status = 'completed';
+  escribirJournal(baseDir, journal);
+  borrarJournal(baseDir);
+  borrarBackupsTransaccion(baseDir, journal.transactionId);
+}
+
+function ejecutarTransaccion(bundle, opciones, operaciones) {
+  const baseDir = baseDirDe(opciones);
+  const journal = {
+    schemaVersion: '1.0.0', transactionId: crearTransactionId(),
+    runtimeId: resolverRuntimeId(bundle, opciones), modo: opciones.modo,
+    startedAt: new Date().toISOString(), status: 'in-progress', operaciones,
+  };
+  escribirJournal(baseDir, journal);
+  for (const op of journal.operaciones) ejecutarOperacion(bundle, baseDir, journal, op);
+
+  // Punto de conmutación: a partir de aquí los archivos en disco YA son
+  // correctos (todas las operaciones llegaron a 'swapped'). Un crash
+  // DESPUÉS de este punto debe TERMINAR la transacción (finalizarTransaccion
+  // es idempotente), nunca revertir los archivos — sin este estado
+  // intermedio, recuperar() no podía distinguir "operaciones a medias"
+  // (revertir) de "operaciones completas, falta cerrar el libro" (terminar),
+  // y un crash entre escribir install-state.json y cerrar el journal dejaba
+  // install-state.json desincronizado del contenido real en disco de forma
+  // permanente, peor aún en uninstall (Nemesis pass2, F-01).
+  journal.status = 'operations-done';
+  escribirJournal(baseDir, journal);
+  hitFault('after-operations');
+
+  finalizarTransaccion(baseDir, journal);
+  return journal;
+}
+
+function baseDirDe(opciones) {
+  return opciones.baseDir;
+}
+
+/**
+ * Instala, actualiza o desinstala un bundle Core-3 en `opciones.baseDir` de
+ * forma transaccional. `bundle` es obligatorio para install/update (debe
+ * venir de `compilarRuntimeBundle`, T03) e ignorado en uninstall (usa el
+ * install-state.json previo). `opciones.dryRun` calcula el plan sin tocar
+ * disco — ni siquiera intenta recuperar una transacción huérfana.
+ */
+function aplicarBundle(bundle, opciones) {
+  validarOpciones(opciones);
+  if (opciones.dryRun) return { dryRun: true, operaciones: planificar(bundle, opciones) };
+
+  const recuperacion = recuperar(opciones.baseDir);
+  const lock = adquirirLockToleranteAPropio(opciones.baseDir);
+  try {
+    const operaciones = planificar(bundle, opciones);
+    if (operaciones.length === 0) return { recuperacion, operaciones: [], sinCambios: true };
+    const journal = ejecutarTransaccion(bundle, opciones, operaciones);
+    return { recuperacion, operaciones: journal.operaciones, sinCambios: false };
+  } finally {
+    liberarLock(lock);
+  }
+}
+
+module.exports = {
+  aplicarBundle,
+  recuperar,
+  leerEstadoInstalado,
+};