bantamkit-mcp 0.29.2 → 0.30.0

package/dist/memory/component.js

@@ -29,7 +29,8 @@ import { BantamError } from '../errors.js';
 import { pyStrip } from './factfile.js';
 import { countFacts, loadGrants, MEMORY_DIR_ENV, PROJECT_STORE, resolveProjectStore, } from './layers.js';
 import { pyHome, pyJoin, pyName, pyParent, pyResolve, PyOSError, PyUnicodeDecodeError } from './pyfs.js';
-import { DEFAULT_INDEX_BUDGET, MemoryBudgetExceeded, MemoryStore, MemoryValidationError, pyHashKey, pyText, } from './store.js';
+import { DEFAULT_INDEX_BUDGET, MemoryBudgetExceeded, MemoryStore, MemoryValidationError, pyHashKey, pyText, RECALL_MIN_SCORE_RATIO, } from './store.js';
+import { dream as runDream, formatFixed3, SUPERSEDED_HEADING } from './dream.js';
 /**
  * The model's spelling adapted to the store's contract: lowercase, `_`/space -> `-`.
  *
@@ -177,8 +178,8 @@ export 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, k = null) {
-        return this.recallOutcome(query, k).reply;
+    recall(query, k = null, minRatio = RECALL_MIN_SCORE_RATIO) {
+        return this.recallOutcome(query, k, minRatio).reply;
     }
     /**
      * `recall`, carrying the walk it performed as numbers rather than as prose.
@@ -196,8 +197,18 @@ export 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, k = null) {
+    recallOutcome(query, k = null, minRatio = RECALL_MIN_SCORE_RATIO) {
         const budget = k === null ? this.k : Math.max(k, this.k);
         const picked = [];
         const seen = new Set();
@@ -210,7 +221,7 @@ export class Memory {
             reached += 1;
             let facts;
             try {
-                facts = store.recall(query, budget, writable);
+                facts = store.recall(query, budget, writable, minRatio);
             }
             catch (e) {
                 if (!(e instanceof BantamError || e instanceof PyOSError || e instanceof PyUnicodeDecodeError)) {
@@ -312,6 +323,147 @@ export class Memory {
             budget: result.budget,
         };
     }
+    /** Consolidate what the project and profile layers hold under the same name. */
+    dream(dryRun = true) {
+        return this.dreamOutcome(dryRun).reply;
+    }
+    /**
+     * `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 = true) {
+        const profile = this.layers.find(([label]) => label === 'profile')?.[1] ?? null;
+        if (profile === null) {
+            return {
+                reply: 'nothing to consolidate: no profile layer is bound, so the project ' +
+                    `store ${this.store.root} is the only layer there is.`,
+                status: 'no-profile-layer',
+                dryRun,
+                merged: 0,
+                consumed: 0,
+                absolutised: 0,
+                superseded: 0,
+                indexBefore: 0,
+                indexAfter: 0,
+                budget: this.store.indexBudget,
+                result: null,
+            };
+        }
+        const result = runDream(this.store, profile, dryRun);
+        let status;
+        if (result.overBudget)
+            status = 'refused-budget';
+        else if (result.changes === 0)
+            status = 'nothing-to-consolidate';
+        else if (result.applied)
+            status = 'consolidated';
+        else
+            status = 'previewed';
+        return {
+            reply: Memory.dreamReply(status, result),
+            status,
+            dryRun: result.dryRun,
+            merged: result.merged.length,
+            consumed: result.consumed.length,
+            absolutised: result.absolutised.length,
+            superseded: result.superseded.length,
+            indexBefore: result.indexBefore,
+            indexAfter: result.indexAfter,
+            budget: result.budget,
+            result,
+        };
+    }
+    /**
+     * 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.
+     */
+    static dreamReply(status, result) {
+        const lines = [];
+        if (status === 'nothing-to-consolidate') {
+            lines.push(`nothing to consolidate: ${result.projectRoot} and ${result.profileRoot} ` +
+                'hold no fact under the same name, and no project fact carries a relative ' +
+                'date this pass will resolve.');
+        }
+        else {
+            const identical = result.merged.filter((merge) => merge.kind === 'identical').length;
+            const diverged = result.merged.length - identical;
+            const verb = status === 'consolidated' ? 'consolidated' : 'would consolidate';
+            lines.push(`${verb} ${result.merged.length} cross-layer name collision(s) — ${identical} ` +
+                `byte-identical, ${diverged} diverged and unioned — and rewrote ` +
+                `${result.rewritten.length} project fact(s). The survivor stays in the ` +
+                `project layer; the profile copy moves to ${result.archiveDir} and is NOT ` +
+                'deleted: restore it by name.');
+        }
+        for (const merge of result.merged) {
+            lines.push(`- ${pyText(merge.name)} (${merge.kind}, name+description similarity ` +
+                `${formatFixed3(merge.jaccard)}) — body ${merge.bodyBefore} -> ${merge.bodyAfter} ` +
+                `bytes, ${merge.blocksAdded} block(s) kept from the ${merge.consumedLayer} ` +
+                `copy, survivor in ${merge.survivorLayer}`);
+        }
+        for (const record of result.superseded) {
+            lines.push(`- superseded '${record.subject}': the ${record.lostLayer} copy ` +
+                `(${record.lostDate}) lost to the ${record.keptLayer} copy ` +
+                `(${record.keptDate}); the older claim is kept verbatim under ` +
+                `'${SUPERSEDED_HEADING}'`);
+        }
+        for (const hit of result.absolutised) {
+            lines.push(`- dated ${pyText(hit.name)} (${hit.layer}): '${hit.term}' -> ${hit.resolved}, ` +
+                `resolved against that fact's own mtime ${hit.basis}, not today`);
+        }
+        for (const hit of result.unresolved) {
+            lines.push(`- left alone in ${pyText(hit.name)} (${hit.layer}): '${hit.term}' — no exact day ` +
+                'follows from an mtime, so nothing was substituted');
+        }
+        for (const [name, reason] of result.refused) {
+            lines.push(`- refused ${pyText(name)}: ${reason}`);
+        }
+        for (const pair of result.similarUnmerged) {
+            lines.push(`- similar but NOT merged: ${pyText(pair.projectName)} (project) and ` +
+                `${pyText(pair.profileName)} (profile) score ${formatFixed3(pair.jaccard)}; this pass merges ` +
+                'on name equality only, so nothing was done about it');
+        }
+        lines.push(`project index ${result.indexBefore} -> ${result.indexAfter} bytes against a ` +
+            `${result.budget}-byte budget; the profile index (derived, no file on disk) ` +
+            `${result.profileIndexBefore} -> ${result.profileIndexAfter}; fact bytes ` +
+            `across both layers ${result.factBytesBefore} -> ${result.factBytesAfter}.`);
+        if (status === 'refused-budget') {
+            lines.push(`NOTHING WAS WRITTEN: the merged index would be ${result.indexAfter} bytes ` +
+                `against a ${result.budget}-byte budget. Call \`memory_compact\` to archive ` +
+                'the stalest facts, then run this again.');
+        }
+        else if (result.dryRun) {
+            lines.push('DRY RUN: nothing was written. Re-run with dry_run false to apply it.');
+        }
+        lines.push('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 lines.join('\n');
+    }
     /**
      * `(index bytes, budget)` for the writable project store; bytes may be `null`.
      *

package/dist/memory/dream.d.ts

@@ -0,0 +1,247 @@
+import type { FactValue } from './factfile.js';
+import { MemoryStore } from './store.js';
+/**
+ * The two layer names this pass knows. A read-only GRANT is deliberately not one of them: a
+ * grant is another operator's store, and consuming a fact out of it is not this person's to
+ * do. Grants are neither merged nor scanned.
+ */
+export declare const PROJECT_LAYER = "project";
+export declare const PROFILE_LAYER = "profile";
+/**
+ * The heading the union writes above claims a contradiction retired. Distinctive on
+ * purpose: a body that already contains an ordinary `## superseded` section must not be
+ * mistaken for one this pass wrote.
+ */
+export declare const SUPERSEDED_HEADING = "## superseded by a dream merge";
+/**
+ * One relative term found in a body, and what — if anything — it resolved to.
+ *
+ * `resolved` is `''` for a term in `UNRESOLVED`: the term was FOUND and REPORTED and the body
+ * was not touched. `basis` is always the ISO date the arithmetic ran against, which is the
+ * fact file's own mtime and never today's date — a fact written in August that says "today"
+ * means a day in August, and resolving it against the day the dream runs is how a
+ * consolidation pass invents history.
+ */
+export interface DateHit {
+    readonly name: FactValue;
+    readonly layer: string;
+    readonly term: string;
+    readonly resolved: string;
+    readonly basis: string;
+}
+/** A claim that lost a contradiction, kept verbatim so nothing is silently dropped. */
+export interface Superseded {
+    readonly subject: string;
+    readonly kept: string;
+    readonly keptLayer: string;
+    readonly keptDate: string;
+    readonly lost: string;
+    readonly lostLayer: string;
+    readonly lostDate: string;
+}
+/** One consolidated name: what it was, what it became, and where each half went. */
+export interface DreamMerge {
+    readonly name: FactValue;
+    readonly kind: 'identical' | 'diverged';
+    readonly jaccard: number;
+    readonly survivorLayer: string;
+    readonly consumedLayer: string;
+    readonly bodyBefore: number;
+    readonly bodyAfter: number;
+    readonly blocksAdded: number;
+    readonly superseded: readonly Superseded[];
+}
+/**
+ * A cross-layer pair similarity would have merged and NAME EQUALITY DID NOT FIND.
+ *
+ * Reported, never acted on. J45-1 measured this population at ZERO on the live stores. It is
+ * carried so a future store that grows a paraphrase is visible rather than silently
+ * unmerged, and so that "similarity contributes nothing today" is a number a reader can
+ * check instead of a sentence they have to trust.
+ */
+export interface SimilarPair {
+    readonly projectName: FactValue;
+    readonly profileName: FactValue;
+    readonly jaccard: number;
+}
+/**
+ * The diff. Everything a caller needs to see what a dream did, or would do.
+ *
+ * `applied` is FALSE for a dry run and for a plan refused by the budget, and it is the only
+ * field that says whether anything on disk moved. The byte fields are projections computed
+ * the same way in both modes, so a preview and the run it previews report the same
+ * arithmetic rather than two numbers a reader has to reconcile.
+ *
+ * `overBudget`, `changes` and `superseded` are `@property` on the reference and plain fields
+ * here — the values are the same and nothing mutates the result.
+ */
+export interface DreamResult {
+    readonly applied: boolean;
+    readonly dryRun: boolean;
+    readonly merged: readonly DreamMerge[];
+    readonly refused: readonly (readonly [FactValue, string])[];
+    readonly absolutised: readonly DateHit[];
+    readonly unresolved: readonly DateHit[];
+    readonly similarUnmerged: readonly SimilarPair[];
+    readonly consumed: readonly FactValue[];
+    readonly rewritten: readonly FactValue[];
+    readonly archiveDir: string;
+    readonly indexBefore: number;
+    readonly indexAfter: number;
+    readonly budget: number;
+    readonly profileIndexBefore: number;
+    readonly profileIndexAfter: number;
+    readonly factBytesBefore: number;
+    readonly factBytesAfter: number;
+    readonly projectRoot: string;
+    readonly profileRoot: string;
+    /** Would the project index not fit after this merge? Then nothing is written. */
+    readonly overBudget: boolean;
+    /** Merges plus rewritten facts — the count that decides `nothing-to-consolidate`. */
+    readonly changes: number;
+    readonly superseded: readonly Superseded[];
+}
+/**
+ * `int(text)` for a run of `\p{Nd}` digits, which is what CPython's `int()` accepts.
+ *
+ * A decimal-digit block is exactly ten consecutive codepoints, so the value of a digit is
+ * its distance from the block's zero and the block's zero is found by walking back while the
+ * previous codepoint is still `Nd` — no table, and correct for every script including the
+ * ones assigned after this file was written.
+ */
+export declare function pyIntDigits(text: string): number;
+/**
+ * `f"{value:.3f}"` — round HALF TO EVEN on the exact binary value of the double.
+ *
+ * NOT `toFixed(3)`, which rounds ties AWAY from zero. The reachable ties are exactly the
+ * odd sixteenths (a tie at three places needs the exact value to be `k/10000` with `k`
+ * ending in 5, and only `j/16` is both that and a double), and four of the eight disagree:
+ * CPython prints `0.062`, `0.312`, `0.562`, `0.812` where `toFixed` prints `0.063`, `0.313`,
+ * `0.563`, `0.813`. A Jaccard of `1/16` is one shared token in a sixteen-token union, which
+ * is an ordinary pair and not a contrived one.
+ *
+ * The arithmetic is exact: the double is decomposed to `mantissa * 2**exponent` over
+ * `BigInt`, so nothing here rounds twice.
+ */
+export declare function formatFixed3(value: number): string;
+/**
+ * `sorted(values)` over what a `Fact.name` can hold — CPython's `listsort` for a single run.
+ *
+ * Every name a `str` is the total order `cmpCodepoint` gives. Anything else can RAISE, and
+ * then WHICH pair CPython happened to probe decides the sentence, so the slow path is
+ * `count_run` + `binarysort` exactly as `sortScored` spells it: pivot on the LEFT of every
+ * probe, midpoint `l + ((r - l) >> 1)`, `==` short-circuiting `<` so two facts both named
+ * `None` order rather than raise.
+ *
+ * THE EDGE, STATED: the reference sorts a `set`, whose iteration order is hash-derived, so
+ * for a list that RAISES the two runtimes can name a different pair of types. Where the
+ * order exists — every name a `str`, which is every store `save` has ever written — the
+ * answer is identical.
+ */
+export declare function sortedNames(values: readonly FactValue[]): FactValue[];
+/** One line, single-spaced. The basis of every comparison key in this module. */
+export declare function collapse(text: string): string;
+/**
+ * The identity of a block for set-union purposes: collapsed whitespace, lowercased.
+ *
+ * Punctuation is deliberately NOT stripped. A rule that ignored it would call two sentences
+ * the same because one ends in a question mark, and this pass is allowed to repeat a claim
+ * but never to drop one.
+ */
+export declare function blockKey(text: string): string;
+/**
+ * Paragraphs: non-empty runs separated by a blank line, each stripped.
+ *
+ * Line endings are normalised first, so the same body blocks identically whether it was
+ * written on Windows or on POSIX — the two runtimes must agree on the block list before they
+ * can agree on the union of two of them.
+ */
+export declare function splitBlocks(text: string): string[];
+/**
+ * `[subject key, value key]` when a block is a single-line `Subject: value`, else `null`.
+ *
+ * See `SLOT` for why this is narrow. It exists only so that a genuine CONTRADICTION — the
+ * same slot given two different values — can be told apart from two claims that are merely
+ * different, which is the whole of what union already handles.
+ */
+export declare function claimSlot(block: string): [string, string] | null;
+/**
+ * `[body, resolved hits, unresolved hits]` — a relative date annotated with its day.
+ *
+ * THE TERM IS KEPT AND THE DATE IS ADDED: `today` becomes `today (2026-08-27)`. Deleting the
+ * word would rewrite the sentence a person wrote; appending the day says which date was
+ * substituted and leaves the reader able to disagree with it. A term already carrying a
+ * stamp is skipped, which is what makes a second dream over the same body a no-op.
+ *
+ * A term whose arithmetic leaves the calendar (see `addDays`) is REPORTED as unresolved and
+ * the body is left alone — the same treatment `recently` and `last month` get, for the same
+ * reason: this pass may say which day it substituted, or say it could not, and never invent
+ * one. Those hits come FIRST in the unresolved list, in the order the relative scan met
+ * them, followed by the `UNRESOLVED` matches in the order the second scan met them, which
+ * is the order `dream.py` builds the same list in.
+ */
+export declare function absolutise(body: string, basis: string, name: FactValue, layer: string): [string, DateHit[], DateHit[]];
+/**
+ * Both descriptions, `; `-joined, unless they are the same line of text.
+ *
+ * The description is what `recall` SCORES against, so dropping one side's would cost the
+ * survivor the query vocabulary that half of the pair used to answer. Equality is on the
+ * collapsed, lowercased key — the same key every other comparison here uses — and nothing
+ * cleverer: a containment or similarity rule would be a second thing to reproduce byte for
+ * byte, and the index budget already bounds the cost of being literal.
+ */
+export declare function mergeDescriptions(base: FactValue, other: FactValue): string;
+/** Ordered set union, base first, exact string identity. Order is the port's contract. */
+export declare function mergeLinks(base: readonly FactValue[], other: readonly FactValue[]): FactValue[];
+/**
+ * UNION, never a winner. `[body, blocks taken from other, superseded records]`.
+ *
+ * THE ALGORITHM, stated as the contract both runtimes reproduce exactly:
+ *
+ * 1. Split both bodies into blocks (`splitBlocks`).
+ * 2. Find CONTRADICTIONS: a `claimSlot` subject present on both sides with two different
+ *    value keys. The side whose FACT FILE has the later mtime wins; a tie goes to `base`,
+ *    which is the writable project layer. The loser is removed from the body sequence and
+ *    recorded in a `Superseded` entry — never dropped.
+ * 3. Emit every surviving BASE block in source order, skipping any whose `blockKey` has
+ *    already been emitted.
+ * 4. Emit every surviving OTHER block in source order, same skip. Count these.
+ * 5. If anything was superseded, append one block: `SUPERSEDED_HEADING`, a blank line, and
+ *    one `- from <layer> (<date>): <collapsed text>` line per record, sorted by subject.
+ * 6. Join with a blank line.
+ *
+ * WHY MTIME AND NOT `created` DECIDES A CONTRADICTION. J45-1 measured all three obvious
+ * clocks on the real diverged pair and every one picks wrong: newest `created` and longest
+ * body each pick the profile copy and lose the project copy's amended paragraph,
+ * project-layer-wins drops ~1.7 kB of the profile copy, and `last_recalled` is the same date
+ * on both. `created` is FIRST-LANDING and the older-created fact there holds the NEWER
+ * content, so it is actively backwards. The file's mtime is the only clock on disk that
+ * records when the text was last written, and it is the same clock `absolutise` uses.
+ *
+ * WHY UNION MAY REPEAT A CLAIM. Two paragraphs that say the same thing in different words
+ * have different `blockKey`s and both survive. That is the deliberate direction of the
+ * error: a repeated claim is something the user can delete in one edit, and a dropped ruling
+ * is not recoverable from the merged fact at all.
+ */
+export declare function mergeBodies(baseBody: string, otherBody: string, baseLayer: string, otherLayer: string, baseDate: string, otherDate: string): [string, number, Superseded[]];
+/**
+ * Consolidate the facts the two layers hold under the same NAME. Reversible, bounded.
+ *
+ * `dryRun` defaults to TRUE because this pass writes into the user's home directory and a
+ * destructive consolidation nobody can preview is not shippable. A dry run performs every
+ * read, every merge and every projection and writes nothing.
+ *
+ * THE BUDGET IS `compact()`'s BUDGET AND NOT A SECOND CAP. The only index this pass can grow
+ * is the project one, and it can grow it only by the bytes a unioned DESCRIPTION adds —
+ * every merged name is already a line in that index, so no line is ever added. The projected
+ * index is measured exactly the way `checkIndexBudget` measures it, and a plan that would
+ * not fit is returned unapplied with `overBudget` set, for the caller to report. It is not
+ * raised: a preview whose answer is an exception has told the operator nothing about the
+ * plan they asked to see.
+ *
+ * WRITE ORDER IS SURVIVORS FIRST, CONSUMPTION SECOND, and it is chosen for the direction of
+ * its failure. If the process dies between the two, the survivor holds everything and the
+ * profile copy is still live — a duplicate that the next dream consolidates. The other order
+ * would leave a window in which the profile copy is archived and the union has not landed.
+ */
+export declare function dream(project: MemoryStore, profile: MemoryStore, dryRun?: boolean): DreamResult;