renor-engine 0.0.0-stage → 1.0.0

package/dist/memory/durableAppend.js

@@ -0,0 +1,57 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.syncDirectory = syncDirectory;
+exports.withAppendLock = withAppendLock;
+exports.markUnrecoverable = markUnrecoverable;
+exports.unrecoverableReason = unrecoverableReason;
+const promises_1 = __importDefault(require("fs/promises"));
+const path_1 = __importDefault(require("path"));
+/**
+ * What the canonical Markdown and ledger appends and the start-up replay share (adv-crashsafe-1012, F1-F3). The append
+ * itself is `appendConfined` (confinedWrite.ts): one function that keeps a write inside the vault AND makes it durable, so
+ * a failed write leaves no bytes behind and an acknowledged write survives a power cut.
+ *
+ * Appends to one file run one at a time (withAppendLock), so the length a failed write is cut back to is still the length
+ * its own bytes started at: no other append can land in between and be removed with it. A cut-back that itself fails
+ * leaves the file refused for the rest of this process (markUnrecoverable), so no later append can make the fragment look
+ * whole; a restart sets that tail aside (replay).
+ */
+/** Flush a directory so that a file created in it is still there after a power cut. */
+async function syncDirectory(dir) {
+    const handle = await promises_1.default.open(dir, 'r');
+    try {
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+}
+const queues = new Map();
+/**
+ * Runs `fn` after every earlier call for the same file has finished, and before any later one starts. In-process only:
+ * two engine processes on one workspace are not serialized by it (not covered by adv-crashsafe-1012 F6 either).
+ */
+function withAppendLock(file, fn) {
+    const key = path_1.default.resolve(file);
+    const run = (queues.get(key) ?? Promise.resolve()).then(fn, fn);
+    const settled = run.then(() => undefined, () => undefined);
+    queues.set(key, settled);
+    void settled.then(() => {
+        if (queues.get(key) === settled)
+            queues.delete(key);
+    });
+    return run;
+}
+/** Files whose last failed write could not be cut back: refused until the process restarts (replay then sets it aside). */
+const unrecoverable = new Map();
+/** Record that `file` holds the bytes of a failed write that could not be cut back. */
+function markUnrecoverable(file, reason) {
+    unrecoverable.set(path_1.default.resolve(file), reason);
+}
+/** Why `file` is refused for appends in this process, or `undefined` when it is not. */
+function unrecoverableReason(file) {
+    return unrecoverable.get(path_1.default.resolve(file));
+}

package/dist/memory/factConflicts.js

@@ -0,0 +1,203 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_DRIFT_VALUES = void 0;
+exports.possibleDuplicates = possibleDuplicates;
+exports.namedConflicts = namedConflicts;
+const rowStore_1 = require("../context/rowStore");
+const queryHelpers_1 = require("../retrieval/queryHelpers");
+const factTerms_1 = require("./factTerms");
+const scope_1 = require("../mvp/scope");
+const sourceName_1 = require("./sourceName");
+/**
+ * Multi-agent drift: current lifecycle facts that may be one thing, named, never merged.
+ *
+ * A correction closes only the current fact of the same subject (one identity: case and Unicode form folded),
+ * predicate and scope (any spelling of it, scopeSpellings). When several agents write, the same thing gets saved under another name (Codex writes
+ * "Atlas project", Claude Code writes "Atlas") or in another scope (a correction saved without the project's scope
+ * goes to global), and then both values stay current. This module supersedes nothing across subjects or scopes.
+ * It names what may be one thing, so the agent or the user can decide:
+ *
+ *   - `possibleDuplicates`, on a fact save's receipt: the other current facts related to the one just written;
+ *   - `conflicts`, on a read: groups of related current facts whose values disagree, for the facts the read returns.
+ *
+ * Two facts are related when they have the same predicate and their subjects are one identity (`identityKey`), or
+ * one name is the other with one more word before or after it: "Atlas" and "Atlas project", "staging database" and
+ * "Atlas staging database". A name longer by more words ("Atlas service shipments") or a possessive ("Ravi's
+ * manager", "user's mother") names another thing. Values are compared after `normDedupeValue`, so "Sao Paulo" and
+ * "São Paulo" do not disagree.
+ *
+ * Scope stays an isolation boundary. A call made in a scope sees that scope's facts only, as its reads do
+ * (`scopeFilterFor`), so it is never told what another scope holds. A call without a scope sees every scope, so it
+ * is the one told that a subject and predicate have another current value elsewhere.
+ *
+ * Cost: one pass over the current lifecycle facts that reads the subject names of those with an asked predicate, then
+ * the facts whose name passes a word test in full. Measured with 12 asked facts, 6 of them sharing their predicate with
+ * a quarter of the facts (host load about 45): 0.4 ms at 150 current facts, 2.4 ms at 2,000, 17 ms at 20,000. Nothing
+ * is written and nothing is embedded.
+ */
+/** The most values a conflict, or a receipt's duplicates, lists: the newest first, with the total when there are more. */
+exports.MAX_DRIFT_VALUES = 8;
+/** A folded word that ends in an apostrophe and s ("ravi's", "ravi’s") or in s and an apostrophe ("users'"). */
+const POSSESSIVE = /[\p{L}\p{N}](?:['’]s|s['’])(?=\s|$)/u;
+/** The fold identityKey applies before its alias table: NFC, trimmed, lower-cased. */
+function fold(name) {
+    return name.normalize('NFC').trim().toLowerCase().normalize('NFC');
+}
+/** What separates two words of a folded name. A word keeps its hyphens and underscores: "atl-412" is one word. */
+const NOT_A_WORD = /[^\p{L}\p{N}\p{M}_-]+/u;
+/** The words of a subject name, by name: a read reads the name of every current fact with an asked predicate, and the names are the same read after read. */
+const wordsOfName = new Map();
+const MAX_WORDS_OF_NAME = 8192;
+function wordsOf(subject) {
+    let words = wordsOfName.get(subject);
+    if (words === undefined) {
+        const folded = fold(subject);
+        const split = POSSESSIVE.test(folded) ? [] : folded.split(NOT_A_WORD).filter(Boolean);
+        words = split.length > 0 ? split : null;
+        if (wordsOfName.size >= MAX_WORDS_OF_NAME)
+            wordsOfName.clear();
+        wordsOfName.set(subject, words);
+    }
+    return words;
+}
+function nameOf(subject, names) {
+    let name = names.get(subject);
+    if (!name) {
+        name = { subject, words: wordsOf(subject) };
+        names.set(subject, name);
+    }
+    return name;
+}
+/** Whether `longer` is `shorter` plus one word at its start or its end. */
+function oneWordLonger(longer, shorter) {
+    if (longer.length !== shorter.length + 1)
+        return false;
+    const same = (offset) => shorter.every((word, i) => longer[i + offset] === word);
+    return same(0) || same(1);
+}
+function related(a, b) {
+    if ((a.key ??= (0, queryHelpers_1.identityKey)(a.subject)) === (b.key ??= (0, queryHelpers_1.identityKey)(b.subject)))
+        return true;
+    if (!a.words || !b.words)
+        return false;
+    return oneWordLonger(a.words, b.words) || oneWordLonger(b.words, a.words);
+}
+/**
+ * The current lifecycle facts, in one scope or (null) every scope, newest first, that have the predicate of an asked
+ * fact and a subject that may be related to its subject; `related` then decides. A related name has the asked name's
+ * first word first, or its last word last: it is the same words, or one more, or one fewer at its start or end. So
+ * one pass reads the subject name of every current fact with an asked predicate, and only the facts whose name passes
+ * that test are read in full. A possessive asked name is related by identity alone, so it is looked for whole; an
+ * alias is looked for by each of its spellings. The partial index of current lifecycle facts holds the predicate, so
+ * superseded facts are never visited: `INDEXED BY` states it, because the planner would otherwise take the
+ * source_path index, which holds every lifecycle fact ever saved.
+ */
+function candidates(db, asked, scope, names) {
+    const firsts = new Set();
+    const lasts = new Set();
+    const wholes = new Set();
+    for (const { subject } of asked) {
+        for (const spelling of (0, queryHelpers_1.identityNames)(subject)) {
+            const { words } = nameOf(spelling, names);
+            if (words) {
+                firsts.add(words[0]);
+                lasts.add(words[words.length - 1]);
+            }
+            else {
+                wholes.add(fold(spelling));
+            }
+        }
+    }
+    const inScope = scope === null ? null : (0, scope_1.savedScopeSqlPredicate)((0, scope_1.normalizeScope)(scope), 'f.scope'); // any spelling of it
+    const named = (0, factTerms_1.prepareOnce)(db, `SELECT f.id, e.canonical_name
+     FROM facts f INDEXED BY idx_facts_current
+     JOIN entities e ON e.id = f.subject_entity_id
+     WHERE f.valid_to IS NULL AND f.source_path = '_mcp_'
+       AND f.predicate IN (SELECT value FROM json_each(?))${inScope ? `
+       AND ${inScope.sql}` : ''}`).raw().all(JSON.stringify([...new Set(asked.map(fact => fact.predicate))]), ...(inScope?.params ?? []));
+    const ids = named.filter(([, subject]) => {
+        const { words } = nameOf(subject, names);
+        return words ? firsts.has(words[0]) || lasts.has(words[words.length - 1]) : wholes.has(fold(subject));
+    }).map(([id]) => id);
+    if (ids.length === 0)
+        return [];
+    return (0, factTerms_1.prepareOnce)(db, `SELECT f.id AS id, e.canonical_name AS subject, f.predicate AS predicate, COALESCE(f.object_text, '') AS object,
+            f.scope AS scope, f.valid_from AS validFrom, f.author AS author
+     FROM json_each(?) c
+     CROSS JOIN facts f ON f.id = c.value
+     JOIN entities e ON e.id = f.subject_entity_id
+     ORDER BY f.valid_from DESC, f.id DESC`).all(JSON.stringify(ids));
+}
+/** A value as a read shows it: who saved it, when it is another agent's or an import's (memory/sourceName.ts). */
+function shown(row, reader) {
+    return { subject: row.subject, object: row.object, scope: row.scope, validFrom: row.validFrom, ...(0, sourceName_1.authorMarker)(row.author, reader) };
+}
+/**
+ * The receipt of a fact save: the other current facts with its predicate whose subject is related to the one written,
+ * newest first. `factId` is the fact the save left current (it is not its own duplicate); `scope` is the save's scope
+ * filter (null when the call named no scope).
+ */
+function possibleDuplicates(db, written, factId, scope, reader) {
+    const names = new Map();
+    const asked = nameOf(written.subject, names);
+    const found = candidates(db, [written], scope, names)
+        .filter(row => row.id !== factId && related(asked, nameOf(row.subject, names)));
+    return { values: found.slice(0, exports.MAX_DRIFT_VALUES).map(row => shown(row, reader)), total: found.length };
+}
+/**
+ * The conflicts behind the current lifecycle facts a read returns: for each of them, the current facts related to it
+ * (its own row included); every group that holds two different values is one conflict. Groups that share a fact are
+ * one conflict. Conflicts come in the order of the first fact that names them. `scope` is the read's scope filter
+ * (null when the read named no scope).
+ */
+function namedConflicts(db, facts, scope, reader) {
+    if (facts.length === 0)
+        return [];
+    const names = new Map();
+    const rows = candidates(db, facts, scope, names);
+    if (rows.length < 2)
+        return [];
+    const parent = rows.map((_, i) => i);
+    const root = (i) => {
+        while (parent[i] !== i)
+            i = parent[i] = parent[parent[i]];
+        return i;
+    };
+    const matched = new Set(); // rows related to a fact the read returned; only these are ever joined
+    const firstOfEach = []; // one row of each returned fact's group, in the order the read returned the facts
+    for (const fact of facts) {
+        const asked = nameOf(fact.subject, names);
+        let first = -1;
+        rows.forEach((row, i) => {
+            if (row.predicate !== fact.predicate || !related(asked, nameOf(row.subject, names)))
+                return;
+            matched.add(i);
+            if (first < 0)
+                first = i;
+            else
+                parent[root(i)] = root(first);
+        });
+        if (first >= 0)
+            firstOfEach.push(first);
+    }
+    const groups = new Map();
+    for (const i of [...matched].sort((a, b) => a - b)) { // row order: newest first
+        const group = groups.get(root(i));
+        if (group)
+            group.push(rows[i]);
+        else
+            groups.set(root(i), [rows[i]]);
+    }
+    const conflicts = [];
+    for (const r of new Set(firstOfEach.map(root))) {
+        const group = groups.get(r);
+        if (new Set(group.map(row => (0, rowStore_1.normDedupeValue)(row.object))).size < 2)
+            continue;
+        conflicts.push({
+            predicate: group[0].predicate,
+            values: group.slice(0, exports.MAX_DRIFT_VALUES).map(row => shown(row, reader)),
+            ...(group.length > exports.MAX_DRIFT_VALUES ? { total: group.length } : {}),
+        });
+    }
+    return conflicts;
+}

package/dist/memory/factTerms.js

@@ -0,0 +1,321 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_COMMON_WORDS = exports.RECENT_WINDOW = exports.COMPLETE_POSTINGS = exports.prepareOnce = void 0;
+exports.words = words;
+exports.atoms = atoms;
+exports.atomSequence = atomSequence;
+exports.canonicalSubject = canonicalSubject;
+exports.factVocabulary = factVocabulary;
+exports.indexFactTerms = indexFactTerms;
+exports.unindexFactTerms = unindexFactTerms;
+exports.ensureFactTerms = ensureFactTerms;
+exports.statementTerms = statementTerms;
+exports.findCurrentFacts = findCurrentFacts;
+exports.newestFactEvent = newestFactEvent;
+exports.currentFactById = currentFactById;
+exports.recentCurrentFacts = recentCurrentFacts;
+const statements_1 = require("../db/statements");
+Object.defineProperty(exports, "prepareOnce", { enumerable: true, get: function () { return statements_1.prepareOnce; } });
+const scope_1 = require("../mvp/scope");
+/**
+ * The words a lifecycle fact is found by, and the index that finds facts by them.
+ *
+ * `fact_terms` is an inverted index over the facts table: one row per (word, scope, fact) for every
+ * lifecycle fact, current or superseded, written by the transaction that writes the fact. A search
+ * reads the rows of the query's words and joins only the facts they name, so a fact is found by its
+ * words however old it is, and the work a read does is bounded (below), not a function of the table.
+ *
+ * How far a read goes down a word's rows. A word is *selective* when at most COMPLETE_POSTINGS rows
+ * of the scope read have it (the rows of superseded facts count): its rows are read completely, so
+ * every current fact that has it is found, however old, and is counted exactly, however many other
+ * selective words the query has. A word with more rows is *common*: its rows are not read, and the
+ * facts it finds are those among the RECENT_WINDOW newest current facts of the scope. So a table of
+ * at most COMPLETE_POSTINGS facts is always read exactly, and so is any query with a selective word.
+ * What is given up, and all of it: a fact that has none of the query's selective words and is older
+ * than the newest RECENT_WINDOW facts is not found through common words alone, and an any-words read
+ * ranks by at most MAX_COMMON_WORDS common words. Every candidate is ranked by the number of the
+ * query's words it has.
+ *
+ * The work is bounded by the query, not by the table: a word costs at most COMPLETE_POSTINGS + 1
+ * rows to classify, and a read collects at most COMPLETE_POSTINGS facts per selective word, so at
+ * most (words in the query) x COMPLETE_POSTINGS candidates, plus RECENT_WINDOW; the tools cap a query
+ * at 1,000 characters. Nothing is dropped to keep it so.
+ *
+ * It is derived data, like the rest of index.db: `ensureFactTerms` indexes whatever is missing (a
+ * database from before the index, or one a release without it has written to). Rows are never
+ * removed: a superseded fact keeps its rows, and the join to `facts` filters it out as current.
+ *
+ * No code deletes a lifecycle fact (a correction closes it). Code that ever does must delete its
+ * rows here too, or the words of an erased fact stay in index.db. The table has no foreign key to
+ * `facts` on purpose: deleting a note's facts would then scan this whole table once per fact.
+ */
+/** The words of `value` in the order they occur, repeats included. */
+function tokens(value) {
+    return value
+        .toLowerCase()
+        .replace(/[^\p{L}\p{N}\p{M}_-]+/gu, ' ')
+        .split(/\s+/)
+        .map(w => w.trim())
+        .filter(w => w.length >= 2);
+}
+function words(value) {
+    return Array.from(new Set(tokens(value)));
+}
+/**
+ * Like `words`, but slugs and snake_case split into their parts, the way the full-text index
+ * reads them: `renor-memory-1002` is renor, memory and 1002.
+ */
+function atoms(value) {
+    return Array.from(new Set(atomSequence(value)));
+}
+/** `atoms` in the order they occur, repeats included: which words are next to each other. */
+function atomSequence(value) {
+    return tokens(value.replace(/[-_]+/g, ' '));
+}
+function predicateWords(predicate) {
+    const out = new Set();
+    const irregularBases = {
+        does: 'do',
+        has: 'have',
+    };
+    for (const word of atoms(predicate)) {
+        out.add(word);
+        // Relation keys commonly use third-person singular verbs while users ask
+        // with the base form. Keep this intentionally bounded so predicate nouns
+        // such as "status" do not get arbitrary stems.
+        const irregular = irregularBases[word];
+        if (irregular) {
+            out.add(irregular);
+        }
+        else if (/^[a-z]+ies$/.test(word) && word.length >= 5) {
+            out.add(`${word.slice(0, -3)}y`);
+        }
+        else if (/^[a-z]+(ches|shes|xes|zes|oes|sses)$/.test(word)) {
+            out.add(word.slice(0, -2));
+        }
+        else if (/^[a-z]+s$/.test(word)
+            && word.length >= 4
+            && !word.endsWith('ss')
+            && !word.endsWith('us')
+            && !word.endsWith('is')) {
+            out.add(word.slice(0, -1));
+        }
+    }
+    return Array.from(out);
+}
+/** The name a read shows for a subject: the entity's, which may be an earlier spelling of an event's. */
+function canonicalSubject(db, entityId) {
+    return (0, statements_1.prepareOnce)(db, 'SELECT canonical_name FROM entities WHERE id = ?').get(entityId).canonical_name;
+}
+/** Every word a fact is found by: its subject and object, and its predicate with common verb forms. */
+function factVocabulary(fact) {
+    return new Set([...atoms(`${fact.subject} ${fact.object}`), ...predicateWords(fact.predicate)]);
+}
+/**
+ * Indexes one fact. The empty term is a marker, not a word (a query word is never empty): it says
+ * the fact has been indexed, so one whose text has no words is not indexed again and again.
+ */
+function indexFactTerms(db, factId, scope, fact) {
+    (0, statements_1.prepareOnce)(db, `INSERT OR IGNORE INTO fact_terms (term, scope, fact_id) SELECT value, ?, ? FROM json_each(?)`)
+        .run(scope, factId, JSON.stringify(['', ...factVocabulary(fact)]));
+}
+/** Removes what indexFactTerms wrote for one fact (a retired fact: memory/lifecycle.ts). */
+function unindexFactTerms(db, factId, scope, fact) {
+    (0, statements_1.prepareOnce)(db, `DELETE FROM fact_terms WHERE scope = ? AND fact_id = ? AND term IN (SELECT value FROM json_each(?))`)
+        .run(scope, factId, JSON.stringify(['', ...factVocabulary(fact)]));
+}
+/** Indexes every lifecycle fact that is not indexed yet, in one transaction; returns how many. */
+function ensureFactTerms(db) {
+    const unindexed = db.prepare(`SELECT f.id AS id, f.scope AS scope, e.canonical_name AS subject, f.predicate AS predicate, f.object_text AS object
+     FROM facts f JOIN entities e ON e.id = f.subject_entity_id
+     WHERE f.source_path = '_mcp_'
+       AND NOT EXISTS (SELECT 1 FROM fact_terms t WHERE t.term = '' AND t.scope = f.scope AND t.fact_id = f.id)`).all();
+    if (unindexed.length === 0)
+        return 0;
+    db.transaction(() => {
+        for (const fact of unindexed)
+            indexFactTerms(db, fact.id, fact.scope, { ...fact, object: fact.object ?? '' });
+    })();
+    return unindexed.length;
+}
+/**
+ * The words of a fact's saved statement, kept with the fact (`facts.statement_words`) so the facts lane can count them
+ * toward a question's words (agentMemory.ts `rankCandidateFacts`). The atoms in the order they occur, space-joined: an
+ * atom never holds a space. Null when the fact was saved with no statement (save_memory) or has no word in it.
+ */
+function statementTerms(statement) {
+    if (statement === undefined)
+        return null;
+    const terms = atoms(statement);
+    return terms.length > 0 ? terms.join(' ') : null;
+}
+const FACT_COLUMNS = `f.event_id AS eventId, e.canonical_name AS subject, f.predicate AS predicate,
+            f.object_text AS object, f.valid_from AS validFrom, f.scope AS scope, f.author AS author,
+            f.statement_words AS statementWords`;
+const FACT_MATCH_COLUMNS = `f.id AS id, ${FACT_COLUMNS}`;
+/** A word with at most this many rows (in the scope read) is selective: its rows are read completely. */
+exports.COMPLETE_POSTINGS = 1_000;
+/** A common word is matched among this many of the newest current facts of the scope. */
+exports.RECENT_WINDOW = 500;
+/** An any-words read ranks by at most this many common words (the first in the query); selective words all count. */
+exports.MAX_COMMON_WORDS = 8;
+/**
+ * The query's words that some fact has, selective ones first and the rarest of them first. Reads at
+ * most COMPLETE_POSTINGS + 1 rows of a word, which is enough to know it is common. With `needAll`,
+ * a word no fact has ends the read: nothing can have every word.
+ */
+function readWords(db, terms, scope, needAll) {
+    const inScope = scope === undefined ? undefined : (0, scope_1.savedScopeSqlPredicate)((0, scope_1.normalizeScope)(scope), 'scope');
+    const read = (0, statements_1.prepareOnce)(db, `SELECT fact_id FROM fact_terms WHERE term = ? ${inScope === undefined ? '' : `AND ${inScope.sql}`} LIMIT ?`).pluck();
+    const found = [];
+    for (const term of terms) {
+        const ids = read.all(term, ...(inScope?.params ?? []), exports.COMPLETE_POSTINGS + 1);
+        if (ids.length === 0) {
+            if (needAll)
+                return null;
+            continue;
+        }
+        const common = ids.length > exports.COMPLETE_POSTINGS;
+        found.push({ term, ids: common ? [] : ids, common });
+    }
+    return found.sort((a, b) => Number(a.common) - Number(b.common) || a.ids.length - b.ids.length);
+}
+/**
+ * The rows `read` returns for each spelling of `scope` (scopeSpellings), merged newest first and cut to `limit`.
+ * `read` takes a spelling and a limit and returns at most that many rows of a partial index, newest first, so the
+ * merge never sorts more than one `limit` per spelling, and a scope with one spelling (global) is returned as read.
+ */
+function newestOfSpellings(read, scope, limit) {
+    const spellings = (0, scope_1.scopeSpellings)((0, scope_1.normalizeScope)(scope));
+    const rows = spellings.flatMap(spelling => read.all(spelling, limit));
+    if (spellings.length === 1)
+        return rows;
+    return rows
+        .sort((a, b) => (a.validFrom === b.validFrom ? b.id - a.id : a.validFrom < b.validFrom ? 1 : -1))
+        .slice(0, limit);
+}
+/** The ids of the newest current facts of the scope: `RECENT_WINDOW` rows of a partial index per spelling, in order. */
+function recentFactIds(db, scope) {
+    const read = (0, statements_1.prepareOnce)(db, `SELECT f.id AS id, f.valid_from AS validFrom FROM facts f INDEXED BY ${scope === undefined ? 'idx_facts_lifecycle_recent' : 'idx_facts_lifecycle_scope_recent'}
+     WHERE f.valid_to IS NULL AND f.source_path = '_mcp_' ${scope === undefined ? '' : 'AND f.scope = ?'}
+     ORDER BY f.valid_from DESC, f.id DESC LIMIT ?`);
+    const rows = scope === undefined
+        ? read.all(exports.RECENT_WINDOW)
+        : newestOfSpellings(read, scope, exports.RECENT_WINDOW);
+    return rows.map(row => row.id);
+}
+/**
+ * The current facts found by `terms`, best first: more of the words, then newest. `scope` is one
+ * scope when given (a normalized scope, read under every spelling of it: scopeSpellings) and every
+ * scope when omitted. Only current lifecycle facts count.
+ *
+ * `any` ranks the facts that have at least one word; `all` needs every word. How much of a word's
+ * rows is read, and what that gives up, is in the header of this file.
+ */
+function findCurrentFacts(db, args) {
+    const { scope, match, limit } = args;
+    const terms = [...new Set(args.terms)].filter(term => term !== ''); // '' is the marker row, never a word
+    if (terms.length === 0 || limit < 1)
+        return [];
+    const words = readWords(db, terms, scope, match === 'all');
+    if (!words || words.length === 0)
+        return [];
+    const scoped = scope === undefined ? undefined : (0, scope_1.savedScopeSqlPredicate)((0, scope_1.normalizeScope)(scope), 'f.scope');
+    const inScope = scoped === undefined ? '' : `AND ${scoped.sql}`;
+    const scopeArgs = scoped?.params ?? [];
+    if (match === 'any') {
+        // Every selective word is read completely; only the common words are matched through the newest
+        // facts, and at most MAX_COMMON_WORDS of them are probed.
+        const probed = words.filter(word => word.common).slice(0, exports.MAX_COMMON_WORDS);
+        // Fact id -> how many selective words it has, counted from the rows already read.
+        const candidates = new Map();
+        for (const word of words)
+            if (!word.common)
+                for (const id of word.ids)
+                    candidates.set(id, (candidates.get(id) ?? 0) + 1);
+        if (probed.length > 0)
+            for (const id of recentFactIds(db, scope))
+                if (!candidates.has(id))
+                    candidates.set(id, 0);
+        // The candidates are ranked on their id, date and count alone; only the `limit` best are joined to
+        // their entity and read in full. A window fact that has none of the probed words scores 0 and is dropped.
+        return (0, statements_1.prepareOnce)(db, `WITH scored AS MATERIALIZED (
+         SELECT f.id AS id, f.valid_from AS validFrom,
+                json_extract(c.value, '$[1]')${probed.length === 0 ? '' : `
+                  + (SELECT COUNT(*) FROM fact_terms p
+                     WHERE p.term IN (${probed.map(() => '?').join(', ')}) AND p.scope = f.scope AND p.fact_id = f.id)`} AS shared
+         FROM json_each(?) c
+         CROSS JOIN facts f ON f.id = json_extract(c.value, '$[0]')
+         WHERE f.valid_to IS NULL AND f.source_path = '_mcp_' ${inScope}
+       ), best AS (
+         SELECT id, validFrom, shared FROM scored WHERE shared > 0
+         ORDER BY shared DESC, validFrom DESC, id DESC
+         LIMIT ?
+       )
+       SELECT ${FACT_MATCH_COLUMNS}, b.shared AS shared
+       FROM best b
+       JOIN facts f ON f.id = b.id
+       JOIN entities e ON e.id = f.subject_entity_id
+       ORDER BY b.shared DESC, b.validFrom DESC, b.id DESC`).all(...probed.map(word => word.term), JSON.stringify([...candidates]), ...scopeArgs, limit);
+    }
+    // `all`: every fact that has every word has the rarest selective word, so its rows are the
+    // candidates and the other words are probed, one candidate at a time. With no selective word, the
+    // candidates are the newest facts and every word is probed.
+    const driver = words.find(word => !word.common);
+    const candidates = driver ? driver.ids : recentFactIds(db, scope);
+    const probed = words.filter(word => word !== driver).map(word => word.term);
+    return (0, statements_1.prepareOnce)(db, `SELECT ${FACT_MATCH_COLUMNS}, ${terms.length} AS shared
+     FROM json_each(?) c
+     CROSS JOIN facts f ON f.id = c.value
+     JOIN entities e ON e.id = f.subject_entity_id
+     WHERE f.valid_to IS NULL AND f.source_path = '_mcp_' ${inScope}
+       ${probed.map(() => 'AND EXISTS (SELECT 1 FROM fact_terms p WHERE p.term = ? AND p.scope = f.scope AND p.fact_id = f.id)').join('\n       ')}
+     ORDER BY f.valid_from DESC, f.id DESC
+     LIMIT ?`).all(JSON.stringify(candidates), ...scopeArgs, ...probed, limit);
+}
+/**
+ * The ledger event that wrote the newest lifecycle fact (current or superseded) of one scope, or of
+ * every scope when none is given. A scope's newest fact is the last row of its marker in the term
+ * index, one seek per spelling of the scope (scopeSpellings); without a scope it is the last row of
+ * the facts table.
+ */
+function newestFactEvent(db, scope) {
+    if (scope === undefined) {
+        const row = (0, statements_1.prepareOnce)(db, `SELECT event_id AS eventId FROM facts WHERE source_path = '_mcp_' AND event_id IS NOT NULL ORDER BY id DESC LIMIT 1`).get();
+        return row?.eventId;
+    }
+    const read = (0, statements_1.prepareOnce)(db, `SELECT t.fact_id AS id, f.event_id AS eventId
+     FROM fact_terms t CROSS JOIN facts f ON f.id = t.fact_id
+     WHERE t.term = '' AND t.scope = ? AND f.source_path = '_mcp_' AND f.event_id IS NOT NULL
+     ORDER BY t.fact_id DESC LIMIT 1`);
+    let newest;
+    for (const spelling of (0, scope_1.scopeSpellings)((0, scope_1.normalizeScope)(scope))) {
+        const row = read.get(spelling);
+        if (row && (!newest || row.id > newest.id))
+            newest = row;
+    }
+    return newest?.eventId;
+}
+/** One current lifecycle fact by its row id; undefined once it is superseded (or was never a lifecycle fact). */
+function currentFactById(db, id) {
+    return (0, statements_1.prepareOnce)(db, `SELECT ${FACT_COLUMNS}
+     FROM facts f JOIN entities e ON e.id = f.subject_entity_id
+     WHERE f.id = ? AND f.valid_to IS NULL AND f.source_path = '_mcp_'`).get(id);
+}
+/**
+ * The newest current facts, for a read with no query. The partial indexes (migration 14) keep them
+ * in order, so this reads `limit` rows however many facts there are; `INDEXED BY` states that
+ * intent, because the planner would otherwise pick the source_path index and sort every fact.
+ */
+function recentCurrentFacts(db, scope, limit) {
+    const read = db.prepare(`SELECT ${FACT_COLUMNS}, f.id AS id
+     FROM facts f INDEXED BY ${scope === undefined ? 'idx_facts_lifecycle_recent' : 'idx_facts_lifecycle_scope_recent'}
+     JOIN entities e ON e.id = f.subject_entity_id
+     WHERE f.valid_to IS NULL AND f.source_path = '_mcp_' ${scope === undefined ? '' : 'AND f.scope = ?'}
+     ORDER BY f.valid_from DESC, f.id DESC
+     LIMIT ?`);
+    const rows = scope === undefined
+        ? read.all(limit)
+        : newestOfSpellings(read, scope, limit);
+    return rows.map(({ id: _id, ...fact }) => fact); // the row id only orders the merge
+}

package/dist/memory/hiveNameHeader.cjs

@@ -0,0 +1,10 @@
+const { createHash } = require('node:crypto');
+
+/** The shared, HTTP-header-safe first stage of every connection's hive name. */
+exports.hiveNameHeader = function hiveNameHeader(label) {
+  const raw = typeof label === 'string' ? label.normalize('NFC').replace(/\s+/g, ' ').trim() : '';
+  if (raw === '') return 'unnamed';
+  const text = raw.replace(/[^\t\x20-\x7e\xa0-\xff]/g, '').replace(/\s+/g, ' ').trim();
+  if (text === '') return `agent-${createHash('sha256').update(raw, 'utf8').digest('hex').slice(0, 8)}`;
+  return text.slice(0, 80);
+};

package/dist/memory/inventory.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ledgerNotePath = ledgerNotePath;
+exports.countEntities = countEntities;
+exports.countInventory = countInventory;
+const lifecycle_1 = require("./lifecycle");
+const entityLookup_1 = require("../retrieval/entityLookup");
+/**
+ * The ledger file as the index stores its path (the vault walk joins from the same resolved directory), or null when
+ * the configured path cannot name a file. Null excludes nothing: the SQL below reads it as `IS NOT NULL`.
+ */
+function ledgerNotePath(vault) {
+    try {
+        return (0, lifecycle_1.resolveLedgerPath)(vault.memoryDir, vault.ledgerRelPath);
+    }
+    catch {
+        return null;
+    }
+}
+function scalar(db, sql, ...params) {
+    return db.prepare(sql).get(...params).c;
+}
+/**
+ * Entities without the one the index registers for the ledger file. The subjects of lifecycle facts (source note
+ * `_mcp_`), while one of their facts is not retired, and the entity of every other note count. `filter` narrows the count to one scope (entityScopeFilter), so a
+ * count handed to a caller who may read only that scope is never workspace-wide. lookup_entity reports this same count
+ * when it finds nothing, so it cannot name a different number of entities than memory_status.
+ */
+function countEntities(db, vault, filter) {
+    const where = ['source_note IS NOT ?'];
+    const params = [ledgerNotePath(vault)];
+    // Without a scope, every scope's (liveEntityFilter): the count lookup_entity reports with no scope.
+    const narrowed = filter ?? (0, entityLookup_1.liveEntityFilter)();
+    where.push(narrowed.sql);
+    params.push(...narrowed.params);
+    return scalar(db, `SELECT COUNT(*) AS c FROM entities WHERE ${where.join(' AND ')}`, ...params);
+}
+function countInventory(db, vault) {
+    // A table that cannot be read counts as empty, as memory_status always has.
+    const orZero = (count) => {
+        try {
+            return count();
+        }
+        catch {
+            return 0;
+        }
+    };
+    return {
+        notes: orZero(() => scalar(db, 'SELECT COUNT(*) AS c FROM notes WHERE path IS NOT ? AND path IS NOT ?', lifecycle_1.LIFECYCLE_NOTE_PATH, ledgerNotePath(vault))),
+        chunks: orZero(() => scalar(db, 'SELECT COUNT(*) AS c FROM chunks')),
+        entities: orZero(() => countEntities(db, vault)),
+        facts: orZero(() => scalar(db, 'SELECT COUNT(*) AS c FROM facts')),
+        relations: orZero(() => scalar(db, 'SELECT COUNT(*) AS c FROM relations')),
+    };
+}

package/dist/memory/invisibleText.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isBlankOrInvisible = isBlankOrInvisible;
+/**
+ * True when `text` holds nothing a reader can see: only whitespace, the Unicode default-ignorable code
+ * points, the Unicode format controls, and the two blank symbols — U+2800 BRAILLE PATTERN BLANK and
+ * U+FFFC OBJECT REPLACEMENT CHARACTER — which render as nothing but are neither whitespace nor
+ * default-ignorable.
+ *
+ * A subject, predicate, object, note or statement made only of these is refused on write, so a memory
+ * that looks empty is never stored and no user has to correct one they cannot see. One rule for every
+ * write path: the ledger's structured fields (`refuseUnstorableFields`), the daily-note writer
+ * (`checkedNoteText`) and the import preview all read it here, so a blank a reader cannot see is blank
+ * everywhere. Whitespace and default-ignorable alone left U+2800, U+FFFC and the interlinear-annotation
+ * controls U+FFF9..U+FFFB accepted (breaker run 2).
+ */
+const BLANK_OR_INVISIBLE = /^[\s\p{Default_Ignorable_Code_Point}\p{Cf}\u2800\uFFFC]*$/u;
+function isBlankOrInvisible(text) {
+    return BLANK_OR_INVISIBLE.test(text);
+}