bantamkit-mcp 0.26.0

package/dist/memory/store.d.ts

@@ -0,0 +1,478 @@
+import { BantamError } from '../errors.js';
+import type { Fact, FactValue } from './factfile.js';
+export type { Fact } from './factfile.js';
+/** `sorted(VALID_TYPES)` is what the error message interpolates, so the order is load-bearing. */
+export declare const VALID_TYPES: readonly ["feedback", "project", "reference", "user"];
+/**
+ * `DURABLE_TYPES` — the types whose worth does NOT decay with time-since-last-recall, and
+ * which `compact` therefore archives only after every other candidate is exhausted
+ * (`byEviction`).
+ *
+ * An ARRAY walked with one `pyEqualValue` per entry, never a `Set`: this is compared
+ * against a value that came out of YAML uncast, and Python's `in` on a tuple is `==` per
+ * element where `in` on a set hashes and raises on a `list`. `runtime-py`'s
+ * `store.DURABLE_TYPES`.
+ */
+export declare const DURABLE_TYPES: readonly ["feedback", "user"];
+export declare const DUPLICATE_JACCARD = 0.5;
+/** See the reference's comment: measured against a real store, not chosen. */
+export declare const DEFAULT_INDEX_BUDGET = 24000;
+export declare class MemoryValidationError extends BantamError {
+}
+export declare class MemoryBudgetExceeded extends BantamError {
+}
+export interface SaveResult {
+    status: 'saved' | 'duplicate';
+    name: string;
+    /** `SaveResult.similar` is the OTHER fact's `name` field, verbatim — see `pyText`. */
+    similar: FactValue;
+}
+/** What one archived fact WAS, kept after its file has left `facts/`. */
+export interface ArchivedFact {
+    name: FactValue;
+    type: FactValue;
+    description: FactValue;
+    indexBytes: number;
+    lastRecalled: FactValue | null;
+    created: FactValue | null;
+}
+/**
+ * Everything the caller needs to understand what compaction cost.
+ *
+ * Archiving is a one-way MOVE, not a delete: the file is still readable under `archive/` and
+ * `restore()` brings it back. This carries the description of each fact that left, so a
+ * caller that never looks in `archive/` can still say what it lost, and the byte arithmetic
+ * so it can see the headroom it bought. `headroom` is a `@property` in the reference and a
+ * plain field here — the value is the same and nothing mutates the result.
+ */
+export interface CompactResult {
+    archived: ArchivedFact[];
+    indexBefore: number;
+    indexAfter: number;
+    budget: number;
+    target: number;
+    reserve: number;
+    headroom: number;
+    archiveDir: string;
+}
+export interface MemoryStoreOptions {
+    indexBudget?: number;
+    k?: number;
+    today?: () => string;
+    create?: boolean;
+}
+/**
+ * `set(re.findall(r"[a-z0-9]+", text.lower()))`.
+ *
+ * ASCII-only, no casefold and no Unicode normalization — so a wholly non-ASCII name and
+ * description produce the EMPTY set in both runtimes. That is not a defect to fix in a
+ * port; it is the behaviour the duplicate gate is built on, and `_jaccard` below is where
+ * it stops being a division by zero.
+ */
+export declare function tokens(text: string): Set<string>;
+/**
+ * `len(a & b) / len(a | b)`, except that an empty side is 0.0 and never a division.
+ *
+ * Python decided this and Python's answer is the one that ships: two facts whose tokens are
+ * both empty score 0.0, so they are NOT duplicates of each other and both save. A port that
+ * "fixed" it to 1.0 for two empty sets would refuse the second of two Thai descriptions.
+ */
+export declare function jaccard(a: Set<string>, b: Set<string>): number;
+/**
+ * Python's `f"{value}"` for the values a hand-edited frontmatter can put in a `str` field.
+ *
+ * `_facts` does no type check: `meta["name"]` is whatever the YAML resolved to, and the
+ * store then interpolates it into the index line, the token text and the FILE PATH. For
+ * `None` Python writes `None` and JS would write `null` — a different index line and a
+ * different file on disk from the same store. Only `null` is reproduced; see the ruling in
+ * `tools/conformance/suites/store.mjs` for the sequence case, which is left differing.
+ *
+ * Exported for `component._format`, which interpolates the same three fields into the line a
+ * model reads. Two spellings of one coercion is how the index line and the recall line would
+ * come to print a different name for the same fact.
+ */
+export declare function pyText(value: unknown): string;
+/**
+ * `hash`/`==` equivalence for the values a `Fact.name` can hold — the key `Memory.recall`'s
+ * `seen` set uses across layers.
+ *
+ * `pyText` is the WRONG key here and the difference is observable: a fact named `7` in the
+ * project layer and one named `'7'` in the profile layer are two different keys to Python
+ * and would collapse into one under `str`. The other direction is just as real — Python's
+ * numeric tower makes `7`, `7.0` and `True` all equal and all one key — so a key built from
+ * the JS type would drop a dedupe Python performs. This spells out both.
+ *
+ * Dates are keyed by their type as well as their text: `date(2026, 8, 23)` and the
+ * `datetime` at midnight of the same day are NOT equal in Python.
+ */
+export declare function pyHashKey(value: FactValue): string;
+/**
+ * `a == b` over the same values — the OTHER half of the tuple comparison, and not a
+ * rephrasing of `<`.
+ *
+ * `tuplerichcompare` walks the key tuple with `==` and calls `<` only on the first element
+ * where `==` answers False. That is what keeps `sorted` from raising on two facts both named
+ * `None`: `None == None` is True, the tuples are equal, and `None < None` — which DOES raise
+ * — is never reached. Measured: without this the port raised `'NoneType' and 'NoneType'`
+ * where CPython answered an order.
+ *
+ * `==` never raises. Across types it is simply False — `7 == 'a'`, a `date` against a
+ * `datetime`, a naive `datetime` against an aware one — while `<` on the same pairs raises.
+ * Inside the numeric family it is Python's: `True == 1`, `7 == 7.0`, and `nan == nan` is
+ * False, which is why NaN is not special-cased anywhere here.
+ */
+export declare function pyEqualValue(a: FactValue, b: FactValue): boolean;
+export declare function pyCompareLt(a: FactValue, b: FactValue): boolean;
+/**
+ * `sorted(scored, key=lambda pair: (-pair[0], pair[1].name))`, comparison for comparison.
+ *
+ * RULING — WHY THE SORT IS SPELLED OUT AND NOT HANDED TO `Array.prototype.sort`. When every
+ * name is a `str` the two agree and this takes the fast path. When they are not, the sort
+ * can RAISE, and then WHICH pair CPython happens to compare first decides the sentence a
+ * model reads: `'int' and 'str'` or `'str' and 'int'`, and with three numeric types in play,
+ * which of `int`/`float`/`bool` gets named. `Array.prototype.sort`'s comparison order is
+ * unspecified and V8's is not Timsort's.
+ *
+ * So the slow path is CPython's `listsort` for a single run: `count_run` (adjacent
+ * `a[i] < a[i-1]`, reversing a strictly descending prefix) then `binarysort` (pivot on the
+ * LEFT of every probe, midpoint `l + ((r - l) >> 1)`), over key tuples compared by
+ * `tuplerichcompare` — `==` down the tuple and `<` only where `==` says they differ.
+ *
+ * MEASURED, and re-measured on every conformance run: the `recall tie-break` case in
+ * `tools/conformance/suites/store.mjs` generates 50,000 `(score, name)` lists from a seeded
+ * LCG — ten name spellings across all four families, n from 2 to 300 — and runs each through
+ * CPython's `sorted` and through this function. 45,629 of them raise. All 50,000 agree, on
+ * the order where there is one and on the TypeError text where there is not.
+ *
+ * TWO MODELS THIS REFUTED, kept because each looks right until it is run. (1) "raise if any
+ * equal-score pair is incomparable" gets the DECISION right — 20,000 of 20,000 in the
+ * derivation probe — and the SENTENCE wrong in 1,087 of 30,000, because the types it names
+ * are whichever pair the binary search actually probed. (2) Calling `<` wherever the scores
+ * tie raises `'NoneType' and 'NoneType'` for two facts both named `None`, where CPython
+ * answers an order: `==` short-circuits the tuple before `<` is ever reached.
+ *
+ * NOT MEASURED, and the honest edge: past 64 elements CPython splits the list into runs and
+ * merges them, while this binary-inserts the whole list. It can only matter if the FIRST
+ * incomparable pair lies past the first run, and the 8,000 generated lists with n between 65
+ * and 300 produced no such case. A store would need 65+ facts tied on one recall score with
+ * the type change late in the file order.
+ */
+export declare function sortScored<T extends {
+    score: number;
+    name: FactValue;
+}>(scored: readonly T[]): T[];
+export declare class MemoryStore {
+    readonly root: string;
+    readonly indexBudget: number;
+    readonly k: number;
+    private readonly today;
+    constructor(root: string, options?: MemoryStoreOptions);
+    private ensureDirs;
+    /**
+     * Write a fact, or refuse it as a near-duplicate of one already here.
+     *
+     * THE FIRST OF TWO READS IS WHAT MAKES THIS SAFE, and the ordering is the reference's, not
+     * an implementation detail: `_facts()` runs for the duplicate check BEFORE `_writeFact`,
+     * so an unreadable store fails the whole op with nothing written and nothing to roll back.
+     * The measured alternative, one directory over in job37: a blind listing let the duplicate
+     * check pass vacuously, the fact landed, and `_rebuildIndex` then wrote a 13,472-byte
+     * index down to zero from the same empty listing.
+     */
+    save(type: string, name: string, description: string, body: string, links?: readonly string[]): SaveResult;
+    /**
+     * Top-`k` facts whose name+description share tokens with `query`.
+     *
+     * An unreadable store raises out of `facts()` rather than scoring zero facts and returning
+     * `[]` — the same answer as a real miss, which `component.Memory` used to turn into "no
+     * memories matched. Try different words", telling a person to rephrase a question at a
+     * filing cabinet nobody could open.
+     */
+    recall(query: string, k?: number | null, stamp?: boolean): Fact[];
+    /**
+     * `len(store._facts())` at the operator CLI, which is the only caller.
+     *
+     * `facts()` stays private: this hands out a COUNT, not the parsed list, so no caller
+     * outside this file can hold a fact array and drift from what is on disk. It is a full
+     * parse — an unreadable or malformed store raises here rather than counting 0, which is
+     * the same rule `indexText` holds and for the same reason.
+     */
+    factCount(): number;
+    /**
+     * Every fact parses and carries a valid type, and the index fits its budget.
+     *
+     * The raise on an unreadable store is the reference's and it is load-bearing: a checker
+     * that passes hardest on the store it could not open is worse than no checker. `_facts()`
+     * raises before the type sweep starts, and `_cmd_lint` in `memory/cli.ts` routes both that
+     * and the budget error to `lint: FAIL — …` on stderr with exit 1.
+     */
+    lint(): void;
+    /**
+     * Archive the stalest facts until the index sits at `budget - reserve` or below.
+     *
+     * THE TARGET IS BELOW THE BUDGET ON PURPOSE, and the reference's docstring records why:
+     * `save` rolls its fact back before raising, so by the time anyone is told to compact, the
+     * index already fits — a loop that stopped at "fits" would archive nothing at the only
+     * moment the remedy is ever named. The default `reserve` is the largest index line the
+     * store currently holds (capped at half the budget), so the headroom bought is "a fact as
+     * big as your biggest one will fit", measured from this store's own data.
+     *
+     * `facts()` runs FIRST, before any rename, so an unreadable store moves nothing.
+     *
+     * THE MOVE IS `os.replace`, AND THE REFERENCE'S IS NOW TOO — the difference this comment
+     * used to report is CLOSED. `pyReplace` is `os.replace`, which replaces an existing
+     * destination on every platform. `Path.rename` is `os.rename`, which replaces silently on
+     * POSIX and raises `FileExistsError` on Windows; the reference called it here until
+     * `d239480` moved it onto `Path.replace`, so Node-on-Windows used to match Python-on-POSIX
+     * and Python-on-Windows matched neither. Nothing about the port changed: this line has
+     * always been `pyReplace`.
+     *
+     * WHAT IS STILL TRUE is the reachability argument, which is why the fix needed a fixture
+     * built for it. The only state that tells `rename` and `replace` apart is an
+     * `archive/<name>.md` that ALREADY exists when this loop moves the live fact over it — an
+     * earlier compaction's copy of a fact that was restored and then went stale again.
+     * `restore` cannot produce it, because it moves the archived copy OUT. On POSIX the two
+     * calls are indistinguishable even in that state, so `memorycli`'s
+     * `compact re-archives over an existing archive entry` is a WINDOWS-ONLY regression guard:
+     * a revert to `rename` on either side stays green on this machine.
+     *
+     * THIS PARAGRAPH USED TO CLAIM THE OTHER TWO MOVES ARE UNOBSERVABLE BY CONSTRUCTION —
+     * "guarded by a `reachable` check that refuses when `facts/<name>.md` is live" and "moves
+     * back onto a path it has just emptied", so "there is no state in which the two calls could
+     * answer differently". THE FIRST HALF IS FALSE, and `archive` (2026-09-05) is what made it
+     * reachable enough to notice. `reachable` is `Path.exists()`, which FOLLOWS symlinks, so a
+     * DANGLING symlink at the destination is an occupied directory ENTRY that the guard reports
+     * as absent — measured on macOS at `archive/alpha.md`: `lexists` True, `exists` False, the
+     * guard passed, and the move landed on top of the link. `os.rename` would raise
+     * `FileExistsError` there on Windows and `pyReplace` would not, which is exactly the
+     * divergence `d239480` closed one method up. The reference's `archive` is therefore on
+     * `Path.replace` too, as of the same day, and its FORWARD move and this one are the same
+     * call on every platform. `restore`'s forward move has the identical hole one directory
+     * over (a dangling symlink at `facts/<name>.md`) and is NOT changed here: narrowing a
+     * shipped command is not this fix's to make, and it is registered instead.
+     *
+     * WHAT IS STILL UNOBSERVABLE BY CONSTRUCTION is the ROLLBACK on both methods, and only that:
+     * it moves back onto a path the forward move has just emptied, so it cannot meet an occupied
+     * destination at all — there is no red to demonstrate for it, which is the reason `d239480`
+     * gave for leaving restore's alone and the reason the reference's two rollbacks are still
+     * `rename` against this file's `pyReplace`.
+     *
+     * THE ORDER IS `byEviction`, NOT `byStaleness` — `sorted(facts, key=self._eviction_key)`.
+     * A `DURABLE_TYPES` fact — `feedback`, the user's standing instruction, or `user`, a
+     * durable fact about them — holds until revoked and its worth does not decay with
+     * time-since-last-recall, so a purely temporal key ranks those classes exactly
+     * backwards. Measured on the real project store (index 21698 of a 24000-byte budget): one
+     * auto-compaction archived 15 facts and 6 of them were `feedback`. See `byEviction`.
+     */
+    compact(reserve?: number | null): CompactResult;
+    /**
+     * Names of the facts sitting in `archive/` — everything `compact` moved out.
+     *
+     * This is the worst place in the module to answer "empty" wrongly, because `compact()` has
+     * already MOVED the operator's facts here; an archive that cannot be listed is not an empty
+     * archive, and saying so makes compaction look like deletion. Hence `listing`, not a glob.
+     *
+     * The sort is over the STEMS and it is a plain string sort — `sorted(Path(name).stem …)` —
+     * not `sortedPathNames`, whose Windows case fold belongs to comparing `Path`s.
+     */
+    archived(): string[];
+    /**
+     * Move an archived fact back into `facts/`; refuse if it would blow the budget.
+     *
+     * THE PROMISE IS THAT A FAILED RESTORE LEAVES THE STORE EXACTLY AS IT FOUND IT, and it
+     * takes both halves the reference has: a `facts()` PARSE before the move (a listing is not
+     * enough — a malformed fact passes a listing and fails the budget check afterwards), and a
+     * rollback keyed on "the op after the move failed" rather than on a list of error types,
+     * because when the ARCHIVED file is the bad one it is not a fact until after the rename.
+     *
+     * `restore` is deliberately NOT routed through `archived()`: it stats one named path
+     * instead of listing, so an unlistable-but-traversable `archive/` still restores. Refusing
+     * a recovery the filesystem was still willing to perform is the wrong direction for the
+     * door back.
+     */
+    /**
+     * Move one named fact out of `facts/` and into `archive/`.
+     *
+     * The door out, taken deliberately. `compact` already moves facts out, but it chooses
+     * them by eviction rank and stops as soon as the index fits the budget, so it can
+     * neither be asked for a PARTICULAR fact nor be used at all when the store is already
+     * under budget. `restore` has taken a name since it was written; until this method the
+     * store could bring a named fact back but not send one away.
+     *
+     * THE NAME IS CHECKED AGAINST `NAME_RE` BEFORE ANY SYSCALL, and the reference does the
+     * same as of 2026-09-05. `save` was the only op enforcing it, and `save` is not the only
+     * op that CREATES a filename: this one builds `archive/<name>.md` out of what it is
+     * handed. Measured on macOS before the check: `archive ALPHA` against a live
+     * `facts/alpha.md` exited 0 on BOTH runtimes and left `archive/ALPHA.md` whose
+     * frontmatter says `name: alpha`, because the filesystem is case-insensitive and nothing
+     * asked the store's naming rule about the destination; on a case-sensitive filesystem the
+     * same command refuses. `restore` is deliberately left unvalidated on both sides.
+     *
+     * Same promise as `restore` — a failed archive leaves the store exactly as it found it —
+     * and one of its three guards carries over while two drop out:
+     *
+     * - Both stats go through `reachable`, not an existence check, for the reason spelled at
+     *   `ARCHIVE_UNREACHABLE`. The two sentences are their own constants because each names
+     *   the side the fact is still on, and that side is the mirror of restore's.
+     * - NO budget check. Archiving removes an index line, so the index can only shrink;
+     *   `checkIndexBudget` is restore's guard in restore's direction and here it could not
+     *   fail.
+     * - NO `facts()` PARSE BEFORE THE MOVE, and the reference dropped it the same day. The
+     *   parse reads EVERY fact, so ONE malformed file in `facts/` refused every archive in
+     *   the store INCLUDING ITS OWN, and no other command removes a fact by name — the one
+     *   file the store calls broken was the one file no CLI route could remove, which is the
+     *   opposite of what this method exists for. Without it the same command succeeds for a
+     *   reason: the move takes the bad file out of `facts/` first, so `rebuildIndex` parses a
+     *   directory that no longer holds it. A DIFFERENT fact being malformed still fails at
+     *   that rebuild, and the rollback below puts the moved fact back.
+     *
+     * The rollback is keyed on "the rebuild after the move failed", and the route that
+     * reaches it is `index.md` BEING A DIRECTORY — not, as the reference's docstring used to
+     * say, a directory at `archive/<name>.md`, which the guard above stats and refuses first.
+     */
+    archive(name: string): void;
+    restore(name: string): void;
+    /**
+     * The index as it should be on disk, derived from `facts/` and nothing else.
+     *
+     * An unreadable store raises here rather than answering `""` — that empty string was both
+     * the input `_rebuildIndex` wrote over `index.md` and the number `_checkIndexBudget`
+     * measured, which is the whole shape of the defect and is why the raise lives in the READ.
+     *
+     * THE BUDGET AND THE BYTES ON DISK AGREE IN THIS PORT, on every platform, because
+     * `pyWriteText` writes exactly this string. They do NOT agree in `runtime-py` on Windows:
+     * `write_text` opens with `newline=None`, so the file gets `\r\n` per line while
+     * `_checkIndexBudget` counts this LF text — 65 bytes apart on the live 65-fact store.
+     * Registered as a runtime-py defect, not fixed here (invariant 8).
+     */
+    indexText(): string;
+    private factPath;
+    private indexLine;
+    /**
+     * `sorted(facts, key=self._eviction_key)` — the eviction order `compact` archives in.
+     *
+     * CLASS FIRST, THEN STALENESS. A `feedback` fact is a standing instruction from the user:
+     * it holds until revoked, and its worth does not decay with time-since-last-recall, so the
+     * temporal key below is INVERTED for that kind of fact — the better an instruction has
+     * been internalised the less anything recalls it, the staler it looks, and the sooner it
+     * leaves the index that is loaded at session start. That class therefore ranks LAST and
+     * every other class is exhausted before any of it is archived. A priority and never a
+     * veto: the budget still wins, and with nothing else left it goes by staleness. Both sorts
+     * are STABLE, so a tied rank leaves the staleness answer below exactly as it was.
+     *
+     * `DURABLE_TYPES` AND NOT `"feedback"` ALONE, because that reason is a property of the
+     * class and not of the word — review round 4 (M12), mirroring `runtime-py` `1d9e5eb`.
+     * `assets/skills/memory.md` tells the model that `user` is "a durable fact about the
+     * user", and a durable fact does not become less true because nothing looked it up.
+     * Measured on the reference before the change, on four facts one per type where nothing
+     * has ever been recalled: one slot to free and `compact` archived `ausr`, a never-recalled
+     * `user` fact, ahead of a `project` note created seven months later. The change is
+     * MONOTONE — the protected set only grows — so no existing store loses a fact this rank
+     * kept for it before. The two protected types share ONE rank rather than being ordered
+     * against each other: the reason for protecting them is identical, so any order between
+     * them would be an invention, and a tied rank leaves the staleness key to answer.
+     *
+     * The protected class is deliberately UNCAPPED. Nothing bounds how much of the index it
+     * may hold, and that cannot make `compact` fail: once every decaying fact is archived the
+     * loop keeps going through the protected ones by staleness, so the budget still wins.
+     *
+     * `last_recalled` ALONE conflated two opposite facts: one written seconds ago and one
+     * nobody has asked for in a year both read as absent, and the empty string sorts before
+     * every real ISO date, so the NEWEST fact was the first evicted. Falling back to `created`
+     * makes absence of evidence mean "as stale as it is old". Ties break on name only after
+     * the dates are equal, so the alphabet can no longer decide a live question.
+     *
+     * `or`, not `??`: every FALSY value falls through, which is what Python's `or` does — a
+     * `last_recalled: ''` or a `created: 0` is not evidence of a recall. The comparison is
+     * `pyCompareLt`, Python's `<`, because these fields come out of YAML and a `date` beside a
+     * `str` raises there instead of sorting; both runtimes must fail the same way. Both sorts
+     * are STABLE, so equal keys keep listing order on either side.
+     */
+    private byEviction;
+    /**
+     * `path.exists()`, except that "I was not allowed to look" is never "it is not there".
+     *
+     * The same invariant as `listing`, one syscall down: `pyExists` swallows exactly
+     * `pathlib._IGNORED_ERRNOS` and re-raises the rest, so EACCES arrives as an OS error and is
+     * converted HERE — in the store, which owns the distinction — rather than in whichever
+     * command happened to call `restore`.
+     */
+    private reachable;
+    /**
+     * The `*.md` names in one of this store's directories, or a raise. Never a lie.
+     *
+     * THE THREE-WAY, which is the whole of job37's fix and is keyed on `lexists` PRECISELY so
+     * that it does not turn on an errno:
+     *
+     *   1. the scan failed with ENOENT and SOMETHING is at the path  -> unreadable
+     *   2. the scan failed with ENOENT and nothing is at the path    -> [] (a first run)
+     *   3. the scan failed any other way                             -> unreadable
+     *
+     * Arm 1 exists because the same shape reports different errnos on different platforms:
+     * POSIX raises ENOTDIR for a scan of a regular file and lands in arm 3, while a Windows
+     * directory scan of a non-directory reports the path as NOT FOUND and would land in arm 2
+     * — answering "empty" for a store that is a file. A dangling symlink reports ENOENT
+     * everywhere. Keying on "is anything there" gives one answer on all four CI jobs.
+     *
+     * Node's `fs` has none of this shape and libuv's Windows error mapping is not CPython's,
+     * so what is reproduced here is the DECISION. The syscalls and the `strerror` live in
+     * `pyfs.ts`; `layers.count_facts` deliberately decides differently on the same ones.
+     *
+     * `consequence` is the caller's half of the sentence, because the two directories fail
+     * differently and one wording cannot be true of both.
+     */
+    private listing;
+    /** Every `facts/*.md`, listed so that "I could not read it" is never "it is empty". */
+    private factPaths;
+    /** One sentence for a directory that could not be listed, and it never says "empty". */
+    private unreadable;
+    /**
+     * Every fact on disk, parsed.
+     *
+     * The `read_text` is OUTSIDE the try in the reference, so a fact file that is not UTF-8
+     * raises a bare `UnicodeDecodeError` rather than a `malformed fact file …` sentence. That
+     * ordering is reproduced: `pyReadText` raises `PyUnicodeDecodeError` with CPython's own
+     * message and it is not caught here.
+     *
+     * RULING — THE MESSAGE TEXT FOR A MALFORMED FILE. `_facts` interpolates the exception into
+     * `malformed fact file {name}: {e}`, and that reaches the model. Three of the four shapes
+     * are matched EXACTLY, because their text is Python's own and short: too few `---\n` parts
+     * (`ValueError` from the tuple unpack), frontmatter that is not a mapping (the store's own
+     * sentence), and a missing key (`KeyError.__str__`, which is the key in single quotes).
+     * The fourth — input outside the grammar `parseFrontmatter` accepts — is NOT matched:
+     * PyYAML answers with a `ScannerError`/`ParserError` carrying its marks and a rendered
+     * snippet, and reproducing that means porting PyYAML's scanner diagnostics, a surface
+     * larger than this whole module, for strings no test in `runtime-py/tests` pins. Node
+     * emits `parseFrontmatter`'s own reason after the identical prefix. The divergence is
+     * carried as a must-differ `ruling` case in the conformance suite so it is re-measured on
+     * every run instead of asserted once and forgotten.
+     */
+    private facts;
+    /**
+     * Date the recall.
+     *
+     * The reference's `snapshot` branch is absent here for the reason given at the top of the
+     * file: nothing on the MCP surface enters a snapshot scope, so `_snapshot` is always
+     * `None` and only this arm ever runs. No fact is left half-dated either way, because the
+     * listing inside `_facts` has already run before any write.
+     */
+    private stamp;
+    /** Write via `<name>.md.tmp` and `os.replace`, so a reader never sees a half-written fact. */
+    private writeFact;
+    /**
+     * Write `index.md` from the facts on disk. THE OP THE ORIGINAL DEFECT DESTROYED.
+     *
+     * Note what is deliberately NOT here: a guard refusing to shrink the index. It could not
+     * tell a wipe from a legitimate `compact()`, and it would leave every reader still being
+     * lied to. The read was wrong and the read is where it is fixed.
+     */
+    private rebuildIndex;
+    /**
+     * Raise `MemoryBudgetExceeded` if the index would not fit.
+     *
+     * This is a PARSE, not a listing: `indexText` reads every fact file, so a caller that
+     * pre-read with `factPaths` has not pre-read what this raises on. An unreadable store
+     * raises `MemoryValidationError` from in here — a DIFFERENT error from the budget one, and
+     * `save`'s rollback below is written to re-throw it untouched.
+     */
+    private checkIndexBudget;
+}