@nxuss/lemma 1.9.1 → 1.11.0

package/dist/cjs/utils/LocalPrefilter.js

@@ -0,0 +1,169 @@
+"use strict";
+/**
+ * LocalPrefilter — spend a local model's tokens so the expensive one never sees the noise.
+ *
+ * A broad `search_workspace` returns 200 matches across 60 files. Four of them matter. The
+ * frontier model currently pays for all 200 — in the turn that produced them and in every
+ * turn afterwards, because tool results stay in the transcript. A 3B model running on the
+ * user's own machine can rank that list for free, in the local sense of free: no API cost,
+ * no context cost, no per-token billing.
+ *
+ * This is the one place in Lemma where a model's judgement decides what the main model
+ * sees, so the safety rules are stricter than anywhere else:
+ *
+ *  1. **It ranks; it does not delete.** The prefilter reorders candidates and the caller
+ *     shows a prefix of that order. Nothing is claimed to be irrelevant — the output says
+ *     how many were withheld and how to get them all back.
+ *  2. **Fail open, always.** No Ollama, wrong model, timeout, malformed reply, an index out
+ *     of range — every one of those returns null and the caller sends the unfiltered list.
+ *     A prefilter that fails closed would silently hide code from the model.
+ *  3. **Disclosed at the call site.** The caller must state that a local model did the
+ *     ranking. A subset presented as if it were the whole search is a lie by omission,
+ *     and the user cannot audit what they were not told happened.
+ *
+ * Opt-in: set `LEMMA_LOCAL_PREFILTER=1` (or `mcp.localPrefilter: true` in lemma.config.json).
+ * Off by default, because a wrong ranking costs a correct answer and the user should choose
+ * to accept that trade.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadPrefilterConfig = loadPrefilterConfig;
+exports.isLocalModelAvailable = isLocalModelAvailable;
+exports.parseRanking = parseRanking;
+exports.rankCandidates = rankCandidates;
+exports.resetPrefilterProbe = resetPrefilterProbe;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const axios_1 = __importDefault(require("axios"));
+const DEFAULT_MODEL = "qwen2.5-coder:3b";
+const PROBE_TIMEOUT_MS = 1500;
+const RANK_TIMEOUT_MS = 12000;
+/**
+ * Below this many candidates the local round-trip (latency the user waits on) is not worth
+ * it — the full list was already cheap.
+ */
+const MIN_CANDIDATES = 25;
+function loadPrefilterConfig(cwd = process.cwd()) {
+    let fileEnabled;
+    let fileModel;
+    try {
+        const raw = JSON.parse(fs_1.default.readFileSync(path_1.default.join(cwd, "lemma.config.json"), "utf8"));
+        if (typeof raw?.mcp?.localPrefilter === "boolean")
+            fileEnabled = raw.mcp.localPrefilter;
+        if (typeof raw?.mcp?.localPrefilterModel === "string")
+            fileModel = raw.mcp.localPrefilterModel;
+    }
+    catch {
+        // An unreadable config must never turn a feature on that the user did not ask for.
+    }
+    const envEnabled = process.env.LEMMA_LOCAL_PREFILTER;
+    const enabled = envEnabled === "1" || envEnabled === "true" ? true : envEnabled === "0" || envEnabled === "false" ? false : fileEnabled === true;
+    return {
+        enabled,
+        url: process.env.OLLAMA_URL || process.env.OLLAMA_HOST || "http://localhost:11434",
+        model: process.env.LEMMA_LOCAL_PREFILTER_MODEL || fileModel || DEFAULT_MODEL,
+    };
+}
+/**
+ * Availability is cached for the process: probing on every search would add a round-trip to
+ * the very path this is meant to make cheaper. A negative result is cached too — if Ollama
+ * isn't running at the start of a session it is almost never running by the end, and
+ * re-probing would tax every search with a timeout.
+ */
+let availability = { checked: false, available: false };
+async function isLocalModelAvailable(config) {
+    if (!config.enabled)
+        return false;
+    if (availability.checked)
+        return availability.available;
+    try {
+        const res = await axios_1.default.get(`${config.url}/api/tags`, { timeout: PROBE_TIMEOUT_MS });
+        const models = (res.data?.models || []).map((m) => String(m?.name ?? ""));
+        // A configured model that isn't pulled would fail on every call; treat that as
+        // unavailable rather than discovering it once per search.
+        const base = config.model.split(":")[0];
+        availability = { checked: true, available: models.some((m) => m === config.model || m.split(":")[0] === base) };
+    }
+    catch {
+        availability = { checked: true, available: false };
+    }
+    return availability.available;
+}
+function buildPrompt(query, candidates) {
+    const list = candidates.map((c, i) => `${i}. ${c.summary}`).join("\n");
+    return [
+        `A developer is searching a codebase for: "${query}"`,
+        ``,
+        `Below are search results, numbered. Rank them by how likely each is to be what the`,
+        `developer is looking for. Definitions and primary implementations rank above call`,
+        `sites; call sites rank above tests, mocks, generated files and build output.`,
+        ``,
+        list,
+        ``,
+        `Reply with ONLY the numbers, most relevant first, comma-separated. Include every`,
+        `number exactly once. No explanation, no other text.`,
+    ].join("\n");
+}
+/**
+ * Parse the model's reply into an ordering.
+ *
+ * Strict on purpose. A small model will sometimes emit prose, duplicate an index, or invent
+ * one; any of those means we do not actually know what it decided, and guessing at its
+ * intent is how the relevant file ends up ranked last. Anything not exactly parseable
+ * returns null, and the caller sends everything.
+ */
+function parseRanking(reply, candidates) {
+    const numbers = (reply.match(/\d+/g) || []).map((n) => parseInt(n, 10));
+    if (numbers.length === 0)
+        return null;
+    const seen = new Set();
+    const order = [];
+    for (const n of numbers) {
+        if (n < 0 || n >= candidates.length)
+            return null; // hallucinated index — reply is untrustworthy
+        if (seen.has(n))
+            continue; // a repeat is sloppy, not wrong; the first position stands
+        seen.add(n);
+        order.push(candidates[n].id);
+    }
+    // Anything the model left out is appended in its original order rather than dropped.
+    // Ranking is not filtering — the caller decides what to show, and it must be able to
+    // show all of them.
+    for (let i = 0; i < candidates.length; i++) {
+        if (!seen.has(i))
+            order.push(candidates[i].id);
+    }
+    return order;
+}
+/**
+ * Rank candidates with the local model. Returns null whenever ranking did not definitively
+ * succeed — the caller must then use its own original order and withhold nothing.
+ */
+async function rankCandidates(query, candidates, config = loadPrefilterConfig()) {
+    if (candidates.length < MIN_CANDIDATES)
+        return null;
+    if (!(await isLocalModelAvailable(config)))
+        return null;
+    try {
+        const res = await axios_1.default.post(`${config.url}/api/generate`, {
+            model: config.model,
+            prompt: buildPrompt(query, candidates),
+            stream: false,
+            // Deterministic: the same search should not reorder itself between calls, and
+            // creativity is worthless for a ranking task.
+            options: { temperature: 0, num_predict: 512 },
+        }, { timeout: RANK_TIMEOUT_MS });
+        const order = parseRanking(String(res.data?.response ?? ""), candidates);
+        return order ? { order, model: config.model } : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Test seam — the availability probe is cached for the process lifetime. */
+function resetPrefilterProbe() {
+    availability = { checked: false, available: false };
+}
+//# sourceMappingURL=LocalPrefilter.js.map

package/dist/cjs/utils/LocalPrefilter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"LocalPrefilter.js","sourceRoot":"","sources":["../../../src/utils/LocalPrefilter.ts"],"names":[],"mappings":"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"}

package/dist/cjs/utils/OutputDelta.d.ts

@@ -0,0 +1,60 @@
+/**
+ * OutputDelta — re-send only what changed, never the whole thing again.
+ *
+ * The problem: a debug loop reads the same file (or runs the same command) six times.
+ * Between two of those calls maybe three lines moved, but the model pays for the entire
+ * file or the entire 400-line `tsc` dump each time — and because tool results stay in the
+ * transcript, it keeps paying for every copy on every subsequent turn.
+ *
+ * `ReadWorkspaceCache` already suppresses the *identical* case. This module covers the far
+ * more common one: it changed, but barely.
+ *
+ * Two rules this module is built around:
+ *
+ *  1. The diff is computed against the exact text the model received. Not the file on
+ *     disk, not the pre-squeeze source — the final emitted string. A diff against
+ *     anything else describes a document the model never had, which is worse than
+ *     re-sending the whole file.
+ *  2. A delta is only emitted when it is decisively smaller than the full text. Below
+ *     that margin, reconstructing from a diff is cognitive work with no token payoff, so
+ *     the full text wins. See `shouldEmitDelta`.
+ */
+export interface Hunk {
+    /** 1-indexed start line in the previous text. */
+    oldStart: number;
+    oldLines: number;
+    /** 1-indexed start line in the new text. */
+    newStart: number;
+    newLines: number;
+    /** Rendered lines, each prefixed with ' ', '-' or '+'. */
+    lines: string[];
+}
+export interface DiffResult {
+    hunks: Hunk[];
+    added: number;
+    removed: number;
+    /** True when the two texts are byte-identical. */
+    identical: boolean;
+}
+/** Line-level diff between the text the model already has and the text we would send now. */
+export declare function computeDiff(previous: string, next: string): DiffResult | null;
+/** Render hunks as a unified diff body (no ---/+++ file headers; the caller supplies context). */
+export declare function renderDiff(diff: DiffResult): string;
+export interface DeltaDecision {
+    emit: boolean;
+    /** The rendered diff body, present only when `emit` is true. */
+    body?: string;
+    added: number;
+    removed: number;
+    hunkCount: number;
+    /** Why a delta was declined — surfaced in logs and receipts, never guessed at. */
+    reason?: string;
+}
+/**
+ * Decide whether to hand the model a delta instead of the full text.
+ *
+ * Declining is the safe direction: the caller falls back to sending everything, which is
+ * always correct. So every uncertain case here resolves to `emit: false`.
+ */
+export declare function shouldEmitDelta(previous: string, next: string): DeltaDecision;
+//# sourceMappingURL=OutputDelta.d.ts.map

package/dist/cjs/utils/OutputDelta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"OutputDelta.d.ts","sourceRoot":"","sources":["../../../src/utils/OutputDelta.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AA2BH,MAAM,WAAW,IAAI;IACnB,iDAAiD;IACjD,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,4CAA4C;IAC5C,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,0DAA0D;IAC1D,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,IAAI,EAAE,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,kDAAkD;IAClD,SAAS,EAAE,OAAO,CAAC;CACpB;AA4HD,6FAA6F;AAC7F,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAY7E;AAED,kGAAkG;AAClG,wBAAgB,UAAU,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAInD;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,OAAO,CAAC;IACd,gEAAgE;IAChE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,kFAAkF;IAClF,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,aAAa,CA+B7E"}

package/dist/cjs/utils/OutputDelta.js

@@ -0,0 +1,226 @@
+"use strict";
+/**
+ * OutputDelta — re-send only what changed, never the whole thing again.
+ *
+ * The problem: a debug loop reads the same file (or runs the same command) six times.
+ * Between two of those calls maybe three lines moved, but the model pays for the entire
+ * file or the entire 400-line `tsc` dump each time — and because tool results stay in the
+ * transcript, it keeps paying for every copy on every subsequent turn.
+ *
+ * `ReadWorkspaceCache` already suppresses the *identical* case. This module covers the far
+ * more common one: it changed, but barely.
+ *
+ * Two rules this module is built around:
+ *
+ *  1. The diff is computed against the exact text the model received. Not the file on
+ *     disk, not the pre-squeeze source — the final emitted string. A diff against
+ *     anything else describes a document the model never had, which is worse than
+ *     re-sending the whole file.
+ *  2. A delta is only emitted when it is decisively smaller than the full text. Below
+ *     that margin, reconstructing from a diff is cognitive work with no token payoff, so
+ *     the full text wins. See `shouldEmitDelta`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeDiff = computeDiff;
+exports.renderDiff = renderDiff;
+exports.shouldEmitDelta = shouldEmitDelta;
+/**
+ * Lines of unchanged context kept around each changed hunk. Three is the unified-diff
+ * convention and is enough to locate a hunk unambiguously in almost all real files.
+ */
+const CONTEXT_LINES = 3;
+/**
+ * A delta must be at most this fraction of the full text to be worth emitting. At 0.5 a
+ * diff that saves only a third of the tokens is rejected: the model still has to
+ * mentally apply it, and a near-full-size diff is strictly worse than the real text.
+ */
+const DELTA_MAX_RATIO = 0.5;
+/**
+ * Below this size the full text is cheap enough that a diff never pays for its own
+ * explanation header, let alone the risk of misapplication.
+ */
+const DELTA_MIN_CHARS = 1200;
+/**
+ * Diffing is O(n*m) in the worst case. Past this line count the DP table costs more CPU
+ * (and latency the user waits on) than the tokens it could save, so we decline.
+ */
+const MAX_DIFF_LINES = 4000;
+/**
+ * Longest-common-subsequence over lines.
+ *
+ * Real edits touch a handful of lines in a file whose head and tail are untouched, so we
+ * strip the common prefix and suffix first. That turns the usual case into a DP over a
+ * few dozen lines instead of a few thousand, which is what keeps this affordable enough
+ * to run on every read.
+ */
+function diffLines(oldLines, newLines) {
+    let start = 0;
+    while (start < oldLines.length && start < newLines.length && oldLines[start] === newLines[start]) {
+        start++;
+    }
+    let endOld = oldLines.length;
+    let endNew = newLines.length;
+    while (endOld > start && endNew > start && oldLines[endOld - 1] === newLines[endNew - 1]) {
+        endOld--;
+        endNew--;
+    }
+    const a = oldLines.slice(start, endOld);
+    const b = newLines.slice(start, endNew);
+    const ops = [];
+    for (let i = 0; i < start; i++)
+        ops.push({ type: "equal", line: oldLines[i] });
+    // DP table of LCS lengths. Sized on the trimmed middle, which is why the trimming above
+    // matters: without it this allocates (n+1)*(m+1) numbers for the whole file.
+    const n = a.length;
+    const m = b.length;
+    const table = Array.from({ length: n + 1 }, () => new Array(m + 1).fill(0));
+    for (let i = n - 1; i >= 0; i--) {
+        for (let j = m - 1; j >= 0; j--) {
+            table[i][j] = a[i] === b[j] ? table[i + 1][j + 1] + 1 : Math.max(table[i + 1][j], table[i][j + 1]);
+        }
+    }
+    let i = 0;
+    let j = 0;
+    while (i < n && j < m) {
+        if (a[i] === b[j]) {
+            ops.push({ type: "equal", line: a[i] });
+            i++;
+            j++;
+        }
+        else if (table[i + 1][j] >= table[i][j + 1]) {
+            ops.push({ type: "del", line: a[i] });
+            i++;
+        }
+        else {
+            ops.push({ type: "ins", line: b[j] });
+            j++;
+        }
+    }
+    while (i < n)
+        ops.push({ type: "del", line: a[i++] });
+    while (j < m)
+        ops.push({ type: "ins", line: b[j++] });
+    for (let k = endOld; k < oldLines.length; k++)
+        ops.push({ type: "equal", line: oldLines[k] });
+    return ops;
+}
+/** Group an op stream into unified-diff hunks with `CONTEXT_LINES` of surrounding context. */
+function buildHunks(ops) {
+    const changedAt = new Set();
+    ops.forEach((op, idx) => {
+        if (op.type !== "equal")
+            changedAt.add(idx);
+    });
+    if (changedAt.size === 0)
+        return [];
+    // Expand each change into a window, then merge windows that touch or overlap so two
+    // edits four lines apart render as one hunk rather than two with duplicated context.
+    const windows = [];
+    for (const idx of Array.from(changedAt).sort((x, y) => x - y)) {
+        const lo = Math.max(0, idx - CONTEXT_LINES);
+        const hi = Math.min(ops.length - 1, idx + CONTEXT_LINES);
+        const last = windows[windows.length - 1];
+        if (last && lo <= last[1] + 1)
+            last[1] = Math.max(last[1], hi);
+        else
+            windows.push([lo, hi]);
+    }
+    // Line counters advance as we scan, so each hunk header reports true positions in both
+    // documents rather than positions relative to the hunk before it.
+    const hunks = [];
+    let oldLine = 1;
+    let newLine = 1;
+    let cursor = 0;
+    for (const [lo, hi] of windows) {
+        while (cursor < lo) {
+            const op = ops[cursor];
+            if (op.type !== "ins")
+                oldLine++;
+            if (op.type !== "del")
+                newLine++;
+            cursor++;
+        }
+        const hunk = { oldStart: oldLine, oldLines: 0, newStart: newLine, newLines: 0, lines: [] };
+        for (let idx = lo; idx <= hi; idx++) {
+            const op = ops[idx];
+            if (op.type === "equal") {
+                hunk.lines.push(` ${op.line}`);
+                hunk.oldLines++;
+                hunk.newLines++;
+                oldLine++;
+                newLine++;
+            }
+            else if (op.type === "del") {
+                hunk.lines.push(`-${op.line}`);
+                hunk.oldLines++;
+                oldLine++;
+            }
+            else {
+                hunk.lines.push(`+${op.line}`);
+                hunk.newLines++;
+                newLine++;
+            }
+        }
+        hunks.push(hunk);
+        cursor = hi + 1;
+    }
+    return hunks;
+}
+/** Line-level diff between the text the model already has and the text we would send now. */
+function computeDiff(previous, next) {
+    if (previous === next)
+        return { hunks: [], added: 0, removed: 0, identical: true };
+    const oldLines = previous.split("\n");
+    const newLines = next.split("\n");
+    if (oldLines.length > MAX_DIFF_LINES || newLines.length > MAX_DIFF_LINES)
+        return null;
+    const ops = diffLines(oldLines, newLines);
+    const hunks = buildHunks(ops);
+    const added = ops.filter((o) => o.type === "ins").length;
+    const removed = ops.filter((o) => o.type === "del").length;
+    return { hunks, added, removed, identical: false };
+}
+/** Render hunks as a unified diff body (no ---/+++ file headers; the caller supplies context). */
+function renderDiff(diff) {
+    return diff.hunks
+        .map((h) => [`@@ -${h.oldStart},${h.oldLines} +${h.newStart},${h.newLines} @@`, ...h.lines].join("\n"))
+        .join("\n");
+}
+/**
+ * Decide whether to hand the model a delta instead of the full text.
+ *
+ * Declining is the safe direction: the caller falls back to sending everything, which is
+ * always correct. So every uncertain case here resolves to `emit: false`.
+ */
+function shouldEmitDelta(previous, next) {
+    const empty = { emit: false, added: 0, removed: 0, hunkCount: 0 };
+    if (next.length < DELTA_MIN_CHARS) {
+        return { ...empty, reason: "full text is small enough that a diff saves nothing" };
+    }
+    const diff = computeDiff(previous, next);
+    if (!diff)
+        return { ...empty, reason: "too large to diff affordably" };
+    if (diff.identical)
+        return { ...empty, reason: "identical" };
+    if (diff.hunks.length === 0)
+        return { ...empty, reason: "no hunks" };
+    const body = renderDiff(diff);
+    const ratio = body.length / next.length;
+    if (ratio > DELTA_MAX_RATIO) {
+        return {
+            ...empty,
+            added: diff.added,
+            removed: diff.removed,
+            hunkCount: diff.hunks.length,
+            reason: `diff is ${Math.round(ratio * 100)}% of the full text — not worth reconstructing`,
+        };
+    }
+    return {
+        emit: true,
+        body,
+        added: diff.added,
+        removed: diff.removed,
+        hunkCount: diff.hunks.length,
+    };
+}
+//# sourceMappingURL=OutputDelta.js.map

package/dist/cjs/utils/OutputDelta.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"OutputDelta.js","sourceRoot":"","sources":["../../../src/utils/OutputDelta.ts"],"names":[],"mappings":"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"}

package/dist/cjs/utils/OutputLedger.d.ts

@@ -0,0 +1,60 @@
+/**
+ * OutputLedger — session memory of what each tool already returned.
+ *
+ * `ReadWorkspaceCache` solves this for file reads, but reads are not where the weight is.
+ * A debug loop runs `npm test` six times and `tsc --noEmit` four; each run dumps hundreds
+ * of near-identical lines into the transcript, and every one of those copies is re-sent on
+ * every later turn. By the end of a session the same failing stack trace can account for
+ * more context than the source files being debugged.
+ *
+ * So: key on (tool, call signature), remember the exact text emitted, and on a repeat
+ * answer with `IDENTICAL` or a diff instead of the payload.
+ *
+ * The correctness rule is the same one that governs the read cache, and it is absolute:
+ * a ledger hit may only suppress text the model demonstrably already received in this
+ * session. Anything else — a cold start, an evicted entry, a caller that didn't record —
+ * resolves to sending the full output. Under-suppressing costs tokens; over-suppressing
+ * costs the user a correct answer.
+ */
+/**
+ * Build a stable key from the arguments that determine the output.
+ *
+ * Only pass arguments that actually change the result. Including an incidental field
+ * (a verbosity flag that doesn't alter the payload, a timestamp) makes every call a
+ * fresh key and silently disables the ledger; including too few makes two genuinely
+ * different calls collide, which would suppress output the model never saw. When unsure,
+ * include the field — a missed saving is recoverable, a wrong suppression is not.
+ */
+export declare function ledgerKey(toolName: string, signature: Record<string, unknown>): string;
+export type LedgerStatus = "new" | "identical" | "changed";
+export interface LedgerResult {
+    status: LedgerStatus;
+    /** Replacement text to return instead of the payload; null means "send the full output". */
+    replacement: string | null;
+    /** Characters saved by the replacement, for the savings ledger. 0 when nothing was suppressed. */
+    savedChars: number;
+}
+export interface LedgerOptions {
+    /**
+     * Human-readable description of the call, used in the marker so the model can tell which
+     * earlier result it is being pointed at ("npm test", "search for 'foo' in src/").
+     */
+    label: string;
+    /**
+     * Set when re-deriving the suppressed output is not free for the caller — a command that
+     * must actually run again. Purely informational; it does not change the decision.
+     */
+    rerunHint?: string;
+}
+/**
+ * Check a freshly produced output against what this tool last returned for the same call.
+ *
+ * Always call `record` afterwards with the text you actually emitted, including when this
+ * returns `new` — otherwise the next repeat has no base to compare against.
+ */
+export declare function checkOutput(key: string, text: string, options: LedgerOptions): LedgerResult;
+/** Record the text a tool emitted (the full payload, not a marker) as the base for next time. */
+export declare function recordOutput(key: string, text: string): void;
+/** Test seam — the map is process-global and would otherwise leak between test cases. */
+export declare function resetOutputLedger(): void;
+//# sourceMappingURL=OutputLedger.d.ts.map

package/dist/cjs/utils/OutputLedger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"OutputLedger.d.ts","sourceRoot":"","sources":["../../../src/utils/OutputLedger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AA2BH;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAMtF;AAED,MAAM,MAAM,YAAY,GAAG,KAAK,GAAG,WAAW,GAAG,SAAS,CAAC;AAE3D,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,YAAY,CAAC;IACrB,4FAA4F;IAC5F,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,kGAAkG;IAClG,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,GAAG,YAAY,CAyC3F;AAED,iGAAiG;AACjG,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAyB5D;AAED,yFAAyF;AACzF,wBAAgB,iBAAiB,IAAI,IAAI,CAIxC"}