bantamkit-mcp 0.29.1 → 0.30.0

package/dist/memory/factfile.d.ts

@@ -14,6 +14,7 @@
  * `tools/conformance/suites/codec.mjs`; the shapes are pinned in `test/codec.test.mjs`.
  */
 import { PyScalar } from './pyyaml.js';
+import { pyStrip } from '../pysem.js';
 export declare class FactParseError extends Error {
 }
 /**
@@ -38,7 +39,18 @@ export interface Fact {
 }
 /** The frontmatter as it comes off disk — exactly the keys the file carries. */
 export type FactMeta = Record<string, FactValue | FactValue[]>;
-export declare function pyStrip(text: string): string;
+/**
+ * `str.strip()`, which is NOT `String.prototype.trim()` — `pysem.ts`'s, and no longer a second
+ * copy of it (`docs/roadmap-toolbox.md` row 8, entry (n)).
+ *
+ * Measured over all 0x110000 codepoints: Python strips 29, JS strips 25, and the two sets
+ * disagree on six. Python also strips U+001C..U+001F and U+0085; JS also strips U+FEFF.
+ * `_write_fact` ends with `fact.body.strip() + "\n"`, so each of those six is a byte of
+ * difference in a file the store then compares, hashes and diffs. `docread.ts` had derived
+ * the same set independently; the two were diffed over every codepoint and 200,000 random
+ * strings before they were merged, and the name stays exported from here.
+ */
+export { pyStrip };
 /**
  * The bytes of a fact file as Python's `Path.read_text(encoding="utf-8")` sees them.
  *

package/dist/memory/factfile.js

@@ -14,32 +14,22 @@
  * `tools/conformance/suites/codec.mjs`; the shapes are pinned in `test/codec.test.mjs`.
  */
 import { constructPlain, PyScalar, safeDumpMapping } from './pyyaml.js';
+import { pyStrip } from '../pysem.js';
 export class FactParseError extends Error {
 }
 // ------------------------------------------------------------------------ whitespace
 /**
- * `str.strip()`, which is NOT `String.prototype.trim()`.
+ * `str.strip()`, which is NOT `String.prototype.trim()` — `pysem.ts`'s, and no longer a second
+ * copy of it (`docs/roadmap-toolbox.md` row 8, entry (n)).
  *
  * Measured over all 0x110000 codepoints: Python strips 29, JS strips 25, and the two sets
  * disagree on six. Python also strips U+001C..U+001F and U+0085; JS also strips U+FEFF.
  * `_write_fact` ends with `fact.body.strip() + "\n"`, so each of those six is a byte of
- * difference in a file the store then compares, hashes and diffs.
+ * difference in a file the store then compares, hashes and diffs. `docread.ts` had derived
+ * the same set independently; the two were diffed over every codepoint and 200,000 random
+ * strings before they were merged, and the name stays exported from here.
  */
-const PY_SPACE = new Set([
-    0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x1c, 0x1d, 0x1e, 0x1f, 0x20, 0x85, 0xa0, 0x1680, 0x2000,
-    0x2001, 0x2002, 0x2003, 0x2004, 0x2005, 0x2006, 0x2007, 0x2008, 0x2009, 0x200a, 0x2028,
-    0x2029, 0x202f, 0x205f, 0x3000,
-]);
-export function pyStrip(text) {
-    const chars = [...text];
-    let start = 0;
-    let end = chars.length;
-    while (start < end && PY_SPACE.has(chars[start].codePointAt(0)))
-        start += 1;
-    while (end > start && PY_SPACE.has(chars[end - 1].codePointAt(0)))
-        end -= 1;
-    return chars.slice(start, end).join('');
-}
+export { pyStrip };
 /**
  * The bytes of a fact file as Python's `Path.read_text(encoding="utf-8")` sees them.
  *

package/dist/memory/pyfs.d.ts

@@ -1,3 +1,4 @@
+import { cmpCodepoint, pyRepr } from '../pysem.js';
 /** The errno names this port claims to render in CPython's words. The suite reads it. */
 export declare const STRERROR_NAMES: readonly string[];
 /**
@@ -242,15 +243,20 @@ export declare function matchesMd(name: string): boolean;
 /** `os.path.normcase` — identity off Windows, `s.replace('/', '\\').lower()` on it. */
 export declare function normcase(name: string): string;
 /**
- * Python's `<` on `str`, which is CODEPOINT order. JS compares UTF-16 code units.
+ * Python's `<` on `str`, which is CODEPOINT order — `pysem.ts`'s, and no longer a second copy
+ * of it (`docs/roadmap-toolbox.md` row 8, entry (n)).
  *
- * They disagree for every astral character: `['\u{1F414}.md', '！.md'].sort()` puts the
- * chicken first because its lead surrogate is 0xD83D, and Python puts it last because
- * 0x1F414 > 0xFF01. `_fact_paths` sorts, `recall` breaks score ties on the name, and the
- * index is written in that order — so a single astral fact name is enough to make two
- * `index.md` files that differ.
+ * JS compares UTF-16 code units, and the two disagree for every astral character:
+ * `['\u{1F414}.md', '！.md'].sort()` puts the chicken first because its lead surrogate is
+ * 0xD83D, and Python puts it last because 0x1F414 > 0xFF01. `_fact_paths` sorts, `recall`
+ * breaks score ties on the name, and the index is written in that order — so a single astral
+ * fact name is enough to make two `index.md` files that differ.
+ *
+ * `docread.ts` carried its own, which agreed on the ORDER for every pair and disagreed on the
+ * numbers (it returned the codepoint difference, this returns -1/0/1). This spelling is the
+ * one that survived, to the digit, because every importer already sees these numbers.
  */
-export declare function cmpCodepoint(a: string, b: string): number;
+export { cmpCodepoint };
 /**
  * `sorted(directory / name for name in names)` — sorting `Path`s, not strings.
  *
@@ -473,20 +479,22 @@ export declare function pyIsFile(path: string): boolean;
  */
 export declare function pyStatIsDir(path: string): boolean;
 /**
- * `repr(str)`, which `_pinned_store` interpolates with `{raw!r}` for a relative pin.
+ * `repr(str)`, which `_pinned_store` interpolates with `{raw!r}` for a relative pin — and
+ * which `pysem.ts` now spells once (`docs/roadmap-toolbox.md` row 8, entry (n)).
  *
  * Python quotes with `'` unless the value contains a `'` and no `"`; it escapes `\\`, the
  * quote, `\t`, `\n`, `\r`, and every codepoint that is not `str.isprintable()` — that is,
- * everything in a `C*` category and every separator except the space itself. JS spells the
- * same predicate `\p{C}` / `\p{Z}` under the `u` flag, so this is the rule rather than a
- * table. The escapes are `\xNN` below U+0100, `\uNNNN` below U+10000, `\UNNNNNNNN` above.
+ * everything in a `C*` category and every separator except the space itself. `docread.ts` had
+ * spelled the same predicate as an explicit `Cc|Cf|Cs|Co|Cn|Zl|Zp|Zs` class where this one
+ * spelled it `\p{C}|\p{Z}`; the two were compared on all 1,114,112 codepoints and answered
+ * byte-identically before they were merged.
  *
  * The one place it can drift is a codepoint whose category changed between CPython 3.12's
  * Unicode 15.0 and the ICU this Node was built against: a newly assigned character is `Cn`
  * (not printable, escaped) for Python and assigned (printable, raw) here. A pin path made of
  * brand-new codepoints is the only input that reaches it.
  */
-export declare function pyRepr(value: string): string;
+export { pyRepr };
 /**
  * `repr(float)`.
  *

package/dist/memory/pyfs.js

@@ -55,6 +55,7 @@
  */
 import { appendFileSync, lstatSync, mkdirSync, readdirSync, readFileSync, readlinkSync, realpathSync, renameSync, statSync, unlinkSync, writeFileSync, } from 'node:fs';
 import { constants as osConstants, homedir, userInfo } from 'node:os';
+import { cmpCodepoint, pyRepr } from '../pysem.js';
 // ------------------------------------------------------------------------------ errno
 /**
  * `os.strerror(errno)` for the errnos a directory scan, a `mkdir` or a file write can
@@ -750,26 +751,20 @@ export function normcase(name) {
 }
 // -------------------------------------------------------------------------- comparison
 /**
- * Python's `<` on `str`, which is CODEPOINT order. JS compares UTF-16 code units.
- *
- * They disagree for every astral character: `['\u{1F414}.md', '！.md'].sort()` puts the
- * chicken first because its lead surrogate is 0xD83D, and Python puts it last because
- * 0x1F414 > 0xFF01. `_fact_paths` sorts, `recall` breaks score ties on the name, and the
- * index is written in that order — so a single astral fact name is enough to make two
- * `index.md` files that differ.
+ * Python's `<` on `str`, which is CODEPOINT order — `pysem.ts`'s, and no longer a second copy
+ * of it (`docs/roadmap-toolbox.md` row 8, entry (n)).
+ *
+ * JS compares UTF-16 code units, and the two disagree for every astral character:
+ * `['\u{1F414}.md', '！.md'].sort()` puts the chicken first because its lead surrogate is
+ * 0xD83D, and Python puts it last because 0x1F414 > 0xFF01. `_fact_paths` sorts, `recall`
+ * breaks score ties on the name, and the index is written in that order — so a single astral
+ * fact name is enough to make two `index.md` files that differ.
+ *
+ * `docread.ts` carried its own, which agreed on the ORDER for every pair and disagreed on the
+ * numbers (it returned the codepoint difference, this returns -1/0/1). This spelling is the
+ * one that survived, to the digit, because every importer already sees these numbers.
  */
-export function cmpCodepoint(a, b) {
-    const x = [...a];
-    const y = [...b];
-    const n = Math.min(x.length, y.length);
-    for (let i = 0; i < n; i += 1) {
-        const p = x[i].codePointAt(0);
-        const q = y[i].codePointAt(0);
-        if (p !== q)
-            return p < q ? -1 : 1;
-    }
-    return x.length - y.length;
-}
+export { cmpCodepoint };
 /**
  * `sorted(directory / name for name in names)` — sorting `Path`s, not strings.
  *
@@ -1458,47 +1453,22 @@ export function pyStatIsDir(path) {
 }
 // --------------------------------------------------------------------------------- repr
 /**
- * `repr(str)`, which `_pinned_store` interpolates with `{raw!r}` for a relative pin.
+ * `repr(str)`, which `_pinned_store` interpolates with `{raw!r}` for a relative pin — and
+ * which `pysem.ts` now spells once (`docs/roadmap-toolbox.md` row 8, entry (n)).
  *
  * Python quotes with `'` unless the value contains a `'` and no `"`; it escapes `\\`, the
  * quote, `\t`, `\n`, `\r`, and every codepoint that is not `str.isprintable()` — that is,
- * everything in a `C*` category and every separator except the space itself. JS spells the
- * same predicate `\p{C}` / `\p{Z}` under the `u` flag, so this is the rule rather than a
- * table. The escapes are `\xNN` below U+0100, `\uNNNN` below U+10000, `\UNNNNNNNN` above.
+ * everything in a `C*` category and every separator except the space itself. `docread.ts` had
+ * spelled the same predicate as an explicit `Cc|Cf|Cs|Co|Cn|Zl|Zp|Zs` class where this one
+ * spelled it `\p{C}|\p{Z}`; the two were compared on all 1,114,112 codepoints and answered
+ * byte-identically before they were merged.
  *
  * The one place it can drift is a codepoint whose category changed between CPython 3.12's
  * Unicode 15.0 and the ICU this Node was built against: a newly assigned character is `Cn`
  * (not printable, escaped) for Python and assigned (printable, raw) here. A pin path made of
  * brand-new codepoints is the only input that reaches it.
  */
-export function pyRepr(value) {
-    const quote = value.includes("'") && !value.includes('"') ? '"' : "'";
-    let out = quote;
-    for (const ch of value) {
-        if (ch === '\\')
-            out += '\\\\';
-        else if (ch === quote)
-            out += `\\${ch}`;
-        else if (ch === '\t')
-            out += '\\t';
-        else if (ch === '\n')
-            out += '\\n';
-        else if (ch === '\r')
-            out += '\\r';
-        else if (ch === ' ' || !/^(?:\p{C}|\p{Z})$/u.test(ch))
-            out += ch;
-        else {
-            const cp = ch.codePointAt(0);
-            if (cp < 0x100)
-                out += `\\x${cp.toString(16).padStart(2, '0')}`;
-            else if (cp < 0x10000)
-                out += `\\u${cp.toString(16).padStart(4, '0')}`;
-            else
-                out += `\\U${cp.toString(16).padStart(8, '0')}`;
-        }
-    }
-    return out + quote;
-}
+export { pyRepr };
 /**
  * `repr(float)`.
  *

package/dist/memory/store.d.ts

@@ -15,6 +15,7 @@ export declare const VALID_TYPES: readonly ["feedback", "project", "reference",
  */
 export declare const DURABLE_TYPES: readonly ["feedback", "user"];
 export declare const DUPLICATE_JACCARD = 0.5;
+export declare const RECALL_MIN_SCORE_RATIO = 0;
 /** 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 {
@@ -55,6 +56,17 @@ export interface CompactResult {
     headroom: number;
     archiveDir: string;
 }
+/**
+ * The store members `dream.ts` needs and no caller outside it should have. See
+ * `MemoryStore.internals`.
+ */
+export interface StoreInternals {
+    facts(): Fact[];
+    factPath(name: FactValue): string;
+    indexLine(fact: Fact): string;
+    writeFact(fact: Fact): void;
+    rebuildIndex(): void;
+}
 export interface MemoryStoreOptions {
     indexBudget?: number;
     k?: number;
@@ -186,8 +198,25 @@ export declare class MemoryStore {
      * `[]` — 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.
+     *
+     * `minRatio` is roadmap #6's precision gate: keep a fact only if its score is at least
+     * that fraction of the BEST score in this same recall. The default is
+     * `RECALL_MIN_SCORE_RATIO`, which is 0.0 and gates nothing — see the paragraph at that
+     * constant for why the number is a no-op today and what has to be measured before it
+     * stops being one. The comparison is relative to this store's own best because that is
+     * the only quantity in reach here that cancels query length; a layered `Memory` therefore
+     * applies the gate once per layer, against each layer's own top hit, and never across
+     * layers.
+     *
+     * THE RANGE CHECK RUNS BEFORE ANY FILE IS READ. A ratio outside `[0.0, 1.0]` is a
+     * caller's bug, and reporting it as "your store has no matches" would send someone to
+     * look at their memories for a defect that is in the argument. It is spelled
+     * `!(minRatio >= 0 && minRatio <= 1)` and NOT `(minRatio < 0 || minRatio > 1)`: every
+     * comparison against `NaN` is false, so the second spelling ADMITS `NaN` where the
+     * reference's `not 0.0 <= min_ratio <= 1.0` refuses it. That is a real mutant (M7b) and
+     * it is killed on both sides.
      */
-    recall(query: string, k?: number | null, stamp?: boolean): Fact[];
+    recall(query: string, k?: number | null, stamp?: boolean, minRatio?: number): Fact[];
     /**
      * `len(store._facts())` at the operator CLI, which is the only caller.
      *
@@ -330,6 +359,49 @@ export declare class MemoryStore {
      * say, a directory at `archive/<name>.md`, which the guard above stats and refuses first.
      */
     archive(name: string): void;
+    /**
+     * `NAME_RE` ENFORCED BEFORE ANY SYSCALL, matching `archive` (job44, z). `restore` has
+     * built `facts/<name>.md` out of whatever it was handed since it was written; measured on
+     * macOS before this check, both runtimes: `restore ALPHA` against a live
+     * `archive/ALPHA.md` exited 0 and wrote `facts/ALPHA.md` — the case-insensitive
+     * filesystem matched the archived source, and nothing asked the store's own naming rule
+     * about the destination it was about to create.
+     *
+     * THE OCCUPIED-DESTINATION GUARD NOW ALSO CATCHES A DANGLING SYMLINK (job44, z). `reachable`
+     * is `pyExists`, `Path.exists()`'s equivalent, which FOLLOWS symlinks — so a dangling
+     * symlink at `facts/<name>.md` is an occupied directory entry the guard alone cannot see:
+     * measured, `pyLexists` true and `pyExists` false, and without the check below the guard
+     * passed and execution reached the pre-move `facts()` parse, which then raised a raw
+     * `FileNotFoundError` reading the dangling link it was about to parse as a fact. `pyLexists`
+     * is only consulted when `reachable` returned `false` WITHOUT raising — an EACCES on the
+     * same stat already escaped out of `reachable` first, so this never masks that distinction.
+     *
+     * TWO SENTENCES, NOT ONE, on job44's reconciliation with the reference. The first two
+     * answers tried here were both wrong: treating a dangling link the same as `reachable` said
+     * "already live", and a live fact is exactly what a dangling link is NOT; letting it fall
+     * through to `facts()`'s pre-read dressed an unrelated `FileNotFoundError` as a move
+     * failure when no move had been attempted (both runtimes made one of these two mistakes).
+     * The link occupies the path — refusing is still correct — but the REASON is that it
+     * cannot be read as a fact, not that a fact is already there, so the second branch below
+     * says that instead and never reaches `facts()` at all.
+     *
+     * THIS IS THE OPPOSITE OUTCOME FROM `archive`'s mirror of the same defect: `archive`'s
+     * forward move is `pyReplace`, which overwrites a dangling link identically on every
+     * platform, so the guard there is deliberately left as `reachable` alone (see the test
+     * pinning that). Closing the guard here removes the ONLY path that could reach an occupied
+     * destination, on both runtimes, rather than picking a side of what would happen there.
+     *
+     * AND THE FORWARD MOVE ITSELF NO LONGER DIVERGES — this sentence used to say it did, and
+     * was stale against its own commit. `restore`'s forward move is `pyReplace` on this side
+     * and `source.replace(destination)` on the reference (`store.py`, `restore`), changed in
+     * the SAME commit that added the guard above; at its parent `f484c70` the reference still
+     * called `source.rename(destination)`, which is what this comment described.
+     * `d239480`'s `rename`-versus-`pyReplace` difference is therefore REMOVED here, not merely
+     * made unreachable, and the same is true of `archive` (fixed by review round 5) and of
+     * `compact` (fixed by `d239480` itself). Every forward move in this store is `replace` on
+     * both sides; the only `rename` calls left on the reference are the two ROLLBACKS, which
+     * move back onto a path the forward move has just emptied — see `docs/porting.md`.
+     */
     restore(name: string): void;
     /**
      * The index as it should be on disk, derived from `facts/` and nothing else.
@@ -345,6 +417,21 @@ export declare class MemoryStore {
      * Registered as a runtime-py defect, not fixed here (invariant 8).
      */
     indexText(): string;
+    /**
+     * The `_`-prefixed members `dream.ts` reaches for, handed out as ONE named seam.
+     *
+     * The reference's `dream.py` calls `store._facts()`, `_fact_path`, `_index_line`,
+     * `_write_fact` and `_rebuild_index` directly — Python's underscore is a convention and
+     * costs nothing to cross. TypeScript's `private` is enforced, so the port needs a door,
+     * and this is deliberately one door rather than five relaxed modifiers: it is greppable,
+     * it names its one caller, and a sixth internal does not become reachable by accident.
+     *
+     * `_fact_text` has no member here because it never needed splitting out on this side —
+     * `formatFact` in `factfile.ts` has always been the serialiser `writeFact` calls, so the
+     * bytes `dream` MEASURES and the bytes the store WRITES are already one function. That is
+     * the code-shape difference the Python half had to manufacture, not a behaviour one.
+     */
+    internals(): StoreInternals;
     private factPath;
     private indexLine;
     /**

package/dist/memory/store.js

@@ -68,6 +68,55 @@ export const DURABLE_TYPES = ['feedback', 'user'];
 const NAME_RE = /^[a-z0-9][a-z0-9-]*\n?$/;
 const NAME_PATTERN = '^[a-z0-9][a-z0-9-]*$';
 export const DUPLICATE_JACCARD = 0.5;
+// ---- the precision gate (roadmap #6) ---------------------------------------------
+//
+// `recall` keeps a fact whose score is at least `minRatio` of the BEST score in the same
+// recall. WHY THIS NUMBER IS 0.0, and what will replace it:
+//
+// 0.0 IS A DELIBERATE NO-OP, not a tuned value. `score >= 0.0 * best` is true for every
+// fact `recall` was ever going to return — the scoring loop keeps only `score > 0` — so
+// shipping this gate at its default changes not one recall, not one injected header, and
+// not one byte of any reply. That is the whole point. The threshold that would actually
+// cut something has to come from `tools/ledger/injection-precision.mjs`, and on the day
+// that tool shipped (2026-09-06) it REFUSED to report a rate: 491 injection records, 3 of
+// them carrying names+scores+session, 2 distinct sessions, and no control arm, against a
+// floor of 100 joinable injections across 5 sessions. There is no retroactive baseline —
+// the 488 older records carry `hits` and `bytes` and nothing joinable — so a number chosen
+// today would be a number chosen off three rows, shipped as a silent suppressor of memory
+// injection. The mechanism lands now; the number lands when that tool answers instead of
+// refusing.
+//
+// WHY A RATIO AND NOT A COUNT. `score` is an unnormalised intersection size,
+// `len(tokens(name + " " + description) & tokens(query))`, so it scales with how long the
+// QUERY is. Measured on the three instrumented records: the same two-fact shape scored 2
+// and 2 on a 452-character prompt, 4 and 4 on a 453-character prompt, and 22 and 21 on a
+// 7855-character one. An absolute cut of, say, 5 would gate out both short prompts
+// entirely and admit everything on the long one, which is a rule about prompt length
+// wearing a relevance costume. Within ONE recall the query is fixed, so dividing by the
+// best score in that same recall cancels the length term exactly. Jaccard was the other
+// candidate and was rejected for the mirror-image bias: `|a & b| / |a | b|` puts the
+// query's own token count in the denominator, so it would gate out LONG prompts instead.
+//
+// THE GATE IS RELATIVE, SO IT CAN NEVER EMPTY A RECALL. The top hit IS the max, so
+// `best >= minRatio * best` holds for every ratio in range, 1.0 included. It narrows an
+// injection; it never suppresses one, and the COUNT of prompts that get an injection is
+// invariant at every setting.
+//
+// WHAT THE RATIO DOES NOT FIX: `tokens` is `re.findall(r"[a-z0-9]+", text.lower())`,
+// ASCII-only. A wholly non-Latin prompt tokenises to the empty set and scores 0 against
+// every fact, so it never reaches this gate at all — it is already an empty recall. This
+// store's operator writes Thai; a threshold tuned on English prompts would be tuned on a
+// population that structurally excludes theirs.
+//
+// The number lives in TWO places, one per runtime, and they must hold the SAME float:
+// `runtime-py/src/bantamkit/memory/store.py`'s `RECALL_MIN_SCORE_RATIO` is the reference.
+// `Memory.recallOutcome` and the `UserPromptSubmit` hook that calls it inherit it rather
+// than restating it.
+export const RECALL_MIN_SCORE_RATIO = 0.0;
+// Spelled once because both runtimes raise it verbatim. The offending value is NOT
+// interpolated: Python renders `2.0` as `2.0` and JavaScript renders it as `2`, so a
+// sentence carrying the number would be a divergence manufactured by float formatting.
+const MIN_RATIO_RANGE = 'recall min-score ratio must be between 0.0 and 1.0';
 /** See the reference's comment: measured against a real store, not chosen. */
 export const DEFAULT_INDEX_BUDGET = 24_000;
 // The second half of the "unreadable" sentence, one per directory this store lists — and
@@ -494,11 +543,30 @@ export class MemoryStore {
      * `[]` — 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.
+     *
+     * `minRatio` is roadmap #6's precision gate: keep a fact only if its score is at least
+     * that fraction of the BEST score in this same recall. The default is
+     * `RECALL_MIN_SCORE_RATIO`, which is 0.0 and gates nothing — see the paragraph at that
+     * constant for why the number is a no-op today and what has to be measured before it
+     * stops being one. The comparison is relative to this store's own best because that is
+     * the only quantity in reach here that cancels query length; a layered `Memory` therefore
+     * applies the gate once per layer, against each layer's own top hit, and never across
+     * layers.
+     *
+     * THE RANGE CHECK RUNS BEFORE ANY FILE IS READ. A ratio outside `[0.0, 1.0]` is a
+     * caller's bug, and reporting it as "your store has no matches" would send someone to
+     * look at their memories for a defect that is in the argument. It is spelled
+     * `!(minRatio >= 0 && minRatio <= 1)` and NOT `(minRatio < 0 || minRatio > 1)`: every
+     * comparison against `NaN` is false, so the second spelling ADMITS `NaN` where the
+     * reference's `not 0.0 <= min_ratio <= 1.0` refuses it. That is a real mutant (M7b) and
+     * it is killed on both sides.
      */
-    recall(query, k = null, stamp = true) {
+    recall(query, k = null, stamp = true, minRatio = RECALL_MIN_SCORE_RATIO) {
+        if (!(minRatio >= 0 && minRatio <= 1))
+            throw new MemoryValidationError(MIN_RATIO_RANGE);
         const limit = k ?? this.k;
         const q = tokens(query);
-        const scored = [];
+        let scored = [];
         for (const fact of this.facts()) {
             let score = 0;
             for (const t of tokens(`${pyText(fact.name)} ${pyText(fact.description)}`))
@@ -507,6 +575,20 @@ export class MemoryStore {
             if (score > 0)
                 scored.push({ score, name: fact.name, fact });
         }
+        if (scored.length > 0) {
+            // No `if (minRatio > 0)` shortcut on purpose: at 0.0 this line still runs and still
+            // keeps everything, so "the default gates nothing" is a fact about the arithmetic
+            // rather than about a branch that could be edited away. `Math.max(...scored)` is NOT
+            // used: a spread is one argument per fact and a large store would overflow the
+            // argument limit, which is a crash the reference's `max(...)` over a generator does
+            // not have.
+            let best = scored[0].score;
+            for (const s of scored)
+                if (s.score > best)
+                    best = s.score;
+            const floor = minRatio * best;
+            scored = scored.filter((s) => s.score >= floor);
+        }
         // `key=lambda pair: (-pair[0], pair[1].name)`. The name comparison is CODEPOINT order
         // for two strings — which is not what `Array.prototype.sort` does — and Python's `<`
         // for everything else, refusals included. See `sortScored`.
@@ -742,28 +824,86 @@ export class MemoryStore {
             throw error;
         }
     }
+    /**
+     * `NAME_RE` ENFORCED BEFORE ANY SYSCALL, matching `archive` (job44, z). `restore` has
+     * built `facts/<name>.md` out of whatever it was handed since it was written; measured on
+     * macOS before this check, both runtimes: `restore ALPHA` against a live
+     * `archive/ALPHA.md` exited 0 and wrote `facts/ALPHA.md` — the case-insensitive
+     * filesystem matched the archived source, and nothing asked the store's own naming rule
+     * about the destination it was about to create.
+     *
+     * THE OCCUPIED-DESTINATION GUARD NOW ALSO CATCHES A DANGLING SYMLINK (job44, z). `reachable`
+     * is `pyExists`, `Path.exists()`'s equivalent, which FOLLOWS symlinks — so a dangling
+     * symlink at `facts/<name>.md` is an occupied directory entry the guard alone cannot see:
+     * measured, `pyLexists` true and `pyExists` false, and without the check below the guard
+     * passed and execution reached the pre-move `facts()` parse, which then raised a raw
+     * `FileNotFoundError` reading the dangling link it was about to parse as a fact. `pyLexists`
+     * is only consulted when `reachable` returned `false` WITHOUT raising — an EACCES on the
+     * same stat already escaped out of `reachable` first, so this never masks that distinction.
+     *
+     * TWO SENTENCES, NOT ONE, on job44's reconciliation with the reference. The first two
+     * answers tried here were both wrong: treating a dangling link the same as `reachable` said
+     * "already live", and a live fact is exactly what a dangling link is NOT; letting it fall
+     * through to `facts()`'s pre-read dressed an unrelated `FileNotFoundError` as a move
+     * failure when no move had been attempted (both runtimes made one of these two mistakes).
+     * The link occupies the path — refusing is still correct — but the REASON is that it
+     * cannot be read as a fact, not that a fact is already there, so the second branch below
+     * says that instead and never reaches `facts()` at all.
+     *
+     * THIS IS THE OPPOSITE OUTCOME FROM `archive`'s mirror of the same defect: `archive`'s
+     * forward move is `pyReplace`, which overwrites a dangling link identically on every
+     * platform, so the guard there is deliberately left as `reachable` alone (see the test
+     * pinning that). Closing the guard here removes the ONLY path that could reach an occupied
+     * destination, on both runtimes, rather than picking a side of what would happen there.
+     *
+     * AND THE FORWARD MOVE ITSELF NO LONGER DIVERGES — this sentence used to say it did, and
+     * was stale against its own commit. `restore`'s forward move is `pyReplace` on this side
+     * and `source.replace(destination)` on the reference (`store.py`, `restore`), changed in
+     * the SAME commit that added the guard above; at its parent `f484c70` the reference still
+     * called `source.rename(destination)`, which is what this comment described.
+     * `d239480`'s `rename`-versus-`pyReplace` difference is therefore REMOVED here, not merely
+     * made unreachable, and the same is true of `archive` (fixed by review round 5) and of
+     * `compact` (fixed by `d239480` itself). Every forward move in this store is `replace` on
+     * both sides; the only `rename` calls left on the reference are the two ROLLBACKS, which
+     * move back onto a path the forward move has just emptied — see `docs/porting.md`.
+     */
     restore(name) {
+        if (!NAME_RE.test(name || '')) {
+            throw new MemoryValidationError(`invalid name '${name}'; must match ${NAME_PATTERN}`);
+        }
         const archive = pyJoin(this.root, 'archive');
         const source = pyJoin(archive, `${name}.md`);
         if (!this.reachable(source, archive, ARCHIVE_UNREACHABLE)) {
             throw new MemoryValidationError(`no archived fact '${name}' under ${archive}`);
         }
         const destination = this.factPath(name);
-        if (this.reachable(destination, pyJoin(this.root, 'facts'), FACTS_UNREACHABLE)) {
+        const facts = pyJoin(this.root, 'facts');
+        if (this.reachable(destination, facts, FACTS_UNREACHABLE)) {
             throw new MemoryValidationError(`fact '${name}' is already live; refusing to overwrite it from archive`);
         }
+        if (pyLexists(destination)) {
+            throw new MemoryValidationError(`facts/${name}.md already exists but cannot be read as a fact; refusing to restore over it`);
+        }
         this.facts(); // parse BEFORE the move, not after it
-        pyMkdirParents(pyJoin(this.root, 'facts'));
+        pyMkdirParents(facts);
         pyReplace(source, destination);
+        // THE FINAL `rebuildIndex()` IS INSIDE THIS TRY, and job44's reconciliation is why: it
+        // used to sit AFTER this block, uncovered, so a failure there — measured by driving the
+        // real fault (`index.md` a directory) rather than reading the code shape — left the fact
+        // STUCK in `facts/`, GONE from `archive/`, with no rollback attempted at all, because
+        // `checkIndexBudget` never touches disk and passes cleanly first. `archive`'s single try
+        // already covered its own write-then-check in one block; this brings restore's rollback
+        // up to the same coverage `runtime-py` gave `_check_index_budget` and the closing
+        // `_rebuild_index` together, in the same reconciliation.
         try {
             this.checkIndexBudget();
+            this.rebuildIndex();
         }
         catch (error) {
             pyReplace(destination, source);
             this.rebuildIndex();
             throw error;
         }
-        this.rebuildIndex();
     }
     /**
      * The index as it should be on disk, derived from `facts/` and nothing else.
@@ -781,6 +921,29 @@ export class MemoryStore {
     indexText() {
         return this.facts().map((fact) => this.indexLine(fact)).join('');
     }
+    /**
+     * The `_`-prefixed members `dream.ts` reaches for, handed out as ONE named seam.
+     *
+     * The reference's `dream.py` calls `store._facts()`, `_fact_path`, `_index_line`,
+     * `_write_fact` and `_rebuild_index` directly — Python's underscore is a convention and
+     * costs nothing to cross. TypeScript's `private` is enforced, so the port needs a door,
+     * and this is deliberately one door rather than five relaxed modifiers: it is greppable,
+     * it names its one caller, and a sixth internal does not become reachable by accident.
+     *
+     * `_fact_text` has no member here because it never needed splitting out on this side —
+     * `formatFact` in `factfile.ts` has always been the serialiser `writeFact` calls, so the
+     * bytes `dream` MEASURES and the bytes the store WRITES are already one function. That is
+     * the code-shape difference the Python half had to manufacture, not a behaviour one.
+     */
+    internals() {
+        return {
+            facts: () => this.facts(),
+            factPath: (name) => this.factPath(name),
+            indexLine: (fact) => this.indexLine(fact),
+            writeFact: (fact) => this.writeFact(fact),
+            rebuildIndex: () => this.rebuildIndex(),
+        };
+    }
     // ---- internals ----
     factPath(name) {
         return pyJoin(this.root, 'facts', `${pyText(name)}.md`);