crbro-memory 2.9.1 → 2.11.0

package/dist/search/index.js

@@ -20,15 +20,19 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SearchEngine = exports.RECALL_KINDS = exports.INDEX_VERSION = void 0;
 exports.recencyOf = recencyOf;
+exports.splitParts = splitParts;
+exports.flushOnExit = flushOnExit;
 exports.projectSlugOf = projectSlugOf;
 const orama_1 = require("@orama/orama");
 const node_path_1 = __importDefault(require("node:path"));
+const node_fs_1 = require("node:fs");
 const fs_js_1 = require("../utils/fs.js");
 const hash_js_1 = require("../utils/hash.js");
 const tokenize_js_1 = require("./tokenize.js");
 const semantic_js_1 = require("./semantic.js");
 const ops_js_1 = require("../sync/ops.js");
 const shelf_js_1 = require("../engine/shelf.js");
+const heat_js_1 = require("../engine/heat.js");
 /**
  * Bump when the schema changes so old on-disk indexes are rebuilt, not loaded.
  * v3: chunk removal used to rely on an Orama `where` filter that silently
@@ -39,15 +43,77 @@ const shelf_js_1 = require("../engine/shelf.js");
  * 2.0) are no longer chunked, so an index built before it must be rebuilt or
  * it would keep serving entries that were retired.
  */
-exports.INDEX_VERSION = 7; // 4: keys field (1.15) · 5: entry_status (2.0) · 6: eid per chunk (2.1) · 7: session logs indexed (2.2)
-/** Weight given to a neuron for each *additional* chunk that matches. */
+exports.INDEX_VERSION = 8; // 4: keys field (1.15) · 5: entry_status (2.0) · 6: eid per chunk (2.1) · 7: session logs indexed (2.2) · 8: own tokenizer, 4 indexed fields, long entries in parts (2.11)
+/**
+ * Lift for each *additional* entry of a neuron that matched by keyword, in
+ * units of one fully matched term (the keyword engine), or of FUSED_UNIT
+ * with the semantic layer on (2.11): the same 0.05 the keyword engine always
+ * had, but no longer added raw to a fused score where it was worth fifteen
+ * ranks.
+ */
 const BREADTH_BONUS = 0.05;
-/** Cap on the breadth bonus — breadth is a tiebreaker, never the main signal. */
+/** Cap on the breadth lift — breadth is a tiebreaker, never the main signal. */
 const BREADTH_CAP = 0.25;
+/** One breadth unit on the fused (reciprocal-rank) scale: the cap is then 0.025, about a rank and a half at the top. */
+const FUSED_UNIT = 0.1;
+/**
+ * The bound project's neurons are lifted by this factor (2.11) — a boost
+ * inside the ranking, not a separate tier above it.
+ */
+const PROJECT_BOOST = 1.25;
+/** Fallback strong line for a vector-only match while a brain has no calibration (the 2.10 constant). */
+const SEMANTIC_STRONG_DEFAULT = 0.86;
+/** Strong needs the calibrated noise top (p95) plus this. */
+const CALIBRATION_MARGIN = 0.01;
+const CALIBRATION_SAMPLES = 40;
+/** Below this many vectors a noise floor is not worth measuring. */
+const CALIBRATION_MIN_VECTORS = 50;
+/** Queries with no word of any brain: their best cosine is pure noise too. */
+const NONSENSE = ['xqzv wkrp jjhg', 'zzkq vrrt plmx', 'qwoijd fhhq', 'bnxl ttqz wpw'];
+/** Vector candidates looked at, of which at most SEMANTIC_CANDIDATES are used. */
+const SEMANTIC_POOL = 160;
+/** At most this many vector candidates from one neuron (2.11: diversity). */
+const SEMANTIC_PER_NEURON = 4;
+/** How long a query waits for the semantic model before answering keyword-only (2.11). CRBRO_SEMANTIC_WAIT_MS overrides. */
+const SEMANTIC_WAIT_DEFAULT_MS = 1500;
+/** The no-answer level is on unless CRBRO_NO_ANSWER=0 (2.11). */
+function noAnswerEnabled() {
+    const v = (process.env.CRBRO_NO_ANSWER || '').toLowerCase();
+    return !(v === '0' || v === 'off' || v === 'false');
+}
+/**
+ * Rows kept when nothing clears the evidence bar. Three, not one: a real
+ * question that shares a single word with its fact looks like a distractor
+ * to a keyword engine, and with one row recall@3 fell from 90 % to 85 % on
+ * the 48-query set. The flag still says "not clearly stored".
+ */
+const NO_ANSWER_ROWS = 3;
+function semanticWaitMs() {
+    const v = Number(process.env.CRBRO_SEMANTIC_WAIT_MS);
+    return Number.isFinite(v) && v >= 0 && v <= 120_000 ? v : SEMANTIC_WAIT_DEFAULT_MS;
+}
+/**
+ * Long entries (2.11) are indexed as overlapping parts: an entry longer than
+ * PART_MAX characters becomes parts of about PART_TARGET with PART_OVERLAP of
+ * overlap, cut at a sentence or a space. BM25 no longer drowns the one line
+ * that matched in the length of the rest, the vector model (which sees about
+ * 512 tokens) sees every part, and recall returns the part that matched
+ * instead of the opening of a 5,000-character entry. PART_MAX equals the
+ * recall handler's content cap, so a part is never cut again on the way
+ * out. Measured on the synthetic brain: parts of 800 made the index file
+ * 38.5 MB, parts of about 1,000 35.2 MB, for the same benchmark results.
+ */
+const PART_MAX = 1200;
+const PART_TARGET = 1000;
+const PART_OVERLAP = 120;
 /** Exponent on term coverage. >1 punishes chunks that only match one term. */
 const COVERAGE_EXPONENT = 1.5;
 /** Debounce before writing the index to disk after a learn. */
 const PERSIST_DEBOUNCE_MS = 5000;
+/** How often a long-lived process compares every file even when the folders did not move (2.11). */
+const FULL_CHECK_MS = 60_000;
+/** How long an exiting process may spend writing its index before it leaves anyway (2.11). */
+const EXIT_FLUSH_MS = 2000;
 /** How many of the top results also carry their neuron's next best chunks. */
 const ALSO_MATCHED_RESULTS = 3;
 /** Semantic fusion (opt-in): candidates asked of the vector index per query. */
@@ -124,13 +190,14 @@ exports.RECALL_KINDS = ['fact', 'decision', 'pattern', 'preference', 'error', 'd
  * line matters, and entry_id reads it whole through crbro_inspect.
  */
 const ALSO_PREVIEW = 300;
-function alsoLine(text, kind, added, eid, from = {}) {
+function alsoLine(text, kind, added, eid, from = {}, entryChars) {
     return {
         ...(eid ? { entry_id: eid } : {}),
         kind,
         added,
         preview: text.length > ALSO_PREVIEW ? `${text.slice(0, ALSO_PREVIEW).trimEnd()}…` : text,
-        chars: text.length,
+        // The whole entry's length, also when the line is one part of a long entry.
+        chars: entryChars || text.length,
         // Same rule as the winning entry: said only when the line is not the user's own.
         ...(from.origin ? { origin: from.origin } : {}),
         ...(from.by ? { by: from.by } : {}),
@@ -151,19 +218,29 @@ function staleView(s) {
         ...(s.age_from ? { age_from: s.age_from } : {}),
     };
 }
+/**
+ * What Orama INDEXES: only the four fields a search reads. Every document
+ * also carries, stored but not indexed (2.11), its `id` ("<neuron_id>#<hash>",
+ * Orama's own key), `neuron`, `kind` (header | fact | decision | pattern |
+ * preference | error | debt | map | session), `eid` (the entry's own id:
+ * factId for facts, entryId otherwise, 'map', '' for the header), `domain`,
+ * `added`, `heat` and, for a part of a long entry, `part`/`parts`/`offset`/
+ * `entry_chars`. Until 2.10 all of them were searchable and sortable
+ * strings: on a 7,386-entry brain the index file was 77.7 MB for 9.25 MB of
+ * neurons, most of it term frequencies, radix trees and sort structures for
+ * ids and dates nobody searched. They are filtered in JS (see searchTerm),
+ * never with an Orama `where`.
+ */
 const SCHEMA = {
-    id: 'string', // "<neuron_id>#<hash>"  — must be `id` for Orama
-    neuron: 'string',
     name: 'string',
     text: 'string',
     keys: 'string', // aliases a future question may use — facts only (1.15)
-    kind: 'string', // header | fact | decision | pattern | preference
-    eid: 'string', // the entry's own id: factId for facts, entryId otherwise, 'map', '' for the header (2.1)
-    domain: 'string',
     tags: 'string',
-    added: 'string',
-    heat: 'number',
 };
+/** A fresh Orama database with CRBRO's tokenizer and no sort structures (nothing sorts by a field). */
+function newDb() {
+    return (0, orama_1.create)({ schema: SCHEMA, components: { tokenizer: (0, tokenize_js_1.createIndexTokenizer)() }, sort: { enabled: false } });
+}
 const SESSION_MATCHES = 3;
 const SESSION_CHUNK = 700;
 /** Best chunk per session, top sessions by coverage-weighted score; total is how many days had a hit. */
@@ -220,6 +297,109 @@ function sessionChunks(summary) {
     }
     return out;
 }
+/** The fields of a stored document a hit carries, without score. */
+function chunkFields(doc) {
+    return {
+        neuron: doc.neuron, name: doc.name, domain: doc.domain, text: doc.text,
+        kind: doc.kind, eid: doc.eid || '', added: doc.added, heat: doc.heat || 0,
+        ...(typeof doc.parts === 'number' ? { part: doc.part, parts: doc.parts, offset: doc.offset, entry_chars: doc.entry_chars } : {}),
+    };
+}
+/**
+ * Ranks for reciprocal-rank fusion counted per neuron (2.11): the first
+ * chunk of each neuron takes the next free rank, every later chunk of the
+ * same neuron sits one place behind its neuron's last one. Input in score order.
+ */
+function rankPerNeuron(list) {
+    const out = new Map();
+    const ultimo = new Map();
+    let siguiente = 1;
+    for (const { id, neuron } of list) {
+        const prev = ultimo.get(neuron);
+        const r = prev === undefined ? siguiente++ : prev + 1;
+        ultimo.set(neuron, r);
+        out.set(id, r);
+    }
+    return out;
+}
+/** File dates for many paths, a bounded number at a time; 0 for a file that is gone. */
+async function mtimesOf(files, width = 64) {
+    const out = new Array(files.length).fill(0);
+    let next = 0;
+    const worker = async () => {
+        while (next < files.length) {
+            const i = next++;
+            out[i] = await (0, fs_js_1.fileMtime)(files[i]);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(width, files.length) }, worker));
+    return out;
+}
+/** One chunk per entry, the best-scoring part of a long one; order kept. Header chunks pass through. */
+function unaPorEntrada(chunks) {
+    const vistas = new Set();
+    const out = [];
+    for (const c of chunks) {
+        if (c.parts && c.eid) {
+            const k = `${c.kind}:${c.eid}`;
+            if (vistas.has(k))
+                continue;
+            vistas.add(k);
+        }
+        out.push(c);
+    }
+    return out;
+}
+/** Cut a long entry into overlapping parts at sentence or word boundaries. Each part is an exact slice. */
+function splitParts(text) {
+    if (text.length <= PART_MAX)
+        return [{ offset: 0, text }];
+    const out = [];
+    let start = 0;
+    while (start < text.length) {
+        let end = Math.min(text.length, start + PART_TARGET);
+        if (text.length - end < PART_TARGET / 5)
+            end = text.length; // no tiny last part (and none over PART_MAX)
+        if (end < text.length) {
+            const ventana = text.slice(start + Math.floor(PART_TARGET * 0.6), end);
+            const frase = Math.max(ventana.lastIndexOf('. '), ventana.lastIndexOf('\n'), ventana.lastIndexOf('; '));
+            const espacio = ventana.lastIndexOf(' ');
+            const corte = frase >= 0 ? frase + 1 : espacio;
+            if (corte > 0)
+                end = start + Math.floor(PART_TARGET * 0.6) + corte;
+        }
+        out.push({ offset: start, text: text.slice(start, end) });
+        if (end >= text.length)
+            break;
+        // Next part starts PART_OVERLAP back, at a word boundary.
+        let next = Math.max(start + 1, end - PART_OVERLAP);
+        const sp = text.indexOf(' ', next);
+        if (sp > 0 && sp < end)
+            next = sp + 1;
+        start = next;
+    }
+    return out;
+}
+/** The full text of an entry by its id, as it is indexed (a decision with its rationale). Null when gone or retired. */
+function entryTextById(neuron, kind, eid) {
+    switch (kind) {
+        case 'fact': {
+            const f = (neuron.facts || []).find(x => !!x && !isRetired(x) && (x.id || (0, hash_js_1.factId)(x.text)) === eid);
+            return f ? f.text : null;
+        }
+        case 'decision': {
+            const d = (neuron.decisions || []).find(x => !!x && (x.id || (0, ops_js_1.entryId)(x.text)) === eid);
+            return d ? (d.rationale ? `${d.text} — ${d.rationale}` : d.text) : null;
+        }
+        case 'map':
+            return neuron.map?.text || null;
+        case 'pattern': return (neuron.patterns || []).find(t => (0, ops_js_1.entryId)(t) === eid) ?? null;
+        case 'preference': return (neuron.preferences || []).find(t => (0, ops_js_1.entryId)(t) === eid) ?? null;
+        case 'error': return (neuron.errors || []).find(t => (0, ops_js_1.entryId)(t) === eid) ?? null;
+        case 'debt': return (neuron.debts || []).find(t => (0, ops_js_1.entryId)(t) === eid) ?? null;
+        default: return null;
+    }
+}
 class SearchEngine {
     brain;
     db = null;
@@ -256,6 +436,17 @@ class SearchEngine {
     rebuilding = null;
     /** When the cortex was last read into this index, in ms. Files newer than this are somebody else's writes. */
     syncedAt = 0;
+    /** File date of each neuron / "session:<id>" as indexed (see StoredIndex.mtimes). */
+    indexedMtime = new Map();
+    /** Folder dates of cortex and hippocampus at the last refresh: a write by anyone renames a file into them. */
+    dirsSeen = { cortex: -1, diary: -1 };
+    /** Last full file-by-file comparison, for writers that edit in place without touching the folder. */
+    lastFullCheck = 0;
+    /** One refresh at a time. */
+    refreshing = null;
+    /** The semantic calibration loaded with the index or measured since. */
+    calibration = null;
+    calibrating = null;
     constructor(brain) {
         this.brain = brain;
         if ((0, semantic_js_1.semanticEnabled)()) {
@@ -294,13 +485,50 @@ class SearchEngine {
         }
         const indexAt = await (0, fs_js_1.fileMtime)(this.brain.paths.chunksIndex());
         if ((await this.loadOrRebuild()) === 'loaded') {
-            // A loaded index is as old as its file. isStale() forgives one second, and
-            // a process killed inside the 5 s persist debounce leaves exactly that:
-            // a neuron on disk, newer than the index by less than the slack, that no
-            // rebuild will ever pick up. Catch up from the file's own timestamp.
+            // A loaded index is as old as its file. Entries without a recorded file
+            // date (an index from 2.10) are judged against it with a second of
+            // slack; the rest by their exact date.
             this.syncedAt = indexAt;
             await this.refresh();
         }
+        this.reconcileVectors();
+    }
+    /**
+     * Make the vectors match the index (2.11), in the background. Vectors were
+     * only ever computed for chunks inserted in this process, so a vectors file
+     * dropped at load (torn by a crash, another model) was never refilled and
+     * the layer stayed empty or partial until a full rebuild; and vectors of
+     * chunks that left the index were never pruned, taking candidate seats.
+     */
+    reconcileVectors() {
+        if (!this.semantic || !this.db)
+            return;
+        const docs = Object.values((this.db?.data?.docs?.docs) || {});
+        const quiero = new Map();
+        for (const d of docs)
+            if (d && d.id && d.kind !== 'header' && d.kind !== 'session')
+                quiero.set(String(d.id), String(d.text || ''));
+        const tengo = new Set(this.semantic.idList());
+        const huerfanos = [...tengo].filter(id => !quiero.has(id));
+        if (huerfanos.length > 0)
+            this.semantic.remove(huerfanos);
+        let faltan = 0;
+        for (const [id, text] of quiero)
+            if (!tengo.has(id)) {
+                this.pendingEmbed.set(id, text);
+                faltan++;
+            }
+        if (faltan === 0 && huerfanos.length === 0)
+            return;
+        const previa = this.embedding ?? Promise.resolve();
+        this.embedding = previa.then(() => this.flushEmbeddings()).then(() => this.markDirty()).catch(() => undefined);
+    }
+    /** Vectors held vs chunks that should have one (status, tests). */
+    semanticCoverage() {
+        if (!this.semantic || !this.db)
+            return null;
+        const docs = Object.values((this.db?.data?.docs?.docs) || {});
+        return { vectors: this.semantic.count(), chunks: docs.filter(d => d && d.kind !== 'header' && d.kind !== 'session').length };
     }
     async loadOrRebuild() {
         if (this.semantic) {
@@ -314,12 +542,22 @@ class SearchEngine {
         if (await (0, fs_js_1.fileExists)(indexPath)) {
             try {
                 const stored = await (0, fs_js_1.readJSON)(indexPath);
-                if (stored && stored.v === exports.INDEX_VERSION && stored.data && !(await this.isStale())) {
-                    this.db = (0, orama_1.create)({ schema: SCHEMA });
+                // An index that is merely BEHIND the files is loaded and caught up by
+                // refresh() (2.11). It used to be rebuilt from scratch whenever any
+                // neuron or day log was newer than it — and a plain read rewrites a
+                // neuron (access count) — so a boot after another process's work paid
+                // a full rebuild: crbro_boot 5.9 s instead of 1.57 s on a 561-neuron
+                // brain. Only a different version, a corrupt file or an unknown shape
+                // rebuild now.
+                if (stored && stored.v === exports.INDEX_VERSION && stored.data) {
+                    this.db = newDb();
                     (0, orama_1.load)(this.db, stored.data);
                     this.docCount = this.countDocs(stored.data);
-                    if (this.recoverChunkMap(stored.data))
+                    if (this.recoverChunkMap(stored.data)) {
+                        this.indexedMtime = new Map(Object.entries(stored.mtimes || {}).filter(([, v]) => typeof v === 'number'));
+                        this.calibration = stored.calibration && stored.calibration.model ? stored.calibration : null;
                         return 'loaded';
+                    }
                     // Could not tell which chunk belongs to which neuron — without
                     // that, removal is blind, so a rebuild is the only safe answer.
                 }
@@ -331,6 +569,25 @@ class SearchEngine {
         await this.rebuild();
         return 'rebuilt';
     }
+    /**
+     * Catch up with writes made by anyone else before answering (2.11). A
+     * process that stays up — a classic stdio server for a whole conversation,
+     * the daemon — only refreshed at boot, so what another session learned was
+     * invisible to it until it restarted. Every writer renames a file into the
+     * cortex or the diary folder, which moves the folder's own date: two stats
+     * per search say whether anything changed, and only then do we compare the
+     * files one by one. Once a minute we compare anyway, for a writer that
+     * edits a file in place.
+     */
+    async catchUp() {
+        if (!this.db || this.rebuilding)
+            return;
+        const [cortex, diary] = await Promise.all([(0, fs_js_1.fileMtime)(this.brain.paths.cortex), (0, fs_js_1.fileMtime)(this.brain.paths.hippocampus)]);
+        const moved = cortex !== this.dirsSeen.cortex || diary !== this.dirsSeen.diary;
+        if (!moved && Date.now() - this.lastFullCheck < FULL_CHECK_MS)
+            return;
+        await this.refresh();
+    }
     /**
      * Bring the in-memory index up to date with the disk: re-index the neurons
      * and day logs whose files changed since the last sync, drop the chunks of
@@ -344,33 +601,62 @@ class SearchEngine {
             await this.init();
             return { reindexed: 0, removed: 0 };
         }
+        if (this.refreshing)
+            return this.refreshing;
+        this.refreshing = this.doRefresh().finally(() => { this.refreshing = null; });
+        return this.refreshing;
+    }
+    /**
+     * Has this file changed since it was indexed? Exact file dates when we
+     * recorded one (2.11); for an entry without a record (an index written by
+     * 2.10), the old rule: newer than the last sync, with a second of slack.
+     */
+    changed(key, mtime, desde) {
+        const known = this.indexedMtime.get(key);
+        return known !== undefined ? known !== mtime : mtime > desde;
+    }
+    async doRefresh() {
         await this.settled();
-        const desde = this.syncedAt - 1000; // the same second of slack isStale() allows
+        const desde = this.syncedAt - 1000; // one second of slack for entries without a recorded date
         const empezado = Date.now();
+        // Taken BEFORE listing: a write landing during this pass moves the folder
+        // again and the next search looks again.
+        const [dirCortex, dirDiary] = await Promise.all([(0, fs_js_1.fileMtime)(this.brain.paths.cortex), (0, fs_js_1.fileMtime)(this.brain.paths.hippocampus)]);
         let reindexed = 0, removed = 0;
         const ids = await (0, fs_js_1.listJSONFiles)(this.brain.paths.cortex);
         const vivos = new Set(ids);
-        for (const id of ids) {
+        let conCalor = null;
+        // Every date first, many at a time (2.11): one stat after another was 563
+        // round trips through the I/O pool, ~20 s on a busy machine (measured while
+        // the semantic layer filled vectors), and every search waited for it.
+        const fechas = await mtimesOf(ids.map(id => this.brain.paths.neuron(id)));
+        for (const [n, id] of ids.entries()) {
             // Unchanged AND already in the index. A neuron with no chunks at all is
             // not indexed, whatever its date says: every neuron has at least its
             // header chunk. That is what an index file written by ANOTHER process
             // looks like from here — newer than the neuron, and without it — and the
             // file date alone would never bring it back.
-            if (this.chunksByNeuron.has(id) && (await (0, fs_js_1.fileMtime)(this.brain.paths.neuron(id))) <= desde)
+            const mtime = fechas[n];
+            if (this.chunksByNeuron.has(id) && !this.changed(id, mtime, desde))
                 continue;
             try {
                 const neuron = await (0, fs_js_1.readJSON)(this.brain.paths.neuron(id));
                 if (!neuron)
                     continue;
-                await this.reindexInPlace(neuron);
+                conCalor ??= await this.heatNow();
+                await this.reindexInPlace(conCalor(neuron));
+                this.indexedMtime.set(id, mtime);
                 reindexed++;
             }
             catch { /* unreadable: leave what we have */ }
         }
         const diarios = await (0, fs_js_1.listJSONFiles)(this.brain.paths.hippocampus);
         const diasVivos = new Set(diarios.map(d => `session:${d}`));
-        for (const id of diarios) {
-            if ((await (0, fs_js_1.fileMtime)(this.brain.paths.session(id))) <= desde)
+        const fechasDia = await mtimesOf(diarios.map(id => this.brain.paths.session(id)));
+        for (const [n, id] of diarios.entries()) {
+            const key = `session:${id}`;
+            const mtime = fechasDia[n];
+            if (!this.changed(key, mtime, desde))
                 continue;
             try {
                 const log = await (0, fs_js_1.readJSON)(this.brain.paths.session(id));
@@ -379,6 +665,7 @@ class SearchEngine {
                 await this.removeNeuronChunks(`session:${log.session_id}`);
                 if (log.summary)
                     await this.insertSessionChunks(log);
+                this.indexedMtime.set(key, mtime);
                 reindexed++;
             }
             catch { /* skip */ }
@@ -394,9 +681,12 @@ class SearchEngine {
             if (await (0, fs_js_1.fileExists)(file))
                 continue;
             await this.removeNeuronChunks(key);
+            this.indexedMtime.delete(key);
             removed++;
         }
         this.syncedAt = empezado;
+        this.dirsSeen = { cortex: dirCortex, diary: dirDiary };
+        this.lastFullCheck = empezado;
         if (reindexed > 0 || removed > 0) {
             this.markDirty();
             // Off the boot path, like rebuild(): every client waits on init(), and
@@ -407,27 +697,6 @@ class SearchEngine {
         }
         return { reindexed, removed };
     }
-    /**
-     * Has the cortex moved on without the index?
-     *
-     * This used to be impossible to notice: init() only rebuilt when the file
-     * was missing, the version had changed or the JSON was corrupt — never
-     * because it had simply fallen behind. So a lost flush, or a second client
-     * writing neurons while this one held a stale index in memory, left those
-     * facts invisible to recall indefinitely. On the reference brain the index
-     * was five and a half hours behind the newest neuron, and a term saved that
-     * afternoon returned nothing at all.
-     */
-    async isStale() {
-        const indexAt = await (0, fs_js_1.fileMtime)(this.brain.paths.chunksIndex());
-        if (indexAt === 0)
-            return true;
-        const cortexAt = await (0, fs_js_1.newestMtime)(this.brain.paths.cortex);
-        // The diary is indexed too (2.2): a log written by another process counts.
-        const diaryAt = await (0, fs_js_1.newestMtime)(this.brain.paths.hippocampus);
-        // One second of slack: a write landing during a rebuild is not staleness.
-        return Math.max(cortexAt, diaryAt) > indexAt + 1000;
-    }
     /**
      * Rebuild the whole index from the cortex.
      * One bad neuron must not take the server down with it, so every neuron
@@ -445,18 +714,38 @@ class SearchEngine {
         if (this.rebuilding)
             await this.rebuilding.catch(() => undefined);
     }
+    /**
+     * Heat as the derived heat state has it (2.11): neuron files are no longer
+     * rewritten when their heat moves, so the value stored in a file is only a
+     * fallback for a neuron the state does not know yet.
+     */
+    async heatNow() {
+        const estado = await (0, heat_js_1.readHeatState)(this.brain);
+        const calor = estado?.neurons || {};
+        return (n) => {
+            const h = calor[n.id]?.heat;
+            return typeof h === 'number' && h !== n.heat ? { ...n, heat: h } : n;
+        };
+    }
     async doRebuild() {
         this.syncedAt = Date.now();
-        this.db = (0, orama_1.create)({ schema: SCHEMA });
+        this.lastFullCheck = this.syncedAt;
+        this.dirsSeen = { cortex: await (0, fs_js_1.fileMtime)(this.brain.paths.cortex), diary: await (0, fs_js_1.fileMtime)(this.brain.paths.hippocampus) };
+        this.db = newDb();
         this.docCount = 0;
         this.chunksByNeuron.clear();
+        this.indexedMtime.clear();
         const ids = await (0, fs_js_1.listJSONFiles)(this.brain.paths.cortex);
+        const conCalor = await this.heatNow();
         for (const id of ids) {
             try {
+                // Dated before reading: a write in between is simply indexed again later.
+                const mtime = await (0, fs_js_1.fileMtime)(this.brain.paths.neuron(id));
                 const neuron = await (0, fs_js_1.readJSON)(this.brain.paths.neuron(id));
                 if (!neuron)
                     continue;
-                await this.insertNeuronChunks(neuron);
+                await this.insertNeuronChunks(conCalor(neuron));
+                this.indexedMtime.set(id, mtime);
             }
             catch {
                 // Skip unreadable neuron, keep going.
@@ -465,9 +754,11 @@ class SearchEngine {
         // The diary too (2.2): every session log, as paragraphs.
         for (const id of await (0, fs_js_1.listJSONFiles)(this.brain.paths.hippocampus)) {
             try {
+                const mtime = await (0, fs_js_1.fileMtime)(this.brain.paths.session(id));
                 const log = await (0, fs_js_1.readJSON)(this.brain.paths.session(id));
                 if (log?.summary)
                     await this.insertSessionChunks(log);
+                this.indexedMtime.set(`session:${id}`, mtime);
             }
             catch {
                 // Skip unreadable log, keep going.
@@ -477,7 +768,7 @@ class SearchEngine {
         // hold boot for minutes on a big brain. Recall serves what is embedded so
         // far; the vectors go to disk with the next index write.
         this.embedding = this.flushEmbeddings().then(() => this.markDirty()).catch(() => undefined);
-        await this.persist();
+        await this.writeIndex();
         await this.dropLegacyIndex();
         return this.docCount;
     }
@@ -491,6 +782,9 @@ class SearchEngine {
             return;
         await this.settled();
         await this.reindexInPlace(neuron);
+        // The file as it is now is what was just indexed (the cortex calls this
+        // right after writing it): recorded, so the next refresh skips it.
+        this.indexedMtime.set(neuron.id, await (0, fs_js_1.fileMtime)(this.brain.paths.neuron(neuron.id)));
         // Ids are content hashes: only the neuron's NEW lines get embedded.
         await this.flushEmbeddings();
         this.markDirty();
@@ -523,6 +817,7 @@ class SearchEngine {
         if (!this.chunksByNeuron.has(neuronId))
             return;
         await this.removeNeuronChunks(neuronId);
+        this.indexedMtime.delete(neuronId);
         this.markDirty();
     }
     /** Wait for the background embedding job of a rebuild, if one is running. */
@@ -530,18 +825,37 @@ class SearchEngine {
         if (this.embedding)
             await this.embedding;
     }
-    /** Write the index to disk now. */
+    /**
+     * Write the index to disk now. First catch up with whatever another
+     * process wrote (2.11): the file is shared, and a long-lived process that
+     * had not seen a later write used to overwrite the other's newer index
+     * with its older view — after which that write looked indexed to every
+     * loader. Catching up first makes what we write a superset of the disk;
+     * the per-file dates written with it (StoredIndex.mtimes) make any
+     * remaining race visible to the next loader instead of permanent.
+     */
     async persist() {
+        if (!this.db)
+            return;
+        await this.catchUp().catch(() => undefined);
+        await this.writeIndex();
+    }
+    storedPayload() {
+        return {
+            v: exports.INDEX_VERSION, data: (0, orama_1.save)(this.db), mtimes: Object.fromEntries(this.indexedMtime),
+            ...(this.calibration ? { calibration: this.calibration } : {}),
+        };
+    }
+    async writeIndex() {
         if (!this.db)
             return;
         if (this.persistTimer) {
             clearTimeout(this.persistTimer);
             this.persistTimer = null;
         }
-        const payload = { v: exports.INDEX_VERSION, data: (0, orama_1.save)(this.db) };
         // Not pretty-printed: this file reaches tens of MB and indentation costs
         // ~25% of both size and write time for something no human reads.
-        await (0, fs_js_1.writeJSON)(this.brain.paths.chunksIndex(), payload, { pretty: false });
+        await (0, fs_js_1.writeJSON)(this.brain.paths.chunksIndex(), this.storedPayload(), { pretty: false });
         this.dirty = false;
         if (this.semantic) {
             try {
@@ -550,6 +864,24 @@ class SearchEngine {
             catch { /* vectors are derived data; recall survives */ }
         }
     }
+    /**
+     * Write synchronously, for the 'exit' event, where nothing async runs any
+     * more. Only when there is something unsaved; never throws.
+     */
+    flushSync() {
+        if (!this.db || !this.dirty)
+            return;
+        try {
+            const file = this.brain.paths.chunksIndex();
+            const tmp = `${file}.${process.pid}.exit.tmp`;
+            (0, node_fs_1.writeFileSync)(tmp, JSON.stringify(this.storedPayload()), 'utf-8');
+            (0, node_fs_1.renameSync)(tmp, file);
+            this.dirty = false;
+        }
+        catch { /* best effort: the next boot refreshes from the files */ }
+    }
+    /** Is there anything in memory the file does not have yet? */
+    isDirty() { return this.dirty; }
     /** Flush if there are unsaved changes. Called on consolidate/shutdown. */
     async flush() {
         if (this.dirty)
@@ -564,13 +896,35 @@ class SearchEngine {
      * the sum of its normalised hits weighted by how much of the query it
      * covers. This is what stops one very common term from deciding the ranking
      * and what makes a chunk matching five of six terms beat a scrap matching one.
+     *
+     * relevance_score (2.11) means one thing in every mode: the ranking score on
+     * a 0–1 scale where 1 is the best this query can score — keyword engine:
+     * every term matched at its best hit (rarity-weighted share of the query);
+     * with the semantic layer: first in both the keyword and the vector
+     * ranking; with several phrasings: 1 when every phrasing scores 1. Recency
+     * and breadth can lift it a few percent above 1. It orders the list; it is
+     * not a truth value, and `confidence` is the label to read.
      */
     async search(query, options) {
+        // A background pass of the semantic layer waits while a search runs
+        // (2.11): its passages are tokenised on this thread, and every await of
+        // a search used to queue behind one — ~2 s a recall, measured, for the
+        // minutes a pass lasted after an upgrade.
+        const release = typeof this.semantic?.hold === 'function' ? this.semantic.hold() : undefined;
+        try {
+            return await this.searchNow(query, options);
+        }
+        finally {
+            release?.();
+        }
+    }
+    async searchNow(query, options) {
         if (!this.db)
             await this.init();
         if (!this.db)
             return [];
         await this.settled();
+        await this.catchUp().catch(() => undefined);
         const limit = options?.limit || 10;
         const terms = (0, tokenize_js_1.queryTerms)(query);
         if (terms.length === 0)
@@ -581,16 +935,26 @@ class SearchEngine {
         const desde = (options?.since || '').slice(0, 10);
         const clases = options?.kinds && options.kinds.length > 0 ? new Set(options.kinds) : null;
         const sinFecha = new Set();
+        const allowed = options?.neuronIds ? new Set(options.neuronIds) : null;
+        const owned = new Set(options?.globalExcludedNeurons || []);
         const admite = (doc) => {
+            if (allowed && !allowed.has(doc.neuron || '')) {
+                const global = options?.includeGlobal && (doc.kind === 'preference' ||
+                    (!!doc.neuron && /^(tech_|process_)/.test(doc.neuron) && !owned.has(doc.neuron) &&
+                        ['pattern', 'error', 'debt'].includes(doc.kind || '')));
+                if (!global)
+                    return false;
+            }
             if (clases && !clases.has(String(doc.kind || '')))
                 return false;
             if (desde) {
                 if (doc.kind === 'header')
                     return false; // dated by the neuron's birth, which says nothing about its content
                 const dia = String(doc.added || '').slice(0, 10);
+                // Counted per entry, not per part of a long one.
                 if (!dia) {
                     if (doc.id)
-                        sinFecha.add(String(doc.id));
+                        sinFecha.add(String(doc.eid ? `${doc.neuron}#${doc.eid}` : doc.id));
                     return false;
                 }
                 if (dia < desde)
@@ -621,58 +985,61 @@ class SearchEngine {
             for (const [t, v] of pesoTermino)
                 pesoTermino.set(t, max > 0 ? v / max : 1);
         }
+        // The most a chunk can collect: every term at its best hit. A term found
+        // nowhere counts as the rarest (weight 1): a question whose words are
+        // mostly absent cannot score near 1 on the one word that is there.
+        const ideal = porTermino.reduce((s, { term }) => s + (pesoTermino.get(term) ?? 1), 0) + (terms.length - porTermino.length) || 1;
         for (const { term, hits } of porTermino) {
-            const best = hits[0].score || 1;
+            // The term's ceiling is its best CONTENT hit (2.11). It used to be the
+            // first hit of any kind: a neuron NAME carrying the word (boosted x2) or
+            // a 700-character day-log paragraph set the 1.0, and every entry that
+            // answers was worth half of that — so how much a term weighed depended
+            // on which header happened to contain it. Day logs have their own
+            // ceiling; a header can reach 1, never more.
+            const best = hits.find(h => !['header', 'session'].includes(h.document.kind))?.score || hits[0].score || 1;
+            const bestSession = hits.find(h => h.document.kind === 'session')?.score || 1;
             const w = pesoTermino.get(term) ?? 1;
             for (const hit of hits) {
                 const doc = hit.document;
                 const key = doc.id;
-                const normalised = best > 0 ? (hit.score / best) * w : 0;
                 // Session logs are searched, but never as neurons: they keep a list
                 // of their own, so a long narrative cannot outrank the fact that
                 // answers, and the neuron path below never sees them.
                 if (doc.kind === 'session') {
+                    if (allowed)
+                        continue; // A daily narrative has no reliable project boundary.
                     if (clases)
                         continue; // a day log is not an entry kind
                     if (desde && String(doc.added || '').slice(0, 10) < desde)
                         continue;
+                    const normalisedSession = (hit.score / bestSession) * w;
                     const prev = perSession.get(key);
                     if (prev) {
-                        prev.score += normalised;
+                        prev.score += normalisedSession;
                         prev.matched += 1;
                     }
                     else
-                        perSession.set(key, { session: String(doc.name || ''), date: String(doc.added || ''), text: String(doc.text || ''), eid: String(doc.eid || ''), score: normalised, matched: 1 });
+                        perSession.set(key, { session: String(doc.name || ''), date: String(doc.added || ''), text: String(doc.text || ''), eid: String(doc.eid || ''), score: normalisedSession, matched: 1 });
                     continue;
                 }
                 if (!admite(doc))
                     continue;
+                const normalised = best > 0 ? Math.min(1, hit.score / best) * w : 0;
                 const existing = perChunk.get(key);
                 if (existing) {
                     existing.score += normalised;
                     existing.matched += 1;
                 }
                 else {
-                    perChunk.set(key, {
-                        neuron: doc.neuron,
-                        name: doc.name,
-                        domain: doc.domain,
-                        text: doc.text,
-                        kind: doc.kind,
-                        eid: doc.eid || '',
-                        added: doc.added,
-                        heat: doc.heat || 0,
-                        score: normalised,
-                        matched: 1,
-                    });
+                    perChunk.set(key, { ...chunkFields(doc), score: normalised, matched: 1 });
                 }
             }
         }
         // Coverage weighting: a chunk matching five of six terms beats a scrap
-        // matching one.
+        // matching one. Then onto the 0–1 scale.
         for (const chunk of perChunk.values()) {
             const coverage = chunk.matched / terms.length;
-            chunk.score = chunk.score * Math.pow(coverage, COVERAGE_EXPONENT);
+            chunk.score = chunk.score * Math.pow(coverage, COVERAGE_EXPONENT) / ideal;
         }
         // Recency: a few percent on the lexical score, so near-ties fall to the
         // newer telling. Before fusion on purpose — see RECENCY_WEIGHT_DEFAULT.
@@ -686,9 +1053,18 @@ class SearchEngine {
         }
         // Semantic fusion — only when the opt-in layer is installed, enabled and
         // holds vectors. Off, this is a no-op and the scores above stand.
+        let semantic;
         if (this.semantic && this.semantic.ready() && this.semantic.count() > 0) {
-            await this.fuseSemantic(query, perChunk, options?.domain, admite);
-        }
+            // While a large pass fills vectors in the background (after an upgrade
+            // split long entries into parts, thousands of them), the keyword engine
+            // answers alone and says so: measured on a 563-neuron brain, a recall
+            // that waited for the model during the pass took 1.5–3 s instead of
+            // 60 ms, for the minutes the pass lasted (2.11).
+            semantic = this.semantic.backfilling?.() ? 'warming' : await this.fuseSemantic(query, perChunk, options?.domain, admite);
+        }
+        const unidad = semantic === 'used' ? FUSED_UNIT : 1 / ideal;
+        if (options?.stats && semantic)
+            options.stats.semantic = semantic;
         if (options?.stats && desde)
             options.stats.undated_skipped = sinFecha.size;
         if (options?.stats) {
@@ -713,14 +1089,23 @@ class SearchEngine {
         // shown five results cannot tell "five matched" from "five of forty".
         if (options?.stats)
             options.stats.matched_neurons = byNeuron.size;
-        return this.materializeResults([...byNeuron.values()], limit, terms.length);
+        return this.materializeResults([...byNeuron.values()], limit, terms.length, options?.preferNeurons, options?.stats, unidad);
     }
     /**
-     * Several phrasings of one question, searched together and fused by
-     * reciprocal rank. The caller is a language model: it knows the synonyms a
-     * keyword index does not, and asking three ways costs it nothing. Rank 1
-     * in every list scores 1.0; a neuron seen by one list out of three scores
-     * about a third. One phrasing behaves exactly like search().
+     * Several phrasings of one question, searched together and fused (2.11).
+     * The caller is a language model: it knows the synonyms a keyword index
+     * does not, and asking three ways costs it nothing.
+     *
+     * Fusion is by score, not by rank: 0.7 x the neuron's best score in any
+     * phrasing + 0.3 x its mean over all phrasings. Reciprocal rank (until
+     * 2.10) gave a neuron sitting second to sixth in every list 0.9+ whatever
+     * its lines covered, because every list is filled to twenty rows. The row
+     * shown is ONE phrasing's row — a strong one if any phrasing found the
+     * neuron strongly, else the best-scoring — and its confidence,
+     * matched_terms, query_terms and semantic_score are all that row's own:
+     * the label never contradicts the numbers beside it (until 2.10 "strong"
+     * was an OR over phrasings next to another row's 2-of-7). One phrasing
+     * behaves exactly like search().
      */
     async searchMany(queries, options = {}) {
         const distintas = [...new Set(queries.map(q => (q || '').trim()).filter(Boolean))];
@@ -734,80 +1119,98 @@ class SearchEngine {
         if (options.stats) {
             // Session hits: a day that several phrasings point at ranks first, then
             // by accumulated coverage (matched over query terms, so 2/2 beats 3/8).
-            // The row kept is the best-covered one, strong if any phrasing found it
-            // so — and the same phrasings in any order give the same list.
+            // The row kept is a strong one when any phrasing found the day strongly,
+            // else the best-covered — and its label is its own.
             const cobertura = (m) => (m.query_terms > 0 ? m.matched_terms / m.query_terms : 0);
+            const mejorFila = (a, b) => (a.confidence === 'strong') !== (b.confidence === 'strong') ? (a.confidence === 'strong' ? a : b)
+                : (cobertura(b) > cobertura(a) || (cobertura(b) === cobertura(a) && b.matched_terms > a.matched_terms)) ? b : a;
             const fusion = new Map();
             for (const s of porConsulta) {
                 for (const m of s.sessions || []) {
                     const f = fusion.get(m.session_id);
                     if (!f) {
-                        fusion.set(m.session_id, { row: m, cobertura: cobertura(m), frases: 1, strong: m.confidence === 'strong' });
+                        fusion.set(m.session_id, { row: m, cobertura: cobertura(m), frases: 1 });
                         continue;
                     }
                     f.cobertura += cobertura(m);
                     f.frases += 1;
-                    f.strong = f.strong || m.confidence === 'strong';
-                    if (cobertura(m) > cobertura(f.row) || (cobertura(m) === cobertura(f.row) && m.matched_terms > f.row.matched_terms))
-                        f.row = m;
+                    f.row = mejorFila(f.row, m);
                 }
             }
             options.stats.sessions = [...fusion.values()]
                 .sort((a, b) => b.frases - a.frases || b.cobertura - a.cobertura || (a.row.session_id < b.row.session_id ? 1 : -1))
                 .slice(0, SESSION_MATCHES)
-                .map(f => ({ ...f.row, confidence: f.strong ? 'strong' : f.row.confidence }));
+                .map(f => f.row);
             // Each phrasing counted its own days: the union is at least the largest count.
             options.stats.sessions_total = Math.max(fusion.size, ...porConsulta.map(s => s.sessions_total || 0));
             if (options.since)
                 options.stats.undated_skipped = Math.max(0, ...porConsulta.map(s => s.undated_skipped || 0));
-        }
+            const sem = porConsulta.map(s => s.semantic).find(Boolean);
+            if (sem)
+                options.stats.semantic = sem;
+        }
+        // One key per entry everywhere (2.11): the entry id, or the text when
+        // there is none. The old map keyed the same line by its full text in one
+        // place and by its id in another, so one entry could fill two of the
+        // three also_matched slots.
+        const claveFila = (r) => r.entry_id || `text:${r.matching_content}`;
+        const claveAlso = (a) => a.entry_id || `text:${a.preview}`;
         const fused = new Map();
-        const alsoOf = (r) => alsoLine(r.matching_content, r.matched_kind || '', r.matched_added || '', r.entry_id, r);
         for (const lista of listas) {
-            lista.forEach((r, i) => {
-                const gain = 1 / (RRF_K + i + 1);
-                let f = fused.get(r.neuron_id);
-                if (!f) {
-                    f = { score: gain, best: r, bestRank: i, strong: r.confidence === 'strong', also: new Map() };
-                    fused.set(r.neuron_id, f);
-                }
+            for (const r of lista) {
+                const f = fused.get(r.neuron_id);
+                if (!f)
+                    fused.set(r.neuron_id, { rows: [r], max: r.relevance_score, sum: r.relevance_score });
                 else {
-                    f.score += gain;
-                    f.strong = f.strong || r.confidence === 'strong';
-                    if (i < f.bestRank) {
-                        // The other list's answer becomes an also_matched line of the winner.
-                        if (f.best.matching_content !== r.matching_content)
-                            f.also.set(f.best.matching_content, alsoOf(f.best));
-                        f.best = r;
-                        f.bestRank = i;
-                    }
-                    else if (r.matching_content !== f.best.matching_content) {
-                        f.also.set(r.matching_content, alsoOf(r));
-                    }
+                    f.rows.push(r);
+                    f.max = Math.max(f.max, r.relevance_score);
+                    f.sum += r.relevance_score;
                 }
-                for (const a of r.also_matched || [])
-                    f.also.set(a.entry_id || a.preview, a);
-            });
+            }
         }
-        const escala = (RRF_K + 1) / listas.length;
-        if (options.stats)
+        const n = listas.length;
+        const preferred = new Set(options.preferNeurons || []);
+        const fusedScore = (f) => 0.7 * f.max + 0.3 * (f.sum / n);
+        const orden = (id, f) => fusedScore(f) * (preferred.has(id) ? PROJECT_BOOST : 1);
+        if (options.stats) {
             options.stats.matched_neurons = fused.size;
-        return [...fused.values()]
-            .sort((a, b) => b.score - a.score)
-            .slice(0, limit)
-            .map(f => {
-            const r = { ...f.best, relevance_score: Math.round(f.score * escala * 1000) / 1000 };
-            r.confidence = f.strong ? 'strong' : 'weak';
-            const propio = alsoLine(r.matching_content, r.matched_kind || '', r.matched_added || '', r.entry_id);
-            const also = [...f.also.values()]
-                .filter(a => (a.entry_id && propio.entry_id) ? a.entry_id !== propio.entry_id : a.preview !== propio.preview)
-                .slice(0, 3);
-            if (also.length)
-                r.also_matched = also;
+            options.stats.no_answer = porConsulta.every(s => s.no_answer === true);
+        }
+        const rows = [...fused.entries()]
+            .sort((a, b) => orden(b[0], b[1]) - orden(a[0], a[1]) || (a[0] < b[0] ? -1 : 1))
+            .slice(0, options.stats?.no_answer ? Math.min(limit, NO_ANSWER_ROWS) : limit)
+            .map(([, f]) => {
+            const shown = f.rows.reduce((a, b) => (a.confidence === 'strong') !== (b.confidence === 'strong') ? (a.confidence === 'strong' ? a : b)
+                : b.relevance_score > a.relevance_score ? b : a);
+            const r = { ...shown, relevance_score: Math.round(fusedScore(f) * 1000) / 1000 };
+            // The other phrasings' lines, then the also lines, one per entry,
+            // never the shown entry itself.
+            const vistas = new Set([claveFila(r)]);
+            const also = [];
+            const otras = f.rows.filter(x => x !== shown).sort((a, b) => b.relevance_score - a.relevance_score);
+            for (const x of otras) {
+                const k = claveFila(x);
+                if (vistas.has(k))
+                    continue;
+                vistas.add(k);
+                also.push(alsoLine(x.matching_content, x.matched_kind || '', x.matched_added || '', x.entry_id, x));
+            }
+            for (const x of [shown, ...otras]) {
+                for (const a of x.also_matched || []) {
+                    const k = claveAlso(a);
+                    if (vistas.has(k))
+                        continue;
+                    vistas.add(k);
+                    also.push(a);
+                }
+            }
+            if (also.length && !options.stats?.no_answer)
+                r.also_matched = also.slice(0, 3);
             else
                 delete r.also_matched;
             return r;
         });
+        return rows;
     }
     /**
      * searchMany plus the one number the list alone cannot carry: how many
@@ -822,6 +1225,8 @@ class SearchEngine {
             results, matched_neurons: stats.matched_neurons ?? results.length, sessions,
             sessions_total: stats.sessions_total ?? sessions.length,
             ...(stats.undated_skipped !== undefined ? { undated_skipped: stats.undated_skipped } : {}),
+            ...(stats.no_answer ? { no_answer: true } : {}),
+            ...(stats.semantic ? { semantic: stats.semantic } : {}),
         };
     }
     /**
@@ -830,46 +1235,80 @@ class SearchEngine {
      * ranked first by both scores 1.0; one seen by a single list scores about
      * half. Vector-only candidates below the cosine floor are dropped, and the
      * header chunks (name + tags) are never surfaced by vector alone.
+     *
+     * Diversity (2.11): ranks are counted per NEURON. A neuron's best chunk
+     * takes the next free rank and its other chunks queue behind it, so a
+     * neuron with hundreds of lines on the topic cannot push every other
+     * neuron down the list by its size; and at most SEMANTIC_PER_NEURON vector
+     * candidates come from one neuron, so it cannot take all the seats either.
+     *
+     * Returns how the layer took part: 'used', or 'warming' when the model was
+     * not loaded within the bounded wait and this answer is keyword-only.
      */
     async fuseSemantic(query, perChunk, domain, admite = () => true) {
         let sem;
         try {
-            sem = await this.semantic.query(query, SEMANTIC_CANDIDATES);
+            const pedido = this.semantic.query(query, SEMANTIC_POOL);
+            // Bounded wait (2.11): the first recall after a cold start used to wait
+            // for the whole model load (~13 s), or a download, with no limit. Past
+            // the wait this answer is keyword-only and says so; the load goes on.
+            const espera = semanticWaitMs();
+            let reloj = null;
+            const tarde = new Promise(resolve => { reloj = setTimeout(() => resolve(null), espera); });
+            const r = await Promise.race([pedido, tarde]);
+            if (reloj)
+                clearTimeout(reloj);
+            if (r === null) {
+                pedido.catch(() => undefined);
+                return 'warming';
+            }
+            sem = r;
         }
         catch {
-            return; // the semantic layer never breaks recall
+            return undefined; // the semantic layer never breaks recall
         }
         const floor = semanticFloor();
+        // A vector whose chunk left the index (an orphan) never takes a seat.
         sem = sem.filter(h => h.score >= floor);
         if (sem.length === 0)
-            return;
+            return 'used';
+        this.maybeCalibrate();
+        const elegidos = [];
+        const porNeurona = new Map();
         for (const h of sem) {
-            if (perChunk.has(h.id))
-                continue;
-            let doc;
-            try {
-                doc = await (0, orama_1.getByID)(this.db, h.id);
-            }
-            catch {
-                doc = undefined;
+            if (elegidos.length >= SEMANTIC_CANDIDATES)
+                break;
+            let doc = perChunk.get(h.id);
+            if (!doc) {
+                try {
+                    doc = await (0, orama_1.getByID)(this.db, h.id);
+                }
+                catch {
+                    doc = undefined;
+                }
+                if (!doc)
+                    continue;
+                if (doc.kind === 'header' || doc.kind === 'session')
+                    continue;
+                if (domain && doc.domain !== domain)
+                    continue;
+                if (!admite(doc))
+                    continue;
             }
-            if (!doc || doc.kind === 'header' || doc.kind === 'session')
-                continue;
-            if (domain && doc.domain !== domain)
+            const k = porNeurona.get(doc.neuron) || 0;
+            if (k >= SEMANTIC_PER_NEURON)
                 continue;
-            if (!admite(doc))
-                continue;
-            perChunk.set(h.id, {
-                neuron: doc.neuron, name: doc.name, domain: doc.domain, text: doc.text,
-                kind: doc.kind, eid: doc.eid || '', added: doc.added, heat: doc.heat || 0, score: 0, matched: 0,
-            });
+            porNeurona.set(doc.neuron, k + 1);
+            elegidos.push(h);
+            if (!perChunk.has(h.id))
+                perChunk.set(h.id, { ...chunkFields(doc), score: 0, matched: 0 });
         }
         const lex = [...perChunk.entries()]
             .filter(([, c]) => c.matched > 0)
             .sort((a, b) => b[1].score - a[1].score);
-        const lexRank = new Map(lex.map(([id], i) => [id, i + 1]));
-        const semRank = new Map(sem.map((h, i) => [h.id, i + 1]));
-        const semScore = new Map(sem.map(h => [h.id, h.score]));
+        const lexRank = rankPerNeuron(lex.map(([id, c]) => ({ id, neuron: c.neuron })));
+        const semRank = rankPerNeuron(elegidos.map(h => ({ id: h.id, neuron: perChunk.get(h.id).neuron })));
+        const semScore = new Map(elegidos.map(h => [h.id, h.score]));
         const top = 2 / (RRF_K + 1);
         for (const [id, chunk] of perChunk) {
             const l = lexRank.get(id);
@@ -878,6 +1317,7 @@ class SearchEngine {
             if (s !== undefined)
                 chunk.semantic = semScore.get(id);
         }
+        return 'used';
     }
     /** Embed the chunks inserted since the last pass. Never throws. */
     async flushEmbeddings() {
@@ -894,6 +1334,80 @@ class SearchEngine {
             // Model missing or failing: recall stays lexical, indexing is unharmed.
         }
     }
+    /**
+     * The cosine at or above which a vector-only match is strong on this
+     * brain: the calibrated one when measured, else the old fixed line.
+     */
+    semanticStrong() {
+        const c = this.calibration;
+        return c && c.model === (0, semantic_js_1.semanticModel)() ? c.strong : SEMANTIC_STRONG_DEFAULT;
+    }
+    /**
+     * Measure this brain's semantic noise floor, in the background, when there
+     * is none or the vector count moved by more than a quarter since (2.11).
+     * Random questions are built from words of random chunks that do not go
+     * together; the best cosine each reaches is what "nothing here" scores on
+     * this brain. Strong then needs noise_p95 + CALIBRATION_MARGIN.
+     */
+    maybeCalibrate() {
+        if (!this.semantic || this.calibrating || !this.db)
+            return;
+        const n = this.semantic.count();
+        const c = this.calibration;
+        if (n < CALIBRATION_MIN_VECTORS)
+            return;
+        if (c && c.model === (0, semantic_js_1.semanticModel)() && Math.abs(n - c.vectors) <= c.vectors * 0.25)
+            return;
+        this.calibrating = this.calibrate().then(() => undefined, () => undefined).finally(() => { this.calibrating = null; });
+    }
+    /** Exposed for tests and the benchmark: measure now and keep the result. */
+    async calibrate(samples = CALIBRATION_SAMPLES) {
+        if (!this.semantic || !this.db)
+            return null;
+        const docs = Object.values((this.db?.data?.docs?.docs) || {});
+        const palabras = [];
+        for (const d of docs) {
+            if (!d || d.kind === 'header' || d.kind === 'session')
+                continue;
+            for (const w of String(d.text || '').split(/\s+/))
+                if (w.length >= 5 && /^[\p{L}]+$/u.test(w))
+                    palabras.push(w);
+            if (palabras.length > 20000)
+                break;
+        }
+        if (palabras.length < 50)
+            return null;
+        // Deterministic per brain size: the same brain calibrates the same way.
+        let s = (docs.length * 2654435761) >>> 0 || 1;
+        const rnd = () => { s = (Math.imul(s ^ (s >>> 15), 1 | s) + 0x6D2B79F5) >>> 0; return s / 4294967296; };
+        const tops = [];
+        for (let i = 0; i < samples; i++) {
+            const q = Array.from({ length: 3 }, () => palabras[Math.floor(rnd() * palabras.length)]).join(' ');
+            const hits = await this.semantic.query(q, 1);
+            if (hits[0])
+                tops.push(hits[0].score);
+        }
+        // Nonsense with no word of the brain at all, too: what "xqzv wkrp" reaches.
+        for (const q of NONSENSE) {
+            const hits = await this.semantic.query(q, 1);
+            if (hits[0])
+                tops.push(hits[0].score);
+        }
+        if (tops.length < 5)
+            return null;
+        tops.sort((a, b) => a - b);
+        const q = (p) => tops[Math.min(tops.length - 1, Math.floor(p * tops.length))];
+        const cal = {
+            model: (0, semantic_js_1.semanticModel)(), vectors: this.semantic.count(), samples: tops.length,
+            noise_p50: Math.round(q(0.5) * 1000) / 1000, noise_p95: Math.round(q(0.95) * 1000) / 1000,
+            strong: Math.round((q(0.95) + CALIBRATION_MARGIN) * 1000) / 1000, at: new Date().toISOString(),
+        };
+        this.calibration = cal;
+        this.markDirty();
+        return cal;
+    }
+    /** The calibration in use, if any (status and tests). */
+    semanticCalibration() { return this.calibration; }
     /**
      * Turn per-neuron chunk lists into results, validating each chunk against
      * the neuron on disk before serving it.
@@ -907,10 +1421,15 @@ class SearchEngine {
      * fall back to its next valid chunk instead. Stale neurons are quietly
      * re-indexed; chunks of deleted neurons are removed on the spot.
      */
-    async materializeResults(porNeurona, limit, queryTermCount) {
+    async materializeResults(porNeurona, limit, queryTermCount, preferNeurons, stats, breadthUnit = 1) {
         // Only the plausible head pays the neuron reads: nothing below it could
-        // reach the answer even if everything above dropped out.
-        porNeurona.sort((a, b) => b[0].score - a[0].score);
+        // reach the answer even if everything above dropped out. The project's
+        // neurons get a bounded lift (2.11), not the head of the line: until
+        // 2.10 any project neuron, matching one word, ranked above the best
+        // global match.
+        const preferred = new Set(preferNeurons || []);
+        const lift = (neuron) => (preferred.has(neuron) ? PROJECT_BOOST : 1);
+        porNeurona.sort((a, b) => b[0].score * lift(b[0].neuron) - a[0].score * lift(a[0].neuron));
         const candidatos = porNeurona.slice(0, Math.max(limit * 3, limit + 8));
         const resultados = [];
         // Shelf life (staleness): judged here, where the neuron file is already
@@ -938,6 +1457,9 @@ class SearchEngine {
             equipo = { espacios };
             return equipo;
         };
+        const strongCut = this.semanticStrong();
+        // A vector match is evidence only above this brain's noise: the strong line.
+        const evidenceCut = strongCut;
         for (const chunks of candidatos) {
             const neuronId = chunks[0].neuron;
             let neuron = null;
@@ -957,7 +1479,9 @@ class SearchEngine {
             const vivos = [];
             let huboRancio = false;
             for (const chunk of chunks) {
-                if (!legible || neuron === null || this.chunkVive(chunk, neuron))
+                // A part of a long entry is checked against the whole entry it came from.
+                const entero = neuron && chunk.parts ? this.wholeOf(chunk, neuron) : chunk;
+                if (!legible || neuron === null || (entero && this.chunkVive(entero, neuron)))
                     vivos.push(chunk);
                 else
                     huboRancio = true;
@@ -972,67 +1496,107 @@ class SearchEngine {
             // the neuron, but it never speaks for it while a live content chunk
             // matched too. Measured on the blind benchmark, letting it win cost 3 of
             // the 13 misses — this rule alone moves recall@1 from 56% to 60%.
-            const contenido = vivos.filter(c => c.kind !== 'header');
+            // One line per entry: the best part of a long entry speaks for it.
+            const contenido = unaPorEntrada(vivos.filter(c => c.kind !== 'header'));
             const elegido = contenido[0] || vivos[0];
-            // Breadth says "this neuron is about the question". A digest (2.5: the
-            // lines a bulk import left, folded together) is about nothing: twenty of
-            // its lines matching "verify" is a property of the pile, and on the
-            // reference brain it put the pile above the project that answered.
+            // Breadth says "this neuron is about the question" — counted from
+            // LEXICAL evidence only (2.11), one per entry, in the unit of the
+            // score's own scale. Until 2.10 it was +0.05 per chunk up to +0.25 on
+            // any scale and counted vector-only neighbours too: with the semantic
+            // layer on, where two ranks sit ~1.6 % apart, a neuron with hundreds of
+            // lines on the topic won by size. A digest (2.5: the lines a bulk
+            // import left, folded together) is about nothing.
             const esDigest = !!neuron && (neuron.tags || []).includes('digest');
-            const breadth = esDigest ? 0 : Math.min((chunks.length - 1) * BREADTH_BONUS, BREADTH_CAP);
+            const lexicas = contenido.filter(c => c.matched > 0).length;
+            const breadth = esDigest ? 0 : Math.min(Math.max(0, lexicas - 1) * BREADTH_BONUS, BREADTH_CAP) * breadthUnit;
             // A keyword engine answers almost any question with something. The
             // label says how much of the question the answer actually covers, so
             // the reader can tell a hit from a coincidence.
+            const coverage = queryTermCount > 0 ? elegido.matched / queryTermCount : 0;
             const lexicalStrong = queryTermCount <= 1
                 ? elegido.matched >= 1
-                : elegido.matched >= 2 && elegido.matched / queryTermCount >= 0.5;
-            const strong = lexicalStrong || (elegido.semantic ?? 0) >= SEMANTIC_STRONG;
+                : elegido.matched >= 2 && coverage >= 0.5;
+            const strong = lexicalStrong || (elegido.semantic ?? 0) >= strongCut;
+            // The minimum evidence bar (2.11): below it the row is a coincidence —
+            // one word of a long question, or a vector inside this brain's noise.
+            const evidence = lexicalStrong || coverage >= 0.5 || (elegido.matched >= 2 && coverage >= 1 / 3)
+                || (elegido.semantic ?? 0) >= evidenceCut;
+            const relevancia = vivos[0].score + breadth;
+            const conPadre = neuron && elegido.parts ? (this.wholeOf(elegido, neuron) || elegido) : elegido;
             resultados.push({
                 r: {
                     neuron_id: elegido.neuron,
                     name: elegido.name,
                     domain: elegido.domain,
-                    relevance_score: Math.round((vivos[0].score + breadth) * 1000) / 1000,
+                    relevance_score: Math.round(relevancia * 1000) / 1000,
                     matching_content: elegido.text,
                     matched_kind: elegido.kind,
                     matched_added: elegido.added || '',
                     ...(elegido.eid ? { entry_id: elegido.eid } : {}),
+                    ...(elegido.parts ? { matched_part: { part: (elegido.part ?? 0) + 1, parts: elegido.parts, offset: elegido.offset ?? 0, entry_chars: elegido.entry_chars ?? 0 } } : {}),
                     heat: elegido.heat,
                     matched_terms: elegido.matched,
                     query_terms: queryTermCount,
                     confidence: strong ? 'strong' : 'weak',
                     ...(elegido.semantic !== undefined ? { semantic_score: elegido.semantic } : {}),
                     ...(neuron?.map?.text ? { has_map: true } : {}),
-                    ...(neuron ? await this.originOf(elegido, neuron, contextoEquipo) : {}),
-                    ...(vida && neuron ? (() => { const s = staleView(this.stalenessOf(elegido, neuron, vida)); return s ? { staleness: s } : {}; })() : {}),
+                    ...(neuron ? await this.originOf(conPadre, neuron, contextoEquipo) : {}),
+                    ...(vida && neuron ? (() => { const s = staleView(this.stalenessOf(conPadre, neuron, vida)); return s ? { staleness: s } : {}; })() : {}),
                 },
                 extra: contenido.filter(c => c !== elegido).slice(0, 2),
                 neuron,
+                orden: relevancia * lift(elegido.neuron),
+                evidence,
             });
         }
         // Synapses do not move this ranking, on purpose: lifting a neuron whose
         // neighbour also scored was measured on 633 queries over the reference
         // brain and changed recall@3 by 0.15 points at most. Pre-registration and
         // numbers in benchmarks/synapse-activation/; mechanism in commit 69917ce.
-        resultados.sort((a, b) => b.r.relevance_score - a.r.relevance_score);
-        const top = resultados.slice(0, limit);
+        resultados.sort((a, b) => b.orden - a.orden);
+        // No answer (2.11): when no row clears the evidence bar, say so instead
+        // of filling the list with coincidences (an unanswerable question used to
+        // come back as five weak rows and ~12,000 characters). The closest rows
+        // stay, weak and without also_matched, so the caller can see what the
+        // nearest things were.
+        const sinRespuesta = noAnswerEnabled() && resultados.length > 0 && !resultados.some(x => x.evidence);
+        if (stats)
+            stats.no_answer = sinRespuesta;
+        const top = resultados.slice(0, sinRespuesta ? Math.min(limit, NO_ANSWER_ROWS) : limit);
         // The neuron's next best lines, for the head of the list only: the line
         // you need is not always the one that scored highest. Measured, it lifts
         // fact-level recall@3 from 73% to 79%, and it costs tokens only where
         // they can still change the answer.
-        for (const { r, extra, neuron } of top.slice(0, ALSO_MATCHED_RESULTS)) {
+        for (const { r, extra, neuron } of sinRespuesta ? [] : top.slice(0, ALSO_MATCHED_RESULTS)) {
             if (extra.length > 0) {
                 // Previews, not bodies: the also lines were 46% of a recall's cost as
                 // full text. The id reads any of them whole. Each line carries its own
                 // origin: a teammate's line next to an own winner is still a teammate's.
-                r.also_matched = await Promise.all(extra.map(async (c) => alsoLine(c.text, c.kind, c.added || '', c.eid, {
-                    ...(neuron ? await this.originOf(c, neuron, contextoEquipo) : {}),
-                    ...(vida && neuron ? { staleness: this.stalenessOf(c, neuron, vida) ?? undefined } : {}),
-                })));
+                r.also_matched = await Promise.all(extra.map(async (c) => {
+                    const padre = neuron && c.parts ? (this.wholeOf(c, neuron) || c) : c;
+                    return alsoLine(c.text, c.kind, c.added || '', c.eid, {
+                        ...(neuron ? await this.originOf(padre, neuron, contextoEquipo) : {}),
+                        ...(vida && neuron ? { staleness: this.stalenessOf(padre, neuron, vida) ?? undefined } : {}),
+                    }, c.entry_chars);
+                }));
             }
         }
         return top.map(x => x.r);
     }
+    /**
+     * The whole entry a part of a long one came from, as a chunk with the full
+     * text — what chunkVive, originOf and stalenessOf compare against. Null
+     * when the entry is gone or no longer contains the part where it was.
+     */
+    wholeOf(chunk, neuron) {
+        const texto = entryTextById(neuron, chunk.kind, chunk.eid);
+        if (texto === null)
+            return null;
+        const off = chunk.offset ?? 0;
+        if (texto.slice(off, off + chunk.text.length) !== chunk.text)
+            return null;
+        return { ...chunk, text: texto, parts: undefined };
+    }
     /**
      * Where the matching entry came from — but only when it is NOT the user's
      * own, so the common case costs nothing: no field, no token. Read from what
@@ -1208,7 +1772,7 @@ class SearchEngine {
                 continue;
             if (isRetired(fact))
                 continue;
-            await this.put({
+            await this.putEntry({
                 ...base,
                 id: (0, hash_js_1.chunkId)(neuron.id, fact.text),
                 text: fact.text,
@@ -1226,7 +1790,7 @@ class SearchEngine {
             const text = decision.rationale
                 ? `${decision.text} — ${decision.rationale}`
                 : decision.text;
-            await this.put({
+            await this.putEntry({
                 ...base,
                 id: (0, hash_js_1.chunkId)(neuron.id, text),
                 text,
@@ -1245,7 +1809,7 @@ class SearchEngine {
                 continue;
             if (entryRetired(neuron, pattern))
                 continue;
-            await this.put({
+            await this.putEntry({
                 ...base,
                 id: (0, hash_js_1.chunkId)(neuron.id, pattern),
                 text: pattern,
@@ -1257,7 +1821,7 @@ class SearchEngine {
         for (const pref of neuron.preferences || []) {
             if (!pref)
                 continue;
-            await this.put({
+            await this.putEntry({
                 ...base,
                 id: (0, hash_js_1.chunkId)(neuron.id, pref),
                 text: pref,
@@ -1271,7 +1835,7 @@ class SearchEngine {
                 continue;
             if (entryRetired(neuron, err))
                 continue;
-            await this.put({
+            await this.putEntry({
                 ...base,
                 id: (0, hash_js_1.chunkId)(neuron.id, `error:${err}`),
                 text: err,
@@ -1285,7 +1849,7 @@ class SearchEngine {
                 continue;
             if (entryRetired(neuron, debt))
                 continue;
-            await this.put({
+            await this.putEntry({
                 ...base,
                 id: (0, hash_js_1.chunkId)(neuron.id, `debt:${debt}`),
                 text: debt,
@@ -1295,7 +1859,7 @@ class SearchEngine {
             });
         }
         if (neuron.map && neuron.map.text) {
-            await this.put({
+            await this.putEntry({
                 ...base,
                 id: (0, hash_js_1.chunkId)(neuron.id, `map:${neuron.map.text}`),
                 text: neuron.map.text,
@@ -1327,6 +1891,7 @@ class SearchEngine {
         if (!this.db)
             return [];
         await this.settled();
+        await this.catchUp().catch(() => undefined);
         // Orama keeps "crbro-memory" and "crbro_memory" as single tokens and
         // matches by prefix, so the project's first word finds every spelling;
         // which field actually names the project is decided below, in our terms.
@@ -1399,6 +1964,7 @@ class SearchEngine {
         await this.removeNeuronChunks(`session:${log.session_id}`);
         if (log.summary)
             await this.insertSessionChunks(log);
+        this.indexedMtime.set(`session:${log.session_id}`, await (0, fs_js_1.fileMtime)(this.brain.paths.session(log.session_id)));
         this.markDirty();
     }
     async insertSessionChunks(log) {
@@ -1419,6 +1985,22 @@ class SearchEngine {
             });
         }
     }
+    /**
+     * Insert one entry: whole when short, as overlapping parts when longer than
+     * PART_MAX (2.11). Every part keeps the entry's kind, eid, date and keys;
+     * its id derives from the whole entry's id, so editing the entry replaces
+     * all of its parts.
+     */
+    async putEntry(doc) {
+        const partes = splitParts(doc.text);
+        if (partes.length === 1) {
+            await this.put(doc);
+            return;
+        }
+        for (const [i, p] of partes.entries()) {
+            await this.put({ ...doc, id: (0, hash_js_1.chunkId)(doc.neuron, `${doc.id}#part${i}`), text: p.text, part: i, parts: partes.length, offset: p.offset, entry_chars: doc.text.length });
+        }
+    }
     async put(doc) {
         try {
             await (0, orama_1.insert)(this.db, doc);
@@ -1544,6 +2126,58 @@ class SearchEngine {
     }
 }
 exports.SearchEngine = SearchEngine;
+/**
+ * Classic stdio mode (2.11): write a dirty index before the process leaves.
+ * The index is written five seconds after the last change on a timer that,
+ * on purpose, never keeps the process alive — so a client that closed the
+ * pipe within those five seconds left the next boot behind the files. Now:
+ * stdin ending or closing, SIGINT and SIGTERM flush (at most EXIT_FLUSH_MS,
+ * then leave anyway), and a plain 'exit' writes synchronously if anything is
+ * still unsaved. Not for the daemon, which has its own shutdown, nor for a
+ * proxy. Returns a function that removes the handlers (for tests).
+ */
+function flushOnExit(engine, opts = {}) {
+    const input = opts.input ?? process.stdin;
+    const exit = opts.exit ?? ((code) => process.exit(code));
+    let leaving = false;
+    const leave = (code) => {
+        if (leaving)
+            return;
+        leaving = true;
+        let done = false;
+        const go = () => { if (!done) {
+            done = true;
+            exit(code);
+        } };
+        const timer = setTimeout(go, EXIT_FLUSH_MS);
+        if (typeof timer.unref === 'function')
+            timer.unref();
+        engine.flush().catch(() => undefined).finally(() => { clearTimeout(timer); go(); });
+    };
+    const onEnd = () => leave(0);
+    const onInt = () => leave(130);
+    const onTerm = () => leave(143);
+    // A flush already under way (or abandoned at its deadline) is not repeated synchronously.
+    const onExit = () => { if (!leaving)
+        engine.flushSync(); };
+    input.once('end', onEnd);
+    input.once('close', onEnd);
+    const signals = opts.signals !== false;
+    if (signals) {
+        process.once('SIGINT', onInt);
+        process.once('SIGTERM', onTerm);
+    }
+    process.once('exit', onExit);
+    return () => {
+        input.off('end', onEnd);
+        input.off('close', onEnd);
+        if (signals) {
+            process.off('SIGINT', onInt);
+            process.off('SIGTERM', onTerm);
+        }
+        process.off('exit', onExit);
+    };
+}
 /** A fact that has been superseded or retracted must not surface in recall. */
 /**
  * The project a `crbro_boot project=` value names: the last segment of a