bantamkit-mcp 0.26.0

package/dist/memory/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export declare function main(argv: readonly string[]): number;

package/dist/memory/cli.js

@@ -0,0 +1,396 @@
+#!/usr/bin/env node
+/**
+ * The operator's half of the lifecycle position, on the Node side: `bantamkit-memory`.
+ *
+ * `docs/memory.md` states, as a design decision, that `lint`, `archived` and `restore`
+ * are **not** agent tools — "lifecycle is an operator decision, not a model decision" —
+ * and the eleven-tool surface holds to it; `compact` is the one exception since job42
+ * (`memory_compact`, the on-refusal path the model reaches itself). `runtime-py` made that
+ * position coherent in August 2026 by giving the operator `python -m bantamkit.memory`.
+ * `runtime-ts` did not. MEASURED 2026-08-24 before this file existed: `node dist/cli.js -h`
+ * and `python -m bantamkit.mcpserver -h` print byte-identical help, neither offers a
+ * subcommand, and the maintenance CLI existed only in Python — so an operator who ran
+ * `npx bantamkit-mcp` and nothing else could not compact, could not lint, and could not
+ * restore an archived fact. Not a documentation gap: there was no code path.
+ *
+ * WHY A SECOND `bin` AND NOT A FLAG ON `bantamkit-mcp`
+ * ---------------------------------------------------
+ * The reference's reason for a separate entry point (`bantamkit-mcp` speaks JSON-RPC over
+ * stdout, so a lifecycle report printed there corrupts the wire) does NOT decide it here:
+ * `--assets-root`, `--mcp-report` and `--statusline` all print and return before a transport
+ * exists, and `src/cli.ts` says so at each of them. The reason a subcommand is refused is
+ * different and it is measured: `bantamkit-mcp`'s help is a BYTE-COMPARED artifact against
+ * `python -m bantamkit.mcpserver -h` (`tools/conformance/suites/cli.mjs`). Hanging a
+ * subparsers action off that parser would add `{memory} ...` to its usage line and a whole
+ * `positional arguments:` section to its help, against a reference that has neither. The
+ * parity that already holds would have to be broken to reach the surface this file adds.
+ *
+ * A second `bin` costs nothing on either install route. `npm i -g bantamkit-mcp` puts both
+ * commands on PATH; without an install, `npx -p bantamkit-mcp bantamkit-memory status` runs
+ * this file straight out of the registry. `package.json` used to declare exactly one bin,
+ * and `src/cli.ts` still reasons from that — see the `--statusline` comment there, which is
+ * about a Claude Code `statusLine` registration and is unaffected: a host that names one
+ * command still names one command.
+ *
+ * THE ONE STRING THAT CANNOT BE THE SAME
+ * --------------------------------------
+ * The Python operator types `python -m bantamkit.memory`; the Node operator types
+ * `bantamkit-memory`. There is no third spelling that both could use: the reference's `prog`
+ * is a Python `-m` invocation and a pure-npm install has no Python in it at all, while
+ * `bantamkit-memory` names a console script that CPython does not install. Everything
+ * downstream of `prog` moves with it — the usage line, every `…: error:` prefix, and the two
+ * remediation sentences that name a command to run (`lint`'s `try:` line and `compact`'s
+ * `restore one with:`). Those two are the reason this is a substitution and not a cosmetic
+ * difference: printing `python -m bantamkit.memory compact …` to someone holding an npx
+ * install would be an instruction they cannot follow.
+ *
+ * The rule, stated so a conformance case can rule on it and MEASURED at 2026-08-24: the two
+ * CLIs produce IDENTICAL BYTES after substituting `python -m bantamkit.memory` ->
+ * `bantamkit-memory`, EXCEPT that a usage line long enough to wrap wraps at different
+ * points, because the hanging indent argparse computes is `len(prefix) + len(prog) + 1`.
+ * Verified both halves: at `COLUMNS=200` all four help forms (`-h`, `status -h`,
+ * `restore -h`, `compact -h`) are byte-identical after the substitution and nothing else; at
+ * `COLUMNS=80` the ONLY diff in each is the continuation indent (31 columns here against 41
+ * there) and, for the top parser, whether the line needed to wrap at all. So the divergence
+ * is `prog` and the arithmetic downstream of `prog`, not a second rendering algorithm — a
+ * ruling should compare at a width where the line fits, and pin the wrap separately.
+ * `PROG` below is the only place the Node spelling appears.
+ *
+ * Scope is deliberately the writable project layer only, exactly as the reference has it.
+ * `Memory.layered()` also mounts read-only grants and the profile store, and
+ * `MemoryStore.compact()` touches neither; resolving through `discoverProjectStore` keeps
+ * this CLI unable to archive a store it does not own, rather than merely unlikely to.
+ *
+ * Exit codes: 0 success, 1 an operational failure the operator must act on (over budget,
+ * malformed fact, refused restore), 2 argparse usage error.
+ */
+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 { 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';
+/** `SystemExit("...")`: the message on stderr, exit 1. */
+class Refusal extends Error {
+}
+/**
+ * `_positive`: a budget of 0 or less silently makes every save fail, so refuse it at the edge.
+ *
+ * The TWO failure sentences are both the reference's and they are different on purpose:
+ * `--budget x` never reaches this body (`int()` raises and argparse prints
+ * `invalid _positive value: 'x'`), while `--budget 0` gets this `ArgumentTypeError`'s own
+ * text. `typeName` below is `_positive` because argparse interpolates the CALLABLE's
+ * `__name__`, and the reference's callable is named `_positive`.
+ */
+function positive(text) {
+    const value = pyIntStrict(text);
+    if (value < 1)
+        throw new ArgumentTypeError('must be >= 1');
+    return value;
+}
+/**
+ * `common(sub)`: the store selector and the budget, on every subcommand.
+ *
+ * ORDER IS WIRE-VISIBLE. argparse prints optionals in the order they were added, so this
+ * array — not any format string — decides that `[--store STORE | --start START]` precedes
+ * `[--budget BYTES]` in every sub-usage, and that `--reserve` follows both under `compact`.
+ * The mutually exclusive group is `[1, 2]` because `-h` is added first by the parser itself.
+ */
+const common = (extra = []) => [
+    {
+        optionStrings: ['-h', '--help'],
+        dest: 'help',
+        kind: 'help',
+        help: 'show this help message and exit',
+        defaultValue: false,
+    },
+    {
+        optionStrings: ['--store'],
+        dest: 'store',
+        kind: 'store',
+        help: 'memory store path (skips project discovery)',
+        defaultValue: null,
+    },
+    {
+        optionStrings: ['--start'],
+        dest: 'start',
+        kind: 'store',
+        help: 'directory to start project-store discovery from (default: cwd)',
+        defaultValue: null,
+    },
+    {
+        optionStrings: ['--budget'],
+        dest: 'budget',
+        metavar: 'BYTES',
+        kind: 'store',
+        help: `index byte budget (default: ${DEFAULT_INDEX_BUDGET})`,
+        convert: positive,
+        typeName: '_positive',
+        defaultValue: DEFAULT_INDEX_BUDGET,
+    },
+    ...extra,
+];
+const sub = (name, actions) => ({
+    prog: `${PROG} ${name}`,
+    // `add_parser` takes no `description=` in the reference, so the sub-help has no paragraph
+    // between its usage line and its first section. An empty string is that absence.
+    description: '',
+    actions,
+    groups: [[1, 2]],
+});
+/** `_parse_args`'s parser, as DATA — the one description of this command line. */
+const PARSER = {
+    prog: PROG,
+    description: 'Operator lifecycle for a bantamkit memory store: inspect, lint, compact, ' +
+        'archive and restore. Not an agent surface.',
+    actions: [
+        {
+            optionStrings: ['-h', '--help'],
+            dest: 'help',
+            kind: 'help',
+            help: 'show this help message and exit',
+            defaultValue: false,
+        },
+        {
+            // `add_subparsers(dest="command", required=True)` — no `help=`, which is why the
+            // `{status,…}` row prints bare above its five indented children.
+            optionStrings: [],
+            dest: 'command',
+            kind: 'subparsers',
+            help: '',
+            defaultValue: null,
+            subcommands: [
+                { name: 'status', help: 'index size, budget, headroom, archive count', parser: sub('status', common()) },
+                {
+                    name: 'lint',
+                    help: 'exit 1 if the store is malformed or over budget',
+                    parser: sub('lint', common()),
+                },
+                {
+                    name: 'compact',
+                    help: 'archive the stalest facts',
+                    parser: sub('compact', common([
+                        {
+                            optionStrings: ['--reserve'],
+                            dest: 'reserve',
+                            metavar: 'BYTES',
+                            kind: 'store',
+                            help: 'headroom to leave below the budget (default: the largest index line kept)',
+                            convert: positive,
+                            typeName: '_positive',
+                            defaultValue: null,
+                        },
+                    ])),
+                },
+                {
+                    name: 'archived',
+                    help: 'list what compaction has moved out',
+                    parser: sub('archived', common()),
+                },
+                {
+                    name: 'archive',
+                    help: 'move one named fact out',
+                    parser: sub('archive', [
+                        ...common(),
+                        {
+                            optionStrings: [],
+                            dest: 'name',
+                            kind: 'positional',
+                            help: 'name of the fact to archive',
+                            defaultValue: null,
+                        },
+                    ]),
+                },
+                {
+                    name: 'restore',
+                    help: 'move an archived fact back',
+                    parser: sub('restore', [
+                        ...common(),
+                        {
+                            optionStrings: [],
+                            dest: 'name',
+                            kind: 'positional',
+                            help: 'name of the archived fact',
+                            defaultValue: null,
+                        },
+                    ]),
+                },
+            ],
+        },
+    ],
+    groups: [],
+};
+function parse(argv) {
+    const values = parseArgs(PARSER, argv);
+    return {
+        command: values['command'],
+        store: values['store'],
+        start: values['start'],
+        budget: values['budget'],
+        reserve: (values['reserve'] ?? null),
+        name: values['name'],
+    };
+}
+/** `_open`: the writable project store, and nothing else this CLI could reach. */
+function open(args) {
+    if (args.store !== null) {
+        if (args.store === '')
+            throw new Refusal('--store requires a non-empty path');
+        return new MemoryStore(args.store, { indexBudget: args.budget });
+    }
+    return new MemoryStore(discoverProjectStore(args.start), { indexBudget: args.budget });
+}
+/**
+ * `len(store.index_text().encode())` — the number the budget is compared against.
+ *
+ * It is the LF text's length on both runtimes. `runtime-py` writes `index.md` through
+ * `write_text` with `newline=None`, so on Windows the file on disk is longer than the number
+ * measured here; that disagreement is a runtime-py defect and is not reproduced.
+ */
+const size = (store) => Buffer.byteLength(store.indexText(), 'utf8');
+const out = (text) => {
+    process.stdout.write(`${text}\n`);
+};
+const err = (text) => {
+    process.stderr.write(`${text}\n`);
+};
+function cmdStatus(store) {
+    const bytes = size(store);
+    out(`store: ${store.root}`);
+    out(`facts: ${store.factCount()}`);
+    out(`index: ${bytes} bytes`);
+    out(`budget: ${store.indexBudget}`);
+    out(`headroom: ${store.indexBudget - bytes}`);
+    out(`archived: ${store.archived().length}`);
+    return 0;
+}
+function cmdLint(store) {
+    try {
+        store.lint();
+    }
+    catch (error) {
+        if (error instanceof MemoryBudgetExceeded) {
+            // Not the store's own message: that one names `compact()`, which is a call in a
+            // language and the wrong remedy to hand someone holding a shell.
+            const where = `--store ${store.root}`;
+            err(`lint: FAIL — index is ${size(store)} bytes, budget is ${store.indexBudget}\n` +
+                `  try: ${PROG} compact ${where} --budget ${store.indexBudget}`);
+            return 1;
+        }
+        if (error instanceof MemoryValidationError) {
+            err(`lint: FAIL — ${error.message}`);
+            return 1;
+        }
+        throw error;
+    }
+    out(`lint: ok — ${store.factCount()} facts, ${size(store)}/${store.indexBudget} bytes`);
+    return 0;
+}
+function cmdCompact(store, args) {
+    const before = size(store);
+    const result = store.compact(args.reserve);
+    out(`compacted ${result.archived.length} fact(s)`);
+    out(`index: ${before} -> ${result.indexAfter} bytes ` +
+        `(budget ${result.budget}, target ${result.target}, ` +
+        `reserve ${result.reserve}, headroom ${result.headroom})`);
+    if (result.archived.length === 0) {
+        out('nothing to archive — the index is already at or below the target');
+        return 0;
+    }
+    // `archive/` is on disk and nothing reads it back on its own, so the names have to land
+    // here or the operator never learns what left.
+    out(`archived -> ${result.archiveDir}`);
+    for (const fact of result.archived) {
+        out(`  ${pyText(fact.name)} (${pyText(fact.type)}, ${fact.indexBytes} bytes)`);
+    }
+    out(`restore one with: ${PROG} restore <name> --store ${store.root}`);
+    return 0;
+}
+function cmdArchived(store) {
+    const names = store.archived();
+    out(`archived facts: ${names.length} (${pyJoin(store.root, 'archive')})`);
+    for (const name of names)
+        out(`  ${name}`);
+    return 0;
+}
+function cmdArchive(store, args) {
+    try {
+        store.archive(args.name);
+    }
+    catch (error) {
+        if (error instanceof MemoryValidationError) {
+            err(`archive failed: ${error.message}`);
+            return 1;
+        }
+        throw error;
+    }
+    out(`archived '${args.name}' — index now ${size(store)}/${store.indexBudget} bytes`);
+    return 0;
+}
+function cmdRestore(store, args) {
+    try {
+        store.restore(args.name);
+    }
+    catch (error) {
+        if (error instanceof MemoryBudgetExceeded) {
+            err(`restore failed: '${args.name}' would put the index over the budget of ` +
+                `${store.indexBudget} bytes. Nothing changed — raise --budget or compact first.`);
+            return 1;
+        }
+        if (error instanceof MemoryValidationError) {
+            err(`restore failed: ${error.message}`);
+            return 1;
+        }
+        throw error;
+    }
+    out(`restored '${args.name}' — index now ${size(store)}/${store.indexBudget} bytes`);
+    return 0;
+}
+const COMMANDS = {
+    status: cmdStatus,
+    lint: cmdLint,
+    compact: cmdCompact,
+    archived: cmdArchived,
+    archive: cmdArchive,
+    restore: cmdRestore,
+};
+export function main(argv) {
+    const args = parse(argv);
+    return COMMANDS[args.command](open(args), args);
+}
+try {
+    process.exitCode = main(process.argv.slice(2));
+}
+catch (error) {
+    if (error instanceof HelpRequested) {
+        // `-h` is an ACTION, not a flag read after parsing: argparse prints and exits 0 the
+        // moment it is taken. `error.spec` is WHOSE help — `restore -h` prints the sub-parser's.
+        process.stdout.write(formatHelp(error.spec ?? PARSER, helpWidth()));
+        process.exitCode = 0;
+    }
+    else if (error instanceof ArgvError) {
+        // And whose USAGE, which is not always this parser's: a bad `--budget` under `status` is
+        // `bantamkit-memory status: error: …`, while an unrecognized argument the sub-parser
+        // handed back is reported by the top parser. Both measured against the reference.
+        const spec = error.spec ?? PARSER;
+        process.stderr.write(`${formatUsageBlock(spec, helpWidth())}${spec.prog}: error: ${error.message}\n`);
+        process.exitCode = 2;
+    }
+    else if (error instanceof Refusal) {
+        process.stderr.write(`${error.message}\n`);
+        process.exitCode = 1;
+    }
+    else if (error instanceof BantamError) {
+        // The store errors the five commands do NOT catch — an unreadable `facts/` under
+        // `status`, `compact` or `archived`. The reference lets those escape `main` and CPython
+        // prints a TRACEBACK, exiting 1. The exit code matches; the stderr text cannot, because
+        // a Python traceback is not a portable artifact. `src/cli.ts` sets the precedent for the
+        // shape used here. Carried as a reported divergence, not a silent one.
+        process.stderr.write(`${PROG}: ${error.message}\n`);
+        process.exitCode = 1;
+    }
+    else {
+        throw error;
+    }
+}

package/dist/memory/component.d.ts

@@ -0,0 +1,256 @@
+import { type StoreBinding } from './layers.js';
+import { MemoryStore } 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 declare function normalizeName<T>(name: T): T;
+/**
+ * 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 declare function profileStore(): string;
+/** The name a layer answers under: the PROJECT directory, not the store directory. */
+export declare function layerLabel(root: string): string;
+export interface MemoryOptions {
+    k?: number;
+    indexBudget?: number;
+    /**
+     * The clock, frozen. `Memory` in the reference takes no such argument — the store it wraps
+     * does, and the conformance harness freezes every layer's `_today` after construction.
+     * This is the same seam, reachable without touching a private field; the default is the
+     * store's own `date.today()`, so nothing about a real run changes.
+     */
+    today?: () => string;
+}
+/**
+ * What `save` DECIDED, beside the sentence it says about it.
+ *
+ * THE POINT OF THIS TYPE IS THAT `status` IS NOT DERIVED FROM `reply`. `Memory.save` has
+ * four outcomes — stored, deduped, refused by validation, refused by the budget — and all
+ * four leave the process as one string that the MCP host records as "completed
+ * successfully in Nms". Anything downstream that wanted to tell them apart had exactly one
+ * route: match the reply text. That route is a re-derivation which breaks silently the day
+ * the wording improves, and it is why this field exists.
+ *
+ * `status` is one of `saved`, `duplicate`, `refused-validation`, `refused-budget`, and
+ * every one of them is read off a decision the code had already made — `SaveResult`'s own
+ * `status`, or which `catch` arm matched. `reply` is the unchanged string `save()` has
+ * always returned; nothing reads it.
+ */
+export interface SaveOutcome {
+    readonly reply: string;
+    readonly status: string;
+}
+/**
+ * What `compact` DID, beside the sentence it says about it.
+ *
+ * Same seam as `SaveOutcome` and `RecallOutcome`: `status` is read off a decision the store
+ * already made — whether `CompactResult.archived` is empty — and never off the reply.
+ * `archived` (**not** deleted, see `MemoryStore.compact`) is the ONLY place the count
+ * survives as a number, because the reply spells it out in prose and the host records only
+ * that a `memory_compact` "completed successfully".
+ *
+ * `status` is `archived` or `nothing-archived`. `reply` is the unchanged string `compact()`
+ * has always returned; nothing reads it.
+ */
+export interface CompactOutcome {
+    readonly reply: string;
+    readonly status: string;
+    readonly archived: number;
+    readonly indexBefore: number;
+    readonly indexAfter: number;
+    readonly budget: number;
+}
+/**
+ * What `recall` DID, beside the facts it formatted.
+ *
+ * `recall` walks the layers in order, stops the moment the budget is spent, dedupes by
+ * name, and — when nothing matched — picks one of three different verdicts about WHY (see
+ * `nothingToReport`). None of that survived into the reply the host times: an empty recall
+ * and a three-fact recall are the same log line to it, and the three empties are
+ * indistinguishable from each other even to a reader of the reply, because telling them
+ * apart means matching prose.
+ *
+ * `status` is `answered` or one of `empty-no-match` / `empty-unreadable-layer` /
+ * `empty-nothing-saved`, keyed on the same branch that chooses the verdict sentence rather
+ * than on the sentence. `source` is the KIND of the layer that answered first — `project`,
+ * `extra` or `profile` — deliberately not the layer's full label, because `extra:<name>`
+ * carries a directory name off the operator's disk and the log this feeds is
+ * metadata-only.
+ */
+export interface RecallOutcome {
+    readonly reply: string;
+    readonly status: string;
+    readonly budget: number;
+    readonly layers: number;
+    readonly reached: number;
+    readonly returned: number;
+    readonly candidates: number;
+    readonly source: string | null;
+    readonly unreadable: number;
+}
+export declare class Memory {
+    readonly store: MemoryStore;
+    readonly k: number;
+    private readonly layers;
+    private showLayers;
+    /**
+     * 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.
+     */
+    private readonly binding;
+    constructor(store: string, options?: MemoryOptions, binding?: StoreBinding | null);
+    /**
+     * 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?: string | null, options?: MemoryOptions): Memory;
+    /** The labels, in order. `_layers` is private in the reference too; this is for the tests. */
+    layerLabels(): string[];
+    /** The reply the model reads. Unchanged, and still the tool's advertised return. */
+    save(type: string, name: string, description: string, body: string, links?: readonly string[] | null): string;
+    /**
+     * `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: string, name: string, description: string, body: string, links?: readonly string[] | null): SaveOutcome;
+    /**
+     * `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: string, k?: number | null): string;
+    /**
+     * `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: string, k?: number | null): RecallOutcome;
+    /**
+     * 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?: number | null): string;
+    /**
+     * `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?: number | null): CompactOutcome;
+    /**
+     * `(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(): [indexBytes: number | null, budget: number];
+    /**
+     * 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.
+     */
+    private nothingToReport;
+    /**
+     * 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.
+     */
+    private static factCount;
+    /** Roots of the layers that could not be listed at all — never counted as 0. */
+    private unreadableLayers;
+    /**
+     * 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.
+     */
+    private searchableFacts;
+    /**
+     * 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.
+     */
+    private static isProfileStore;
+    /**
+     * 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.
+     */
+    private walkAscended;
+    /**
+     * 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.
+     */
+    private bindingDiagnosis;
+    private format;
+}