renor-engine 0.0.0-stage → 1.0.0

package/dist/memorymap/replacedJournal.js

@@ -0,0 +1,58 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REPLACED_FILE_NAME = void 0;
+exports.forgetReplacementsOf = forgetReplacementsOf;
+const crypto_1 = __importDefault(require("crypto"));
+const promises_1 = __importDefault(require("fs/promises"));
+const path_1 = __importDefault(require("path"));
+/** The replacement journal (a correction that names the memory it corrects), beside the retirement journal. */
+exports.REPLACED_FILE_NAME = 'replaced.jsonl';
+/**
+ * Drop every replacement record that names one of `memoryIds` as the memory it corrects or the correction that replaces it,
+ * so a permanently deleted memory leaves no id behind (export keeps these records). `retiredDir` is the retirement folder,
+ * already inside the vault. The file is replaced atomically; a torn or unreadable line is kept as it is, and a file that is
+ * not a plain single-name file is refused. Idempotent, so a retry after a crash repeats it harmlessly.
+ */
+async function forgetReplacementsOf(retiredDir, memoryIds) {
+    if (memoryIds.size === 0)
+        return;
+    const file = path_1.default.join(retiredDir, exports.REPLACED_FILE_NAME);
+    let st;
+    try {
+        st = await promises_1.default.lstat(file);
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return;
+        throw err;
+    }
+    if (!st.isFile() || st.nlink !== 1)
+        throw new Error(`refusing to rewrite ${JSON.stringify(exports.REPLACED_FILE_NAME)}: it is not a regular file with a single name`);
+    const raw = await promises_1.default.readFile(file, 'utf8');
+    let changed = false;
+    const kept = [];
+    for (const line of raw.split('\n')) {
+        if (!line.trim())
+            continue;
+        let hit = false;
+        try {
+            const r = JSON.parse(line);
+            hit = memoryIds.has(String(r.old)) || memoryIds.has(String(r.by));
+        }
+        catch {
+            // A torn final line is kept as it is; the reader skips it.
+        }
+        if (hit)
+            changed = true;
+        else
+            kept.push(line);
+    }
+    if (!changed)
+        return;
+    const tmp = `${file}.${process.pid}.${crypto_1.default.randomBytes(4).toString('hex')}.tmp`;
+    await promises_1.default.writeFile(tmp, kept.map((line) => `${line}\n`).join(''), { flag: 'wx', mode: st.mode & 0o777 });
+    await promises_1.default.rename(tmp, file);
+}

package/dist/memorymap/replacements.js

@@ -0,0 +1,405 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hasReplacements = hasReplacements;
+exports.replacementIndex = replacementIndex;
+exports.allReplacementRecords = allReplacementRecords;
+exports.assertReplaceable = assertReplaceable;
+exports.recordReplacement = recordReplacement;
+exports.withReplacements = withReplacements;
+const fs_1 = __importDefault(require("fs"));
+const promises_1 = __importDefault(require("fs/promises"));
+const path_1 = __importDefault(require("path"));
+const crypto_1 = __importDefault(require("crypto"));
+const dailyNote_1 = require("../memory/dailyNote");
+const scope_1 = require("../mvp/scope");
+const toolRefusal_1 = require("../toolRefusal");
+const sourceName_1 = require("../memory/sourceName");
+const orchestrator_1 = require("../retrieval/orchestrator");
+const memoryMap_1 = require("./memoryMap");
+const replacedJournal_1 = require("./replacedJournal");
+// ---------------------------------------------------------------------------
+// Replacements: a correction that names the earlier memory it corrects.
+//
+// Agents already save corrections ("the export now includes daily entries"), but nothing linked one to the note it
+// corrects, so a recall served the stale note as current (owner request 2026-10-12; two wrong answers the same day).
+// `remember({statement, replaces: <id>})` saves the correction as usual and appends one record here. Nothing stored is
+// touched: the earlier memory keeps its text, its place in search, its export, and stays retrievable. A read that returns it
+// labels it replaced, points at the correction, and lays the correction out before it.
+//
+// The record lives beside the retirement journal (.trash/renor-retired/replaced.jsonl), not in the fact ledger: the
+// ledger is replayed strictly at startup (an unknown event kind refuses to load), so a new kind there would stop an older
+// engine release from starting on a workspace that holds one, and a replacement is no fact.
+//
+// A replacement is in effect while its correction is live. Retiring the correction (retire_memory) ends it; restoring the
+// correction brings it back, with nothing else to undo. Corrections chain (A replaced by B, B by C): A reads as replaced by C.
+// ---------------------------------------------------------------------------
+const REPLACED_FILE = path_1.default.join(memoryMap_1.RETIRED_DIR, replacedJournal_1.REPLACED_FILE_NAME);
+/** The corrected text of a note a replacement pulls into a reply, by characters (an entry is whole). */
+const NOTE_CORRECTION_CHARS = 1200;
+const MAX_CHAIN = 64;
+const EMPTY = { size: 0, replacedBy: () => undefined, replaces: () => [], reaches: () => false, paths: new Set() };
+const relOf = (id) => {
+    if (id.startsWith('note:'))
+        return id.slice(5);
+    const hashAt = id.lastIndexOf('#');
+    return id.slice(6, hashAt);
+};
+/**
+ * A source as a label or a link carries it: the daily-note header form (letters, digits, hyphens), cut to MAX_SOURCE_LENGTH.
+ * Both sides are reduced the same way, so one agent spelled two ways is one source, and a source taken from a note's own front
+ * matter is bounded and clean before any reply carries it (memory text can name anything there). Null when nothing is left.
+ */
+function sourceForLabel(source) {
+    if (typeof source !== 'string')
+        return null;
+    return (0, sourceName_1.headerSource)(source) || null;
+}
+/**
+ * The label for a memory replaced by `replaced`, whose newest correction is `correction` (the last link of its chain). The source
+ * is the correction's; the note is added only when both sides' sources are recorded and differ, so a reader can weigh a correction
+ * from another agent. A record without `oldSource` (written before it was kept) names no other side.
+ */
+function labelOf(replaced, correction) {
+    const saver = sourceForLabel(correction.source);
+    const label = { by: correction.by, at: correction.at, ...(saver ? { source: saver } : {}) };
+    if (replaced.oldSource === undefined)
+        return label;
+    const from = sourceForLabel(replaced.oldSource);
+    if (saver === from)
+        return label;
+    return { ...label, note: `the correction's source differs from the replaced memory's source (${from ?? 'none recorded'})` };
+}
+let cache;
+/**
+ * Whether this workspace has ever recorded a replacement, answered at once (one stat, no await): a read of a workspace with none
+ * goes on exactly as it did before replacements existed, with no extra turn of the event loop in its assembly.
+ */
+function hasReplacements(memoryDir) {
+    try {
+        return fs_1.default.lstatSync(path_1.default.join(memoryDir, REPLACED_FILE)).size > 0;
+    }
+    catch {
+        return false;
+    }
+}
+async function readRecords(ctx) {
+    const rootReal = await promises_1.default.realpath(ctx.memoryDir);
+    const file = path_1.default.join(rootReal, REPLACED_FILE);
+    let stat;
+    try {
+        stat = await promises_1.default.lstat(file);
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return [];
+        throw err;
+    }
+    const key = `${file}\0${stat.mtimeMs}\0${stat.size}\0${stat.ino}`;
+    if (cache?.key === key)
+        return cache.records;
+    for (const dir of [path_1.default.join(rootReal, '.trash'), path_1.default.join(rootReal, memoryMap_1.RETIRED_DIR)]) {
+        const st = await promises_1.default.lstat(dir);
+        if (st.isSymbolicLink() || !st.isDirectory())
+            throw new Error('the replacement journal is not inside the vault');
+    }
+    const handle = await (0, memoryMap_1.openConfined)(file);
+    let raw;
+    try {
+        raw = await handle.readFile('utf8');
+    }
+    finally {
+        await handle.close();
+    }
+    const records = [];
+    for (const line of raw.split('\n')) {
+        if (!line.trim())
+            continue;
+        try {
+            const r = JSON.parse(line);
+            if (typeof r.rid === 'string' && typeof r.old === 'string' && typeof r.by === 'string' && typeof r.at === 'string')
+                records.push(r);
+        }
+        catch {
+            // A torn final line (a crash mid-append) is skipped, never fatal.
+        }
+    }
+    cache = { key, records };
+    return records;
+}
+/** The replacements in effect: those whose correction is live (not retired), with each chain followed to its newest correction. */
+async function replacementIndex(ctx) {
+    const records = await readRecords(ctx);
+    if (records.length === 0)
+        return EMPTY;
+    const retired = new Set((0, memoryMap_1.activeRetired)(await (0, memoryMap_1.readJournal)(ctx)).map(r => r.id));
+    const direct = new Map();
+    const byAll = new Map();
+    for (const r of records) {
+        if (retired.has(r.by) || r.old === r.by)
+            continue;
+        const kept = direct.get(r.old);
+        if (!kept || r.at >= kept.at)
+            direct.set(r.old, r);
+    }
+    for (const r of direct.values())
+        if (!retired.has(r.old))
+            byAll.set(r.by, [...(byAll.get(r.by) ?? []), r.old]);
+    if (direct.size === 0)
+        return EMPTY;
+    // The newest correction of a chain. A loop (or a chain longer than any real one) has no newest: it is read as not replaced,
+    // never as replaced by itself or by a middle link.
+    const head = (id) => {
+        const first = direct.get(id);
+        if (!first)
+            return undefined;
+        let at = first;
+        const seen = new Set([id]);
+        for (let hops = 0;; hops++) {
+            if (seen.has(at.by) || hops > MAX_CHAIN)
+                return undefined;
+            seen.add(at.by);
+            const next = direct.get(at.by);
+            if (!next)
+                return labelOf(first, at);
+            at = next;
+        }
+    };
+    const reaches = (from, target) => {
+        const seen = new Set();
+        for (let at = from; at !== undefined && !seen.has(at) && seen.size <= MAX_CHAIN; at = direct.get(at)?.by) {
+            if (at === target)
+                return true;
+            seen.add(at);
+        }
+        return false;
+    };
+    const paths = new Set();
+    for (const r of direct.values()) {
+        paths.add(relOf(r.old));
+        paths.add(relOf(r.by));
+    }
+    return { size: direct.size, replacedBy: head, replaces: id => byAll.get(id) ?? [], reaches, paths };
+}
+/** Every record ever written for a correction, in effect or not (export keeps the link of a retired correction). */
+async function allReplacementRecords(ctx) {
+    return readRecords(ctx);
+}
+/**
+ * Refuse a replacement that cannot hold, before anything is saved: the memory must exist and be live, be a note or a
+ * daily-log entry (a fact is corrected by saving it again with the same subject, predicate and scope), and be in the scope the
+ * correction is saved to, so a correction never reaches into another scope's memories, nor a read of one scope into another's.
+ */
+async function assertReplaceable(ctx, id, scope) {
+    if (typeof id === 'string' && id.startsWith('fact:')) {
+        throw (0, toolRefusal_1.refusal)('invalid_argument', 'a fact is corrected by saving it again with the same subject, predicate and scope, not with replaces');
+    }
+    (0, memoryMap_1.parseMemoryId)(id);
+    const memory = (await (0, memoryMap_1.readMemory)(ctx, id)).memory;
+    if (!(0, scope_1.notePathMatchesScope)(memory.path, scope)) {
+        throw (0, toolRefusal_1.refusal)('invalid_argument', 'replaces names a memory of another scope: a correction replaces only memories of its own scope');
+    }
+}
+/**
+ * The source the memory `id` was saved with, in the label form (null: none recorded), or undefined when it cannot be read: the
+ * link is kept without it. A note's source is its own front matter, so it is reduced here, before it is stored or compared.
+ */
+async function sourceOfMemory(ctx, id) {
+    try {
+        return sourceForLabel((await (0, memoryMap_1.readMemory)(ctx, id)).memory.source);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Record that `by` replaces `old`. Null, and nothing recorded, when that would make a loop: the save is the memory it replaces
+ * (an identical line saved again in the same second is the same memory, since an id is the hash of the line), or is already
+ * replaced by it, directly or down a chain.
+ */
+async function recordReplacement(ctx, old, by, source) {
+    const existing = (await readRecords(ctx)).find(r => r.old === old && r.by === by);
+    if (existing)
+        return existing;
+    if (old === by || (await replacementIndex(ctx)).reaches(by, old))
+        return null;
+    const oldSource = await sourceOfMemory(ctx, old);
+    const saver = sourceForLabel(source);
+    const record = {
+        rid: `replaced:${crypto_1.default.randomBytes(8).toString('hex')}`, old, by, at: new Date().toISOString(), ...(saver ? { source: saver } : {}),
+        ...(oldSource !== undefined ? { oldSource } : {}),
+    };
+    const dir = await (0, memoryMap_1.ensureRealDir)(await promises_1.default.realpath(ctx.memoryDir), memoryMap_1.RETIRED_DIR);
+    const handle = await promises_1.default.open(path_1.default.join(dir, path_1.default.basename(REPLACED_FILE)), promises_1.default.constants.O_RDWR | promises_1.default.constants.O_APPEND | promises_1.default.constants.O_CREAT | memoryMap_1.NOFOLLOW, 0o600);
+    try {
+        // A crash can leave a torn last line; start on a fresh line so this record is never glued to it.
+        const size = (await handle.stat()).size;
+        let prefix = '';
+        if (size > 0) {
+            const last = Buffer.alloc(1);
+            await handle.read(last, 0, 1, size - 1);
+            if (last[0] !== 0x0a)
+                prefix = '\n';
+        }
+        await handle.appendFile(`${prefix}${JSON.stringify(record)}\n`, 'utf8');
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+    cache = undefined;
+    return record;
+}
+/** The memory ids a hit is: the note, or the daily-log entries whose text holds it. A fact or a ledger statement is none. */
+async function hitIds(ctx, index, hit, entries) {
+    if (hit.notePath === '' || !index.paths.has(hit.notePath))
+        return [];
+    if (!dailyNote_1.DAILY_FILE_RE.test(hit.notePath))
+        return [`note:${hit.notePath}`];
+    let blocks = entries.get(hit.notePath);
+    if (!blocks) {
+        blocks = (async () => {
+            try {
+                const file = await (0, memoryMap_1.resolveVaultFile)(ctx, hit.notePath, true);
+                const read = await (0, memoryMap_1.readPrefix)(file.real, 8 * 1024 * 1024);
+                return read ? (0, memoryMap_1.parseEntries)(file.rel, read.text).blocks : [];
+            }
+            catch {
+                return []; // gone since it was indexed: the hit stays what it was
+            }
+        })();
+        entries.set(hit.notePath, blocks);
+    }
+    const text = hit.text.trim();
+    return (await blocks).filter(b => b.raw.trim() === text || b.text.trim() === text || b.raw.includes(text)).map(b => b.id);
+}
+/** A correction that was not among the hits, as a hit: an entry whole, a note by its first characters. */
+async function correctionHit(ctx, id) {
+    try {
+        const { memory, text } = await (0, memoryMap_1.readMemory)(ctx, id);
+        const body = memory.kind === 'entry' ? text : text.slice(0, NOTE_CORRECTION_CHARS);
+        const raw = memory.kind === 'entry' ? await entryRaw(ctx, id) : null;
+        const bound = (0, orchestrator_1.createNoteTimeBound)(ctx.db);
+        const indexed = path_1.default.resolve(ctx.memoryDir, memory.path);
+        const date = memory.session_date ?? (memory.kind === 'entry' ? bound(indexed, memory.at) : (0, orchestrator_1.resolveSessionDate)(undefined, memory.at));
+        return {
+            notePath: memory.path,
+            headingPath: dailyNote_1.DAILY_FILE_RE.exec(memory.path)?.[2] ?? '',
+            text: raw ?? body,
+            ...(date ? { session_date: date } : {}),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+async function entryRaw(ctx, id) {
+    const { rel } = (0, memoryMap_1.parseMemoryId)(id);
+    const file = await (0, memoryMap_1.resolveVaultFile)(ctx, rel, true);
+    const read = await (0, memoryMap_1.readPrefix)(file.real, 8 * 1024 * 1024);
+    return read ? (0, memoryMap_1.parseEntries)(file.rel, read.text).blocks.find(b => b.id === id)?.raw ?? null : null;
+}
+/**
+ * Lay a reply's hits out for the replacements in effect: a hit that is a replaced memory gets `replaced` (its label) and
+ * follows its correction, and a correction the read did not return is added before the first memory it replaces, with that
+ * memory's score and reason "replacement", so an agent that recalls a stale note is handed the fix with it. Nothing is dropped
+ * for it and no text changes. `pairs` receives each replaced hit with the correction listed for it, for a caller that budgets
+ * (get_context). `limit` is the most hits the reply may hold: an added correction takes the place of the last hit that is
+ * neither a replaced memory nor a correction, so a page never grows past its top_k (and a limit too small for the pair lists the
+ * correction and leaves the replaced memory out). A reply none of whose hits is involved is
+ * returned as it was, and a workspace with no replacement pays one stat.
+ */
+async function withReplacements(ctx, hits, options = {}) {
+    if (!hasReplacements(ctx.memoryDir))
+        return hits;
+    const index = await replacementIndex(ctx);
+    if (index.size === 0 || !hits.some(h => index.paths.has(h.notePath)))
+        return hits;
+    const entries = new Map();
+    const ids = await Promise.all(hits.map(h => hitIds(ctx, index, h, entries)));
+    const labels = ids.map(own => {
+        const labelled = own.map(id => index.replacedBy(id));
+        return own.length > 0 && labelled.every(l => l !== undefined) ? labelled[0] : undefined;
+    });
+    const correctionAt = new Map(); // correction id -> position of the hit that is it
+    ids.forEach((own, i) => { if (labels[i] === undefined)
+        for (const id of own)
+            correctionAt.set(id, i); });
+    if (labels.every(l => l === undefined))
+        return hits;
+    const out = [];
+    const waiting = new Map(); // replaced hits held until their correction is out
+    const flush = (hitIds) => {
+        for (const id of hitIds) {
+            for (const held of waiting.get(id) ?? [])
+                out.push(held);
+            waiting.delete(id);
+        }
+    };
+    const added = new Map(); // correction id -> the hit added for it (null: unreadable)
+    const involved = new Set();
+    const paired = [];
+    for (let i = 0; i < hits.length; i++) {
+        const label = labels[i];
+        if (label === undefined) {
+            out.push(hits[i]);
+            flush(ids[i]);
+            continue;
+        }
+        const replaced = { ...hits[i], replaced: label };
+        involved.add(replaced);
+        paired.push({ replaced, by: label.by });
+        if (correctionAt.has(label.by)) {
+            // The correction is among the hits: before this one if it came first, else this one waits for it.
+            if (correctionAt.get(label.by) < i)
+                out.push(replaced);
+            else
+                waiting.set(label.by, [...(waiting.get(label.by) ?? []), replaced]);
+            continue;
+        }
+        if (!added.has(label.by)) {
+            const fix = await correctionHit(ctx, label.by);
+            const hit = fix ? { ...fix, ...(hits[i].score !== undefined ? { score: hits[i].score } : {}), reason: 'replacement' } : null;
+            added.set(label.by, hit);
+            if (hit) {
+                out.push(hit);
+                involved.add(hit);
+            }
+        }
+        out.push(replaced);
+    }
+    for (const held of waiting.values())
+        out.push(...held);
+    for (const { by } of paired)
+        if (correctionAt.has(by))
+            involved.add(hits[correctionAt.get(by)]);
+    if (options.pairs) {
+        for (const { replaced, by } of paired) {
+            const correction = added.get(by) ?? (correctionAt.has(by) ? hits[correctionAt.get(by)] : null);
+            if (correction)
+                options.pairs.push({ replaced, correction });
+        }
+    }
+    const limit = options.limit;
+    if (limit !== undefined) {
+        while (out.length > limit) {
+            let at = -1;
+            for (let i = out.length - 1; i >= 0; i--)
+                if (!involved.has(out[i])) {
+                    at = i;
+                    break;
+                }
+            // Nothing else left to give up: a top_k too small for the pair lists the correction and leaves the replaced memory out.
+            if (at < 0)
+                for (let i = out.length - 1; i >= 0 && at < 0; i--)
+                    if (out[i].replaced !== undefined)
+                        at = i;
+            if (at < 0)
+                break;
+            out.splice(at, 1);
+        }
+    }
+    return out;
+}

package/dist/mvp/activity.js

@@ -0,0 +1,86 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ActivityGauge = exports.ACTIVITY_PATH = exports.ACTIVITY_REPORT_VERSION = void 0;
+/**
+ * What the release asks an engine before it restarts it: is work running that a restart would cut, and when did the last
+ * of it end.
+ *
+ * Always on, unlike the on-demand IdleMonitor. It counts every unit of work a restart could cut and nothing else:
+ *   - an MCP request (POST or DELETE /mcp) from its start until its HTTP response has finished or closed, which is later
+ *     than its tool handler returning (a streamed response can still be in delivery), and ends when the client aborts;
+ *   - every tool call until it returns, even one whose client has gone;
+ *   - the flights the monitor tracks (evidence extraction, digests);
+ *   - the process-owned jobs a call starts and does not await (the embedding rebuild, the background index) while they
+ *     are working. A job that is only waiting out a delay before its next attempt is not work in progress: it holds
+ *     nothing, and it is resumed from the index at the next start (an embedding outage must not hold a release forever).
+ * An open MCP stream (GET /mcp) is not work, so a connected agent that is not calling anything leaves it at zero. It holds
+ * a count and a time, never a tool name, an argument or a tenant.
+ *
+ * With an IdleMonitor (RENOR_ON_DEMAND) tracked work is handed on to it unchanged, so the idle clock sees exactly what it
+ * saw before this existed.
+ */
+/** Marks the body of GET /internal/activity as this report, so a reader never mistakes another answer for it. */
+exports.ACTIVITY_REPORT_VERSION = 'activity/v1';
+exports.ACTIVITY_PATH = '/internal/activity';
+class ActivityGauge {
+    inner;
+    now;
+    background;
+    inFlight = 0;
+    lastEnded = null;
+    watched = new WeakSet();
+    constructor(inner = null, now = Date.now, 
+    /** The background jobs running now (the embedding rebuild, the background index); asked at every report. */
+    background = () => []) {
+        this.inner = inner;
+        this.now = now;
+        this.background = background;
+    }
+    /** Counts one unit of work from now until the returned function is called (once; further calls do nothing). */
+    begin() {
+        this.inFlight++;
+        let ended = false;
+        return () => {
+            if (ended)
+                return;
+            ended = true;
+            this.inFlight--;
+            this.lastEnded = this.now();
+        };
+    }
+    /** Counts a request until its response has finished or closed (an abort included). */
+    request(res) {
+        const end = this.begin();
+        res.once('close', end);
+    }
+    /** Same contract as IdleMonitor.track, so it stands in for the monitor wherever work is tracked. */
+    async track(work) {
+        const end = this.begin();
+        try {
+            return await (this.inner ? this.inner.track(work) : work());
+        }
+        finally {
+            end();
+        }
+    }
+    report() {
+        let jobs = 0;
+        for (const job of this.background()) {
+            if (!job)
+                continue;
+            // The moment a job ends is when the last work ended, whoever asks and whenever.
+            if (!this.watched.has(job.done)) {
+                this.watched.add(job.done);
+                void job.done.then(() => { this.lastEnded = this.now(); }, () => { this.lastEnded = this.now(); });
+            }
+            if (!job.waiting())
+                jobs++;
+        }
+        return {
+            renor: exports.ACTIVITY_REPORT_VERSION,
+            inFlight: this.inFlight + jobs,
+            lastEndedAgoMs: this.lastEnded === null ? null : Math.max(0, Math.floor(this.now() - this.lastEnded)),
+        };
+    }
+}
+exports.ActivityGauge = ActivityGauge;