bantamkit-mcp 0.29.0 → 0.29.2

package/dist/mcp/pyargs.d.ts

@@ -41,6 +41,25 @@ export interface ArgModel {
     readonly model: string;
     readonly fields: readonly FieldSpec[];
 }
+/**
+ * `assets/tools/bantamkit_read.json` `offset.maximum` — `Number.MAX_SAFE_INTEGER`, the
+ * largest integer `JSON.parse` reads back unchanged (F1). The reference binds it as
+ * `Annotated[int, Field(le=OFFSET_MAXIMUM)]`, so above it the refusal is pydantic's
+ * `less_than_equal` frame and the handler never runs; this side reads the JSON with its
+ * own decoder, so `9007199254740993` arrives exact and is refused with the same text.
+ *
+ * EXPORTED so the number can be TIED to the asset rather than copied a fourth time.
+ * `assets/tools/bantamkit_read.json` is the published contract and this is the number the
+ * signature enforces; `test/document-cache-and-bounds.test.mjs` reads that file OFF DISK and
+ * compares it against this constant, against the schema the server actually serves, and
+ * against what the handler refuses — the port of `runtime-py`'s
+ * `tests/test_document_manifest_parity.py`. Register entries (c) and (l),
+ * `docs/roadmap-toolbox.md` row 8. It stays a test rather than a runtime read for the
+ * reference's reason: a module-level asset load would make importing this module fail
+ * wherever the asset pack is not on disk, which is a worse failure than a refusal to
+ * register a tool.
+ */
+export declare const OFFSET_MAXIMUM = 9007199254740991n;
 /**
  * One model per handler, mirroring `build_server`'s closures signature for signature.
  *

package/dist/mcp/pyargs.js

@@ -41,8 +41,19 @@ const opt = (name, kind, bound = {}) => ({
  * `Annotated[int, Field(le=OFFSET_MAXIMUM)]`, so above it the refusal is pydantic's
  * `less_than_equal` frame and the handler never runs; this side reads the JSON with its
  * own decoder, so `9007199254740993` arrives exact and is refused with the same text.
+ *
+ * EXPORTED so the number can be TIED to the asset rather than copied a fourth time.
+ * `assets/tools/bantamkit_read.json` is the published contract and this is the number the
+ * signature enforces; `test/document-cache-and-bounds.test.mjs` reads that file OFF DISK and
+ * compares it against this constant, against the schema the server actually serves, and
+ * against what the handler refuses — the port of `runtime-py`'s
+ * `tests/test_document_manifest_parity.py`. Register entries (c) and (l),
+ * `docs/roadmap-toolbox.md` row 8. It stays a test rather than a runtime read for the
+ * reference's reason: a module-level asset load would make importing this module fail
+ * wherever the asset pack is not on disk, which is a worse failure than a refusal to
+ * register a tool.
  */
-const OFFSET_MAXIMUM = 9007199254740991n;
+export const OFFSET_MAXIMUM = 9007199254740991n;
 /**
  * One model per handler, mirroring `build_server`'s closures signature for signature.
  *

package/dist/mcp/server.js

@@ -22,7 +22,7 @@
  * indistinguishable from a typo: a manifest renamed or a surface dropped would silently
  * shrink the served set, and the field would be a comment.
  */
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
@@ -173,6 +173,87 @@ function recordRaise(log, tool, body) {
         throw e;
     }
 }
+/**
+ * The last `docread.extract` result this server produced, and what it was OF.
+ *
+ * The port of `mcpserver._DocumentCache` (register entry (i), `docs/roadmap-toolbox.md` row
+ * 8). `bantamkit_read` re-parsed the whole document on EVERY call, so a caller paging a
+ * 12,001-row sheet in 200-row pages parsed the workbook once per page — paging was O(N^2) in
+ * the row window. MEASURED on this machine over a 1,553,944-byte 12,001-row xlsx driven
+ * through a real client with `docread.extract` counted by a loader hook: 68 tool calls, **68**
+ * parses, 4.128 s for the walk. After, over the same fixture and the same counter: **1**
+ * parse, 0.104 s (0.103 / 0.108 on two repeats). The committed, rerunnable form of the same
+ * count is `test/document-cache-and-bounds.test.mjs`, at 7 calls rather than 68.
+ *
+ * ONE entry, deliberately, and for the reference's reason. A single entry evicts whenever two
+ * callers alternate between two documents, and that case then costs exactly one parse per
+ * call — which is what the code this replaces cost for EVERY case, so the cache cannot make
+ * any caller slower than it was (`test/document-cache-and-bounds.test.mjs` counts the
+ * alternating walk and pins the number). What more entries would cost is resident memory: a
+ * `Document` holds its whole rendering as strings, bounded per document by
+ * `docread.TEXT_MAX_BYTES` and `docread.XLSX_MAX_TEXT_BYTES` (16 MiB each), and every extra
+ * entry multiplies that ceiling by one.
+ *
+ * **The key is (realpath, size, mtimeNs), and it has one hole — stated, not implied.** A
+ * rewrite that lands inside a single filesystem timestamp tick AND leaves the byte count
+ * unchanged is indistinguishable from no rewrite at all, and would be served from the stale
+ * parse. `mtimeNs` is nanosecond-SHAPED and not nanosecond-GRAINED: what it reports is
+ * whatever the filesystem stored, which on HFS+ is one second and on APFS/ext4 is finer but
+ * not unbounded. The alternative — hashing the bytes — would re-read the file this cache
+ * exists to avoid re-reading, which is the whole cost on the large documents that motivate
+ * it. So the hole stays, and the test that proves the key works changes the SIZE rather than
+ * racing the clock, because a test that raced it would be measuring the filesystem.
+ *
+ * THE CACHED VALUE IS THE RESULT, NEVER A READER. `docread.extract` hands its own `ZipReader`
+ * down to `extractXlsx`/`extractDocx` so an archive is read from disk once instead of twice,
+ * and that reader's lifetime ends with the `extract` call that opened it. This sits one layer
+ * above and holds a finished `Document`; no file handle outlives a call because of it.
+ */
+class DocumentCache {
+    key = null;
+    doc = null;
+    /** The cached document for `key`, or `null` — a `null` key never matches. */
+    get(key) {
+        if (key === null || key !== this.key) {
+            return null;
+        }
+        return this.doc;
+    }
+    put(key, doc) {
+        if (key === null) {
+            return;
+        }
+        this.key = key;
+        this.doc = doc;
+    }
+}
+/**
+ * What identifies the bytes at `path` — or `null`, which means "do not cache".
+ *
+ * `statSync` FOLLOWS symlinks, which is the same file the reader is about to open, and
+ * `{bigint: true}` is not decoration: `Stats.mtimeMs` is a float and has already lost the
+ * sub-millisecond digits the reference's `st_mtime_ns` keeps, so a key built from it would
+ * have a coarser hole than the one documented above. `size` and `mtimeNs` are read from the
+ * bigint view for the same reason.
+ *
+ * Any error here returns `null` rather than refusing: this is a cache key, and the refusal a
+ * caller reads must be the one `docread.extract` raises in the reader's own words, not one
+ * this function invented from a different syscall's errno. That covers the one shape the
+ * reference does not have — `os.path.realpath` is non-strict in CPython and answers even for
+ * a path that does not resolve, while `realpathSync` throws. A path that stats but will not
+ * resolve is therefore uncached here and cached there; nothing a client can observe moves,
+ * because the reply is the reader's either way.
+ */
+function documentKey(path) {
+    try {
+        const stat = statSync(path, { bigint: true });
+        // NUL cannot occur in a path on either platform, so the join is unambiguous.
+        return `${realpathSync(path)}\0${stat.size}\0${stat.mtimeNs}`;
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Run a shiftwork handler and record its `result` — the register's OWN verdict.
  *
@@ -230,7 +311,7 @@ function recordResult(log, tool, call) {
  * byte-compares, and would make the log move when nothing the tool did moved. `noted` and
  * `notedDict` below therefore run last, on the way out.
  */
-function runTool(name, memory, args, version, log) {
+function runTool(name, memory, args, version, log, documents) {
     /**
      * The footer for right now — recomputed per call, never cached.
      *
@@ -403,37 +484,46 @@ function runTool(name, memory, args, version, log) {
             // `document_error` like the encrypted one. Until job43 G2 this arm ran `extract`
             // outside `recordRaise` with a hand-copied catch.
             return recordRaise(log, 'bantamkit_read', () => {
-                let doc;
-                try {
-                    doc = docread.extract(path);
-                }
-                catch (e) {
-                    // `except (docread.DocumentReadError, OSError)`. A Node fs error is CPython's
-                    // `OSError` with the sentence rebuilt by `asPyOSError` — `[Errno 13] Permission
-                    // denied: '<path>'` for a file this process may not open — through the CRT arm,
-                    // because `open()` is the call the reference makes. A `BadZipFile` never reaches
-                    // this arm on either side: `docread.ts`'s `zipKind`/`openZip` catch it exactly
-                    // where `docread.py`'s `_zip_kind`/`_open` do, and what leaves them is the
-                    // sentence naming what the reader saw, never the zip module's.
-                    // A `PyOSError` the reader raised itself is already the reference's sentence —
-                    // `[Errno 22] Invalid argument` from a zip whose member offset is negative, with
-                    // NO filename, because the `seek` that fails there has none. Re-wrapping it would
-                    // append `: '<path>'`.
-                    // ONLY a filesystem rejection is an `OSError`: numeric `errno` AND the `syscall`
-                    // it came from. A string `code` alone is not one — `Z_DATA_ERROR`,
-                    // `ERR_INVALID_ARG_VALUE` and `ERR_STRING_TOO_LONG` all carry one, and until job43
-                    // G2 each was printed as a fabricated `[Errno 0] …` sentence where the reference
-                    // raises (the corrupt stream) or says `no such file` (the NUL byte, which
-                    // `docread.statPath` now answers before this arm is reached).
-                    const refusal = e instanceof docread.DocumentReadError || e instanceof PyOSError
-                        ? e
-                        : isFsError(e)
-                            ? asPyOSError(e, path, undefined, 'crt')
-                            : null;
-                    if (refusal === null)
-                        throw e;
-                    log.record('bantamkit_read', 'refused-unreadable');
-                    return { value: { t: 'str', v: noted(documentError(refusal)) }, wrapped: true };
+                // (i): the parse is cached on (realpath, size, mtimeNs), so a paging walk over one
+                // unchanged document parses it once. `documentKey` answering `null` means "do not
+                // cache" and leaves this arm exactly as it was.
+                const key = documentKey(path);
+                let doc = documents.get(key);
+                if (doc === null) {
+                    try {
+                        doc = docread.extract(path);
+                    }
+                    catch (e) {
+                        // `except (docread.DocumentReadError, OSError)`. A Node fs error is CPython's
+                        // `OSError` with the sentence rebuilt by `asPyOSError` — `[Errno 13] Permission
+                        // denied: '<path>'` for a file this process may not open — through the CRT arm,
+                        // because `open()` is the call the reference makes. A `BadZipFile` never reaches
+                        // this arm on either side: `docread.ts`'s `zipKind`/`openZip` catch it exactly
+                        // where `docread.py`'s `_zip_kind`/`_open` do, and what leaves them is the
+                        // sentence naming what the reader saw, never the zip module's.
+                        // A `PyOSError` the reader raised itself is already the reference's sentence —
+                        // `[Errno 22] Invalid argument` from a zip whose member offset is negative, with
+                        // NO filename, because the `seek` that fails there has none. Re-wrapping it would
+                        // append `: '<path>'`.
+                        // ONLY a filesystem rejection is an `OSError`: numeric `errno` AND the `syscall`
+                        // it came from. A string `code` alone is not one — `Z_DATA_ERROR`,
+                        // `ERR_INVALID_ARG_VALUE` and `ERR_STRING_TOO_LONG` all carry one, and until job43
+                        // G2 each was printed as a fabricated `[Errno 0] …` sentence where the reference
+                        // raises (the corrupt stream) or says `no such file` (the NUL byte, which
+                        // `docread.statPath` now answers before this arm is reached).
+                        const refusal = e instanceof docread.DocumentReadError || e instanceof PyOSError
+                            ? e
+                            : isFsError(e)
+                                ? asPyOSError(e, path, undefined, 'crt')
+                                : null;
+                        if (refusal === null)
+                            throw e;
+                        log.record('bantamkit_read', 'refused-unreadable');
+                        return { value: { t: 'str', v: noted(documentError(refusal)) }, wrapped: true };
+                    }
+                    // A refusal is NOT cached: the entry holds a parse, and a path that has no parse
+                    // must reach the reader again next call so the reply stays the reader's own.
+                    documents.put(key, doc);
                 }
                 const detail = { kind: doc.kind, parts: doc.parts.length };
                 if (part === null) {
@@ -589,6 +679,10 @@ export function buildServer(memory, wire, version, log = EventLog.fromEnv(memory
         },
         instructions: loadSkill('memory'),
     });
+    // Per SERVER, not per process: two servers in one interpreter (the tests build several)
+    // must not answer each other's files, and the entry dies with the server rather than
+    // outliving it in a module global. The reference does the same, inside `build_server`.
+    const documents = new DocumentCache();
     // Startup, not call time: a tool without a manifest, or with the wrong surface, must stop
     // the process before a client ever sees a `tools/list`. The reference gets this from
     // `MCPServer(..., tools=[...])`; here it is one eager pass.
@@ -697,7 +791,7 @@ export function buildServer(memory, wire, version, log = EventLog.fromEnv(memory
             if (model === undefined)
                 throw new BantamError(`Unknown tool: ${name}`);
             const bound = validateArguments(model, args);
-            const { value, wrapped } = runTool(name, memory, bound, version, log);
+            const { value, wrapped } = runTool(name, memory, bound, version, log, documents);
             // `_convert_to_content` runs BEFORE the `{"result": ...}` wrap, so a str tool's text
             // block is the RAW STRING and a dict tool's is `to_json(..., indent=2)`.
             text = value.t === 'str' ? value.v : sdkJson(value, 2);

package/dist/memory/cli.js

@@ -67,7 +67,7 @@
 import { BantamError } from '../errors.js';
 import { ArgumentTypeError, ArgvError, formatHelp, formatUsageBlock, HelpRequested, helpWidth, parseArgs, pyIntStrict, } from '../pyargparse.js';
 import { discoverProjectStore } from './layers.js';
-import { pyJoin } from './pyfs.js';
+import { pyJoin, PyOSError } from './pyfs.js';
 import { DEFAULT_INDEX_BUDGET, MemoryBudgetExceeded, MemoryStore, MemoryValidationError, pyText, } from './store.js';
 /** The Node operator's spelling of the reference's `python -m bantamkit.memory`. */
 const PROG = 'bantamkit-memory';
@@ -314,6 +314,40 @@ function cmdArchived(store) {
         out(`  ${name}`);
     return 0;
 }
+/**
+ * job44 (y): an uncaught OS exception used to reach the operator here as a raw stack trace.
+ * Measured 2026-09-05 on macOS, both entrances: `archive/` at 0o555 (the guards pass,
+ * `pyMkdirParents` is a no-op on a directory that is already there, and the MOVE is refused)
+ * and `index.md` as a directory (the move succeeds, `rebuildIndex` raises, the rollback
+ * restores the store correctly, and the exception then escapes `main` the same way). Both
+ * already exited 1 — Node's default for an uncaught exception — so only the TEXT differed:
+ * a `node:fs` / `pyfs.js` stack ending in `PyOSError` here, a CPython traceback ending in
+ * `PermissionError: [Errno 13]` on the reference. `PyOSError` does not extend `BantamError`,
+ * so it reached neither this catch nor the top-level `BantamError` arm below — it fell all
+ * the way to `throw error` and out of the process.
+ *
+ * THE SENTENCE DELIBERATELY DOES NOT INTERPOLATE THE UNDERLYING ERROR, the same reason
+ * `cmdLint`'s budget sentence is not the store's own message: `PyOSError`'s text is a
+ * translation of Node's `errno`/`code`, and `OSError`'s is CPython's `strerror` — the two
+ * are never going to read the same, so printing either would just move the divergence from
+ * a stack trace into a sentence. RECONCILED WITH U7's published wording (job44 handoff).
+ *
+ * "NOTHING UNDER `store.root` CHANGED" IS A CLAIM, NOT A FLOURISH, and it was FALSE on the
+ * reference until U7's own reconciliation: `restore`'s final `_rebuild_index()` used to sit
+ * OUTSIDE its only `try`, so the same `index.md`-is-a-directory fault this comment describes
+ * left a restored fact stuck in `facts/`, gone from `archive/`, with no rollback at all.
+ * MEASURED the same way on this side before printing this sentence, not reasoned from the
+ * code shape: driving that exact fault against the pre-reconciliation `restore` here left
+ * `facts/alpha.md` present and `archive/` empty afterwards — the same hole, open on both
+ * runtimes. `restore`'s two-step tail is now ONE `try` (`checkIndexBudget` and the closing
+ * `rebuildIndex` together) for exactly that reason, so this sentence is true when it prints.
+ * `archive` never had the hole — its one write step was inside its only `try` from the start
+ * — and is untouched by that fix.
+ */
+function osErrorSentence(command, name, store) {
+    return (`${command} failed: a filesystem error stopped the move of '${name}'; ` +
+        `nothing under ${store.root} changed`);
+}
 function cmdArchive(store, args) {
     try {
         store.archive(args.name);
@@ -323,6 +357,10 @@ function cmdArchive(store, args) {
             err(`archive failed: ${error.message}`);
             return 1;
         }
+        if (error instanceof PyOSError) {
+            err(osErrorSentence('archive', args.name, store));
+            return 1;
+        }
         throw error;
     }
     out(`archived '${args.name}' — index now ${size(store)}/${store.indexBudget} bytes`);
@@ -342,6 +380,10 @@ function cmdRestore(store, args) {
             err(`restore failed: ${error.message}`);
             return 1;
         }
+        if (error instanceof PyOSError) {
+            err(osErrorSentence('restore', args.name, store));
+            return 1;
+        }
         throw error;
     }
     out(`restored '${args.name}' — index now ${size(store)}/${store.indexBudget} bytes`);

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

@@ -330,6 +330,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.