@hoilab/ada-cli 0.84.21 → 0.85.0

package/dist/core/audit/libro.d.ts

@@ -0,0 +1,318 @@
+/**
+ * Libro de sesión — qué HIZO el agente, en una cadena de hashes verificable.
+ *
+ * `memory-engine/audit.ts` ya tenía el mecanismo: JSONL append-only donde cada
+ * entrada lleva el hash de la anterior, de modo que alterar un registro se
+ * detecta reverificando la cadena. Lo que no tenía era ALCANCE: solo lo usaba
+ * el motor de memoria, así que auditábamos escrituras de memoria y no
+ * ejecuciones de tool, llamadas al modelo, ficheros tocados ni comandos.
+ *
+ * Este módulo aplica el mismo mecanismo a lo que un DPO pregunta de verdad, que
+ * es el registro del artículo 12 del AI Act y el 30 del RGPD.
+ *
+ * Dos decisiones de diseño que conviene no deshacer sin pensarlo:
+ *
+ * 1. **Minimización por defecto.** El libro guarda la FORMA de lo que pasó, no
+ *    su contenido: del fichero, su hash antes y después, nunca el texto. Un
+ *    registro de cumplimiento que copiara los datos sería un segundo almacén de
+ *    justo aquello que el RGPD quiere minimizar.
+ * 2. **Una sola canonicalización.** `memory-engine/audit.ts` construye la carga
+ *    a hashear dos veces, en `append` y en `verify`, con dos listas de campos
+ *    escritas a mano. Añadir un campo a una y olvidar la otra rompe la
+ *    verificación en silencio y solo para las entradas nuevas. Aquí la
+ *    verificación reconstruye la carga con un rest (`{hash, prevHash, ...resto}`),
+ *    así que un campo nuevo entra solo y las dos caras no pueden divergir.
+ */
+/** Lo que se le puede pedir al libro que anote. */
+export type SucesoDeSesion = {
+    tipo: "tool";
+    nombre: string;
+    ok: boolean;
+    decision?: string;
+    motivo?: string;
+} | {
+    tipo: "modelo";
+    proveedor: string;
+    modelo: string;
+    entrada: number;
+    salida: number;
+    coste?: number;
+    /** `stop`, `toolUse`, `error`, `aborted`… Un fallo del modelo también es auditable. */
+    motivoParada?: string;
+} | {
+    tipo: "comando";
+    argv: string[];
+    codigo: number;
+    sandbox?: "permitido" | "bloqueado";
+    violaciones?: string[];
+    /**
+     * Quién escribió el comando: el agente (por defecto, si se omite), el
+     * usuario desde la terminal integrada del escritorio, o una extensión
+     * a través de `pi.exec`.
+     *
+     * La terminal ejecuta lo que el usuario teclea SIN pasar por la
+     * política de aprobación — es su shell, no la del agente — así que este
+     * campo es lo único que evita que un registro de cumplimiento confunda
+     * "lo que decidió el agente" con "lo que tecleó la persona". Omitirlo
+     * en vez de dar por defecto "agente" habría dejado pasar en silencio
+     * una terminal que se le olvida anotarse.
+     *
+     * `extension` es el tercer estado, y hasta hoy faltaba: `pi.exec` no
+     * pasaba por la política NI dejaba rastro, así que una extensión leía
+     * el vault y el libro no lo sabía. Atribuirlo al "agente" habría sido
+     * peor que no anotarlo: quien audite tiene que poder distinguir lo que
+     * decidió el modelo de lo que hizo código de terceros cargado en el
+     * proceso.
+     */
+    origen?: "agente" | "usuario" | "extension";
+    /** Ruta de la extensión, cuando `origen` es `extension`. Sin ella el aviso no es accionable. */
+    extension?: string;
+} | {
+    /**
+     * Una purga por retención, anotada como HECHO en vez de dejada como
+     * hueco. Sin esto, cumplir el art. 5.1.e del RGPD hacía que
+     * `verificar` acusara de manipulación; y borrar también el índice
+     * hacía desaparecer la purga sin rastro. Ver `audit/retencion.ts`.
+     */
+    tipo: "purga";
+    fichero: string;
+    entradas: number;
+    desde: string;
+    hasta: string;
+    hashDeCierre: string;
+    politica: string;
+} | {
+    tipo: "fichero";
+    ruta: string;
+    antes: string | null;
+    despues: string | null;
+    tool: string;
+} | {
+    tipo: "red";
+    dominio: string;
+    permitido: boolean;
+    motivo?: string;
+} | {
+    /** El broker de credenciales (core/credenciales/) es lo que oh-my-pi no
+     * tiene: un registro de quién usó qué cuenta y cuándo. `accion` distingue
+     * PEDIR una credencial de REPORTAR cómo fue usarla. */
+    tipo: "credencial";
+    accion: "resuelta" | "uso";
+    proveedor: string;
+    /** `null` en "resuelta" = no había ninguna credencial activa (no es que fallara el libro). */
+    credencialId: string | null;
+    /** "ok" | "sin-credencial-activa" | una `ClaseDeError` de errores/proveedor.ts. */
+    resultado: string;
+    cliente?: string;
+};
+export interface EntradaDelLibro {
+    seq: number;
+    ts: string;
+    sesion: string;
+    suceso: Record<string, unknown>;
+    hash: string;
+    prevHash: string | null;
+}
+export interface Veredicto {
+    valido: boolean;
+    comprobadas: number;
+    /** Sello de tiempo de la primera entrada que no cuadra. */
+    alteradaEn?: string;
+    /**
+     * Fichero donde está esa entrada.
+     *
+     * Sin esto el veredicto decía «alterada en la del 03:09:55» sobre un
+     * directorio con 26 ficheros de sesión: cierto, verificable y no accionable.
+     * Quien recibe un aviso de manipulación necesita saber DÓNDE mirar, o el
+     * aviso se queda en susto.
+     */
+    ficheroAlterado?: string;
+    /**
+     * Por qué no verifica, en una frase estable.
+     *
+     * Existe para no confundir «lo he mirado y no cuadra» con «no lo he podido
+     * mirar»: un fichero ilegible y un hash que no coincide daban el mismo
+     * veredicto y el mismo mensaje, y son dos cosas distintas para quien
+     * responde a una auditoría.
+     */
+    motivo?: string;
+    /**
+     * Lo que FALTA: ficheros que el índice recuerda y que ya no están en
+     * `sesion/`, con cuántas entradas tenía cada uno.
+     *
+     * Es el tercer estado, y es el que faltaba. Antes de esto la cadena
+     * distinguía «íntegra» de «alterada» y nada más, así que borrar el fichero
+     * entero —lo que haría un agente tapando sus pasos— salía como
+     * `{valido: true, comprobadas: 0}`: un fallo que se lee como éxito en la
+     * pieza que se vende como prueba. Medido ejecutando el CLI: con tres
+     * comandos anotados decía «cadena íntegra: 3 entradas», y tras un `rm`
+     * decía «el libro está vacío» y salía con código 0.
+     */
+    faltan?: {
+        fichero: string;
+        entradas: number;
+    }[];
+    /**
+     * Ficheros que ya no están y cuya ausencia el libro EXPLICA con una lápida
+     * de purga. No cuentan como manipulación: son el art. 5.1.e cumplido.
+     */
+    purgados?: {
+        fichero: string;
+        entradas: number;
+        politica: string;
+    }[];
+    /**
+     * Sitios donde la cadena vuelve a empezar dentro de un mismo fichero.
+     *
+     * Ni íntegro ni alterado: el TERCER estado. Un reinicio del proceso lo
+     * produce, y quien quite entradas del medio y escriba una cadena nueva
+     * produce exactamente lo mismo. Desde el fichero no se distinguen, así que se
+     * dice dónde está y se deja que lo juzgue quien audita, en vez de acusar o de
+     * absolver por nuestra cuenta.
+     */
+    reinicios?: {
+        fichero: string;
+        ts: string;
+        entradasAntes: number;
+    }[];
+    /**
+     * Ficheros presentes en `sesion/` sin ancla en el índice.
+     *
+     * NO cuenta como manipulación y por eso va aparte de `faltan`: son los
+     * libros escritos antes de que el índice existiera, y también lo que queda
+     * en un sistema de ficheros sin enlaces duros. Meterlo en `valido: false`
+     * habría hecho que toda instalación ya existente gritara «manipulado» el
+     * día de la actualización — un detector que grita siempre no vale, y
+     * además volvería indistinguible la manipulación real.
+     */
+    sinAncla?: string[];
+}
+export declare class LibroDeSesion {
+    private readonly dir;
+    /** El índice: un enlace duro por fichero de sesión. Ver `DIR_INDICE`. */
+    private readonly dirIndice;
+    private readonly sesion;
+    private seq;
+    private ultimoHash;
+    /** Fijado en la primera escritura por `reservarFichero`; no cambia despues. */
+    private rutaFichero;
+    constructor(raiz: string, sesionId: string);
+    /**
+     * Un fichero por sesión, no uno por día.
+     *
+     * Compartir fichero entre sesiones parecía más ordenado y hacía el libro
+     * INVERIFICABLE, cosa que solo se vio ejecutando: cada proceso arranca su
+     * `seq` en 1 y su hash anterior en `null`, así que tres sesiones seguidas
+     * dejaban tres cadenas encadenadas dentro del mismo fichero y `verificar`
+     * fallaba en la primera entrada de la segunda.
+     *
+     * Arreglarlo cargando el último hash al abrir no habría bastado: el CLI y el
+     * escritorio corren a la vez, y dos procesos que leyeran el mismo hash
+     * anterior escribirían dos entradas con el mismo `prevHash`.
+     *
+     * El límite que esto dejaba, y que era el agujero: borrar el fichero de una
+     * sesión entera no lo detecta la cadena, que solo ve la modificación DENTRO
+     * de una sesión. Se documentaba aquí mientras el veredicto seguía diciendo
+     * `valido: true` — o sea, un fallo que se leía como éxito en la pieza que se
+     * vende como prueba. Lo cierra el índice de `reservarFichero`.
+     *
+     * «Un fichero, un escritor» es la PRECONDICIÓN de todo lo anterior, y por eso
+     * `reservarFichero` la impone en vez de confiar en ella. Se rompía por dos
+     * caminos distintos, los dos encontrados sobre el libro real de esta máquina:
+     *
+     *   1. Dos escritores en un fichero. El escritorio usa el id fijo `desktop`,
+     *      así que cada encarnación del proceso —cada recompilación de Next—
+     *      abría el MISMO fichero creyéndose la primera y escribía otra entrada
+     *      con `seq 1` y `prevHash null`. Encontrado en
+     *      `sesion-2026-08-24-desktop.jsonl`: dos entradas, las dos `seq 1`.
+     *   2. Un escritor que cruza la medianoche. El nombre salía de la fecha de
+     *      CADA entrada, así que a las 00:00 la sesión saltaba a un fichero nuevo
+     *      cuya primera entrada llevaba el `prevHash` del fichero anterior —
+     *      mientras `verificar` arranca cada fichero esperando `null`.
+     *
+     * Los dos daban `CADENA ALTERADA` sobre un libro que nadie había tocado. Y el
+     * daño no es el ruido: es que una alteración de verdad queda indistinguible
+     * del caso benigno, y un medidor que grita siempre deja de leerse.
+     */
+    private nombreBase;
+    /**
+     * Reserva el fichero de ESTA instancia, una sola vez, y no lo suelta.
+     *
+     * Fijarlo en la primera escritura mata el caso 2 de golpe: la sesión se queda
+     * en su fichero aunque cambie el día.
+     *
+     * Para el caso 1 se reclama el nombre con `wx` —crear-o-fallar—, que es
+     * atómico en el sistema de ficheros. Quien lo gana lo tiene; quien lo pierde
+     * prueba el siguiente. Así el «un escritor por fichero» deja de ser un
+     * acuerdo entre quienes llaman y pasa a ser cierto por construcción, incluso
+     * entre procesos distintos que no se conocen.
+     *
+     * Se prefiere partir en dos ficheros antes que leer la cola del ajeno y
+     * continuarlo: dos procesos que leyeran el mismo último hash escribirían dos
+     * entradas con el mismo `prevHash`, que es otra vez una cadena rota sin nadie
+     * manipulando nada. Dos ficheros íntegros son mejor que uno dudoso, y
+     * `verificar` ya los trata por separado.
+     *
+     * EL ANCLA. El nombre se reclama en el ÍNDICE y el fichero de `sesion/` es un
+     * ENLACE DURO al del índice, no una copia. Tres propiedades que hacen falta
+     * las tres:
+     *
+     *   1. `rm -rf sesion/` —el movimiento del agente que quiere tapar sus
+     *      pasos— borra un NOMBRE, no el fichero: los bytes siguen ahí bajo el
+     *      otro nombre, así que `verificar` no solo detecta la desaparición sino
+     *      que puede seguir leyendo lo que se quiso esconder.
+     *   2. El ancla no puede desincronizarse del libro, porque no es un
+     *      resumen que haya que mantener al día: es el mismo inodo. Un índice
+     *      con su propio contador tendría que escribirse en cada anotación, y
+     *      dos procesos escribiendo el mismo índice es la carrera que ya nos
+     *      dejó el libro inverificable una vez.
+     *   3. El nombre se reclama en el índice y no en `sesion/`, así que un
+     *      nombre gastado no se puede reutilizar aunque su fichero de sesión
+     *      haya desaparecido. Sin esto, borrar y reescribir con una entrada
+     *      dejaba el libro con el mismo aspecto que uno legítimo de una entrada.
+     *
+     * Hasta dónde llega, dicho sin adornos: quien borre los DOS directorios deja
+     * un libro vacío indistinguible de una instalación nueva. Contra eso está la
+     * otra mitad del trabajo —la política, que deniega la carpeta al agente
+     * incluso en `yolo`— y no un tercer ancla, porque un ancla que viva en el
+     * mismo disco y con los mismos permisos siempre se puede borrar igual. Lo que
+     * esto elimina es que un solo `rm` pase desapercibido.
+     */
+    /**
+     * El fichero que esta sesión está escribiendo, o `null` si aún no ha escrito.
+     *
+     * La purga lo necesita para no llevarse el suelo de un libro vivo, y tiene que
+     * saberlo por IDENTIDAD, no por fecha: fiarlo a «su última entrada es de hoy»
+     * deja el caso raro —un reloj movido, una sesión larga— rompiendo la cadena en
+     * memoria sin avisar.
+     */
+    get ficheroEnCurso(): string | null;
+    private reservarFichero;
+    /**
+     * Anota un suceso. Nunca lanza: un fallo del libro no puede tumbar la
+     * conversación, igual que en el audit del motor de memoria.
+     */
+    anotar(suceso: SucesoDeSesion): Promise<void>;
+    private escribir;
+    private listar;
+    private inventario;
+    /** Las últimas entradas, de la más reciente hacia atrás. */
+    leer(limite?: number): Promise<EntradaDelLibro[]>;
+    /**
+     * Reverifica la cadena entera y contesta TRES estados, no dos.
+     *
+     * «Íntegra», «alterada» y «FALTA algo que debería estar». El tercero es el
+     * que faltaba: la cadena de hashes detecta la modificación DENTRO de un
+     * fichero y no puede, por construcción, notar la desaparición del fichero —
+     * para eso hace falta saber qué debería haber, que es lo que aporta el índice
+     * (ver `reservarFichero`).
+     *
+     * De la cadena rota devuelve en la PRIMERA entrada que no cuadra, y
+     * `comprobadas` cuenta las que sí cuadraban antes de ella — así el número
+     * dice dónde empieza la manipulación, no cuántas hay en total. Lo que ya se
+     * hubiera detectado como ausente viaja con esa respuesta: no se pierde por
+     * salir antes.
+     */
+    verificar(): Promise<Veredicto>;
+}
+//# sourceMappingURL=libro.d.ts.map

package/dist/core/audit/libro.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"libro.d.ts","sourceRoot":"","sources":["../../../src/core/audit/libro.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Libro de sesión — qué HIZO el agente, en una cadena de hashes verificable.\n *\n * `memory-engine/audit.ts` ya tenía el mecanismo: JSONL append-only donde cada\n * entrada lleva el hash de la anterior, de modo que alterar un registro se\n * detecta reverificando la cadena. Lo que no tenía era ALCANCE: solo lo usaba\n * el motor de memoria, así que auditábamos escrituras de memoria y no\n * ejecuciones de tool, llamadas al modelo, ficheros tocados ni comandos.\n *\n * Este módulo aplica el mismo mecanismo a lo que un DPO pregunta de verdad, que\n * es el registro del artículo 12 del AI Act y el 30 del RGPD.\n *\n * Dos decisiones de diseño que conviene no deshacer sin pensarlo:\n *\n * 1. **Minimización por defecto.** El libro guarda la FORMA de lo que pasó, no\n *    su contenido: del fichero, su hash antes y después, nunca el texto. Un\n *    registro de cumplimiento que copiara los datos sería un segundo almacén de\n *    justo aquello que el RGPD quiere minimizar.\n * 2. **Una sola canonicalización.** `memory-engine/audit.ts` construye la carga\n *    a hashear dos veces, en `append` y en `verify`, con dos listas de campos\n *    escritas a mano. Añadir un campo a una y olvidar la otra rompe la\n *    verificación en silencio y solo para las entradas nuevas. Aquí la\n *    verificación reconstruye la carga con un rest (`{hash, prevHash, ...resto}`),\n *    así que un campo nuevo entra solo y las dos caras no pueden divergir.\n */\n\nimport { createHash } from \"node:crypto\";\nimport { appendFileSync, linkSync, mkdirSync, rmSync, writeFileSync } from \"node:fs\";\nimport { readdir, readFile, stat } from \"node:fs/promises\";\nimport { basename, join } from \"node:path\";\nimport { taparAntesDeEscribir } from \"../privacidad/tapar.ts\";\nimport { ficherosPurgados } from \"./retencion.ts\";\nimport { DIR_INDICE, DIR_SESION } from \"./rutas.ts\";\n\n/** Lo que se le puede pedir al libro que anote. */\nexport type SucesoDeSesion =\n\t| { tipo: \"tool\"; nombre: string; ok: boolean; decision?: string; motivo?: string }\n\t| {\n\t\t\ttipo: \"modelo\";\n\t\t\tproveedor: string;\n\t\t\tmodelo: string;\n\t\t\tentrada: number;\n\t\t\tsalida: number;\n\t\t\tcoste?: number;\n\t\t\t/** `stop`, `toolUse`, `error`, `aborted`… Un fallo del modelo también es auditable. */\n\t\t\tmotivoParada?: string;\n\t  }\n\t| {\n\t\t\ttipo: \"comando\";\n\t\t\targv: string[];\n\t\t\tcodigo: number;\n\t\t\tsandbox?: \"permitido\" | \"bloqueado\";\n\t\t\tviolaciones?: string[];\n\t\t\t/**\n\t\t\t * Quién escribió el comando: el agente (por defecto, si se omite), el\n\t\t\t * usuario desde la terminal integrada del escritorio, o una extensión\n\t\t\t * a través de `pi.exec`.\n\t\t\t *\n\t\t\t * La terminal ejecuta lo que el usuario teclea SIN pasar por la\n\t\t\t * política de aprobación — es su shell, no la del agente — así que este\n\t\t\t * campo es lo único que evita que un registro de cumplimiento confunda\n\t\t\t * \"lo que decidió el agente\" con \"lo que tecleó la persona\". Omitirlo\n\t\t\t * en vez de dar por defecto \"agente\" habría dejado pasar en silencio\n\t\t\t * una terminal que se le olvida anotarse.\n\t\t\t *\n\t\t\t * `extension` es el tercer estado, y hasta hoy faltaba: `pi.exec` no\n\t\t\t * pasaba por la política NI dejaba rastro, así que una extensión leía\n\t\t\t * el vault y el libro no lo sabía. Atribuirlo al \"agente\" habría sido\n\t\t\t * peor que no anotarlo: quien audite tiene que poder distinguir lo que\n\t\t\t * decidió el modelo de lo que hizo código de terceros cargado en el\n\t\t\t * proceso.\n\t\t\t */\n\t\t\torigen?: \"agente\" | \"usuario\" | \"extension\";\n\t\t\t/** Ruta de la extensión, cuando `origen` es `extension`. Sin ella el aviso no es accionable. */\n\t\t\textension?: string;\n\t  }\n\t| {\n\t\t\t/**\n\t\t\t * Una purga por retención, anotada como HECHO en vez de dejada como\n\t\t\t * hueco. Sin esto, cumplir el art. 5.1.e del RGPD hacía que\n\t\t\t * `verificar` acusara de manipulación; y borrar también el índice\n\t\t\t * hacía desaparecer la purga sin rastro. Ver `audit/retencion.ts`.\n\t\t\t */\n\t\t\ttipo: \"purga\";\n\t\t\tfichero: string;\n\t\t\tentradas: number;\n\t\t\tdesde: string;\n\t\t\thasta: string;\n\t\t\thashDeCierre: string;\n\t\t\tpolitica: string;\n\t  }\n\t| { tipo: \"fichero\"; ruta: string; antes: string | null; despues: string | null; tool: string }\n\t| { tipo: \"red\"; dominio: string; permitido: boolean; motivo?: string }\n\t| {\n\t\t\t/** El broker de credenciales (core/credenciales/) es lo que oh-my-pi no\n\t\t\t * tiene: un registro de quién usó qué cuenta y cuándo. `accion` distingue\n\t\t\t * PEDIR una credencial de REPORTAR cómo fue usarla. */\n\t\t\ttipo: \"credencial\";\n\t\t\taccion: \"resuelta\" | \"uso\";\n\t\t\tproveedor: string;\n\t\t\t/** `null` en \"resuelta\" = no había ninguna credencial activa (no es que fallara el libro). */\n\t\t\tcredencialId: string | null;\n\t\t\t/** \"ok\" | \"sin-credencial-activa\" | una `ClaseDeError` de errores/proveedor.ts. */\n\t\t\tresultado: string;\n\t\t\tcliente?: string;\n\t  };\n\nexport interface EntradaDelLibro {\n\tseq: number;\n\tts: string;\n\tsesion: string;\n\tsuceso: Record<string, unknown>;\n\thash: string;\n\tprevHash: string | null;\n}\n\nexport interface Veredicto {\n\tvalido: boolean;\n\tcomprobadas: number;\n\t/** Sello de tiempo de la primera entrada que no cuadra. */\n\talteradaEn?: string;\n\t/**\n\t * Fichero donde está esa entrada.\n\t *\n\t * Sin esto el veredicto decía «alterada en la del 03:09:55» sobre un\n\t * directorio con 26 ficheros de sesión: cierto, verificable y no accionable.\n\t * Quien recibe un aviso de manipulación necesita saber DÓNDE mirar, o el\n\t * aviso se queda en susto.\n\t */\n\tficheroAlterado?: string;\n\t/**\n\t * Por qué no verifica, en una frase estable.\n\t *\n\t * Existe para no confundir «lo he mirado y no cuadra» con «no lo he podido\n\t * mirar»: un fichero ilegible y un hash que no coincide daban el mismo\n\t * veredicto y el mismo mensaje, y son dos cosas distintas para quien\n\t * responde a una auditoría.\n\t */\n\tmotivo?: string;\n\t/**\n\t * Lo que FALTA: ficheros que el índice recuerda y que ya no están en\n\t * `sesion/`, con cuántas entradas tenía cada uno.\n\t *\n\t * Es el tercer estado, y es el que faltaba. Antes de esto la cadena\n\t * distinguía «íntegra» de «alterada» y nada más, así que borrar el fichero\n\t * entero —lo que haría un agente tapando sus pasos— salía como\n\t * `{valido: true, comprobadas: 0}`: un fallo que se lee como éxito en la\n\t * pieza que se vende como prueba. Medido ejecutando el CLI: con tres\n\t * comandos anotados decía «cadena íntegra: 3 entradas», y tras un `rm`\n\t * decía «el libro está vacío» y salía con código 0.\n\t */\n\tfaltan?: { fichero: string; entradas: number }[];\n\t/**\n\t * Ficheros que ya no están y cuya ausencia el libro EXPLICA con una lápida\n\t * de purga. No cuentan como manipulación: son el art. 5.1.e cumplido.\n\t */\n\tpurgados?: { fichero: string; entradas: number; politica: string }[];\n\t/**\n\t * Sitios donde la cadena vuelve a empezar dentro de un mismo fichero.\n\t *\n\t * Ni íntegro ni alterado: el TERCER estado. Un reinicio del proceso lo\n\t * produce, y quien quite entradas del medio y escriba una cadena nueva\n\t * produce exactamente lo mismo. Desde el fichero no se distinguen, así que se\n\t * dice dónde está y se deja que lo juzgue quien audita, en vez de acusar o de\n\t * absolver por nuestra cuenta.\n\t */\n\treinicios?: { fichero: string; ts: string; entradasAntes: number }[];\n\t/**\n\t * Ficheros presentes en `sesion/` sin ancla en el índice.\n\t *\n\t * NO cuenta como manipulación y por eso va aparte de `faltan`: son los\n\t * libros escritos antes de que el índice existiera, y también lo que queda\n\t * en un sistema de ficheros sin enlaces duros. Meterlo en `valido: false`\n\t * habría hecho que toda instalación ya existente gritara «manipulado» el\n\t * día de la actualización — un detector que grita siempre no vale, y\n\t * además volvería indistinguible la manipulación real.\n\t */\n\tsinAncla?: string[];\n}\n\n/** Un fichero del libro, mirado desde los dos directorios a la vez. */\ninterface FicheroDelLibro {\n\tnombre: string;\n\t/** De dónde se leen las entradas: la copia que exista. */\n\truta: string;\n\t/** Está en el índice y ya NO en `sesion/`: alguien lo borró. */\n\tfalta: boolean;\n\t/** Está en `sesion/` y no en el índice: libro antiguo o FS sin enlaces duros. */\n\tsinAncla: boolean;\n\t/** Están los dos nombres pero NO son el mismo fichero: sustitución. */\n\tsuplantado: boolean;\n}\n\n/** Hash de un contenido de fichero. `null` = el fichero no existía. */\nfunction hashContenido(texto: string | null): string | null {\n\treturn texto === null ? null : createHash(\"sha256\").update(texto).digest(\"hex\").slice(0, 16);\n}\n\n/**\n * Redacta cada hoja de texto por separado.\n *\n * Se hace hoja a hoja y no sobre el JSON ya serializado a propósito: un patrón\n * que se pasara de largo sobre el texto serializado podría comerse una comilla\n * y dejar el registro sin parsear. Sobre la hoja, lo peor que puede pasar es\n * que redacte de más.\n */\nfunction redactarHoja(valor: unknown): unknown {\n\tif (typeof valor === \"string\") return taparAntesDeEscribir(valor, \"strict\");\n\tif (Array.isArray(valor)) return valor.map(redactarHoja);\n\tif (valor && typeof valor === \"object\") {\n\t\treturn Object.fromEntries(Object.entries(valor).map(([k, v]) => [k, redactarHoja(v)]));\n\t}\n\treturn valor;\n}\n\n/** Pasa del suceso que da quien llama al registro que se guarda. */\nfunction aRegistro(suceso: SucesoDeSesion): Record<string, unknown> {\n\tconst base =\n\t\tsuceso.tipo === \"fichero\"\n\t\t\t? { ...suceso, antes: hashContenido(suceso.antes), despues: hashContenido(suceso.despues) }\n\t\t\t: suceso;\n\treturn redactarHoja(base) as Record<string, unknown>;\n}\n\nfunction hashDe(prevHash: string | null, carga: Omit<EntradaDelLibro, \"hash\" | \"prevHash\">): string {\n\treturn createHash(\"sha256\")\n\t\t.update(JSON.stringify({ prevHash, ...carga }))\n\t\t.digest(\"hex\");\n}\n\nexport class LibroDeSesion {\n\tprivate readonly dir: string;\n\t/** El índice: un enlace duro por fichero de sesión. Ver `DIR_INDICE`. */\n\tprivate readonly dirIndice: string;\n\tprivate readonly sesion: string;\n\tprivate seq = 0;\n\tprivate ultimoHash: string | null = null;\n\t/** Fijado en la primera escritura por `reservarFichero`; no cambia despues. */\n\tprivate rutaFichero: string | null = null;\n\n\tconstructor(raiz: string, sesionId: string) {\n\t\tthis.dir = join(raiz, DIR_SESION);\n\t\tthis.dirIndice = join(raiz, DIR_INDICE);\n\t\tthis.sesion = sesionId;\n\t}\n\n\t/**\n\t * Un fichero por sesión, no uno por día.\n\t *\n\t * Compartir fichero entre sesiones parecía más ordenado y hacía el libro\n\t * INVERIFICABLE, cosa que solo se vio ejecutando: cada proceso arranca su\n\t * `seq` en 1 y su hash anterior en `null`, así que tres sesiones seguidas\n\t * dejaban tres cadenas encadenadas dentro del mismo fichero y `verificar`\n\t * fallaba en la primera entrada de la segunda.\n\t *\n\t * Arreglarlo cargando el último hash al abrir no habría bastado: el CLI y el\n\t * escritorio corren a la vez, y dos procesos que leyeran el mismo hash\n\t * anterior escribirían dos entradas con el mismo `prevHash`.\n\t *\n\t * El límite que esto dejaba, y que era el agujero: borrar el fichero de una\n\t * sesión entera no lo detecta la cadena, que solo ve la modificación DENTRO\n\t * de una sesión. Se documentaba aquí mientras el veredicto seguía diciendo\n\t * `valido: true` — o sea, un fallo que se leía como éxito en la pieza que se\n\t * vende como prueba. Lo cierra el índice de `reservarFichero`.\n\t *\n\t * «Un fichero, un escritor» es la PRECONDICIÓN de todo lo anterior, y por eso\n\t * `reservarFichero` la impone en vez de confiar en ella. Se rompía por dos\n\t * caminos distintos, los dos encontrados sobre el libro real de esta máquina:\n\t *\n\t *   1. Dos escritores en un fichero. El escritorio usa el id fijo `desktop`,\n\t *      así que cada encarnación del proceso —cada recompilación de Next—\n\t *      abría el MISMO fichero creyéndose la primera y escribía otra entrada\n\t *      con `seq 1` y `prevHash null`. Encontrado en\n\t *      `sesion-2026-08-24-desktop.jsonl`: dos entradas, las dos `seq 1`.\n\t *   2. Un escritor que cruza la medianoche. El nombre salía de la fecha de\n\t *      CADA entrada, así que a las 00:00 la sesión saltaba a un fichero nuevo\n\t *      cuya primera entrada llevaba el `prevHash` del fichero anterior —\n\t *      mientras `verificar` arranca cada fichero esperando `null`.\n\t *\n\t * Los dos daban `CADENA ALTERADA` sobre un libro que nadie había tocado. Y el\n\t * daño no es el ruido: es que una alteración de verdad queda indistinguible\n\t * del caso benigno, y un medidor que grita siempre deja de leerse.\n\t */\n\tprivate nombreBase(fecha: string): string {\n\t\tconst id = this.sesion.replace(/[^a-zA-Z0-9-]/g, \"_\").slice(0, 40);\n\t\treturn `sesion-${fecha}-${id}.jsonl`;\n\t}\n\n\t/**\n\t * Reserva el fichero de ESTA instancia, una sola vez, y no lo suelta.\n\t *\n\t * Fijarlo en la primera escritura mata el caso 2 de golpe: la sesión se queda\n\t * en su fichero aunque cambie el día.\n\t *\n\t * Para el caso 1 se reclama el nombre con `wx` —crear-o-fallar—, que es\n\t * atómico en el sistema de ficheros. Quien lo gana lo tiene; quien lo pierde\n\t * prueba el siguiente. Así el «un escritor por fichero» deja de ser un\n\t * acuerdo entre quienes llaman y pasa a ser cierto por construcción, incluso\n\t * entre procesos distintos que no se conocen.\n\t *\n\t * Se prefiere partir en dos ficheros antes que leer la cola del ajeno y\n\t * continuarlo: dos procesos que leyeran el mismo último hash escribirían dos\n\t * entradas con el mismo `prevHash`, que es otra vez una cadena rota sin nadie\n\t * manipulando nada. Dos ficheros íntegros son mejor que uno dudoso, y\n\t * `verificar` ya los trata por separado.\n\t *\n\t * EL ANCLA. El nombre se reclama en el ÍNDICE y el fichero de `sesion/` es un\n\t * ENLACE DURO al del índice, no una copia. Tres propiedades que hacen falta\n\t * las tres:\n\t *\n\t *   1. `rm -rf sesion/` —el movimiento del agente que quiere tapar sus\n\t *      pasos— borra un NOMBRE, no el fichero: los bytes siguen ahí bajo el\n\t *      otro nombre, así que `verificar` no solo detecta la desaparición sino\n\t *      que puede seguir leyendo lo que se quiso esconder.\n\t *   2. El ancla no puede desincronizarse del libro, porque no es un\n\t *      resumen que haya que mantener al día: es el mismo inodo. Un índice\n\t *      con su propio contador tendría que escribirse en cada anotación, y\n\t *      dos procesos escribiendo el mismo índice es la carrera que ya nos\n\t *      dejó el libro inverificable una vez.\n\t *   3. El nombre se reclama en el índice y no en `sesion/`, así que un\n\t *      nombre gastado no se puede reutilizar aunque su fichero de sesión\n\t *      haya desaparecido. Sin esto, borrar y reescribir con una entrada\n\t *      dejaba el libro con el mismo aspecto que uno legítimo de una entrada.\n\t *\n\t * Hasta dónde llega, dicho sin adornos: quien borre los DOS directorios deja\n\t * un libro vacío indistinguible de una instalación nueva. Contra eso está la\n\t * otra mitad del trabajo —la política, que deniega la carpeta al agente\n\t * incluso en `yolo`— y no un tercer ancla, porque un ancla que viva en el\n\t * mismo disco y con los mismos permisos siempre se puede borrar igual. Lo que\n\t * esto elimina es que un solo `rm` pase desapercibido.\n\t */\n\t/**\n\t * El fichero que esta sesión está escribiendo, o `null` si aún no ha escrito.\n\t *\n\t * La purga lo necesita para no llevarse el suelo de un libro vivo, y tiene que\n\t * saberlo por IDENTIDAD, no por fecha: fiarlo a «su última entrada es de hoy»\n\t * deja el caso raro —un reloj movido, una sesión larga— rompiendo la cadena en\n\t * memoria sin avisar.\n\t */\n\tget ficheroEnCurso(): string | null {\n\t\treturn this.rutaFichero ? basename(this.rutaFichero) : null;\n\t}\n\n\tprivate reservarFichero(fecha: string): string {\n\t\tif (this.rutaFichero) return this.rutaFichero;\n\t\tmkdirSync(this.dirIndice, { recursive: true });\n\t\tconst base = this.nombreBase(fecha);\n\t\tfor (let n = 1; ; n++) {\n\t\t\tconst nombre = n === 1 ? base : base.replace(/\\.jsonl$/, `-${n}.jsonl`);\n\t\t\tconst ancla = join(this.dirIndice, nombre);\n\t\t\ttry {\n\t\t\t\twriteFileSync(ancla, \"\", { flag: \"wx\" });\n\t\t\t} catch (error) {\n\t\t\t\tif ((error as NodeJS.ErrnoException).code !== \"EEXIST\") throw error;\n\t\t\t\tcontinue; // nombre gastado (otro escritor, u otra ejecución): el siguiente\n\t\t\t}\n\t\t\tconst ruta = join(this.dir, nombre);\n\t\t\ttry {\n\t\t\t\tlinkSync(ancla, ruta);\n\t\t\t} catch (error) {\n\t\t\t\t// El nombre estaba libre en el índice pero ocupado en `sesion/`: es un\n\t\t\t\t// libro escrito ANTES de que el índice existiera. Se suelta el ancla\n\t\t\t\t// vacía y se prueba el siguiente nombre. Soltarla no es cosmético:\n\t\t\t\t// dejar un ancla de 0 bytes junto a un fichero de sesión con\n\t\t\t\t// contenido son dos inodos con el mismo nombre, y `verificar` lo\n\t\t\t\t// leería como suplantación en toda instalación que se actualice.\n\t\t\t\trmSync(ancla, { force: true });\n\t\t\t\tif ((error as NodeJS.ErrnoException).code === \"EEXIST\") continue;\n\t\t\t\t// Sin enlaces duros (FS exótico, montaje raro) el libro sigue\n\t\t\t\t// funcionando SIN ancla, porque un libro que no se escribe es peor\n\t\t\t\t// que uno sin ancla; `verificar` lo dirá como `sinAncla`, que es un\n\t\t\t\t// tercer estado y no una acusación.\n\t\t\t\twriteFileSync(ruta, \"\", { flag: \"wx\" });\n\t\t\t}\n\t\t\tthis.rutaFichero = ruta;\n\t\t\treturn ruta;\n\t\t}\n\t}\n\n\t/**\n\t * Anota un suceso. Nunca lanza: un fallo del libro no puede tumbar la\n\t * conversación, igual que en el audit del motor de memoria.\n\t */\n\tanotar(suceso: SucesoDeSesion): Promise<void> {\n\t\t// SÍNCRONO, y no es una simplificación perezosa: es lo correcto aquí.\n\t\t//\n\t\t// Antes esto encolaba una escritura asíncrona y devolvía la promesa, y casi\n\t\t// todos los llamantes hacen `void libro.anotar(...)` — no la esperan, porque\n\t\t// un fallo del libro no puede tumbar la conversación. Eso deja dos agujeros:\n\t\t//\n\t\t//   1. Las últimas entradas se pierden si el proceso termina antes de que\n\t\t//      la cola se vacíe. En un registro de cumplimiento, perder justo lo\n\t\t//      último que hizo el agente es perder lo que más se va a mirar.\n\t\t//   2. Escrituras que aterrizan DESPUÉS de que la sesión se haya cerrado.\n\t\t//      Salió en una prueba de regresión de upstream: al borrar su\n\t\t//      directorio temporal, el libro seguía creando ficheros dentro y\n\t\t//      `rmSync` fallaba con ENOTEMPTY. La prueba pasaba en HEAD~1 y falló\n\t\t//      al fusionar el índice — el ancla ensanchó una carrera que ya existía.\n\t\t//\n\t\t// El coste está MEDIDO, y sale a favor: 40 µs por entrada en síncrono\n\t\t// frente a 56 µs en asíncrono (1.000 escrituras de 268 bytes). Es más\n\t\t// rápido porque para una escritura tan pequeña la promesa pesa más que el\n\t\t// `write`. Y 40 µs contra una llamada a herramienta que tarda milisegundos\n\t\t// o segundos no se nota.\n\t\t//\n\t\t// Además desaparece la cola entera: JavaScript es de un solo hilo, así que\n\t\t// dos `anotar` seguidos ya no pueden leer el mismo `ultimoHash`. La carrera\n\t\t// que la cola existía para evitar deja de ser posible por construcción, que\n\t\t// es mejor que evitarla con disciplina.\n\t\t//\n\t\t// Se mantiene la firma `Promise<void>` para no tocar a los llamantes.\n\t\tthis.escribir(suceso);\n\t\treturn Promise.resolve();\n\t}\n\n\tprivate escribir(suceso: SucesoDeSesion): void {\n\t\ttry {\n\t\t\tmkdirSync(this.dir, { recursive: true });\n\t\t\tconst carga = {\n\t\t\t\tseq: ++this.seq,\n\t\t\t\tts: new Date().toISOString(),\n\t\t\t\tsesion: this.sesion,\n\t\t\t\tsuceso: aRegistro(suceso),\n\t\t\t};\n\t\t\tconst hash = hashDe(this.ultimoHash, carga);\n\t\t\tconst entrada: EntradaDelLibro = { ...carga, hash, prevHash: this.ultimoHash };\n\t\t\tthis.ultimoHash = hash;\n\t\t\tconst ruta = this.reservarFichero(carga.ts.slice(0, 10));\n\t\t\tappendFileSync(ruta, `${JSON.stringify(entrada)}\\n`, \"utf-8\");\n\t\t} catch {\n\t\t\t// El libro nunca rompe la sesión.\n\t\t}\n\t}\n\n\tprivate async listar(dir: string): Promise<string[]> {\n\t\ttry {\n\t\t\treturn (await readdir(dir)).filter((f) => /^sesion-.*\\.jsonl$/.test(f)).sort();\n\t\t} catch {\n\t\t\treturn [];\n\t\t}\n\t}\n\n\t/**\n\t * Los ficheros del libro vistos desde los DOS directorios.\n\t *\n\t * Esta es la comparación que antes no existía: `readdir(sesion/)` solo puede\n\t * contestar «lo que hay», nunca «lo que debería haber», y por eso un borrado\n\t * salía como un libro vacío.\n\t */\n\tprivate async inventario(): Promise<FicheroDelLibro[]> {\n\t\tconst enSesion = new Set(await this.listar(this.dir));\n\t\tconst enIndice = new Set(await this.listar(this.dirIndice));\n\t\tconst out: FicheroDelLibro[] = [];\n\t\tfor (const nombre of [...new Set([...enSesion, ...enIndice])].sort()) {\n\t\t\tconst s = enSesion.has(nombre);\n\t\t\tconst i = enIndice.has(nombre);\n\t\t\t// Con los dos nombres presentes tienen que ser el MISMO inodo, porque\n\t\t\t// así los creó `reservarFichero`. Si no lo son, alguien borró el de\n\t\t\t// `sesion/` y puso otro en su sitio — y como el algoritmo de la cadena\n\t\t\t// es público, ese otro puede tener una cadena interna perfecta. Sin\n\t\t\t// esta comprobación la suplantación se leería como «cadena íntegra».\n\t\t\tlet suplantado = false;\n\t\t\tif (s && i) {\n\t\t\t\ttry {\n\t\t\t\t\tconst [a, b] = await Promise.all([stat(join(this.dir, nombre)), stat(join(this.dirIndice, nombre))]);\n\t\t\t\t\tsuplantado = a.ino !== b.ino;\n\t\t\t\t} catch {\n\t\t\t\t\t// No se pudo mirar: no se acusa. «No lo he podido comprobar» no es\n\t\t\t\t\t// «está manipulado», y el fichero se verifica igual más abajo.\n\t\t\t\t}\n\t\t\t}\n\t\t\tout.push({\n\t\t\t\tnombre,\n\t\t\t\t// Se lee del índice cuando el de `sesion/` no está (es el caso del\n\t\t\t\t// borrado) o cuando no coincide con él: el índice es el ancla.\n\t\t\t\truta: s && !suplantado ? join(this.dir, nombre) : join(this.dirIndice, nombre),\n\t\t\t\tfalta: i && !s,\n\t\t\t\tsinAncla: s && !i,\n\t\t\t\tsuplantado,\n\t\t\t});\n\t\t}\n\t\treturn out;\n\t}\n\n\t/** Las últimas entradas, de la más reciente hacia atrás. */\n\tasync leer(limite = 50): Promise<EntradaDelLibro[]> {\n\t\tconst out: EntradaDelLibro[] = [];\n\t\tfor (const f of (await this.inventario()).reverse()) {\n\t\t\tlet crudo: string;\n\t\t\ttry {\n\t\t\t\t// Por `f.ruta` y no por `sesion/`: las entradas de un fichero borrado\n\t\t\t\t// sobreviven en el índice y quien investiga tiene que poder verlas.\n\t\t\t\tcrudo = await readFile(f.ruta, \"utf-8\");\n\t\t\t} catch {\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tfor (const linea of crudo.split(\"\\n\").filter(Boolean).reverse()) {\n\t\t\t\ttry {\n\t\t\t\t\tout.push(JSON.parse(linea) as EntradaDelLibro);\n\t\t\t\t\tif (out.length >= limite) return out;\n\t\t\t\t} catch {\n\t\t\t\t\t// Línea ilegible: la verificación es quien lo denuncia, no la lectura.\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t\treturn out;\n\t}\n\n\t/**\n\t * Reverifica la cadena entera y contesta TRES estados, no dos.\n\t *\n\t * «Íntegra», «alterada» y «FALTA algo que debería estar». El tercero es el\n\t * que faltaba: la cadena de hashes detecta la modificación DENTRO de un\n\t * fichero y no puede, por construcción, notar la desaparición del fichero —\n\t * para eso hace falta saber qué debería haber, que es lo que aporta el índice\n\t * (ver `reservarFichero`).\n\t *\n\t * De la cadena rota devuelve en la PRIMERA entrada que no cuadra, y\n\t * `comprobadas` cuenta las que sí cuadraban antes de ella — así el número\n\t * dice dónde empieza la manipulación, no cuántas hay en total. Lo que ya se\n\t * hubiera detectado como ausente viaja con esa respuesta: no se pierde por\n\t * salir antes.\n\t */\n\tasync verificar(): Promise<Veredicto> {\n\t\tlet comprobadas = 0;\n\t\tconst faltan: { fichero: string; entradas: number }[] = [];\n\t\tconst reinicios: { fichero: string; ts: string; entradasAntes: number }[] = [];\n\t\tconst sinAncla: string[] = [];\n\t\t// Las lápidas se leen ANTES de recorrer: una purga anotada en el fichero de\n\t\t// hoy explica un hueco de un fichero de hace un año.\n\t\tconst purgados = ficherosPurgados(await this.leer());\n\t\tfor (const f of await this.inventario()) {\n\t\t\tif (f.suplantado) {\n\t\t\t\treturn {\n\t\t\t\t\tvalido: false,\n\t\t\t\t\tcomprobadas,\n\t\t\t\t\tficheroAlterado: f.nombre,\n\t\t\t\t\tmotivo: \"el fichero de sesión ya no es el mismo que el del índice: lo han sustituido\",\n\t\t\t\t\t...(faltan.length ? { faltan } : {}),\n\t\t\t\t\t...(sinAncla.length ? { sinAncla } : {}),\n\t\t\t\t};\n\t\t\t}\n\t\t\t// La cadena empieza de cero en CADA fichero, porque cada fichero es una\n\t\t\t// sesión y su primera entrada lleva `prevHash: null`. Arrastrar el hash\n\t\t\t// de un fichero al siguiente es lo que hacía fallar la verificación en\n\t\t\t// cuanto había más de una sesión.\n\t\t\tlet prevHash: string | null = null;\n\t\t\tlet enEste = 0;\n\t\t\tlet crudo: string;\n\t\t\ttry {\n\t\t\t\tcrudo = await readFile(f.ruta, \"utf-8\");\n\t\t\t} catch {\n\t\t\t\treturn {\n\t\t\t\t\tvalido: false,\n\t\t\t\t\tcomprobadas,\n\t\t\t\t\tficheroAlterado: f.nombre,\n\t\t\t\t\tmotivo: \"no se ha podido leer el fichero: no es «está bien», es «no lo sé»\",\n\t\t\t\t\t...(faltan.length ? { faltan } : {}),\n\t\t\t\t};\n\t\t\t}\n\t\t\tfor (const linea of crudo.split(\"\\n\").filter(Boolean)) {\n\t\t\t\tlet entrada: EntradaDelLibro;\n\t\t\t\ttry {\n\t\t\t\t\tentrada = JSON.parse(linea) as EntradaDelLibro;\n\t\t\t\t} catch {\n\t\t\t\t\treturn {\n\t\t\t\t\t\tvalido: false,\n\t\t\t\t\t\tcomprobadas,\n\t\t\t\t\t\tficheroAlterado: f.nombre,\n\t\t\t\t\t\tmotivo: \"hay una línea que no es JSON válido\",\n\t\t\t\t\t\t...(faltan.length ? { faltan } : {}),\n\t\t\t\t\t};\n\t\t\t\t}\n\t\t\t\t// El rest es lo que impide que esta lista y la de `escribir`\n\t\t\t\t// se separen: aquí no hay lista.\n\t\t\t\tconst { hash, prevHash: declarado, ...resto } = entrada;\n\t\t\t\t// Se separan DOS preguntas que antes iban juntas y contestaban lo\n\t\t\t\t// mismo, acusando siempre de lo primero:\n\t\t\t\t//\n\t\t\t\t//   · ¿el hash cuadra con SU PROPIO contenido? Si no, alguien editó la\n\t\t\t\t//     entrada. Eso es manipulación y se dice así.\n\t\t\t\t//   · ¿su `prevHash` apunta a la entrada anterior? Si no, el enlace\n\t\t\t\t//     está roto, que es otra cosa: faltan entradas o están cambiadas\n\t\t\t\t//     de orden.\n\t\t\t\t//\n\t\t\t\t// Medido sobre el libro real de esta máquina: un fichero de dos\n\t\t\t\t// entradas, las dos con `seq: 1` y `prevHash: null`, salía como «el\n\t\t\t\t// hash de una entrada no cuadra con su contenido». Cuadraba\n\t\t\t\t// perfectamente. Eran dos procesos del escritorio escribiendo el mismo\n\t\t\t\t// fichero antes de que `reservarFichero` diera nombres distintos.\n\t\t\t\tif (hash !== hashDe(declarado, resto)) {\n\t\t\t\t\treturn {\n\t\t\t\t\t\tvalido: false,\n\t\t\t\t\t\tcomprobadas,\n\t\t\t\t\t\talteradaEn: entrada.ts,\n\t\t\t\t\t\tficheroAlterado: f.nombre,\n\t\t\t\t\t\tmotivo: \"el hash de una entrada no cuadra con su contenido: la han editado\",\n\t\t\t\t\t\t...(faltan.length ? { faltan } : {}),\n\t\t\t\t\t};\n\t\t\t\t}\n\t\t\t\tif (declarado !== prevHash) {\n\t\t\t\t\t// Una cadena que vuelve a empezar dentro del mismo fichero. Lo\n\t\t\t\t\t// produce un reinicio del proceso —y lo produce igual quien quite\n\t\t\t\t\t// entradas del medio y escriba una cadena nueva—. Desde el fichero\n\t\t\t\t\t// no se distinguen, así que NO se llama manipulación ni se da por\n\t\t\t\t\t// bueno: es el tercer estado, y se dice entero en `reinicios`.\n\t\t\t\t\tif (declarado === null && prevHash !== null) {\n\t\t\t\t\t\treinicios.push({ fichero: f.nombre, ts: entrada.ts, entradasAntes: enEste });\n\t\t\t\t\t\tprevHash = hash;\n\t\t\t\t\t\tcomprobadas++;\n\t\t\t\t\t\tenEste++;\n\t\t\t\t\t\tcontinue;\n\t\t\t\t\t}\n\t\t\t\t\treturn {\n\t\t\t\t\t\tvalido: false,\n\t\t\t\t\t\tcomprobadas,\n\t\t\t\t\t\talteradaEn: entrada.ts,\n\t\t\t\t\t\tficheroAlterado: f.nombre,\n\t\t\t\t\t\tmotivo:\n\t\t\t\t\t\t\t\"el enlace de una entrada no apunta a la anterior: faltan entradas o están cambiadas de orden\",\n\t\t\t\t\t\t...(faltan.length ? { faltan } : {}),\n\t\t\t\t\t};\n\t\t\t\t}\n\t\t\t\tprevHash = hash;\n\t\t\t\tcomprobadas++;\n\t\t\t\tenEste++;\n\t\t\t}\n\t\t\t// Un fichero VACÍO que falta no es una ausencia: es una reserva de\n\t\t\t// nombre que nunca llegó a escribirse (la sesión murió entre reservar y\n\t\t\t// anotar). Contarlo habría hecho que una sesión nueva y legítima, sin\n\t\t\t// una sola entrada todavía, se reportara como manipulada — la mitad que\n\t\t\t// decide, porque un detector que grita siempre no distingue nada.\n\t\t\tif (enEste === 0) continue;\n\t\t\t// Un hueco EXPLICADO no es una manipulación.\n\t\t\t//\n\t\t\t// Si el propio libro lleva una lápida diciendo que ese fichero se purgó\n\t\t\t// —cuándo, cuántas entradas, bajo qué política y con qué hash de\n\t\t\t// cierre—, la ausencia es un hecho declarado y no una desaparición. Sin\n\t\t\t// esto, cumplir el art. 5.1.e del RGPD hacía que `verificar` contestara\n\t\t\t// «alguien los ha borrado»: la ley nos acusaba de manipular. Ver\n\t\t\t// `audit/retencion.ts`.\n\t\t\tif (f.falta && !purgados.has(f.nombre)) faltan.push({ fichero: f.nombre, entradas: enEste });\n\t\t\tif (f.sinAncla) sinAncla.push(f.nombre);\n\t\t}\n\t\t// Las lápidas se enseñan TODAS, no solo las que tapan un hueco del\n\t\t// inventario. Una purga completa se lleva el fichero Y su ancla, así que no\n\t\t// deja hueco ninguno: si solo se informara de las que explican una ausencia,\n\t\t// el caso normal —el que de verdad ocurre— saldría mudo y el DPO leería\n\t\t// «cadena íntegra, 1 entrada» sin enterarse de que se purgaron tres. Que es\n\t\t// exactamente el «desaparece sin rastro» que este mecanismo existe para\n\t\t// impedir.\n\t\tconst explicados = [...purgados.values()].map((l) => ({\n\t\t\tfichero: l.fichero,\n\t\t\tentradas: l.entradas,\n\t\t\tpolitica: l.politica,\n\t\t}));\n\t\treturn {\n\t\t\tvalido: faltan.length === 0,\n\t\t\t...(explicados.length ? { purgados: explicados } : {}),\n\t\t\t...(reinicios.length ? { reinicios } : {}),\n\t\t\tcomprobadas,\n\t\t\t...(faltan.length ? { faltan } : {}),\n\t\t\t...(sinAncla.length ? { sinAncla } : {}),\n\t\t};\n\t}\n}\n"]}