bantamkit-mcp 0.29.0 → 0.29.2

package/dist/memory/store.js

@@ -742,28 +742,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.

package/dist/pysem.d.ts

@@ -0,0 +1,81 @@
+/**
+ * CPython string semantics this runtime needs in more than one place, written ONCE.
+ *
+ * `docs/roadmap-toolbox.md` row 8, entry (n): `pyStrip`, `cmpCodepoint` and `pyRepr` had each
+ * been ported twice — once in `docread.ts` and once under `memory/` — as independent
+ * re-derivations of the same three CPython behaviours. Two implementations of one semantic are
+ * two chances to be right and one certainty of drifting, and neither copy had a test that
+ * compared it to the other.
+ *
+ * **The pairs were diffed before they were merged**, because unifying two functions that are
+ * not the same function is a behaviour change wearing a refactor's clothes:
+ *
+ * * `pyStrip` — the two agreed on the set of characters `str.isspace()` is true for (29 each,
+ *   with an empty symmetric difference over all 1,114,112 codepoints) and on 200,000 random
+ *   strings built from that alphabet. Kept: the REGEX spelling, because the set-based one
+ *   spreads the whole string into an array of characters first, and this is called once per
+ *   rendered row.
+ * * `pyRepr` — byte-identical output on every one of the 1,114,112 codepoints and on a pool of
+ *   quoting edge cases. `docread`'s explicit `Cc|Cf|Cs|Co|Cn|Zl|Zp|Zs` class and `memory`'s
+ *   `\p{C}|\p{Z}` are the same set spelled two ways. Kept: the precompiled class.
+ * * `cmpCodepoint` — the same ORDER on every pair (0 sign disagreements), and different
+ *   NUMBERS: `docread`'s returned the codepoint difference and the `memory` copy returns
+ *   -1/0/1, so `cmp('', 'ab')` was -1 there and -2 here. Kept: the `memory` spelling to the
+ *   digit, because every importer outside `docread.ts` already sees those numbers, while
+ *   `docread`'s copy had no importer at all and one use — `Array.prototype.sort`, which reads
+ *   the sign and nothing else.
+ *
+ * **A THIRD COPY SURVIVED THAT CLOSURE AND WAS FOLDED IN ON 2026-09-06 (job44, unit F4).**
+ * "written ONCE" was not true when it was written: entry (n) named `docread.ts` and `memory/`
+ * and nothing else, so `skillaudit.ts` — product surface, the eleventh MCP tool — kept its own
+ * `pyStrip` on a 29-codepoint Set and its own `cmpCodepoint` in the `cx - cy` spelling, the two
+ * this module had just rejected. Both now import from here, gated first by the same method:
+ * an empty symmetric difference between the two whitespace sets over every codepoint, 0
+ * disagreements on `pyStrip` over 200,000 random strings, 0 disagreements on a
+ * `` `^${PY_WS_CLASS}` `` regex against that module's Set-membership `startsWithSpace` over
+ * every codepoint, and — the reason the gate is not optional — `cmpCodepoint` agreeing on SIGN
+ * in all of 324 exhaustive plus 200,000 random pairs while disagreeing on the NUMBER in
+ * 167,851 of them. `skillaudit.ts`'s six uses read the sign alone, which is what made the
+ * substitution safe; its header carries the reading and the caveat.
+ *
+ * Nothing here is re-exported from `index.ts`: the names stay exported from the modules that
+ * always exported them, so this is a delegation and not a surface change.
+ */
+/**
+ * The characters `str.isspace()` is true for — what `strip()` and `split()` consume.
+ *
+ * NOT `String.prototype.trim()`'s set. Measured over all 0x110000 codepoints: Python strips 29,
+ * JS strips 25, and the two 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 memory store then compares, hashes and diffs; in
+ * `docread` the same six decide whether a row is blank.
+ */
+export declare const PY_WS = "\t\n\v\f\r\u001C\u001D\u001E\u001F \u0085\u00A0\u1680\u2000\u2001\u2002\u2003\u2004\u2005\u2006\u2007\u2008\u2009\u200A\u2028\u2029\u202F\u205F\u3000";
+/** `PY_WS` as a character class, with the four characters a class gives meaning escaped. */
+export declare const PY_WS_CLASS: string;
+/** `str.strip()` with no argument. */
+export declare function pyStrip(s: string): string;
+/**
+ * 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. In
+ * `docread` the same order decides which omission reason is rendered first.
+ */
+export declare function cmpCodepoint(a: string, b: string): number;
+/**
+ * `repr(str)` — the refusal sentences' quoting, and `_pinned_store`'s `{raw!r}`.
+ *
+ * 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. The escapes are
+ * `\xNN` below U+0100, `\uNNNN` below U+10000, `\UNNNNNNNN` above.
+ *
+ * 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 path made of
+ * brand-new codepoints is the only input that reaches it.
+ */
+export declare function pyRepr(s: string): string;

package/dist/pysem.js

@@ -0,0 +1,126 @@
+/**
+ * CPython string semantics this runtime needs in more than one place, written ONCE.
+ *
+ * `docs/roadmap-toolbox.md` row 8, entry (n): `pyStrip`, `cmpCodepoint` and `pyRepr` had each
+ * been ported twice — once in `docread.ts` and once under `memory/` — as independent
+ * re-derivations of the same three CPython behaviours. Two implementations of one semantic are
+ * two chances to be right and one certainty of drifting, and neither copy had a test that
+ * compared it to the other.
+ *
+ * **The pairs were diffed before they were merged**, because unifying two functions that are
+ * not the same function is a behaviour change wearing a refactor's clothes:
+ *
+ * * `pyStrip` — the two agreed on the set of characters `str.isspace()` is true for (29 each,
+ *   with an empty symmetric difference over all 1,114,112 codepoints) and on 200,000 random
+ *   strings built from that alphabet. Kept: the REGEX spelling, because the set-based one
+ *   spreads the whole string into an array of characters first, and this is called once per
+ *   rendered row.
+ * * `pyRepr` — byte-identical output on every one of the 1,114,112 codepoints and on a pool of
+ *   quoting edge cases. `docread`'s explicit `Cc|Cf|Cs|Co|Cn|Zl|Zp|Zs` class and `memory`'s
+ *   `\p{C}|\p{Z}` are the same set spelled two ways. Kept: the precompiled class.
+ * * `cmpCodepoint` — the same ORDER on every pair (0 sign disagreements), and different
+ *   NUMBERS: `docread`'s returned the codepoint difference and the `memory` copy returns
+ *   -1/0/1, so `cmp('', 'ab')` was -1 there and -2 here. Kept: the `memory` spelling to the
+ *   digit, because every importer outside `docread.ts` already sees those numbers, while
+ *   `docread`'s copy had no importer at all and one use — `Array.prototype.sort`, which reads
+ *   the sign and nothing else.
+ *
+ * **A THIRD COPY SURVIVED THAT CLOSURE AND WAS FOLDED IN ON 2026-09-06 (job44, unit F4).**
+ * "written ONCE" was not true when it was written: entry (n) named `docread.ts` and `memory/`
+ * and nothing else, so `skillaudit.ts` — product surface, the eleventh MCP tool — kept its own
+ * `pyStrip` on a 29-codepoint Set and its own `cmpCodepoint` in the `cx - cy` spelling, the two
+ * this module had just rejected. Both now import from here, gated first by the same method:
+ * an empty symmetric difference between the two whitespace sets over every codepoint, 0
+ * disagreements on `pyStrip` over 200,000 random strings, 0 disagreements on a
+ * `` `^${PY_WS_CLASS}` `` regex against that module's Set-membership `startsWithSpace` over
+ * every codepoint, and — the reason the gate is not optional — `cmpCodepoint` agreeing on SIGN
+ * in all of 324 exhaustive plus 200,000 random pairs while disagreeing on the NUMBER in
+ * 167,851 of them. `skillaudit.ts`'s six uses read the sign alone, which is what made the
+ * substitution safe; its header carries the reading and the caveat.
+ *
+ * Nothing here is re-exported from `index.ts`: the names stay exported from the modules that
+ * always exported them, so this is a delegation and not a surface change.
+ */
+// ------------------------------------------------------------------------- str.strip()
+/**
+ * The characters `str.isspace()` is true for — what `strip()` and `split()` consume.
+ *
+ * NOT `String.prototype.trim()`'s set. Measured over all 0x110000 codepoints: Python strips 29,
+ * JS strips 25, and the two 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 memory store then compares, hashes and diffs; in
+ * `docread` the same six decide whether a row is blank.
+ */
+export const PY_WS = '\t\n\x0b\x0c\r\x1c\x1d\x1e\x1f \x85\xa0            

  　';
+/** `PY_WS` as a character class, with the four characters a class gives meaning escaped. */
+export const PY_WS_CLASS = `[${PY_WS.replace(/[\]\\^-]/g, '\\$&')}]`;
+const PY_STRIP = new RegExp(`^${PY_WS_CLASS}+|${PY_WS_CLASS}+$`, 'g');
+/** `str.strip()` with no argument. */
+export function pyStrip(s) {
+    return s.replace(PY_STRIP, '');
+}
+// ------------------------------------------------------------------------ sorted() on str
+/**
+ * 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. In
+ * `docread` the same order decides which omission reason is rendered first.
+ */
+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;
+}
+// ---------------------------------------------------------------------------- repr(str)
+// `str.isprintable()` is false for these categories (space itself excepted). Precompiled: the
+// refusal sentences build one of these per character of a path.
+const NONPRINTABLE = /[\p{Cc}\p{Cf}\p{Cs}\p{Co}\p{Cn}\p{Zl}\p{Zp}\p{Zs}]/u;
+/**
+ * `repr(str)` — the refusal sentences' quoting, and `_pinned_store`'s `{raw!r}`.
+ *
+ * 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. The escapes are
+ * `\xNN` below U+0100, `\uNNNN` below U+10000, `\UNNNNNNNN` above.
+ *
+ * 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 path made of
+ * brand-new codepoints is the only input that reaches it.
+ */
+export function pyRepr(s) {
+    const quote = s.includes("'") && !s.includes('"') ? '"' : "'";
+    let out = quote;
+    for (const ch of s) {
+        const code = ch.codePointAt(0);
+        if (ch === quote || ch === '\\')
+            out += '\\' + ch;
+        else if (ch === '\t')
+            out += '\\t';
+        else if (ch === '\n')
+            out += '\\n';
+        else if (ch === '\r')
+            out += '\\r';
+        else if (ch !== ' ' && NONPRINTABLE.test(ch)) {
+            if (code < 0x100)
+                out += '\\x' + code.toString(16).padStart(2, '0');
+            else if (code < 0x10000)
+                out += '\\u' + code.toString(16).padStart(4, '0');
+            else
+                out += '\\U' + code.toString(16).padStart(8, '0');
+        }
+        else
+            out += ch;
+    }
+    return out + quote;
+}

package/dist/skillaudit.js

@@ -72,6 +72,7 @@
 import { readdirSync, readFileSync, statSync } from 'node:fs';
 import { basename, dirname, join } from 'node:path';
 import { BantamError } from './errors.js';
+import { cmpCodepoint, PY_WS_CLASS, pyStrip } from './pysem.js';
 import { reprValue } from './pyjson.js';
 // The file a skill IS. Case-sensitive: the host loads this name and so does this reader.
 export const SKILL_FILE = 'SKILL.md';
@@ -168,47 +169,39 @@ export class SkillAuditError extends BantamError {
 }
 // -------------------------------------------------------------- Python string semantics
 /**
- * `str.strip()`, which is NOT `String.prototype.trim()` — measured, they disagree on six
- * code points (`memory/factfile.ts`). A frontmatter line's indent is stripped with this.
+ * `str.strip()` and `sorted()`'s order are `pysem.ts`'s, and no longer a third copy.
+ *
+ * This module carried its own `pyStrip` (a `PY_SPACE` Set of 29 codepoints, spread over
+ * `[...text]`) and its own `cmpCodepoint` (paired iterators returning `cx - cy`) —
+ * independently re-derived, and the two spellings `pysem.ts` explicitly REJECTED when it
+ * unified `docread.ts`'s and `memory/`'s copies for `docs/roadmap-toolbox.md` row 8, entry
+ * (n). That entry named only those two homes, so this third copy survived its closure while
+ * `pysem.ts`'s header claimed the semantics were written ONCE.
+ *
+ * **The pairs were gated before they were merged** (2026-09-06, job44 unit F4, the method U2
+ * used, against `dist/pysem.js` with this module's two functions transcribed beside it):
+ *
+ * * the SET — 29 codepoints on each side, and an EMPTY symmetric difference walking every
+ *   codepoint from 0 to 0x10FFFF, surrogates skipped;
+ * * `pyStrip` — 0 disagreements over 200,000 random strings built from the union alphabet
+ *   plus `a Z 0 U+1F414 U+FEFF U+200B U+FF1A` as non-space padding (the last three are the
+ *   characters `String.prototype.trim()` and `str.strip()` argue about);
+ * * `startsWithSpace` — 0 disagreements against `` new RegExp(`^${PY_WS_CLASS}`) `` over
+ *   eight hand-picked shapes AND over `String.fromCodePoint(cp) + 'x'` for every codepoint,
+ *   which is what lets the Set membership test below become a regex test;
+ * * `cmpCodepoint` — **0 sign disagreements** over 324 exhaustive pairs and 200,000 random
+ *   astral-bearing pairs, and **167,851 NUMBER disagreements** in the same run, the first
+ *   being `cmp('', 'ab')`: `-1` in the spelling deleted here, `-2` in `pysem.ts`'s. Same
+ *   order, different function. Safe only because every one of this module's six uses reads
+ *   the sign alone — `cmpParts` (`!== 0`, and itself only ever a `.sort` comparator), the
+ *   `> 0` version pick, and four bare `.sort()` calls — so the numbers were never observable
+ *   from here. A future use that subtracts or scales one of these values is NOT covered by
+ *   that argument and would have to re-establish it.
  */
-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,
-]);
-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('');
-}
 /** `line[:1].isspace()`: whether the line is a FOLD rather than a key. */
+const STARTS_WITH_PY_SPACE = new RegExp(`^${PY_WS_CLASS}`);
 function startsWithSpace(line) {
-    const first = line.codePointAt(0);
-    return first !== undefined && PY_SPACE.has(first);
-}
-/** `sorted()` on strings: by code point, which is not what `Array.sort` does above U+FFFF. */
-function cmpCodepoint(a, b) {
-    const ia = a[Symbol.iterator]();
-    const ib = b[Symbol.iterator]();
-    for (;;) {
-        const x = ia.next();
-        const y = ib.next();
-        if (x.done && y.done)
-            return 0;
-        if (x.done)
-            return -1;
-        if (y.done)
-            return 1;
-        const cx = x.value.codePointAt(0);
-        const cy = y.value.codePointAt(0);
-        if (cx !== cy)
-            return cx - cy;
-    }
+    return STARTS_WITH_PY_SPACE.test(line);
 }
 /** `sorted(paths, key=lambda p: p.parts)`: a tuple comparison, segment by segment. */
 function cmpParts(a, b) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bantamkit-mcp",
-  "version": "0.29.0",
+  "version": "0.29.2",
   "description": "bantamkit MCP server — pure Node, runnable with npx",
   "type": "module",
   "bin": {
@@ -20,7 +20,7 @@
     "assets"
   ],
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",