bantamkit-mcp 0.26.0

package/dist/memory/component.js

@@ -0,0 +1,497 @@
+/**
+ * Agent-facing memory component: skill in the prompt, correctness in the store.
+ *
+ * A port of `runtime-py/src/bantamkit/memory/component.py`. Roughly half of it is SENTENCES,
+ * and the value of a sentence here is that it is exactly the one the Python server produces:
+ * these are what an agent acts on when its memory appears empty, and job37 exists because
+ * "empty" and "unreadable" were once the same answer. A one-word difference is a defect.
+ *
+ * WHAT IS DELIBERATELY MISSING. `setup()` and `batch()`, the only two consumers of `Agent`.
+ * The prep probe traced a real stdio server through the tools and both resource templates:
+ * neither is reachable from the MCP surface. They are absent rather than stubbed so that
+ * nobody reads a stub and believes the batch scope exists here. If a tool ever calls one,
+ * that is a refutation of the trace and wants reporting, not a quiet addition.
+ *
+ * WHAT USED TO BE MISSING AND NO LONGER IS. `compact()` was on that list, with the note that
+ * its store half was not ported either. The store half landed first (`MemoryStore.compact`,
+ * the operator CLI's `compact` verb), and job42 registered `memory_compact` as the ninth MCP
+ * tool on the reference — the model's half of compaction, the remedy the refused-budget
+ * reply now names. So `compact()` / `compactOutcome()` are ported below, sentence for
+ * sentence, and reach ONLY `this.store` (the writable project layer): `layered` puts grants
+ * and the profile store in `_layers`, never in `this.store`, so a compaction cannot see them.
+ *
+ * BOTH REGISTRATIONS ARE REAL AND BOTH ARE PORTED. `.mcp.json` and the user-scope config
+ * invoke the server with no `--store`, so PRODUCTION RUNS `Memory.layered` and its recall
+ * lines carry a `[project] ` tag that the `--store` form never emits. A port validated
+ * against only one of them ships a string the deployment never produces.
+ */
+import { BantamError } from '../errors.js';
+import { pyStrip } from './factfile.js';
+import { countFacts, loadGrants, MEMORY_DIR_ENV, PROJECT_STORE, resolveProjectStore, } from './layers.js';
+import { pyHome, pyJoin, pyName, pyParent, pyResolve, PyOSError, PyUnicodeDecodeError } from './pyfs.js';
+import { DEFAULT_INDEX_BUDGET, MemoryBudgetExceeded, MemoryStore, MemoryValidationError, pyHashKey, pyText, } from './store.js';
+/**
+ * The model's spelling adapted to the store's contract: lowercase, `_`/space -> `-`.
+ *
+ * The store's pattern does not move; the component bends the argument to it. Measured cause:
+ * 5 of the 7b probe runs burned their whole turn budget retrying `memory_save` with the
+ * snake_case names the model invents. Non-strings are handed on untouched so that store
+ * validation still speaks.
+ */
+export function normalizeName(name) {
+    if (typeof name !== 'string')
+        return name;
+    // `str.strip()` is NOT `String.trim()` — they disagree on six codepoints, and `pyStrip`
+    // is N2's answer to that. `str.lower()` IS `String.toLowerCase()`, including the one place
+    // it was expected not to be: CPython applies the Final_Sigma condition too, so `ΑΣ`
+    // lowercases to `ας` in both runtimes and a per-codepoint fold would have been the thing
+    // that differed. MEASURED — the case `normalize_name over the strip and lowercase
+    // boundary` compares thirteen spellings, `ΣΟΦΟΣ` among them.
+    return pyStrip(name).toLowerCase().replace(/_/g, '-').replace(/ /g, '-');
+}
+/**
+ * The last layer `layered` appends, named once so other code can recognise it.
+ *
+ * It was spelled inline and nowhere else, which is how it came to be prescribed as a place
+ * to start a project store: nothing that wrote the advice could see that the directory it
+ * was recommending is also the machine-wide layer.
+ */
+export function profileStore() {
+    return pyJoin(pyHome(), ...PROJECT_STORE);
+}
+/** The name a layer answers under: the PROJECT directory, not the store directory. */
+export function layerLabel(root) {
+    if (pyName(pyParent(root)) === '.bantamkit')
+        return pyName(pyParent(pyParent(root)));
+    return pyName(root);
+}
+export class Memory {
+    store;
+    k;
+    layers;
+    showLayers = false;
+    /**
+     * How this store came to be the store, captured once. It cannot be re-derived later: the
+     * constructor above has already made the directory, so a store that was only DESIGNATED a
+     * moment ago is indistinguishable on disk from one that was found empty. `null` means the
+     * caller named the path outright and no resolution happened to report.
+     */
+    binding;
+    constructor(store, options = {}, binding = null) {
+        const k = options.k ?? 3;
+        this.store = new MemoryStore(store, {
+            indexBudget: options.indexBudget ?? DEFAULT_INDEX_BUDGET,
+            k,
+            ...(options.today ? { today: options.today } : {}),
+        });
+        this.k = k;
+        this.layers = [['project', this.store, true]];
+        this.binding = binding;
+    }
+    /**
+     * Project store (resolved) + configured read-only grants + profile store.
+     *
+     * `resolveProjectStore` rather than `discoverProjectStore`: the path both return is the
+     * same path, but only the binding carries WHY it is that path and whether it holds
+     * anything — and `recall` cannot recover either fact afterwards, because constructing the
+     * store creates the directory.
+     */
+    static layered(start, options = {}) {
+        const binding = resolveProjectStore(start);
+        const mem = new Memory(binding.path, options, binding);
+        mem.showLayers = true;
+        const k = options.k ?? 3;
+        const today = options.today;
+        for (const grant of loadGrants(binding.path)) {
+            mem.layers.push([
+                `extra:${layerLabel(grant)}`,
+                new MemoryStore(grant, { k, create: false, ...(today ? { today } : {}) }),
+                false,
+            ]);
+        }
+        mem.layers.push([
+            'profile',
+            new MemoryStore(profileStore(), { k, create: false, ...(today ? { today } : {}) }),
+            false,
+        ]);
+        return mem;
+    }
+    /** The labels, in order. `_layers` is private in the reference too; this is for the tests. */
+    layerLabels() {
+        return this.layers.map(([label]) => label);
+    }
+    /** The reply the model reads. Unchanged, and still the tool's advertised return. */
+    save(type, name, description, body, links = null) {
+        return this.saveOutcome(type, name, description, body, links).reply;
+    }
+    /**
+     * `save`, with the branch it took carried out alongside the sentence it wrote.
+     *
+     * Same body, same order, same four exits: the only change is that each exit now NAMES
+     * itself. That is the whole of the narrow seam the MCP server needs to log an outcome
+     * without matching text, and it moves no wording and no return type — `save()` above
+     * still answers `string`, and `assets/tools/memory_save.json` still advertises `str`.
+     */
+    saveOutcome(type, name, description, body, links = null) {
+        const normalized = normalizeName(name);
+        const normalizedLinks = (links ?? []).map((link) => normalizeName(link));
+        let result;
+        try {
+            result = this.store.save(type, normalized, description, body, normalizedLinks);
+        }
+        catch (e) {
+            if (e instanceof MemoryValidationError) {
+                return { reply: `error: ${e.message}`, status: 'refused-validation' };
+            }
+            if (e instanceof MemoryBudgetExceeded) {
+                // Not an argument problem: retrying the same call cannot fit the index. Two
+                // audiences, two remedies. The store's own text names `compact()`; this reply goes
+                // to the MODEL, and since job42 the model HAS a compaction tool — `memory_compact`
+                // (`docs/memory.md`: the user ruled compaction automatic on 2026-08-24; the hook
+                // covers the 90 % band, the tool covers this refusal) — so the last sentence names
+                // it. Everything before that sentence is byte-identical to what it was when
+                // compaction was operator-only.
+                return {
+                    reply: `error: ${e.message}. Nothing was saved and retrying will not help — shorten ` +
+                        'the description, or save under the name of an existing memory to replace it. ' +
+                        'Or call `memory_compact` to archive the stalest facts and free room — nothing is deleted.',
+                    status: 'refused-budget',
+                };
+            }
+            throw e;
+        }
+        if (result.status === 'duplicate') {
+            return {
+                reply: `similar memory '${result.similar}' already exists — save under that SAME ` +
+                    'name to update it, or skip. Do not rename to force a copy.',
+                status: 'duplicate',
+            };
+        }
+        return { reply: `saved '${result.name}'`, status: 'saved' };
+    }
+    /**
+     * `k` is the model asking for MORE, never for less than the store's default.
+     *
+     * Measured cause (RB-P1, qwen2.5:14b-instruct): 57 of 60 `memory_recall` calls across 12
+     * seeded runs sent `k: 1`, and honouring it truncated recall to the single best-scoring
+     * fact. The floor is the operator's configured default, not a constant, so a consumer who
+     * really wants top-1 says so once at construction.
+     */
+    recall(query, k = null) {
+        return this.recallOutcome(query, k).reply;
+    }
+    /**
+     * `recall`, carrying the walk it performed as numbers rather than as prose.
+     *
+     * The reply is byte-for-byte what `recall` has always returned; every field beside it is
+     * counted here because it CANNOT be recovered afterwards. How far down the layer list the
+     * budget got, how many of the layers reached were readable, how many facts those layers
+     * held against how many came back, and which of the three empty verdicts fired — all of
+     * it is gone by the time the string exists, and the host's log records only that a
+     * `memory_recall` "completed successfully".
+     *
+     * `candidates` counts `facts/*.md` in the layers actually READ, via `countFacts` — the
+     * same filter `MemoryStore.recall` scores over, so the ratio to `returned` is between two
+     * counts of one population and not between two different ones. A layer whose directory
+     * refuses to list contributes nothing and raises the `unreadable` count instead of being
+     * scored as empty; that distinction is the whole subject of `nothingToReport` below and
+     * must not be undone here.
+     */
+    recallOutcome(query, k = null) {
+        const budget = k === null ? this.k : Math.max(k, this.k);
+        const picked = [];
+        const seen = new Set();
+        let reached = 0;
+        let unreadable = 0;
+        let candidates = 0;
+        for (const [label, store, writable] of this.layers) {
+            if (picked.length >= budget)
+                break; // budget spent: later layers are never even read
+            reached += 1;
+            let facts;
+            try {
+                facts = store.recall(query, budget, writable);
+            }
+            catch (e) {
+                if (!(e instanceof BantamError || e instanceof PyOSError || e instanceof PyUnicodeDecodeError)) {
+                    throw e;
+                }
+                if (writable)
+                    throw e; // the project layer failing is a real error, as in v1
+                unreadable += 1;
+                continue; // a corrupt grant/profile layer must not take down recall
+            }
+            try {
+                candidates += countFacts(store.root);
+            }
+            catch (e) {
+                // It scored a moment ago, so it is readable; a race that unlists it now must not
+                // turn a successful recall into a failed one for a log field.
+                if (!(e instanceof PyOSError))
+                    throw e;
+            }
+            for (const fact of facts) {
+                // `if fact.name in seen` over a Python `set`, which is `hash`/`==` and not `str` —
+                // see `store.pyHashKey` for why a hand-edited numeric name makes the two differ.
+                const key = pyHashKey(fact.name);
+                if (seen.has(key) || picked.length >= budget)
+                    continue;
+                seen.add(key);
+                picked.push([label, fact]);
+            }
+        }
+        const counts = {
+            budget,
+            layers: this.layers.length,
+            reached,
+            returned: picked.length,
+            candidates,
+            unreadable,
+        };
+        if (picked.length === 0) {
+            const [status, reply] = this.nothingToReport();
+            return { reply, status, source: null, ...counts };
+        }
+        return {
+            reply: picked.map(([label, fact]) => this.format(label, fact)).join('\n\n'),
+            status: 'answered',
+            source: picked[0][0].split(':', 1)[0],
+            ...counts,
+        };
+    }
+    /**
+     * Archive the stalest facts until a fact as large as the biggest one kept will fit.
+     *
+     * The reply is the ONLY place the model learns what left the index: `archive/` is a
+     * directory the model calling this will never look in — if the return value does not carry
+     * what was lost, nothing does. Ported from `Memory.compact` in `component.py`, which is
+     * written for a model; the tool's advertised return is this string, unchanged.
+     */
+    compact(reserve = null) {
+        return this.compactOutcome(reserve).reply;
+    }
+    /**
+     * `compact`, with the decision it took carried beside the sentence it wrote.
+     *
+     * `this.store` is the writable project layer and nothing else: `layered` appends grants
+     * and the profile store to `_layers` only, never to `this.store`, so this cannot reach
+     * either (`test/layers.test.mjs` pins a profile fact through a compaction). The reply is
+     * byte-for-byte what `compact` has always returned on the reference: Python `f"{int}"`
+     * is a plain decimal, and `result.archive_dir` is `str(Path)`, which `archiveDir` already
+     * is — `MemoryStore.compact` builds it with `pyJoin`.
+     */
+    compactOutcome(reserve = null) {
+        const result = this.store.compact(reserve);
+        let reply;
+        let status;
+        if (result.archived.length === 0) {
+            reply =
+                `nothing archived: the index is ${result.indexAfter} bytes against a ` +
+                    `${result.budget}-byte budget, already at or under the ` +
+                    `${result.target}-byte compaction target.`;
+            status = 'nothing-archived';
+        }
+        else {
+            const lost = result.archived
+                .map((fact) => `- ${fact.name} (${fact.type}) — ${fact.description}`)
+                .join('\n');
+            reply =
+                `archived ${result.archived.length} memories; the index went from ` +
+                    `${result.indexBefore} to ${result.indexAfter} bytes against a ` +
+                    `${result.budget}-byte budget, leaving ${result.headroom} bytes of headroom. ` +
+                    `These moved to ${result.archiveDir} and are NOT deleted — they can be ` +
+                    `restored by name:\n${lost}`;
+            status = 'archived';
+        }
+        return {
+            reply,
+            status,
+            archived: result.archived.length,
+            indexBefore: result.indexBefore,
+            indexAfter: result.indexAfter,
+            budget: result.budget,
+        };
+    }
+    /**
+     * `(index bytes, budget)` for the writable project store; bytes may be `null`.
+     *
+     * Measured exactly the way `MemoryStore.checkIndexBudget` measures — the UTF-8 length of
+     * `indexText()` — so the number a log records and the number a refusal was decided
+     * against are one number and not two that can drift apart.
+     *
+     * `null` means the store could not be read, and it is never 0: an unreadable store
+     * reporting an empty index is the same slander this module spends `nothingToReport`
+     * refusing to commit, and it would read as infinite headroom at exactly the moment there
+     * is none. The cost is a full parse of `facts/`, which is why nothing calls this on the
+     * tool path unless a log is actually enabled.
+     */
+    indexAccounting() {
+        try {
+            return [Buffer.byteLength(this.store.indexText(), 'utf8'), this.store.indexBudget];
+        }
+        catch (e) {
+            if (e instanceof BantamError || e instanceof PyOSError || e instanceof PyUnicodeDecodeError) {
+                return [null, this.store.indexBudget];
+            }
+            throw e;
+        }
+    }
+    // ---- the empty answer, split into the answers it was hiding ----------------
+    /**
+     * An empty recall is at least three different situations; say which one.
+     *
+     * Answers `[status, text]`. The status is the SAME BRANCH that picks the sentence, handed
+     * out rather than re-derived: a caller that needs to tell the three empties apart — the
+     * MCP event log does — would otherwise have to match the prose this comment exists to say
+     * is allowed to improve.
+     *
+     * Until job37 all of them returned "no memories matched. Try different words", which tells
+     * a person to rephrase a question against a filing cabinet that may not exist.
+     *
+     * The verdict is keyed on what could have been read RIGHT NOW, counted the way
+     * `MemoryStore._facts` reads, not on the construction-time binding — a store that was empty
+     * at construction and has been saved to since really can answer. The DIAGNOSIS is keyed on
+     * the binding, because "designated" stops being visible on disk the moment `MemoryStore`
+     * creates the directory.
+     */
+    nothingToReport() {
+        let status;
+        let verdict;
+        const unreadable = this.unreadableLayers();
+        if (this.searchableFacts()) {
+            status = 'empty-no-match';
+            verdict = 'no memories matched. Try different words, or proceed without.';
+        }
+        else if (unreadable.length > 0) {
+            // A layer nobody could open is not a layer that held nothing. Saying "nothing is
+            // saved" here is the same slander as calling an unreadable store empty, one call out.
+            status = 'empty-unreadable-layer';
+            verdict =
+                'no memories matched, and that is not evidence there are none: ' +
+                    `${unreadable.join(', ')} could not be read.`;
+        }
+        else {
+            status = 'empty-nothing-saved';
+            verdict = 'no memories to search: nothing is saved in any layer bound here.';
+        }
+        const diagnosis = this.bindingDiagnosis();
+        return [status, diagnosis ? `${verdict} ${diagnosis}` : verdict];
+    }
+    /**
+     * How many facts a store holds, or `null` when that cannot be established.
+     *
+     * A store that cannot be listed answers `null` and never 0: "I could not read it" and "it
+     * holds nothing" are the two answers this whole unit exists to keep apart.
+     */
+    static factCount(root) {
+        try {
+            return countFacts(root);
+        }
+        catch (e) {
+            if (e instanceof PyOSError)
+                return null;
+            throw e;
+        }
+    }
+    /** Roots of the layers that could not be listed at all — never counted as 0. */
+    unreadableLayers() {
+        return this.layers
+            .filter(([, store]) => Memory.factCount(store.root) === null)
+            .map(([, store]) => store.root);
+    }
+    /**
+     * Facts the layers actually consulted could have matched, counted live.
+     *
+     * An unreadable layer contributes nothing rather than counting as empty: `recall` already
+     * skips it, and it must not become evidence that there was nothing to read.
+     */
+    searchableFacts() {
+        let total = 0;
+        for (const [, store] of this.layers)
+            total += Memory.factCount(store.root) ?? 0;
+        return total;
+    }
+    /**
+     * Is this store also the machine-wide profile layer `layered` appends?
+     *
+     * Resolved on both sides because the walk returns its store path unresolved while
+     * `Path.home()` may itself be a symlink; a comparison that missed on a symlink would put
+     * the harmful advice back exactly where it does damage.
+     */
+    static isProfileStore(root) {
+        try {
+            return pyResolve(root) === pyResolve(profileStore());
+        }
+        catch {
+            return false; // `except (OSError, RuntimeError)` — a symlink loop lands here too
+        }
+    }
+    /**
+     * Did the walk actually leave the directory it started in?
+     *
+     * `origin === "walk"` says a walk ran, not that it climbed. A walk that terminates at step
+     * zero has bound `searchedFrom`'s OWN store, and the clause that reads well for an ancestor
+     * binding — "which has no store of its own" — is then simply false about the commonest case
+     * there is: a project whose store exists and is empty.
+     */
+    walkAscended() {
+        const binding = this.binding;
+        if (binding === null || binding.searchedFrom === null)
+            return false;
+        return binding.path !== pyJoin(binding.searchedFrom, ...PROJECT_STORE);
+    }
+    /**
+     * Why THIS store, when the project layer is the one that cannot answer.
+     *
+     * Silent while the project store holds facts: that is the case that already works, and it
+     * keeps its exact wording. The remedy names `MEMORY_DIR_ENV` from `layers`, never a
+     * literal, so the message and the resolver cannot drift onto two different variables.
+     */
+    bindingDiagnosis() {
+        if (Memory.factCount(this.store.root) !== 0)
+            return ''; // holds facts, or unreadable
+        const root = this.store.root;
+        const binding = this.binding;
+        let where;
+        if (binding === null) {
+            where = `The project store ${root} is empty.`;
+        }
+        else if (binding.state === 'designated') {
+            where =
+                `No memory store existed at or above ${binding.searchedFrom}, so the ` +
+                    `empty ${root} was created for this session.`;
+        }
+        else if (binding.origin === 'pin') {
+            where = `The project store ${root} is empty; ${MEMORY_DIR_ENV} pinned it.`;
+        }
+        else if (this.walkAscended()) {
+            where =
+                `The project store ${root} is empty; it was bound by walking up from ` +
+                    `${binding.searchedFrom}, which has no store of its own.`;
+        }
+        else {
+            where =
+                `The project store ${root} is empty; it is ${binding.searchedFrom}'s own ` +
+                    'store, bound without the walk leaving that directory.';
+        }
+        const remedy = 'That is a binding, not a search result — if your facts are in another ' +
+            `store, set ${MEMORY_DIR_ENV} to its absolute path and restart`;
+        if (Memory.isProfileStore(root)) {
+            // The store bound here IS the profile layer, which every project with no store of its
+            // own also binds. "Save a memory to start this one" would therefore start a store that
+            // answers for all of them.
+            return (`${where} ${remedy}. Do NOT save here to start it: ${root} is also the ` +
+                'profile layer, so a memory saved there answers for every project on ' +
+                'this machine that has no store of its own — give this project a store ' +
+                'of its own instead.');
+        }
+        return `${where} ${remedy}; otherwise save a memory to start this one.`;
+    }
+    format(label, fact) {
+        // `pyText` for the three interpolated fields, not template-literal coercion: a
+        // hand-edited `name:` with nothing after it is `None` in Python's sentence and would be
+        // `null` in this one. The store already reproduces it in the index line and on disk.
+        const tag = this.showLayers ? `[${label}] ` : '';
+        return `${tag}[${pyText(fact.name)}] (${pyText(fact.type)}) ${pyText(fact.description)}\n${fact.body}`;
+    }
+}

package/dist/memory/factfile.d.ts

@@ -0,0 +1,120 @@
+/**
+ * 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 { PyScalar } from './pyyaml.js';
+export declare class FactParseError extends Error {
+}
+/**
+ * What one frontmatter value can be.
+ *
+ * `PyScalar` is not a widening for its own sake: `_facts` in the reference puts
+ * `yaml.safe_load`'s answer into the dataclass with no type check, so a hand-edited
+ * `description: 2026` really does give the Python store an `int` in a `str` field and the
+ * store really does keep working. The three-way is the whole ruling — see `constructPlain`
+ * in `pyyaml.ts` for what lands in which arm, and `store.pyText` for how it is rendered.
+ */
+export type FactValue = string | PyScalar | null;
+/** `store.Fact`. `created` is `null` only before a Fact's first write. */
+export interface Fact {
+    name: FactValue;
+    description: FactValue;
+    type: FactValue;
+    body: string;
+    links: FactValue[];
+    last_recalled: FactValue;
+    created?: FactValue;
+}
+/** 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;
+/**
+ * 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 declare function decodeFactBytes(bytes: Uint8Array): string;
+/**
+ * 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 declare function formatFact(fact: Fact): string;
+/**
+ * `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 declare function parseFactText(text: string): {
+    meta: FactMeta;
+    body: string;
+};
+/**
+ * `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 declare function pySplit(text: string, sep: string, maxsplit: number): string[];
+/**
+ * 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 declare function parseFrontmatter(front: string): FactMeta;
+/**
+ * `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 declare function todayLocal(now?: Date): string;