@smeltjs/core 0.1.0

package/dist/repomap/rank.d.ts

@@ -0,0 +1,52 @@
+import type { FileTags } from './tags.ts';
+/**
+ * Deterministic PageRank over the cross-file reference graph.
+ *
+ * Modelled on Aider's repo-map ranking (https://aider.chat/docs/repomap.html; see
+ * `aider/repomap.py` in https://github.com/Aider-AI/aider): files are the graph's
+ * nodes, and a file that references an identifier defined in another file contributes
+ * a weighted edge toward the definer. A file's rank is then distributed across its
+ * definitions in proportion to the reference weight each one attracted. The idea is
+ * Aider's; only the implementation is this repository's.
+ *
+ * Deterministic by construction, which is what makes the map snapshot-testable:
+ * fixed damping, a fixed iteration count, nodes visited in sorted-path order, and a
+ * total tie-break (rank, then path, then name, then line). No `Math.random`, no
+ * `Date`, no map-iteration order leaking into the output.
+ */
+/** The damping factor. 0.85 is the classic PageRank constant; fixed, never sampled. */
+export declare const PAGERANK_DAMPING = 0.85;
+/** Fixed iteration count — no convergence test, so runtime and output never vary. */
+export declare const PAGERANK_ITERATIONS = 50;
+/** What the caller hands the ranker: one file's path and its extracted tags. */
+export interface FileTagsEntry {
+    readonly path: string;
+    readonly tags: FileTags;
+}
+/** One definition with its computed rank and the measured counts that explain it. */
+export interface RankedDefinition {
+    readonly path: string;
+    readonly name: string;
+    readonly kind: string;
+    readonly line: number;
+    /** Accumulated PageRank share. `0` when no other file references this name. */
+    readonly rank: number;
+    /** Total references to this name across every scanned file (its own included). */
+    readonly refsIn: number;
+    /** Distinct files holding at least one of those references. */
+    readonly refsInFiles: number;
+    /** References the defining file makes to names defined in *other* files. */
+    readonly refsOut: number;
+}
+/**
+ * Rank every definition in the tag set.
+ *
+ * Only cross-file references move rank — a file citing its own definitions does not
+ * boost itself — but `refsIn`/`refsInFiles` count every reference, so the explanation
+ * a symbol carries never hides same-file usage.
+ *
+ * Returns all definitions (rank `0` included), sorted by rank descending with the
+ * stable tie-break: path ascending, then name ascending, then line ascending.
+ */
+export declare function rankDefinitions(files: readonly FileTagsEntry[]): readonly RankedDefinition[];
+//# sourceMappingURL=rank.d.ts.map

package/dist/repomap/rank.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rank.d.ts","sourceRoot":"","sources":["../../src/repomap/rank.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAE1C;;;;;;;;;;;;;;GAcG;AAEH,uFAAuF;AACvF,eAAO,MAAM,gBAAgB,OAAO,CAAC;AAErC,qFAAqF;AACrF,eAAO,MAAM,mBAAmB,KAAK,CAAC;AAEtC,gFAAgF;AAChF,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;CACzB;AAED,qFAAqF;AACrF,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,+EAA+E;IAC/E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,kFAAkF;IAClF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,+DAA+D;IAC/D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,4EAA4E;IAC5E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,aAAa,EAAE,GAAG,SAAS,gBAAgB,EAAE,CAkH5F"}

package/dist/repomap/rank.js

@@ -0,0 +1,155 @@
+/**
+ * Deterministic PageRank over the cross-file reference graph.
+ *
+ * Modelled on Aider's repo-map ranking (https://aider.chat/docs/repomap.html; see
+ * `aider/repomap.py` in https://github.com/Aider-AI/aider): files are the graph's
+ * nodes, and a file that references an identifier defined in another file contributes
+ * a weighted edge toward the definer. A file's rank is then distributed across its
+ * definitions in proportion to the reference weight each one attracted. The idea is
+ * Aider's; only the implementation is this repository's.
+ *
+ * Deterministic by construction, which is what makes the map snapshot-testable:
+ * fixed damping, a fixed iteration count, nodes visited in sorted-path order, and a
+ * total tie-break (rank, then path, then name, then line). No `Math.random`, no
+ * `Date`, no map-iteration order leaking into the output.
+ */
+/** The damping factor. 0.85 is the classic PageRank constant; fixed, never sampled. */
+export const PAGERANK_DAMPING = 0.85;
+/** Fixed iteration count — no convergence test, so runtime and output never vary. */
+export const PAGERANK_ITERATIONS = 50;
+/**
+ * Rank every definition in the tag set.
+ *
+ * Only cross-file references move rank — a file citing its own definitions does not
+ * boost itself — but `refsIn`/`refsInFiles` count every reference, so the explanation
+ * a symbol carries never hides same-file usage.
+ *
+ * Returns all definitions (rank `0` included), sorted by rank descending with the
+ * stable tie-break: path ascending, then name ascending, then line ascending.
+ */
+export function rankDefinitions(files) {
+    const sorted = [...files].toSorted((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+    const paths = sorted.map((file) => file.path);
+    const defsByName = new Map();
+    const allDefs = [];
+    for (const { path, tags } of sorted) {
+        for (const def of tags.defs) {
+            const mutable = { path, name: def.name, kind: def.kind, line: def.line, rank: 0 };
+            allDefs.push(mutable);
+            const existing = defsByName.get(def.name);
+            if (existing === undefined)
+                defsByName.set(def.name, [mutable]);
+            else
+                existing.push(mutable);
+        }
+    }
+    // Cross-file edges: referencing file → defining file, weighted by reference count.
+    // outWeight is each file's total outgoing weight — the PageRank edge denominator,
+    // which legitimately grows once per definer file so each edge keeps its full weight.
+    // refsOutByFile is the *measured* count a Law 2 explanation may quote: it adds
+    // `ref.count` exactly once per reference to a name some other file defines, no
+    // matter how many files define it. edgeWeights aggregates per file pair for the
+    // PageRank pass, while rank distribution below re-walks the refs so each
+    // *definition* receives its own share.
+    const outWeight = new Map(paths.map((path) => [path, 0]));
+    const refsOutByFile = new Map(paths.map((path) => [path, 0]));
+    const edgeWeights = new Map(paths.map((path) => [path, new Map()]));
+    const refsInTotal = new Map();
+    const refsInFiles = new Map();
+    for (const { path, tags } of sorted) {
+        for (const ref of tags.refs) {
+            const definers = defsByName.get(ref.name);
+            if (definers === undefined)
+                continue;
+            refsInTotal.set(ref.name, (refsInTotal.get(ref.name) ?? 0) + ref.count);
+            refsInFiles.set(ref.name, (refsInFiles.get(ref.name) ?? 0) + 1);
+            const targets = new Set(definers.map((def) => def.path));
+            let crossFile = false;
+            for (const target of [...targets].toSorted()) {
+                if (target === path)
+                    continue;
+                crossFile = true;
+                outWeight.set(path, (outWeight.get(path) ?? 0) + ref.count);
+                const row = edgeWeights.get(path);
+                row.set(target, (row.get(target) ?? 0) + ref.count);
+            }
+            if (crossFile)
+                refsOutByFile.set(path, (refsOutByFile.get(path) ?? 0) + ref.count);
+        }
+    }
+    // PageRank, fixed iterations. Dangling files (no outgoing weight) spread their rank
+    // uniformly, the standard treatment; every sum runs in sorted-path order so the
+    // floating-point result is identical on every run.
+    const nodeCount = paths.length;
+    let rank = new Map(paths.map((path) => [path, nodeCount === 0 ? 0 : 1 / nodeCount]));
+    for (let iteration = 0; iteration < PAGERANK_ITERATIONS; iteration += 1) {
+        let danglingSum = 0;
+        for (const path of paths) {
+            if (outWeight.get(path) === 0)
+                danglingSum += rank.get(path);
+        }
+        const next = new Map();
+        const base = nodeCount === 0
+            ? 0
+            : (1 - PAGERANK_DAMPING) / nodeCount + (PAGERANK_DAMPING * danglingSum) / nodeCount;
+        for (const path of paths)
+            next.set(path, base);
+        for (const source of paths) {
+            const total = outWeight.get(source);
+            if (total === 0)
+                continue;
+            const share = (PAGERANK_DAMPING * rank.get(source)) / total;
+            for (const [target, weight] of edgeWeights.get(source)) {
+                next.set(target, next.get(target) + share * weight);
+            }
+        }
+        rank = next;
+    }
+    // Distribute each file's rank across the definitions that attracted it, exactly the
+    // way Aider does: every cross-file reference edge hands the referencing file's rank,
+    // scaled by the edge's share of that file's outgoing weight, to the definition it
+    // points at.
+    for (const { path, tags } of sorted) {
+        const total = outWeight.get(path);
+        if (total === 0)
+            continue;
+        const sourceRank = rank.get(path);
+        for (const ref of tags.refs) {
+            const definers = defsByName.get(ref.name);
+            if (definers === undefined)
+                continue;
+            for (const def of definers) {
+                if (def.path === path)
+                    continue;
+                def.rank += (sourceRank * ref.count) / total;
+            }
+        }
+    }
+    const ranked = allDefs.map((def) => ({
+        path: def.path,
+        name: def.name,
+        kind: def.kind,
+        line: def.line,
+        rank: def.rank,
+        refsIn: refsInTotal.get(def.name) ?? 0,
+        refsInFiles: refsInFiles.get(def.name) ?? 0,
+        refsOut: refsOutByFile.get(def.path) ?? 0,
+    }));
+    return ranked.toSorted(compareRanked);
+}
+/**
+ * The total order every emitted map obeys: rank descending, then the stable
+ * tie-break by path, name, and line. Total, so equal-rank symbols land in the same
+ * place on every run and on every machine — remove any leg of it and the map's
+ * byte-for-byte determinism claim quietly dies.
+ */
+function compareRanked(a, b) {
+    if (a.rank !== b.rank)
+        return a.rank > b.rank ? -1 : 1;
+    if (a.path !== b.path)
+        return a.path < b.path ? -1 : 1;
+    if (a.name !== b.name)
+        return a.name < b.name ? -1 : 1;
+    return a.line - b.line;
+}
+//# sourceMappingURL=rank.js.map

package/dist/repomap/rank.js.map

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

package/dist/repomap/tags.d.ts

@@ -0,0 +1,47 @@
+import type { LanguageId } from '../types.ts';
+/**
+ * Definition/reference tag extraction for the repo map — one file at a time, through
+ * the same bundled tree-sitter grammars the structural planner uses.
+ *
+ * Modelled on Aider's repo-map tags (https://aider.chat/docs/repomap.html): a *def* is
+ * a named declaration read off the parse tree, a *ref* is an identifier occurrence.
+ * Aider extracts both with per-language `.scm` query files; here the same facts come
+ * from a manual tree walk over each language's `repomap` profile section
+ * (`src/lang/`), so no query assets are added. The design is Aider's, not this
+ * project's.
+ *
+ * Honest scope, stated rather than implied: refs count `identifier`/`type_identifier`
+ * nodes only, so a member access like `config.load()` contributes `config`, not
+ * `load` — method references travel through the object they are called on. A def whose
+ * name is a destructuring pattern is skipped rather than guessed at.
+ */
+/** One named definition, read off the parse tree. `line` is 1-based. */
+export interface DefinitionTag {
+    readonly name: string;
+    /** Human word for the node kind, e.g. `'function'` — same register as the planners. */
+    readonly kind: string;
+    readonly line: number;
+}
+/** One referenced identifier and how many times this file references it. */
+export interface ReferenceTag {
+    readonly name: string;
+    readonly count: number;
+}
+/** Everything the repo map needs to know about one file. */
+export interface FileTags {
+    /** In document order. */
+    readonly defs: readonly DefinitionTag[];
+    /** Sorted by name, so the extraction is deterministic end to end. */
+    readonly refs: readonly ReferenceTag[];
+}
+/**
+ * Extract definition and reference tags from one file.
+ *
+ * Deterministic: same text, same language, identical tags — defs in document order,
+ * refs sorted by name. A def's own name node is not counted as a reference to itself.
+ *
+ * @throws {GrammarUnavailableError} when the grammar cannot load or produces no tree.
+ *   Never a lexical guess — same no-fallback rule as the structural planner.
+ */
+export declare function extractTags(text: string, language: LanguageId): Promise<FileTags>;
+//# sourceMappingURL=tags.d.ts.map

package/dist/repomap/tags.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tags.d.ts","sourceRoot":"","sources":["../../src/repomap/tags.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C;;;;;;;;;;;;;;;GAeG;AAEH,wEAAwE;AACxE,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,uFAAuF;IACvF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,4EAA4E;AAC5E,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,4DAA4D;AAC5D,MAAM,WAAW,QAAQ;IACvB,yBAAyB;IACzB,QAAQ,CAAC,IAAI,EAAE,SAAS,aAAa,EAAE,CAAC;IACxC,qEAAqE;IACrE,QAAQ,CAAC,IAAI,EAAE,SAAS,YAAY,EAAE,CAAC;CACxC;AAiCD;;;;;;;;GAQG;AACH,wBAAsB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,UAAU,GAAG,OAAO,CAAC,QAAQ,CAAC,CA8DvF"}

package/dist/repomap/tags.js

@@ -0,0 +1,101 @@
+import { Parser } from 'web-tree-sitter';
+import { GrammarUnavailableError } from '../errors.js';
+import { profileFor } from '../lang/registry.js';
+import { loadGrammar } from '../plan/grammar.js';
+/**
+ * C/C++ specifier node types that name a *usage site* as readily as a definition:
+ * `struct point p;` parses as a `struct_specifier` with a `name` and no `body`, same
+ * as the `struct point { … };` that actually defines it. Only the bodied form is a
+ * definition. Without this check a mere mention earns a `defined at` receipt, *and*
+ * its name node lands in `defNameStarts` — so the real definition's cross-file
+ * references silently vanish from the map.
+ */
+const BODY_REQUIRED_TYPES = new Set([
+    'struct_specifier',
+    'union_specifier',
+    'enum_specifier',
+    'class_specifier',
+]);
+/**
+ * A local `const x = …` inside a function body is not a map-worthy symbol. A
+ * `variable_declarator` counts as a definition only at module top level — directly
+ * under the program node, or under an `export` statement that is.
+ */
+function isDefinitionSite(node) {
+    if (BODY_REQUIRED_TYPES.has(node.type) && node.childForFieldName('body') === null) {
+        return false; // a bodiless specifier is a usage or forward declaration, not a definition
+    }
+    if (node.type !== 'variable_declarator')
+        return true;
+    const container = node.parent?.parent;
+    if (container === null || container === undefined)
+        return false;
+    if (container.type === 'program')
+        return true;
+    return container.type === 'export_statement' && container.parent?.type === 'program';
+}
+/**
+ * Extract definition and reference tags from one file.
+ *
+ * Deterministic: same text, same language, identical tags — defs in document order,
+ * refs sorted by name. A def's own name node is not counted as a reference to itself.
+ *
+ * @throws {GrammarUnavailableError} when the grammar cannot load or produces no tree.
+ *   Never a lexical guess — same no-fallback rule as the structural planner.
+ */
+export async function extractTags(text, language) {
+    const grammar = await loadGrammar(language);
+    // The per-language facts live on the language's profile (`src/lang/`). A profile
+    // without a repomap section contributes nothing — no symbols, never wrong ones.
+    const repomap = profileFor(language).repomap;
+    const defKinds = repomap?.defKinds ?? {};
+    const refTypes = repomap?.refTypes ?? [];
+    const parser = new Parser();
+    let tree = null;
+    try {
+        parser.setLanguage(grammar);
+        tree = parser.parse(text);
+        if (tree === null) {
+            throw new GrammarUnavailableError(`smelt: the ${language} parser returned no tree, so no tags can be extracted. ` +
+                `Refusing to guess at definitions that were never parsed.`);
+        }
+        const defs = [];
+        const refCounts = new Map();
+        /** Start indices of def-name nodes, so a definition never references itself. */
+        const defNameStarts = new Set();
+        // Depth-first, document order, via an explicit stack — recursion depth on a real
+        // file is the tree's depth, which nothing bounds.
+        const stack = [tree.rootNode];
+        while (stack.length > 0) {
+            const node = stack.pop();
+            const kind = defKinds[node.type];
+            if (kind !== undefined && isDefinitionSite(node)) {
+                const nameNode = node.childForFieldName('name');
+                // Only a plain identifier names a def; a destructuring pattern is skipped, not
+                // guessed at.
+                if (nameNode !== null && nameNode.type.endsWith('identifier')) {
+                    defs.push({ name: nameNode.text, kind, line: node.startPosition.row + 1 });
+                    defNameStarts.add(nameNode.startIndex);
+                }
+            }
+            if (refTypes.includes(node.type) && !defNameStarts.has(node.startIndex)) {
+                refCounts.set(node.text, (refCounts.get(node.text) ?? 0) + 1);
+            }
+            const children = node.namedChildren;
+            for (let i = children.length - 1; i >= 0; i -= 1) {
+                const child = children[i];
+                if (child !== null && child !== undefined)
+                    stack.push(child);
+            }
+        }
+        const refs = [...refCounts.entries()]
+            .toSorted(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+            .map(([name, count]) => ({ name, count }));
+        return { defs, refs };
+    }
+    finally {
+        tree?.delete();
+        parser.delete();
+    }
+}
+//# sourceMappingURL=tags.js.map

package/dist/repomap/tags.js.map

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

package/dist/retrieve.d.ts

@@ -0,0 +1,14 @@
+import type { ElisionStore, RetrieveTool } from './types.ts';
+/** The tool name smelt's markers reference. Consumers hard-code it; do not rename it. */
+export declare const RETRIEVE_TOOL_NAME = "smelt_retrieve";
+/**
+ * Wrap a store as the tool a model calls.
+ *
+ * Why the description says "ask whenever it might matter": under-retrieval is the
+ * failure mode that looks like success. A model that never calls this produces a
+ * confident answer built on material it never saw, and the retrieve rate reads 0% —
+ * which is indistinguishable from perfect pruning. Encouraging retrieval keeps the
+ * signal in {@link ElisionStore.stats} honest.
+ */
+export declare function createRetrieveTool(store: ElisionStore): RetrieveTool;
+//# sourceMappingURL=retrieve.d.ts.map

package/dist/retrieve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retrieve.d.ts","sourceRoot":"","sources":["../src/retrieve.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE7D,yFAAyF;AACzF,eAAO,MAAM,kBAAkB,mBAAmB,CAAC;AAwBnD;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,YAAY,GAAG,YAAY,CAWpE"}

package/dist/retrieve.js

@@ -0,0 +1,44 @@
+import { defaultMarker } from './apply.js';
+/** The tool name smelt's markers reference. Consumers hard-code it; do not rename it. */
+export const RETRIEVE_TOOL_NAME = 'smelt_retrieve';
+/**
+ * The example marker inside the tool description is *rendered by the real marker
+ * builder*, never hand-written — the description is the one string a model reads to
+ * recognize markers, and an example whose shape drifted from the wire format
+ * (`<<smelt: …>>` when real markers say `<<smelt/v1: …>>`) would teach the model to
+ * miss every marker it actually receives. `test/guards/marker-format.test.ts` pins
+ * this to `MARKER_FORMAT_VERSION`.
+ */
+const EXAMPLE_MARKER = defaultMarker({
+    hash: 'a1b2c3d4e5f60718',
+    bytes: 412,
+    rule: 'sibling-collapse',
+    explanation: 'collapsed 3 sibling functions',
+});
+const DESCRIPTION = 'Return the exact original text that was elided from a previous tool result. ' +
+    `Context you were given may contain markers like \`${EXAMPLE_MARKER}\`. ` +
+    'Call this with that hash to get those bytes ' +
+    'back verbatim. Nothing was deleted — it is all still here. Ask whenever the elided ' +
+    'material might matter; guessing at what a marker hid is never correct.';
+/**
+ * Wrap a store as the tool a model calls.
+ *
+ * Why the description says "ask whenever it might matter": under-retrieval is the
+ * failure mode that looks like success. A model that never calls this produces a
+ * confident answer built on material it never saw, and the retrieve rate reads 0% —
+ * which is indistinguishable from perfect pruning. Encouraging retrieval keeps the
+ * signal in {@link ElisionStore.stats} honest.
+ */
+export function createRetrieveTool(store) {
+    return {
+        name: RETRIEVE_TOOL_NAME,
+        description: DESCRIPTION,
+        inputSchema: {
+            type: 'object',
+            properties: { hash: { type: 'string' } },
+            required: ['hash'],
+        },
+        invoke: ({ hash }) => store.retrieve(hash),
+    };
+}
+//# sourceMappingURL=retrieve.js.map

package/dist/retrieve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retrieve.js","sourceRoot":"","sources":["../src/retrieve.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAG3C,yFAAyF;AACzF,MAAM,CAAC,MAAM,kBAAkB,GAAG,gBAAgB,CAAC;AAEnD;;;;;;;GAOG;AACH,MAAM,cAAc,GAAG,aAAa,CAAC;IACnC,IAAI,EAAE,kBAAkB;IACxB,KAAK,EAAE,GAAG;IACV,IAAI,EAAE,kBAAkB;IACxB,WAAW,EAAE,+BAA+B;CAC7C,CAAC,CAAC;AAEH,MAAM,WAAW,GACf,8EAA8E;IAC9E,qDAAqD,cAAc,MAAM;IACzE,8CAA8C;IAC9C,qFAAqF;IACrF,wEAAwE,CAAC;AAE3E;;;;;;;;GAQG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAmB;IACpD,OAAO;QACL,IAAI,EAAE,kBAAkB;QACxB,WAAW,EAAE,WAAW;QACxB,WAAW,EAAE;YACX,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE;YACxC,QAAQ,EAAE,CAAC,MAAM,CAAC;SACnB;QACD,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC;KAC3C,CAAC;AACJ,CAAC"}

package/dist/stages.d.ts

@@ -0,0 +1,22 @@
+import type { DistillStage, RerankStage } from './types.ts';
+/**
+ * The reranker that ships with smelt: one that refuses.
+ *
+ * It exists so that "reranking is a seam, not a feature" is enforced rather than
+ * promised. Wire this in and you get an exception naming the interface you were
+ * supposed to implement. There is no default hosted reranker, no bundled key handling,
+ * and no `SMELT_RERANK_API_KEY` — the first of those to appear breaks Law 1 for every
+ * consumer at once, including the ones who never read the changelog.
+ */
+export declare const unconfiguredRerankStage: RerankStage;
+/**
+ * Learned distillation, same treatment, for a different reason.
+ *
+ * Distillation is out of v1 because a model-written summary cannot satisfy Law 2. "The
+ * model condensed this" does not say what was removed, and once the text is rewritten
+ * there is nothing left to store under a hash. If this ever ships it will store the
+ * original, explain itself in the same rule-named terms every other elision uses, and
+ * be reversible — or it will not ship.
+ */
+export declare const unconfiguredDistillStage: DistillStage;
+//# sourceMappingURL=stages.d.ts.map

package/dist/stages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stages.d.ts","sourceRoot":"","sources":["../src/stages.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAmB,WAAW,EAAqB,MAAM,YAAY,CAAC;AAEhG;;;;;;;;GAQG;AACH,eAAO,MAAM,uBAAuB,EAAE,WAYrC,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,wBAAwB,EAAE,YAQtC,CAAC"}

package/dist/stages.js

@@ -0,0 +1,33 @@
+import { NotImplementedError } from './errors.js';
+/**
+ * The reranker that ships with smelt: one that refuses.
+ *
+ * It exists so that "reranking is a seam, not a feature" is enforced rather than
+ * promised. Wire this in and you get an exception naming the interface you were
+ * supposed to implement. There is no default hosted reranker, no bundled key handling,
+ * and no `SMELT_RERANK_API_KEY` — the first of those to appear breaks Law 1 for every
+ * consumer at once, including the ones who never read the changelog.
+ */
+export const unconfiguredRerankStage = {
+    id: 'rerank/unconfigured',
+    rerank(_candidates, _query) {
+        throw new NotImplementedError('reranking', 'docs/HANDOFF.md § "Explicitly out of v1" — implement `RerankStage` in your own ' +
+            'code, with your own key, so the network call is visible in your source');
+    },
+};
+/**
+ * Learned distillation, same treatment, for a different reason.
+ *
+ * Distillation is out of v1 because a model-written summary cannot satisfy Law 2. "The
+ * model condensed this" does not say what was removed, and once the text is rewritten
+ * there is nothing left to store under a hash. If this ever ships it will store the
+ * original, explain itself in the same rule-named terms every other elision uses, and
+ * be reversible — or it will not ship.
+ */
+export const unconfiguredDistillStage = {
+    id: 'distill/unconfigured',
+    distill(_text, _budgetBytes) {
+        throw new NotImplementedError('learned distillation', 'docs/HANDOFF.md § "Explicitly out of v1"');
+    },
+};
+//# sourceMappingURL=stages.js.map

package/dist/stages.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stages.js","sourceRoot":"","sources":["../src/stages.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAGlD;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAgB;IAClD,EAAE,EAAE,qBAAqB;IACzB,MAAM,CACJ,WAAuC,EACvC,MAAc;QAEd,MAAM,IAAI,mBAAmB,CAC3B,WAAW,EACX,iFAAiF;YAC/E,wEAAwE,CAC3E,CAAC;IACJ,CAAC;CACF,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAiB;IACpD,EAAE,EAAE,sBAAsB;IAC1B,OAAO,CAAC,KAAa,EAAE,YAAoB;QACzC,MAAM,IAAI,mBAAmB,CAC3B,sBAAsB,EACtB,0CAA0C,CAC3C,CAAC;IACJ,CAAC;CACF,CAAC"}

package/dist/stats.d.ts

@@ -0,0 +1,40 @@
+import type { RetrieveStats } from './types.ts';
+/**
+ * The directly-observed half of {@link RetrieveStats}: the five counts a store reads
+ * off its own records — a map size, a directory scan, a journal fold. Nothing in here
+ * is derived; every field is a fact the store witnessed. The derived half —
+ * `expansionRate` and `allElisionsRetrieved`, the honesty arithmetic of Law 3 — is
+ * computed from these by {@link retrieveStats}, in exactly one place.
+ */
+export type RawRetrieveCounters = Omit<RetrieveStats, 'expansionRate' | 'allElisionsRetrieved'>;
+/**
+ * The one derivation of the honesty arithmetic, shared by every store.
+ *
+ * `expansionRate` is the number this project exists to keep honest, and
+ * `allElisionsRetrieved` is the one degenerate outcome it names (HANDOFF Decision 4).
+ * When each store derived them privately, the two copies could drift — and a store
+ * whose arithmetic drifted flattering-ward would be the exact silent failure Law 3's
+ * counters exist to refuse. So the seam between a store and its stats is narrowed to
+ * raw counters: an {@link ElisionStore} adapter *supplies counts*
+ * ({@link RawRetrieveCounters}) and never derives the metric.
+ *
+ * **Contract for adapter authors.** A custom store implements a
+ * `rawCounters(): RawRetrieveCounters` method (or any equivalent that gathers the five
+ * counts from its own records) and delegates its public `stats()` to this function:
+ *
+ * ```ts
+ * stats(): RetrieveStats {
+ *   return retrieveStats(this.rawCounters());
+ * }
+ * ```
+ *
+ * This is a free wrapper function rather than an abstract base class, deliberately —
+ * it is the least-breaking shape. The stores share no storage machinery (one is a
+ * `Map`, one is a directory), so a base class would couple every adapter's inheritance
+ * chain to smelt's for the sake of two lines of arithmetic; an existing `ElisionStore`
+ * implementation keeps its own hierarchy and adopts this contract by changing only its
+ * `stats()` body. The {@link ElisionStore} interface itself is unchanged: consumers
+ * still call `stats()` and never see this seam.
+ */
+export declare function retrieveStats(raw: RawRetrieveCounters): RetrieveStats;
+//# sourceMappingURL=stats.d.ts.map

package/dist/stats.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stats.d.ts","sourceRoot":"","sources":["../src/stats.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD;;;;;;GAMG;AACH,MAAM,MAAM,mBAAmB,GAAG,IAAI,CAAC,aAAa,EAAE,eAAe,GAAG,sBAAsB,CAAC,CAAC;AAEhG;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,mBAAmB,GAAG,aAAa,CAMrE"}

package/dist/stats.js

@@ -0,0 +1,37 @@
+/**
+ * The one derivation of the honesty arithmetic, shared by every store.
+ *
+ * `expansionRate` is the number this project exists to keep honest, and
+ * `allElisionsRetrieved` is the one degenerate outcome it names (HANDOFF Decision 4).
+ * When each store derived them privately, the two copies could drift — and a store
+ * whose arithmetic drifted flattering-ward would be the exact silent failure Law 3's
+ * counters exist to refuse. So the seam between a store and its stats is narrowed to
+ * raw counters: an {@link ElisionStore} adapter *supplies counts*
+ * ({@link RawRetrieveCounters}) and never derives the metric.
+ *
+ * **Contract for adapter authors.** A custom store implements a
+ * `rawCounters(): RawRetrieveCounters` method (or any equivalent that gathers the five
+ * counts from its own records) and delegates its public `stats()` to this function:
+ *
+ * ```ts
+ * stats(): RetrieveStats {
+ *   return retrieveStats(this.rawCounters());
+ * }
+ * ```
+ *
+ * This is a free wrapper function rather than an abstract base class, deliberately —
+ * it is the least-breaking shape. The stores share no storage machinery (one is a
+ * `Map`, one is a directory), so a base class would couple every adapter's inheritance
+ * chain to smelt's for the sake of two lines of arithmetic; an existing `ElisionStore`
+ * implementation keeps its own hierarchy and adopts this contract by changing only its
+ * `stats()` body. The {@link ElisionStore} interface itself is unchanged: consumers
+ * still call `stats()` and never see this seam.
+ */
+export function retrieveStats(raw) {
+    return {
+        ...raw,
+        expansionRate: raw.elisionsStored === 0 ? 0 : raw.uniqueRetrieved / raw.elisionsStored,
+        allElisionsRetrieved: raw.elisionsStored > 0 && raw.uniqueRetrieved === raw.elisionsStored,
+    };
+}
+//# sourceMappingURL=stats.js.map

package/dist/stats.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stats.js","sourceRoot":"","sources":["../src/stats.ts"],"names":[],"mappings":"AAWA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,UAAU,aAAa,CAAC,GAAwB;IACpD,OAAO;QACL,GAAG,GAAG;QACN,aAAa,EAAE,GAAG,CAAC,cAAc,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,eAAe,GAAG,GAAG,CAAC,cAAc;QACtF,oBAAoB,EAAE,GAAG,CAAC,cAAc,GAAG,CAAC,IAAI,GAAG,CAAC,eAAe,KAAK,GAAG,CAAC,cAAc;KAC3F,CAAC;AACJ,CAAC"}