bantamkit-mcp 0.29.2 → 0.30.0

package/dist/memory/store.d.ts

@@ -15,6 +15,7 @@ export declare const VALID_TYPES: readonly ["feedback", "project", "reference",
  */
 export declare const DURABLE_TYPES: readonly ["feedback", "user"];
 export declare const DUPLICATE_JACCARD = 0.5;
+export declare const RECALL_MIN_SCORE_RATIO = 0;
 /** See the reference's comment: measured against a real store, not chosen. */
 export declare const DEFAULT_INDEX_BUDGET = 24000;
 export declare class MemoryValidationError extends BantamError {
@@ -55,6 +56,17 @@ export interface CompactResult {
     headroom: number;
     archiveDir: string;
 }
+/**
+ * The store members `dream.ts` needs and no caller outside it should have. See
+ * `MemoryStore.internals`.
+ */
+export interface StoreInternals {
+    facts(): Fact[];
+    factPath(name: FactValue): string;
+    indexLine(fact: Fact): string;
+    writeFact(fact: Fact): void;
+    rebuildIndex(): void;
+}
 export interface MemoryStoreOptions {
     indexBudget?: number;
     k?: number;
@@ -186,8 +198,25 @@ export declare class MemoryStore {
      * `[]` — the same answer as a real miss, which `component.Memory` used to turn into "no
      * memories matched. Try different words", telling a person to rephrase a question at a
      * filing cabinet nobody could open.
+     *
+     * `minRatio` is roadmap #6's precision gate: keep a fact only if its score is at least
+     * that fraction of the BEST score in this same recall. The default is
+     * `RECALL_MIN_SCORE_RATIO`, which is 0.0 and gates nothing — see the paragraph at that
+     * constant for why the number is a no-op today and what has to be measured before it
+     * stops being one. The comparison is relative to this store's own best because that is
+     * the only quantity in reach here that cancels query length; a layered `Memory` therefore
+     * applies the gate once per layer, against each layer's own top hit, and never across
+     * layers.
+     *
+     * THE RANGE CHECK RUNS BEFORE ANY FILE IS READ. A ratio outside `[0.0, 1.0]` is a
+     * caller's bug, and reporting it as "your store has no matches" would send someone to
+     * look at their memories for a defect that is in the argument. It is spelled
+     * `!(minRatio >= 0 && minRatio <= 1)` and NOT `(minRatio < 0 || minRatio > 1)`: every
+     * comparison against `NaN` is false, so the second spelling ADMITS `NaN` where the
+     * reference's `not 0.0 <= min_ratio <= 1.0` refuses it. That is a real mutant (M7b) and
+     * it is killed on both sides.
      */
-    recall(query: string, k?: number | null, stamp?: boolean): Fact[];
+    recall(query: string, k?: number | null, stamp?: boolean, minRatio?: number): Fact[];
     /**
      * `len(store._facts())` at the operator CLI, which is the only caller.
      *
@@ -388,6 +417,21 @@ export declare class MemoryStore {
      * Registered as a runtime-py defect, not fixed here (invariant 8).
      */
     indexText(): string;
+    /**
+     * The `_`-prefixed members `dream.ts` reaches for, handed out as ONE named seam.
+     *
+     * The reference's `dream.py` calls `store._facts()`, `_fact_path`, `_index_line`,
+     * `_write_fact` and `_rebuild_index` directly — Python's underscore is a convention and
+     * costs nothing to cross. TypeScript's `private` is enforced, so the port needs a door,
+     * and this is deliberately one door rather than five relaxed modifiers: it is greppable,
+     * it names its one caller, and a sixth internal does not become reachable by accident.
+     *
+     * `_fact_text` has no member here because it never needed splitting out on this side —
+     * `formatFact` in `factfile.ts` has always been the serialiser `writeFact` calls, so the
+     * bytes `dream` MEASURES and the bytes the store WRITES are already one function. That is
+     * the code-shape difference the Python half had to manufacture, not a behaviour one.
+     */
+    internals(): StoreInternals;
     private factPath;
     private indexLine;
     /**

package/dist/memory/store.js

@@ -68,6 +68,55 @@ export const DURABLE_TYPES = ['feedback', 'user'];
 const NAME_RE = /^[a-z0-9][a-z0-9-]*\n?$/;
 const NAME_PATTERN = '^[a-z0-9][a-z0-9-]*$';
 export const DUPLICATE_JACCARD = 0.5;
+// ---- the precision gate (roadmap #6) ---------------------------------------------
+//
+// `recall` keeps a fact whose score is at least `minRatio` of the BEST score in the same
+// recall. WHY THIS NUMBER IS 0.0, and what will replace it:
+//
+// 0.0 IS A DELIBERATE NO-OP, not a tuned value. `score >= 0.0 * best` is true for every
+// fact `recall` was ever going to return — the scoring loop keeps only `score > 0` — so
+// shipping this gate at its default changes not one recall, not one injected header, and
+// not one byte of any reply. That is the whole point. The threshold that would actually
+// cut something has to come from `tools/ledger/injection-precision.mjs`, and on the day
+// that tool shipped (2026-09-06) it REFUSED to report a rate: 491 injection records, 3 of
+// them carrying names+scores+session, 2 distinct sessions, and no control arm, against a
+// floor of 100 joinable injections across 5 sessions. There is no retroactive baseline —
+// the 488 older records carry `hits` and `bytes` and nothing joinable — so a number chosen
+// today would be a number chosen off three rows, shipped as a silent suppressor of memory
+// injection. The mechanism lands now; the number lands when that tool answers instead of
+// refusing.
+//
+// WHY A RATIO AND NOT A COUNT. `score` is an unnormalised intersection size,
+// `len(tokens(name + " " + description) & tokens(query))`, so it scales with how long the
+// QUERY is. Measured on the three instrumented records: the same two-fact shape scored 2
+// and 2 on a 452-character prompt, 4 and 4 on a 453-character prompt, and 22 and 21 on a
+// 7855-character one. An absolute cut of, say, 5 would gate out both short prompts
+// entirely and admit everything on the long one, which is a rule about prompt length
+// wearing a relevance costume. Within ONE recall the query is fixed, so dividing by the
+// best score in that same recall cancels the length term exactly. Jaccard was the other
+// candidate and was rejected for the mirror-image bias: `|a & b| / |a | b|` puts the
+// query's own token count in the denominator, so it would gate out LONG prompts instead.
+//
+// THE GATE IS RELATIVE, SO IT CAN NEVER EMPTY A RECALL. The top hit IS the max, so
+// `best >= minRatio * best` holds for every ratio in range, 1.0 included. It narrows an
+// injection; it never suppresses one, and the COUNT of prompts that get an injection is
+// invariant at every setting.
+//
+// WHAT THE RATIO DOES NOT FIX: `tokens` is `re.findall(r"[a-z0-9]+", text.lower())`,
+// ASCII-only. A wholly non-Latin prompt tokenises to the empty set and scores 0 against
+// every fact, so it never reaches this gate at all — it is already an empty recall. This
+// store's operator writes Thai; a threshold tuned on English prompts would be tuned on a
+// population that structurally excludes theirs.
+//
+// The number lives in TWO places, one per runtime, and they must hold the SAME float:
+// `runtime-py/src/bantamkit/memory/store.py`'s `RECALL_MIN_SCORE_RATIO` is the reference.
+// `Memory.recallOutcome` and the `UserPromptSubmit` hook that calls it inherit it rather
+// than restating it.
+export const RECALL_MIN_SCORE_RATIO = 0.0;
+// Spelled once because both runtimes raise it verbatim. The offending value is NOT
+// interpolated: Python renders `2.0` as `2.0` and JavaScript renders it as `2`, so a
+// sentence carrying the number would be a divergence manufactured by float formatting.
+const MIN_RATIO_RANGE = 'recall min-score ratio must be between 0.0 and 1.0';
 /** See the reference's comment: measured against a real store, not chosen. */
 export const DEFAULT_INDEX_BUDGET = 24_000;
 // The second half of the "unreadable" sentence, one per directory this store lists — and
@@ -494,11 +543,30 @@ export class MemoryStore {
      * `[]` — the same answer as a real miss, which `component.Memory` used to turn into "no
      * memories matched. Try different words", telling a person to rephrase a question at a
      * filing cabinet nobody could open.
+     *
+     * `minRatio` is roadmap #6's precision gate: keep a fact only if its score is at least
+     * that fraction of the BEST score in this same recall. The default is
+     * `RECALL_MIN_SCORE_RATIO`, which is 0.0 and gates nothing — see the paragraph at that
+     * constant for why the number is a no-op today and what has to be measured before it
+     * stops being one. The comparison is relative to this store's own best because that is
+     * the only quantity in reach here that cancels query length; a layered `Memory` therefore
+     * applies the gate once per layer, against each layer's own top hit, and never across
+     * layers.
+     *
+     * THE RANGE CHECK RUNS BEFORE ANY FILE IS READ. A ratio outside `[0.0, 1.0]` is a
+     * caller's bug, and reporting it as "your store has no matches" would send someone to
+     * look at their memories for a defect that is in the argument. It is spelled
+     * `!(minRatio >= 0 && minRatio <= 1)` and NOT `(minRatio < 0 || minRatio > 1)`: every
+     * comparison against `NaN` is false, so the second spelling ADMITS `NaN` where the
+     * reference's `not 0.0 <= min_ratio <= 1.0` refuses it. That is a real mutant (M7b) and
+     * it is killed on both sides.
      */
-    recall(query, k = null, stamp = true) {
+    recall(query, k = null, stamp = true, minRatio = RECALL_MIN_SCORE_RATIO) {
+        if (!(minRatio >= 0 && minRatio <= 1))
+            throw new MemoryValidationError(MIN_RATIO_RANGE);
         const limit = k ?? this.k;
         const q = tokens(query);
-        const scored = [];
+        let scored = [];
         for (const fact of this.facts()) {
             let score = 0;
             for (const t of tokens(`${pyText(fact.name)} ${pyText(fact.description)}`))
@@ -507,6 +575,20 @@ export class MemoryStore {
             if (score > 0)
                 scored.push({ score, name: fact.name, fact });
         }
+        if (scored.length > 0) {
+            // No `if (minRatio > 0)` shortcut on purpose: at 0.0 this line still runs and still
+            // keeps everything, so "the default gates nothing" is a fact about the arithmetic
+            // rather than about a branch that could be edited away. `Math.max(...scored)` is NOT
+            // used: a spread is one argument per fact and a large store would overflow the
+            // argument limit, which is a crash the reference's `max(...)` over a generator does
+            // not have.
+            let best = scored[0].score;
+            for (const s of scored)
+                if (s.score > best)
+                    best = s.score;
+            const floor = minRatio * best;
+            scored = scored.filter((s) => s.score >= floor);
+        }
         // `key=lambda pair: (-pair[0], pair[1].name)`. The name comparison is CODEPOINT order
         // for two strings — which is not what `Array.prototype.sort` does — and Python's `<`
         // for everything else, refusals included. See `sortScored`.
@@ -839,6 +921,29 @@ export class MemoryStore {
     indexText() {
         return this.facts().map((fact) => this.indexLine(fact)).join('');
     }
+    /**
+     * The `_`-prefixed members `dream.ts` reaches for, handed out as ONE named seam.
+     *
+     * The reference's `dream.py` calls `store._facts()`, `_fact_path`, `_index_line`,
+     * `_write_fact` and `_rebuild_index` directly — Python's underscore is a convention and
+     * costs nothing to cross. TypeScript's `private` is enforced, so the port needs a door,
+     * and this is deliberately one door rather than five relaxed modifiers: it is greppable,
+     * it names its one caller, and a sixth internal does not become reachable by accident.
+     *
+     * `_fact_text` has no member here because it never needed splitting out on this side —
+     * `formatFact` in `factfile.ts` has always been the serialiser `writeFact` calls, so the
+     * bytes `dream` MEASURES and the bytes the store WRITES are already one function. That is
+     * the code-shape difference the Python half had to manufacture, not a behaviour one.
+     */
+    internals() {
+        return {
+            facts: () => this.facts(),
+            factPath: (name) => this.factPath(name),
+            indexLine: (fact) => this.indexLine(fact),
+            writeFact: (fact) => this.writeFact(fact),
+            rebuildIndex: () => this.rebuildIndex(),
+        };
+    }
     // ---- internals ----
     factPath(name) {
         return pyJoin(this.root, 'facts', `${pyText(name)}.md`);

package/dist/repomap.d.ts

@@ -0,0 +1,247 @@
+export declare const DAMPING = 0.2;
+export declare const ITERATIONS = 30;
+export declare const MIN_REFERENCE_LENGTH = 3;
+export declare const REFERENCE_DF_MAX_NUM = 1;
+export declare const REFERENCE_DF_MAX_DEN = 8;
+export declare const MAX_DEFINITIONS_PER_FILE = 4;
+export declare const DEFAULT_BUDGET = 4000;
+export declare const SCORE_SCALE = 1000000000;
+export declare const MAX_FILE_BYTES = 1048576;
+export declare const SKIP_DIRS: readonly string[];
+/**
+ * Suffix -> dialect. Two dialects only: `python` and `ecma`. TypeScript and JavaScript
+ * share a scanner because their DECLARATION forms are the same set; the extra TypeScript
+ * keywords (`interface`, `type`, `enum`) are simply absent from a `.js` file.
+ */
+export declare const LANGUAGES: Readonly<Record<string, string>>;
+export declare const OMIT_UNKNOWN_LANGUAGE = "unknown-language";
+export declare const OMIT_UNREADABLE = "unreadable-bytes";
+export declare const OMIT_SIZE_CAP = "size-cap";
+export declare const OMIT_NO_DEFINITIONS = "no-definitions";
+export declare const OMIT_UNREACHABLE = "unreachable";
+export declare const OMIT_PER_FILE_CAP = "per-file-cap";
+export declare const OMIT_BUDGET = "budget";
+/**
+ * Fixed render order for the footer, so two runs of the same map cannot disagree about the
+ * order of their disclosures.
+ */
+export declare const OMISSION_ORDER: readonly string[];
+/**
+ * One definition, at the line it was declared on. `line` is 1-based and counts lines of the
+ * ORIGINAL file, not of the comment-stripped view: a caller that jumps to it must land
+ * where the reader would.
+ */
+export interface Definition {
+    readonly path: string;
+    readonly line: number;
+    readonly kind: string;
+    readonly name: string;
+}
+/**
+ * Something the tree holds that the map does not carry, as a COUNT and the fact behind it —
+ * `docread`'s `Omission` discipline, deliberately re-stated here rather than imported,
+ * because these subjects are this module's and a shared vocabulary would make a change to
+ * one reader a change to the other.
+ *
+ * Never an adjective. `subject` is one of the `OMIT_*` tokens; a renderer that meets a token
+ * it does not know must still print the count. A silent skip is how a reader lies about its
+ * coverage.
+ */
+export interface Omission {
+    readonly subject: string;
+    readonly count: number;
+    readonly size: number;
+    readonly facts: readonly (readonly [string, number])[];
+}
+export interface RankedFile {
+    readonly path: string;
+    readonly rankUnits: number;
+    readonly definitions: readonly Definition[];
+    /**
+     * The raw double. Reported for a caller that wants it; NEVER rendered, and never the sort
+     * key — see trap (8).
+     */
+    readonly score: number;
+}
+export interface RepoMap {
+    readonly text: string;
+    readonly ranked: readonly RankedFile[];
+    readonly omissions: readonly Omission[];
+    readonly focus: readonly string[];
+    readonly nodes: number;
+    readonly edges: number;
+    readonly definitions: number;
+    readonly damping: number;
+    readonly iterations: number;
+    readonly budget: number;
+    readonly perFile: number;
+    readonly listingBytes: number;
+    readonly filesRendered: number;
+    readonly definitionsRendered: number;
+}
+export interface RepoMapOptions {
+    readonly focus?: readonly string[];
+    readonly budget?: number;
+    readonly files?: readonly string[] | null;
+    readonly damping?: number;
+    readonly iterations?: number;
+    readonly perFile?: number;
+}
+/**
+ * The dialect for a path, or `null` when this scanner has no reader for it.
+ *
+ * Dispatch is on SUFFIX, and that is a deliberate departure from `docread`, which sniffs
+ * because a suffix is measurably a lie about a document's container. A source file is
+ * different: `.py` and `.ts` name a GRAMMAR, and there is no magic number for a grammar. A
+ * file whose suffix is unknown is reported, never guessed at.
+ */
+export declare function languageOf(path: string): string | null;
+/**
+ * The file's lines with comments and docstrings blanked, one output line per input line so
+ * line numbers survive.
+ *
+ * Line-oriented and stateful across lines, because both traps that matter span lines: a
+ * Python triple-quoted docstring and an ECMAScript block comment. What is removed:
+ *
+ * - `python` — `'''`/`"""` blocks (the delimiter that opens is the only one that can close),
+ *   and everything from an unquoted `#` to end of line.
+ * - `ecma` — block comments, and everything from `//` to end of line.
+ *
+ * What is NOT removed, and is declared rather than hidden: the contents of a SINGLE-line
+ * string literal. Stripping those would lose the real references inside an f-string, and
+ * keeping them costs a definition-shaped line inside a one-line string being read as a
+ * definition. Backslash escapes are NOT honoured: a `"""` inside a string toggles the state
+ * machine. Both runtimes get that wrong identically, which is the requirement.
+ */
+export declare function stripNoncode(text: string, language: string): string[];
+/**
+ * Every definition in `text`, in source order.
+ *
+ * `python` — `def` and `class` at ANY indentation, so a method counts. Methods are the
+ * signal that made the difference in measurement: a focus on `memory/dream.py` reaches
+ * `memory/store.py` through `_write_fact`, `_fact_path` and `_check_index_budget`, none of
+ * which is top-level. Plus a bare `NAME =` or `NAME: T =` at column 0, which is how this
+ * repository declares its constants.
+ *
+ * `ecma` — `function class interface type const let var enum` at COLUMN 0 only, optionally
+ * behind `export` and `default` and `async`. Restricting to column 0 was the second-largest
+ * measured improvement in this module (recall@10 0.361 -> 0.410 on its own): an indented
+ * `const` is a local, and `runtime-ts/src/docread.ts` was contributing 452 of them.
+ *
+ * The asymmetry is real and is not an oversight: an ECMAScript class member cannot be told
+ * from a call at the same indentation without tracking braces, and a scanner that guessed
+ * would invent definitions. Python's `def` keyword makes the same question free.
+ */
+export declare function scanDefinitions(text: string, language: string, path?: string): Definition[];
+/**
+ * Every identifier of at least `MIN_REFERENCE_LENGTH` characters outside a comment.
+ *
+ * A SET, not a count. The edge weight below is "how many DISTINCT names of B does A
+ * mention", so a file that repeats one name a hundred times does not out-weigh a file that
+ * mentions ten. That is the choice the ambiguity filter and `MIN_REFERENCE_LENGTH` were
+ * tuned against and it keeps every weight an exact integer.
+ */
+export declare function referenceNames(text: string, language: string): Set<string>;
+/**
+ * Every path under `root`, relative, POSIX, code-point sorted.
+ *
+ * DIRECTORY SYMLINKS ARE NOT FOLLOWED, AND ON THIS SIDE THAT IS REAL LOGIC RATHER THAN A
+ * FLAG. `os.walk(followlinks=False)` gives CPython the whole rule for free, and J45-9's
+ * mutation 24 — delete the explicit `islink` filter — SURVIVED there for exactly that
+ * reason. Node has no equivalent, and the Dirent that looks like the answer is the wrong
+ * one: `readdirSync(..., {withFileTypes: true})` reports from **lstat**, so a symlink to a
+ * directory answers `isDirectory() === false` and a naive port hands it to the scanner as a
+ * source FILE. CPython does the opposite — `os.scandir`'s `entry.is_dir()` FOLLOWS, so the
+ * link lands in `dirs`, and `followlinks=False` then declines to descend, so it appears in
+ * the output neither as a file nor as a directory.
+ *
+ * Measured on node v25.2.1 and CPython 3.12.13 over one tree holding `real/`,
+ * `linkdir -> real`, `linkfile.py -> plain.py` and a dangling `dangling.py`: CPython's walk
+ * yields `dirs=['linkdir', 'real'] files=['dangling.py', 'linkfile.py', 'plain.py']` and
+ * `walk_sources` returns `['dangling.py', 'linkfile.py', 'plain.py', 'real/a.py']`. So the
+ * three cases are separated by a FOLLOW-`stat`, not by the Dirent:
+ *
+ * - symlink whose target is a directory  -> a directory, and not descended into: gone.
+ * - symlink whose target is a file       -> a file: kept.
+ * - dangling symlink                     -> `stat` throws, CPython's `is_dir()` raises and
+ *                                           is caught as False: a file, kept, and it will
+ *                                           be counted as `unreadable-bytes` downstream.
+ *
+ * Two reasons the rule exists and both are measured elsewhere in this repository: a symlink
+ * cycle makes the walk non-terminating, and a dangling directory symlink is one error shape
+ * on POSIX and two on Windows (`reference-windows-dangling-symlink-two-shapes`).
+ *
+ * A directory whose listing throws is skipped whole, silently, because that is what
+ * `os.walk`'s default `onerror=None` does.
+ */
+export declare function walkSources(root: string): string[];
+/**
+ * `source -> {target: weight}`, weight being the number of surviving names the source
+ * mentions that ONLY the target defines.
+ *
+ * Weights are exact integers, so `out[i]` in `pagerank` is an exact integer too and the only
+ * inexact step in the whole pass is the one division.
+ */
+export declare function buildGraph(definitions: Map<string, readonly Definition[]>, references: Map<string, ReadonlySet<string>>): Map<string, Map<string, number>>;
+/**
+ * At most `limit` of a file's definitions, chosen by kind then reach, returned in SOURCE
+ * order.
+ *
+ * The key is `(kind rank, -reference count, line, name)`, and every part of it is an integer
+ * or a code-point comparison, so the choice is TOTAL — which is why this port does not lean
+ * on `Array.prototype.sort` being stable. `references` is the RAW count from `nameIndex`;
+ * see there for why it is not the filtered one.
+ *
+ * **This ordering is argued, not measured, and the difference matters.** Every other
+ * constant in this module beat a named alternative on a yardstick. This one cannot: the
+ * yardstick is "does the focus file's own import appear in the rendered map", which is a
+ * question about which FILES are listed, and selection only decides which lines appear UNDER
+ * a file already listed. Measured, it moves that number by zero. So it rests on a stated
+ * principle instead — name the file's subject before its details — and a later unit with a
+ * definition-level yardstick is entitled to overturn it. What it is NOT is source order,
+ * which put `VALID_TYPES`, `DURABLE_TYPES`, `NAME_RE` and `DUPLICATE_JACCARD` at the head of
+ * `memory/store.py`'s block.
+ *
+ * The selected definitions are re-sorted into SOURCE order for rendering: a block whose line
+ * numbers ran backwards would be harder to read for no gain, and the order a block is chosen
+ * in is not the order it is read in.
+ */
+export declare function selectDefinitions(definitions: readonly Definition[], references: Map<string, number>, limit: number): readonly Definition[];
+/**
+ * Personalised PageRank, bit-identical to `repomap.py` by construction.
+ *
+ * The port contract, in the order the loop performs it:
+ *
+ * 1. `nodes` is already sorted; index by position in it.
+ * 2. `out[i]` is the exact integer sum of node i's out-weights.
+ * 3. Each node's out-edges are visited in sorted TARGET order.
+ * 4. The personalisation vector is `1/len(personal)` on each focus node and 0 elsewhere;
+ *    with no focus it is `1/n` on every node. The INITIAL vector is that same vector.
+ * 5. Per round: zero `next`; walk sources in node order; a node with no out-edges adds its
+ *    whole score to `dangling`; otherwise each out-edge adds `score[i] * weight / out[i]`,
+ *    evaluated strictly left to right.
+ * 6. `tele = damping * dangling + (1.0 - damping)`, then
+ *    `next[i] = next[i] * damping + tele * personal[i]`.
+ * 7. Exactly `iterations` rounds. No early stop, no convergence test — a branch on a float
+ *    is one more thing for a port to get wrong, and the contraction bound (the linear part
+ *    is `damping * column-stochastic`, so the residual after 30 rounds is under
+ *    `2 * 0.2 ** 30` = 2.1e-21) makes the test unnecessary.
+ *
+ * THERE IS NO `reduce` HERE AND THERE MUST NOT BE ONE: every accumulation is a written-out
+ * loop in the same order as CPython's, because CPython's `sum()` is Neumaier-compensated and
+ * nothing in JavaScript is (trap 7). The Python side is held to the same rule by
+ * `test_no_float_summation_or_rounding_in_the_source`, which reads that function's body.
+ */
+export declare function pagerank(nodes: readonly string[], edges: Map<string, Map<string, number>>, personal: readonly string[], damping?: number, iterations?: number): number[];
+/**
+ * Scan `root`, rank its files against `focus`, and render a listing within `budget`.
+ *
+ * `focus` is the current unit's files, relative to `root` and POSIX-separated; a focus entry
+ * that is not a scanned source is ignored for the personalisation vector but is still
+ * excluded from the listing, because a caller naming a file has it open already. An empty
+ * focus gives the uniform vector — plain centrality over the whole tree.
+ *
+ * `budget` is UTF-8 BYTES of the listing. See the header: this runtime has no model
+ * tokenizer and will not pretend to one.
+ */
+export declare function repoMap(root: string, options?: RepoMapOptions): RepoMap;