crbro-memory 2.10.0 → 2.11.0

package/dist/engine/cortex.js

@@ -1,15 +1,24 @@
 "use strict";
 // ─── CRBRO Cortex Engine ─────────────────────────────────────────
 // Neuron CRUD — create, read, update, list neurons
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Cortex = exports.MAX_PROMOTION_CANDIDATES = exports.sessionScope = exports.newTally = void 0;
+exports.Cortex = exports.MAX_PROMOTION_CANDIDATES = exports.sessionScope = exports.newTally = exports.UnreadableNeuronError = void 0;
 exports.nearDuplicatesAmong = nearDuplicatesAmong;
 exports.findPromotionCandidates = findPromotionCandidates;
 exports.unionNeuron = unionNeuron;
 exports.normalizeKeys = normalizeKeys;
 const node_async_hooks_1 = require("node:async_hooks");
+const node_fs_1 = require("node:fs");
+const node_path_1 = __importDefault(require("node:path"));
 const fs_js_1 = require("../utils/fs.js");
+const lock_js_1 = require("../utils/lock.js");
 const ids_js_1 = require("../utils/ids.js");
+const quarantine_js_1 = require("./quarantine.js");
+const backup_js_1 = require("./backup.js");
+const heat_js_1 = require("./heat.js");
 const hash_js_1 = require("../utils/hash.js");
 const ops_js_1 = require("../sync/ops.js");
 const materialize_js_1 = require("../sync/materialize.js");
@@ -25,8 +34,34 @@ const TYPE_PREFIX_RE = /^(project_|tech_|lang_|person_|domain_|process_|protocol
  */
 const NEAR_DUP_THRESHOLD = 0.8;
 const NEAR_DUP_MIN_LENGTH = 60;
-/** Minimum similarity before we accept a near-miss as "the same topic". */
-const NAME_MATCH_THRESHOLD = 0.85;
+/**
+ * A neuron file that exists and cannot be parsed. Readers skip it and list it
+ * (Cortex.unreadable); writers refuse with this error, which names the file
+ * and where a good copy may be.
+ */
+class UnreadableNeuronError extends Error {
+    neuronId;
+    path;
+    recovery;
+    constructor(neuronId, path, recovery, reason) {
+        super(`Neuron "${neuronId}" cannot be read (${reason}). Nothing was written. ${recovery}`);
+        this.neuronId = neuronId;
+        this.path = path;
+        this.recovery = recovery;
+        this.name = 'UnreadableNeuronError';
+    }
+}
+exports.UnreadableNeuronError = UnreadableNeuronError;
+/**
+ * The same identifier written two ways: underscores dropped and each long
+ * word's plural folded ("widget_catalogs" ~ "widget catalog", "octo_chat" ~
+ * "octochat"). Nothing else. The bigram similarity this replaces merged
+ * "sprint_a" into "sprint_b" (0.857 ≥ 0.85) and any two long names one letter
+ * apart: a letter that differs is usually what tells two things apart.
+ */
+function nameVariantKey(slug) {
+    return slug.split('_').filter(Boolean).map(t => (t.length > 4 && !/\d/.test(t) ? t.replace(/(es|s)$/, '') : t)).join('');
+}
 const newTally = () => ({ facts: 0, decisions: 0, topics: new Set(), witnessed: new Set() });
 exports.newTally = newTally;
 /**
@@ -41,28 +76,26 @@ exports.sessionScope = new node_async_hooks_1.AsyncLocalStorage();
  * for "Widget Catalog" vs "widget_catalog", and — unlike substring containment —
  * it does not consider a 60-character walkthrough id a match for "SEO".
  */
-function similarity(a, b) {
-    if (a === b)
-        return 1;
-    if (a.length < 2 || b.length < 2)
+function bigramsOf(s) {
+    const out = new Map();
+    for (let i = 0; i < s.length - 1; i++) {
+        const g = s.slice(i, i + 2);
+        out.set(g, (out.get(g) || 0) + 1);
+    }
+    return out;
+}
+/** Dice of a precomputed bigram map (text of length aLen) against b. */
+function diceFrom(A, aLen, b) {
+    if (aLen < 2 || b.length < 2)
         return 0;
-    const bigrams = (s) => {
-        const out = new Map();
-        for (let i = 0; i < s.length - 1; i++) {
-            const g = s.slice(i, i + 2);
-            out.set(g, (out.get(g) || 0) + 1);
-        }
-        return out;
-    };
-    const A = bigrams(a);
-    const B = bigrams(b);
+    const B = bigramsOf(b);
     let shared = 0;
     for (const [g, countA] of A) {
         const countB = B.get(g);
         if (countB)
             shared += Math.min(countA, countB);
     }
-    return (2 * shared) / (a.length - 1 + b.length - 1);
+    return (2 * shared) / (aLen - 1 + b.length - 1);
 }
 /**
  * Do two slugs carry the same numbers, in the same order?
@@ -89,17 +122,20 @@ function nearDuplicatesAmong(content, candidates) {
     if (content.length < NEAR_DUP_MIN_LENGTH)
         return [];
     const nuevo = content.toLowerCase();
+    // The new text's bigrams once, not once per candidate (2.11): on a 700-fact
+    // neuron that was the same map rebuilt hundreds of times per learn.
+    const bigramasNuevo = bigramsOf(nuevo);
     const out = [];
     for (const c of candidates) {
         if (!c.text || c.text.length < NEAR_DUP_MIN_LENGTH)
             continue;
         // Dice over bigrams cannot reach the threshold when one side is much
         // longer: 2·min/(a+b) bounds it. A free filter before the real count.
-        const otro = c.text.toLowerCase();
-        const a = nuevo.length, b = otro.length;
+        const a = nuevo.length, b = c.text.length;
         if ((2 * Math.min(a, b)) / (a + b) < NEAR_DUP_THRESHOLD)
             continue;
-        const score = similarity(nuevo, otro);
+        const otro = c.text.toLowerCase();
+        const score = nuevo === otro ? 1 : diceFrom(bigramasNuevo, nuevo.length, otro);
         if (score >= NEAR_DUP_THRESHOLD)
             out.push({ id: c.id, similarity: Math.round(score * 100) / 100, text: c.text });
     }
@@ -548,20 +584,108 @@ class Cortex {
     /**
      * Copy a whole neuron to .quarantine/ with a timestamp, before anything
      * destructive. Same stamp format everywhere, so restoreNeuron can pick the
-     * newest copy by name alone.
+     * newest copy by name alone. Sealed when encryption at rest is on; throws
+     * (and the caller removes nothing) when it is on and the key is missing.
      */
     async quarantine(neuron) {
-        const sello = (0, fs_js_1.now)().replace(/[:.]/g, '-');
-        const backup = `${this.brain.paths.quarantine}/${neuron.id}.${sello}.json`;
-        await (0, fs_js_1.writeJSON)(backup, neuron);
-        return backup;
+        return (0, quarantine_js_1.writeQuarantine)(this.brain.paths.quarantine, neuron.id, neuron, 'whole');
     }
-    /** Remove the neuron file, drop its chunks, and keep the manifest honest. */
-    async deleteNeuronFile(id) {
-        await (0, fs_js_1.deleteJSON)(this.brain.paths.neuron(id));
-        await this.unindex(id);
-        const manifest = await this.brain.getManifest();
-        await this.brain.updateManifest({ total_neurons: Math.max(0, manifest.total_neurons - 1) });
+    /** Neuron files that exist and could not be parsed, seen by this process (2.11). */
+    skipped = new Map();
+    /** Where a good copy of a neuron may be: the newest backup, or a quarantine copy. */
+    async recoveryHint(id) {
+        const partes = [];
+        try {
+            const copias = (await (0, quarantine_js_1.listQuarantine)(this.brain.paths.quarantine, id)).filter(c => c.kind === 'whole');
+            if (copias.length)
+                partes.push(`a whole copy is in quarantine (${node_path_1.default.join(this.brain.paths.quarantine, copias[0].file)}; crbro_forget restore:true brings it back once the bad file is moved aside)`);
+        }
+        catch { /* no quarantine */ }
+        try {
+            const dir = (0, backup_js_1.resolveBackupDir)(this.brain.paths.root);
+            const b = (await (0, backup_js_1.listBackups)(dir))[0];
+            if (b)
+                partes.push(`the newest backup is ${b.path} (npx crbro-memory backup restore "${b.file}" --into <empty folder>, then copy cortex/${id}.json back)`);
+        }
+        catch { /* no backups */ }
+        const donde = partes.length ? `Recovery: ${partes.join('; or ')}.` : 'No backup or quarantine copy was found.';
+        return `${donde} Or fix the JSON by hand (a UTF-8 byte-order mark is accepted since 2.11).`;
+    }
+    async noteUnreadable(id, err) {
+        const info = {
+            id,
+            path: this.brain.paths.neuron(id),
+            error: err instanceof fs_js_1.CorruptJSONError ? err.reason : err?.message || String(err),
+            recovery: await this.recoveryHint(id),
+        };
+        this.skipped.set(id, info);
+        return info;
+    }
+    /**
+     * Unreadable neuron files: the ones readers met and skipped since this
+     * process started (default), or every one on disk now (`scan: true`).
+     * Callers that list or search the cortex surface these instead of failing.
+     */
+    async unreadable(options) {
+        if (options?.scan) {
+            for (const id of await (0, fs_js_1.listJSONFiles)(this.brain.paths.cortex)) {
+                try {
+                    await (0, fs_js_1.readJSON)(this.brain.paths.neuron(id));
+                    this.skipped.delete(id);
+                }
+                catch (err) {
+                    await this.noteUnreadable(id, err);
+                }
+            }
+        }
+        // A file fixed since it was seen is no longer reported.
+        const out = [];
+        for (const [id, info] of this.skipped) {
+            try {
+                await (0, fs_js_1.readJSON)(this.brain.paths.neuron(id));
+                this.skipped.delete(id);
+            }
+            catch {
+                out.push(info);
+            }
+        }
+        return out.sort((a, b) => (a.id < b.id ? -1 : 1));
+    }
+    /** A strict read for write paths: null when absent, UnreadableNeuronError when corrupt. */
+    async readStrict(id) {
+        try {
+            return await (0, fs_js_1.readJSON)(this.brain.paths.neuron(id));
+        }
+        catch (err) {
+            if (!(await (0, fs_js_1.fileExists)(this.brain.paths.neuron(id))))
+                return null;
+            const info = await this.noteUnreadable(id, err);
+            throw new UnreadableNeuronError(id, info.path, info.recovery, info.error);
+        }
+    }
+    /**
+     * updateJSON on a neuron, with a corrupt file turned into an error that
+     * names it and says where a good copy is.
+     */
+    async updateNeuron(id, mutate) {
+        try {
+            return await (0, fs_js_1.updateJSON)(this.brain.paths.neuron(id), mutate);
+        }
+        catch (err) {
+            if (err instanceof fs_js_1.CorruptJSONError) {
+                const info = await this.noteUnreadable(id, err);
+                throw new UnreadableNeuronError(id, info.path, info.recovery, info.error);
+            }
+            throw err;
+        }
+    }
+    /** Resolution for write paths: exact id first, then the name; a corrupt match is an error, not a miss. */
+    async resolveForWrite(ref) {
+        return (await this.readStrict(ref)) || (await this.findByName(ref, { strict: true }));
+    }
+    /** The neuron was deleted between resolution and the lock: a write must not bring it back. */
+    deletedMeanwhile(id) {
+        return new Error(`Neuron "${id}" was deleted while this write was in progress. Nothing was written, so it was not brought back.`);
     }
     async emit(neuronId, change) {
         if (!this.emitter)
@@ -582,7 +706,7 @@ class Cortex {
     async mergeFromSync(nid, ops) {
         let report;
         let created = false;
-        const saved = await (0, fs_js_1.updateJSON)(this.brain.paths.neuron(nid), current => {
+        const saved = await this.updateNeuron(nid, current => {
             created = current === null;
             const merged = (0, materialize_js_1.applyOps)(current, ops, { id: nid });
             report = merged.report;
@@ -597,19 +721,46 @@ class Cortex {
         if (!this.indexer)
             return;
         try {
-            await this.indexer(neuron);
+            // Heat lives in the derived heat state since 2.11 and is no longer
+            // rewritten into every neuron file; the index gets the current value.
+            const h = (await this.heatMap()).get(neuron.id);
+            await this.indexer(h === undefined || h === neuron.heat ? neuron : { ...neuron, heat: h });
         }
         catch {
             // Indexing must never break a write. The index is derived data.
         }
     }
+    heatCache = null;
+    /**
+     * id → heat from the derived heat state (prefrontal/heat_state.json),
+     * cached on the file's mtime. Empty when it was never computed: readers
+     * then fall back to the heat stored in the neuron, as before 2.11.
+     */
+    async heatMap() {
+        const file = node_path_1.default.join(this.brain.paths.prefrontal, 'heat_state.json');
+        let mtime = 0;
+        try {
+            mtime = (await node_fs_1.promises.stat(file)).mtimeMs;
+        }
+        catch {
+            return new Map();
+        }
+        if (this.heatCache && this.heatCache.mtime === mtime)
+            return this.heatCache.map;
+        const state = await (0, heat_js_1.readHeatState)(this.brain).catch(() => null);
+        const map = new Map();
+        for (const [id, e] of Object.entries(state?.neurons || {}))
+            map.set(id, e.heat);
+        this.heatCache = { mtime, map };
+        return map;
+    }
     /**
      * Get a neuron by ID.
      */
     async get(id) {
         // Even a read touches the file (access time and count), so it goes through
         // the same locked read-modify-write as everything else.
-        return (0, fs_js_1.updateJSON)(this.brain.paths.neuron(id), current => {
+        return this.updateNeuron(id, current => {
             if (!current)
                 return null;
             current.last_accessed = (0, fs_js_1.now)();
@@ -619,9 +770,24 @@ class Cortex {
     }
     /**
      * Get a neuron by ID without updating access stats.
+     *
+     * Tolerant (2.11): a file that exists and cannot be parsed reads as null
+     * and is recorded in unreadable(), so one truncated neuron no longer takes
+     * down recall, inspect or consolidate. Write paths use a strict read.
      */
     async peek(id) {
-        return (0, fs_js_1.readJSON)(this.brain.paths.neuron(id));
+        // A reference with a path separator is a name ("CI/CD") or an attempt to leave the brain, never an id.
+        if (typeof id !== 'string' || !id || /[\\/:\0]/.test(id))
+            return null;
+        try {
+            return await (0, fs_js_1.readJSON)(this.brain.paths.neuron(id));
+        }
+        catch (err) {
+            // An existing file that does not parse is recorded; anything else is a miss.
+            if (await (0, fs_js_1.fileExists)(this.brain.paths.neuron(id)))
+                await this.noteUnreadable(id, err);
+            return null;
+        }
     }
     /**
      * Find a neuron by name.
@@ -635,49 +801,76 @@ class Cortex {
      * wrong neuron, and no amount of index tuning repairs that. A wrong guess
      * is worse than a new neuron.
      */
-    async findByName(name) {
-        const ids = await (0, fs_js_1.listJSONFiles)(this.brain.paths.cortex);
-        const slug = (0, ids_js_1.toSnakeCase)(name);
-        if (!slug)
+    async findByName(name, options) {
+        const r = await this.resolveTopic(name, options);
+        if (!r)
             return null;
-        // Neurons created before accents were folded live under a mangled name
-        // ("bsqueda" for "búsqueda"). Try the correct slug first, then that one,
-        // so upgrading does not orphan them.
-        const legacy = (0, ids_js_1.legacySnakeCase)(name);
-        const candidatos = legacy && legacy !== slug ? [slug, legacy] : [slug];
-        // 1. Exact: the id itself, or the id minus its type prefix.
-        for (const buscado of candidatos) {
-            for (const id of ids) {
-                if (id === buscado || id.replace(TYPE_PREFIX_RE, '') === buscado) {
-                    return this.peek(id);
-                }
+        return options?.strict ? this.readStrict(r.id) : this.peek(r.id);
+    }
+    /**
+     * Which existing neuron a topic names, without reading any neuron unless
+     * two candidates tie. In order, for each slug the name may be filed under
+     * (current rule, the 2.10 rule, the pre-1.x accent-mangling rule):
+     *
+     *  1. `id`   — the slug IS an existing id ("project_crbro");
+     *  2. `name` — an id minus its type prefix equals the slug;
+     *  3. `variant` — the same identifier written with or without underscores
+     *     or a plural (see nameVariantKey). Never a letter or a number apart.
+     *
+     * Several neurons of different types on one name (project_react and
+     * tech_react): the requested type wins, then the type an id-shaped topic
+     * names, then the type the name implies; failing that the most used, and
+     * the others come back in `ambiguous` so the caller can say so.
+     */
+    async resolveTopic(name, options) {
+        const cands = (0, ids_js_1.slugCandidates)(name);
+        if (cands.length === 0)
+            return null;
+        const ids = await (0, fs_js_1.listJSONFiles)(this.brain.paths.cortex);
+        const idSet = new Set(ids);
+        const bareOf = (id) => id.replace(TYPE_PREFIX_RE, '');
+        const typeOf = (id) => (0, ids_js_1.typeOfIdShape)(id);
+        const prefer = [];
+        if (options?.type)
+            prefer.push(options.type);
+        const shape = (0, ids_js_1.typeOfIdShape)(cands[0]);
+        if (shape)
+            prefer.push(shape);
+        prefer.push((0, ids_js_1.inferNeuronType)(name));
+        const pick = async (matches, resolved_by) => {
+            if (matches.length === 1)
+                return { id: matches[0], resolved_by };
+            for (const t of prefer) {
+                const delTipo = matches.filter(id => typeOf(id) === t);
+                if (delTipo.length === 1)
+                    return { id: delTipo[0], resolved_by, ambiguous: matches.filter(m => m !== delTipo[0]) };
             }
-        }
-        // 2. Near-miss, but only a real one. Ties go to the most used neuron.
-        const candidates = [];
-        for (const id of ids) {
-            const bare = id.replace(TYPE_PREFIX_RE, '');
-            const score = similarity(slug, bare);
-            if (score >= NAME_MATCH_THRESHOLD && sameNumbers(slug, bare)) {
-                candidates.push({ id, score });
+            let best = null;
+            for (const id of [...matches].sort()) {
+                const n = await this.peek(id);
+                const uses = n?.access_count || 0;
+                if (!best || uses > best.uses)
+                    best = { id, uses };
             }
+            return { id: best.id, resolved_by, ambiguous: matches.filter(m => m !== best.id) };
+        };
+        for (const s of cands) {
+            if (idSet.has(s))
+                return { id: s, resolved_by: 'id' };
+            // An id-shaped slug also matches an id that carries its prefix twice
+            // ("project_x" → project_project_x, made by 2.10 from such a topic):
+            // that one's bare id is the slug itself.
+            const bare = ids.filter(id => bareOf(id) === s);
+            if (bare.length)
+                return pick(bare, 'name');
         }
-        if (candidates.length === 0)
-            return null;
-        candidates.sort((a, b) => b.score - a.score);
-        const top = candidates[0].score;
-        const tied = candidates.filter(c => c.score >= top - 0.001);
-        if (tied.length === 1)
-            return this.peek(tied[0].id);
-        let best = null;
-        for (const c of tied) {
-            const n = await this.peek(c.id);
-            if (!n)
-                continue;
-            if (!best || (n.access_count || 0) > (best.access_count || 0))
-                best = n;
+        const key = nameVariantKey(cands[0].replace(TYPE_PREFIX_RE, ''));
+        if (key.length >= 4) {
+            const variantes = ids.filter(id => nameVariantKey(bareOf(id)) === key);
+            if (variantes.length)
+                return pick(variantes, 'variant');
         }
-        return best;
+        return null;
     }
     /**
      * Create a new neuron.
@@ -689,7 +882,7 @@ class Cortex {
         // Check-then-create has to happen inside the lock, or two clients starting
         // the same topic at the same moment both think they are the first.
         let creada = false;
-        const neuron = await (0, fs_js_1.updateJSON)(this.brain.paths.neuron(id), current => {
+        const neuron = await this.updateNeuron(id, current => {
             if (current)
                 return null;
             creada = true;
@@ -733,32 +926,72 @@ class Cortex {
         // exists and what kind — the knowledge without the liability.
         const limpio = (0, secrets_js_1.redact)(content);
         content = limpio.text;
-        let neuron = null;
+        // The rationale and the aliases are stored, indexed and shared too (G8).
+        if (options?.rationale || options?.keys?.length) {
+            options = { ...options,
+                ...(options.rationale ? { rationale: (0, secrets_js_1.redact)(options.rationale).text } : {}),
+                ...(options.keys?.length ? { keys: options.keys.map(k => (0, secrets_js_1.redact)(k).text) } : {}) };
+        }
         let action = 'updated';
+        let targetId;
+        let resolvedBy;
+        let ambiguous;
+        // Resolution reads no neuron (2.11): only the id is needed here, and the
+        // lock below reads the file anyway. On a 1 MB neuron that was a whole
+        // extra parse per learn.
         if (options?.neuronId) {
-            neuron = await this.peek(options.neuronId);
-        }
-        if (!neuron) {
-            neuron = await this.findByName(topic);
+            // An explicit id is a promise about where the knowledge goes. A typo in
+            // it used to fall back to the topic and write somewhere else, silently.
+            const nid = options.neuronId.trim();
+            const existe = !!nid && !/[\\/]/.test(nid) && await (0, fs_js_1.fileExists)(this.brain.paths.neuron(nid));
+            // The one case an absent id is created: it is exactly the id the topic
+            // itself makes ("Tienda" + project_tienda). Anything else would be the
+            // knowledge landing somewhere the caller did not name.
+            const tipoDelId = existe ? null : (0, ids_js_1.typeOfIdShape)(nid);
+            const mismoId = !!tipoDelId && !!topic.trim() && (0, ids_js_1.neuronId)(topic, tipoDelId) === nid;
+            if (existe) {
+                targetId = nid;
+                resolvedBy = 'neuron_id';
+            }
+            else if (mismoId && options.createIfMissing !== false) {
+                targetId = (await this.create(topic, tipoDelId, options.domain || 'general')).id;
+                action = 'created';
+                resolvedBy = 'created';
+            }
+            else {
+                throw new Error(`No neuron with id "${options.neuronId}". Nothing was written. ` +
+                    'Find the right id with crbro_recall or crbro_inspect view=neurons, or pass only topic to resolve it by name.');
+            }
         }
-        if (!neuron) {
-            if (options?.createIfMissing === false) {
-                return {
-                    neuron: null, action: 'skipped', superseded: 0,
-                    supersedes_unmatched: options?.supersedes || [], near_duplicates: [], redacted: limpio.found,
-                    duplicate: false, updated_in_place: false, skipped_retired: null,
-                };
+        else {
+            const r = await this.resolveTopic(topic, { type: options?.neuronType });
+            if (r) {
+                targetId = r.id;
+                resolvedBy = r.resolved_by;
+                ambiguous = r.ambiguous;
+            }
+            else {
+                if (options?.createIfMissing === false) {
+                    return {
+                        neuron: null, action: 'skipped', superseded: 0,
+                        supersedes_unmatched: options?.supersedes || [], near_duplicates: [], redacted: limpio.found,
+                        duplicate: false, updated_in_place: false, skipped_retired: null,
+                    };
+                }
+                const nType = options?.neuronType || (0, ids_js_1.inferNeuronType)(topic);
+                const domain = options?.domain || 'general';
+                targetId = (await this.create(topic, nType, domain)).id;
+                action = 'created';
+                resolvedBy = 'created';
             }
-            const nType = options?.neuronType || (0, ids_js_1.inferNeuronType)(topic);
-            const domain = options?.domain || 'general';
-            neuron = await this.create(topic, nType, domain);
-            action = 'created';
         }
         let superseded = 0;
-        // Stays empty unless retire() actually runs: a duplicate fact skips the
-        // whole block, and warning "still live" about targets nobody touched is
-        // a false alarm on every idempotent retry.
+        // Only targets that matched nothing, live or already retired: a retry of
+        // a supersedes that already ran finds its target retired, and warning
+        // "still live" about it would be a false alarm.
         let supersedesUnmatched = [];
+        let retiradosAhora = [];
+        let gone = false;
         let nearDuplicates = [];
         let emitir = null;
         let duplicate = false;
@@ -803,13 +1036,50 @@ class Cortex {
                     delete n.entry_source;
             }
         };
-        const actualizada = await (0, fs_js_1.updateJSON)(this.brain.paths.neuron(neuron.id), current => {
-            const n = current || neuron;
+        // One identity rule for every kind (2.11): the normalised text entryId
+        // hashes — whitespace runs collapsed, NFC. Before, a pattern differing by
+        // a line break was stored twice under one sidecar key, and a fact with a
+        // trailing newline became a second fact.
+        const clave = (0, ops_js_1.normalizeText)(content);
+        const mismaEntrada = (t) => t === content || (0, ops_js_1.normalizeText)(t) === clave;
+        const claveLower = clave.toLowerCase();
+        const contentLower = content.toLowerCase();
+        const mismoHecho = (t) => {
+            if (t.length === content.length && t.toLowerCase() === contentLower)
+                return true;
+            // Normalising only shrinks a text, so a shorter one cannot match.
+            if (t.length < clave.length || t.length > clave.length * 2 + 16)
+                return false;
+            return (0, ops_js_1.normalizeText)(t).toLowerCase() === claveLower;
+        };
+        const supersedeDesde = (n, propio) => {
+            if (!options?.supersedes?.length)
+                return;
+            // A fact never supersedes itself, whatever the caller listed.
+            const objetivos = options.supersedes.filter(t => t.trim().toLowerCase() !== propio.id.toLowerCase() && !mismoHecho(t.trim()));
+            const r = this.retire(n, objetivos, propio.id, 'superseded');
+            superseded = r.count;
+            retiradosAhora = r.ids;
+            // A target that is already retired was found: a retry of a supersedes
+            // that already ran is not a miss.
+            const yaRetirado = (t) => {
+                const w = t.trim().toLowerCase();
+                return n.facts.some(f => (f.status === 'superseded' || f.status === 'retracted')
+                    && ((f.id || (0, hash_js_1.factId)(f.text)).toLowerCase() === w || f.text.trim().toLowerCase() === w));
+            };
+            supersedesUnmatched = r.unmatched.filter(t => !yaRetirado(t));
+        };
+        const actualizada = await this.updateNeuron(targetId, current => {
+            if (!current) {
+                gone = true;
+                return null;
+            }
+            const n = current;
             switch (type) {
                 case 'fact': {
                     const id = (0, hash_js_1.factId)(content);
                     const keys = normalizeKeys(options?.keys);
-                    const existente = n.facts.find(f => f.text.toLowerCase() === content.toLowerCase());
+                    const existente = n.facts.find(f => mismoHecho(f.text));
                     if (existente && (existente.status === 'superseded' || existente.status === 'retracted')) {
                         // The same line was deliberately retired. Re-adding it would
                         // undo that revision by accident; report it and write nothing.
@@ -905,13 +1175,13 @@ class Cortex {
                             ...(existente.shelf_life ? { shelf: existente.shelf_life } : {}) };
                         const sv = (0, shelf_js_1.shelfOfFact)(existente);
                         shelf = { shelf_life: sv.shelf, inferred: sv.inferred, ...(sv.reason ? { reason: sv.reason } : {}) };
+                        // The same line again WITH supersedes: the retry after fixing a
+                        // mistyped id. It used to skip the retirement in silence, and
+                        // the old value stayed live while the caller believed it gone.
+                        supersedeDesde(n, { id: existente.id || (0, hash_js_1.factId)(existente.text), text: existente.text });
                     }
                     if (!isDuplicate) {
-                        if (options?.supersedes?.length) {
-                            const retirado = this.retire(n, options.supersedes, id, 'superseded');
-                            superseded = retirado.count;
-                            supersedesUnmatched = retirado.unmatched;
-                        }
+                        supersedeDesde(n, { id, text: content });
                         // Near-duplicate check, against what will still be active
                         // AFTER supersedes ran — retiring the old telling is exactly
                         // the fix this warning exists to suggest, so a properly
@@ -953,6 +1223,12 @@ class Cortex {
                 case 'decision': {
                     if (retirada(n, content))
                         return null;
+                    // A retry no longer adds a second copy under the same entry id.
+                    const previa = n.decisions.find(d => mismaEntrada(d.text || ''));
+                    if (previa) {
+                        emitir = { kind: 'decision', text: previa.text, why: previa.rationale || undefined, at: previa.date || (0, fs_js_1.now)() };
+                        break;
+                    }
                     const decision = {
                         text: content,
                         date: (0, fs_js_1.now)(),
@@ -969,16 +1245,18 @@ class Cortex {
                 case 'pattern': {
                     if (retirada(n, content))
                         return null;
-                    if (!n.patterns.includes(content)) {
+                    const previo = n.patterns.find(mismaEntrada);
+                    if (previo === undefined) {
                         n.patterns.push(content);
                         fechar(n, content);
                         origen(n, content);
                     }
-                    emitir = { kind: 'pattern', text: content, at: n.entry_dates?.[(0, ops_js_1.entryId)(content)] || (0, fs_js_1.now)() };
+                    const texto = previo ?? content;
+                    emitir = { kind: 'pattern', text: texto, at: n.entry_dates?.[(0, ops_js_1.entryId)(texto)] || (0, fs_js_1.now)() };
                     break;
                 }
                 case 'preference': {
-                    if (!n.preferences.includes(content)) {
+                    if (!n.preferences.some(mismaEntrada)) {
                         n.preferences.push(content);
                         fechar(n, content);
                     }
@@ -989,13 +1267,15 @@ class Cortex {
                         return null;
                     if (!n.errors)
                         n.errors = [];
-                    if (!n.errors.includes(content)) {
+                    const previo = n.errors.find(mismaEntrada);
+                    if (previo === undefined) {
                         n.errors.push(content);
                         fechar(n, content);
                         origen(n, content);
                         this.tally.topics.add(n.id);
                     }
-                    emitir = { kind: 'error', text: content, at: n.entry_dates?.[(0, ops_js_1.entryId)(content)] || (0, fs_js_1.now)() };
+                    const texto = previo ?? content;
+                    emitir = { kind: 'error', text: texto, at: n.entry_dates?.[(0, ops_js_1.entryId)(texto)] || (0, fs_js_1.now)() };
                     break;
                 }
                 case 'debt': {
@@ -1003,13 +1283,15 @@ class Cortex {
                         return null;
                     if (!n.debts)
                         n.debts = [];
-                    if (!n.debts.includes(content)) {
+                    const previo = n.debts.find(mismaEntrada);
+                    if (previo === undefined) {
                         n.debts.push(content);
                         fechar(n, content);
                         origen(n, content);
                         this.tally.topics.add(n.id);
                     }
-                    emitir = { kind: 'debt', text: content, at: n.entry_dates?.[(0, ops_js_1.entryId)(content)] || (0, fs_js_1.now)() };
+                    const texto = previo ?? content;
+                    emitir = { kind: 'debt', text: texto, at: n.entry_dates?.[(0, ops_js_1.entryId)(texto)] || (0, fs_js_1.now)() };
                     break;
                 }
             }
@@ -1020,13 +1302,16 @@ class Cortex {
             }
             return n;
         });
-        const final = (actualizada || neuron);
+        if (gone || !actualizada)
+            throw this.deletedMeanwhile(targetId);
+        const final = actualizada;
         if (skippedRetired) {
             // Nothing was written, so nothing to index, emit or tally.
             return {
                 neuron: final, action: 'skipped_retired', superseded: 0, supersedes_unmatched: [],
                 near_duplicates: [], redacted: limpio.found,
                 duplicate: false, updated_in_place: false, skipped_retired: skippedRetired,
+                resolved_by: resolvedBy, ...(ambiguous?.length ? { ambiguous } : {}),
             };
         }
         await this.reindex(final);
@@ -1034,6 +1319,12 @@ class Cortex {
         // key and the least likely to be worth sharing.
         if (emitir)
             await this.emit(final.id, emitir);
+        // The retirement travels too (2.11), exactly as crbro_revise sends it:
+        // before, teammates got the new value and kept the old one as current.
+        for (const fid of retiradosAhora) {
+            const f = final.facts.find(x => x.id === fid);
+            await this.emit(final.id, { kind: 'status', fid, to: 'superseded', at: f?.revised || (0, fs_js_1.now)() });
+        }
         return {
             neuron: final, action, superseded, supersedes_unmatched: supersedesUnmatched,
             near_duplicates: nearDuplicates, redacted: limpio.found,
@@ -1041,6 +1332,7 @@ class Cortex {
             ...(confirmations !== undefined ? { confirmations } : {}),
             ...(shelf ? { shelf } : {}),
             ...(shelfLengthened ? { shelf_lengthened: true } : {}),
+            resolved_by: resolvedBy, ...(ambiguous?.length ? { ambiguous } : {}),
         };
     }
     /**
@@ -1053,14 +1345,18 @@ class Cortex {
      * caller usually has the text in front of it and not the hash.
      */
     async revise(neuronRef, targets, options) {
-        const neuron = (await this.peek(neuronRef)) || (await this.findByName(neuronRef));
+        const neuron = await this.resolveForWrite(neuronRef);
         if (!neuron)
             return { neuron: null, revised: 0, unmatched: targets.slice() };
+        if (options?.note)
+            options = { ...options, note: (0, secrets_js_1.redact)(options.note).text }; // G8: notes are stored and shared
         const status = options?.status || 'superseded';
         let revised = 0;
         let unmatched = targets.slice();
-        const actualizada = await (0, fs_js_1.updateJSON)(this.brain.paths.neuron(neuron.id), current => {
-            const n = current || neuron;
+        const actualizada = await this.updateNeuron(neuron.id, current => {
+            if (!current)
+                return null; // deleted meanwhile: never resurrect it (2.11)
+            const n = current;
             const retirado = status === 'active'
                 ? this.reactivate(n, targets, options?.note)
                 : this.retire(n, targets, options?.replacedBy, status, options?.note);
@@ -1111,15 +1407,17 @@ class Cortex {
         const evidence = (0, evidence_js_1.makeVerification)(targets.evidence, (0, fs_js_1.now)());
         const facts = (targets.facts || []).filter(t => typeof t === 'string');
         const entries = (targets.entries || []).filter(t => typeof t === 'string');
-        const neuron = (await this.peek(neuronRef)) || (await this.findByName(neuronRef));
+        const neuron = await this.resolveForWrite(neuronRef);
         if (!neuron)
             return { neuron: null, verified: [], unmatched: [...facts, ...entries], retired: [] };
         const verified = [];
         let unmatched = [];
         let retired = [];
         const emitir = [];
-        const actualizada = await (0, fs_js_1.updateJSON)(this.brain.paths.neuron(neuron.id), current => {
-            const n = current || neuron;
+        const actualizada = await this.updateNeuron(neuron.id, current => {
+            if (!current)
+                return null; // deleted meanwhile: never resurrect it (2.11)
+            const n = current;
             const cuando = (0, fs_js_1.now)();
             verified.length = 0;
             unmatched = [];
@@ -1213,6 +1511,7 @@ class Cortex {
         let count = 0;
         const wanted = targets.map(t => t.trim().toLowerCase());
         const hit = new Set();
+        const ids = [];
         for (const fact of neuron.facts) {
             if (fact.status === 'superseded' || fact.status === 'retracted')
                 continue;
@@ -1233,8 +1532,9 @@ class Cortex {
             if (note)
                 fact.revision_note = note;
             count++;
+            ids.push(fid);
         }
-        return { count, unmatched: targets.filter((_, i) => !hit.has(i)) };
+        return { count, unmatched: targets.filter((_, i) => !hit.has(i)), ids };
     }
     /**
      * Bring retired facts back. The inverse of retire: only superseded or
@@ -1279,15 +1579,19 @@ class Cortex {
      * survives a sync because applyOps copies and prunes it.
      */
     async retireEntries(neuronRef, targets, options) {
-        const neuron = (await this.peek(neuronRef)) || (await this.findByName(neuronRef));
+        const neuron = await this.resolveForWrite(neuronRef);
         if (!neuron)
             return { neuron: null, revised: 0, unmatched: targets.slice() };
+        if (options?.note)
+            options = { ...options, note: (0, secrets_js_1.redact)(options.note).text }; // G8: notes are stored and shared
         const status = options?.status || 'superseded';
         const wanted = targets.map(t => (0, ops_js_1.normalizeText)(t).toLowerCase());
         let revised = 0;
         let unmatched = targets.slice();
-        const actualizada = await (0, fs_js_1.updateJSON)(this.brain.paths.neuron(neuron.id), current => {
-            const n = current || neuron;
+        const actualizada = await this.updateNeuron(neuron.id, current => {
+            if (!current)
+                return null; // deleted meanwhile: never resurrect it (2.11)
+            const n = current;
             const estados = n.entry_status || {};
             const hit = new Set();
             const cuando = (0, fs_js_1.now)();
@@ -1350,7 +1654,7 @@ class Cortex {
      * Not emitted: NeuronOp is only an announcement, and metadata is local.
      */
     async setMeta(neuronRef, meta) {
-        const neuron = (await this.peek(neuronRef)) || (await this.findByName(neuronRef));
+        const neuron = await this.resolveForWrite(neuronRef);
         if (!neuron)
             return { neuron: null, changed: [], redacted: [] };
         let redacted = [];
@@ -1366,8 +1670,10 @@ class Cortex {
         const domain = meta.domain === undefined ? undefined : meta.domain.trim();
         const name = meta.name === undefined ? undefined : meta.name.trim();
         const changed = [];
-        const actualizada = await (0, fs_js_1.updateJSON)(this.brain.paths.neuron(neuron.id), current => {
-            const n = current || neuron;
+        const actualizada = await this.updateNeuron(neuron.id, current => {
+            if (!current)
+                return null; // deleted meanwhile: never resurrect it (2.11)
+            const n = current;
             if (summary !== undefined && summary !== n.summary) {
                 n.summary = summary;
                 changed.push('summary');
@@ -1413,7 +1719,7 @@ class Cortex {
         // The other way round, an exact neuron id could land on a near-miss whose
         // prefix-stripped id matches first, and the map would be written to one
         // neuron while every reader resolves the other.
-        let neuron = (await this.peek(neuronRef)) || (await this.findByName(neuronRef));
+        let neuron = await this.resolveForWrite(neuronRef);
         let action = 'updated';
         if (!neuron) {
             const nType = options?.neuronType || (0, ids_js_1.inferNeuronType)(neuronRef);
@@ -1422,8 +1728,10 @@ class Cortex {
         }
         const cuando = (0, fs_js_1.now)();
         const vaciar = content.trim() === '';
-        const actualizada = await (0, fs_js_1.updateJSON)(this.brain.paths.neuron(neuron.id), current => {
-            const n = current || neuron;
+        const actualizada = await this.updateNeuron(neuron.id, current => {
+            if (!current)
+                return null; // deleted meanwhile: never resurrect it (2.11)
+            const n = current;
             // An empty map is not a map: writing '' clears it outright, so the
             // reader never meets a document that exists but says nothing.
             if (vaciar)
@@ -1434,7 +1742,9 @@ class Cortex {
             n.access_count = (n.access_count || 0) + 1;
             return n;
         });
-        const final = (actualizada || neuron);
+        if (!actualizada)
+            throw this.deletedMeanwhile(neuron.id);
+        const final = actualizada;
         await this.reindex(final);
         // Clearing emits too: an empty map op is the tombstone that wins the LWW
         // on every machine, so a stale copy cannot resurrect the cleared map.
@@ -1450,36 +1760,48 @@ class Cortex {
      * slice, which is the only number a pager can trust.
      */
     async listWithTotal(options) {
-        const all = await this.list({ ...options, limit: Number.MAX_SAFE_INTEGER, offset: 0 });
+        const unreadable = [];
+        const all = await this.list({ ...options, limit: Number.MAX_SAFE_INTEGER, offset: 0 }, unreadable);
         const limit = options?.limit || 50;
         const offset = Math.max(0, options?.offset || 0);
-        return { total: all.length, rows: all.slice(offset, offset + limit) };
+        return { total: all.length, rows: all.slice(offset, offset + limit), unreadable };
     }
     /**
      * List all neurons with optional filters.
      */
-    async list(options) {
+    async list(options, unreadable) {
         const ids = await (0, fs_js_1.listJSONFiles)(this.brain.paths.cortex);
         const neurons = [];
+        const calor = await this.heatMap();
         for (const id of ids) {
-            const neuron = await (0, fs_js_1.readJSON)(this.brain.paths.neuron(id));
+            let neuron;
+            try {
+                neuron = await (0, fs_js_1.readJSON)(this.brain.paths.neuron(id));
+            }
+            catch (err) {
+                // One unreadable file is listed apart, never the end of the listing.
+                const info = await this.noteUnreadable(id, err);
+                unreadable?.push(info);
+                continue;
+            }
             if (!neuron)
                 continue;
+            const heat = calor.get(neuron.id) ?? neuron.heat;
             // Apply filters
             if (options?.domain && neuron.domain !== options.domain)
                 continue;
             if (options?.type && neuron.type !== options.type)
                 continue;
-            if (options?.min_heat && neuron.heat < options.min_heat)
+            if (options?.min_heat && heat < options.min_heat)
                 continue;
             neurons.push({
                 id: neuron.id,
                 name: neuron.name,
                 domain: neuron.domain,
                 type: neuron.type,
-                heat: neuron.heat,
+                heat,
                 last_accessed: neuron.last_accessed,
-                facts_count: neuron.facts.length,
+                facts_count: (neuron.facts || []).length,
             });
         }
         // Sort by heat (descending)
@@ -1493,7 +1815,7 @@ class Cortex {
      * Update a neuron's summary.
      */
     async updateSummary(id, summary) {
-        const neuron = await (0, fs_js_1.updateJSON)(this.brain.paths.neuron(id), current => {
+        const neuron = await this.updateNeuron(id, current => {
             if (!current)
                 return null;
             current.summary = summary;
@@ -1509,7 +1831,7 @@ class Cortex {
      * Add tags to a neuron.
      */
     async addTags(id, tags) {
-        const neuron = await (0, fs_js_1.updateJSON)(this.brain.paths.neuron(id), current => {
+        const neuron = await this.updateNeuron(id, current => {
             if (!current)
                 return null;
             for (const tag of tags) {
@@ -1532,10 +1854,10 @@ class Cortex {
      * not exist at all — a credential, someone's personal data.
      */
     async forget(neuronRef, targets) {
-        const found = (await this.peek(neuronRef)) || (await this.findByName(neuronRef));
+        const found = await this.resolveForWrite(neuronRef);
         if (!found)
             return { neuron_id: null, removed: 0, backup: null };
-        const backup = await this.quarantine(found);
+        let backup = null;
         let removed = 0;
         const wanted = targets.map(t => t.trim().toLowerCase());
         // An entry goes when a target names its text or its id: the entryId the
@@ -1549,42 +1871,83 @@ class Cortex {
             return wanted.includes(t) || wanted.includes((0, ops_js_1.entryId)(text).toLowerCase())
                 || (!!ownId && wanted.includes(ownId.toLowerCase()));
         };
-        const after = await (0, fs_js_1.updateJSON)(this.brain.paths.neuron(found.id), current => {
+        const factMatches = (f) => {
+            const fid = (f.id || (0, hash_js_1.factId)(f.text)).toLowerCase();
+            return wanted.includes(fid) || wanted.includes(f.text.trim().toLowerCase());
+        };
+        // What left, read inside the lock: the quarantine copy and the emitted
+        // removals describe exactly what this call took out, not a snapshot read
+        // before somebody else wrote.
+        let quitado = null;
+        const after = await this.updateNeuron(found.id, async (current) => {
             if (!current)
                 return null;
-            const antes = current.facts.length + current.decisions.length +
-                current.patterns.length + current.preferences.length;
+            const q = {
+                quarantine_format: 2, kind: 'entries',
+                neuron_id: current.id, name: current.name, type: current.type, domain: current.domain, taken_at: (0, fs_js_1.now)(),
+                facts: (current.facts || []).filter(factMatches).map(copyFact),
+                decisions: (current.decisions || []).filter(d => matches(d.text, d.id)).map(d => ({ ...d })),
+                patterns: (current.patterns || []).filter(p => matches(p)),
+                preferences: (current.preferences || []).filter(p => matches(p)),
+                errors: (current.errors || []).filter(e => matches(e)),
+                debts: (current.debts || []).filter(d => matches(d)),
+                ...(current.map && wanted.includes(current.map.text.trim().toLowerCase()) ? { map: { ...current.map } } : {}),
+            };
+            removed = q.facts.length + q.decisions.length + q.patterns.length + q.preferences.length
+                + q.errors.length + q.debts.length + (q.map ? 1 : 0);
+            // Nothing matched: nothing is written, and no copy is kept either.
+            if (removed === 0)
+                return null;
+            // The sidecars of what leaves travel with it, so restore puts each entry
+            // back with its date, retirement, provenance and check.
+            const llaves = new Set([...q.decisions.map(d => d.text), ...q.patterns, ...q.preferences, ...q.errors, ...q.debts].map(ops_js_1.entryId));
+            const parte = (rec) => {
+                if (!rec)
+                    return undefined;
+                const out = {};
+                for (const k of Object.keys(rec))
+                    if (llaves.has(k))
+                        out[k] = rec[k];
+                return Object.keys(out).length ? out : undefined;
+            };
+            const fechas = parte(current.entry_dates);
+            if (fechas)
+                q.entry_dates = fechas;
+            const estados = parte(current.entry_status);
+            if (estados)
+                q.entry_status = estados;
+            const origenes = parte(current.entry_source);
+            if (origenes)
+                q.entry_source = origenes;
+            const verificadas = parte(current.entry_verified);
+            if (verificadas)
+                q.entry_verified = verificadas;
+            const evidencias = parte(current.entry_verification);
+            if (evidencias)
+                q.entry_verification = evidencias;
+            // The copy first, inside the lock: if it cannot be written (a full disk,
+            // encryption on without its key) nothing is removed.
+            backup = await (0, quarantine_js_1.writeQuarantine)(this.brain.paths.quarantine, current.id, q, 'entries');
+            quitado = q;
             // Dated entries before the removal, so their dates can go with them.
             const fechadasAntes = [
                 ...current.patterns, ...current.preferences,
                 ...(current.errors || []), ...(current.debts || []),
             ];
-            current.facts = current.facts.filter(f => {
-                const fid = (f.id || (0, hash_js_1.factId)(f.text)).toLowerCase();
-                return !(wanted.includes(fid) || wanted.includes(f.text.trim().toLowerCase()));
-            });
+            current.facts = current.facts.filter(f => !factMatches(f));
             // Decisions, patterns and preferences too. A credential is no less
             // exposed for sitting in one of those, and nothing else could remove it.
             current.decisions = current.decisions.filter(d => !matches(d.text, d.id));
             current.patterns = current.patterns.filter(p => !matches(p));
             current.preferences = current.preferences.filter(p => !matches(p));
-            const erroresAntes = (current.errors || []).length;
             if (current.errors) {
                 current.errors = current.errors.filter(e => !matches(e));
             }
-            const deudasAntes = (current.debts || []).length;
             if (current.debts) {
                 current.debts = current.debts.filter(d => !matches(d));
             }
-            let mapaBorrado = 0;
-            if (current.map && wanted.includes(current.map.text.trim().toLowerCase())) {
+            if (q.map)
                 delete current.map;
-                mapaBorrado = 1;
-            }
-            removed = antes - (current.facts.length + current.decisions.length +
-                current.patterns.length + current.preferences.length) + (erroresAntes - (current.errors || []).length) + (deudasAntes - (current.debts || []).length) + mapaBorrado;
-            if (removed === 0)
-                return null;
             // Drop the dates of what left, so the sidecar never outlives its entry.
             if (current.entry_dates) {
                 const quedan = new Set([
@@ -1641,7 +2004,8 @@ class Cortex {
             current.last_accessed = (0, fs_js_1.now)();
             return current;
         });
-        if (removed > 0 && after) {
+        const q = quitado;
+        if (removed > 0 && after && q) {
             await this.reindex(after);
             // The removal must travel, or the next sync resurrects from the team
             // log exactly what the user asked to destroy. Facts retract (status
@@ -1649,33 +2013,22 @@ class Cortex {
             // a purge op keyed by content hash; a cleared map emits the empty-map
             // tombstone that wins the LWW. The emitter no-ops on unshared neurons.
             const cuando = (0, fs_js_1.now)();
-            for (const f of found.facts || []) {
-                const fid = (f.id || (0, hash_js_1.factId)(f.text)).toLowerCase();
-                if (wanted.includes(fid) || wanted.includes(f.text.trim().toLowerCase())) {
-                    await this.emit(found.id, { kind: 'status', fid: f.id || (0, hash_js_1.factId)(f.text), to: 'retracted', at: cuando, why: 'forgotten' });
-                }
+            for (const f of q.facts) {
+                await this.emit(found.id, { kind: 'status', fid: f.id || (0, hash_js_1.factId)(f.text), to: 'retracted', at: cuando, why: 'forgotten' });
             }
-            for (const d of found.decisions || []) {
-                if (matches(d.text, d.id)) {
-                    await this.emit(found.id, { kind: 'decision_purge', key: (0, ops_js_1.entryId)(d.text), at: cuando });
-                }
+            for (const d of q.decisions) {
+                await this.emit(found.id, { kind: 'decision_purge', key: (0, ops_js_1.entryId)(d.text), at: cuando });
             }
-            for (const p of found.patterns || []) {
-                if (matches(p)) {
-                    await this.emit(found.id, { kind: 'pattern_purge', key: (0, ops_js_1.entryId)(p), at: cuando });
-                }
+            for (const p of q.patterns) {
+                await this.emit(found.id, { kind: 'pattern_purge', key: (0, ops_js_1.entryId)(p), at: cuando });
             }
-            for (const e of found.errors || []) {
-                if (matches(e)) {
-                    await this.emit(found.id, { kind: 'error_purge', key: (0, ops_js_1.entryId)(e), at: cuando });
-                }
+            for (const e of q.errors) {
+                await this.emit(found.id, { kind: 'error_purge', key: (0, ops_js_1.entryId)(e), at: cuando });
             }
-            for (const d of found.debts || []) {
-                if (matches(d)) {
-                    await this.emit(found.id, { kind: 'debt_purge', key: (0, ops_js_1.entryId)(d), at: cuando });
-                }
+            for (const d of q.debts) {
+                await this.emit(found.id, { kind: 'debt_purge', key: (0, ops_js_1.entryId)(d), at: cuando });
             }
-            if (found.map && wanted.includes(found.map.text.trim().toLowerCase())) {
+            if (q.map) {
                 await this.emit(found.id, { kind: 'map', text: '', at: cuando });
             }
         }
@@ -1692,37 +2045,60 @@ class Cortex {
      * emitted: there is no neuron-delete op.
      */
     async forgetNeuron(neuronRef) {
-        const found = (await this.peek(neuronRef)) || (await this.findByName(neuronRef));
-        if (!found) {
-            return {
-                neuron_id: null, backup: null,
-                counts: { facts: 0, decisions: 0, patterns: 0, preferences: 0, errors: 0, debts: 0, connections: 0 },
-            };
-        }
-        const backup = await this.quarantine(found);
-        await this.deleteNeuronFile(found.id);
+        const vacio = { facts: 0, decisions: 0, patterns: 0, preferences: 0, errors: 0, debts: 0, connections: 0 };
+        const found = await this.resolveForWrite(neuronRef);
+        if (!found)
+            return { neuron_id: null, backup: null, counts: vacio };
+        // Copy and delete under the neuron's lock (2.11): a learn landing between
+        // the copy and the unlink used to be deleted without being in the copy.
+        const r = await this.quarantineAndDelete(found.id);
+        if (!r)
+            return { neuron_id: null, backup: null, counts: vacio };
+        const n = r.neuron;
         return {
-            neuron_id: found.id,
-            backup,
+            neuron_id: n.id,
+            backup: r.backup,
             counts: {
-                facts: (found.facts || []).length,
-                decisions: (found.decisions || []).length,
-                patterns: (found.patterns || []).length,
-                preferences: (found.preferences || []).length,
-                errors: (found.errors || []).length,
-                debts: (found.debts || []).length,
-                connections: (found.connections || []).length,
+                facts: (n.facts || []).length,
+                decisions: (n.decisions || []).length,
+                patterns: (n.patterns || []).length,
+                preferences: (n.preferences || []).length,
+                errors: (n.errors || []).length,
+                debts: (n.debts || []).length,
+                connections: (n.connections || []).length,
             },
         };
     }
     /**
-     * Quarantine copies of one neuron, newest first. Stamps sort lexically, so
-     * the file name alone orders them.
+     * Under the neuron's lock: read it as it is now, copy it whole to
+     * quarantine, delete the file. Null when it is already gone. If the copy
+     * cannot be written (encryption on without its key, a full disk) nothing is
+     * deleted. Index and manifest follow outside the lock.
+     */
+    async quarantineAndDelete(id) {
+        const file = this.brain.paths.neuron(id);
+        const r = await (0, lock_js_1.withLock)(file, async () => {
+            const current = await this.readStrict(id);
+            if (!current)
+                return null;
+            const backup = await this.quarantine(current);
+            await (0, fs_js_1.deleteJSON)(file);
+            return { neuron: current, backup };
+        });
+        if (!r)
+            return null;
+        await this.unindex(id);
+        const manifest = await this.brain.getManifest();
+        await this.brain.updateManifest({ total_neurons: Math.max(0, manifest.total_neurons - 1) });
+        return r;
+    }
+    /**
+     * Quarantine copies of one neuron, newest first: whole copies and copies of
+     * forgotten entries, clear or sealed. Stamps sort lexically, so the file
+     * name alone orders them; `base` is what restore's `file` option takes.
      */
     async quarantineCopies(neuronId) {
-        const prefijo = `${neuronId}.`;
-        const files = await (0, fs_js_1.listJSONFiles)(this.brain.paths.quarantine);
-        return files.filter(f => f.startsWith(prefijo)).sort().reverse();
+        return (await (0, quarantine_js_1.listQuarantine)(this.brain.paths.quarantine, neuronId)).map(c => ({ base: c.base, file: c.file }));
     }
     /**
      * Bring a neuron back from quarantine.
@@ -1732,30 +2108,40 @@ class Cortex {
      * (a forget of facts, or the topic was re-created since) the copy is
      * unioned into it. The quarantine file stays where it is, so a restore is
      * repeatable. Nothing is emitted.
+     *
+     * A copy of forgotten entries (2.11) holds those entries and their
+     * sidecars, not the neuron: unioned into the neuron when it exists, or
+     * written as a neuron of its own name, type and domain when it does not.
+     * Sealed copies are opened with the at-rest key.
      */
     async restoreNeuron(neuronId, options) {
         const nada = { neuron: null, restored_from: null, merged_into_existing: false, moved: null };
-        let basename = null;
+        const copias = await this.quarantineCopies(neuronId);
+        let elegida;
         if (options?.file) {
-            const pedido = options.file.replace(/\.json$/i, '');
-            const copias = await this.quarantineCopies(neuronId);
-            basename = copias.includes(pedido) ? pedido : null;
+            const pedido = options.file.replace(/\.json(\.enc)?$/i, '');
+            elegida = copias.find(c => c.base === pedido);
         }
         else {
-            basename = (await this.quarantineCopies(neuronId))[0] || null;
+            elegida = copias[0];
         }
-        if (!basename)
+        if (!elegida)
             return nada;
-        const ruta = `${this.brain.paths.quarantine}/${basename}.json`;
-        const copia = await (0, fs_js_1.readJSON)(ruta);
-        if (!copia || !copia.id)
+        const ruta = node_path_1.default.join(this.brain.paths.quarantine, elegida.file);
+        const leida = await (0, quarantine_js_1.readQuarantine)(ruta);
+        let copia = null;
+        if ((0, quarantine_js_1.isEntriesCopy)(leida))
+            copia = (0, quarantine_js_1.entriesAsNeuron)(leida);
+        else if (leida && typeof leida === 'object' && leida.id)
+            copia = leida;
+        if (!copia)
             return nada;
         copia.id = neuronId;
         // Decide inside the lock, like create: whether the neuron exists again is
         // only known for sure while nobody else can write it.
         let escrita = false;
         let moved = null;
-        const saved = await (0, fs_js_1.updateJSON)(this.brain.paths.neuron(neuronId), current => {
+        const saved = await this.updateNeuron(neuronId, current => {
             if (!current) {
                 escrita = true;
                 return copia;
@@ -1784,25 +2170,48 @@ class Cortex {
      * re-creates it).
      */
     async mergeNeurons(fromRef, intoRef) {
-        const from = (await this.peek(fromRef)) || (await this.findByName(fromRef));
-        const into = (await this.peek(intoRef)) || (await this.findByName(intoRef));
+        const from = await this.resolveForWrite(fromRef);
+        const into = await this.resolveForWrite(intoRef);
         if (!from || !into || from.id === into.id) {
             return { from: from?.id ?? null, into: into?.id ?? null, backup: null, moved: null };
         }
-        const backup = await this.quarantine(from);
+        // Under the source's lock (2.11): what is copied, unioned and deleted is
+        // the source as it is at that moment, so a learn into it meanwhile is
+        // either in all three or waits and then finds it gone.
         let antes = into;
         let moved = null;
-        const saved = await (0, fs_js_1.updateJSON)(this.brain.paths.neuron(into.id), current => {
-            antes = current || into;
-            const r = unionNeuron(antes, from);
-            moved = r.moved;
-            return r.neuron;
+        let intoGone = false;
+        const hecho = await (0, lock_js_1.withLock)(this.brain.paths.neuron(from.id), async () => {
+            const fuente = await this.readStrict(from.id);
+            if (!fuente)
+                return null;
+            const backup = await this.quarantine(fuente);
+            const saved = await this.updateNeuron(into.id, current => {
+                if (!current) {
+                    intoGone = true;
+                    return null;
+                }
+                antes = current;
+                const r = unionNeuron(current, fuente);
+                moved = r.moved;
+                return r.neuron;
+            });
+            if (!saved || intoGone)
+                return { backup, final: null };
+            await (0, fs_js_1.deleteJSON)(this.brain.paths.neuron(from.id));
+            return { backup, final: saved };
         });
-        const final = (saved || into);
+        if (!hecho)
+            return { from: null, into: into.id, backup: null, moved: null };
+        if (!hecho.final)
+            throw this.deletedMeanwhile(into.id);
+        const final = hecho.final;
         await this.reindex(final);
         await this.emitAdded(antes, final);
-        await this.deleteNeuronFile(from.id);
-        return { from: from.id, into: into.id, backup, moved };
+        await this.unindex(from.id);
+        const manifest = await this.brain.getManifest();
+        await this.brain.updateManifest({ total_neurons: Math.max(0, manifest.total_neurons - 1) });
+        return { from: from.id, into: into.id, backup: hecho.backup, moved };
     }
     /**
      * Emit what a union added, by diffing the result against what the target
@@ -1877,7 +2286,7 @@ class Cortex {
      * moves: it describes the system, not an entry.
      */
     async moveEntries(fromRef, targets, intoRef, options) {
-        const from = (await this.peek(fromRef)) || (await this.findByName(fromRef));
+        const from = await this.resolveForWrite(fromRef);
         if (!from)
             return { from: null, into: null, created: false, moved: 0, unmatched: targets, backup: null };
         const wanted = new Set(targets.map(t => t.trim().toLowerCase()).filter(Boolean));
@@ -1917,7 +2326,7 @@ class Cortex {
         const unmatched = targets.filter(t => !usados.has(t.trim().toLowerCase()));
         if (textos.length === 0)
             return { from: from.id, into: null, created: false, moved: 0, unmatched, backup: null };
-        let into = (await this.peek(intoRef)) || (await this.findByName(intoRef));
+        let into = await this.resolveForWrite(intoRef);
         let created = false;
         if (!into) {
             into = await this.create(intoRef, from.type, options?.domain || from.domain);
@@ -1926,7 +2335,7 @@ class Cortex {
         if (into.id === from.id)
             return { from: from.id, into: into.id, created: false, moved: 0, unmatched, backup: null };
         let antes = into;
-        const saved = await (0, fs_js_1.updateJSON)(this.brain.paths.neuron(into.id), current => {
+        const saved = await this.updateNeuron(into.id, current => {
             antes = current || into;
             return unionNeuron(antes, parte).neuron;
         });
@@ -1970,8 +2379,10 @@ class Cortex {
         const targetId = target.id;
         for (const n of sources)
             await this.quarantine(n);
-        const saved = await (0, fs_js_1.updateJSON)(this.brain.paths.neuron(targetId), current => {
-            let acc = (current || target);
+        const saved = await this.updateNeuron(targetId, current => {
+            if (!current)
+                return null; // deleted meanwhile: never resurrect it (2.11)
+            let acc = current;
             for (const n of sources) {
                 if (n.id === targetId)
                     continue;
@@ -1985,13 +2396,36 @@ class Cortex {
             }
             return acc;
         });
-        const final = (saved || target);
+        if (!saved)
+            throw this.deletedMeanwhile(targetId);
+        const final = saved;
         await this.reindex(final);
         const folded = [];
         for (const n of sources) {
             if (n.id === targetId)
                 continue;
-            await this.deleteNeuronFile(n.id);
+            // Delete only the source as it was read: one written since keeps its
+            // file (its old line is in the digest too — a duplicate, never a loss).
+            const borrada = await (0, lock_js_1.withLock)(this.brain.paths.neuron(n.id), async () => {
+                let ahora = null;
+                try {
+                    ahora = await (0, fs_js_1.readJSON)(this.brain.paths.neuron(n.id));
+                }
+                catch {
+                    return false;
+                }
+                if (!ahora || JSON.stringify(ahora) !== JSON.stringify(n))
+                    return false;
+                await (0, fs_js_1.deleteJSON)(this.brain.paths.neuron(n.id));
+                return true;
+            });
+            if (!borrada) {
+                skipped.push(n.id);
+                continue;
+            }
+            await this.unindex(n.id);
+            const manifest = await this.brain.getManifest();
+            await this.brain.updateManifest({ total_neurons: Math.max(0, manifest.total_neurons - 1) });
             folded.push(n.id);
         }
         const entries = final.facts.length + final.decisions.length + final.patterns.length
@@ -2005,7 +2439,7 @@ class Cortex {
     async auditSecrets() {
         const out = [];
         for (const id of await (0, fs_js_1.listJSONFiles)(this.brain.paths.cortex)) {
-            const n = await (0, fs_js_1.readJSON)(this.brain.paths.neuron(id));
+            const n = await this.peek(id); // an unreadable file is skipped and listed in unreadable()
             if (!n)
                 continue;
             const kinds = new Set();
@@ -2023,8 +2457,9 @@ class Cortex {
             // Every field, not just facts. A credential is just as exposed sitting in
             // a decision or a preference, and those were invisible here — an audit
             // could report a neuron clean while a key sat in preferences[0].
-            const facts = contar((n.facts || []).map(f => f.text));
-            const decisions = contar((n.decisions || []).map(d => d.text));
+            // Rationales, aliases and revision notes count with their entry (G8).
+            const facts = contar((n.facts || []).map(f => [f.text, ...(f.keys || []), f.revision_note || ''].join('\n')));
+            const decisions = contar((n.decisions || []).map(d => `${d.text}\n${d.rationale || ''}`));
             const patterns = contar(n.patterns || []);
             const preferences = contar(n.preferences || []);
             const errors = contar(n.errors || []);