@hoilab/ada-cli 0.84.21 → 0.85.0

package/dist/core/memory-engine/audit-export.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Bundle de evidencia — auditoría que se queda con el cliente.
+ *
+ * Es la dirección OPUESTA a subir transcripciones a una nube: un cliente
+ * regulado produce, en local y por sí mismo, un artefacto verificable de qué
+ * hizo el agente y qué se verificó. Cero red.
+ *
+ * No inventa nada: junta tres fuentes que ya existen y añade el resultado de la
+ * verificación de la cadena hash.
+ *
+ * ponytail: la cadena hash prueba consistencia interna, NO procedencia. Si un
+ * cliente necesita no-repudio, eso es una conversación de HSM/firma — el
+ * manifiesto lo dice explícitamente en vez de insinuar que lo cubre.
+ */
+import type { VeredictoDelRegistro } from "./audit-indice.ts";
+export interface AuditBundleInput {
+    /** Raíz del engine (`<agentDir>/memory-engine`). */
+    rootDir: string;
+    /** Directorio de runs de workflow (`<agentDir>/workflows/runs`). */
+    runsDir?: string;
+    /** Fichero del grafo, si existe. */
+    graphPath?: string;
+    /** Solo entradas con `ts >= since` (ISO). */
+    since?: string;
+    /** Verificador de la cadena (inyectable para tests). */
+    verify: () => Promise<VeredictoDelRegistro>;
+    /** Lector de entradas de auditoría. */
+    entries: (limit: number) => Promise<Array<Record<string, unknown>>>;
+}
+export interface AuditBundleManifest {
+    version: 1;
+    generatedAt: string;
+    since?: string;
+    /**
+     * El veredicto ENTERO, no un resumen.
+     *
+     * Antes este campo estaba declarado como `{valid, tamperedAt, entriesChecked}`
+     * y el veredicto pasaba por ese hueco perdiendo lo demás sin dar un solo
+     * error: el manifiesto decía `"chain": {"valid": true}` sobre un registro al
+     * que le faltaban ficheros enteros. Un tipo intermedio que recorta campos es
+     * peor que uno que se queja, porque el recorte no se ve en ningún sitio.
+     */
+    chain: VeredictoDelRegistro;
+    counts: {
+        auditEntries: number;
+        workflowRuns: number;
+    };
+    /** Lo que este bundle NO prueba. Explícito a propósito. */
+    limitations: string[];
+}
+/**
+ * Escribe el bundle en `outDir`. Devuelve el manifiesto.
+ * `generatedAt` se inyecta para que el test sea determinista.
+ */
+export declare function exportAuditBundle(input: AuditBundleInput, outDir: string, now?: () => string): Promise<AuditBundleManifest>;
+//# sourceMappingURL=audit-export.d.ts.map

package/dist/core/memory-engine/audit-export.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-export.d.ts","sourceRoot":"","sources":["../../../src/core/memory-engine/audit-export.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAE9D,MAAM,WAAW,gBAAgB;IAChC,qDAAoD;IACpD,OAAO,EAAE,MAAM,CAAC;IAChB,oEAAoE;IACpE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oCAAoC;IACpC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6CAA6C;IAC7C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wDAAwD;IACxD,MAAM,EAAE,MAAM,OAAO,CAAC,oBAAoB,CAAC,CAAC;IAC5C,wCAAuC;IACvC,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;CACpE;AAED,MAAM,WAAW,mBAAmB;IACnC,OAAO,EAAE,CAAC,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;;;;OAQG;IACH,KAAK,EAAE,oBAAoB,CAAC;IAC5B,MAAM,EAAE;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC;IACvD,6DAA2D;IAC3D,WAAW,EAAE,MAAM,EAAE,CAAC;CACtB;AAED;;;GAGG;AACH,wBAAsB,iBAAiB,CACtC,KAAK,EAAE,gBAAgB,EACvB,MAAM,EAAE,MAAM,EACd,GAAG,GAAE,MAAM,MAAuC,GAChD,OAAO,CAAC,mBAAmB,CAAC,CA+E9B","sourcesContent":["/**\n * Bundle de evidencia — auditoría que se queda con el cliente.\n *\n * Es la dirección OPUESTA a subir transcripciones a una nube: un cliente\n * regulado produce, en local y por sí mismo, un artefacto verificable de qué\n * hizo el agente y qué se verificó. Cero red.\n *\n * No inventa nada: junta tres fuentes que ya existen y añade el resultado de la\n * verificación de la cadena hash.\n *\n * ponytail: la cadena hash prueba consistencia interna, NO procedencia. Si un\n * cliente necesita no-repudio, eso es una conversación de HSM/firma — el\n * manifiesto lo dice explícitamente en vez de insinuar que lo cubre.\n */\n\nimport { mkdir, readdir, readFile, writeFile } from \"node:fs/promises\";\nimport { join } from \"node:path\";\nimport type { VeredictoDelRegistro } from \"./audit-indice.ts\";\n\nexport interface AuditBundleInput {\n\t/** Raíz del engine (`<agentDir>/memory-engine`). */\n\trootDir: string;\n\t/** Directorio de runs de workflow (`<agentDir>/workflows/runs`). */\n\trunsDir?: string;\n\t/** Fichero del grafo, si existe. */\n\tgraphPath?: string;\n\t/** Solo entradas con `ts >= since` (ISO). */\n\tsince?: string;\n\t/** Verificador de la cadena (inyectable para tests). */\n\tverify: () => Promise<VeredictoDelRegistro>;\n\t/** Lector de entradas de auditoría. */\n\tentries: (limit: number) => Promise<Array<Record<string, unknown>>>;\n}\n\nexport interface AuditBundleManifest {\n\tversion: 1;\n\tgeneratedAt: string;\n\tsince?: string;\n\t/**\n\t * El veredicto ENTERO, no un resumen.\n\t *\n\t * Antes este campo estaba declarado como `{valid, tamperedAt, entriesChecked}`\n\t * y el veredicto pasaba por ese hueco perdiendo lo demás sin dar un solo\n\t * error: el manifiesto decía `\"chain\": {\"valid\": true}` sobre un registro al\n\t * que le faltaban ficheros enteros. Un tipo intermedio que recorta campos es\n\t * peor que uno que se queja, porque el recorte no se ve en ningún sitio.\n\t */\n\tchain: VeredictoDelRegistro;\n\tcounts: { auditEntries: number; workflowRuns: number };\n\t/** Lo que este bundle NO prueba. Explícito a propósito. */\n\tlimitations: string[];\n}\n\n/**\n * Escribe el bundle en `outDir`. Devuelve el manifiesto.\n * `generatedAt` se inyecta para que el test sea determinista.\n */\nexport async function exportAuditBundle(\n\tinput: AuditBundleInput,\n\toutDir: string,\n\tnow: () => string = () => new Date().toISOString(),\n): Promise<AuditBundleManifest> {\n\tawait mkdir(outDir, { recursive: true });\n\n\tconst chain = await input.verify();\n\n\tconst all = await input.entries(100000);\n\tconst audit = input.since\n\t\t? all.filter((e) => typeof e.ts === \"string\" && (e.ts as string) >= (input.since as string))\n\t\t: all;\n\tawait writeFile(join(outDir, \"audit.jsonl\"), audit.map((e) => JSON.stringify(e)).join(\"\\n\"), \"utf-8\");\n\n\t// Runs de workflow: el journal ya guarda script, args, fases y resultPath.\n\tconst runs: Array<Record<string, unknown>> = [];\n\tif (input.runsDir) {\n\t\ttry {\n\t\t\tfor (const file of (await readdir(input.runsDir)).filter((f) => f.endsWith(\".json\"))) {\n\t\t\t\ttry {\n\t\t\t\t\tconst state = JSON.parse(await readFile(join(input.runsDir, file), \"utf-8\")) as Record<string, unknown>;\n\t\t\t\t\tif (input.since && typeof state.startedAt === \"string\" && state.startedAt < input.since) continue;\n\t\t\t\t\truns.push({\n\t\t\t\t\t\trunId: state.runId,\n\t\t\t\t\t\tname: state.name,\n\t\t\t\t\t\tstatus: state.status,\n\t\t\t\t\t\tstartedAt: state.startedAt,\n\t\t\t\t\t\tupdatedAt: state.updatedAt,\n\t\t\t\t\t\tagentCount: state.agentCount,\n\t\t\t\t\t\ttokenUsage: state.tokenUsage,\n\t\t\t\t\t\tphases: state.phases,\n\t\t\t\t\t\tresultPath: state.resultPath,\n\t\t\t\t\t\targs: state.args,\n\t\t\t\t\t});\n\t\t\t\t} catch {\n\t\t\t\t\t// un run ilegible no invalida el bundle\n\t\t\t\t}\n\t\t\t}\n\t\t} catch {\n\t\t\t// sin runs todavía\n\t\t}\n\t}\n\tawait writeFile(join(outDir, \"workflow-runs.json\"), JSON.stringify(runs, null, 2), \"utf-8\");\n\n\t// Grafo: la traza de qué se verificó y con qué evidencia.\n\tif (input.graphPath) {\n\t\ttry {\n\t\t\tawait writeFile(join(outDir, \"graph.json\"), await readFile(input.graphPath, \"utf-8\"), \"utf-8\");\n\t\t} catch {\n\t\t\t// sin grafo\n\t\t}\n\t}\n\n\tconst manifest: AuditBundleManifest = {\n\t\tversion: 1,\n\t\tgeneratedAt: now(),\n\t\tsince: input.since,\n\t\tchain,\n\t\tcounts: { auditEntries: audit.length, workflowRuns: runs.length },\n\t\tlimitations: [\n\t\t\t...(chain.borrados?.length\n\t\t\t\t? [\n\t\t\t\t\t\t`FALTAN ${chain.borrados.length} fichero(s) que el índice recuerda, con ${chain.borrados.reduce((n, f) => n + f.entradas, 0)} entrada(s): ${chain.borrados.map((f) => f.fichero).join(\", \")}.`,\n\t\t\t\t\t]\n\t\t\t\t: []),\n\t\t\t...(chain.incompletos?.length\n\t\t\t\t? [\n\t\t\t\t\t\t`${chain.incompletos.length} fichero(s) han perdido entradas por la cola: ${chain.incompletos.map((f) => `${f.fichero} (faltan ${f.faltan})`).join(\", \")}.`,\n\t\t\t\t\t]\n\t\t\t\t: []),\n\t\t\t...(chain.sinAncla?.length\n\t\t\t\t? [\n\t\t\t\t\t\t`${chain.sinAncla.length} fichero(s) sin ancla en el índice (escritos antes de que existiera): su desaparición no se podría detectar.`,\n\t\t\t\t\t]\n\t\t\t\t: []),\n\t\t\t\"La cadena hash prueba INTEGRIDAD INTERNA del log (que no se editó ni reordenó), no PROCEDENCIA: no acredita quién lo generó ni en qué máquina.\",\n\t\t\t\"Para no-repudio hace falta firma con clave gestionada (HSM); este bundle no la incluye.\",\n\t\t\t\"El bundle refleja lo que el agente registró. No es una auditoría independiente del código resultante.\",\n\t\t],\n\t};\n\tawait writeFile(join(outDir, \"manifest.json\"), JSON.stringify(manifest, null, 2), \"utf-8\");\n\treturn manifest;\n}\n"]}

package/dist/core/memory-engine/audit-export.js

@@ -0,0 +1,100 @@
+/**
+ * Bundle de evidencia — auditoría que se queda con el cliente.
+ *
+ * Es la dirección OPUESTA a subir transcripciones a una nube: un cliente
+ * regulado produce, en local y por sí mismo, un artefacto verificable de qué
+ * hizo el agente y qué se verificó. Cero red.
+ *
+ * No inventa nada: junta tres fuentes que ya existen y añade el resultado de la
+ * verificación de la cadena hash.
+ *
+ * ponytail: la cadena hash prueba consistencia interna, NO procedencia. Si un
+ * cliente necesita no-repudio, eso es una conversación de HSM/firma — el
+ * manifiesto lo dice explícitamente en vez de insinuar que lo cubre.
+ */
+import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+/**
+ * Escribe el bundle en `outDir`. Devuelve el manifiesto.
+ * `generatedAt` se inyecta para que el test sea determinista.
+ */
+export async function exportAuditBundle(input, outDir, now = () => new Date().toISOString()) {
+    await mkdir(outDir, { recursive: true });
+    const chain = await input.verify();
+    const all = await input.entries(100000);
+    const audit = input.since
+        ? all.filter((e) => typeof e.ts === "string" && e.ts >= input.since)
+        : all;
+    await writeFile(join(outDir, "audit.jsonl"), audit.map((e) => JSON.stringify(e)).join("\n"), "utf-8");
+    // Runs de workflow: el journal ya guarda script, args, fases y resultPath.
+    const runs = [];
+    if (input.runsDir) {
+        try {
+            for (const file of (await readdir(input.runsDir)).filter((f) => f.endsWith(".json"))) {
+                try {
+                    const state = JSON.parse(await readFile(join(input.runsDir, file), "utf-8"));
+                    if (input.since && typeof state.startedAt === "string" && state.startedAt < input.since)
+                        continue;
+                    runs.push({
+                        runId: state.runId,
+                        name: state.name,
+                        status: state.status,
+                        startedAt: state.startedAt,
+                        updatedAt: state.updatedAt,
+                        agentCount: state.agentCount,
+                        tokenUsage: state.tokenUsage,
+                        phases: state.phases,
+                        resultPath: state.resultPath,
+                        args: state.args,
+                    });
+                }
+                catch {
+                    // un run ilegible no invalida el bundle
+                }
+            }
+        }
+        catch {
+            // sin runs todavía
+        }
+    }
+    await writeFile(join(outDir, "workflow-runs.json"), JSON.stringify(runs, null, 2), "utf-8");
+    // Grafo: la traza de qué se verificó y con qué evidencia.
+    if (input.graphPath) {
+        try {
+            await writeFile(join(outDir, "graph.json"), await readFile(input.graphPath, "utf-8"), "utf-8");
+        }
+        catch {
+            // sin grafo
+        }
+    }
+    const manifest = {
+        version: 1,
+        generatedAt: now(),
+        since: input.since,
+        chain,
+        counts: { auditEntries: audit.length, workflowRuns: runs.length },
+        limitations: [
+            ...(chain.borrados?.length
+                ? [
+                    `FALTAN ${chain.borrados.length} fichero(s) que el índice recuerda, con ${chain.borrados.reduce((n, f) => n + f.entradas, 0)} entrada(s): ${chain.borrados.map((f) => f.fichero).join(", ")}.`,
+                ]
+                : []),
+            ...(chain.incompletos?.length
+                ? [
+                    `${chain.incompletos.length} fichero(s) han perdido entradas por la cola: ${chain.incompletos.map((f) => `${f.fichero} (faltan ${f.faltan})`).join(", ")}.`,
+                ]
+                : []),
+            ...(chain.sinAncla?.length
+                ? [
+                    `${chain.sinAncla.length} fichero(s) sin ancla en el índice (escritos antes de que existiera): su desaparición no se podría detectar.`,
+                ]
+                : []),
+            "La cadena hash prueba INTEGRIDAD INTERNA del log (que no se editó ni reordenó), no PROCEDENCIA: no acredita quién lo generó ni en qué máquina.",
+            "Para no-repudio hace falta firma con clave gestionada (HSM); este bundle no la incluye.",
+            "El bundle refleja lo que el agente registró. No es una auditoría independiente del código resultante.",
+        ],
+    };
+    await writeFile(join(outDir, "manifest.json"), JSON.stringify(manifest, null, 2), "utf-8");
+    return manifest;
+}
+//# sourceMappingURL=audit-export.js.map

package/dist/core/memory-engine/audit-export.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-export.js","sourceRoot":"","sources":["../../../src/core/memory-engine/audit-export.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Bundle de evidencia — auditoría que se queda con el cliente.\n *\n * Es la dirección OPUESTA a subir transcripciones a una nube: un cliente\n * regulado produce, en local y por sí mismo, un artefacto verificable de qué\n * hizo el agente y qué se verificó. Cero red.\n *\n * No inventa nada: junta tres fuentes que ya existen y añade el resultado de la\n * verificación de la cadena hash.\n *\n * ponytail: la cadena hash prueba consistencia interna, NO procedencia. Si un\n * cliente necesita no-repudio, eso es una conversación de HSM/firma — el\n * manifiesto lo dice explícitamente en vez de insinuar que lo cubre.\n */\n\nimport { mkdir, readdir, readFile, writeFile } from \"node:fs/promises\";\nimport { join } from \"node:path\";\nimport type { VeredictoDelRegistro } from \"./audit-indice.ts\";\n\nexport interface AuditBundleInput {\n\t/** Raíz del engine (`<agentDir>/memory-engine`). */\n\trootDir: string;\n\t/** Directorio de runs de workflow (`<agentDir>/workflows/runs`). */\n\trunsDir?: string;\n\t/** Fichero del grafo, si existe. */\n\tgraphPath?: string;\n\t/** Solo entradas con `ts >= since` (ISO). */\n\tsince?: string;\n\t/** Verificador de la cadena (inyectable para tests). */\n\tverify: () => Promise<VeredictoDelRegistro>;\n\t/** Lector de entradas de auditoría. */\n\tentries: (limit: number) => Promise<Array<Record<string, unknown>>>;\n}\n\nexport interface AuditBundleManifest {\n\tversion: 1;\n\tgeneratedAt: string;\n\tsince?: string;\n\t/**\n\t * El veredicto ENTERO, no un resumen.\n\t *\n\t * Antes este campo estaba declarado como `{valid, tamperedAt, entriesChecked}`\n\t * y el veredicto pasaba por ese hueco perdiendo lo demás sin dar un solo\n\t * error: el manifiesto decía `\"chain\": {\"valid\": true}` sobre un registro al\n\t * que le faltaban ficheros enteros. Un tipo intermedio que recorta campos es\n\t * peor que uno que se queja, porque el recorte no se ve en ningún sitio.\n\t */\n\tchain: VeredictoDelRegistro;\n\tcounts: { auditEntries: number; workflowRuns: number };\n\t/** Lo que este bundle NO prueba. Explícito a propósito. */\n\tlimitations: string[];\n}\n\n/**\n * Escribe el bundle en `outDir`. Devuelve el manifiesto.\n * `generatedAt` se inyecta para que el test sea determinista.\n */\nexport async function exportAuditBundle(\n\tinput: AuditBundleInput,\n\toutDir: string,\n\tnow: () => string = () => new Date().toISOString(),\n): Promise<AuditBundleManifest> {\n\tawait mkdir(outDir, { recursive: true });\n\n\tconst chain = await input.verify();\n\n\tconst all = await input.entries(100000);\n\tconst audit = input.since\n\t\t? all.filter((e) => typeof e.ts === \"string\" && (e.ts as string) >= (input.since as string))\n\t\t: all;\n\tawait writeFile(join(outDir, \"audit.jsonl\"), audit.map((e) => JSON.stringify(e)).join(\"\\n\"), \"utf-8\");\n\n\t// Runs de workflow: el journal ya guarda script, args, fases y resultPath.\n\tconst runs: Array<Record<string, unknown>> = [];\n\tif (input.runsDir) {\n\t\ttry {\n\t\t\tfor (const file of (await readdir(input.runsDir)).filter((f) => f.endsWith(\".json\"))) {\n\t\t\t\ttry {\n\t\t\t\t\tconst state = JSON.parse(await readFile(join(input.runsDir, file), \"utf-8\")) as Record<string, unknown>;\n\t\t\t\t\tif (input.since && typeof state.startedAt === \"string\" && state.startedAt < input.since) continue;\n\t\t\t\t\truns.push({\n\t\t\t\t\t\trunId: state.runId,\n\t\t\t\t\t\tname: state.name,\n\t\t\t\t\t\tstatus: state.status,\n\t\t\t\t\t\tstartedAt: state.startedAt,\n\t\t\t\t\t\tupdatedAt: state.updatedAt,\n\t\t\t\t\t\tagentCount: state.agentCount,\n\t\t\t\t\t\ttokenUsage: state.tokenUsage,\n\t\t\t\t\t\tphases: state.phases,\n\t\t\t\t\t\tresultPath: state.resultPath,\n\t\t\t\t\t\targs: state.args,\n\t\t\t\t\t});\n\t\t\t\t} catch {\n\t\t\t\t\t// un run ilegible no invalida el bundle\n\t\t\t\t}\n\t\t\t}\n\t\t} catch {\n\t\t\t// sin runs todavía\n\t\t}\n\t}\n\tawait writeFile(join(outDir, \"workflow-runs.json\"), JSON.stringify(runs, null, 2), \"utf-8\");\n\n\t// Grafo: la traza de qué se verificó y con qué evidencia.\n\tif (input.graphPath) {\n\t\ttry {\n\t\t\tawait writeFile(join(outDir, \"graph.json\"), await readFile(input.graphPath, \"utf-8\"), \"utf-8\");\n\t\t} catch {\n\t\t\t// sin grafo\n\t\t}\n\t}\n\n\tconst manifest: AuditBundleManifest = {\n\t\tversion: 1,\n\t\tgeneratedAt: now(),\n\t\tsince: input.since,\n\t\tchain,\n\t\tcounts: { auditEntries: audit.length, workflowRuns: runs.length },\n\t\tlimitations: [\n\t\t\t...(chain.borrados?.length\n\t\t\t\t? [\n\t\t\t\t\t\t`FALTAN ${chain.borrados.length} fichero(s) que el índice recuerda, con ${chain.borrados.reduce((n, f) => n + f.entradas, 0)} entrada(s): ${chain.borrados.map((f) => f.fichero).join(\", \")}.`,\n\t\t\t\t\t]\n\t\t\t\t: []),\n\t\t\t...(chain.incompletos?.length\n\t\t\t\t? [\n\t\t\t\t\t\t`${chain.incompletos.length} fichero(s) han perdido entradas por la cola: ${chain.incompletos.map((f) => `${f.fichero} (faltan ${f.faltan})`).join(\", \")}.`,\n\t\t\t\t\t]\n\t\t\t\t: []),\n\t\t\t...(chain.sinAncla?.length\n\t\t\t\t? [\n\t\t\t\t\t\t`${chain.sinAncla.length} fichero(s) sin ancla en el índice (escritos antes de que existiera): su desaparición no se podría detectar.`,\n\t\t\t\t\t]\n\t\t\t\t: []),\n\t\t\t\"La cadena hash prueba INTEGRIDAD INTERNA del log (que no se editó ni reordenó), no PROCEDENCIA: no acredita quién lo generó ni en qué máquina.\",\n\t\t\t\"Para no-repudio hace falta firma con clave gestionada (HSM); este bundle no la incluye.\",\n\t\t\t\"El bundle refleja lo que el agente registró. No es una auditoría independiente del código resultante.\",\n\t\t],\n\t};\n\tawait writeFile(join(outDir, \"manifest.json\"), JSON.stringify(manifest, null, 2), \"utf-8\");\n\treturn manifest;\n}\n"]}

package/dist/core/memory-engine/audit-indice.d.ts

@@ -0,0 +1,153 @@
+/**
+ * El índice del audit del motor de memoria: lo que DEBERÍA existir.
+ *
+ * EL AGUJERO, medido antes de escribir nada, sobre un directorio temporal con
+ * cinco entradas y la implementación de `audit.ts` tal como estaba:
+ *
+ *   1) las 5 entradas intactas      : {"valid":true,"entriesChecked":5}
+ *   2) editada la del medio         : {"valid":false,"entriesChecked":2}
+ *   3) fichero BORRADO entero       : {"valid":true,"entriesChecked":0}   <- éxito
+ *   4) TRUNCADO (-2 últimas)        : {"valid":true,"entriesChecked":3}   <- éxito
+ *   5) QUITADA una del medio        : {"valid":false,"entriesChecked":2}
+ *
+ * Y las dos que sacan la forma completa:
+ *
+ *   B) directorio `audit/` borrado  : {"valid":false,"entriesChecked":0}
+ *   C) instalación nueva            : {"valid":false,"entriesChecked":0}   <- lo mismo
+ *
+ * O sea: no había tres estados, había dos, y ninguno caía donde debía. Un
+ * borrado se leía como éxito y una instalación virgen se leía como
+ * manipulación — un detector que acusa a toda instalación limpia deja de
+ * leerse, y con él se va también la señal de la manipulación real.
+ *
+ * LA RAZÓN DE FONDO, y por eso esto es un módulo aparte y no un `if` más en
+ * `verify`: la cadena de hashes NO PUEDE, por construcción, hablar de lo que ya
+ * no está. `readdir(audit/)` solo sabe contestar «lo que hay». Para contestar
+ * «lo que debería haber» hace falta un registro APARTE, que es exactamente lo
+ * que `audit/libro.ts` resolvió con su índice de dos directorios.
+ *
+ * LA DIFERENCIA CON `libro.ts`, que es la que decide el diseño: allí el ancla
+ * es un ENLACE DURO por fichero, y basta porque el ataque que importa es `rm`.
+ * Aquí no basta. Un enlace duro comparte inodo, así que `truncate` recorta los
+ * bytes de los DOS nombres a la vez y el caso 4 seguiría pasando entero. Y el
+ * caso 4 tiene una variante peor, la que de verdad ocurre: truncar y dejar que
+ * el proceso siga: `load()` lee la última entrada superviviente, retoma `seq` y
+ * `lastHash` desde ahí y encadena por encima del hueco. Quedan `seq` 1,2,3,4
+ * correlativos y cadena perfecta, con dos entradas desaparecidas y ni una sola
+ * señal.
+ *
+ * Por eso el ancla de aquí es por ENTRADA y no por fichero: un fichero
+ * `<nombre>.ancla` en `audit-indice/`, append-only, con el hash de cada entrada
+ * escrita, uno por línea. Verificar es entonces una resta de conjuntos: los
+ * hashes que el índice recuerda y que ya no aparecen en el log son entradas que
+ * han desaparecido, se las hayan llevado borrando el fichero, recortándole la
+ * cola o quitándolas del medio.
+ *
+ * DOS DECISIONES QUE CONVIENE NO DESHACER SIN PENSARLAS:
+ *
+ * 1. **Se ancla DESPUÉS de escribir la entrada, nunca antes.** Al revés —
+ *    escribir el ancla primero— un proceso que muera entre las dos escrituras
+ *    dejaría un hash anclado cuya entrada no llegó nunca, y la siguiente
+ *    verificación acusaría de manipulación a un simple corte de luz. Se prefiere
+ *    el fallo del otro lado: durante esa ventana de microsegundos la última
+ *    entrada está sin anclar y su desaparición no se detectaría. Un falso
+ *    negativo estrechísimo es mejor que un falso positivo en cada caída.
+ * 2. **Lo que sobra no acusa.** Entradas del log que no estén en el índice NO
+ *    son un hallazgo: son logs escritos antes de que el índice existiera, o la
+ *    ventana del punto anterior. Solo cuenta lo que el índice recuerda y ya no
+ *    está. Sin esta asimetría, el día de la actualización toda instalación
+ *    existente gritaría «manipulado».
+ *
+ * HASTA DÓNDE LLEGA, dicho sin adornos: quien borre los DOS directorios deja un
+ * registro vacío indistinguible de una instalación nueva. Contra eso no hay
+ * ancla local que valga —cualquier ancla en el mismo disco y con los mismos
+ * permisos se borra igual—; hace falta un ancla externa. Lo que esto elimina es
+ * que un solo `rm` o un solo `truncate` pasen desapercibidos.
+ */
+/** Donde vive el log: `<rootDir>/audit/audit-YYYY-MM-DD.jsonl`. */
+export declare const DIR_AUDIT = "audit";
+/**
+ * El índice: `<rootDir>/audit-indice/<nombre del log>.ancla`.
+ *
+ * Va FUERA de `audit/` a propósito. Dentro, el `rm -rf audit/` que este
+ * mecanismo existe para detectar se llevaría por delante también la prueba.
+ */
+export declare const DIR_INDICE_AUDIT = "audit-indice";
+/** Los tres estados. «Vacío» NO es «íntegro»: ver la cabecera de este fichero. */
+export type EstadoDelRegistro = "integro" | "alterado" | "vacio";
+/**
+ * Por qué está alterado, que no es lo mismo que el hecho de que lo esté.
+ *
+ * Un detector que diera el mismo veredicto a tres causas distintas no
+ * distinguiría ninguna, y el mensaje acabaría acusando de lo que no es.
+ *
+ * `ilegible` es el que no acusa de nada: es «no lo he podido mirar», y va
+ * separado de los demás porque para quien responde a una auditoría no es lo
+ * mismo que «lo he mirado y no cuadra».
+ */
+export type CausaDeAlteracion = "editada" | "enlace-roto" | "borrado" | "faltan-entradas" | "ilegible";
+export interface VeredictoDelRegistro {
+    estado: EstadoDelRegistro;
+    /**
+     * Compat con quien ya lee este veredicto: el modo interactivo, la ruta
+     * `/api/memory/audit` del escritorio y `audit-export.ts`. Es `estado ===
+     * "integro" || estado === "vacio"` — una instalación virgen no está
+     * manipulada, y quien quiera distinguirlas tiene `estado`.
+     */
+    valid: boolean;
+    entriesChecked: number;
+    /** Sello de tiempo de la primera entrada que no cuadra. */
+    tamperedAt?: string;
+    causa?: CausaDeAlteracion;
+    /** Por qué no verifica, en una frase estable. */
+    motivo?: string;
+    /** Dónde mirar. Sin esto el aviso de manipulación se queda en susto. */
+    ficheroAlterado?: string;
+    /** Ficheros que el índice recuerda y que ya no están, con cuántas entradas tenían. */
+    borrados?: {
+        fichero: string;
+        entradas: number;
+    }[];
+    /** Ficheros que siguen ahí pero a los que les faltan entradas ancladas. */
+    incompletos?: {
+        fichero: string;
+        entradas: number;
+        faltan: number;
+    }[];
+    /**
+     * Ficheros del log sin ancla en el índice: logs anteriores al índice.
+     *
+     * NO es una acusación y por eso va aparte: meterlo en `estado: "alterado"`
+     * habría hecho que toda instalación ya existente gritara «manipulado» el día
+     * de la actualización.
+     */
+    sinAncla?: string[];
+}
+/** Carga a hashear de una entrada, tal y como `audit.ts` la reconstruye. */
+type Rehasheador = (prevHash: string | null, carga: Record<string, unknown>) => string;
+/**
+ * Anota en el índice el hash de una entrada recién escrita.
+ *
+ * Append-only y una línea por entrada: sobrescribir un ancla con «la última»
+ * la volvería inútil justo en el caso que importa, porque tras un truncado el
+ * proceso siguiente la sobrescribiría con un número MENOR y borraría la prueba.
+ */
+export declare function anclarEntrada(raiz: string, fichero: string, hash: string): Promise<void>;
+/**
+ * Verifica el registro entero y contesta TRES estados.
+ *
+ * Reparto de tareas, que es lo que hace que esto no sea un parche:
+ *
+ *   · la cadena de hashes dice si lo que HAY está intacto y en orden;
+ *   · el índice dice si lo que hay es TODO lo que hubo.
+ *
+ * Ninguna de las dos puede contestar la pregunta de la otra.
+ *
+ * `rehash` se inyecta en vez de importarse para no crear un ciclo con
+ * `audit.ts`, que es quien tiene la única canonicalización buena — la misma que
+ * usa al escribir, reconstruida con un rest para que las dos caras no puedan
+ * divergir.
+ */
+export declare function verificarRegistro(raiz: string, rehash: Rehasheador): Promise<VeredictoDelRegistro>;
+export {};
+//# sourceMappingURL=audit-indice.d.ts.map

package/dist/core/memory-engine/audit-indice.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-indice.d.ts","sourceRoot":"","sources":["../../../src/core/memory-engine/audit-indice.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiEG;AAKH,mEAAmE;AACnE,eAAO,MAAM,SAAS,UAAU,CAAC;AAEjC;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,iBAAiB,CAAC;AAK/C,wFAAkF;AAClF,MAAM,MAAM,iBAAiB,GAAG,SAAS,GAAG,UAAU,GAAG,OAAO,CAAC;AAEjE;;;;;;;;;GASG;AACH,MAAM,MAAM,iBAAiB,GAAG,SAAS,GAAG,aAAa,GAAG,SAAS,GAAG,iBAAiB,GAAG,UAAU,CAAC;AAEvG,MAAM,WAAW,oBAAoB;IACpC,MAAM,EAAE,iBAAiB,CAAC;IAC1B;;;;;OAKG;IACH,KAAK,EAAE,OAAO,CAAC;IACf,cAAc,EAAE,MAAM,CAAC;IACvB,2DAA2D;IAC3D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,iBAAiB,CAAC;IAC1B,kDAAiD;IACjD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0EAAwE;IACxE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,0FAAsF;IACtF,QAAQ,CAAC,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACnD,4EAA2E;IAC3E,WAAW,CAAC,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACtE;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,4EAA4E;AAC5E,KAAK,WAAW,GAAG,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,CAAC;AAUvF;;;;;;GAMG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAI9F;AAgBD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAuJxG","sourcesContent":["/**\n * El índice del audit del motor de memoria: lo que DEBERÍA existir.\n *\n * EL AGUJERO, medido antes de escribir nada, sobre un directorio temporal con\n * cinco entradas y la implementación de `audit.ts` tal como estaba:\n *\n *   1) las 5 entradas intactas      : {\"valid\":true,\"entriesChecked\":5}\n *   2) editada la del medio         : {\"valid\":false,\"entriesChecked\":2}\n *   3) fichero BORRADO entero       : {\"valid\":true,\"entriesChecked\":0}   <- éxito\n *   4) TRUNCADO (-2 últimas)        : {\"valid\":true,\"entriesChecked\":3}   <- éxito\n *   5) QUITADA una del medio        : {\"valid\":false,\"entriesChecked\":2}\n *\n * Y las dos que sacan la forma completa:\n *\n *   B) directorio `audit/` borrado  : {\"valid\":false,\"entriesChecked\":0}\n *   C) instalación nueva            : {\"valid\":false,\"entriesChecked\":0}   <- lo mismo\n *\n * O sea: no había tres estados, había dos, y ninguno caía donde debía. Un\n * borrado se leía como éxito y una instalación virgen se leía como\n * manipulación — un detector que acusa a toda instalación limpia deja de\n * leerse, y con él se va también la señal de la manipulación real.\n *\n * LA RAZÓN DE FONDO, y por eso esto es un módulo aparte y no un `if` más en\n * `verify`: la cadena de hashes NO PUEDE, por construcción, hablar de lo que ya\n * no está. `readdir(audit/)` solo sabe contestar «lo que hay». Para contestar\n * «lo que debería haber» hace falta un registro APARTE, que es exactamente lo\n * que `audit/libro.ts` resolvió con su índice de dos directorios.\n *\n * LA DIFERENCIA CON `libro.ts`, que es la que decide el diseño: allí el ancla\n * es un ENLACE DURO por fichero, y basta porque el ataque que importa es `rm`.\n * Aquí no basta. Un enlace duro comparte inodo, así que `truncate` recorta los\n * bytes de los DOS nombres a la vez y el caso 4 seguiría pasando entero. Y el\n * caso 4 tiene una variante peor, la que de verdad ocurre: truncar y dejar que\n * el proceso siga: `load()` lee la última entrada superviviente, retoma `seq` y\n * `lastHash` desde ahí y encadena por encima del hueco. Quedan `seq` 1,2,3,4\n * correlativos y cadena perfecta, con dos entradas desaparecidas y ni una sola\n * señal.\n *\n * Por eso el ancla de aquí es por ENTRADA y no por fichero: un fichero\n * `<nombre>.ancla` en `audit-indice/`, append-only, con el hash de cada entrada\n * escrita, uno por línea. Verificar es entonces una resta de conjuntos: los\n * hashes que el índice recuerda y que ya no aparecen en el log son entradas que\n * han desaparecido, se las hayan llevado borrando el fichero, recortándole la\n * cola o quitándolas del medio.\n *\n * DOS DECISIONES QUE CONVIENE NO DESHACER SIN PENSARLAS:\n *\n * 1. **Se ancla DESPUÉS de escribir la entrada, nunca antes.** Al revés —\n *    escribir el ancla primero— un proceso que muera entre las dos escrituras\n *    dejaría un hash anclado cuya entrada no llegó nunca, y la siguiente\n *    verificación acusaría de manipulación a un simple corte de luz. Se prefiere\n *    el fallo del otro lado: durante esa ventana de microsegundos la última\n *    entrada está sin anclar y su desaparición no se detectaría. Un falso\n *    negativo estrechísimo es mejor que un falso positivo en cada caída.\n * 2. **Lo que sobra no acusa.** Entradas del log que no estén en el índice NO\n *    son un hallazgo: son logs escritos antes de que el índice existiera, o la\n *    ventana del punto anterior. Solo cuenta lo que el índice recuerda y ya no\n *    está. Sin esta asimetría, el día de la actualización toda instalación\n *    existente gritaría «manipulado».\n *\n * HASTA DÓNDE LLEGA, dicho sin adornos: quien borre los DOS directorios deja un\n * registro vacío indistinguible de una instalación nueva. Contra eso no hay\n * ancla local que valga —cualquier ancla en el mismo disco y con los mismos\n * permisos se borra igual—; hace falta un ancla externa. Lo que esto elimina es\n * que un solo `rm` o un solo `truncate` pasen desapercibidos.\n */\n\nimport { appendFile, mkdir, readdir, readFile } from \"node:fs/promises\";\nimport { join } from \"node:path\";\n\n/** Donde vive el log: `<rootDir>/audit/audit-YYYY-MM-DD.jsonl`. */\nexport const DIR_AUDIT = \"audit\";\n\n/**\n * El índice: `<rootDir>/audit-indice/<nombre del log>.ancla`.\n *\n * Va FUERA de `audit/` a propósito. Dentro, el `rm -rf audit/` que este\n * mecanismo existe para detectar se llevaría por delante también la prueba.\n */\nexport const DIR_INDICE_AUDIT = \"audit-indice\";\n\nconst RE_LOG = /^audit-.*\\.jsonl$/;\nconst SUFIJO_ANCLA = \".ancla\";\n\n/** Los tres estados. «Vacío» NO es «íntegro»: ver la cabecera de este fichero. */\nexport type EstadoDelRegistro = \"integro\" | \"alterado\" | \"vacio\";\n\n/**\n * Por qué está alterado, que no es lo mismo que el hecho de que lo esté.\n *\n * Un detector que diera el mismo veredicto a tres causas distintas no\n * distinguiría ninguna, y el mensaje acabaría acusando de lo que no es.\n *\n * `ilegible` es el que no acusa de nada: es «no lo he podido mirar», y va\n * separado de los demás porque para quien responde a una auditoría no es lo\n * mismo que «lo he mirado y no cuadra».\n */\nexport type CausaDeAlteracion = \"editada\" | \"enlace-roto\" | \"borrado\" | \"faltan-entradas\" | \"ilegible\";\n\nexport interface VeredictoDelRegistro {\n\testado: EstadoDelRegistro;\n\t/**\n\t * Compat con quien ya lee este veredicto: el modo interactivo, la ruta\n\t * `/api/memory/audit` del escritorio y `audit-export.ts`. Es `estado ===\n\t * \"integro\" || estado === \"vacio\"` — una instalación virgen no está\n\t * manipulada, y quien quiera distinguirlas tiene `estado`.\n\t */\n\tvalid: boolean;\n\tentriesChecked: number;\n\t/** Sello de tiempo de la primera entrada que no cuadra. */\n\ttamperedAt?: string;\n\tcausa?: CausaDeAlteracion;\n\t/** Por qué no verifica, en una frase estable. */\n\tmotivo?: string;\n\t/** Dónde mirar. Sin esto el aviso de manipulación se queda en susto. */\n\tficheroAlterado?: string;\n\t/** Ficheros que el índice recuerda y que ya no están, con cuántas entradas tenían. */\n\tborrados?: { fichero: string; entradas: number }[];\n\t/** Ficheros que siguen ahí pero a los que les faltan entradas ancladas. */\n\tincompletos?: { fichero: string; entradas: number; faltan: number }[];\n\t/**\n\t * Ficheros del log sin ancla en el índice: logs anteriores al índice.\n\t *\n\t * NO es una acusación y por eso va aparte: meterlo en `estado: \"alterado\"`\n\t * habría hecho que toda instalación ya existente gritara «manipulado» el día\n\t * de la actualización.\n\t */\n\tsinAncla?: string[];\n}\n\n/** Carga a hashear de una entrada, tal y como `audit.ts` la reconstruye. */\ntype Rehasheador = (prevHash: string | null, carga: Record<string, unknown>) => string;\n\n/** Lo mínimo que la verificación necesita saber de una entrada. */\ninterface EntradaLeida {\n\tts?: string;\n\thash?: string;\n\tprevHash?: string | null;\n\t[campo: string]: unknown;\n}\n\n/**\n * Anota en el índice el hash de una entrada recién escrita.\n *\n * Append-only y una línea por entrada: sobrescribir un ancla con «la última»\n * la volvería inútil justo en el caso que importa, porque tras un truncado el\n * proceso siguiente la sobrescribiría con un número MENOR y borraría la prueba.\n */\nexport async function anclarEntrada(raiz: string, fichero: string, hash: string): Promise<void> {\n\tconst dir = join(raiz, DIR_INDICE_AUDIT);\n\tawait mkdir(dir, { recursive: true });\n\tawait appendFile(join(dir, fichero + SUFIJO_ANCLA), `${hash}\\n`, \"utf-8\");\n}\n\n/** `null` = no se ha podido mirar, que no es lo mismo que «no hay nada». */\nasync function listar(dir: string, filtro: RegExp): Promise<string[] | null> {\n\ttry {\n\t\treturn (await readdir(dir)).filter((f) => filtro.test(f)).sort();\n\t} catch (error) {\n\t\tif ((error as NodeJS.ErrnoException).code === \"ENOENT\") return [];\n\t\treturn null;\n\t}\n}\n\nfunction veredictoIlegible(motivo: string, comprobadas = 0): VeredictoDelRegistro {\n\treturn { estado: \"alterado\", valid: false, entriesChecked: comprobadas, causa: \"ilegible\", motivo };\n}\n\n/**\n * Verifica el registro entero y contesta TRES estados.\n *\n * Reparto de tareas, que es lo que hace que esto no sea un parche:\n *\n *   · la cadena de hashes dice si lo que HAY está intacto y en orden;\n *   · el índice dice si lo que hay es TODO lo que hubo.\n *\n * Ninguna de las dos puede contestar la pregunta de la otra.\n *\n * `rehash` se inyecta en vez de importarse para no crear un ciclo con\n * `audit.ts`, que es quien tiene la única canonicalización buena — la misma que\n * usa al escribir, reconstruida con un rest para que las dos caras no puedan\n * divergir.\n */\nexport async function verificarRegistro(raiz: string, rehash: Rehasheador): Promise<VeredictoDelRegistro> {\n\tconst dirAudit = join(raiz, DIR_AUDIT);\n\tconst dirIndice = join(raiz, DIR_INDICE_AUDIT);\n\n\tconst logs = await listar(dirAudit, RE_LOG);\n\tif (logs === null)\n\t\treturn veredictoIlegible(\"no se ha podido leer el directorio del registro: no es «está bien», es «no lo sé»\");\n\tconst anclas = await listar(dirIndice, new RegExp(`^audit-.*\\\\.jsonl\\\\${SUFIJO_ANCLA}$`));\n\tif (anclas === null)\n\t\treturn veredictoIlegible(\"no se ha podido leer el índice del registro: no es «está bien», es «no lo sé»\");\n\n\t// Lo que el índice recuerda, por fichero.\n\tconst recordados = new Map<string, string[]>();\n\tfor (const ancla of anclas) {\n\t\tconst nombre = ancla.slice(0, -SUFIJO_ANCLA.length);\n\t\ttry {\n\t\t\tconst hashes = (await readFile(join(dirIndice, ancla), \"utf-8\")).split(\"\\n\").filter(Boolean);\n\t\t\tif (hashes.length > 0) recordados.set(nombre, hashes);\n\t\t} catch {\n\t\t\treturn veredictoIlegible(`no se ha podido leer el ancla de ${nombre}: no es «está bien», es «no lo sé»`);\n\t\t}\n\t}\n\n\t// Un registro que nunca se escribió NO es un registro íntegro. Este es el\n\t// caso C: sin esto, la instalación virgen daba el mismo veredicto que el\n\t// directorio borrado del caso B.\n\tif (logs.length === 0 && recordados.size === 0) {\n\t\treturn { estado: \"vacio\", valid: true, entriesChecked: 0 };\n\t}\n\n\tconst presentes = new Set(logs);\n\tconst borrados: { fichero: string; entradas: number }[] = [];\n\tconst incompletos: { fichero: string; entradas: number; faltan: number }[] = [];\n\tconst sinAncla: string[] = [];\n\n\t// Los ficheros que el índice recuerda y ya NO están. Se cuentan antes de\n\t// recorrer la cadena porque son la EXPLICACIÓN de los enlaces rotos que\n\t// vengan después: sin esto, un fichero borrado se denunciaría como «enlace\n\t// roto» en el fichero siguiente, acusando de mover entradas a quien borró un\n\t// día entero.\n\tfor (const [nombre, hashes] of recordados) {\n\t\tif (!presentes.has(nombre)) borrados.push({ fichero: nombre, entradas: hashes.length });\n\t}\n\n\tlet prevHash: string | null = null;\n\tlet comprobadas = 0;\n\t// La cadena del audit de memoria es GLOBAL entre ficheros —`append` nunca\n\t// reinicia `prevHash` al cambiar de día—, así que se arrastra de un fichero\n\t// al siguiente. Es justo al revés que en `libro.ts`, donde cada fichero es\n\t// una sesión y empieza en `null`.\n\tfor (const nombre of logs) {\n\t\tconst anclados = recordados.get(nombre);\n\t\tif (!anclados) sinAncla.push(nombre);\n\t\tlet crudo: string;\n\t\ttry {\n\t\t\tcrudo = await readFile(join(dirAudit, nombre), \"utf-8\");\n\t\t} catch {\n\t\t\treturn {\n\t\t\t\t...veredictoIlegible(`no se ha podido leer ${nombre}: no es «está bien», es «no lo sé»`, comprobadas),\n\t\t\t\tficheroAlterado: nombre,\n\t\t\t};\n\t\t}\n\t\tconst vistos = new Set<string>();\n\t\tfor (const linea of crudo.split(\"\\n\").filter(Boolean)) {\n\t\t\tlet entrada: EntradaLeida;\n\t\t\ttry {\n\t\t\t\tentrada = JSON.parse(linea) as EntradaLeida;\n\t\t\t} catch {\n\t\t\t\treturn {\n\t\t\t\t\testado: \"alterado\",\n\t\t\t\t\tvalid: false,\n\t\t\t\t\tentriesChecked: comprobadas,\n\t\t\t\t\tcausa: \"editada\",\n\t\t\t\t\tmotivo: \"hay una línea que no es JSON válido\",\n\t\t\t\t\tficheroAlterado: nombre,\n\t\t\t\t\t...(borrados.length ? { borrados } : {}),\n\t\t\t\t};\n\t\t\t}\n\t\t\tconst { hash, prevHash: declarado, ...carga } = entrada;\n\t\t\t// Dos preguntas distintas que antes iban juntas y contestaban lo mismo:\n\t\t\t//\n\t\t\t//   · ¿el hash cuadra con SU PROPIO contenido? -> la han editado.\n\t\t\t//   · ¿su `prevHash` apunta a la anterior?     -> faltan entradas o\n\t\t\t//     están cambiadas de orden.\n\t\t\tif (typeof hash !== \"string\" || hash !== rehash(declarado ?? null, carga)) {\n\t\t\t\treturn {\n\t\t\t\t\testado: \"alterado\",\n\t\t\t\t\tvalid: false,\n\t\t\t\t\tentriesChecked: comprobadas,\n\t\t\t\t\ttamperedAt: entrada.ts,\n\t\t\t\t\tcausa: \"editada\",\n\t\t\t\t\tmotivo: \"el hash de una entrada no cuadra con su contenido: la han editado\",\n\t\t\t\t\tficheroAlterado: nombre,\n\t\t\t\t\t...(borrados.length ? { borrados } : {}),\n\t\t\t\t};\n\t\t\t}\n\t\t\tif ((declarado ?? null) !== prevHash) {\n\t\t\t\t// Un enlace roto DESPUÉS de una ausencia ya conocida no es un\n\t\t\t\t// hallazgo nuevo: es su consecuencia. Se sigue leyendo para poder\n\t\t\t\t// contar lo que queda, y la causa se decide al final.\n\t\t\t\tif (borrados.length === 0 && incompletos.length === 0) {\n\t\t\t\t\treturn {\n\t\t\t\t\t\testado: \"alterado\",\n\t\t\t\t\t\tvalid: false,\n\t\t\t\t\t\tentriesChecked: comprobadas,\n\t\t\t\t\t\ttamperedAt: entrada.ts,\n\t\t\t\t\t\tcausa: \"enlace-roto\",\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\tficheroAlterado: nombre,\n\t\t\t\t\t};\n\t\t\t\t}\n\t\t\t}\n\t\t\tvistos.add(hash);\n\t\t\tprevHash = hash;\n\t\t\tcomprobadas++;\n\t\t}\n\t\t// La resta que la cadena no puede hacer: lo que el índice recuerda y el\n\t\t// fichero ya no enseña. Cubre el truncado, el truncado-y-seguir-\n\t\t// escribiendo, y la entrada quitada del medio.\n\t\tif (anclados) {\n\t\t\tconst faltan = anclados.filter((h) => !vistos.has(h)).length;\n\t\t\tif (faltan > 0) incompletos.push({ fichero: nombre, entradas: anclados.length, faltan });\n\t\t}\n\t}\n\n\tif (borrados.length > 0 || incompletos.length > 0) {\n\t\tconst soloBorrados = incompletos.length === 0;\n\t\treturn {\n\t\t\testado: \"alterado\",\n\t\t\tvalid: false,\n\t\t\tentriesChecked: comprobadas,\n\t\t\tcausa: soloBorrados ? \"borrado\" : \"faltan-entradas\",\n\t\t\tmotivo: soloBorrados\n\t\t\t\t? \"el índice recuerda ficheros que ya no están: los han borrado\"\n\t\t\t\t: \"faltan entradas que el índice recuerda haber escrito: las han quitado del registro\",\n\t\t\t...(borrados.length ? { borrados } : {}),\n\t\t\t...(incompletos.length ? { incompletos } : {}),\n\t\t\t...(sinAncla.length ? { sinAncla } : {}),\n\t\t};\n\t}\n\n\t// Un registro con ancla y sin entradas todavía sigue siendo un registro\n\t// vacío: `estado: \"vacio\"` y no `\"integro\"`, para que la respuesta no\n\t// dependa de si el índice llegó a crearse antes de la primera entrada.\n\treturn {\n\t\testado: comprobadas === 0 ? \"vacio\" : \"integro\",\n\t\tvalid: true,\n\t\tentriesChecked: comprobadas,\n\t\t...(sinAncla.length ? { sinAncla } : {}),\n\t};\n}\n"]}