bantamkit-mcp 0.26.0

package/dist/memory/factfile.js

@@ -0,0 +1,406 @@
+/**
+ * The fact-file codec: the bytes on disk under `<store>/facts/<name>.md`, both directions.
+ *
+ * A port of `_write_fact` and the frontmatter half of `_facts` in
+ * `runtime-py/src/bantamkit/memory/store.py`. The store itself — `save`, `recall`, the
+ * index, scoring, the budget — is NOT here.
+ *
+ * THE PROPERTY THIS FILE OWES
+ * ---------------------------
+ * For every fact, the bytes Node writes and the bytes Python writes are identical, and
+ * each runtime parses what the other wrote. Both directions matter: the live store already
+ * contains 65 files Python wrote, and `_stamp` rewrites a file on every recall hit, so a
+ * Node server re-emits Python's files constantly. The differential that proves it runs in
+ * `tools/conformance/suites/codec.mjs`; the shapes are pinned in `test/codec.test.mjs`.
+ */
+import { constructPlain, PyScalar, safeDumpMapping } from './pyyaml.js';
+export class FactParseError extends Error {
+}
+// ------------------------------------------------------------------------ whitespace
+/**
+ * `str.strip()`, which is NOT `String.prototype.trim()`.
+ *
+ * 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.
+ */
+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('');
+}
+/**
+ * The bytes of a fact file as Python's `Path.read_text(encoding="utf-8")` sees them.
+ *
+ * Text mode applies universal-newline translation: `\r\n` and a lone `\r` both become
+ * `\n`. `readFileSync(p, 'utf8')` does not. Measured in the prep probe: a CRLF fact file
+ * splits into 3 frontmatter parts in Python and 1 in Node, so without this the Node store
+ * calls a file malformed that the Python store reads fine.
+ *
+ * The WRITE side deliberately does not mirror Python. See `formatFact`.
+ */
+export function decodeFactBytes(bytes) {
+    return new TextDecoder('utf-8').decode(bytes).replace(/\r\n?/g, '\n');
+}
+// ----------------------------------------------------------------------------- encode
+/**
+ * The exact bytes `_write_fact` writes, as a string.
+ *
+ * RULING — NEWLINES ON THE WAY OUT. Python opens the file in text mode with
+ * `newline=None`, which translates `\n` to `os.linesep`, so on Windows every fact file
+ * Python writes is CRLF while every byte count the store computes (the index budget, the
+ * digests) is LF. This port writes LF on every platform and does not reproduce that.
+ * Reasons, in order: the CRLF is incidental to `newline=None` rather than intended; it
+ * already disagrees with the store's own arithmetic; and reproducing it would make the
+ * same Fact emit different bytes on two machines, which is precisely the property this
+ * port exists to hold. Reading stays universal-newline on both sides, so a store written
+ * by either runtime is read identically by both. On macOS and Linux `os.linesep` is `\n`
+ * and there is no divergence at all — the conformance suite measures byte identity there.
+ */
+export function formatFact(fact) {
+    const front = safeDumpMapping([
+        ['name', fact.name],
+        ['description', fact.description],
+        ['type', fact.type],
+        ['created', fact.created ?? null],
+        ['last_recalled', fact.last_recalled ?? null],
+        ['links', fact.links],
+    ]);
+    return '---\n' + front + '---\n\n' + pyStrip(fact.body) + '\n';
+}
+// ----------------------------------------------------------------------------- decode
+/**
+ * `text.split("---\n", 2)` plus `yaml.safe_load(front)`, and the `body.strip()` after it.
+ *
+ * Python unpacks the split into three names, so fewer than three parts is a `ValueError`
+ * that `_facts` turns into `MemoryValidationError`. Here it is a `FactParseError`; the
+ * sentence the model finally sees is the store's to phrase, not this module's.
+ */
+export function parseFactText(text) {
+    const parts = pySplit(text, '---\n', 2);
+    if (parts.length !== 3) {
+        throw new FactParseError(`expected 3 parts from split('---\\n', 2), got ${parts.length}`);
+    }
+    return { meta: parseFrontmatter(parts[1]), body: pyStrip(parts[2]) };
+}
+/**
+ * `str.split(sep, maxsplit)` — JS's `String.split` has no maxsplit and would over-split.
+ *
+ * Exported because `store._facts` does this split ITSELF in the reference, and needs the
+ * part count to build Python's own `ValueError` text for a truncated file. Two spellings of
+ * one split is how the two would drift.
+ */
+export function pySplit(text, sep, maxsplit) {
+    const out = [];
+    let from = 0;
+    while (out.length < maxsplit) {
+        const at = text.indexOf(sep, from);
+        if (at === -1)
+            break;
+        out.push(text.slice(from, at));
+        from = at + sep.length;
+    }
+    out.push(text.slice(from));
+    return out;
+}
+/**
+ * The frontmatter mapping, for the language `safeDumpMapping` emits and no more.
+ *
+ * RULING — SCOPE. This is not a YAML parser and does not try to be. It accepts a
+ * root-level block mapping of plain keys whose values are plain, single-quoted or
+ * double-quoted scalars (wrapped or not), `[]`, or a block sequence of such scalars at
+ * column 0 — which is exactly what PyYAML emits for a `Fact` at these dump settings.
+ * Anything else RAISES instead of guessing. The reason is the failure mode this whole unit
+ * exists for: a parser that silently produces something plausible for input it does not
+ * understand turns a hand-edited fact file into a wrong `Fact`, and nothing anywhere
+ * reports it. A raise is visible; `_facts` already has a sentence for it.
+ *
+ * KNOWN NON-IDENTICAL BEHAVIOUR, registered rather than hidden: for input outside that
+ * language, Python and Node both fail but with different message text (PyYAML's scanner
+ * error vs this module's). `_facts` interpolates that text into
+ * `malformed fact file {name}: {e}`, so the string a model sees for a corrupt file is not
+ * byte-identical across runtimes. Making it identical would mean porting PyYAML's scanner
+ * diagnostics, which is a far larger surface than the codec, and no test in
+ * `runtime-py/tests` pins those strings. Owner: whichever unit takes `_facts`.
+ */
+export function parseFrontmatter(front) {
+    const meta = {};
+    let pos = 0;
+    while (pos < front.length) {
+        const key = /^([A-Za-z_][A-Za-z0-9_-]*):/.exec(front.slice(pos, front.indexOf('\n', pos) + 1 || undefined));
+        if (!key) {
+            throw new FactParseError(`frontmatter line is not a plain "key:" mapping entry: ${line(front, pos)}`);
+        }
+        pos += key[0].length;
+        let value;
+        if (front[pos] === '\n') {
+            pos += 1;
+            if (/^-(?: |\n|$)/.test(front.slice(pos))) {
+                [value, pos] = scanBlockSequence(front, pos);
+            }
+            else {
+                value = null; // `key:` with nothing after it is null in YAML
+            }
+        }
+        else if (front[pos] === ' ') {
+            pos += 1;
+            [value, pos] = scanNode(front, pos);
+            if (pos < front.length && front[pos] !== '\n') {
+                throw new FactParseError(`trailing content after the value of "${key[1]}": ${line(front, pos)}`);
+            }
+            pos += 1;
+        }
+        else {
+            throw new FactParseError(`expected " " or end of line after "${key[1]}:"`);
+        }
+        meta[key[1]] = value;
+    }
+    return meta;
+}
+function line(text, pos) {
+    const end = text.indexOf('\n', pos);
+    return JSON.stringify(text.slice(pos, end === -1 ? undefined : end));
+}
+/** A single-line-or-wrapped scalar starting at `pos`. Returns the value and the index after it. */
+function scanNode(front, pos) {
+    const ch = front[pos];
+    if (ch === "'")
+        return scanQuoted(front, pos, "'");
+    if (ch === '"')
+        return scanQuoted(front, pos, '"');
+    if (ch === '[') {
+        const m = /^\[\s*\]/.exec(front.slice(pos));
+        if (!m) {
+            throw new FactParseError(`only the empty flow sequence "[]" is in this codec's language: ${line(front, pos)}`);
+        }
+        return [[], pos + m[0].length];
+    }
+    return scanPlain(front, pos);
+}
+/**
+ * A plain scalar and its wrapped continuation lines.
+ *
+ * A continuation line is one that starts with a space; a new mapping key and a sequence
+ * dash both sit at column 0, so nothing else is needed to find the end. Line breaks fold
+ * to a single space, which is the inverse of the emitter dropping the space it broke at.
+ */
+function scanPlain(front, pos) {
+    const pieces = [];
+    let i = pos;
+    for (;;) {
+        const eol = front.indexOf('\n', i);
+        const raw = eol === -1 ? front.slice(i) : front.slice(i, eol);
+        // A ` #` starts a comment in a plain scalar. PyYAML's emitter never produces one — it
+        // quotes instead — so this only matters for a hand-edited file, where matching what
+        // Python reads is the point.
+        const hash = raw.indexOf(' #');
+        const cut = hash === -1 ? raw : raw.slice(0, hash);
+        const piece = cut.replace(/[ \t]+$/, '').replace(/^[ \t]+/, '');
+        if (pieces.length > 0 && piece === '') {
+            throw new FactParseError('a blank line inside a plain scalar is outside this codec\'s language');
+        }
+        pieces.push(piece);
+        const next = eol === -1 ? front.length : eol + 1;
+        if (hash !== -1) {
+            // The comment ran to end of line; the value ends here.
+            i = eol === -1 ? front.length : eol;
+            break;
+        }
+        if (next >= front.length || front[next] !== ' ') {
+            i = eol === -1 ? front.length : eol;
+            break;
+        }
+        i = next;
+    }
+    const value = pieces.join(' ');
+    if (/(^|[ \t]):([ \t]|$)/.test(value)) {
+        throw new FactParseError(`a plain scalar containing ": " is not readable YAML — PyYAML rejects it too: ${JSON.stringify(value)}`);
+    }
+    return [resolvePlain(value), i];
+}
+/**
+ * RULING — WHAT A PLAIN SCALAR RESOLVES TO. Decided by N10; the reason the old ruling stood
+ * on was measured false by N8 and is deleted with the behaviour it justified.
+ *
+ * PyYAML resolves a plain scalar by pattern, so a hand-edited `created: 2026-08-23` comes
+ * back as a `datetime.date` and `links:\n- 12` as an `int`. This function used to RAISE for
+ * every tag but `str` and `null`, on the belief — written into the comment as if it were a
+ * ruling — that Python "reaches the model as a `TypeError` several frames away". It does
+ * not. Measured against the reference over 26 shapes, CPython raises on FOUR (three
+ * out-of-range timestamps and the two constructor-less tags) and answers on the rest: it
+ * interpolates the value, writes a working `index.md` line, answers `memory_recall`, stamps
+ * the file and accepts the next `memory_save`. A bare `created: 2026-08-23` round-trips
+ * through `_stamp` unquoted.
+ *
+ * What the raise COST was not a wrong sentence, it was the store: one such file made
+ * `memory_recall`, `memory_save` and the index rebuild all raise `MemoryValidationError`
+ * naming that one file, while a Python server bound to the same directory kept working.
+ * Fact files are Markdown a human is invited to edit, so the shape is reachable — 13 of 17
+ * scalar shapes N8 tried did it. Nothing this codec WRITES is affected: every value it
+ * emits is quoted when quoting is what keeps the tag.
+ *
+ * So: `constructPlain` builds what `SafeConstructor` builds, and the store renders it with
+ * `pyText`. The full width — which tags are constructed, which raise, and the three shapes
+ * where CPython and this codec genuinely disagree because this codec has no SCANNER — is
+ * written at `constructPlain` in `pyyaml.ts` and re-measured by the `frontmatter scalar`
+ * scenarios in `tools/conformance/suites/store.mjs` on every run.
+ */
+function resolvePlain(value) {
+    // The constructor lives with the emitter and the resolver: the quoting decision on the
+    // way out is the same question this asks on the way in.
+    return constructPlain(value);
+}
+/**
+ * A quoted scalar, from its opening quote to its closing one, across as many lines as it
+ * takes. Line folding is YAML's: one break becomes a space, n>1 breaks become n-1
+ * newlines, and whitespace either side of a break is dropped. That is the exact inverse of
+ * `write_single_quoted`'s `breaks` arm, which emits one extra break so that a `\n` in the
+ * value survives as a blank line on disk.
+ */
+function scanQuoted(front, pos, quote) {
+    const out = [];
+    let i = pos + 1;
+    for (;;) {
+        if (i >= front.length) {
+            throw new FactParseError(`unterminated ${quote === "'" ? 'single' : 'double'}-quoted scalar`);
+        }
+        const ch = front[i];
+        if (ch === quote) {
+            if (quote === "'" && front[i + 1] === "'") {
+                out.push("'");
+                i += 2;
+                continue;
+            }
+            return [out.join(''), i + 1];
+        }
+        if (quote === '"' && ch === '\\') {
+            const next = front[i + 1];
+            if (next === '\n') {
+                // An escaped line break contributes nothing, and the indent after it is not content.
+                i += 2;
+                while (front[i] === ' ' || front[i] === '\t')
+                    i += 1;
+                continue;
+            }
+            const [text, used] = unescape(front, i);
+            out.push(text);
+            i += used;
+            continue;
+        }
+        if (ch === '\n') {
+            while (out.length > 0 && /^[ \t]$/.test(out[out.length - 1]))
+                out.pop();
+            let breaks = 0;
+            while (front[i] === '\n') {
+                breaks += 1;
+                i += 1;
+                while (front[i] === ' ' || front[i] === '\t')
+                    i += 1;
+            }
+            out.push(breaks === 1 ? ' ' : '\n'.repeat(breaks - 1));
+            continue;
+        }
+        out.push(ch);
+        i += 1;
+    }
+}
+/** The reader's half of `ESCAPE_REPLACEMENTS`, plus the numeric escapes. */
+const UNESCAPE = new Map([
+    ['0', '\0'],
+    ['a', '\x07'],
+    ['b', '\b'],
+    ['t', '\t'],
+    ['\t', '\t'],
+    ['n', '\n'],
+    ['v', '\v'],
+    ['f', '\f'],
+    ['r', '\r'],
+    ['e', '\x1b'],
+    [' ', ' '],
+    ['"', '"'],
+    ['/', '/'],
+    ['\\', '\\'],
+    ['N', '\x85'],
+    ['_', '\xa0'],
+    ['L', '\u2028'],
+    ['P', '\u2029'],
+]);
+const NUMERIC_ESCAPE = { x: 2, u: 4, U: 8 };
+function unescape(front, at) {
+    const code = front[at + 1];
+    if (code === undefined)
+        throw new FactParseError('a double-quoted scalar ends in a backslash');
+    const simple = UNESCAPE.get(code);
+    if (simple !== undefined)
+        return [simple, 2];
+    const width = NUMERIC_ESCAPE[code];
+    if (width === undefined)
+        throw new FactParseError(`unknown escape \\${code}`);
+    const digits = front.slice(at + 2, at + 2 + width);
+    if (!new RegExp(`^[0-9A-Fa-f]{${width}}$`).test(digits)) {
+        throw new FactParseError(`malformed \\${code} escape: ${JSON.stringify(digits)}`);
+    }
+    return [String.fromCodePoint(parseInt(digits, 16)), 2 + width];
+}
+/**
+ * A block sequence whose dashes are at column 0 — the only shape PyYAML emits here.
+ *
+ * An item resolves exactly as a mapping value does, so `links:\n- 12` is a one-element list
+ * holding an `int` in both runtimes. It used to raise `a sequence item must be a string`,
+ * which took the whole store down for a file Python read.
+ */
+function scanBlockSequence(front, pos) {
+    const items = [];
+    let i = pos;
+    while (i < front.length && front[i] === '-') {
+        if (front[i + 1] === '\n' || i + 1 === front.length) {
+            // `- ` with nothing after it is a null item, which `list()` keeps and `represent_none`
+            // writes back as `- null`. Python has no complaint about it, so neither does this.
+            items.push(null);
+            i += 2;
+            continue;
+        }
+        if (front[i + 1] !== ' ') {
+            throw new FactParseError(`expected "- " at the start of a sequence item: ${line(front, i)}`);
+        }
+        const [value, next] = scanNode(front, i + 2);
+        if (Array.isArray(value)) {
+            // A nested block sequence is outside the emitter's language and outside this codec's.
+            throw new FactParseError('a nested sequence item is not in this codec\'s language');
+        }
+        items.push(value);
+        if (next < front.length && front[next] !== '\n') {
+            throw new FactParseError(`trailing content after a sequence item: ${line(front, next)}`);
+        }
+        i = next + 1;
+    }
+    return [items, i];
+}
+// ------------------------------------------------------------------------------ clock
+/**
+ * `date.today().isoformat()`, which is LOCAL.
+ *
+ * `new Date().toISOString().slice(0, 10)` is UTC and is a different date for part of every
+ * day — measured against CPython under four zones and twelve instants, the local getters
+ * agreed in all twelve and the UTC slice disagreed in four. `created` and `last_recalled`
+ * are written with this, while shift-work's `ts` is UTC; they are not the same clock and
+ * the store must not borrow one for the other.
+ *
+ * The parameter exists so a caller can freeze it. Every comparison against Python is
+ * otherwise a race across midnight, and `_stamp` fires on every recall hit.
+ */
+export function todayLocal(now = new Date()) {
+    const pad = (n, w = 2) => String(n).padStart(w, '0');
+    return `${pad(now.getFullYear(), 4)}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}`;
+}

package/dist/memory/layers.d.ts

@@ -0,0 +1,92 @@
+/** `Path(".bantamkit") / "memory"`, kept as its components so `pyJoin` builds it. */
+export declare const PROJECT_STORE: readonly string[];
+export declare const CONFIG_NAME = "config.yaml";
+/**
+ * The operator's one lever over binding, and the only one they actually hold: an MCP
+ * server's cwd is chosen by the HOST, not by the user, so every rule derived from cwd is a
+ * rule the operator cannot control. The name is spelled here and nowhere else — including in
+ * the tests and in the sentences `component.Memory` builds — because a magic string
+ * duplicated between a resolver and its message is how the two come to name different
+ * variables.
+ */
+export declare const MEMORY_DIR_ENV = "BANTAMKIT_MEMORY_DIR";
+/**
+ * Which store the walk bound to, and whether that store can answer at all.
+ *
+ * `state` is one of three, and they are three because two of them were one: "populated"
+ * (found, holds facts), "empty" (found, holds none — a recall against it returns nothing,
+ * and that nothing means "wrong filing cabinet" rather than "no match"), and "designated"
+ * (no store anywhere up the tree; `path` is where one WOULD go and nothing was created).
+ *
+ * `searchedFrom` is the resolved directory the walk started at, and is `null` when no walk
+ * ran. `origin` is "walk" or "pin": a pinned binding that still reported `searchedFrom`
+ * would be asserting an ascent that never happened, and a diagnostic field that lies is the
+ * same defect as a state field that lies.
+ *
+ * The two field names are camelCase where Python's are `fact_count` and `searched_from`.
+ * Nothing serialises this record — unlike `Fact`, whose snake_case names are YAML keys on
+ * disk — so the port follows the language it is written in.
+ */
+export interface StoreBinding {
+    path: string;
+    state: 'populated' | 'empty' | 'designated';
+    factCount: number;
+    searchedFrom: string | null;
+    origin: 'walk' | 'pin';
+}
+/**
+ * Walk up from `start` (default cwd) looking for an existing `.bantamkit/memory`.
+ *
+ * Returns the nearest existing store dir; if none exists anywhere up the tree, designates
+ * `start/.bantamkit/memory` without creating anything. The ancestor path is fully resolved;
+ * the returned store path is not resolved further — a symlinked store keeps its config
+ * beside the symlink. `MEMORY_DIR_ENV` outranks all of it.
+ */
+export declare function discoverProjectStore(start?: string | null): string;
+/**
+ * The same walk, plus what is actually in the store.
+ *
+ * Read-only in both directions. An unreadable `facts/` raises `MemoryValidationError` rather
+ * than reporting "empty" — reporting a store you could not read as a store with nothing in
+ * it is the exact conflation this exists to end. A pin never yields "designated":
+ * `pinnedStore` has already established that the pinned directory is there, or raised.
+ */
+export declare function resolveProjectStore(start?: string | null): StoreBinding;
+/**
+ * How many `facts/*.md` a store holds, counted so that unreadable is never zero.
+ *
+ * A directory scan that fails RAISES and each caller decides what to do with it; nobody gets
+ * to be told "empty" by accident. The name filter mirrors `MemoryStore._facts`' `glob("*.md")`
+ * exactly — dotfiles and directories included — because a count that disagrees with the read
+ * is the other half of the same lie.
+ *
+ * THIS DECIDES DIFFERENTLY FROM `store._listing` AND THAT IS A KNOWN DEFECT, DEFERRED
+ * UPSTREAM. `_listing` keys "first run" on `os.path.lexists`, so a `facts/` that is a
+ * DANGLING SYMLINK is unreadable there; this catches `FileNotFoundError` and only that, so
+ * the same shape counts 0 and the binding answers `state="empty"`. runtime-py pins the
+ * disagreement with an unconditional `xfail(strict=True)` on
+ * `test_a_dangling_facts_symlink_is_unreadable_to_both_layers`, and job37/W5 measured what it
+ * costs: on a read-only GRANT layer `Memory.recall` then says "nothing is saved in any layer
+ * bound here" where the same store at `0o311` correctly says "could not be read".
+ *
+ * DO NOT FIX IT HERE. A port that quietly does the right thing where the reference does the
+ * wrong thing is a port that disagrees with production. The conformance case
+ * `count_facts: a dangling facts/ symlink is 0 — THE DEFERRED DEFECT` compares this against
+ * the running Python, so the day `count_facts` grows the check, that case goes red and
+ * somebody has to come here.
+ *
+ * On Windows the shape splits in two and only one half is this one: a FILE reparse point
+ * raises `NotADirectoryError` (errno 20, winerror 267) and the layers AGREE, while a
+ * DIRECTORY reparse point raises `FileNotFoundError` (errno 2, winerror 3) and they do not.
+ * On POSIX a symlink has no type and both collapse to the second. NOT MEASURED on Windows.
+ */
+export declare function countFacts(root: string): number;
+/**
+ * Read extra read-only store paths from the config beside the project store.
+ *
+ * Missing config -> no grants. A config that exists but is wrong — unparsable, not a
+ * mapping, non-list/non-str `extra_stores`, or a listed path that is not an existing
+ * directory — raises `MemoryValidationError`: a grant you wrote that is wrong is a mistake to
+ * surface at construction, not silently drop. Returned grant paths are fully resolved.
+ */
+export declare function loadGrants(projectStore: string): string[];