renor-engine 0.0.0-stage → 1.0.0

package/dist/memory/confinedWrite.js

@@ -0,0 +1,315 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertHandleInside = assertHandleInside;
+exports.appendConfined = appendConfined;
+exports.createConfined = createConfined;
+exports.withConfinedFile = withConfinedFile;
+exports.writeConfined = writeConfined;
+exports.assertConfinedTarget = assertConfinedTarget;
+const promises_1 = __importDefault(require("fs/promises"));
+const fs_1 = require("fs");
+const path_1 = __importDefault(require("path"));
+const durableAppend_1 = require("./durableAppend");
+/**
+ * Writes into the vault that cannot be turned into a write somewhere else.
+ *
+ * The read side (memorymap's resolveVaultFile / ensureRealDir / openConfined) already refuses a symbolic link at any
+ * level. These helpers give the write side the same rule, for a vault someone else put files in (a cloned or shared
+ * notes repository, a synced folder, an archive): every directory between the vault's real root and the file is a real
+ * directory (a link is refused, never followed), the file itself is opened with O_NOFOLLOW and O_NONBLOCK (so a link is
+ * an error and a FIFO with no reader is an error, not a hang), and what was opened must be a regular file with one name
+ * (a hard link would write through to the file it shares). The vault root itself may be a link: it is where the user put
+ * their vault.
+ *
+ * The walk and the open are two steps, so a process that can write inside the vault could swap a directory for a link
+ * between them. After the open and before the first byte, `assertHandleInside` asks the kernel where the open file really
+ * is (/proc/self/fd/<fd>) and refuses unless that is under the vault's real root. Node has no openat2(RESOLVE_BENEATH) and
+ * /proc exists on Linux only; elsewhere that race stays open (engine/docs/self-hosting.md says so).
+ *
+ * Files are created 0600 and directories 0700: the vault holds the owner's statements in plain text.
+ *
+ * Durable as well (adv-crashsafe-1012 F1-F3): `appendConfined` is the one append for the daily log and the ledger. A write
+ * that fails part-way is cut back to the length the file had before the call, or removed when the call created it, so a
+ * caller told the save failed leaves no fragment; a successful write is fsynced before it returns, and so is the directory
+ * entry of a file it created. The cut and the append share one per-file lock (durableAppend.ts).
+ */
+function refusal(relFile, why) {
+    return new Error(`refusing to write ${JSON.stringify(relFile)}: ${why}`);
+}
+/** The vault-relative parts of `relFile`, refusing a path that is empty or leaves the vault. */
+function partsOf(relFile) {
+    const parts = relFile.split(/[\\/]/).filter(p => p && p !== '.');
+    const name = parts.pop();
+    if (!name || parts.includes('..') || name === '..' || path_1.default.isAbsolute(relFile)) {
+        throw refusal(relFile, 'it is not a path inside the vault');
+    }
+    return { dirs: parts, name };
+}
+/** The vault's real root; a vault that does not exist yet is created (the writers always did). */
+async function realRoot(vaultRoot) {
+    try {
+        return await promises_1.default.realpath(vaultRoot);
+    }
+    catch (err) {
+        if (err.code !== 'ENOENT')
+            throw err;
+        await promises_1.default.mkdir(vaultRoot, { recursive: true });
+        return promises_1.default.realpath(vaultRoot);
+    }
+}
+/**
+ * Walk the directories below the root, one lstat at a time. `create` makes a missing one (as `mkdir -p` did); without it a
+ * missing directory ends the walk with `null`.
+ */
+async function walkDirs(root, relFile, dirs, create) {
+    let dir = root;
+    for (const part of dirs) {
+        dir = path_1.default.join(dir, part);
+        let st;
+        try {
+            st = await promises_1.default.lstat(dir);
+        }
+        catch (err) {
+            if (err.code !== 'ENOENT')
+                throw err;
+            if (!create)
+                return null;
+            try {
+                await promises_1.default.mkdir(dir, { mode: 0o700 });
+            }
+            catch (e2) {
+                if (e2.code !== 'EEXIST')
+                    throw e2;
+            }
+            st = await promises_1.default.lstat(dir);
+        }
+        if (st.isSymbolicLink() || !st.isDirectory()) {
+            throw refusal(relFile, `${JSON.stringify(dirs.join('/'))} is a symbolic link or not a plain directory inside the vault`);
+        }
+    }
+    return dir;
+}
+/**
+ * Refuse an open file that is not under the vault's real root, whatever path was used to reach it. A directory swapped for
+ * a link after the walk makes the open land elsewhere; the kernel's own answer for the descriptor says where. Without
+ * /proc (not Linux) there is nothing to ask and the check passes: the residual is documented. A file this call just
+ * created outside is left where it landed, empty: a later step never removes it by name, because the name may by then
+ * resolve to some other file.
+ */
+async function assertHandleInside(handle, realVaultRoot, relFile) {
+    let where;
+    try {
+        where = await promises_1.default.readlink(`/proc/self/fd/${handle.fd}`);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === 'ENOENT' || code === 'ENOTDIR')
+            return;
+        throw err;
+    }
+    const rel = path_1.default.relative(realVaultRoot, where);
+    // '..safe' is a plain name below the root; only a '..' component leaves it.
+    if (rel === '' || rel === '..' || rel.startsWith(`..${path_1.default.sep}`) || path_1.default.isAbsolute(rel)) {
+        throw refusal(relFile, 'the file opened is outside the vault (a directory was replaced by a link while it was written)');
+    }
+}
+async function checkHandle(handle, root, relFile) {
+    await assertHandleInside(handle, root, relFile);
+    const st = await handle.stat();
+    if (!st.isFile() || st.nlink !== 1)
+        throw refusal(relFile, 'it is not a regular file with a single name');
+}
+/**
+ * Append to a vault file, creating it (and its directories) when absent. `header` goes in first, and only when this call
+ * created the file. Resolves once the bytes are on disk; rejects with the original error after undoing whatever landed.
+ * Returns the file's path.
+ */
+async function appendConfined(vaultRoot, relFile, content, header = '') {
+    const { dirs, name } = partsOf(relFile);
+    const root = await realRoot(vaultRoot);
+    const dir = (await walkDirs(root, relFile, dirs, true));
+    const file = path_1.default.join(dir, name);
+    const key = path_1.default.resolve(vaultRoot, relFile);
+    return (0, durableAppend_1.withAppendLock)(key, async () => {
+        const refused = (0, durableAppend_1.unrecoverableReason)(key);
+        if (refused)
+            throw refusal(relFile, `it holds the bytes of a failed write that could not be cut back (${refused}); refusing further appends until the engine restarts, which sets that tail aside`);
+        const OPEN = fs_1.constants.O_WRONLY | fs_1.constants.O_APPEND | fs_1.constants.O_NOFOLLOW | fs_1.constants.O_NONBLOCK;
+        let handle;
+        let created = false;
+        try {
+            // O_EXCL does not follow a link at the final component: a link there, dangling or not, is EEXIST.
+            handle = await promises_1.default.open(file, OPEN | fs_1.constants.O_CREAT | fs_1.constants.O_EXCL, 0o600);
+            created = true;
+        }
+        catch (err) {
+            if (err.code !== 'EEXIST')
+                throw err;
+            try {
+                handle = await promises_1.default.open(file, OPEN);
+            }
+            catch (e2) {
+                const code = e2.code;
+                if (code === 'ELOOP' || code === 'ENXIO')
+                    throw refusal(relFile, 'it is a symbolic link or not a regular file');
+                throw e2;
+            }
+        }
+        let before = null;
+        let inside = false;
+        let failure = null;
+        try {
+            await assertHandleInside(handle, root, relFile);
+            inside = true;
+            await checkHandle(handle, root, relFile);
+            before = (await handle.stat()).size;
+            await handle.appendFile(created ? header + content : content, 'utf8');
+            await handle.sync();
+            if (created)
+                await (0, durableAppend_1.syncDirectory)(dir);
+        }
+        catch (error) {
+            failure = { error };
+            // Cut the partial bytes back. Only a known length is ever truncated to: a failed stat must not be read as zero.
+            if (!created && before !== null) {
+                await handle.truncate(before).then(() => handle.sync()).catch((cutError) => {
+                    (0, durableAppend_1.markUnrecoverable)(key, cutError instanceof Error ? cutError.message : String(cutError));
+                });
+            }
+        }
+        finally {
+            await handle.close().catch(() => undefined);
+        }
+        if (failure) {
+            // Removed by name only when the open landed inside the vault (adv-crashsafe-1012 review P3-3): when it did not, the
+            // name may now resolve to some other file, so the empty file this call made stays where it landed.
+            if (created && inside)
+                await promises_1.default.rm(file, { force: true }).catch(() => undefined);
+            throw failure.error;
+        }
+        return file;
+    });
+}
+/**
+ * Create a new vault file, durably: `content` is synced and so is the directory entry. It never replaces anything: a name
+ * that is taken (a file, or a link at it, dangling or not) fails with EEXIST, and the caller picks another name.
+ * Confined like every other write here. Returns the file's path.
+ */
+async function createConfined(vaultRoot, relFile, content) {
+    const { dirs, name } = partsOf(relFile);
+    const root = await realRoot(vaultRoot);
+    const dir = (await walkDirs(root, relFile, dirs, true));
+    const file = path_1.default.join(dir, name);
+    const handle = await promises_1.default.open(file, fs_1.constants.O_WRONLY | fs_1.constants.O_CREAT | fs_1.constants.O_EXCL | fs_1.constants.O_NOFOLLOW | fs_1.constants.O_NONBLOCK, 0o600);
+    let inside = false;
+    let failure = null;
+    try {
+        await assertHandleInside(handle, root, relFile);
+        inside = true;
+        await checkHandle(handle, root, relFile);
+        await handle.writeFile(content, 'utf8');
+        await handle.sync();
+        await (0, durableAppend_1.syncDirectory)(dir);
+    }
+    catch (error) {
+        failure = { error };
+    }
+    finally {
+        await handle.close().catch(() => undefined);
+    }
+    if (failure) {
+        if (inside)
+            await promises_1.default.rm(file, { force: true }).catch(() => undefined);
+        throw failure.error;
+    }
+    return file;
+}
+/**
+ * Runs `fn` with an open handle on an existing vault file, opened the way a confined write opens it: the directories on
+ * the way are real, the file is opened with O_NOFOLLOW and O_NONBLOCK, and what was opened must be a regular file with one
+ * name inside the vault. The handle is read and written by `fn`, and closed after it.
+ */
+async function withConfinedFile(vaultRoot, relFile, fn) {
+    const { dirs, name } = partsOf(relFile);
+    const root = await realRoot(vaultRoot);
+    const dir = await walkDirs(root, relFile, dirs, false);
+    if (dir === null)
+        throw Object.assign(new Error(`ENOENT: no such file or directory, ${relFile}`), { code: 'ENOENT' });
+    let handle;
+    try {
+        handle = await promises_1.default.open(path_1.default.join(dir, name), fs_1.constants.O_RDWR | fs_1.constants.O_NOFOLLOW | fs_1.constants.O_NONBLOCK);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === 'ELOOP' || code === 'ENXIO')
+            throw refusal(relFile, 'it is a symbolic link or not a regular file');
+        throw err;
+    }
+    try {
+        await checkHandle(handle, root, relFile);
+        return await fn(handle);
+    }
+    finally {
+        await handle.close().catch(() => undefined);
+    }
+}
+/** Create a vault file, or replace the content of the regular file already there. Returns the file's path. */
+async function writeConfined(vaultRoot, relFile, content) {
+    const { dirs, name } = partsOf(relFile);
+    const root = await realRoot(vaultRoot);
+    const dir = (await walkDirs(root, relFile, dirs, true));
+    const file = path_1.default.join(dir, name);
+    let handle;
+    try {
+        // No O_TRUNC: the file is only emptied once it is known to be a regular file with a single name.
+        handle = await promises_1.default.open(file, fs_1.constants.O_WRONLY | fs_1.constants.O_CREAT | fs_1.constants.O_NOFOLLOW | fs_1.constants.O_NONBLOCK, 0o600);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === 'ELOOP' || code === 'ENXIO')
+            throw refusal(relFile, 'it is a symbolic link or not a regular file');
+        throw err;
+    }
+    try {
+        await checkHandle(handle, root, relFile);
+        await handle.truncate(0);
+        await handle.writeFile(content, 'utf8');
+    }
+    finally {
+        await handle.close().catch(() => undefined);
+    }
+    return file;
+}
+/**
+ * Refuse, before anything is read or written, a vault file that a confined write would refuse: a link or a directory on
+ * the way, or an existing file that is not a regular file with one name. An absent file or directory is fine.
+ */
+async function assertConfinedTarget(vaultRoot, relFile) {
+    const { dirs, name } = partsOf(relFile);
+    let root;
+    try {
+        root = await promises_1.default.realpath(vaultRoot);
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return;
+        throw err;
+    }
+    const dir = await walkDirs(root, relFile, dirs, false);
+    if (dir === null)
+        return;
+    let st;
+    try {
+        st = await promises_1.default.lstat(path_1.default.join(dir, name));
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return;
+        throw err;
+    }
+    if (!st.isFile() || st.nlink !== 1)
+        throw refusal(relFile, 'it is a symbolic link or not a regular file with a single name');
+}

package/dist/memory/controls.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.unstorableControls = unstorableControls;
+exports.assertNoUnstorableControls = assertNoUnstorableControls;
+const toolRefusal_1 = require("../toolRefusal");
+/**
+ * The control characters a stored memory cannot keep.
+ *
+ * A memory is text that is read back verbatim — by an agent, by a log, by an editor, by a script that
+ * splits on lines — so anything that is not printable text is REFUSED rather than written. The sharp
+ * case is NUL (U+0000): both the filesystem and SQLite accept it, so a note carrying one is written,
+ * indexed and served as though it were ordinary text, while every C-string boundary in a downstream
+ * reader ends the line early. The rest of the class is the same argument: ESC and the other C0
+ * controls carry no words, arrive by accident (a binary blob pasted as a note) or on purpose (a
+ * terminal escape sequence that rewrites what a transcript shows), and are invisible in a diff.
+ *
+ * The set is the one this engine already uses for its structured fields (lifecycle.ts CONTROL_CHARS,
+ * importing/facts.ts CONTROL_CHARS): every C0 control and DEL. Three are kept, because they are
+ * whitespace a note legitimately holds:
+ *
+ *   TAB (U+0009), LF (U+000A) and CR (U+000D) — the carriage return of a Windows line ending. The
+ *   chunker already splits a daily note on all three, and an entry a Windows user pastes arrives
+ *   CRLF-terminated, so refusing CR would refuse real memories to fix none. VT and FF (U+000B,
+ *   U+000C) are kept out: they are not the whitespace anyone types.
+ *
+ * Where this rule does NOT apply, and why:
+ *
+ *   - The ledger's `statement` field (memory/lifecycle.ts). It is written as ONE JSON string literal,
+ *     which escapes every C0 control, so a statement keeps any character sequence without being able
+ *     to break the ledger's framing — the property src/memory/statement-encoding.test.ts proves with
+ *     a NUL, 4000 NULs, forged heading lines and JSON that tries to close the string. Refusing there
+ *     would also make a ledger written by an earlier build un-replayable-by-resent (that test loads a
+ *     literal separator and expects the same words to be a nochange resend).
+ *   - The structured lifecycle fields (subject, predicate, object, source) in the same file: they
+ *     already refuse this same set, and tab/newline too, because the ledger framing needs it.
+ *   - REPLY text. Nothing stored is rewritten, and what a reader sees is made safe on the way out:
+ *     escapeInvisibleControls (mvp/sanitize.ts) renders every C0 control, C1 control and format
+ *     character as a `\uXXXX` escape in every JSON reply, so a stored value never applies a hidden
+ *     character to a transcript while the archive keeps every character.
+ *
+ * One rule for every path that stores text RAW — the daily note, an imported Markdown note, a request
+ * another agent reads — so the answer is the same whichever write tool the caller used.
+ */
+// An unpaired surrogate is refused too: SQLite and the files keep it as CESU-style bytes, and every reader
+// shows it as three replacement characters. A valid pair is one code point, so emoji are not matched.
+const UNSTORABLE_CONTROL = /[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F]|\p{Cs}/gu;
+/** The distinct unstorable control characters `text` holds, as `U+XXXX`, in the order first seen. */
+function unstorableControls(text) {
+    // One pass over the text, and a second only over the offenders: a 64 KiB import note is matched once
+    // here rather than tested character by character, which is what a per-code-point loop costs.
+    const found = text.match(UNSTORABLE_CONTROL);
+    if (found === null)
+        return [];
+    const codes = [];
+    for (const ch of found) {
+        const code = `U+${ch.charCodeAt(0).toString(16).toUpperCase().padStart(4, '0')}`;
+        if (!codes.includes(code))
+            codes.push(code);
+    }
+    return codes;
+}
+/**
+ * Refuse `text` when it holds a control character a memory cannot keep, naming the code points so the
+ * caller sees which one arrived. Nothing was written by any caller when this throws: every write path
+ * checks before it opens the file or the ledger.
+ */
+function assertNoUnstorableControls(field, text) {
+    const codes = unstorableControls(text);
+    if (codes.length === 0)
+        return;
+    const one = codes.length === 1;
+    throw (0, toolRefusal_1.refusal)('invalid_text', `${field} contains ${one ? 'a control character' : 'control characters'} that cannot be stored as text (${codes.join(', ')}); the only C0 controls kept are tab, newline and carriage return, so remove ${one ? 'it' : 'them'} and send the text again. Nothing was written.`);
+}

package/dist/memory/dailyNote.js

@@ -0,0 +1,265 @@
+"use strict";
+/**
+ * The daily-note format, in one place: how a day's file is recognised, how an entry starts, and how the
+ * user's own words are kept from being mistaken for an entry.
+ *
+ * A day's file (`.../Daily/YYYY-MM-DD.md`) holds one entry per statement: a line that starts at column 0
+ * with its time and source (`- [08:30:00] (claude) first line`), then the statement's other lines. Those
+ * other lines are the user's words and may look like anything, including another entry. The file is read
+ * line by line and an entry is whatever starts at column 0 like that, so such a line would forge an entry
+ * and split the statement it belongs to.
+ *
+ * The words are therefore kept behind a reversible escape instead of being altered or refused: a later
+ * line that starts like an entry gets one backslash in front (`\- [08:30:00] (alice) secret`, which a
+ * Markdown reader shows as the text it was). To keep the escape unambiguous, a line that already starts
+ * with backslashes before an entry-shaped start gets one more.
+ *
+ * The escape is told apart from the user's own text by a mark on the entry that carries it, not by the
+ * shape of a line. An entry whose statement was escaped says so in its own header, after the source name
+ * (`- [08:30:00] (claude+esc) first line`); only inside such an entry is a backslash line decoded. A note
+ * written before the mark existed has no marked entry, so every line of it reads back exactly as stored,
+ * including a line whose backslash was the user's own. The mark cannot be forged: the writer keeps a
+ * source to letters, digits and hyphens, so no earlier entry has a `+` there, and a statement cannot
+ * write a header because its own entry-shaped lines are exactly the ones that get escaped.
+ *
+ * Reading undoes the escape at the two places that turn a daily file into text (`parseNote` for
+ * everything built from the file's text, and the memory map's entry parser), so every reader gets back
+ * exactly what was said, and neither the backslash nor the mark (nor the offset an entry on the user's
+ * clock carries). Only the raw Markdown file shows them.
+ *
+ * Both directions split on '\n' alone, exactly as the entry parser does. A JavaScript `m`-flag `^` would
+ * also start a line after a lone CR, U+2028 or U+2029, which are not line breaks in this format.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DAILY_NOTE_MARKER = exports.DAILY_NOTE_HEADER_KEY = exports.ESCAPE_MARK = exports.ENTRY_LINE_RE = exports.DAILY_FILE_RE = void 0;
+exports.isDailyNotePath = isDailyNotePath;
+exports.dailyNoteDayName = dailyNoteDayName;
+exports.engineDailyHeader = engineDailyHeader;
+exports.isEngineDailyNote = isEngineDailyNote;
+exports.isEmptyEngineDailyNote = isEmptyEngineDailyNote;
+exports.isEngineHeaderDate = isEngineHeaderDate;
+exports.isEarlierHeaderText = isEarlierHeaderText;
+exports.parseEntryHeader = parseEntryHeader;
+exports.entryInstant = entryInstant;
+exports.encodeEntryText = encodeEntryText;
+exports.decodeEntryLine = decodeEntryLine;
+exports.formatEntry = formatEntry;
+exports.decodeDailyNoteText = decodeDailyNoteText;
+/**
+ * A daily note: `.../Daily/YYYY-MM-DD.md`. Group 2 is the date.
+ *
+ * A path under the import namespace (`Imported/<label>/…`) is never a daily note, whatever it is called: the
+ * import tool writes untrusted source files as ordinary notes (`Imported/`, importing/hosted.ts), so a source
+ * folder called `Daily/` must not turn an imported file into the engine's own daily log. Without this, a file
+ * imported at `Daily/YYYY-MM-DD.md` was read as a daily log: its `- [HH:MM:SS] (source) text` lines became
+ * entries attributed to a source the importer chose, and a prose file there vanished from memory_map and the
+ * export. The engine's own daily logs live under `Memory/Daily/` or `Memory/Scopes/<slug>/Daily/`, never under
+ * `Imported/`.
+ */
+exports.DAILY_FILE_RE = /^(?!Imported\/)(?:(.*)\/)?Daily\/(\d{4}-\d{2}-\d{2})\.md$/;
+/**
+ * An entry's first line is everything after its prefix, and lines are split on '\n' alone. dotAll, because
+ * `.` otherwise refuses U+2028, U+2029 and a lone \r in the text, and an entry whose first line holds one of
+ * them stopped being an entry: it was folded into the one above it, so retiring that neighbour took it too.
+ */
+exports.ENTRY_LINE_RE = /^- \[(\d{2}:\d{2}:\d{2})\] \(([^)]*)\) (.*)$/s;
+/** Follows the source name in the header of an entry whose statement carries the escape. */
+exports.ESCAPE_MARK = '+esc';
+/**
+ * Follows the source name in the header of an entry stamped on the user's own clock rather than in UTC: that clock's
+ * offset from UTC (`- [21:00:01] (cursor, UTC-03:00) ...`). The entry's day and time are then the user's, and the
+ * offset keeps the moment exact. An entry without it was stamped in UTC, as every entry was before it existed. A
+ * source is kept to letters, digits and hyphens, so no source name can write it; it comes before the escape mark,
+ * so a release that does not know it still finds the escape. Like the escape mark it is the file's, not the
+ * reader's: readers get the user's day and time without it (so it is never searched for, nor paid for in tokens),
+ * and the memory map reads it from the file for the exact moment.
+ */
+const OFFSET_MARK_RE = /, UTC([+-]\d{2}:\d{2})$/;
+const offsetMark = (offset) => (offset ? `, UTC${offset}` : '');
+/** A line that starts like an entry (whatever follows the parenthesis), behind any number of backslashes. */
+const ENTRY_SHAPED = /^\\*- \[\d{2}:\d{2}:\d{2}\] \(/;
+/** The same, with at least one backslash: a line the writer escaped. */
+const ESCAPED_ENTRY_SHAPED = /^\\+- \[\d{2}:\d{2}:\d{2}\] \(/;
+/** Is this file one of the engine's daily notes? Separators are normalised so a Windows path matches too. */
+function isDailyNotePath(filePath) {
+    return exports.DAILY_FILE_RE.test(filePath.replace(/\\/g, '/'));
+}
+/**
+ * The front-matter key the engine writes into every daily note it creates (`updated: YYYY-MM-DD`, in writer.ts and
+ * where the memory map restores an entry into a day that has no file). It is the day the file is about.
+ */
+exports.DAILY_NOTE_HEADER_KEY = 'updated';
+/** The day a daily note's own name gives (`.../Daily/2026-10-03.md` is `2026-10-03`), or null when the path is no daily note or the name is no real day. */
+function dailyNoteDayName(filePath) {
+    const match = exports.DAILY_FILE_RE.exec(filePath.replace(/\\/g, '/'));
+    if (!match)
+        return null;
+    const at = Date.parse(`${match[2]}T00:00:00Z`);
+    // `2026-02-31` parses (as March 3rd): only a name that survives the round trip is a day.
+    return !Number.isNaN(at) && new Date(at).toISOString().slice(0, 10) === match[2] ? match[2] : null;
+}
+/**
+ * The line the engine writes into the front matter of every daily note it creates. It is how a note the engine wrote is
+ * told from a person's note in the same folder: not by where the note is, what it is called or what it says (a person
+ * writes `updated: 2026-03-30` and timestamped lines too), but by a stamp that nothing but the engine's writers puts
+ * there; a person would have to copy it on purpose. Bump the version, never the key, if the layout changes.
+ */
+exports.DAILY_NOTE_MARKER = 'renor: daily-v1';
+/**
+ * What the engine writes at the top of every daily note it creates (writer.ts, one write with the first entry after it,
+ * and the memory map when it restores an entry into a day that has no file): its `kind: note`, the day as a bare YAML
+ * date, the marker, and the heading. A test pins both writers to this function.
+ *
+ * Before the marker existed the engine wrote the same without its line, and those notes are still on disk (see
+ * `isEngineDailyNote`).
+ */
+function engineDailyHeader(day) {
+    return `---\nkind: note\nupdated: ${day}\n${exports.DAILY_NOTE_MARKER}\n---\n# ${day}\n`;
+}
+/** The text between the fences of the front matter that opens `head`, or null when it does not open with one that closes in it. */
+function frontMatterBlock(head) {
+    if (!head.startsWith('---\n'))
+        return null;
+    const end = head.indexOf('\n---\n', 3);
+    return end === -1 ? null : head.slice(4, Math.max(4, end));
+}
+/**
+ * Did the engine write this daily note? One rule, over the front matter alone, never the body (a person can write
+ * anything in the body, timestamped lines in the engine's own format included). The note must be in the daily layout
+ * with a real day for its name, and then:
+ *
+ *  - a note the engine has written since it stamps its notes carries the marker line, `renor: daily-v1`, in its front
+ *    matter;
+ *  - a note written before that has none, and is told only by being the complete front matter the engine then wrote,
+ *    every key, value and its order and nothing else in it: `kind: note`, then `updated:` with the day of the note's own
+ *    name (the engine wrote nothing else, so nothing else matches).
+ *
+ * A note that is neither keeps what it says: a natural `updated: 2026-03-30`, a further or reordered key, a quoted date,
+ * another day, a marker-less note anywhere else, a marker in the body. What this cannot do is tell an old note of the
+ * engine's from a person's note that copies its two lines exactly, or one that copies the marker: they are the same
+ * bytes. That is why the answer is about the note and the fact dropped is narrower (`isEngineHeaderDate`).
+ *
+ * `head` is the start of the file (the front matter is a few dozen bytes; a front matter that does not close in `head`
+ * is not the engine's).
+ */
+function isEngineDailyNote(filePath, head) {
+    const day = dailyNoteDayName(filePath);
+    const block = day === null ? null : frontMatterBlock(head);
+    if (day === null || block === null)
+        return false;
+    return block.split('\n').includes(exports.DAILY_NOTE_MARKER) || block === `kind: note\nupdated: ${day}`;
+}
+/**
+ * Does this daily note hold nothing but what the engine wrote at its top: its own front matter (`isEngineDailyNote`), the
+ * heading of its day, and blank lines? That is what is left of a day whose last entry was retired, and none of it is
+ * anyone's memory. A line a person wrote anywhere in it, or a front matter that is theirs, makes it a note that holds
+ * something.
+ */
+function isEmptyEngineDailyNote(filePath, content) {
+    const day = dailyNoteDayName(filePath);
+    if (day === null || !isEngineDailyNote(filePath, content))
+        return false;
+    const body = content.slice(content.indexOf('\n---\n', 3) + '\n---\n'.length);
+    return body.split('\n').every(line => line === `# ${day}` || /^[ \t\r]*$/.test(line));
+}
+/**
+ * Is this front-matter value the engine's own `updated`: the bare date of the note's own day, which YAML reads as that
+ * day's midnight (UTC)? In a note the engine wrote that is the only value of `updated` that is bookkeeping. A person's
+ * own value in it (a plugin that stamps the time it was saved, another day, a quoted date) is theirs and is kept.
+ */
+function isEngineHeaderDate(filePath, value) {
+    const day = dailyNoteDayName(filePath);
+    return day !== null && value instanceof Date && value.getTime() === Date.parse(`${day}T00:00:00Z`);
+}
+/** What `Date.prototype.toString` prints: the Date a bare YAML date becomes, in the timezone of the host that printed it. */
+const DATE_TO_STRING_RE = /^(Mon|Tue|Wed|Thu|Fri|Sat|Sun) (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) \d{2} \d{4} \d{2}:\d{2}:\d{2} GMT[+-]\d{4}(?: \(.+\))?$/;
+/**
+ * Is this the text an earlier indexer stored as the "fact" `updated` of a daily note's header: the Date of the note's
+ * own day, printed in the timezone of the host that indexed it (any zone: it is read back to the day)? It says what the
+ * row looks like; whether the note is the engine's is `isEngineDailyNote`'s to say.
+ */
+function isEarlierHeaderText(filePath, text) {
+    const day = dailyNoteDayName(filePath);
+    return day !== null && typeof text === 'string' && DATE_TO_STRING_RE.test(text) && Date.parse(text) === Date.parse(`${day}T00:00:00Z`);
+}
+/** The parts of an entry's first line, or null when the line does not start an entry. */
+function parseEntryHeader(line) {
+    if (!line.startsWith('- ['))
+        return null; // most lines of a note: skip the regex
+    const m = exports.ENTRY_LINE_RE.exec(line);
+    if (!m)
+        return null;
+    const escaped = m[2].endsWith(exports.ESCAPE_MARK);
+    const named = escaped ? m[2].slice(0, -exports.ESCAPE_MARK.length) : m[2];
+    const clock = OFFSET_MARK_RE.exec(named);
+    return {
+        time: m[1],
+        source: clock ? named.slice(0, clock.index) : named,
+        ...(clock ? { offset: clock[1] } : {}),
+        escaped,
+        text: m[3],
+    };
+}
+/**
+ * When an entry was saved, as an ISO instant: the day of its file and the time of its header, on the clock the header
+ * names (UTC when it names none, exactly as before offsets existed). An offset that makes no real time, which only a
+ * hand edit can write, is read as UTC too.
+ */
+function entryInstant(day, header) {
+    const utc = `${day}T${header.time}.000Z`;
+    if (!header.offset)
+        return utc;
+    const at = Date.parse(`${day}T${header.time}${header.offset}`);
+    return Number.isNaN(at) ? utc : new Date(at).toISOString();
+}
+/**
+ * A statement as it is written into an entry. The first line follows the entry's prefix, so it is never at
+ * column 0; only the later lines can start like an entry and need the escape. `escaped` says whether any
+ * did, which is what the entry's header must then record.
+ */
+function encodeEntryText(text) {
+    const lines = text.split('\n');
+    let escaped = false;
+    for (let i = 1; i < lines.length; i++) {
+        if (ENTRY_SHAPED.test(lines[i])) {
+            lines[i] = `\\${lines[i]}`;
+            escaped = true;
+        }
+    }
+    return { text: lines.join('\n'), escaped };
+}
+/** The inverse of the escape for one line of an escaped entry. */
+function decodeEntryLine(line) {
+    return ESCAPED_ENTRY_SHAPED.test(line) ? line.slice(1) : line;
+}
+/**
+ * One entry exactly as the writer stores it (without the line break that separates entries). `escape` is
+ * false for a file that is not in the daily-note layout, which is written as said. `offset` is given when
+ * `time` is on the user's clock rather than UTC.
+ */
+function formatEntry(time, source, text, escape = true, offset) {
+    const body = escape ? encodeEntryText(text) : { text, escaped: false };
+    return `- [${time}] (${source}${offsetMark(offset)}${body.escaped ? exports.ESCAPE_MARK : ''}) ${body.text}`;
+}
+/**
+ * The inverse for the text of a whole daily note: inside each marked entry every escaped line gets its
+ * words back, and the header loses the mark; a header loses its offset too. An entry with neither is left
+ * exactly as stored, and so is everything before the first entry. Applying it twice changes nothing more,
+ * because the first pass removes the marks.
+ */
+function decodeDailyNoteText(content) {
+    const lines = content.split('\n');
+    let inEscapedEntry = false;
+    for (let i = 0; i < lines.length; i++) {
+        const header = parseEntryHeader(lines[i]);
+        if (header) {
+            inEscapedEntry = header.escaped;
+            if (header.escaped || header.offset)
+                lines[i] = `- [${header.time}] (${header.source}) ${header.text}`;
+        }
+        else if (inEscapedEntry) {
+            lines[i] = decodeEntryLine(lines[i]);
+        }
+    }
+    return lines.join('\n');
+}