@smeltjs/core 0.5.0 → 0.6.0

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"","sourcesContent":["/** Languages smelt can parse structurally. Everything else falls back to the lexical planner. */\nexport type LanguageId =\n  | 'typescript'\n  | 'tsx'\n  | 'javascript'\n  | 'rust'\n  | 'python'\n  | 'go'\n  | 'java'\n  | 'c'\n  | 'cpp'\n  | 'c_sharp'\n  | 'ruby'\n  | 'php'\n  | 'kotlin'\n  | 'swift'\n  | 'bash';\n\n/** `'unknown'` is a first-class outcome, not a failure: it selects the lexical planner. */\nexport type DetectedLanguage = LanguageId | 'unknown';\n\n/** A half-open byte range `[start, end)` into the UTF-8 bytes of the input. */\nexport interface ByteRange {\n  readonly start: number;\n  readonly end: number;\n}\n\n/**\n * Why a range was elided, in two registers: a stable id for counters, and a sentence\n * a human can read in a diff. Law 2 — every elision is explainable — lives here:\n * if you cannot write the sentence, the rule does not ship.\n */\nexport interface ElisionReason {\n  /** Stable machine id, e.g. `'sibling-collapse'`, `'line-window'`. */\n  readonly rule: string;\n  /** e.g. `'collapsed 3 sibling functions'`. Present tense, no trailing period. */\n  readonly explanation: string;\n}\n\n/** One range a planner proposes to remove. Plans are pure data — inspectable and testable. */\nexport interface PlannedElision {\n  readonly range: ByteRange;\n  readonly reason: ElisionReason;\n}\n\n/**\n * The complete output of a planner: the whole decision, before anything is mutated.\n * A plan can be logged, diffed, snapshot-tested, and rejected without touching the text.\n */\nexport interface ElisionPlan {\n  readonly planner: string;\n  readonly language: DetectedLanguage;\n  readonly elisions: readonly PlannedElision[];\n}\n\n/**\n * The seam through which a planner asks what a marker will cost, in UTF-8 bytes.\n *\n * Marker cost is `apply.ts`'s fact — the applier renders the marker, so only the\n * applier knows its price. Planners need that price for two decisions (profitability:\n * a marker that costs more than it removes grows the output; and budget prediction:\n * which ladder rung actually fits), and before this seam each planner rebuilt the\n * marker machinery privately to measure it — correct, but an inversion. Now\n * `markerPricing()` in `apply.ts` builds the one adapter from the exact builder\n * `applyPlan` will use, and planners ask it. They never guess, and they never render\n * a marker of their own.\n *\n * The price is exact, not an estimate: the cost of the marker this elision would\n * earn, comment leader and all, with a stand-in hash of the real hash's length —\n * marker cost depends on the hash's *length*, never its value.\n */\nexport interface MarkerPricing {\n  /** The exact UTF-8 byte cost of the marker an elision with this reason and size would earn. */\n  costBytes(reason: ElisionReason, elidedBytes: number): number;\n}\n\n/**\n * What the caller hands a planner.\n *\n * Constructed centrally: `createSmelter` (and through it, the CLI) builds the one\n * `PlanInput` per call, including its {@link MarkerPricing} — a caller invoking\n * `planLexical`/`planStructural` directly builds `pricing` with `markerPricing()`\n * from `apply.ts`. A JS caller who omits it gets {@link MissingMarkerPricingError}\n * at plan time, not a guessed cost.\n */\nexport interface PlanInput {\n  readonly text: string;\n  readonly language: DetectedLanguage;\n  /** Soft ceiling for the emitted output, in UTF-8 bytes. Planners aim under it. */\n  readonly budgetBytes: number;\n  /**\n   * What the caller was actually looking for — grep pattern, symbol name, error string.\n   * Planners keep matching regions and collapse around them.\n   */\n  readonly focus?: readonly string[];\n  /**\n   * What a marker costs. Required: a planner that guesses marker cost can plan an\n   * elision that grows the output. See {@link MarkerPricing}; built by\n   * `markerPricing()` in `apply.ts` from the exact builder `applyPlan` will use.\n   */\n  readonly pricing: MarkerPricing;\n}\n\n/**\n * A planner decides *what* to remove. It never removes anything itself; `applyPlan`\n * does that. Keeping the decision and the mutation apart is what makes the decision\n * testable in isolation.\n */\nexport interface Planner {\n  readonly id: string;\n  plan(input: PlanInput): Promise<ElisionPlan>;\n}\n\n/** One elision that actually happened, with the receipt needed to undo it. */\nexport interface AppliedElision {\n  /** Content hash of the removed bytes — the key `retrieve()` takes. */\n  readonly hash: string;\n  /** Where the removed bytes were in the *input*. */\n  readonly range: ByteRange;\n  /**\n   * Where the marker sits in the *output*. Law 3 — every elision is reversible — needs\n   * this: {@link Reconstructor} splices stored bytes back over these ranges. Without it,\n   * \"reversible\" would mean parsing markers back out of the text, which is a guess.\n   * This is a fact recorded at the moment of the cut.\n   */\n  readonly outputRange: ByteRange;\n  /** Size of the removed content, in UTF-8 bytes. */\n  readonly bytes: number;\n  readonly reason: ElisionReason;\n  /** The exact marker text substituted into the output. */\n  readonly marker: string;\n}\n\n/**\n * A consumer-supplied counter, so a caller who bills in tokens can *see* tokens.\n *\n * Budgets in smelt's core are UTF-8 bytes, permanently — bytes are the only unit that\n * is computable locally for every model, and they mean the same thing in five years.\n * See `docs/ARCHITECTURE.md` § \"Decision 1\". This hook does not change that: it adds a\n * second, labelled number to the result. The plan is still made in bytes.\n *\n * Both `id` and `unit` are required, and that is a Law 4 decision rather than\n * bookkeeping: a token count is meaningless without naming the tokenizer that produced\n * it. Anthropic's own docs record that Claude 4.7 and later use a newer tokenizer where\n * the same text yields roughly 30% more tokens than on earlier models — so `1,204\n * tokens` is not a fact, and `1,204 tokens (claude-4.7/count_tokens)` is.\n *\n * **This hook does not relax Law 1.** smelt imports no transport and the guard proves\n * that about smelt's own modules; it cannot prove it about a function you hand in. A\n * `count()` that calls an API makes *your* process call an API, from a line in *your*\n * source — exactly the arrangement {@link RerankStage} already describes. `count` is\n * synchronous on purpose: local tokenizers are synchronous, and network clients are not.\n */\nexport interface Measure {\n  /** Names the counter, e.g. `'tiktoken/o200k_base'` or `'claude-4.7/count_tokens'`. */\n  readonly id: string;\n  /** The unit `count()` returns, e.g. `'tokens'`. Printed next to the number. */\n  readonly unit: string;\n  /** Local, synchronous count over the whole string. */\n  count(text: string): number;\n}\n\n/** A second size for a result, in someone else's unit, with the counter named. */\nexport interface MeasuredSize {\n  /** {@link Measure.id} of the counter that produced these numbers. */\n  readonly measure: string;\n  /** {@link Measure.unit}. */\n  readonly unit: string;\n  readonly input: number;\n  readonly output: number;\n}\n\n/** The result of smelting one blob of text. */\nexport interface SmeltResult {\n  readonly text: string;\n  readonly inputBytes: number;\n  readonly outputBytes: number;\n  readonly planner: string;\n  readonly language: DetectedLanguage;\n  readonly elisions: readonly AppliedElision[];\n  /** Present only when the caller supplied a {@link Measure}. Never invented. */\n  readonly measured?: MeasuredSize;\n}\n\n/**\n * Reversibility, as a callable. Takes a {@link SmeltResult} and the store that holds its\n * elided bytes, and returns the original text — byte for byte.\n */\nexport type Reconstructor = (result: SmeltResult, store: ElisionStore) => string;\n\n// ---------------------------------------------------------------------------\n// The store, and the counters that make over-pruning visible\n// ---------------------------------------------------------------------------\n\n/**\n * The numbers that keep smelt honest about itself.\n *\n * Law 3 says elisions are reversible. That is cheap to satisfy and easy to abuse: a\n * compressor that cuts everything is \"reversible\" and useless. The *retrieve rate* is\n * the tell. If the model keeps calling `smelt_retrieve`, smelt cut material the task\n * needed, and the round trip cost more tokens than the elision saved.\n *\n * So: `expansionRate` is not telemetry. It is the metric a caller tunes budgets\n * against, and the only number smelt is willing to have an opinion about — because it\n * measures it locally, per session, on the caller's own traffic.\n */\nexport interface RetrieveStats {\n  /** Distinct blobs put into the store. */\n  readonly elisionsStored: number;\n  /** Total bytes held by the store. */\n  readonly bytesStored: number;\n  /** Every `retrieve()` call, including repeats and misses. */\n  readonly retrieveCalls: number;\n  /** Distinct hashes successfully retrieved at least once. */\n  readonly uniqueRetrieved: number;\n  /** Calls for a hash the store does not hold. Non-zero means a bug, not over-pruning. */\n  readonly misses: number;\n  /**\n   * `uniqueRetrieved / elisionsStored`, or `0` when nothing has been stored.\n   *\n   * Read it as: *what fraction of what smelt hid did the model have to ask for back?*\n   * There is no universally right value, and smelt does not ship a threshold it has\n   * not measured. Rising across a workload is the signal.\n   */\n  readonly expansionRate: number;\n  /**\n   * The one degenerate outcome smelt is willing to name: **every distinct blob it hid\n   * was asked for again.**\n   *\n   * smelt ships no expansion-rate threshold, because a threshold is a policy claim it\n   * has no basis for and the right rate depends on how aggressive a budget the caller\n   * chose — and a library printing warnings into someone else's process is bad manners.\n   * This is not a threshold. At `uniqueRetrieved === elisionsStored` the elision\n   * achieved nothing and cost a round trip: an arithmetic fact, not a preference. What\n   * to do about it is the caller's call.\n   *\n   * `false` for an empty store — nothing was hidden, so nothing was defeated.\n   */\n  readonly allElisionsRetrieved: boolean;\n}\n\n/**\n * Local, content-addressed storage for elided bytes. No network, no eviction in v1 —\n * evicting is how \"reversible\" quietly becomes \"reversible for a while\".\n */\nexport interface ElisionStore {\n  /** Store content, returning its hash. Idempotent for identical content. */\n  put(content: string): string;\n  /** The stored content, or `undefined` if this store never held that hash. */\n  peek(hash: string): string | undefined;\n  /**\n   * The stored content, *counted* as a retrieval. This is what the model's tool calls.\n   *\n   * @throws {UnknownHashError} when the hash is unknown.\n   * @throws {StoreCorruptionError} — {@link DirectoryElisionStore} only — when the\n   *   bytes on disk no longer hash to their own name. Distinct from\n   *   `UnknownHashError` on purpose: \"we hold damaged bytes\" and \"it never existed\"\n   *   are different answers, and a caller that conflates them will report the wrong\n   *   one to its user.\n   *\n   * A {@link DirectoryElisionStore} whose journal cannot be written (a read-only\n   * store directory, a full disk) still returns the bytes — verified bytes are never\n   * withheld over a bookkeeping failure — and surfaces the lost count as a\n   * `process.emitWarning` named `SmeltCounterWriteFailure` instead of throwing. Its\n   * stats go quiet from that point; the retrieval itself succeeded.\n   */\n  retrieve(hash: string): string;\n  /**\n   * Whether this hash can be retrieved — **not** merely whether a slot bearing it\n   * exists. `true` must mean the very next `retrieve(hash)` returns bytes, so a store\n   * that verifies content on read verifies here too and raises its corruption error\n   * rather than answering `true` for bytes it would then refuse. Uncounted: a check is\n   * not the model asking for material back.\n   */\n  has(hash: string): boolean;\n  /** A snapshot of the counters. See {@link RetrieveStats}. */\n  stats(): RetrieveStats;\n}\n\n/**\n * The retrieval tool a consumer exposes to its model. Deliberately not an MCP or\n * provider-specific shape — smelt does not know which SDK you use. The consumer adapts\n * this into its own tool schema; the contract is `hash in, exact bytes out`.\n */\nexport interface RetrieveTool {\n  /** `'smelt_retrieve'`. Stable — consumers hard-code it in prompts. */\n  readonly name: string;\n  /** Prose the consumer can put straight into a tool description. */\n  readonly description: string;\n  /**\n   * JSON-Schema-shaped parameter description, for consumers that want one.\n   *\n   * Strict-mode shaped: `additionalProperties: false` and a `required` naming every\n   * property, so a consumer registering this under OpenAI's structured-outputs strict\n   * mode is not refused at registration. See {@link createRetrieveTool}.\n   */\n  readonly inputSchema: {\n    readonly type: 'object';\n    readonly properties: {\n      readonly hash: { readonly type: 'string'; readonly description: string };\n    };\n    readonly required: readonly ['hash'];\n    readonly additionalProperties: false;\n  };\n  /**\n   * @throws {UnknownHashError} when the hash is unknown.\n   * @throws {StoreCorruptionError} when the backing store holds damaged bytes for\n   *   that hash — see {@link ElisionStore.retrieve}, whose contract this forwards\n   *   verbatim. Surface either to the model as a tool error, never as empty text.\n   */\n  invoke(input: { readonly hash: string }): string;\n}\n\n// ---------------------------------------------------------------------------\n// Pluggable stages — interfaces in v1, nothing more\n// ---------------------------------------------------------------------------\n\n/** A candidate handed to a {@link RerankStage}: an opaque id plus the text to judge. */\nexport interface RerankCandidate {\n  readonly id: string;\n  readonly text: string;\n}\n\n/** A reranked candidate, most relevant first. `score` is the stage's own scale. */\nexport interface RerankedCandidate extends RerankCandidate {\n  readonly score: number;\n}\n\n/**\n * Relevance reranking — a *seam*, not a feature.\n *\n * Hosted rerankers are good and smelt will never bundle one, because bundling would\n * break Law 1: the moment smelt ships a default reranker, `smelt()` can make a network\n * call that the caller did not ask for and cannot see. A consumer that wants one\n * implements this interface, wires its own key, and owns the fact that its context now\n * leaves the machine. That decision must be legible in the consumer's own source.\n */\nexport interface RerankStage {\n  readonly id: string;\n  /** May make network calls — that is the consumer's choice, made in the consumer's code. */\n  rerank(\n    candidates: readonly RerankCandidate[],\n    query: string,\n  ): Promise<readonly RerankedCandidate[]>;\n}\n\n/**\n * Learned distillation — rewriting content with a model instead of cutting it.\n *\n * Out of v1 for a reason beyond the network: a distilled paragraph cannot satisfy\n * Law 2. \"The model summarised this\" is not an explanation of what was removed, and\n * the removed material is no longer recoverable from the output. If this ever ships,\n * it ships as a stage that stores the original and explains itself in the same terms\n * every other rule does.\n */\nexport interface DistillStage {\n  readonly id: string;\n  distill(text: string, budgetBytes: number): Promise<string>;\n}\n"]}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"","sourcesContent":["/** Languages smelt can parse structurally. Everything else falls back to the lexical planner. */\nexport type LanguageId =\n  | 'typescript'\n  | 'tsx'\n  | 'javascript'\n  | 'rust'\n  | 'python'\n  | 'go'\n  | 'java'\n  | 'c'\n  | 'cpp'\n  | 'c_sharp'\n  | 'ruby'\n  | 'php'\n  | 'kotlin'\n  | 'swift'\n  | 'bash';\n\n/** `'unknown'` is a first-class outcome, not a failure: it selects the lexical planner. */\nexport type DetectedLanguage = LanguageId | 'unknown';\n\n/** A half-open byte range `[start, end)` into the UTF-8 bytes of the input. */\nexport interface ByteRange {\n  readonly start: number;\n  readonly end: number;\n}\n\n/**\n * Why a range was elided, in two registers: a stable id for counters, and a sentence\n * a human can read in a diff. Law 2 — every elision is explainable — lives here:\n * if you cannot write the sentence, the rule does not ship.\n */\nexport interface ElisionReason {\n  /** Stable machine id, e.g. `'sibling-collapse'`, `'line-window'`. */\n  readonly rule: string;\n  /** e.g. `'collapsed 3 sibling functions'`. Present tense, no trailing period. */\n  readonly explanation: string;\n}\n\n/** One range a planner proposes to remove. Plans are pure data — inspectable and testable. */\nexport interface PlannedElision {\n  readonly range: ByteRange;\n  readonly reason: ElisionReason;\n  /**\n   * The **outline**: the names of the declarations this elision collapses, in source\n   * order — `['parseConfig', 'normalisePath']` — when the planner can read them off a\n   * parse tree. Absent, never empty, when it cannot (a lexical planner sees lines, not\n   * declarations; a run of comments has nothing to name).\n   *\n   * Out of band by design. The names ride on the plan, the applied elision and the\n   * report — never in the marker, whose bytes and priced cost do not move by one byte\n   * (`test/guards/marker-format.test.ts` pins that). It exists because the planner\n   * held the cheapest possible index of what it hid and threw it away at explanation\n   * time, leaving a model on a whole-file task to retrieve hash by hash just to learn\n   * what was behind each marker.\n   */\n  readonly names?: readonly string[];\n}\n\n/**\n * The complete output of a planner: the whole decision, before anything is mutated.\n * A plan can be logged, diffed, snapshot-tested, and rejected without touching the text.\n */\nexport interface ElisionPlan {\n  readonly planner: string;\n  readonly language: DetectedLanguage;\n  readonly elisions: readonly PlannedElision[];\n}\n\n/**\n * The seam through which a planner asks what a marker will cost, in UTF-8 bytes.\n *\n * Marker cost is `apply.ts`'s fact — the applier renders the marker, so only the\n * applier knows its price. Planners need that price for two decisions (profitability:\n * a marker that costs more than it removes grows the output; and budget prediction:\n * which ladder rung actually fits), and before this seam each planner rebuilt the\n * marker machinery privately to measure it — correct, but an inversion. Now\n * `markerPricing()` in `apply.ts` builds the one adapter from the exact builder\n * `applyPlan` will use, and planners ask it. They never guess, and they never render\n * a marker of their own.\n *\n * The price is exact, not an estimate: the cost of the marker this elision would\n * earn, comment leader and all, with a stand-in hash of the real hash's length —\n * marker cost depends on the hash's *length*, never its value.\n */\nexport interface MarkerPricing {\n  /** The exact UTF-8 byte cost of the marker an elision with this reason and size would earn. */\n  costBytes(reason: ElisionReason, elidedBytes: number): number;\n}\n\n/**\n * What the caller hands a planner.\n *\n * Constructed centrally: `createSmelter` (and through it, the CLI) builds the one\n * `PlanInput` per call, including its {@link MarkerPricing} — a caller invoking\n * `planLexical`/`planStructural` directly builds `pricing` with `markerPricing()`\n * from `apply.ts`. A JS caller who omits it gets {@link MissingMarkerPricingError}\n * at plan time, not a guessed cost.\n */\nexport interface PlanInput {\n  readonly text: string;\n  readonly language: DetectedLanguage;\n  /** Soft ceiling for the emitted output, in UTF-8 bytes. Planners aim under it. */\n  readonly budgetBytes: number;\n  /**\n   * What the caller was actually looking for — grep pattern, symbol name, error string.\n   * Planners keep matching regions and collapse around them.\n   */\n  readonly focus?: readonly string[];\n  /**\n   * What a marker costs. Required: a planner that guesses marker cost can plan an\n   * elision that grows the output. See {@link MarkerPricing}; built by\n   * `markerPricing()` in `apply.ts` from the exact builder `applyPlan` will use.\n   */\n  readonly pricing: MarkerPricing;\n  /**\n   * The store's per-rule ledger — how many cuts each rule has made in this store and\n   * how many of them were asked for back — when the store can supply one. Filled\n   * centrally by `createSmelter`, like {@link MarkerPricing}; never guessed.\n   *\n   * **Opt-in data, not a lever.** The shipped planners do not read it: smelt measures\n   * the expansion rate and never thresholds it (`docs/ARCHITECTURE.md` § Decision 4),\n   * so a rule that \"does not pay\" is a fact a *caller's* planner may weigh, and never\n   * a warning smelt authors. This is the deterministic form of \"revert a cut that got\n   * asked back\": the loop is closed as data a planner can read, in one place.\n   */\n  readonly ruleHistory?: readonly RuleLedgerEntry[];\n}\n\n/**\n * A planner decides *what* to remove. It never removes anything itself; `applyPlan`\n * does that. Keeping the decision and the mutation apart is what makes the decision\n * testable in isolation.\n */\nexport interface Planner {\n  readonly id: string;\n  plan(input: PlanInput): Promise<ElisionPlan>;\n}\n\n/** One elision that actually happened, with the receipt needed to undo it. */\nexport interface AppliedElision {\n  /** Content hash of the removed bytes — the key `retrieve()` takes. */\n  readonly hash: string;\n  /** Where the removed bytes were in the *input*. */\n  readonly range: ByteRange;\n  /**\n   * Where the marker sits in the *output*. Law 3 — every elision is reversible — needs\n   * this: {@link Reconstructor} splices stored bytes back over these ranges. Without it,\n   * \"reversible\" would mean parsing markers back out of the text, which is a guess.\n   * This is a fact recorded at the moment of the cut.\n   */\n  readonly outputRange: ByteRange;\n  /** Size of the removed content, in UTF-8 bytes. */\n  readonly bytes: number;\n  readonly reason: ElisionReason;\n  /** The exact marker text substituted into the output. */\n  readonly marker: string;\n  /** The planner's outline, carried verbatim from {@link PlannedElision.names}. */\n  readonly names?: readonly string[];\n}\n\n/**\n * A consumer-supplied counter, so a caller who bills in tokens can *see* tokens.\n *\n * Budgets in smelt's core are UTF-8 bytes, permanently — bytes are the only unit that\n * is computable locally for every model, and they mean the same thing in five years.\n * See `docs/ARCHITECTURE.md` § \"Decision 1\". This hook does not change that: it adds a\n * second, labelled number to the result. The plan is still made in bytes.\n *\n * Both `id` and `unit` are required, and that is a Law 4 decision rather than\n * bookkeeping: a token count is meaningless without naming the tokenizer that produced\n * it. Anthropic's own docs record that Claude 4.7 and later use a newer tokenizer where\n * the same text yields roughly 30% more tokens than on earlier models — so `1,204\n * tokens` is not a fact, and `1,204 tokens (claude-4.7/count_tokens)` is.\n *\n * **This hook does not relax Law 1.** smelt imports no transport and the guard proves\n * that about smelt's own modules; it cannot prove it about a function you hand in. A\n * `count()` that calls an API makes *your* process call an API, from a line in *your*\n * source — exactly the arrangement {@link RerankStage} already describes. `count` is\n * synchronous on purpose: local tokenizers are synchronous, and network clients are not.\n */\nexport interface Measure {\n  /** Names the counter, e.g. `'tiktoken/o200k_base'` or `'claude-4.7/count_tokens'`. */\n  readonly id: string;\n  /** The unit `count()` returns, e.g. `'tokens'`. Printed next to the number. */\n  readonly unit: string;\n  /** Local, synchronous count over the whole string. */\n  count(text: string): number;\n}\n\n/** A second size for a result, in someone else's unit, with the counter named. */\nexport interface MeasuredSize {\n  /** {@link Measure.id} of the counter that produced these numbers. */\n  readonly measure: string;\n  /** {@link Measure.unit}. */\n  readonly unit: string;\n  readonly input: number;\n  readonly output: number;\n}\n\n/** The result of smelting one blob of text. */\nexport interface SmeltResult {\n  readonly text: string;\n  readonly inputBytes: number;\n  readonly outputBytes: number;\n  readonly planner: string;\n  readonly language: DetectedLanguage;\n  readonly elisions: readonly AppliedElision[];\n  /** Present only when the caller supplied a {@link Measure}. Never invented. */\n  readonly measured?: MeasuredSize;\n}\n\n/**\n * Reversibility, as a callable. Takes a {@link SmeltResult} and the store that holds its\n * elided bytes, and returns the original text — byte for byte.\n */\nexport type Reconstructor = (result: SmeltResult, store: ElisionStore) => string;\n\n// ---------------------------------------------------------------------------\n// The store, and the counters that make over-pruning visible\n// ---------------------------------------------------------------------------\n\n/**\n * The numbers that keep smelt honest about itself.\n *\n * Law 3 says elisions are reversible. That is cheap to satisfy and easy to abuse: a\n * compressor that cuts everything is \"reversible\" and useless. The *retrieve rate* is\n * the tell. If the model keeps calling `smelt_retrieve`, smelt cut material the task\n * needed, and the round trip cost more tokens than the elision saved.\n *\n * So: `expansionRate` is not telemetry. It is the metric a caller tunes budgets\n * against, and the only number smelt is willing to have an opinion about — because it\n * measures it locally, per session, on the caller's own traffic.\n */\nexport interface RetrieveStats {\n  /** Distinct blobs put into the store. */\n  readonly elisionsStored: number;\n  /** Total bytes held by the store. */\n  readonly bytesStored: number;\n  /** Every `retrieve()` call, including repeats and misses. */\n  readonly retrieveCalls: number;\n  /** Distinct hashes successfully retrieved at least once. */\n  readonly uniqueRetrieved: number;\n  /** Calls for a hash the store does not hold. Non-zero means a bug, not over-pruning. */\n  readonly misses: number;\n  /**\n   * `uniqueRetrieved / elisionsStored`, or `0` when nothing has been stored.\n   *\n   * Read it as: *what fraction of what smelt hid did the model have to ask for back?*\n   * There is no universally right value, and smelt does not ship a threshold it has\n   * not measured. Rising across a workload is the signal.\n   */\n  readonly expansionRate: number;\n  /**\n   * The one degenerate outcome smelt is willing to name: **every distinct blob it hid\n   * was asked for again.**\n   *\n   * smelt ships no expansion-rate threshold, because a threshold is a policy claim it\n   * has no basis for and the right rate depends on how aggressive a budget the caller\n   * chose — and a library printing warnings into someone else's process is bad manners.\n   * This is not a threshold. At `uniqueRetrieved === elisionsStored` the elision\n   * achieved nothing and cost a round trip: an arithmetic fact, not a preference. What\n   * to do about it is the caller's call.\n   *\n   * `false` for an empty store — nothing was hidden, so nothing was defeated.\n   */\n  readonly allElisionsRetrieved: boolean;\n}\n\n/**\n * One row of a store's **ledger**: a rule, the distinct hashes it put, and how many\n * of those were retrieved at least once. Rows are sorted by rule, so two reads of one\n * store — or of one directory from two processes — render identically.\n *\n * `retrieved === stored` for a rule is the per-rule form of `allElisionsRetrieved`:\n * every cut that rule made was asked for back, an arithmetic fact and never a\n * threshold. What to do about it is the caller's call.\n */\nexport interface RuleLedgerEntry {\n  /** The {@link ElisionReason.rule} id, e.g. `'sibling-collapse'`. */\n  readonly rule: string;\n  /** Distinct hashes put under this rule. */\n  readonly stored: number;\n  /** Of those, distinct hashes retrieved at least once. */\n  readonly retrieved: number;\n}\n\n/**\n * Local, content-addressed storage for elided bytes. No network, no eviction in v1 —\n * evicting is how \"reversible\" quietly becomes \"reversible for a while\".\n */\nexport interface ElisionStore {\n  /**\n   * Store content, returning its hash. Idempotent for identical content.\n   *\n   * `reason` is the rule the content was cut by, when the caller is the applier — it\n   * feeds the store's {@link ledger}. Optional, so a store written before ledgers and\n   * a caller storing bytes for its own reasons both keep working; a put with no\n   * reason is stored and never attributed.\n   */\n  put(content: string, reason?: ElisionReason): string;\n  /** The stored content, or `undefined` if this store never held that hash. */\n  peek(hash: string): string | undefined;\n  /**\n   * The stored content, *counted* as a retrieval. This is what the model's tool calls.\n   *\n   * @throws {UnknownHashError} when the hash is unknown.\n   * @throws {StoreCorruptionError} — {@link DirectoryElisionStore} only — when the\n   *   bytes on disk no longer hash to their own name. Distinct from\n   *   `UnknownHashError` on purpose: \"we hold damaged bytes\" and \"it never existed\"\n   *   are different answers, and a caller that conflates them will report the wrong\n   *   one to its user.\n   *\n   * A {@link DirectoryElisionStore} whose journal cannot be written (a read-only\n   * store directory, a full disk) still returns the bytes — verified bytes are never\n   * withheld over a bookkeeping failure — and surfaces the lost count as a\n   * `process.emitWarning` named `SmeltCounterWriteFailure` instead of throwing. Its\n   * stats go quiet from that point; the retrieval itself succeeded.\n   */\n  retrieve(hash: string): string;\n  /**\n   * Whether this hash can be retrieved — **not** merely whether a slot bearing it\n   * exists. `true` must mean the very next `retrieve(hash)` returns bytes, so a store\n   * that verifies content on read verifies here too and raises its corruption error\n   * rather than answering `true` for bytes it would then refuse. Uncounted: a check is\n   * not the model asking for material back.\n   */\n  has(hash: string): boolean;\n  /** A snapshot of the counters. See {@link RetrieveStats}. */\n  stats(): RetrieveStats;\n  /**\n   * The per-rule ledger, when this store keeps one — both shipped stores do. Optional\n   * so a custom store need not; a consumer that wants the feedback loop implements it\n   * with the shared `ruleLedger()` derivation from `stats.ts`. Uncounted, like\n   * `stats()`: reading the ledger never moves it.\n   */\n  ledger?(): readonly RuleLedgerEntry[];\n}\n\n/**\n * The retrieval tool a consumer exposes to its model. Deliberately not an MCP or\n * provider-specific shape — smelt does not know which SDK you use. The consumer adapts\n * this into its own tool schema; the contract is `hash in, exact bytes out`.\n */\nexport interface RetrieveTool {\n  /** `'smelt_retrieve'`. Stable — consumers hard-code it in prompts. */\n  readonly name: string;\n  /** Prose the consumer can put straight into a tool description. */\n  readonly description: string;\n  /**\n   * JSON-Schema-shaped parameter description, for consumers that want one.\n   *\n   * Strict-mode shaped: `additionalProperties: false` and a `required` naming every\n   * property, so a consumer registering this under OpenAI's structured-outputs strict\n   * mode is not refused at registration. See {@link createRetrieveTool}.\n   */\n  readonly inputSchema: {\n    readonly type: 'object';\n    readonly properties: {\n      readonly hash: { readonly type: 'string'; readonly description: string };\n    };\n    readonly required: readonly ['hash'];\n    readonly additionalProperties: false;\n  };\n  /**\n   * @throws {UnknownHashError} when the hash is unknown.\n   * @throws {StoreCorruptionError} when the backing store holds damaged bytes for\n   *   that hash — see {@link ElisionStore.retrieve}, whose contract this forwards\n   *   verbatim. Surface either to the model as a tool error, never as empty text.\n   */\n  invoke(input: { readonly hash: string }): string;\n}\n\n/**\n * One answer inside a batched retrieval: the exact bytes for a hash, or the store's\n * own refusal for it. A batch never fails as a whole — a model that asked for\n * eighteen blobs and typo'd one must still get the seventeen, and the one refusal\n * must still be the store's distinct error (`UnknownHashError` vs\n * `StoreCorruptionError`), never an empty string standing in for either.\n */\nexport type RetrievedBlock =\n  | { readonly hash: string; readonly text: string }\n  | { readonly hash: string; readonly error: Error };\n\n/**\n * The batched sibling of {@link RetrieveTool}: N hashes in, one {@link RetrievedBlock}\n * per hash out, in the order asked. Additive — `smelt_retrieve` is the frozen wire\n * surface and stays byte-identical beside this.\n *\n * Why it exists is a measured fact, not a convenience: every tool call is a new\n * request, and input tokens are billed per request, so a model expanding eighteen\n * markers one call at a time re-bills its whole transcript eighteen times. One\n * request for eighteen blocks changes what that costs without changing what the\n * expansion rate *means* — each hit inside the batch is journalled exactly as a\n * single call would journal it.\n */\nexport interface RetrieveBatchTool {\n  /** `'smelt_retrieve_batch'`. Stable — consumers hard-code it in prompts. */\n  readonly name: string;\n  /** Prose the consumer can put straight into a tool description. */\n  readonly description: string;\n  /** Strict-mode shaped, like {@link RetrieveTool.inputSchema}. */\n  readonly inputSchema: {\n    readonly type: 'object';\n    readonly properties: {\n      readonly hashes: {\n        readonly type: 'array';\n        readonly items: { readonly type: 'string' };\n        readonly description: string;\n      };\n    };\n    readonly required: readonly ['hashes'];\n    readonly additionalProperties: false;\n  };\n  /**\n   * One block per hash, in order. Never throws for a hash the store refuses — that\n   * refusal rides inside its block — but anything that is not the store's own\n   * refusal (an I/O failure, a bug) still propagates.\n   */\n  invoke(input: { readonly hashes: readonly string[] }): readonly RetrievedBlock[];\n}\n\n// ---------------------------------------------------------------------------\n// Pluggable stages — interfaces in v1, nothing more\n// ---------------------------------------------------------------------------\n\n/** A candidate handed to a {@link RerankStage}: an opaque id plus the text to judge. */\nexport interface RerankCandidate {\n  readonly id: string;\n  readonly text: string;\n}\n\n/** A reranked candidate, most relevant first. `score` is the stage's own scale. */\nexport interface RerankedCandidate extends RerankCandidate {\n  readonly score: number;\n}\n\n/**\n * Relevance reranking — a *seam*, not a feature.\n *\n * Hosted rerankers are good and smelt will never bundle one, because bundling would\n * break Law 1: the moment smelt ships a default reranker, `smelt()` can make a network\n * call that the caller did not ask for and cannot see. A consumer that wants one\n * implements this interface, wires its own key, and owns the fact that its context now\n * leaves the machine. That decision must be legible in the consumer's own source.\n */\nexport interface RerankStage {\n  readonly id: string;\n  /** May make network calls — that is the consumer's choice, made in the consumer's code. */\n  rerank(\n    candidates: readonly RerankCandidate[],\n    query: string,\n  ): Promise<readonly RerankedCandidate[]>;\n}\n\n/**\n * Learned distillation — rewriting content with a model instead of cutting it.\n *\n * Out of v1 for a reason beyond the network: a distilled paragraph cannot satisfy\n * Law 2. \"The model summarised this\" is not an explanation of what was removed, and\n * the removed material is no longer recoverable from the output. If this ever ships,\n * it ships as a stage that stores the original and explains itself in the same terms\n * every other rule does.\n */\nexport interface DistillStage {\n  readonly id: string;\n  distill(text: string, budgetBytes: number): Promise<string>;\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smeltjs/core",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Structure-aware, reversible, offline context optimization for AI coding agents.",
   "license": "Apache-2.0",
   "author": "mong-x",