bantamkit-mcp 0.29.2 → 0.30.0

package/README.md

@@ -1,7 +1,7 @@
 # bantamkit-mcp
 
 The bantamkit MCP server as a pure-Node package: `npx bantamkit-mcp`, no Python, no
-`uv`, no `pipx`, no interpreter bootstrap. It serves the same eleven tools, the same
+`uv`, no `pipx`, no interpreter bootstrap. It serves the same thirteen tools, the same
 `bantamkit_status` prompt and the same two resource templates as `runtime-py`'s server,
 reads and writes the same memory store, and is checked against the Python server frame by
 frame — 4500+ conformance cases, with every intentional difference written down as a

package/assets/tools/memory_dream.json

@@ -0,0 +1,20 @@
+{
+  "name": "memory_dream",
+  "description": "Consolidate the memories the project layer and the machine-wide profile layer hold under the SAME NAME, and say exactly what changed. Byte-identical copies collapse to one; a pair that has diverged is UNIONED — every claim from both copies survives, never a winner-takes-all — and a relative date in a body is annotated with the day it resolves to against that fact's own mtime, never against today. The survivor stays in the writable project layer and the profile copy MOVES to that store's archive/: nothing is deleted and any consumed memory can be restored by name. This is a correctness pass, not a token saving: the profile index is derived at read time and is not loaded from a prompt, so consolidating it frees approximately no bytes — what it buys is one copy of a ruling instead of two that can disagree. It defaults to a DRY RUN because the profile store is machine-wide: a memory archived out of it stops answering for every other project on this machine that has no store of its own. Read the plan first, then call it again with dry_run false to apply it.",
+  "surfaces": ["mcp"],
+  "parameters": {
+    "type": "object",
+    "properties": {
+      "dry_run": {
+        "type": "boolean",
+        "description": "Preview only. True (the default) performs every read, merge and projection and writes nothing. Pass false to apply the plan."
+      }
+    }
+  },
+  "output_schema": {
+    "properties": { "result": { "title": "Result", "type": "string" } },
+    "required": ["result"],
+    "type": "object",
+    "title": "memory_dreamOutput"
+  }
+}

package/assets/tools/repo_map.json

@@ -0,0 +1,44 @@
+{
+  "name": "repo_map",
+  "description": "A ranked map of a source tree: every file's definitions, ordered by how central that file is to the files you name in `focus`, truncated to a byte budget. Call it when you are about to work on a file and want to know which OTHER files matter to it — the ports, the callers, the module it reaches through a private helper — rather than reading a directory listing and guessing. `focus` is the file or files you are editing, relative to `root` and POSIX-separated; they are excluded from the listing because you already have them open, and an empty focus gives plain centrality over the whole tree. This is a PRECISION pass and it is not a token saving: the gate this feature was supposed to clear 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. Nothing the scanner cannot read is dropped silently: every unread file resolves into a named omission (unknown-language, unreadable-bytes, size-cap, no-definitions, unreachable, per-file-cap, budget) counted in a footer that is NOT charged to the budget. The budget is UTF-8 BYTES of the listing, not tokens; there is no model tokenizer in either runtime and this tool will not pretend to one.",
+  "surfaces": [
+    "mcp"
+  ],
+  "parameters": {
+    "type": "object",
+    "required": [
+      "root"
+    ],
+    "properties": {
+      "root": {
+        "type": "string",
+        "description": "Directory to map, absolute or relative to the server's working directory"
+      },
+      "focus": {
+        "type": "array",
+        "items": {
+          "type": "string"
+        },
+        "description": "The files you are working on, relative to `root` and POSIX-separated. They are excluded from the listing. A name that is not a scanned source is ignored rather than refused."
+      },
+      "budget": {
+        "type": "integer",
+        "minimum": 0,
+        "description": "UTF-8 bytes of listing to render; default 4000. The omission footer is not charged against it."
+      }
+    }
+  },
+  "output_schema": {
+    "properties": {
+      "result": {
+        "title": "Result",
+        "type": "string"
+      }
+    },
+    "required": [
+      "result"
+    ],
+    "type": "object",
+    "title": "repo_mapOutput"
+  }
+}

package/dist/eventlog.js

@@ -32,10 +32,11 @@
  *   one stray write breaks the wire suite. Nothing in this module names `process.stdout`,
  *   `process.stderr` or `console`.
  * * **Metadata only.** Never a tool argument's value, never a memory body, never a
- *   validated output, never a query, never a document row. Six of the eleven tools take
- *   unbounded free text and five take absolute paths (`bantamkit_read`'s `path` is one and
- *   `skill_audit`'s `root` is another; each record carries counts and tokens from a closed
- *   set — never the path, never a part name, never a skill id).
+ *   validated output, never a query, never a document row. Seven of the thirteen tools take
+ *   unbounded free text and six take absolute paths (`bantamkit_read`'s `path` is one,
+ *   `skill_audit`'s `root` is another and `repo_map`'s `root` and `focus` are the third;
+ *   each record carries counts and tokens from a closed set — never the path, never a part
+ *   name, never a skill id, never a mapped file).
  *   Every value written here is an ASCII token from a closed set, a number, or a boolean.
  * * **Never `String(err)`.** Only the constructor name. This is not hypothetical: the host
  *   itself has already persisted `input_value={'schema_path': '/Users/k...

package/dist/index.d.ts

@@ -13,11 +13,13 @@ export type { PyOrder, YamlScalar, YamlValue } from './memory/pyyaml.js';
 export { countFacts, discoverProjectStore, loadGrants, MEMORY_DIR_ENV, PROJECT_STORE, resolveProjectStore, } from './memory/layers.js';
 export type { StoreBinding } from './memory/layers.js';
 export { layerLabel, Memory, normalizeName, profileStore } from './memory/component.js';
-export type { CompactOutcome, MemoryOptions, RecallOutcome, SaveOutcome } from './memory/component.js';
+export type { CompactOutcome, DreamOutcome, MemoryOptions, RecallOutcome, SaveOutcome, } from './memory/component.js';
+export { absolutise, blockKey, claimSlot, collapse, dream, formatFixed3, mergeBodies, mergeDescriptions, mergeLinks, PROFILE_LAYER, PROJECT_LAYER, pyIntDigits, sortedNames, splitBlocks, SUPERSEDED_HEADING, } from './memory/dream.js';
+export type { DateHit, DreamMerge, DreamResult, SimilarPair, Superseded } from './memory/dream.js';
 export { CAP_BYTES, DEFAULT_RELATIVE_PATH, defaultPath, encodeRecord, EVENT_LOG_ENV, EventLog, formatTimestamp, resolvePath, SCHEMA_VERSION, } from './eventlog.js';
 export type { DetailValue } from './eventlog.js';
-export { DEFAULT_INDEX_BUDGET, DUPLICATE_JACCARD, jaccard, MemoryBudgetExceeded, MemoryStore, MemoryValidationError, pyCompareLt, pyEqualValue, pyHashKey, pyText, sortScored, tokens, VALID_TYPES, } from './memory/store.js';
-export type { MemoryStoreOptions, SaveResult } from './memory/store.js';
+export { DEFAULT_INDEX_BUDGET, DUPLICATE_JACCARD, jaccard, MemoryBudgetExceeded, MemoryStore, MemoryValidationError, pyCompareLt, pyEqualValue, pyHashKey, pyText, RECALL_MIN_SCORE_RATIO, sortScored, tokens, VALID_TYPES, } from './memory/store.js';
+export type { MemoryStoreOptions, SaveResult, StoreInternals } from './memory/store.js';
 export { asPyOSError, cmpCodepoint, matchesMd, normcase, pyDecodeUtf8, pyCwd, pyExists, pyExpanduser, pyHome, pyIsAbsolute, pyIsDir, pyIsFile, pyJoin, pyLexists, pyMkdirParents, pyMtimeDate, pyName, PyOSError, pyParent, pyParents, pyReadText, pyReplace, pyRepr, pyResolve, PyRuntimeError, pyScandirNames, PyUnicodeDecodeError, pyAppendText, pyStatIsDir, pySuffix, pyUnlink, pyWithSuffix, pyWriteText, sortedPathNames, sortedPathParts, STRERROR_NAMES, } from './memory/pyfs.js';
 export { clockIn, clockOut, HISTORY_RING_SIZE, SCHEMA_NAME, status, TERMINAL_UNIT_STATUS, timestamp, } from './shiftwork.js';
 export type { ClockOptions } from './shiftwork.js';

package/dist/index.js

@@ -7,7 +7,8 @@ export { decodeFactBytes, FactParseError, formatFact, parseFactText, parseFrontm
 export { constructPlain, PyScalar, resolveImplicitTag, safeDumpMapping, YamlConstructError, YamlEmitError, } from './memory/pyyaml.js';
 export { countFacts, discoverProjectStore, loadGrants, MEMORY_DIR_ENV, PROJECT_STORE, resolveProjectStore, } from './memory/layers.js';
 export { layerLabel, Memory, normalizeName, profileStore } from './memory/component.js';
+export { absolutise, blockKey, claimSlot, collapse, dream, formatFixed3, mergeBodies, mergeDescriptions, mergeLinks, PROFILE_LAYER, PROJECT_LAYER, pyIntDigits, sortedNames, splitBlocks, SUPERSEDED_HEADING, } from './memory/dream.js';
 export { CAP_BYTES, DEFAULT_RELATIVE_PATH, defaultPath, encodeRecord, EVENT_LOG_ENV, EventLog, formatTimestamp, resolvePath, SCHEMA_VERSION, } from './eventlog.js';
-export { DEFAULT_INDEX_BUDGET, DUPLICATE_JACCARD, jaccard, MemoryBudgetExceeded, MemoryStore, MemoryValidationError, pyCompareLt, pyEqualValue, pyHashKey, pyText, sortScored, tokens, VALID_TYPES, } from './memory/store.js';
+export { DEFAULT_INDEX_BUDGET, DUPLICATE_JACCARD, jaccard, MemoryBudgetExceeded, MemoryStore, MemoryValidationError, pyCompareLt, pyEqualValue, pyHashKey, pyText, RECALL_MIN_SCORE_RATIO, sortScored, tokens, VALID_TYPES, } from './memory/store.js';
 export { asPyOSError, cmpCodepoint, matchesMd, normcase, pyDecodeUtf8, pyCwd, pyExists, pyExpanduser, pyHome, pyIsAbsolute, pyIsDir, pyIsFile, pyJoin, pyLexists, pyMkdirParents, pyMtimeDate, pyName, PyOSError, pyParent, pyParents, pyReadText, pyReplace, pyRepr, pyResolve, PyRuntimeError, pyScandirNames, PyUnicodeDecodeError, pyAppendText, pyStatIsDir, pySuffix, pyUnlink, pyWithSuffix, pyWriteText, sortedPathNames, sortedPathParts, STRERROR_NAMES, } from './memory/pyfs.js';
 export { clockIn, clockOut, HISTORY_RING_SIZE, SCHEMA_NAME, status, TERMINAL_UNIT_STATUS, timestamp, } from './shiftwork.js';

package/dist/mcp/pyargs.d.ts

@@ -31,7 +31,7 @@ import { type PyValue } from '../pyjson.js';
 /** What a parameter accepts. `optional` is `| None = None` in the signature. */
 export interface FieldSpec {
     readonly name: string;
-    readonly kind: 'str' | 'int' | 'dict' | 'dictInt' | 'dictStr' | 'listStr';
+    readonly kind: 'str' | 'int' | 'bool' | 'dict' | 'dictInt' | 'dictStr' | 'listStr';
     readonly optional: boolean;
     /** `Field(le=...)`: an inclusive ceiling, checked AFTER the lax int parse succeeds. */
     readonly le?: bigint;

package/dist/mcp/pyargs.js

@@ -126,6 +126,28 @@ export const ARG_MODELS = {
     // `dict[str, str]`, and the reason `dictStr` exists beside it: a `str` field is STRICT even
     // in lax mode, so `{'a': 1}` is `versions.a` / `string_type` where the same value under
     // `usage` would validate.
+    // `dry_run: bool | None = None` on the reference (job45 row 5). LAX bool, and every arm
+    // below was MEASURED against the real stdio server, not read off pydantic's docs
+    // (`scratchpad` probe, 33 inputs): `0`/`1` and `0.0`/`1.0` coerce; any OTHER integral
+    // number — `2`, `-1`, `2.0` — is `bool_parsing`; a FRACTIONAL float is `bool_type`, a
+    // different frame from the integral one and the reason the float arm is split; a string
+    // is matched case-insensitively against two closed sets and is NOT stripped first, so
+    // `'true'` validates and `' true '` is `bool_parsing`; `''` is `bool_parsing`; a list or a
+    // dict is `bool_type`; and an explicit `null` is the default.
+    memory_dream: { model: 'memory_dreamArguments', fields: [opt('dry_run', 'bool')] },
+    // `repo_map(root: str, focus: list[str] | None = None, budget: int | None = None)` on
+    // the reference (job45 row 10). `root` is the strict `str` every other string field is —
+    // `123` is `string_type`. `focus` is the same `list[str]` as `skill_audit`'s `enabled`,
+    // so a non-list is `list_type` and a list holding a non-string is `focus.0` /
+    // `string_type`. `budget` is the lax `int` that `k`, `reserve` and `limit` are: `'2'`,
+    // `True` and `3.0` validate, `'2.5'` is `int_parsing`, `2.5` is `int_from_float`, and an
+    // explicit `null` is the default. No `le`, because the reference binds none — the
+    // manifest's `minimum: 0` is advisory to the client and the handler's own refusal is the
+    // negative one, exactly as `skill_audit`'s `budget` works.
+    repo_map: {
+        model: 'repo_mapArguments',
+        fields: [req('root', 'str'), opt('focus', 'listStr'), opt('budget', 'int')],
+    },
     skill_audit: {
         model: 'skill_auditArguments',
         fields: [
@@ -178,6 +200,13 @@ function truncateRepr(text) {
         tail += 1;
     return `${decoder.decode(bytes.slice(0, head))}...${decoder.decode(bytes.slice(tail))}`;
 }
+/**
+ * The two closed sets pydantic-core matches a string against for a lax `bool`, lowercased.
+ *
+ * No stripping: `' true '` is `bool_parsing` on the reference, measured over the wire.
+ */
+const BOOL_TRUE = new Set(['1', 'on', 't', 'true', 'y', 'yes']);
+const BOOL_FALSE = new Set(['0', 'off', 'f', 'false', 'n', 'no']);
 /** i64, which is the width pydantic parses an int into before it complains about size. */
 const I64_MAX = 9223372036854775807n;
 const I64_MIN = -9223372036854775808n;
@@ -258,6 +287,45 @@ function checkField(spec, value) {
             }
             return bad.length > 0 ? bad : { value };
         }
+        case 'bool': {
+            const parsing = () => [
+                {
+                    loc: spec.name,
+                    type: 'bool_parsing',
+                    msg: 'Input should be a valid boolean, unable to interpret input',
+                    input: value,
+                },
+            ];
+            const wrongType = () => [
+                { loc: spec.name, type: 'bool_type', msg: 'Input should be a valid boolean', input: value },
+            ];
+            if (value.t === 'bool')
+                return { value };
+            if (value.t === 'int') {
+                if (value.v === 0n || value.v === 1n)
+                    return { value: { t: 'bool', v: value.v === 1n } };
+                return parsing();
+            }
+            if (value.t === 'float') {
+                // A FRACTIONAL float is `bool_type` and an out-of-range integral one is
+                // `bool_parsing`. Measured, and not a distinction anyone would guess: `0.5` and
+                // `2.0` are both floats and they refuse under different frames.
+                if (!Number.isInteger(value.v))
+                    return wrongType();
+                if (value.v === 0 || value.v === 1)
+                    return { value: { t: 'bool', v: value.v === 1 } };
+                return parsing();
+            }
+            if (value.t === 'str') {
+                const key = value.v.toLowerCase();
+                if (BOOL_TRUE.has(key))
+                    return { value: { t: 'bool', v: true } };
+                if (BOOL_FALSE.has(key))
+                    return { value: { t: 'bool', v: false } };
+                return parsing();
+            }
+            return wrongType();
+        }
         case 'int': {
             const checked = checkInt(spec.name, value);
             if (!('value' in checked))

package/dist/mcp/server.d.ts

@@ -1,17 +1,19 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import * as repomap from '../repomap.js';
 import { EventLog } from '../eventlog.js';
 import type { Memory } from '../memory/component.js';
 import type { RawStdioTransport } from './transport.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 declare const MCP_TOOLS: readonly ["memory_save", "memory_recall", "validate_json", "shiftwork_clock_in", "shiftwork_clock_out", "shiftwork_status", "build_identity", "bantamkit_status", "memory_compact", "bantamkit_read", "skill_audit"];
+export declare const MCP_TOOLS: readonly ["memory_save", "memory_recall", "validate_json", "shiftwork_clock_in", "shiftwork_clock_out", "shiftwork_status", "build_identity", "bantamkit_status", "memory_compact", "bantamkit_read", "skill_audit", "memory_dream", "repo_map"];
 /**
  * The advertisement for one tool, out of its manifest, with the surface checked.
  *
@@ -28,6 +30,34 @@ export declare const MCP_TOOLS: readonly ["memory_save", "memory_recall", "valid
  * that detects drift. Registered here, not fixed here; `runtime-py` is the reference.
  */
 export declare function fromManifest(name: string): Record<string, unknown>;
+/**
+ * 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 declare const REPO_MAP_TAIL: string;
+/** What a listing says when there is nothing to list. The reference's `REPO_MAP_EMPTY`. */
+export declare 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 declare function repoMapReply(result: repomap.RepoMap): string;
 /**
  * Assemble the MCP server around one Memory instance (the per-person state).
  *

package/dist/mcp/server.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.
  *
@@ -448,6 +511,29 @@ function runTool(name, memory, args, version, log, documents) {
             });
             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,
@@ -645,6 +731,67 @@ function runTool(name, memory, args, version, log, documents) {
                 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.

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`

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`.
      *