@smeltjs/core 0.2.0 → 0.4.0

package/dist/ops/inputs.js

@@ -0,0 +1,142 @@
+import { readFileSync, statSync } from 'node:fs';
+import { DEFAULT_STRATEGY } from '../plan/planners.js';
+import { MemoryElisionStore } from '../store.js';
+import { DirectoryElisionStore } from '../store-dir.js';
+/**
+ * Law: **a budget is required, and there is no default.**
+ *
+ * The reasoning is the whole point of the sentence, so it is stated once here rather
+ * than paraphrased per surface: a budget smelt invented would silently decide how much
+ * of the caller's context to throw away, which is a number nobody measured making a
+ * decision nobody made.
+ */
+export function budgetRequired(naming) {
+    return (`${naming.knob} is required, in UTF-8 bytes. There is no default, because a budget ` +
+        `smelt invented would silently decide how much of ${naming.stake}.` +
+        (naming.advice === undefined ? '' : ` ${naming.advice}`));
+}
+/**
+ * Law: **a budget is a whole number of UTF-8 bytes greater than zero.**
+ *
+ * The numeric half only. Getting a candidate *number* out of a surface is that
+ * surface's own lexing and stays there: argv carries strings (`--budget 4kb` is a
+ * malformed number, and `-1` never reaches here because a leading `-` is not a
+ * budget at all), while a JSON tool argument carries whatever type the model sent.
+ * Both then ask this function the same question about the same rule.
+ */
+export function budgetFault(value) {
+    if (!Number.isInteger(value))
+        return 'not-an-integer';
+    if (value <= 0)
+        return 'not-positive';
+    return undefined;
+}
+/**
+ * The sentence for a {@link BudgetFault}, naming the value it rejected.
+ *
+ * `got` is rendered with `JSON.stringify`, which is what both front doors already
+ * printed: a CLI passes the raw argv word and gets it back quoted (`"4kb"`), a tool
+ * passes the raw JSON value and gets numbers bare (`0`) and strings quoted. One
+ * renderer, because a value echoed back in a different shape than it was written is a
+ * value the author has to translate before they can see their own typo.
+ */
+export function budgetMalformed(fault, knob, got) {
+    return fault === 'not-an-integer'
+        ? `${knob} must be a whole number of bytes, got ${JSON.stringify(got)}.`
+        : `${knob} must be greater than zero, got ${JSON.stringify(got)}.`;
+}
+/**
+ * The strategy a run falls back to when neither the caller nor a config names one.
+ *
+ * Re-exported rather than restated: {@link DEFAULT_STRATEGY} is the planner registry's
+ * own fact, and a second spelling here would be the fork this seam exists to close.
+ */
+export { DEFAULT_STRATEGY } from '../plan/planners.js';
+/**
+ * Law: **an explicit strategy wins over a configured one, and `lexical` fills last.**
+ *
+ * Both front doors had this precedence written out, and both spelled the built-in
+ * `'lexical'` inline — so a sixth planner promoted to the default would have been a
+ * two-package edit with no compiler and no test to notice half of it. `chosen` is
+ * whatever the caller said explicitly (a `--strategy` flag, a `"strategy"` argument);
+ * `configured` is what the nearest `smelt.config.json` says. Validating the name is
+ * *not* part of this law — membership in the `PLANNERS` registry (`isStrategy`) is
+ * that, already shared, and the sentence each surface refuses an unknown name with is
+ * its own register: a flag and a JSON argument do not read alike.
+ */
+export function resolveStrategy(chosen, configured) {
+    if (chosen !== undefined)
+        return { strategy: chosen, source: 'flag' };
+    if (configured !== undefined)
+        return { strategy: configured, source: 'config' };
+    return { strategy: DEFAULT_STRATEGY, source: 'builtin' };
+}
+/**
+ * Law: **read a path, or fail naming it.**
+ *
+ * `shownAs` is the path as its author wrote it, which is not always the path opened:
+ * a tool resolves a relative argument against the server's working directory, and
+ * echoing back the absolute result would answer a question nobody asked. The cause is
+ * carried through verbatim — an `EACCES` and an `ENOENT` call for different
+ * responses, and flattening them to "could not read" throws that away.
+ */
+export function readBlob(fullPath, shownAs) {
+    try {
+        return { ok: true, value: readFileSync(fullPath, 'utf8') };
+    }
+    catch (cause) {
+        return { ok: false, refusal: `cannot read "${shownAs}": ${describe(cause)}` };
+    }
+}
+/**
+ * Law: **a tree reader reads a directory, and says so when handed a file.**
+ *
+ * Two distinct refusals, kept distinct: a path that cannot be statted at all
+ * (misspelled, unreadable) and a path that is a perfectly good *file*. The second is
+ * the interesting one — it is a caller who wanted the other verb, so the refusal
+ * names the other verb instead of leaving them to guess which of their two options
+ * was wrong.
+ */
+export function readTree(fullPath, shownAs, naming) {
+    let isDirectory;
+    try {
+        isDirectory = statSync(fullPath).isDirectory();
+    }
+    catch (cause) {
+        return { ok: false, refusal: `cannot read directory "${shownAs}": ${describe(cause)}` };
+    }
+    if (!isDirectory) {
+        return {
+            ok: false,
+            refusal: `"${shownAs}" is not a directory. ${naming.tree} reads a whole tree; for one ` +
+                `file, use ${naming.file}.`,
+        };
+    }
+    return { ok: true, value: fullPath };
+}
+/**
+ * Law: **a store decision, opened.**
+ *
+ * The *decision* — which kind, and where — is `configuredStore()` in `cli/config.ts`,
+ * one reading of one config key. This is the other half: turning that decision into a
+ * live {@link ElisionStore}. It was the missing half. The MCP package needed exactly
+ * this and could not import it, so it re-derived the decision *and* the construction
+ * from the config keys directly, and a second reading of `store.kind` came into
+ * existence in another package.
+ *
+ * What each front door does with a memory store stays the front door's: `smelt
+ * retrieve` and `smelt stats` refuse one (a marker's hash from an earlier run names
+ * bytes no memory store ever held), while the MCP server accepts one and says so at
+ * the moment it bites. That divergence is deliberate and documented; it is a policy
+ * about a store, not a fact about opening one.
+ */
+export function openStore(decision) {
+    return decision.kind === 'memory'
+        ? new MemoryElisionStore()
+        : new DirectoryElisionStore(decision.path);
+}
+/** A thrown cause as one line, without pretending an unknown throw was an Error. */
+function describe(cause) {
+    return cause instanceof Error ? cause.message : String(cause);
+}
+//# sourceMappingURL=inputs.js.map

package/dist/ops/inputs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inputs.js","sourceRoot":"","sources":["../../src/ops/inputs.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAGjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAEvD,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAiExD;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAAC,MAAoB;IACjD,OAAO,CACL,GAAG,MAAM,CAAC,IAAI,sEAAsE;QACpF,oDAAoD,MAAM,CAAC,KAAK,GAAG;QACnE,CAAC,MAAM,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC,CACzD,CAAC;AACJ,CAAC;AAKD;;;;;;;;GAQG;AACH,MAAM,UAAU,WAAW,CAAC,KAAa;IACvC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC;QAAE,OAAO,gBAAgB,CAAC;IACtD,IAAI,KAAK,IAAI,CAAC;QAAE,OAAO,cAAc,CAAC;IACtC,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,CAAC,KAAkB,EAAE,IAAY,EAAE,GAAY;IAC5E,OAAO,KAAK,KAAK,gBAAgB;QAC/B,CAAC,CAAC,GAAG,IAAI,yCAAyC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG;QACxE,CAAC,CAAC,GAAG,IAAI,mCAAmC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC;AACvE,CAAC;AAED;;;;;GAKG;AACH,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAWvD;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,eAAe,CAC7B,MAA4B,EAC5B,UAAgC;IAEhC,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;IACtE,IAAI,UAAU,KAAK,SAAS;QAAE,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;IAChF,OAAO,EAAE,QAAQ,EAAE,gBAAgB,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;AAC3D,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,QAAQ,CAAC,QAAgB,EAAE,OAAe;IACxD,IAAI,CAAC;QACH,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,YAAY,CAAC,QAAQ,EAAE,MAAM,CAAC,EAAE,CAAC;IAC7D,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,gBAAgB,OAAO,MAAM,QAAQ,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC;IAChF,CAAC;AACH,CAAC;AAUD;;;;;;;;GAQG;AACH,MAAM,UAAU,QAAQ,CAAC,QAAgB,EAAE,OAAe,EAAE,MAAkB;IAC5E,IAAI,WAAoB,CAAC;IACzB,IAAI,CAAC;QACH,WAAW,GAAG,QAAQ,CAAC,QAAQ,CAAC,CAAC,WAAW,EAAE,CAAC;IACjD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,0BAA0B,OAAO,MAAM,QAAQ,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC;IAC1F,CAAC;IACD,IAAI,CAAC,WAAW,EAAE,CAAC;QACjB,OAAO;YACL,EAAE,EAAE,KAAK;YACT,OAAO,EACL,IAAI,OAAO,yBAAyB,MAAM,CAAC,IAAI,+BAA+B;gBAC9E,aAAa,MAAM,CAAC,IAAI,GAAG;SAC9B,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC;AACvC,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,SAAS,CAAC,QAAyB;IACjD,OAAO,QAAQ,CAAC,IAAI,KAAK,QAAQ;QAC/B,CAAC,CAAC,IAAI,kBAAkB,EAAE;QAC1B,CAAC,CAAC,IAAI,qBAAqB,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;AAC/C,CAAC;AAED,oFAAoF;AACpF,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAChE,CAAC","sourcesContent":["import { readFileSync, statSync } from 'node:fs';\n\nimport type { ConfiguredStore } from '../cli/config.ts';\nimport { DEFAULT_STRATEGY } from '../plan/planners.ts';\nimport type { Strategy } from '../plan/planners.ts';\nimport { MemoryElisionStore } from '../store.ts';\nimport { DirectoryElisionStore } from '../store-dir.ts';\nimport type { ElisionStore } from '../types.ts';\n\n/**\n * The laws an operation's input must satisfy — stated once, for every front door.\n *\n * Each rule here was, until this seam existed, written twice: once in a\n * `cli/subcommands/*` verb and once in the MCP server's tool handlers. Two copies of a\n * law is two laws, and the copies had already begun to differ — the `smelt` CLI and\n * the `smelt_file` tool refuse a missing budget with the same reasoning in two\n * separately-maintained sentences, and only one of them was ever edited at a time.\n *\n * **What is shared and what is not.** A law has two halves, and only one of them can\n * be shared honestly:\n *\n *   - the **rule and its reasoning** — that a budget is a whole number of bytes\n *     greater than zero, that there is no default and why, that a tree-reader refuses\n *     a file, that a strategy falls back to `lexical` last. That half lives here.\n *   - the **naming** — a CLI spells its budget `--budget` and points at\n *     `smelt.config.json`; a tool spells it `\"budgetBytes\"` and points at nothing.\n *     That half is the front door's own, and every function here takes it as an\n *     argument rather than guessing.\n *\n * Nothing here throws. The two front doors refuse in different currencies — the CLI\n * with a {@link CliUsageError} that exits 2, the MCP server with a tool-level error\n * carrying `isError: true` — and a shared law that threw would force one of them to\n * catch and re-wrap the other's error type, which is how an exit code changes by\n * accident. So a law that can refuse returns a {@link Ruling}: the value, or the one\n * sentence that refuses it, for the caller to throw in its own currency.\n *\n * Nothing here *finds* a `smelt.config.json` either. Config discovery is a CLI\n * concern by design (see `cli/config.ts`); {@link openStore} takes a decision that\n * has already been made and opens it, so no library call's behaviour depends on the\n * directory it was invoked from.\n */\n\n/**\n * The answer to a law that can refuse: the value, or the one sentence refusing it.\n *\n * Deliberately not an exception — see the module comment. The refusal is the\n * complete sentence *minus* whatever prefix the front door puts on its own errors\n * (`smelt: ` for the CLI, the tool name for MCP), because that prefix is naming, and\n * naming belongs to the caller.\n */\nexport type Ruling<T> =\n  { readonly ok: true; readonly value: T } | { readonly ok: false; readonly refusal: string };\n\n/** How one front door spells the budget it is refusing, and what it points at next. */\nexport interface BudgetNaming {\n  /** The knob, as this surface spells it: `--budget`, `\"budgetBytes\"`. */\n  readonly knob: string;\n  /**\n   * What a budget smelt invented would silently decide — the back half of the\n   * no-default sentence. `'your context to throw away'` for a blob run, `'the map to\n   * leave out'` for a tree.\n   */\n  readonly stake: string;\n  /**\n   * Anything this surface adds after the law: where else the value can come from, and\n   * an example. Appended after a single space. The CLI names `defaultBudgetBytes` and\n   * `smelt init` here; a tool whose schema already says `required` adds nothing.\n   */\n  readonly advice?: string;\n}\n\n/**\n * Law: **a budget is required, and there is no default.**\n *\n * The reasoning is the whole point of the sentence, so it is stated once here rather\n * than paraphrased per surface: a budget smelt invented would silently decide how much\n * of the caller's context to throw away, which is a number nobody measured making a\n * decision nobody made.\n */\nexport function budgetRequired(naming: BudgetNaming): string {\n  return (\n    `${naming.knob} is required, in UTF-8 bytes. There is no default, because a budget ` +\n    `smelt invented would silently decide how much of ${naming.stake}.` +\n    (naming.advice === undefined ? '' : ` ${naming.advice}`)\n  );\n}\n\n/** The two ways a budget that *was* given can still be wrong. See {@link budgetFault}. */\nexport type BudgetFault = 'not-an-integer' | 'not-positive';\n\n/**\n * Law: **a budget is a whole number of UTF-8 bytes greater than zero.**\n *\n * The numeric half only. Getting a candidate *number* out of a surface is that\n * surface's own lexing and stays there: argv carries strings (`--budget 4kb` is a\n * malformed number, and `-1` never reaches here because a leading `-` is not a\n * budget at all), while a JSON tool argument carries whatever type the model sent.\n * Both then ask this function the same question about the same rule.\n */\nexport function budgetFault(value: number): BudgetFault | undefined {\n  if (!Number.isInteger(value)) return 'not-an-integer';\n  if (value <= 0) return 'not-positive';\n  return undefined;\n}\n\n/**\n * The sentence for a {@link BudgetFault}, naming the value it rejected.\n *\n * `got` is rendered with `JSON.stringify`, which is what both front doors already\n * printed: a CLI passes the raw argv word and gets it back quoted (`\"4kb\"`), a tool\n * passes the raw JSON value and gets numbers bare (`0`) and strings quoted. One\n * renderer, because a value echoed back in a different shape than it was written is a\n * value the author has to translate before they can see their own typo.\n */\nexport function budgetMalformed(fault: BudgetFault, knob: string, got: unknown): string {\n  return fault === 'not-an-integer'\n    ? `${knob} must be a whole number of bytes, got ${JSON.stringify(got)}.`\n    : `${knob} must be greater than zero, got ${JSON.stringify(got)}.`;\n}\n\n/**\n * The strategy a run falls back to when neither the caller nor a config names one.\n *\n * Re-exported rather than restated: {@link DEFAULT_STRATEGY} is the planner registry's\n * own fact, and a second spelling here would be the fork this seam exists to close.\n */\nexport { DEFAULT_STRATEGY } from '../plan/planners.ts';\n\n/** Where a resolved strategy came from — the receipt {@link resolveStrategy} returns. */\nexport type StrategySource = 'flag' | 'config' | 'builtin';\n\n/** A strategy, with the provenance that explains it. */\nexport interface ResolvedStrategy {\n  readonly strategy: Strategy;\n  readonly source: StrategySource;\n}\n\n/**\n * Law: **an explicit strategy wins over a configured one, and `lexical` fills last.**\n *\n * Both front doors had this precedence written out, and both spelled the built-in\n * `'lexical'` inline — so a sixth planner promoted to the default would have been a\n * two-package edit with no compiler and no test to notice half of it. `chosen` is\n * whatever the caller said explicitly (a `--strategy` flag, a `\"strategy\"` argument);\n * `configured` is what the nearest `smelt.config.json` says. Validating the name is\n * *not* part of this law — membership in the `PLANNERS` registry (`isStrategy`) is\n * that, already shared, and the sentence each surface refuses an unknown name with is\n * its own register: a flag and a JSON argument do not read alike.\n */\nexport function resolveStrategy(\n  chosen: Strategy | undefined,\n  configured: Strategy | undefined,\n): ResolvedStrategy {\n  if (chosen !== undefined) return { strategy: chosen, source: 'flag' };\n  if (configured !== undefined) return { strategy: configured, source: 'config' };\n  return { strategy: DEFAULT_STRATEGY, source: 'builtin' };\n}\n\n/**\n * Law: **read a path, or fail naming it.**\n *\n * `shownAs` is the path as its author wrote it, which is not always the path opened:\n * a tool resolves a relative argument against the server's working directory, and\n * echoing back the absolute result would answer a question nobody asked. The cause is\n * carried through verbatim — an `EACCES` and an `ENOENT` call for different\n * responses, and flattening them to \"could not read\" throws that away.\n */\nexport function readBlob(fullPath: string, shownAs: string): Ruling<string> {\n  try {\n    return { ok: true, value: readFileSync(fullPath, 'utf8') };\n  } catch (cause) {\n    return { ok: false, refusal: `cannot read \"${shownAs}\": ${describe(cause)}` };\n  }\n}\n\n/** How one front door names the tree verb and its single-file sibling. */\nexport interface TreeNaming {\n  /** The whole-tree reader, as this surface spells it: `map`, `repo_map`. */\n  readonly tree: string;\n  /** Where to go for one file instead: `` `smelt <file>` ``, `smelt_file`. */\n  readonly file: string;\n}\n\n/**\n * Law: **a tree reader reads a directory, and says so when handed a file.**\n *\n * Two distinct refusals, kept distinct: a path that cannot be statted at all\n * (misspelled, unreadable) and a path that is a perfectly good *file*. The second is\n * the interesting one — it is a caller who wanted the other verb, so the refusal\n * names the other verb instead of leaving them to guess which of their two options\n * was wrong.\n */\nexport function readTree(fullPath: string, shownAs: string, naming: TreeNaming): Ruling<string> {\n  let isDirectory: boolean;\n  try {\n    isDirectory = statSync(fullPath).isDirectory();\n  } catch (cause) {\n    return { ok: false, refusal: `cannot read directory \"${shownAs}\": ${describe(cause)}` };\n  }\n  if (!isDirectory) {\n    return {\n      ok: false,\n      refusal:\n        `\"${shownAs}\" is not a directory. ${naming.tree} reads a whole tree; for one ` +\n        `file, use ${naming.file}.`,\n    };\n  }\n  return { ok: true, value: fullPath };\n}\n\n/**\n * Law: **a store decision, opened.**\n *\n * The *decision* — which kind, and where — is `configuredStore()` in `cli/config.ts`,\n * one reading of one config key. This is the other half: turning that decision into a\n * live {@link ElisionStore}. It was the missing half. The MCP package needed exactly\n * this and could not import it, so it re-derived the decision *and* the construction\n * from the config keys directly, and a second reading of `store.kind` came into\n * existence in another package.\n *\n * What each front door does with a memory store stays the front door's: `smelt\n * retrieve` and `smelt stats` refuse one (a marker's hash from an earlier run names\n * bytes no memory store ever held), while the MCP server accepts one and says so at\n * the moment it bites. That divergence is deliberate and documented; it is a policy\n * about a store, not a fact about opening one.\n */\nexport function openStore(decision: ConfiguredStore): ElisionStore {\n  return decision.kind === 'memory'\n    ? new MemoryElisionStore()\n    : new DirectoryElisionStore(decision.path);\n}\n\n/** A thrown cause as one line, without pretending an unknown throw was an Error. */\nfunction describe(cause: unknown): string {\n  return cause instanceof Error ? cause.message : String(cause);\n}\n"]}

package/dist/ops/verbs.d.ts

@@ -0,0 +1,136 @@
+import type { RepoMap } from '../repomap/map.ts';
+import type { Strategy } from '../plan/planners.ts';
+import type { DetectedLanguage, ElisionStore, RetrieveStats, SmeltResult } from '../types.ts';
+/**
+ * The four verbs, as library functions over already-resolved inputs.
+ *
+ * This is the seam that sits **below both front doors**. The `smelt` CLI and the
+ * `@smeltjs/mcp` server are the same four operations wearing two different coats, and
+ * before this file existed each of them owned a full copy of the middle: build a
+ * smelter from a strategy and a store, call it, hand the totals to a report; stat a
+ * directory, build a map, render its warnings; retrieve one hash; read the counters.
+ * The library exported the pieces, so both copies were *correct* — and both had to be
+ * edited, in two packages, for one change to how a verb runs.
+ *
+ * What an op takes is already resolved: a budget that survived its law, a strategy
+ * that won its precedence, a store that has been opened, text that has been read. What
+ * an op returns is data — the smelted text and the values a report needs, a
+ * {@link RepoMap}, bytes, counters. An op never sees argv, never writes to a stream,
+ * never returns an exit code, and knows nothing about `CallToolResult`. Those are the
+ * adapters' four jobs, and keeping them out here is what makes the same operation
+ * testable once instead of twice.
+ *
+ * The division of labour, in one line: **a front door parses and resolves, an op runs,
+ * a front door renders.**
+ */
+/** One blob to smelt, fully resolved. */
+export interface SmeltBlobOp {
+    /** The text itself. Reading a file into it is the front door's job (`readBlob`). */
+    readonly text: string;
+    /** What to call the input in a report: a path, `'<stdin>'`, `'<text>'`. */
+    readonly source: string;
+    /** UTF-8 bytes. Already past the budget law — see `ops/inputs.ts`. */
+    readonly budgetBytes: number;
+    /** Already past its precedence — see `resolveStrategy` in `ops/inputs.ts`. */
+    readonly strategy: Strategy;
+    /**
+     * Where elided bytes go. Optional only so a caller with nothing to persist gets the
+     * library's own default (a fresh {@link MemoryElisionStore}); a front door that read
+     * a config opens the store it decided on and passes it.
+     */
+    readonly store?: ElisionStore;
+    /** The path the text came from, for language detection. Absent for a pasted blob. */
+    readonly path?: string;
+    /** Overrides detection entirely, when a surface offers that. */
+    readonly language?: DetectedLanguage;
+    /** What the task is about. Empty and absent mean the same thing to every planner. */
+    readonly focus?: readonly string[];
+}
+/**
+ * What one smelt run produced.
+ *
+ * The fields a report needs are the fields `formatReport` takes, deliberately: an op
+ * returns exactly the values the render step reads off, so no front door assembles a
+ * report input by hand and no front door counts a byte itself. (`formatReport(outcome)`
+ * typechecks as written.) The store comes back too, because the `--json` envelope has
+ * to `peek` at the bytes the run just stored, and a caller that passed no store never
+ * had a handle on the one the library made.
+ */
+export interface SmeltBlobOutcome {
+    readonly result: SmeltResult;
+    /** What the input was called. Echoed back so a report never re-derives it. */
+    readonly source: string;
+    /** The budget the run was given, so a report can say when it was missed. */
+    readonly budgetBytes: number;
+    /** The exact text that was smelted. */
+    readonly inputText: string;
+    /** The store the run actually used — the one passed in, or the library's default. */
+    readonly store: ElisionStore;
+}
+/**
+ * Verb: **cut one blob to a budget.**
+ *
+ * Every refusal the library can raise passes straight through — a `structural` run on
+ * a language with no bundled grammar throws `GrammarUnavailableError` here exactly as
+ * it does anywhere else, because a planner that quietly fell back to line windows
+ * would be undetectable from outside. Coming back *over budget* is not a refusal and
+ * not an error: the plan is returned as it came back, and whether that deserves a
+ * non-zero exit code is a question only a front door can answer.
+ */
+export declare function smeltBlob(op: SmeltBlobOp): Promise<SmeltBlobOutcome>;
+/** One tree to map, fully resolved. */
+export interface MapTreeOp {
+    /** A directory. Proving it is one is the front door's job (`readTree`). */
+    readonly root: string;
+    /** UTF-8 bytes. The map fits itself to this by construction. */
+    readonly budgetBytes: number;
+    readonly focus?: readonly string[];
+    /** Replaces the built-in ignore list when present. */
+    readonly ignore?: readonly string[];
+    /** Only when present does the map write anything to disk. */
+    readonly cacheDir?: string;
+}
+/**
+ * Verb: **map a whole tree inside a budget.**
+ *
+ * Returns the {@link RepoMap} itself — the map *is* the data, warnings and cache
+ * counts included, and wrapping it in an outcome struct would only give two front
+ * doors a second place to disagree about what a map is. Nothing is elided, stored or
+ * reversible, so there is nothing here to retrieve and no over-budget case to report.
+ */
+export declare function mapTree(op: MapTreeOp): Promise<RepoMap>;
+/** One hash to turn back into bytes. */
+export interface RetrieveBytesOp {
+    /** The store holding them — already opened. See `openStore` in `ops/inputs.ts`. */
+    readonly store: ElisionStore;
+    /** The hash exactly as a marker printed it. Validated by the store, not here. */
+    readonly hash: string;
+}
+/**
+ * Verb: **the counted read.**
+ *
+ * Thin on purpose, and named anyway: this is the expansion rate moving. `retrieve()`
+ * journals the hit, so a shell user typing `smelt retrieve` and a model calling
+ * `smelt_retrieve` move the same counter through the same call — which is the only
+ * reason the number means anything. The exact original bytes come back, nothing
+ * appended and nothing re-encoded, and an unknown or damaged hash throws the store's
+ * own distinct error rather than an empty string.
+ *
+ * @throws {UnknownHashError} for a hash the store never held.
+ * @throws {StoreCorruptionError} for bytes that no longer hash to their name.
+ */
+export declare function retrieveBytes(op: RetrieveBytesOp): string;
+/** One store to read the counters off. */
+export interface ReadCountersOp {
+    readonly store: ElisionStore;
+}
+/**
+ * Verb: **the uncounted read.**
+ *
+ * The sibling of {@link retrieveBytes}, and the asymmetry is the point: `stats()`
+ * folds the journal without writing to it, so watching the expansion rate can never
+ * move it. An observer that inflated its own metric would make the honest signal
+ * dishonest.
+ */
+export declare function readCounters(op: ReadCountersOp): RetrieveStats;
+//# sourceMappingURL=verbs.d.ts.map

package/dist/ops/verbs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verbs.d.ts","sourceRoot":"","sources":["../../src/ops/verbs.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAEjD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,KAAK,EAAE,gBAAgB,EAAE,YAAY,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE9F;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,yCAAyC;AACzC,MAAM,WAAW,WAAW;IAC1B,oFAAoF;IACpF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,sEAAsE;IACtE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,8EAA8E;IAC9E,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,YAAY,CAAC;IAC9B,qFAAqF;IACrF,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,gEAAgE;IAChE,QAAQ,CAAC,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IACrC,qFAAqF;IACrF,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,8EAA8E;IAC9E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,4EAA4E;IAC5E,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,uCAAuC;IACvC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,qFAAqF;IACrF,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;CAC9B;AAED;;;;;;;;;GASG;AACH,wBAAsB,SAAS,CAAC,EAAE,EAAE,WAAW,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAkB1E;AAED,uCAAuC;AACvC,MAAM,WAAW,SAAS;IACxB,2EAA2E;IAC3E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,gEAAgE;IAChE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,sDAAsD;IACtD,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,6DAA6D;IAC7D,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;GAOG;AACH,wBAAgB,OAAO,CAAC,EAAE,EAAE,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC,CAQvD;AAED,wCAAwC;AACxC,MAAM,WAAW,eAAe;IAC9B,mFAAmF;IACnF,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B,iFAAiF;IACjF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,EAAE,EAAE,eAAe,GAAG,MAAM,CAEzD;AAED,0CAA0C;AAC1C,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;CAC9B;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,EAAE,EAAE,cAAc,GAAG,aAAa,CAE9D","sourcesContent":["import { buildRepoMap } from '../repomap/map.ts';\nimport type { RepoMap } from '../repomap/map.ts';\nimport { createSmelter } from '../smelter.ts';\nimport type { Strategy } from '../plan/planners.ts';\nimport type { DetectedLanguage, ElisionStore, RetrieveStats, SmeltResult } from '../types.ts';\n\n/**\n * The four verbs, as library functions over already-resolved inputs.\n *\n * This is the seam that sits **below both front doors**. The `smelt` CLI and the\n * `@smeltjs/mcp` server are the same four operations wearing two different coats, and\n * before this file existed each of them owned a full copy of the middle: build a\n * smelter from a strategy and a store, call it, hand the totals to a report; stat a\n * directory, build a map, render its warnings; retrieve one hash; read the counters.\n * The library exported the pieces, so both copies were *correct* — and both had to be\n * edited, in two packages, for one change to how a verb runs.\n *\n * What an op takes is already resolved: a budget that survived its law, a strategy\n * that won its precedence, a store that has been opened, text that has been read. What\n * an op returns is data — the smelted text and the values a report needs, a\n * {@link RepoMap}, bytes, counters. An op never sees argv, never writes to a stream,\n * never returns an exit code, and knows nothing about `CallToolResult`. Those are the\n * adapters' four jobs, and keeping them out here is what makes the same operation\n * testable once instead of twice.\n *\n * The division of labour, in one line: **a front door parses and resolves, an op runs,\n * a front door renders.**\n */\n\n/** One blob to smelt, fully resolved. */\nexport interface SmeltBlobOp {\n  /** The text itself. Reading a file into it is the front door's job (`readBlob`). */\n  readonly text: string;\n  /** What to call the input in a report: a path, `'<stdin>'`, `'<text>'`. */\n  readonly source: string;\n  /** UTF-8 bytes. Already past the budget law — see `ops/inputs.ts`. */\n  readonly budgetBytes: number;\n  /** Already past its precedence — see `resolveStrategy` in `ops/inputs.ts`. */\n  readonly strategy: Strategy;\n  /**\n   * Where elided bytes go. Optional only so a caller with nothing to persist gets the\n   * library's own default (a fresh {@link MemoryElisionStore}); a front door that read\n   * a config opens the store it decided on and passes it.\n   */\n  readonly store?: ElisionStore;\n  /** The path the text came from, for language detection. Absent for a pasted blob. */\n  readonly path?: string;\n  /** Overrides detection entirely, when a surface offers that. */\n  readonly language?: DetectedLanguage;\n  /** What the task is about. Empty and absent mean the same thing to every planner. */\n  readonly focus?: readonly string[];\n}\n\n/**\n * What one smelt run produced.\n *\n * The fields a report needs are the fields `formatReport` takes, deliberately: an op\n * returns exactly the values the render step reads off, so no front door assembles a\n * report input by hand and no front door counts a byte itself. (`formatReport(outcome)`\n * typechecks as written.) The store comes back too, because the `--json` envelope has\n * to `peek` at the bytes the run just stored, and a caller that passed no store never\n * had a handle on the one the library made.\n */\nexport interface SmeltBlobOutcome {\n  readonly result: SmeltResult;\n  /** What the input was called. Echoed back so a report never re-derives it. */\n  readonly source: string;\n  /** The budget the run was given, so a report can say when it was missed. */\n  readonly budgetBytes: number;\n  /** The exact text that was smelted. */\n  readonly inputText: string;\n  /** The store the run actually used — the one passed in, or the library's default. */\n  readonly store: ElisionStore;\n}\n\n/**\n * Verb: **cut one blob to a budget.**\n *\n * Every refusal the library can raise passes straight through — a `structural` run on\n * a language with no bundled grammar throws `GrammarUnavailableError` here exactly as\n * it does anywhere else, because a planner that quietly fell back to line windows\n * would be undetectable from outside. Coming back *over budget* is not a refusal and\n * not an error: the plan is returned as it came back, and whether that deserves a\n * non-zero exit code is a question only a front door can answer.\n */\nexport async function smeltBlob(op: SmeltBlobOp): Promise<SmeltBlobOutcome> {\n  const smelter = createSmelter({\n    strategy: op.strategy,\n    ...(op.store === undefined ? {} : { store: op.store }),\n  });\n  const result = await smelter.smelt(op.text, {\n    budgetBytes: op.budgetBytes,\n    ...(op.path === undefined ? {} : { path: op.path }),\n    ...(op.language === undefined ? {} : { language: op.language }),\n    ...(op.focus === undefined || op.focus.length === 0 ? {} : { focus: op.focus }),\n  });\n  return {\n    result,\n    source: op.source,\n    budgetBytes: op.budgetBytes,\n    inputText: op.text,\n    store: smelter.store,\n  };\n}\n\n/** One tree to map, fully resolved. */\nexport interface MapTreeOp {\n  /** A directory. Proving it is one is the front door's job (`readTree`). */\n  readonly root: string;\n  /** UTF-8 bytes. The map fits itself to this by construction. */\n  readonly budgetBytes: number;\n  readonly focus?: readonly string[];\n  /** Replaces the built-in ignore list when present. */\n  readonly ignore?: readonly string[];\n  /** Only when present does the map write anything to disk. */\n  readonly cacheDir?: string;\n}\n\n/**\n * Verb: **map a whole tree inside a budget.**\n *\n * Returns the {@link RepoMap} itself — the map *is* the data, warnings and cache\n * counts included, and wrapping it in an outcome struct would only give two front\n * doors a second place to disagree about what a map is. Nothing is elided, stored or\n * reversible, so there is nothing here to retrieve and no over-budget case to report.\n */\nexport function mapTree(op: MapTreeOp): Promise<RepoMap> {\n  return buildRepoMap({\n    root: op.root,\n    budgetBytes: op.budgetBytes,\n    ...(op.focus === undefined || op.focus.length === 0 ? {} : { focus: op.focus }),\n    ...(op.ignore === undefined || op.ignore.length === 0 ? {} : { ignore: op.ignore }),\n    ...(op.cacheDir === undefined ? {} : { cacheDir: op.cacheDir }),\n  });\n}\n\n/** One hash to turn back into bytes. */\nexport interface RetrieveBytesOp {\n  /** The store holding them — already opened. See `openStore` in `ops/inputs.ts`. */\n  readonly store: ElisionStore;\n  /** The hash exactly as a marker printed it. Validated by the store, not here. */\n  readonly hash: string;\n}\n\n/**\n * Verb: **the counted read.**\n *\n * Thin on purpose, and named anyway: this is the expansion rate moving. `retrieve()`\n * journals the hit, so a shell user typing `smelt retrieve` and a model calling\n * `smelt_retrieve` move the same counter through the same call — which is the only\n * reason the number means anything. The exact original bytes come back, nothing\n * appended and nothing re-encoded, and an unknown or damaged hash throws the store's\n * own distinct error rather than an empty string.\n *\n * @throws {UnknownHashError} for a hash the store never held.\n * @throws {StoreCorruptionError} for bytes that no longer hash to their name.\n */\nexport function retrieveBytes(op: RetrieveBytesOp): string {\n  return op.store.retrieve(op.hash);\n}\n\n/** One store to read the counters off. */\nexport interface ReadCountersOp {\n  readonly store: ElisionStore;\n}\n\n/**\n * Verb: **the uncounted read.**\n *\n * The sibling of {@link retrieveBytes}, and the asymmetry is the point: `stats()`\n * folds the journal without writing to it, so watching the expansion rate can never\n * move it. An observer that inflated its own metric would make the honest signal\n * dishonest.\n */\nexport function readCounters(op: ReadCountersOp): RetrieveStats {\n  return op.store.stats();\n}\n"]}

package/dist/ops/verbs.js

@@ -0,0 +1,76 @@
+import { buildRepoMap } from '../repomap/map.js';
+import { createSmelter } from '../smelter.js';
+/**
+ * Verb: **cut one blob to a budget.**
+ *
+ * Every refusal the library can raise passes straight through — a `structural` run on
+ * a language with no bundled grammar throws `GrammarUnavailableError` here exactly as
+ * it does anywhere else, because a planner that quietly fell back to line windows
+ * would be undetectable from outside. Coming back *over budget* is not a refusal and
+ * not an error: the plan is returned as it came back, and whether that deserves a
+ * non-zero exit code is a question only a front door can answer.
+ */
+export async function smeltBlob(op) {
+    const smelter = createSmelter({
+        strategy: op.strategy,
+        ...(op.store === undefined ? {} : { store: op.store }),
+    });
+    const result = await smelter.smelt(op.text, {
+        budgetBytes: op.budgetBytes,
+        ...(op.path === undefined ? {} : { path: op.path }),
+        ...(op.language === undefined ? {} : { language: op.language }),
+        ...(op.focus === undefined || op.focus.length === 0 ? {} : { focus: op.focus }),
+    });
+    return {
+        result,
+        source: op.source,
+        budgetBytes: op.budgetBytes,
+        inputText: op.text,
+        store: smelter.store,
+    };
+}
+/**
+ * Verb: **map a whole tree inside a budget.**
+ *
+ * Returns the {@link RepoMap} itself — the map *is* the data, warnings and cache
+ * counts included, and wrapping it in an outcome struct would only give two front
+ * doors a second place to disagree about what a map is. Nothing is elided, stored or
+ * reversible, so there is nothing here to retrieve and no over-budget case to report.
+ */
+export function mapTree(op) {
+    return buildRepoMap({
+        root: op.root,
+        budgetBytes: op.budgetBytes,
+        ...(op.focus === undefined || op.focus.length === 0 ? {} : { focus: op.focus }),
+        ...(op.ignore === undefined || op.ignore.length === 0 ? {} : { ignore: op.ignore }),
+        ...(op.cacheDir === undefined ? {} : { cacheDir: op.cacheDir }),
+    });
+}
+/**
+ * Verb: **the counted read.**
+ *
+ * Thin on purpose, and named anyway: this is the expansion rate moving. `retrieve()`
+ * journals the hit, so a shell user typing `smelt retrieve` and a model calling
+ * `smelt_retrieve` move the same counter through the same call — which is the only
+ * reason the number means anything. The exact original bytes come back, nothing
+ * appended and nothing re-encoded, and an unknown or damaged hash throws the store's
+ * own distinct error rather than an empty string.
+ *
+ * @throws {UnknownHashError} for a hash the store never held.
+ * @throws {StoreCorruptionError} for bytes that no longer hash to their name.
+ */
+export function retrieveBytes(op) {
+    return op.store.retrieve(op.hash);
+}
+/**
+ * Verb: **the uncounted read.**
+ *
+ * The sibling of {@link retrieveBytes}, and the asymmetry is the point: `stats()`
+ * folds the journal without writing to it, so watching the expansion rate can never
+ * move it. An observer that inflated its own metric would make the honest signal
+ * dishonest.
+ */
+export function readCounters(op) {
+    return op.store.stats();
+}
+//# sourceMappingURL=verbs.js.map

package/dist/ops/verbs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verbs.js","sourceRoot":"","sources":["../../src/ops/verbs.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEjD,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAyE9C;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,EAAe;IAC7C,MAAM,OAAO,GAAG,aAAa,CAAC;QAC5B,QAAQ,EAAE,EAAE,CAAC,QAAQ;QACrB,GAAG,CAAC,EAAE,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,EAAE,CAAC;KACvD,CAAC,CAAC;IACH,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE;QAC1C,WAAW,EAAE,EAAE,CAAC,WAAW;QAC3B,GAAG,CAAC,EAAE,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC;QACnD,GAAG,CAAC,EAAE,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,EAAE,CAAC,QAAQ,EAAE,CAAC;QAC/D,GAAG,CAAC,EAAE,CAAC,KAAK,KAAK,SAAS,IAAI,EAAE,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,EAAE,CAAC;KAChF,CAAC,CAAC;IACH,OAAO;QACL,MAAM;QACN,MAAM,EAAE,EAAE,CAAC,MAAM;QACjB,WAAW,EAAE,EAAE,CAAC,WAAW;QAC3B,SAAS,EAAE,EAAE,CAAC,IAAI;QAClB,KAAK,EAAE,OAAO,CAAC,KAAK;KACrB,CAAC;AACJ,CAAC;AAeD;;;;;;;GAOG;AACH,MAAM,UAAU,OAAO,CAAC,EAAa;IACnC,OAAO,YAAY,CAAC;QAClB,IAAI,EAAE,EAAE,CAAC,IAAI;QACb,WAAW,EAAE,EAAE,CAAC,WAAW;QAC3B,GAAG,CAAC,EAAE,CAAC,KAAK,KAAK,SAAS,IAAI,EAAE,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,EAAE,CAAC;QAC/E,GAAG,CAAC,EAAE,CAAC,MAAM,KAAK,SAAS,IAAI,EAAE,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC;QACnF,GAAG,CAAC,EAAE,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,EAAE,CAAC,QAAQ,EAAE,CAAC;KAChE,CAAC,CAAC;AACL,CAAC;AAUD;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,aAAa,CAAC,EAAmB;IAC/C,OAAO,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC;AACpC,CAAC;AAOD;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAAC,EAAkB;IAC7C,OAAO,EAAE,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;AAC1B,CAAC","sourcesContent":["import { buildRepoMap } from '../repomap/map.ts';\nimport type { RepoMap } from '../repomap/map.ts';\nimport { createSmelter } from '../smelter.ts';\nimport type { Strategy } from '../plan/planners.ts';\nimport type { DetectedLanguage, ElisionStore, RetrieveStats, SmeltResult } from '../types.ts';\n\n/**\n * The four verbs, as library functions over already-resolved inputs.\n *\n * This is the seam that sits **below both front doors**. The `smelt` CLI and the\n * `@smeltjs/mcp` server are the same four operations wearing two different coats, and\n * before this file existed each of them owned a full copy of the middle: build a\n * smelter from a strategy and a store, call it, hand the totals to a report; stat a\n * directory, build a map, render its warnings; retrieve one hash; read the counters.\n * The library exported the pieces, so both copies were *correct* — and both had to be\n * edited, in two packages, for one change to how a verb runs.\n *\n * What an op takes is already resolved: a budget that survived its law, a strategy\n * that won its precedence, a store that has been opened, text that has been read. What\n * an op returns is data — the smelted text and the values a report needs, a\n * {@link RepoMap}, bytes, counters. An op never sees argv, never writes to a stream,\n * never returns an exit code, and knows nothing about `CallToolResult`. Those are the\n * adapters' four jobs, and keeping them out here is what makes the same operation\n * testable once instead of twice.\n *\n * The division of labour, in one line: **a front door parses and resolves, an op runs,\n * a front door renders.**\n */\n\n/** One blob to smelt, fully resolved. */\nexport interface SmeltBlobOp {\n  /** The text itself. Reading a file into it is the front door's job (`readBlob`). */\n  readonly text: string;\n  /** What to call the input in a report: a path, `'<stdin>'`, `'<text>'`. */\n  readonly source: string;\n  /** UTF-8 bytes. Already past the budget law — see `ops/inputs.ts`. */\n  readonly budgetBytes: number;\n  /** Already past its precedence — see `resolveStrategy` in `ops/inputs.ts`. */\n  readonly strategy: Strategy;\n  /**\n   * Where elided bytes go. Optional only so a caller with nothing to persist gets the\n   * library's own default (a fresh {@link MemoryElisionStore}); a front door that read\n   * a config opens the store it decided on and passes it.\n   */\n  readonly store?: ElisionStore;\n  /** The path the text came from, for language detection. Absent for a pasted blob. */\n  readonly path?: string;\n  /** Overrides detection entirely, when a surface offers that. */\n  readonly language?: DetectedLanguage;\n  /** What the task is about. Empty and absent mean the same thing to every planner. */\n  readonly focus?: readonly string[];\n}\n\n/**\n * What one smelt run produced.\n *\n * The fields a report needs are the fields `formatReport` takes, deliberately: an op\n * returns exactly the values the render step reads off, so no front door assembles a\n * report input by hand and no front door counts a byte itself. (`formatReport(outcome)`\n * typechecks as written.) The store comes back too, because the `--json` envelope has\n * to `peek` at the bytes the run just stored, and a caller that passed no store never\n * had a handle on the one the library made.\n */\nexport interface SmeltBlobOutcome {\n  readonly result: SmeltResult;\n  /** What the input was called. Echoed back so a report never re-derives it. */\n  readonly source: string;\n  /** The budget the run was given, so a report can say when it was missed. */\n  readonly budgetBytes: number;\n  /** The exact text that was smelted. */\n  readonly inputText: string;\n  /** The store the run actually used — the one passed in, or the library's default. */\n  readonly store: ElisionStore;\n}\n\n/**\n * Verb: **cut one blob to a budget.**\n *\n * Every refusal the library can raise passes straight through — a `structural` run on\n * a language with no bundled grammar throws `GrammarUnavailableError` here exactly as\n * it does anywhere else, because a planner that quietly fell back to line windows\n * would be undetectable from outside. Coming back *over budget* is not a refusal and\n * not an error: the plan is returned as it came back, and whether that deserves a\n * non-zero exit code is a question only a front door can answer.\n */\nexport async function smeltBlob(op: SmeltBlobOp): Promise<SmeltBlobOutcome> {\n  const smelter = createSmelter({\n    strategy: op.strategy,\n    ...(op.store === undefined ? {} : { store: op.store }),\n  });\n  const result = await smelter.smelt(op.text, {\n    budgetBytes: op.budgetBytes,\n    ...(op.path === undefined ? {} : { path: op.path }),\n    ...(op.language === undefined ? {} : { language: op.language }),\n    ...(op.focus === undefined || op.focus.length === 0 ? {} : { focus: op.focus }),\n  });\n  return {\n    result,\n    source: op.source,\n    budgetBytes: op.budgetBytes,\n    inputText: op.text,\n    store: smelter.store,\n  };\n}\n\n/** One tree to map, fully resolved. */\nexport interface MapTreeOp {\n  /** A directory. Proving it is one is the front door's job (`readTree`). */\n  readonly root: string;\n  /** UTF-8 bytes. The map fits itself to this by construction. */\n  readonly budgetBytes: number;\n  readonly focus?: readonly string[];\n  /** Replaces the built-in ignore list when present. */\n  readonly ignore?: readonly string[];\n  /** Only when present does the map write anything to disk. */\n  readonly cacheDir?: string;\n}\n\n/**\n * Verb: **map a whole tree inside a budget.**\n *\n * Returns the {@link RepoMap} itself — the map *is* the data, warnings and cache\n * counts included, and wrapping it in an outcome struct would only give two front\n * doors a second place to disagree about what a map is. Nothing is elided, stored or\n * reversible, so there is nothing here to retrieve and no over-budget case to report.\n */\nexport function mapTree(op: MapTreeOp): Promise<RepoMap> {\n  return buildRepoMap({\n    root: op.root,\n    budgetBytes: op.budgetBytes,\n    ...(op.focus === undefined || op.focus.length === 0 ? {} : { focus: op.focus }),\n    ...(op.ignore === undefined || op.ignore.length === 0 ? {} : { ignore: op.ignore }),\n    ...(op.cacheDir === undefined ? {} : { cacheDir: op.cacheDir }),\n  });\n}\n\n/** One hash to turn back into bytes. */\nexport interface RetrieveBytesOp {\n  /** The store holding them — already opened. See `openStore` in `ops/inputs.ts`. */\n  readonly store: ElisionStore;\n  /** The hash exactly as a marker printed it. Validated by the store, not here. */\n  readonly hash: string;\n}\n\n/**\n * Verb: **the counted read.**\n *\n * Thin on purpose, and named anyway: this is the expansion rate moving. `retrieve()`\n * journals the hit, so a shell user typing `smelt retrieve` and a model calling\n * `smelt_retrieve` move the same counter through the same call — which is the only\n * reason the number means anything. The exact original bytes come back, nothing\n * appended and nothing re-encoded, and an unknown or damaged hash throws the store's\n * own distinct error rather than an empty string.\n *\n * @throws {UnknownHashError} for a hash the store never held.\n * @throws {StoreCorruptionError} for bytes that no longer hash to their name.\n */\nexport function retrieveBytes(op: RetrieveBytesOp): string {\n  return op.store.retrieve(op.hash);\n}\n\n/** One store to read the counters off. */\nexport interface ReadCountersOp {\n  readonly store: ElisionStore;\n}\n\n/**\n * Verb: **the uncounted read.**\n *\n * The sibling of {@link retrieveBytes}, and the asymmetry is the point: `stats()`\n * folds the journal without writing to it, so watching the expansion rate can never\n * move it. An observer that inflated its own metric would make the honest signal\n * dishonest.\n */\nexport function readCounters(op: ReadCountersOp): RetrieveStats {\n  return op.store.stats();\n}\n"]}

package/dist/plan/auto.d.ts

@@ -0,0 +1,69 @@
+import type { ElisionPlan, PlanInput, Planner } from '../types.ts';
+import type { LexicalPlannerOptions } from './lexical.ts';
+import type { StructuralPlannerOptions } from './structural.ts';
+/**
+ * The id of the *selector*, never of a plan.
+ *
+ * Every plan `auto` returns carries the id of the planner that actually ran —
+ * `lexical/v1` or `structural/v1` — because a caller reading `result.planner` is
+ * asking what happened to their bytes, not which name they typed. This constant
+ * exists so `PLANNERS.auto({}).id` says something true about the object it is on, and
+ * `test/guards/auto-strategy.test.ts` pins that it never reaches an `ElisionPlan`.
+ */
+export declare const AUTO_PLANNER_ID = "auto/v1";
+export interface AutoPlannerOptions {
+    /** Passed through when auto picks the lexical planner. */
+    readonly lexical?: LexicalPlannerOptions;
+    /** Passed through when auto picks the structural planner. */
+    readonly structural?: StructuralPlannerOptions;
+}
+/**
+ * The strategy that picks a strategy: **structural where a grammar is bundled,
+ * lexical everywhere else, and the result says which one ran.**
+ *
+ * It exists because the choice it makes is one a caller cannot make once. A consumer
+ * smelting whatever a tool handed it — a `.ts` file this call, a build log the next —
+ * has to name a strategy per call or accept the wrong one every other call, and the
+ * two wrong answers are not symmetric: `lexical` on TypeScript is a working planner
+ * doing a weak job, while `structural` on a build log is a `GrammarUnavailableError`.
+ * So the honest default for a *mixed* stream was neither name, and callers picked one
+ * anyway.
+ *
+ * **This is a selector, not a fallback, and the distinction is the whole design.**
+ *
+ *   - It decides on a *fact*: whether the language carries a bundled grammar
+ *     ({@link STRUCTURAL_LANGUAGES}). That is knowable before a byte is parsed, so
+ *     the decision is made up front and stated in the result's `planner` field.
+ *   - It never decides on an *accident*. A grammar that fails to load on a language
+ *     smelt claims to support is a broken install, and `GrammarUnavailableError`
+ *     travels straight out of here exactly as it does under `strategy: 'structural'`.
+ *     Catching it and answering with line windows would turn a loud environment fault
+ *     into quietly worse output — the failure mode Law 2's no-silent-downgrade
+ *     reasoning is about, wearing a friendlier name.
+ *   - It changes nothing about an explicit `strategy: 'structural'`. That still
+ *     refuses an unsupported language, because a caller who named the planner asked
+ *     for *its* guarantees, and a refusal is the only answer that does not fabricate
+ *     them. `auto` is a different request — "pick for me" — and answers it in the
+ *     open.
+ *
+ * `DEFAULT_STRATEGY` stays `lexical`: auto is opt-in, and a default that changed
+ * which planner ran would change what existing callers' results are labelled without
+ * anyone asking for it.
+ */
+export declare class AutoPlanner implements Planner {
+    #private;
+    readonly id = "auto/v1";
+    constructor(options?: AutoPlannerOptions);
+    plan(input: PlanInput): Promise<ElisionPlan>;
+}
+/**
+ * The selector as a function, exported like {@link planLexical} and
+ * {@link planStructural} so it can be tested and reused directly. Deterministic: the
+ * choice is a lookup in {@link STRUCTURAL_LANGUAGES}, and each planner it delegates to
+ * is deterministic in turn.
+ *
+ * @throws {GrammarUnavailableError} when the language *is* one smelt claims to parse
+ *   and its grammar cannot be loaded. Never caught here — see {@link AutoPlanner}.
+ */
+export declare function planAuto(input: PlanInput, options?: AutoPlannerOptions): Promise<ElisionPlan>;
+//# sourceMappingURL=auto.d.ts.map

package/dist/plan/auto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto.d.ts","sourceRoot":"","sources":["../../src/plan/auto.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAGnE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAE1D,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,iBAAiB,CAAC;AAEhE;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe,YAAY,CAAC;AAEzC,MAAM,WAAW,kBAAkB;IACjC,0DAA0D;IAC1D,QAAQ,CAAC,OAAO,CAAC,EAAE,qBAAqB,CAAC;IACzC,6DAA6D;IAC7D,QAAQ,CAAC,UAAU,CAAC,EAAE,wBAAwB,CAAC;CAChD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,qBAAa,WAAY,YAAW,OAAO;;IACzC,QAAQ,CAAC,EAAE,aAAmB;IAG9B,YAAY,OAAO,GAAE,kBAAuB,EAE3C;IAED,IAAI,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,WAAW,CAAC,CAE3C;CACF;AAED;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,WAAW,CAAC,CAIjG","sourcesContent":["import type { ElisionPlan, PlanInput, Planner } from '../types.ts';\n\nimport { planLexical } from './lexical.ts';\nimport type { LexicalPlannerOptions } from './lexical.ts';\nimport { isStructuralLanguage, planStructural } from './structural.ts';\nimport type { StructuralPlannerOptions } from './structural.ts';\n\n/**\n * The id of the *selector*, never of a plan.\n *\n * Every plan `auto` returns carries the id of the planner that actually ran —\n * `lexical/v1` or `structural/v1` — because a caller reading `result.planner` is\n * asking what happened to their bytes, not which name they typed. This constant\n * exists so `PLANNERS.auto({}).id` says something true about the object it is on, and\n * `test/guards/auto-strategy.test.ts` pins that it never reaches an `ElisionPlan`.\n */\nexport const AUTO_PLANNER_ID = 'auto/v1';\n\nexport interface AutoPlannerOptions {\n  /** Passed through when auto picks the lexical planner. */\n  readonly lexical?: LexicalPlannerOptions;\n  /** Passed through when auto picks the structural planner. */\n  readonly structural?: StructuralPlannerOptions;\n}\n\n/**\n * The strategy that picks a strategy: **structural where a grammar is bundled,\n * lexical everywhere else, and the result says which one ran.**\n *\n * It exists because the choice it makes is one a caller cannot make once. A consumer\n * smelting whatever a tool handed it — a `.ts` file this call, a build log the next —\n * has to name a strategy per call or accept the wrong one every other call, and the\n * two wrong answers are not symmetric: `lexical` on TypeScript is a working planner\n * doing a weak job, while `structural` on a build log is a `GrammarUnavailableError`.\n * So the honest default for a *mixed* stream was neither name, and callers picked one\n * anyway.\n *\n * **This is a selector, not a fallback, and the distinction is the whole design.**\n *\n *   - It decides on a *fact*: whether the language carries a bundled grammar\n *     ({@link STRUCTURAL_LANGUAGES}). That is knowable before a byte is parsed, so\n *     the decision is made up front and stated in the result's `planner` field.\n *   - It never decides on an *accident*. A grammar that fails to load on a language\n *     smelt claims to support is a broken install, and `GrammarUnavailableError`\n *     travels straight out of here exactly as it does under `strategy: 'structural'`.\n *     Catching it and answering with line windows would turn a loud environment fault\n *     into quietly worse output — the failure mode Law 2's no-silent-downgrade\n *     reasoning is about, wearing a friendlier name.\n *   - It changes nothing about an explicit `strategy: 'structural'`. That still\n *     refuses an unsupported language, because a caller who named the planner asked\n *     for *its* guarantees, and a refusal is the only answer that does not fabricate\n *     them. `auto` is a different request — \"pick for me\" — and answers it in the\n *     open.\n *\n * `DEFAULT_STRATEGY` stays `lexical`: auto is opt-in, and a default that changed\n * which planner ran would change what existing callers' results are labelled without\n * anyone asking for it.\n */\nexport class AutoPlanner implements Planner {\n  readonly id = AUTO_PLANNER_ID;\n  readonly #options: AutoPlannerOptions;\n\n  constructor(options: AutoPlannerOptions = {}) {\n    this.#options = options;\n  }\n\n  plan(input: PlanInput): Promise<ElisionPlan> {\n    return planAuto(input, this.#options);\n  }\n}\n\n/**\n * The selector as a function, exported like {@link planLexical} and\n * {@link planStructural} so it can be tested and reused directly. Deterministic: the\n * choice is a lookup in {@link STRUCTURAL_LANGUAGES}, and each planner it delegates to\n * is deterministic in turn.\n *\n * @throws {GrammarUnavailableError} when the language *is* one smelt claims to parse\n *   and its grammar cannot be loaded. Never caught here — see {@link AutoPlanner}.\n */\nexport function planAuto(input: PlanInput, options: AutoPlannerOptions = {}): Promise<ElisionPlan> {\n  return isStructuralLanguage(input.language)\n    ? planStructural(input, options.structural ?? {})\n    : Promise.resolve(planLexical(input, options.lexical ?? {}));\n}\n"]}

package/dist/plan/auto.js

@@ -0,0 +1,70 @@
+import { planLexical } from './lexical.js';
+import { isStructuralLanguage, planStructural } from './structural.js';
+/**
+ * The id of the *selector*, never of a plan.
+ *
+ * Every plan `auto` returns carries the id of the planner that actually ran —
+ * `lexical/v1` or `structural/v1` — because a caller reading `result.planner` is
+ * asking what happened to their bytes, not which name they typed. This constant
+ * exists so `PLANNERS.auto({}).id` says something true about the object it is on, and
+ * `test/guards/auto-strategy.test.ts` pins that it never reaches an `ElisionPlan`.
+ */
+export const AUTO_PLANNER_ID = 'auto/v1';
+/**
+ * The strategy that picks a strategy: **structural where a grammar is bundled,
+ * lexical everywhere else, and the result says which one ran.**
+ *
+ * It exists because the choice it makes is one a caller cannot make once. A consumer
+ * smelting whatever a tool handed it — a `.ts` file this call, a build log the next —
+ * has to name a strategy per call or accept the wrong one every other call, and the
+ * two wrong answers are not symmetric: `lexical` on TypeScript is a working planner
+ * doing a weak job, while `structural` on a build log is a `GrammarUnavailableError`.
+ * So the honest default for a *mixed* stream was neither name, and callers picked one
+ * anyway.
+ *
+ * **This is a selector, not a fallback, and the distinction is the whole design.**
+ *
+ *   - It decides on a *fact*: whether the language carries a bundled grammar
+ *     ({@link STRUCTURAL_LANGUAGES}). That is knowable before a byte is parsed, so
+ *     the decision is made up front and stated in the result's `planner` field.
+ *   - It never decides on an *accident*. A grammar that fails to load on a language
+ *     smelt claims to support is a broken install, and `GrammarUnavailableError`
+ *     travels straight out of here exactly as it does under `strategy: 'structural'`.
+ *     Catching it and answering with line windows would turn a loud environment fault
+ *     into quietly worse output — the failure mode Law 2's no-silent-downgrade
+ *     reasoning is about, wearing a friendlier name.
+ *   - It changes nothing about an explicit `strategy: 'structural'`. That still
+ *     refuses an unsupported language, because a caller who named the planner asked
+ *     for *its* guarantees, and a refusal is the only answer that does not fabricate
+ *     them. `auto` is a different request — "pick for me" — and answers it in the
+ *     open.
+ *
+ * `DEFAULT_STRATEGY` stays `lexical`: auto is opt-in, and a default that changed
+ * which planner ran would change what existing callers' results are labelled without
+ * anyone asking for it.
+ */
+export class AutoPlanner {
+    id = AUTO_PLANNER_ID;
+    #options;
+    constructor(options = {}) {
+        this.#options = options;
+    }
+    plan(input) {
+        return planAuto(input, this.#options);
+    }
+}
+/**
+ * The selector as a function, exported like {@link planLexical} and
+ * {@link planStructural} so it can be tested and reused directly. Deterministic: the
+ * choice is a lookup in {@link STRUCTURAL_LANGUAGES}, and each planner it delegates to
+ * is deterministic in turn.
+ *
+ * @throws {GrammarUnavailableError} when the language *is* one smelt claims to parse
+ *   and its grammar cannot be loaded. Never caught here — see {@link AutoPlanner}.
+ */
+export function planAuto(input, options = {}) {
+    return isStructuralLanguage(input.language)
+        ? planStructural(input, options.structural ?? {})
+        : Promise.resolve(planLexical(input, options.lexical ?? {}));
+}
+//# sourceMappingURL=auto.js.map

package/dist/plan/auto.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto.js","sourceRoot":"","sources":["../../src/plan/auto.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAE3C,OAAO,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAGvE;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,SAAS,CAAC;AASzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,OAAO,WAAW;IACb,EAAE,GAAG,eAAe,CAAC;IACrB,QAAQ,CAAqB;IAEtC,YAAY,OAAO,GAAuB,EAAE;QAC1C,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC;IAC1B,CAAC;IAED,IAAI,CAAC,KAAgB;QACnB,OAAO,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;IACxC,CAAC;CACF;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,QAAQ,CAAC,KAAgB,EAAE,OAAO,GAAuB,EAAE;IACzE,OAAO,oBAAoB,CAAC,KAAK,CAAC,QAAQ,CAAC;QACzC,CAAC,CAAC,cAAc,CAAC,KAAK,EAAE,OAAO,CAAC,UAAU,IAAI,EAAE,CAAC;QACjD,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,WAAW,CAAC,KAAK,EAAE,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,CAAC;AACjE,CAAC","sourcesContent":["import type { ElisionPlan, PlanInput, Planner } from '../types.ts';\n\nimport { planLexical } from './lexical.ts';\nimport type { LexicalPlannerOptions } from './lexical.ts';\nimport { isStructuralLanguage, planStructural } from './structural.ts';\nimport type { StructuralPlannerOptions } from './structural.ts';\n\n/**\n * The id of the *selector*, never of a plan.\n *\n * Every plan `auto` returns carries the id of the planner that actually ran —\n * `lexical/v1` or `structural/v1` — because a caller reading `result.planner` is\n * asking what happened to their bytes, not which name they typed. This constant\n * exists so `PLANNERS.auto({}).id` says something true about the object it is on, and\n * `test/guards/auto-strategy.test.ts` pins that it never reaches an `ElisionPlan`.\n */\nexport const AUTO_PLANNER_ID = 'auto/v1';\n\nexport interface AutoPlannerOptions {\n  /** Passed through when auto picks the lexical planner. */\n  readonly lexical?: LexicalPlannerOptions;\n  /** Passed through when auto picks the structural planner. */\n  readonly structural?: StructuralPlannerOptions;\n}\n\n/**\n * The strategy that picks a strategy: **structural where a grammar is bundled,\n * lexical everywhere else, and the result says which one ran.**\n *\n * It exists because the choice it makes is one a caller cannot make once. A consumer\n * smelting whatever a tool handed it — a `.ts` file this call, a build log the next —\n * has to name a strategy per call or accept the wrong one every other call, and the\n * two wrong answers are not symmetric: `lexical` on TypeScript is a working planner\n * doing a weak job, while `structural` on a build log is a `GrammarUnavailableError`.\n * So the honest default for a *mixed* stream was neither name, and callers picked one\n * anyway.\n *\n * **This is a selector, not a fallback, and the distinction is the whole design.**\n *\n *   - It decides on a *fact*: whether the language carries a bundled grammar\n *     ({@link STRUCTURAL_LANGUAGES}). That is knowable before a byte is parsed, so\n *     the decision is made up front and stated in the result's `planner` field.\n *   - It never decides on an *accident*. A grammar that fails to load on a language\n *     smelt claims to support is a broken install, and `GrammarUnavailableError`\n *     travels straight out of here exactly as it does under `strategy: 'structural'`.\n *     Catching it and answering with line windows would turn a loud environment fault\n *     into quietly worse output — the failure mode Law 2's no-silent-downgrade\n *     reasoning is about, wearing a friendlier name.\n *   - It changes nothing about an explicit `strategy: 'structural'`. That still\n *     refuses an unsupported language, because a caller who named the planner asked\n *     for *its* guarantees, and a refusal is the only answer that does not fabricate\n *     them. `auto` is a different request — \"pick for me\" — and answers it in the\n *     open.\n *\n * `DEFAULT_STRATEGY` stays `lexical`: auto is opt-in, and a default that changed\n * which planner ran would change what existing callers' results are labelled without\n * anyone asking for it.\n */\nexport class AutoPlanner implements Planner {\n  readonly id = AUTO_PLANNER_ID;\n  readonly #options: AutoPlannerOptions;\n\n  constructor(options: AutoPlannerOptions = {}) {\n    this.#options = options;\n  }\n\n  plan(input: PlanInput): Promise<ElisionPlan> {\n    return planAuto(input, this.#options);\n  }\n}\n\n/**\n * The selector as a function, exported like {@link planLexical} and\n * {@link planStructural} so it can be tested and reused directly. Deterministic: the\n * choice is a lookup in {@link STRUCTURAL_LANGUAGES}, and each planner it delegates to\n * is deterministic in turn.\n *\n * @throws {GrammarUnavailableError} when the language *is* one smelt claims to parse\n *   and its grammar cannot be loaded. Never caught here — see {@link AutoPlanner}.\n */\nexport function planAuto(input: PlanInput, options: AutoPlannerOptions = {}): Promise<ElisionPlan> {\n  return isStructuralLanguage(input.language)\n    ? planStructural(input, options.structural ?? {})\n    : Promise.resolve(planLexical(input, options.lexical ?? {}));\n}\n"]}

package/dist/plan/budget.d.ts

@@ -0,0 +1,21 @@
+import type { MarkerPricing, PlannedElision } from '../types.ts';
+/**
+ * What a plan will cost once its markers land — the arithmetic both planners do.
+ *
+ * Two planners now read `budgetBytes`, and both answer the same question with it:
+ * *given these elisions, how big is the output?* The lexical planner asks it to pick a
+ * ladder rung; the structural planner asks it to decide whether its budget rung is
+ * needed at all. Written twice it would be two answers to one question, which is how
+ * one planner ends up believing a marker costs something the other does not — the
+ * exact fork the {@link MarkerPricing} seam exists to prevent, one level up.
+ *
+ * Nothing here estimates. Every byte comes from `pricing.costBytes`, the seam
+ * `apply.ts` builds from the exact builder `applyPlan` will use.
+ */
+/** The exact UTF-8 cost of the marker this elision would earn. Asked, not guessed. */
+export declare function markerBytes(elision: PlannedElision, pricing: MarkerPricing): number;
+/** What one elision saves: the bytes it removes, less the marker that replaces them. */
+export declare function savingBytes(elision: PlannedElision, pricing: MarkerPricing): number;
+/** The output size these elisions predict, markers included. */
+export declare function predictOutputBytes(inputBytes: number, elisions: readonly PlannedElision[], pricing: MarkerPricing): number;
+//# sourceMappingURL=budget.d.ts.map

package/dist/plan/budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget.d.ts","sourceRoot":"","sources":["../../src/plan/budget.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAEjE;;;;;;;;;;;;GAYG;AAEH,sFAAsF;AACtF,wBAAgB,WAAW,CAAC,OAAO,EAAE,cAAc,EAAE,OAAO,EAAE,aAAa,GAAG,MAAM,CAEnF;AAED,wFAAwF;AACxF,wBAAgB,WAAW,CAAC,OAAO,EAAE,cAAc,EAAE,OAAO,EAAE,aAAa,GAAG,MAAM,CAEnF;AAED,gEAAgE;AAChE,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,SAAS,cAAc,EAAE,EACnC,OAAO,EAAE,aAAa,GACrB,MAAM,CAER","sourcesContent":["import type { MarkerPricing, PlannedElision } from '../types.ts';\n\n/**\n * What a plan will cost once its markers land — the arithmetic both planners do.\n *\n * Two planners now read `budgetBytes`, and both answer the same question with it:\n * *given these elisions, how big is the output?* The lexical planner asks it to pick a\n * ladder rung; the structural planner asks it to decide whether its budget rung is\n * needed at all. Written twice it would be two answers to one question, which is how\n * one planner ends up believing a marker costs something the other does not — the\n * exact fork the {@link MarkerPricing} seam exists to prevent, one level up.\n *\n * Nothing here estimates. Every byte comes from `pricing.costBytes`, the seam\n * `apply.ts` builds from the exact builder `applyPlan` will use.\n */\n\n/** The exact UTF-8 cost of the marker this elision would earn. Asked, not guessed. */\nexport function markerBytes(elision: PlannedElision, pricing: MarkerPricing): number {\n  return pricing.costBytes(elision.reason, elision.range.end - elision.range.start);\n}\n\n/** What one elision saves: the bytes it removes, less the marker that replaces them. */\nexport function savingBytes(elision: PlannedElision, pricing: MarkerPricing): number {\n  return elision.range.end - elision.range.start - markerBytes(elision, pricing);\n}\n\n/** The output size these elisions predict, markers included. */\nexport function predictOutputBytes(\n  inputBytes: number,\n  elisions: readonly PlannedElision[],\n  pricing: MarkerPricing,\n): number {\n  return elisions.reduce((bytes, elision) => bytes - savingBytes(elision, pricing), inputBytes);\n}\n"]}