bantamkit 0.29.2__tar.gz → 0.30.0__tar.gz

{bantamkit-0.29.2 → bantamkit-0.30.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: bantamkit
-Version: 0.29.2
+Version: 0.30.0
 Summary: bantamweight tooling — harness primitives that lift small-model agents
 License-Expression: MIT
 Requires-Python: >=3.11

bantamkit-0.30.0/_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"
+  }
+}

bantamkit-0.30.0/_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"
+  }
+}

{bantamkit-0.29.2 → bantamkit-0.30.0}/src/bantamkit/__init__.py

@@ -29,4 +29,4 @@ from bantamkit.structured import StructuredOutputError, extract_json, structured
 # file as its dynamic version source, so the wheel's metadata and the string the MCP
 # server advertises are the same committed bytes, and neither is a function of when
 # someone last ran `pip`.
-__version__ = "0.29.2"
+__version__ = "0.30.0"

{bantamkit-0.29.2 → bantamkit-0.30.0}/src/bantamkit/eventlog.py

@@ -30,10 +30,11 @@ THREE HARD RULES, each with the failure it prevents:
   byte-compares both runtimes' streams; one stray write breaks the wire suite. Nothing
   in this module touches `sys.stderr` or `sys.stdout`.
 * **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, an `int`, or a `bool`.
 * **Never `str(exception)`.** Only `type(exc).__name__`. This is not hypothetical: the

{bantamkit-0.29.2 → bantamkit-0.30.0}/src/bantamkit/mcpserver.py

@@ -17,7 +17,15 @@ from pathlib import Path
 from typing import Annotated, Any
 
 import bantamkit
-from bantamkit import __version__, docmanifest, docread, hostinstall, shiftwork, skillaudit
+from bantamkit import (
+    __version__,
+    docmanifest,
+    docread,
+    hostinstall,
+    repomap,
+    shiftwork,
+    skillaudit,
+)
 from bantamkit.assets import AssetNotFound, assets_root, load_skill, load_tool_asset
 from bantamkit.client import BantamError
 from bantamkit.contract import (
@@ -861,6 +869,59 @@ def _record_result(log: EventLog, tool: str, call: Callable[[], dict[str, Any]])
     return answer
 
 
+#: The last paragraph of every `repo_map` reply, refusal excepted. FIXED AND MANDATORY.
+#:
+#: 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. Bytes are what is
+#: enforced, so bytes are what the reply says.
+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. An empty string with two blank lines
+#: around it is not an answer, and "0 files" is already on the header line — this names the
+#: reason, which is the same discipline the omission footer is built on.
+REPO_MAP_EMPTY = "(nothing listed: no file under this root scanned into a definition)"
+
+
+def repo_map_reply(result: repomap.RepoMap) -> str:
+    """The `repo_map` tool's prose, byte for byte, from the structured result.
+
+    Split out of the handler so the two runtimes have ONE shape to reproduce rather than a
+    format string embedded in a `case`, and so the `repomap` conformance suite can compare
+    the rendered reply without standing up a server. No float is ever rendered here — see
+    `repomap`'s trap (8); every number on the header line is an int.
+    """
+    focus = (
+        ", ".join(result.focus)
+        if result.focus
+        else "(none) — plain centrality over the whole tree"
+    )
+    head = (
+        f"repo map: {result.nodes} files scanned, {result.definitions} definitions, "
+        f"{result.edges} edges.\n"
+        f"focus: {focus}\n"
+        f"budget: {result.budget} UTF-8 bytes; listing {result.listing_bytes} bytes; "
+        f"rendered {result.files_rendered} files, "
+        f"{result.definitions_rendered} definitions."
+    )
+    body = result.text if result.text else REPO_MAP_EMPTY
+    return f"{head}\n\n{body}\n\n{REPO_MAP_TAIL}"
+
+
 def build_server(memory: Memory, log: EventLog | None = None) -> Any:
     """Assemble the MCP server around one Memory instance (the per-person state).
 
@@ -984,6 +1045,34 @@ def build_server(memory: Memory, log: EventLog | None = None) -> Any:
         )
         return _noted(outcome.reply)
 
+    def memory_dream(dry_run: bool | None = None) -> str:
+        """Consolidate what the project and the machine-wide profile layer both hold.
+
+        `dry_run` DEFAULTS TO TRUE and the default lives HERE rather than in the
+        component: a client that omits the argument gets `None` through pydantic's
+        `bool | None = None`, 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 — so the short call is the preview.
+
+        The status is a decision the pass already made (`DreamResult.applied`,
+        `.over_budget`, `.changes`), never a match on the reply.
+        """
+        with _record_raise(log, "memory_dream"):
+            outcome = memory.dream_outcome(True if dry_run is None else bool(dry_run))
+        log.record(
+            "memory_dream",
+            outcome.status,
+            {
+                "absolutised": outcome.absolutised,
+                "consumed": outcome.consumed,
+                "dry_run": outcome.dry_run,
+                "merged": outcome.merged,
+            },
+        )
+        return _noted(outcome.reply)
+
     def validate_json(output: str, schema: dict[str, Any]) -> dict[str, Any]:
         with _record_raise(log, "validate_json"):
             error = schema_error(output, schema)
@@ -1215,13 +1304,89 @@ def build_server(memory: Memory, log: EventLog | None = None) -> Any:
             )
             return _noted(result.as_json())
 
+    def repo_map(
+        root: str,
+        focus: list[str] | None = None,
+        budget: int | None = None,
+    ) -> str:
+        """The ranked definition map on the MCP surface: `repomap` measures, this serves it.
+
+        THE THREE REFUSALS LIVE HERE AND NOT IN `repomap.py`, and that is deliberate.
+        `repo_map()` 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, the way `bantamkit_read`'s
+        `refused-offset` is, and the engine J45-9/J45-10 proved byte-identical is not
+        touched by this unit.
+
+        `focus` names the files the caller already has open; they are excluded from the
+        listing. A focus entry that is not a scanned source is IGNORED, not refused —
+        `repo_map` documents that, and refusing would make the tool useless the moment a
+        caller named a file the scanner has no dialect for.
+
+        THE LAST PARAGRAPH IS FIXED AND MANDATORY. Row 10's build gate was refuted by
+        measurement (0.114 % of real prompt tokens) and the feature ships on an explicit
+        ruling to build it anyway; a surface that let a caller believe the map is a saving
+        would be the one sentence this whole feature is not allowed to say.
+
+        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.
+        """
+        with _record_raise(log, "repo_map"):
+            names = [str(f) for f in (focus or [])]
+            wanted = repomap.DEFAULT_BUDGET if budget is None else int(budget)
+            base = Path(root)
+            if not root:
+                log.record("repo_map", "refused")
+                return _noted(
+                    tool_failed(
+                        "repo_map", "root must not be empty; name the directory to map"
+                    )
+                )
+            if wanted < 0:
+                log.record("repo_map", "refused")
+                return _noted(
+                    tool_failed("repo_map", f"budget must not be negative; got {wanted}")
+                )
+            # `Path.exists()` and `Path.is_dir()` both SWALLOW the not-here errno family
+            # (ENOENT, ENOTDIR, ELOOP, EBADF) and re-raise anything else, so a dangling
+            # symlink and `a-file.py/sub` are both "no such directory" while a permission
+            # failure flies to `_record_raise` rather than being dressed up as a missing
+            # tree. Node's `statSync` arm reproduces exactly that split; there is no
+            # `except OSError` here because `repomap.repo_map` raises none — its walk and
+            # its reads each already resolve a failure into a counted Omission.
+            if not base.exists():
+                log.record("repo_map", "refused")
+                return _noted(tool_failed("repo_map", f"no such directory: {root}"))
+            if not base.is_dir():
+                log.record("repo_map", "refused")
+                return _noted(
+                    tool_failed("repo_map", f"{root} is a file, not a directory to map")
+                )
+            result = repomap.repo_map(base, focus=names, budget=wanted)
+        log.record(
+            "repo_map",
+            "mapped",
+            {
+                "definitions": result.definitions,
+                "edges": result.edges,
+                "files_rendered": result.files_rendered,
+                "listing_bytes": result.listing_bytes,
+                "nodes": result.nodes,
+            },
+        )
+        return _noted(repo_map_reply(result))
+
     # The served surface, in one place, read out of the asset pack. Adding a tool here
     # without an asset raises AssetNotFound at startup — the manifest cannot drift behind
     # the server, because the server cannot start without it.
     #
     # `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. Registration order IS the served order
+    # after that, `skill_audit` after that, `memory_dream` after that and `repo_map`
+    # after that. Registration order IS the served order
     # (`test_tool_manifest.py::test_the_golden_records_the_order_the_wire_actually_
     # serves`), and appending is the only edit that leaves the others where every
     # existing declaration says they are.
@@ -1237,6 +1402,8 @@ def build_server(memory: Memory, log: EventLog | None = None) -> Any:
         _from_manifest(memory_compact, "memory_compact"),
         _from_manifest(bantamkit_read, "bantamkit_read"),
         _from_manifest(skill_audit, "skill_audit"),
+        _from_manifest(memory_dream, "memory_dream"),
+        _from_manifest(repo_map, "repo_map"),
     ]
 
     server = MCPServer(

{bantamkit-0.29.2 → bantamkit-0.30.0}/src/bantamkit/memory/__init__.py

@@ -1,4 +1,10 @@
-from bantamkit.memory.component import CompactOutcome, Memory, RecallOutcome, SaveOutcome
+from bantamkit.memory.component import (
+    CompactOutcome,
+    DreamOutcome,
+    Memory,
+    RecallOutcome,
+    SaveOutcome,
+)
 from bantamkit.memory.divergence import (
     BodyDiff,
     DivergenceReport,
@@ -10,6 +16,13 @@ from bantamkit.memory.divergence import (
     parse_fact,
     read_store,
 )
+from bantamkit.memory.dream import (
+    DreamMerge,
+    DreamResult,
+    SimilarPair,
+    Superseded,
+    dream,
+)
 from bantamkit.memory.layers import (
     MEMORY_DIR_ENV,
     StoreBinding,
@@ -18,6 +31,7 @@ from bantamkit.memory.layers import (
 )
 from bantamkit.memory.store import (
     DEFAULT_INDEX_BUDGET,
+    RECALL_MIN_SCORE_RATIO,
     ArchivedFact,
     CompactResult,
     Fact,

{bantamkit-0.29.2 → bantamkit-0.30.0}/src/bantamkit/memory/__main__.py

@@ -2,7 +2,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
+model decision" — 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). That position is only coherent if the operator can actually make the
 decision. Measured

{bantamkit-0.29.2 → bantamkit-0.30.0}/src/bantamkit/memory/component.py

@@ -10,6 +10,8 @@ from pathlib import Path
 from bantamkit.agent import Agent, ToolDef
 from bantamkit.assets import load_skill, load_tool
 from bantamkit.client import BantamError
+from bantamkit.memory.dream import SUPERSEDED_HEADING, DreamResult
+from bantamkit.memory.dream import dream as _dream
 from bantamkit.memory.layers import (
     MEMORY_DIR_ENV,
     PROJECT_STORE,
@@ -20,6 +22,7 @@ from bantamkit.memory.layers import (
 )
 from bantamkit.memory.store import (
     DEFAULT_INDEX_BUDGET,
+    RECALL_MIN_SCORE_RATIO,
     Fact,
     MemoryBudgetExceeded,
     MemoryStore,
@@ -114,6 +117,32 @@ class CompactOutcome:
     budget: int
 
 
+@dataclass(frozen=True)
+class DreamOutcome:
+    """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`, `.over_budget`,
+    `.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`.
+    """
+
+    reply: str
+    status: str
+    dry_run: bool
+    merged: int
+    consumed: int
+    absolutised: int
+    superseded: int
+    index_before: int
+    index_after: int
+    budget: int
+    result: DreamResult | None = None
+
+
 def _profile_store() -> Path:
     """The last layer `layered` appends, named once so other code can recognise it.
 
@@ -259,7 +288,12 @@ class Memory:
             )
         return SaveOutcome(reply=f"saved '{result.name}'", status="saved")
 
-    def recall(self, query: str, k: int | None = None) -> str:
+    def recall(
+        self,
+        query: str,
+        k: int | None = None,
+        min_ratio: float = RECALL_MIN_SCORE_RATIO,
+    ) -> str:
         """`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
@@ -273,9 +307,14 @@ class Memory:
         The floor is the operator's configured default, not a constant, so a consumer
         who really wants top-1 says so once at construction (`Memory(store, k=1)`).
         """
-        return self.recall_outcome(query, k).reply
+        return self.recall_outcome(query, k, min_ratio).reply
 
-    def recall_outcome(self, query: str, k: int | None = None) -> RecallOutcome:
+    def recall_outcome(
+        self,
+        query: str,
+        k: int | None = None,
+        min_ratio: float = RECALL_MIN_SCORE_RATIO,
+    ) -> RecallOutcome:
         """`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
@@ -291,6 +330,17 @@ class Memory:
         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 `_nothing_to_report` below and must not be undone here.
+
+        `min_ratio` (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 `except` below would otherwise file a caller's bad argument as
+        a corrupt grant.
         """
         budget = self.k if k is None else max(k, self.k)
         picked: list[tuple[str, Fact]] = []
@@ -303,7 +353,7 @@ class Memory:
                 break  # budget spent: later (read-only) layers are never even read
             reached += 1
             try:
-                facts = store.recall(query, budget, stamp=writable)
+                facts = store.recall(query, budget, stamp=writable, min_ratio=min_ratio)
             except (BantamError, OSError, UnicodeDecodeError):
                 if writable:
                     raise  # the project layer failing is a real error, as in v1
@@ -560,6 +610,158 @@ class Memory:
             budget=result.budget,
         )
 
+    def dream(self, dry_run: bool = True) -> str:
+        """Consolidate what the project and profile layers hold under the same name."""
+        return self.dream_outcome(dry_run).reply
+
+    def dream_outcome(self, dry_run: bool = True) -> DreamOutcome:
+        """`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.
+
+        `dry_run` 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.
+        """
+        profile = next((store for label, store, _ in self._layers if label == "profile"), None)
+        if profile is None:
+            return DreamOutcome(
+                reply=(
+                    "nothing to consolidate: no profile layer is bound, so the project "
+                    f"store {self.store.root} is the only layer there is."
+                ),
+                status="no-profile-layer",
+                dry_run=dry_run,
+                merged=0,
+                consumed=0,
+                absolutised=0,
+                superseded=0,
+                index_before=0,
+                index_after=0,
+                budget=self.store.index_budget,
+            )
+        result = _dream(self.store, profile, dry_run)
+        if result.over_budget:
+            status = "refused-budget"
+        elif not result.changes:
+            status = "nothing-to-consolidate"
+        elif result.applied:
+            status = "consolidated"
+        else:
+            status = "previewed"
+        return DreamOutcome(
+            reply=self._dream_reply(status, result),
+            status=status,
+            dry_run=result.dry_run,
+            merged=len(result.merged),
+            consumed=len(result.consumed),
+            absolutised=len(result.absolutised),
+            superseded=len(result.superseded),
+            index_before=result.index_before,
+            index_after=result.index_after,
+            budget=result.budget,
+            result=result,
+        )
+
+    @staticmethod
+    def _dream_reply(status: str, result: DreamResult) -> str:
+        """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.
+        """
+        lines: list[str] = []
+        if status == "nothing-to-consolidate":
+            lines.append(
+                f"nothing to consolidate: {result.project_root} and {result.profile_root} "
+                f"hold no fact under the same name, and no project fact carries a relative "
+                f"date this pass will resolve."
+            )
+        else:
+            identical = sum(1 for merge in result.merged if merge.kind == "identical")
+            diverged = len(result.merged) - identical
+            verb = {
+                "consolidated": "consolidated",
+                "previewed": "would consolidate",
+                "refused-budget": "would consolidate",
+            }[status]
+            lines.append(
+                f"{verb} {len(result.merged)} cross-layer name collision(s) — {identical} "
+                f"byte-identical, {diverged} diverged and unioned — and rewrote "
+                f"{len(result.rewritten)} project fact(s). The survivor stays in the "
+                f"project layer; the profile copy moves to {result.archive_dir} and is NOT "
+                f"deleted: restore it by name."
+            )
+        for merge in result.merged:
+            lines.append(
+                f"- {merge.name} ({merge.kind}, name+description similarity "
+                f"{merge.jaccard:.3f}) — body {merge.body_before} -> {merge.body_after} "
+                f"bytes, {merge.blocks_added} block(s) kept from the {merge.consumed_layer} "
+                f"copy, survivor in {merge.survivor_layer}"
+            )
+        for record in result.superseded:
+            lines.append(
+                f"- superseded '{record.subject}': the {record.lost_layer} copy "
+                f"({record.lost_date}) lost to the {record.kept_layer} copy "
+                f"({record.kept_date}); the older claim is kept verbatim under "
+                f"'{SUPERSEDED_HEADING}'"
+            )
+        for hit in result.absolutised:
+            lines.append(
+                f"- dated {hit.name} ({hit.layer}): '{hit.term}' -> {hit.resolved}, "
+                f"resolved against that fact's own mtime {hit.basis}, not today"
+            )
+        for hit in result.unresolved:
+            lines.append(
+                f"- left alone in {hit.name} ({hit.layer}): '{hit.term}' — no exact day "
+                f"follows from an mtime, so nothing was substituted"
+            )
+        for name, reason in result.refused:
+            lines.append(f"- refused {name}: {reason}")
+        for pair in result.similar_unmerged:
+            lines.append(
+                f"- similar but NOT merged: {pair.project_name} (project) and "
+                f"{pair.profile_name} (profile) score {pair.jaccard:.3f}; this pass merges "
+                f"on name equality only, so nothing was done about it"
+            )
+        lines.append(
+            f"project index {result.index_before} -> {result.index_after} bytes against a "
+            f"{result.budget}-byte budget; the profile index (derived, no file on disk) "
+            f"{result.profile_index_before} -> {result.profile_index_after}; fact bytes "
+            f"across both layers {result.fact_bytes_before} -> {result.fact_bytes_after}."
+        )
+        if status == "refused-budget":
+            lines.append(
+                f"NOTHING WAS WRITTEN: the merged index would be {result.index_after} bytes "
+                f"against a {result.budget}-byte budget. Call `memory_compact` to archive "
+                f"the stalest facts, then run this again."
+            )
+        elif result.dry_run:
+            lines.append(
+                "DRY RUN: nothing was written. Re-run with dry_run false to apply it."
+            )
+        lines.append(
+            "This is a correctness pass, not a token saving: the profile index is derived "
+            "at read time and is not loaded from a file, so consolidating it frees "
+            "approximately no prompt bytes. What it buys is one copy of a ruling instead "
+            "of two that can diverge."
+        )
+        return "\n".join(lines)
+
     # Back-compat aliases: the component's API predates the public names.
     _save = save
     _recall = recall