bantamkit-mcp 0.29.1 → 0.30.0

package/dist/mcp/server.js

@@ -22,7 +22,7 @@
  * indistinguishable from a typo: a manifest renamed or a surface dropped would silently
  * shrink the served set, and the field would be a comment.
  */
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
@@ -31,6 +31,7 @@ import { AssetNotFound, assetsRoot, loadSkill, loadToolAsset } from '../assets.j
 import { BantamError } from '../errors.js';
 import { bantamkitReadUnknownPart, documentError, documentManifest, documentOffsetPastEnd, documentPage, schemaError, toolFailed, } from '../contract.js';
 import * as docread from '../docread.js';
+import * as repomap from '../repomap.js';
 import * as skillaudit from '../skillaudit.js';
 import { EventLog } from '../eventlog.js';
 import { PyOSError, asPyOSError, pyReadText } from '../memory/pyfs.js';
@@ -41,13 +42,14 @@ import { ARG_MODELS, PyValidationFailure, validateArguments } from './pyargs.js'
 import { sdkJson } from './sdkjson.js';
 import { degradedConditions, degradedNotice, SERVED_PROMPTS, SERVED_RESOURCE_TEMPLATES, statusReport, STATUS_NAME, STATUS_PROMPT_DESCRIPTION, STATUS_PROMPT_TAIL, STATUS_PROMPT_TITLE, } from './status.js';
 /**
- * The eleven, in the order `build_server` lists them — which is the order `tools/list` emits.
+ * The thirteen, in the order `build_server` lists them — which is the order `tools/list` emits.
  *
  * `bantamkit_status` went LAST rather than first, `memory_compact` after it rather than
- * beside `memory_save` where a reader would look for it, `bantamkit_read` after that and
- * `skill_audit` after that, for the same reason the reference appends all four: registration
- * order IS the served order, and appending is the only edit that leaves the other ten where
- * every existing declaration says they are.
+ * beside `memory_save` where a reader would look for it, `bantamkit_read` after that,
+ * `skill_audit` after that, `memory_dream` after that and `repo_map` after that, for the
+ * same reason the reference appends all six: registration order IS the served order, and
+ * appending is the only edit that leaves the other twelve where every existing declaration
+ * says they are.
  */
 export const MCP_TOOLS = [
     'memory_save',
@@ -61,6 +63,8 @@ export const MCP_TOOLS = [
     'memory_compact',
     'bantamkit_read',
     'skill_audit',
+    'memory_dream',
+    'repo_map',
 ];
 /**
  * The advertisement for one tool, out of its manifest, with the surface checked.
@@ -147,6 +151,65 @@ const asText = (value) => (value && value.t === 'str' ? value.v : '');
 function asInt(value) {
     return value && value.t === 'int' ? Number(value.v) : null;
 }
+/**
+ * The errno family `Path.exists()` and `Path.is_dir()` answer `False` for instead of
+ * raising — CPython `pathlib`'s `_IGNORED_ERRNOS`, spelled as Node's `code` strings.
+ *
+ * Not a guess and not a superset: anything OUTSIDE this set makes both predicates raise on
+ * the reference, so it must reach `recordRaise` here too. A `statSync` wrapped in a bare
+ * `catch { }` would turn a permission failure into "no such directory", which is a
+ * different sentence about a different problem.
+ */
+const EXISTS_IGNORED = new Set(['ENOENT', 'ENOTDIR', 'EBADF', 'ELOOP']);
+/**
+ * The last paragraph of every `repo_map` reply, refusal excepted. FIXED AND MANDATORY, and
+ * byte-identical to the reference's `REPO_MAP_TAIL`.
+ *
+ * Roadmap row 10's build gate was "build only after #4 shows discovery tokens dominate",
+ * and #4 REFUTED it: discovery is 0.114 % of real prompt tokens because 97.8 % of the bill
+ * is `cache_read`. The feature ships on an explicit ruling to build it anyway, as a
+ * PRECISION feature. A surface that let a caller believe the map is a token saving would
+ * say the one thing the measurement forbids, so the refutation travels with every answer
+ * rather than living only in a doc nobody reads at call time.
+ *
+ * The second sentence is the budget's unit, for the same reason: `DEFAULT_BUDGET = 4000` is
+ * "1 K tokens" only at the char/4 convention, whose error bar is unmeasured because
+ * measuring it needs the tokenizer the pure-node ruling forbids.
+ */
+export const REPO_MAP_TAIL = 'This is a precision pass, not a token saving: this feature\'s build gate was REFUTED ' +
+    'by measurement — discovery is 0.114% of real prompt tokens, because 97.8% of the ' +
+    'bill is cache_read — so a map does not make a session cheaper. What it buys is the ' +
+    'right file found sooner.\n' +
+    'The budget above is UTF-8 BYTES of listing, not tokens: neither runtime carries a ' +
+    'model tokenizer and this tool will not pretend to one.';
+/** What a listing says when there is nothing to list. The reference's `REPO_MAP_EMPTY`. */
+export const REPO_MAP_EMPTY = '(nothing listed: no file under this root scanned into a definition)';
+/**
+ * The `repo_map` tool's prose, byte for byte, from the structured result.
+ *
+ * Split out of the handler for the same reason the reference splits `repo_map_reply` out of
+ * its own: one shape to reproduce rather than a format string buried in a `case`, and the
+ * `repomap` conformance suite compares the rendered reply without standing up a server. No
+ * float is ever rendered here — `repomap`'s trap (8); every number on the header line is an
+ * integer, and `String(1.0)` is `'1'` where `repr(1.0)` is `'1.0'`.
+ */
+export function repoMapReply(result) {
+    const focus = result.focus.length > 0
+        ? result.focus.join(', ')
+        : '(none) — plain centrality over the whole tree';
+    const head = `repo map: ${result.nodes} files scanned, ${result.definitions} definitions, ` +
+        `${result.edges} edges.\n` +
+        `focus: ${focus}\n` +
+        `budget: ${result.budget} UTF-8 bytes; listing ${result.listingBytes} bytes; ` +
+        `rendered ${result.filesRendered} files, ` +
+        `${result.definitionsRendered} definitions.`;
+    const body = result.text !== '' ? result.text : REPO_MAP_EMPTY;
+    return `${head}\n\n${body}\n\n${REPO_MAP_TAIL}`;
+}
+/** `bool | None` after validation: the tagged bool, or `null` for the default. */
+function asBool(value) {
+    return value && value.t === 'bool' ? value.v : null;
+}
 /**
  * Run `body` and, if it throws, record the exception's TYPE before letting it fly on.
  *
@@ -173,6 +236,87 @@ function recordRaise(log, tool, body) {
         throw e;
     }
 }
+/**
+ * The last `docread.extract` result this server produced, and what it was OF.
+ *
+ * The port of `mcpserver._DocumentCache` (register entry (i), `docs/roadmap-toolbox.md` row
+ * 8). `bantamkit_read` re-parsed the whole document on EVERY call, so a caller paging a
+ * 12,001-row sheet in 200-row pages parsed the workbook once per page — paging was O(N^2) in
+ * the row window. MEASURED on this machine over a 1,553,944-byte 12,001-row xlsx driven
+ * through a real client with `docread.extract` counted by a loader hook: 68 tool calls, **68**
+ * parses, 4.128 s for the walk. After, over the same fixture and the same counter: **1**
+ * parse, 0.104 s (0.103 / 0.108 on two repeats). The committed, rerunnable form of the same
+ * count is `test/document-cache-and-bounds.test.mjs`, at 7 calls rather than 68.
+ *
+ * ONE entry, deliberately, and for the reference's reason. A single entry evicts whenever two
+ * callers alternate between two documents, and that case then costs exactly one parse per
+ * call — which is what the code this replaces cost for EVERY case, so the cache cannot make
+ * any caller slower than it was (`test/document-cache-and-bounds.test.mjs` counts the
+ * alternating walk and pins the number). What more entries would cost is resident memory: a
+ * `Document` holds its whole rendering as strings, bounded per document by
+ * `docread.TEXT_MAX_BYTES` and `docread.XLSX_MAX_TEXT_BYTES` (16 MiB each), and every extra
+ * entry multiplies that ceiling by one.
+ *
+ * **The key is (realpath, size, mtimeNs), and it has one hole — stated, not implied.** A
+ * rewrite that lands inside a single filesystem timestamp tick AND leaves the byte count
+ * unchanged is indistinguishable from no rewrite at all, and would be served from the stale
+ * parse. `mtimeNs` is nanosecond-SHAPED and not nanosecond-GRAINED: what it reports is
+ * whatever the filesystem stored, which on HFS+ is one second and on APFS/ext4 is finer but
+ * not unbounded. The alternative — hashing the bytes — would re-read the file this cache
+ * exists to avoid re-reading, which is the whole cost on the large documents that motivate
+ * it. So the hole stays, and the test that proves the key works changes the SIZE rather than
+ * racing the clock, because a test that raced it would be measuring the filesystem.
+ *
+ * THE CACHED VALUE IS THE RESULT, NEVER A READER. `docread.extract` hands its own `ZipReader`
+ * down to `extractXlsx`/`extractDocx` so an archive is read from disk once instead of twice,
+ * and that reader's lifetime ends with the `extract` call that opened it. This sits one layer
+ * above and holds a finished `Document`; no file handle outlives a call because of it.
+ */
+class DocumentCache {
+    key = null;
+    doc = null;
+    /** The cached document for `key`, or `null` — a `null` key never matches. */
+    get(key) {
+        if (key === null || key !== this.key) {
+            return null;
+        }
+        return this.doc;
+    }
+    put(key, doc) {
+        if (key === null) {
+            return;
+        }
+        this.key = key;
+        this.doc = doc;
+    }
+}
+/**
+ * What identifies the bytes at `path` — or `null`, which means "do not cache".
+ *
+ * `statSync` FOLLOWS symlinks, which is the same file the reader is about to open, and
+ * `{bigint: true}` is not decoration: `Stats.mtimeMs` is a float and has already lost the
+ * sub-millisecond digits the reference's `st_mtime_ns` keeps, so a key built from it would
+ * have a coarser hole than the one documented above. `size` and `mtimeNs` are read from the
+ * bigint view for the same reason.
+ *
+ * Any error here returns `null` rather than refusing: this is a cache key, and the refusal a
+ * caller reads must be the one `docread.extract` raises in the reader's own words, not one
+ * this function invented from a different syscall's errno. That covers the one shape the
+ * reference does not have — `os.path.realpath` is non-strict in CPython and answers even for
+ * a path that does not resolve, while `realpathSync` throws. A path that stats but will not
+ * resolve is therefore uncached here and cached there; nothing a client can observe moves,
+ * because the reply is the reader's either way.
+ */
+function documentKey(path) {
+    try {
+        const stat = statSync(path, { bigint: true });
+        // NUL cannot occur in a path on either platform, so the join is unambiguous.
+        return `${realpathSync(path)}\0${stat.size}\0${stat.mtimeNs}`;
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Run a shiftwork handler and record its `result` — the register's OWN verdict.
  *
@@ -230,7 +374,7 @@ function recordResult(log, tool, call) {
  * byte-compares, and would make the log move when nothing the tool did moved. `noted` and
  * `notedDict` below therefore run last, on the way out.
  */
-function runTool(name, memory, args, version, log) {
+function runTool(name, memory, args, version, log, documents) {
     /**
      * The footer for right now — recomputed per call, never cached.
      *
@@ -367,6 +511,29 @@ function runTool(name, memory, args, version, log) {
             });
             return { value: { t: 'str', v: noted(outcome.reply) }, wrapped: true };
         }
+        case 'memory_dream': {
+            // Consolidate what the project layer and the machine-wide profile layer both hold
+            // under one name (job45, roadmap row 5). `dryRun` DEFAULTS TO TRUE and the default
+            // lives HERE rather than in the component, exactly as the reference's handler carries
+            // it: a client that omits the argument sends nothing, `asBool` answers `null`, and
+            // turning that into the SAFE answer is this handler's job. It is the only tool on
+            // this surface that writes into the user's home directory, and the only one whose
+            // effect is machine-wide — a fact archived out of the profile store stops answering
+            // for every other project on this machine with no store of its own.
+            //
+            // THE RECORD IS A DECISION. `DreamOutcome.status` is read off `DreamResult.applied`,
+            // `.overBudget` and `.changes` — never off the reply, whose prose is allowed to
+            // improve without moving a single byte of the event log.
+            const dryRun = asBool(args.get('dry_run'));
+            const outcome = recordRaise(log, 'memory_dream', () => memory.dreamOutcome(dryRun === null ? true : dryRun));
+            log.record('memory_dream', outcome.status, {
+                absolutised: outcome.absolutised,
+                consumed: outcome.consumed,
+                dry_run: outcome.dryRun,
+                merged: outcome.merged,
+            });
+            return { value: { t: 'str', v: noted(outcome.reply) }, wrapped: true };
+        }
         case 'bantamkit_read': {
             // The reader on the MCP surface (job43): `docread` digests, `contract` words it. The
             // handler makes the SAME `contract` calls the reference's `bantamkit_read` makes,
@@ -403,37 +570,46 @@ function runTool(name, memory, args, version, log) {
             // `document_error` like the encrypted one. Until job43 G2 this arm ran `extract`
             // outside `recordRaise` with a hand-copied catch.
             return recordRaise(log, 'bantamkit_read', () => {
-                let doc;
-                try {
-                    doc = docread.extract(path);
-                }
-                catch (e) {
-                    // `except (docread.DocumentReadError, OSError)`. A Node fs error is CPython's
-                    // `OSError` with the sentence rebuilt by `asPyOSError` — `[Errno 13] Permission
-                    // denied: '<path>'` for a file this process may not open — through the CRT arm,
-                    // because `open()` is the call the reference makes. A `BadZipFile` never reaches
-                    // this arm on either side: `docread.ts`'s `zipKind`/`openZip` catch it exactly
-                    // where `docread.py`'s `_zip_kind`/`_open` do, and what leaves them is the
-                    // sentence naming what the reader saw, never the zip module's.
-                    // A `PyOSError` the reader raised itself is already the reference's sentence —
-                    // `[Errno 22] Invalid argument` from a zip whose member offset is negative, with
-                    // NO filename, because the `seek` that fails there has none. Re-wrapping it would
-                    // append `: '<path>'`.
-                    // ONLY a filesystem rejection is an `OSError`: numeric `errno` AND the `syscall`
-                    // it came from. A string `code` alone is not one — `Z_DATA_ERROR`,
-                    // `ERR_INVALID_ARG_VALUE` and `ERR_STRING_TOO_LONG` all carry one, and until job43
-                    // G2 each was printed as a fabricated `[Errno 0] …` sentence where the reference
-                    // raises (the corrupt stream) or says `no such file` (the NUL byte, which
-                    // `docread.statPath` now answers before this arm is reached).
-                    const refusal = e instanceof docread.DocumentReadError || e instanceof PyOSError
-                        ? e
-                        : isFsError(e)
-                            ? asPyOSError(e, path, undefined, 'crt')
-                            : null;
-                    if (refusal === null)
-                        throw e;
-                    log.record('bantamkit_read', 'refused-unreadable');
-                    return { value: { t: 'str', v: noted(documentError(refusal)) }, wrapped: true };
+                // (i): the parse is cached on (realpath, size, mtimeNs), so a paging walk over one
+                // unchanged document parses it once. `documentKey` answering `null` means "do not
+                // cache" and leaves this arm exactly as it was.
+                const key = documentKey(path);
+                let doc = documents.get(key);
+                if (doc === null) {
+                    try {
+                        doc = docread.extract(path);
+                    }
+                    catch (e) {
+                        // `except (docread.DocumentReadError, OSError)`. A Node fs error is CPython's
+                        // `OSError` with the sentence rebuilt by `asPyOSError` — `[Errno 13] Permission
+                        // denied: '<path>'` for a file this process may not open — through the CRT arm,
+                        // because `open()` is the call the reference makes. A `BadZipFile` never reaches
+                        // this arm on either side: `docread.ts`'s `zipKind`/`openZip` catch it exactly
+                        // where `docread.py`'s `_zip_kind`/`_open` do, and what leaves them is the
+                        // sentence naming what the reader saw, never the zip module's.
+                        // A `PyOSError` the reader raised itself is already the reference's sentence —
+                        // `[Errno 22] Invalid argument` from a zip whose member offset is negative, with
+                        // NO filename, because the `seek` that fails there has none. Re-wrapping it would
+                        // append `: '<path>'`.
+                        // ONLY a filesystem rejection is an `OSError`: numeric `errno` AND the `syscall`
+                        // it came from. A string `code` alone is not one — `Z_DATA_ERROR`,
+                        // `ERR_INVALID_ARG_VALUE` and `ERR_STRING_TOO_LONG` all carry one, and until job43
+                        // G2 each was printed as a fabricated `[Errno 0] …` sentence where the reference
+                        // raises (the corrupt stream) or says `no such file` (the NUL byte, which
+                        // `docread.statPath` now answers before this arm is reached).
+                        const refusal = e instanceof docread.DocumentReadError || e instanceof PyOSError
+                            ? e
+                            : isFsError(e)
+                                ? asPyOSError(e, path, undefined, 'crt')
+                                : null;
+                        if (refusal === null)
+                            throw e;
+                        log.record('bantamkit_read', 'refused-unreadable');
+                        return { value: { t: 'str', v: noted(documentError(refusal)) }, wrapped: true };
+                    }
+                    // A refusal is NOT cached: the entry holds a parse, and a path that has no parse
+                    // must reach the reader again next call so the reply stays the reader's own.
+                    documents.put(key, doc);
                 }
                 const detail = { kind: doc.kind, parts: doc.parts.length };
                 if (part === null) {
@@ -555,6 +731,67 @@ function runTool(name, memory, args, version, log) {
                 return { value: { t: 'str', v: noted(result.asJson()) }, wrapped: true };
             });
         }
+        case 'repo_map': {
+            // The ranked definition map on the MCP surface (job45 row 10): `repomap` measures,
+            // this serves it. Byte for byte the reference's `repo_map` handler.
+            //
+            // THE THREE REFUSALS LIVE HERE AND NOT IN `repomap.ts`, and that is deliberate.
+            // `repoMap()` over a root that does not exist answers an EMPTY map on both runtimes
+            // — `os.walk` yields nothing for a missing directory and `walkSources`' `readdirSync`
+            // catch does the same — which is the right answer for a library and the wrong one for
+            // a tool: a caller who typed the path wrong would be told the tree holds no source.
+            // So the argument checks are the SURFACE's, and the engine J45-9/J45-10 proved
+            // byte-identical is not touched.
+            //
+            // THE `statSync` ARM IS `Path.exists()` / `Path.is_dir()`, NOT A SHORTCUT FOR THEM.
+            // Both pathlib predicates SWALLOW the not-here errno family and re-raise anything
+            // else, so `EXISTS_IGNORED` below is that family spelled out: a dangling symlink and
+            // `a-file.py/sub` are "no such directory" on both runtimes, while a permission
+            // failure flies to `recordRaise` rather than being dressed up as a missing tree.
+            //
+            // THE RECORD IS A DECISION AND HOLDS NO PATH. `root` is what the operator typed and
+            // `focus` is the name of the file they are editing; neither is a decision this
+            // handler made, so neither is written down. The counts are.
+            const root = asText(args.get('root'));
+            const focusArg = args.get('focus');
+            const focus = focusArg !== undefined && focusArg.t === 'list'
+                ? focusArg.v.map((item) => (item.t === 'str' ? item.v : ''))
+                : [];
+            const budgetArg = args.get('budget');
+            const budget = budgetArg !== undefined && budgetArg.t === 'int' ? Number(budgetArg.v) : repomap.DEFAULT_BUDGET;
+            return recordRaise(log, 'repo_map', () => {
+                const refuse = (detail) => {
+                    log.record('repo_map', 'refused');
+                    return { value: { t: 'str', v: noted(toolFailed('repo_map', detail)) }, wrapped: true };
+                };
+                if (root === '')
+                    return refuse('root must not be empty; name the directory to map');
+                if (budget < 0)
+                    return refuse(`budget must not be negative; got ${budget}`);
+                let stat = null;
+                try {
+                    stat = statSync(root);
+                }
+                catch (e) {
+                    const code = e?.code;
+                    if (!EXISTS_IGNORED.has(String(code)))
+                        throw asPyOSError(e, root);
+                }
+                if (stat === null)
+                    return refuse(`no such directory: ${root}`);
+                if (!stat.isDirectory())
+                    return refuse(`${root} is a file, not a directory to map`);
+                const result = repomap.repoMap(root, { focus, budget });
+                log.record('repo_map', 'mapped', {
+                    definitions: result.definitions,
+                    edges: result.edges,
+                    files_rendered: result.filesRendered,
+                    listing_bytes: result.listingBytes,
+                    nodes: result.nodes,
+                });
+                return { value: { t: 'str', v: noted(repoMapReply(result)) }, wrapped: true };
+            });
+        }
         default:
             // `tool_manager.call_tool` raises `ToolError(f"Unknown tool: {name}")`, which the
             // handler turns into an isError result rather than a JSON-RPC error.
@@ -589,6 +826,10 @@ export function buildServer(memory, wire, version, log = EventLog.fromEnv(memory
         },
         instructions: loadSkill('memory'),
     });
+    // Per SERVER, not per process: two servers in one interpreter (the tests build several)
+    // must not answer each other's files, and the entry dies with the server rather than
+    // outliving it in a module global. The reference does the same, inside `build_server`.
+    const documents = new DocumentCache();
     // Startup, not call time: a tool without a manifest, or with the wrong surface, must stop
     // the process before a client ever sees a `tools/list`. The reference gets this from
     // `MCPServer(..., tools=[...])`; here it is one eager pass.
@@ -697,7 +938,7 @@ export function buildServer(memory, wire, version, log = EventLog.fromEnv(memory
             if (model === undefined)
                 throw new BantamError(`Unknown tool: ${name}`);
             const bound = validateArguments(model, args);
-            const { value, wrapped } = runTool(name, memory, bound, version, log);
+            const { value, wrapped } = runTool(name, memory, bound, version, log, documents);
             // `_convert_to_content` runs BEFORE the `{"result": ...}` wrap, so a str tool's text
             // block is the RAW STRING and a dict tool's is `to_json(..., indent=2)`.
             text = value.t === 'str' ? value.v : sdkJson(value, 2);

package/dist/memory/cli.js

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

package/dist/memory/component.d.ts

@@ -1,5 +1,6 @@
 import { type StoreBinding } from './layers.js';
 import { MemoryStore } from './store.js';
+import type { DreamResult } from './dream.js';
 /**
  * The model's spelling adapted to the store's contract: lowercase, `_`/space -> `-`.
  *
@@ -97,6 +98,30 @@ export interface RecallOutcome {
     readonly source: string | null;
     readonly unreadable: number;
 }
+/**
+ * What `dream` DID, beside the sentence it says about it.
+ *
+ * The same seam as `SaveOutcome`, `RecallOutcome` and `CompactOutcome`: `status` is read off
+ * a decision the pass already made — `DreamResult.applied`, `.overBudget`, `.changes` — and
+ * never off the reply. `result` carries the whole diff for a caller that wants the numbers
+ * rather than the prose.
+ *
+ * `status` is one of `consolidated`, `previewed`, `nothing-to-consolidate`,
+ * `refused-budget`, `no-profile-layer`.
+ */
+export interface DreamOutcome {
+    readonly reply: string;
+    readonly status: string;
+    readonly dryRun: boolean;
+    readonly merged: number;
+    readonly consumed: number;
+    readonly absolutised: number;
+    readonly superseded: number;
+    readonly indexBefore: number;
+    readonly indexAfter: number;
+    readonly budget: number;
+    readonly result: DreamResult | null;
+}
 export declare class Memory {
     readonly store: MemoryStore;
     readonly k: number;
@@ -140,7 +165,7 @@ export declare class Memory {
      * 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(query: string, k?: number | null, minRatio?: number): string;
     /**
      * `recall`, carrying the walk it performed as numbers rather than as prose.
      *
@@ -157,8 +182,18 @@ export declare class Memory {
      * 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.
+     *
+     * `minRatio` (roadmap #6) rides through to every layer's `MemoryStore.recall` unchanged,
+     * so the gate is measured against EACH LAYER's own best score and never across layers: a
+     * profile fact does not have to out-score the project store's top hit to be admitted,
+     * because the two stores are answering as two stores. Its default is
+     * `RECALL_MIN_SCORE_RATIO` = 0.0, which keeps every fact `recall` was going to return,
+     * and nothing on the tool path passes anything else today. A ratio outside `[0.0, 1.0]`
+     * raises out of the FIRST layer, which is the writable project store, so it surfaces as
+     * the error it is rather than as an `unreadable` count — the read-only-layer `catch`
+     * below would otherwise file a caller's bad argument as a corrupt grant.
      */
-    recallOutcome(query: string, k?: number | null): RecallOutcome;
+    recallOutcome(query: string, k?: number | null, minRatio?: number): RecallOutcome;
     /**
      * Archive the stalest facts until a fact as large as the biggest one kept will fit.
      *
@@ -179,6 +214,42 @@ export declare class Memory {
      * is — `MemoryStore.compact` builds it with `pyJoin`.
      */
     compactOutcome(reserve?: number | null): CompactOutcome;
+    /** Consolidate what the project and profile layers hold under the same name. */
+    dream(dryRun?: boolean): string;
+    /**
+     * `dream`, with the decision it took carried beside the sentence it wrote.
+     *
+     * ONLY THE PROFILE LAYER IS CONSUMED. `layers` also carries read-only GRANTS, and a grant
+     * is another operator's store: consolidating a fact out of one is not this person's move
+     * to make, so `dream` never looks at them. The label is matched exactly (`profile`), never
+     * by prefix, because a grant is labelled `extra:<name>` and a prefix match on a directory
+     * called `profile-something` would reach one.
+     *
+     * A `Memory` constructed directly — not through `layered` — has no profile layer at all,
+     * and that is `no-profile-layer` rather than an error: there is nothing to consolidate
+     * ACROSS when only one layer is bound.
+     *
+     * `dryRun` DEFAULTS TO TRUE. This is the only op in this component that writes into the
+     * user's home directory, and it is the only one whose effect is machine-wide: a fact
+     * archived out of the profile store stops answering for every other project on this
+     * machine that has no store of its own. A destructive consolidation nobody can preview is
+     * not shippable, so the safe call is the short one.
+     */
+    dreamOutcome(dryRun?: boolean): DreamOutcome;
+    /**
+     * The whole diff as prose: what merged, what was dated, what moved, what it cost.
+     *
+     * THE HONESTY SENTENCE AT THE END IS NOT DECORATION. Row 5 was planned as a token saving
+     * and J45-1 measured that it is not one: the profile store has no `index.md` on disk, its
+     * index is derived at read time, and nothing loads it into a prompt — so deduplicating it
+     * frees approximately zero prompt bytes. The value is that one ruling now has one copy
+     * instead of two that can disagree, and the reply says which of those two things the
+     * operator just bought.
+     *
+     * `formatFixed3` and not `toFixed(3)` for the two similarity figures: see the header of
+     * `dream.ts`. CPython's `.3f` rounds ties to EVEN and they are reachable.
+     */
+    private static dreamReply;
     /**
      * `(index bytes, budget)` for the writable project store; bytes may be `null`.
      *