@smeltjs/core 0.2.0 → 0.4.0

package/dist/cli/subcommands/stats.js

@@ -0,0 +1,62 @@
+import { CliUsageError } from '../../errors.js';
+import { openStore } from '../../ops/inputs.js';
+import { readCounters } from '../../ops/verbs.js';
+import { CLI_NAME, EXIT } from '../shell.js';
+import { resolveStoreRun } from './retrieve.js';
+/**
+ * The `smelt stats --json` envelope format. Its own version line for the same reason
+ * `smelt map` has one: the two envelopes carry different structures and must move
+ * independently.
+ */
+export const CLI_STATS_JSON_FORMAT = 'smelt-stats-cli/v1';
+export const statsCommand = {
+    name: 'stats',
+    flags: ['json'],
+    refusal: `stats reads counters; there is nothing to budget, focus or plan.`,
+    usage: {
+        synopsis: ['stats [--json]'],
+        section: {
+            heading: 'RETRIEVE & STATS',
+            body: `  ${CLI_NAME} stats prints the same store's counters, one \`name value\` per line —\n` +
+                `  elisionsStored, bytesStored, retrieveCalls, uniqueRetrieved, expansionRate,\n` +
+                `  allElisionsRetrieved — and reading them is NOT counted as a retrieval. --json\n` +
+                `  emits the RetrieveStats verbatim in its own versioned envelope.\n` +
+                `\n` +
+                `  Both need somewhere for elisions to outlive the run that made them: a\n` +
+                `  smelt.config.json with a directory store (\`${CLI_NAME} init\` writes one). With a\n` +
+                `  memory store — or no config — every run's store dies with its process, so there\n` +
+                `  is nothing to retrieve across runs, and that is a usage error rather than a\n` +
+                `  quiet empty answer.`,
+        },
+    },
+    parse(values, positionals) {
+        if (positionals.length > 1) {
+            throw new CliUsageError(`${CLI_NAME}: stats takes no further arguments, got ` +
+                `${positionals.slice(1).join(', ')}. It reports on the one configured store.`);
+        }
+        return { mode: 'stats', json: values.json === true };
+    },
+    resolve(invocation, config) {
+        return { store: resolveStoreRun('stats', config()), json: invocation.json };
+    },
+    run(resolved, io) {
+        const store = openStore({ kind: 'directory', path: resolved.store.storePath });
+        const stats = readCounters({ store });
+        if (resolved.json) {
+            const statsEnvelope = { format: CLI_STATS_JSON_FORMAT, stats };
+            io.stdout(`${JSON.stringify(statsEnvelope, null, 2)}\n`);
+            return EXIT.ok;
+        }
+        io.stdout([
+            `elisionsStored ${String(stats.elisionsStored)}`,
+            `bytesStored ${String(stats.bytesStored)}`,
+            `retrieveCalls ${String(stats.retrieveCalls)}`,
+            `uniqueRetrieved ${String(stats.uniqueRetrieved)}`,
+            `expansionRate ${String(stats.expansionRate)}`,
+            `allElisionsRetrieved ${String(stats.allElisionsRetrieved)}`,
+            '',
+        ].join('\n'));
+        return EXIT.ok;
+    },
+};
+//# sourceMappingURL=stats.js.map

package/dist/cli/subcommands/stats.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stats.js","sourceRoot":"","sources":["../../../src/cli/subcommands/stats.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAChD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAI7C,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAiChD;;;;GAIG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,oBAAoB,CAAC;AAS1D,MAAM,CAAC,MAAM,YAAY,GAAkD;IACzE,IAAI,EAAE,OAAO;IACb,KAAK,EAAE,CAAC,MAAM,CAAC;IACf,OAAO,EAAE,kEAAkE;IAC3E,KAAK,EAAE;QACL,QAAQ,EAAE,CAAC,gBAAgB,CAAC;QAC5B,OAAO,EAAE;YACP,OAAO,EAAE,kBAAkB;YAC3B,IAAI,EACF,KAAK,QAAQ,0EAA0E;gBACvF,iFAAiF;gBACjF,mFAAmF;gBACnF,qEAAqE;gBACrE,IAAI;gBACJ,2EAA2E;gBAC3E,iDAAiD,QAAQ,+BAA+B;gBACxF,qFAAqF;gBACrF,iFAAiF;gBACjF,uBAAuB;SAC1B;KACF;IAED,KAAK,CAAC,MAAkB,EAAE,WAA8B;QACtD,IAAI,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC3B,MAAM,IAAI,aAAa,CACrB,GAAG,QAAQ,0CAA0C;gBACnD,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,2CAA2C,CAChF,CAAC;QACJ,CAAC;QACD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,KAAK,IAAI,EAAE,CAAC;IACvD,CAAC;IAED,OAAO,CAAC,UAA2B,EAAE,MAAoB;QACvD,OAAO,EAAE,KAAK,EAAE,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,UAAU,CAAC,IAAI,EAAE,CAAC;IAC9E,CAAC;IAED,GAAG,CAAC,QAA0B,EAAE,EAAS;QACvC,MAAM,KAAK,GAAG,SAAS,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,QAAQ,CAAC,KAAK,CAAC,SAAS,EAAE,CAAC,CAAC;QAC/E,MAAM,KAAK,GAAG,YAAY,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;QAEtC,IAAI,QAAQ,CAAC,IAAI,EAAE,CAAC;YAClB,MAAM,aAAa,GAAyB,EAAE,MAAM,EAAE,qBAAqB,EAAE,KAAK,EAAE,CAAC;YACrF,EAAE,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;YACzD,OAAO,IAAI,CAAC,EAAE,CAAC;QACjB,CAAC;QAED,EAAE,CAAC,MAAM,CACP;YACE,kBAAkB,MAAM,CAAC,KAAK,CAAC,cAAc,CAAC,EAAE;YAChD,eAAe,MAAM,CAAC,KAAK,CAAC,WAAW,CAAC,EAAE;YAC1C,iBAAiB,MAAM,CAAC,KAAK,CAAC,aAAa,CAAC,EAAE;YAC9C,mBAAmB,MAAM,CAAC,KAAK,CAAC,eAAe,CAAC,EAAE;YAClD,iBAAiB,MAAM,CAAC,KAAK,CAAC,aAAa,CAAC,EAAE;YAC9C,wBAAwB,MAAM,CAAC,KAAK,CAAC,oBAAoB,CAAC,EAAE;YAC5D,EAAE;SACH,CAAC,IAAI,CAAC,IAAI,CAAC,CACb,CAAC;QACF,OAAO,IAAI,CAAC,EAAE,CAAC;IACjB,CAAC;CACF,CAAC","sourcesContent":["import { CliUsageError } from '../../errors.ts';\nimport { openStore } from '../../ops/inputs.ts';\nimport { readCounters } from '../../ops/verbs.ts';\nimport type { RetrieveStats } from '../../types.ts';\nimport { CLI_NAME, EXIT } from '../shell.ts';\nimport type { CliIo } from '../shell.ts';\n\nimport type { FlagValues } from './flags.ts';\nimport { resolveStoreRun } from './retrieve.ts';\nimport type { ResolvedStoreRun } from './retrieve.ts';\nimport type { ConfigSource, Subcommand } from './subcommand.ts';\n\n/**\n * `smelt stats` — the store's counters, without touching them.\n *\n * Reading stats does NOT count as a retrieval: `stats()` folds the journal and scans\n * the blobs, journaling nothing, so watching the expansion rate can never move it —\n * an observer that inflated its own metric would make the honest signal dishonest.\n *\n * The plain form is one `name value` per line, greppable and stable; `--json` emits\n * the {@link RetrieveStats} verbatim in its own versioned envelope\n * ({@link CLI_STATS_JSON_FORMAT}), like every other machine-read surface here.\n *\n * It resolves through `retrieve`'s {@link resolveStoreRun} because the two verbs\n * share one merge — the store leg, and the same refusal when that store cannot\n * outlive a run. Sharing the function is the point; sharing a struct with a hash\n * field `stats` would never read is not.\n */\n\n/** `smelt stats` — the store's counters, read without touching them. */\nexport interface StatsInvocation {\n  readonly mode: 'stats';\n  readonly json: boolean;\n}\n\n/** What `stats` runs on: the shared store leg, plus how to print it. */\nexport interface ResolvedStatsRun {\n  readonly store: ResolvedStoreRun;\n  readonly json: boolean;\n}\n\n/**\n * The `smelt stats --json` envelope format. Its own version line for the same reason\n * `smelt map` has one: the two envelopes carry different structures and must move\n * independently.\n */\nexport const CLI_STATS_JSON_FORMAT = 'smelt-stats-cli/v1';\n\n/** What `smelt stats --json` prints: the {@link RetrieveStats} verbatim, versioned. */\nexport interface CliStatsJsonEnvelope {\n  readonly format: string;\n  /** The {@link RetrieveStats} exactly as the store's `stats()` returned them. */\n  readonly stats: RetrieveStats;\n}\n\nexport const statsCommand: Subcommand<StatsInvocation, ResolvedStatsRun> = {\n  name: 'stats',\n  flags: ['json'],\n  refusal: `stats reads counters; there is nothing to budget, focus or plan.`,\n  usage: {\n    synopsis: ['stats [--json]'],\n    section: {\n      heading: 'RETRIEVE & STATS',\n      body:\n        `  ${CLI_NAME} stats prints the same store's counters, one \\`name value\\` per line —\\n` +\n        `  elisionsStored, bytesStored, retrieveCalls, uniqueRetrieved, expansionRate,\\n` +\n        `  allElisionsRetrieved — and reading them is NOT counted as a retrieval. --json\\n` +\n        `  emits the RetrieveStats verbatim in its own versioned envelope.\\n` +\n        `\\n` +\n        `  Both need somewhere for elisions to outlive the run that made them: a\\n` +\n        `  smelt.config.json with a directory store (\\`${CLI_NAME} init\\` writes one). With a\\n` +\n        `  memory store — or no config — every run's store dies with its process, so there\\n` +\n        `  is nothing to retrieve across runs, and that is a usage error rather than a\\n` +\n        `  quiet empty answer.`,\n    },\n  },\n\n  parse(values: FlagValues, positionals: readonly string[]): StatsInvocation {\n    if (positionals.length > 1) {\n      throw new CliUsageError(\n        `${CLI_NAME}: stats takes no further arguments, got ` +\n          `${positionals.slice(1).join(', ')}. It reports on the one configured store.`,\n      );\n    }\n    return { mode: 'stats', json: values.json === true };\n  },\n\n  resolve(invocation: StatsInvocation, config: ConfigSource): ResolvedStatsRun {\n    return { store: resolveStoreRun('stats', config()), json: invocation.json };\n  },\n\n  run(resolved: ResolvedStatsRun, io: CliIo): number {\n    const store = openStore({ kind: 'directory', path: resolved.store.storePath });\n    const stats = readCounters({ store });\n\n    if (resolved.json) {\n      const statsEnvelope: CliStatsJsonEnvelope = { format: CLI_STATS_JSON_FORMAT, stats };\n      io.stdout(`${JSON.stringify(statsEnvelope, null, 2)}\\n`);\n      return EXIT.ok;\n    }\n\n    io.stdout(\n      [\n        `elisionsStored ${String(stats.elisionsStored)}`,\n        `bytesStored ${String(stats.bytesStored)}`,\n        `retrieveCalls ${String(stats.retrieveCalls)}`,\n        `uniqueRetrieved ${String(stats.uniqueRetrieved)}`,\n        `expansionRate ${String(stats.expansionRate)}`,\n        `allElisionsRetrieved ${String(stats.allElisionsRetrieved)}`,\n        '',\n      ].join('\\n'),\n    );\n    return EXIT.ok;\n  },\n};\n"]}

package/dist/cli/subcommands/subcommand.d.ts

@@ -0,0 +1,113 @@
+import type { LoadedConfig } from '../config.ts';
+import type { CliIo } from '../shell.ts';
+import type { FlagValues, VerbFlag } from './flags.ts';
+/**
+ * The verbs `smelt` answers to. `'smelt'` is the default verb — the bare
+ * `smelt <file>` / `smelt < input` run — and is the only one with no word on the
+ * command line, which is why a file literally named `map` needs `./map`.
+ *
+ * Order is meaningful: it is the order `--help` renders every derived list in, and the
+ * order a refusal names owners in. Keep it stable and append new verbs at the end.
+ */
+export type Verb = 'smelt' | 'init' | 'map' | 'retrieve' | 'stats' | 'hooks' | 'agents';
+/** The verb a bare invocation selects — a file or stdin, with no subcommand word. */
+export declare const DEFAULT_VERB = "smelt";
+/**
+ * The nearest `smelt.config.json`, loaded on demand.
+ *
+ * A thunk rather than a value, because two verbs must **not** load it: `init` and
+ * `hooks` read the config file themselves, with their own tolerance, and a wizard you
+ * run to *fix* a malformed config cannot be a wizard that refuses to start because the
+ * config is malformed. Loading eagerly in the dispatcher would quietly turn that into
+ * a usage error.
+ */
+export type ConfigSource = () => LoadedConfig | undefined;
+/** What one verb contributes to `--help`. See `cli/usage.ts` for the rendering. */
+export interface SubcommandUsage {
+    /**
+     * The command's everyday forms, rendered in the first block of USAGE in registry
+     * order. Each entry is the text *after* the CLI name.
+     */
+    readonly synopsis: readonly string[];
+    /**
+     * Forms rendered in the second block, after every command's everyday forms: the
+     * round trip (`--reconstruct`) and the one-time setup (`init`) — jobs you do
+     * occasionally rather than the shape of a normal run. It keeps USAGE reading
+     * top-to-bottom by how often you type a thing without anyone arranging the list.
+     */
+    readonly occasional?: readonly string[];
+    /**
+     * The verb's own section of the help — a heading and its body, already indented.
+     * Two verbs may declare the same heading (`retrieve` and `stats` share RETRIEVE &
+     * STATS, because the loop is one story); their bodies are joined under it in
+     * registry order.
+     */
+    readonly section?: {
+        readonly heading: string;
+        readonly body: string;
+    };
+}
+/**
+ * One subcommand: everything the CLI knows about one verb, in one place.
+ *
+ * This is the seam the CLI was missing. A verb used to be a *shape* restated in four
+ * modules — an `*Invocation` interface and a `parse*Args` in `cli/args.ts`, a
+ * `Resolved*Run` and a `resolve*` in `cli/resolve.ts`, a `case` and a `run*` in
+ * `cli/run.ts`, plus a hand-written help block and a hand-written refusal for every
+ * flag it did not want. The refusals were the compounding cost: because no verb owned
+ * its flags, every verb refused every other verb's flags by hand, so an eleventh flag
+ * edited five messages.
+ *
+ * Now a verb is one file exporting one of these, and `SUBCOMMANDS` in `./registry.ts`
+ * is `Record<Verb, …>` — the {@link LANGUAGE_PROFILES} / {@link HARNESS_PROFILES}
+ * pattern, so totality is a compile error and every rendered list (USAGE, the sections,
+ * the `map only.` prefixes in OPTIONS) is a derived view.
+ *
+ * The type parameters are the verb's own two shapes, and they never merge:
+ *
+ * @typeParam I - what the verb's `parse` returns, e.g. `MapInvocation`. Pure data, so
+ *   the parse is testable on its own.
+ * @typeParam R - what its `resolve` returns, e.g. `ResolvedMapRun`. The verb's single
+ *   merge of flags + config + built-ins, each value carrying its provenance. Deliberately
+ *   one type per verb: `map` has no store, no strategy and no stdin, and a shared struct
+ *   whose fields are lies for half its users is not a seam, it is a coincidence.
+ */
+export interface Subcommand<I, R> {
+    /** The word on the command line — and the registry key. `'smelt'` has no word. */
+    readonly name: Verb;
+    /**
+     * The flags this verb owns. **The whole point.** Every flag outside this list is
+     * refused by one generated message (`refuseForeignFlags` in `./registry.ts`) rather
+     * than by prose the next verb has to write again. A flag silently ignored would be a
+     * setting the user believed was in force.
+     */
+    readonly flags: readonly VerbFlag[];
+    /**
+     * What this verb *is*, as one sentence — the tail of the generated refusal, and the
+     * only part of it a verb writes. It answers "why not here?", which is the half of
+     * the old hand-written messages worth keeping; the offending flag, this verb's name
+     * and the verb the flag does belong to are all derived from the registry.
+     */
+    readonly refusal: string;
+    /** What this verb contributes to `--help`. Rendered, never hand-arranged. */
+    readonly usage: SubcommandUsage;
+    /**
+     * The verb's own validation, over the flags it owns and the positionals it was
+     * given (index 0 is the verb word itself, except for the default verb).
+     *
+     * @throws {CliUsageError} on anything the user got wrong. Never guesses.
+     */
+    parse(values: FlagValues, positionals: readonly string[]): I;
+    /**
+     * The verb's single merge of flags + config + built-ins. Precedence for this verb
+     * lives here and nowhere else, so a precedence question is answered by one function
+     * instead of by reading two files.
+     *
+     * @throws {CliUsageError} when a required value has no source — the budget, for the
+     *   two verbs that need one.
+     */
+    resolve(invocation: I, config: ConfigSource): R;
+    /** Execute the resolved run straight-line, and return the exit code. */
+    run(resolved: R, io: CliIo): number | Promise<number>;
+}
+//# sourceMappingURL=subcommand.d.ts.map

package/dist/cli/subcommands/subcommand.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subcommand.d.ts","sourceRoot":"","sources":["../../../src/cli/subcommands/subcommand.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAEzC,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEvD;;;;;;;GAOG;AACH,MAAM,MAAM,IAAI,GAAG,OAAO,GAAG,MAAM,GAAG,KAAK,GAAG,UAAU,GAAG,OAAO,GAAG,OAAO,GAAG,QAAQ,CAAC;AAExF,qFAAqF;AACrF,eAAO,MAAM,YAAY,UAAyB,CAAC;AAEnD;;;;;;;;GAQG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,YAAY,GAAG,SAAS,CAAC;AAE1D,mFAAmF;AACnF,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;CACxE;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,WAAW,UAAU,CAAC,CAAC,EAAE,CAAC;IAC9B,kFAAkF;IAClF,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,EAAE,SAAS,QAAQ,EAAE,CAAC;IACpC;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,6EAA6E;IAC7E,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAC;IAChC;;;;;OAKG;IACH,KAAK,CAAC,MAAM,EAAE,UAAU,EAAE,WAAW,EAAE,SAAS,MAAM,EAAE,GAAG,CAAC,CAAC;IAC7D;;;;;;;OAOG;IACH,OAAO,CAAC,UAAU,EAAE,CAAC,EAAE,MAAM,EAAE,YAAY,GAAG,CAAC,CAAC;IAChD,wEAAwE;IACxE,GAAG,CAAC,QAAQ,EAAE,CAAC,EAAE,EAAE,EAAE,KAAK,GAAG,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACvD","sourcesContent":["import type { LoadedConfig } from '../config.ts';\nimport type { CliIo } from '../shell.ts';\n\nimport type { FlagValues, VerbFlag } from './flags.ts';\n\n/**\n * The verbs `smelt` answers to. `'smelt'` is the default verb — the bare\n * `smelt <file>` / `smelt < input` run — and is the only one with no word on the\n * command line, which is why a file literally named `map` needs `./map`.\n *\n * Order is meaningful: it is the order `--help` renders every derived list in, and the\n * order a refusal names owners in. Keep it stable and append new verbs at the end.\n */\nexport type Verb = 'smelt' | 'init' | 'map' | 'retrieve' | 'stats' | 'hooks' | 'agents';\n\n/** The verb a bare invocation selects — a file or stdin, with no subcommand word. */\nexport const DEFAULT_VERB = 'smelt' satisfies Verb;\n\n/**\n * The nearest `smelt.config.json`, loaded on demand.\n *\n * A thunk rather than a value, because two verbs must **not** load it: `init` and\n * `hooks` read the config file themselves, with their own tolerance, and a wizard you\n * run to *fix* a malformed config cannot be a wizard that refuses to start because the\n * config is malformed. Loading eagerly in the dispatcher would quietly turn that into\n * a usage error.\n */\nexport type ConfigSource = () => LoadedConfig | undefined;\n\n/** What one verb contributes to `--help`. See `cli/usage.ts` for the rendering. */\nexport interface SubcommandUsage {\n  /**\n   * The command's everyday forms, rendered in the first block of USAGE in registry\n   * order. Each entry is the text *after* the CLI name.\n   */\n  readonly synopsis: readonly string[];\n  /**\n   * Forms rendered in the second block, after every command's everyday forms: the\n   * round trip (`--reconstruct`) and the one-time setup (`init`) — jobs you do\n   * occasionally rather than the shape of a normal run. It keeps USAGE reading\n   * top-to-bottom by how often you type a thing without anyone arranging the list.\n   */\n  readonly occasional?: readonly string[];\n  /**\n   * The verb's own section of the help — a heading and its body, already indented.\n   * Two verbs may declare the same heading (`retrieve` and `stats` share RETRIEVE &\n   * STATS, because the loop is one story); their bodies are joined under it in\n   * registry order.\n   */\n  readonly section?: { readonly heading: string; readonly body: string };\n}\n\n/**\n * One subcommand: everything the CLI knows about one verb, in one place.\n *\n * This is the seam the CLI was missing. A verb used to be a *shape* restated in four\n * modules — an `*Invocation` interface and a `parse*Args` in `cli/args.ts`, a\n * `Resolved*Run` and a `resolve*` in `cli/resolve.ts`, a `case` and a `run*` in\n * `cli/run.ts`, plus a hand-written help block and a hand-written refusal for every\n * flag it did not want. The refusals were the compounding cost: because no verb owned\n * its flags, every verb refused every other verb's flags by hand, so an eleventh flag\n * edited five messages.\n *\n * Now a verb is one file exporting one of these, and `SUBCOMMANDS` in `./registry.ts`\n * is `Record<Verb, …>` — the {@link LANGUAGE_PROFILES} / {@link HARNESS_PROFILES}\n * pattern, so totality is a compile error and every rendered list (USAGE, the sections,\n * the `map only.` prefixes in OPTIONS) is a derived view.\n *\n * The type parameters are the verb's own two shapes, and they never merge:\n *\n * @typeParam I - what the verb's `parse` returns, e.g. `MapInvocation`. Pure data, so\n *   the parse is testable on its own.\n * @typeParam R - what its `resolve` returns, e.g. `ResolvedMapRun`. The verb's single\n *   merge of flags + config + built-ins, each value carrying its provenance. Deliberately\n *   one type per verb: `map` has no store, no strategy and no stdin, and a shared struct\n *   whose fields are lies for half its users is not a seam, it is a coincidence.\n */\nexport interface Subcommand<I, R> {\n  /** The word on the command line — and the registry key. `'smelt'` has no word. */\n  readonly name: Verb;\n  /**\n   * The flags this verb owns. **The whole point.** Every flag outside this list is\n   * refused by one generated message (`refuseForeignFlags` in `./registry.ts`) rather\n   * than by prose the next verb has to write again. A flag silently ignored would be a\n   * setting the user believed was in force.\n   */\n  readonly flags: readonly VerbFlag[];\n  /**\n   * What this verb *is*, as one sentence — the tail of the generated refusal, and the\n   * only part of it a verb writes. It answers \"why not here?\", which is the half of\n   * the old hand-written messages worth keeping; the offending flag, this verb's name\n   * and the verb the flag does belong to are all derived from the registry.\n   */\n  readonly refusal: string;\n  /** What this verb contributes to `--help`. Rendered, never hand-arranged. */\n  readonly usage: SubcommandUsage;\n  /**\n   * The verb's own validation, over the flags it owns and the positionals it was\n   * given (index 0 is the verb word itself, except for the default verb).\n   *\n   * @throws {CliUsageError} on anything the user got wrong. Never guesses.\n   */\n  parse(values: FlagValues, positionals: readonly string[]): I;\n  /**\n   * The verb's single merge of flags + config + built-ins. Precedence for this verb\n   * lives here and nowhere else, so a precedence question is answered by one function\n   * instead of by reading two files.\n   *\n   * @throws {CliUsageError} when a required value has no source — the budget, for the\n   *   two verbs that need one.\n   */\n  resolve(invocation: I, config: ConfigSource): R;\n  /** Execute the resolved run straight-line, and return the exit code. */\n  run(resolved: R, io: CliIo): number | Promise<number>;\n}\n"]}

package/dist/cli/subcommands/subcommand.js

@@ -0,0 +1,3 @@
+/** The verb a bare invocation selects — a file or stdin, with no subcommand word. */
+export const DEFAULT_VERB = 'smelt';
+//# sourceMappingURL=subcommand.js.map

package/dist/cli/subcommands/subcommand.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subcommand.js","sourceRoot":"","sources":["../../../src/cli/subcommands/subcommand.ts"],"names":[],"mappings":"AAeA,qFAAqF;AACrF,MAAM,CAAC,MAAM,YAAY,GAAG,OAAsB,CAAC","sourcesContent":["import type { LoadedConfig } from '../config.ts';\nimport type { CliIo } from '../shell.ts';\n\nimport type { FlagValues, VerbFlag } from './flags.ts';\n\n/**\n * The verbs `smelt` answers to. `'smelt'` is the default verb — the bare\n * `smelt <file>` / `smelt < input` run — and is the only one with no word on the\n * command line, which is why a file literally named `map` needs `./map`.\n *\n * Order is meaningful: it is the order `--help` renders every derived list in, and the\n * order a refusal names owners in. Keep it stable and append new verbs at the end.\n */\nexport type Verb = 'smelt' | 'init' | 'map' | 'retrieve' | 'stats' | 'hooks' | 'agents';\n\n/** The verb a bare invocation selects — a file or stdin, with no subcommand word. */\nexport const DEFAULT_VERB = 'smelt' satisfies Verb;\n\n/**\n * The nearest `smelt.config.json`, loaded on demand.\n *\n * A thunk rather than a value, because two verbs must **not** load it: `init` and\n * `hooks` read the config file themselves, with their own tolerance, and a wizard you\n * run to *fix* a malformed config cannot be a wizard that refuses to start because the\n * config is malformed. Loading eagerly in the dispatcher would quietly turn that into\n * a usage error.\n */\nexport type ConfigSource = () => LoadedConfig | undefined;\n\n/** What one verb contributes to `--help`. See `cli/usage.ts` for the rendering. */\nexport interface SubcommandUsage {\n  /**\n   * The command's everyday forms, rendered in the first block of USAGE in registry\n   * order. Each entry is the text *after* the CLI name.\n   */\n  readonly synopsis: readonly string[];\n  /**\n   * Forms rendered in the second block, after every command's everyday forms: the\n   * round trip (`--reconstruct`) and the one-time setup (`init`) — jobs you do\n   * occasionally rather than the shape of a normal run. It keeps USAGE reading\n   * top-to-bottom by how often you type a thing without anyone arranging the list.\n   */\n  readonly occasional?: readonly string[];\n  /**\n   * The verb's own section of the help — a heading and its body, already indented.\n   * Two verbs may declare the same heading (`retrieve` and `stats` share RETRIEVE &\n   * STATS, because the loop is one story); their bodies are joined under it in\n   * registry order.\n   */\n  readonly section?: { readonly heading: string; readonly body: string };\n}\n\n/**\n * One subcommand: everything the CLI knows about one verb, in one place.\n *\n * This is the seam the CLI was missing. A verb used to be a *shape* restated in four\n * modules — an `*Invocation` interface and a `parse*Args` in `cli/args.ts`, a\n * `Resolved*Run` and a `resolve*` in `cli/resolve.ts`, a `case` and a `run*` in\n * `cli/run.ts`, plus a hand-written help block and a hand-written refusal for every\n * flag it did not want. The refusals were the compounding cost: because no verb owned\n * its flags, every verb refused every other verb's flags by hand, so an eleventh flag\n * edited five messages.\n *\n * Now a verb is one file exporting one of these, and `SUBCOMMANDS` in `./registry.ts`\n * is `Record<Verb, …>` — the {@link LANGUAGE_PROFILES} / {@link HARNESS_PROFILES}\n * pattern, so totality is a compile error and every rendered list (USAGE, the sections,\n * the `map only.` prefixes in OPTIONS) is a derived view.\n *\n * The type parameters are the verb's own two shapes, and they never merge:\n *\n * @typeParam I - what the verb's `parse` returns, e.g. `MapInvocation`. Pure data, so\n *   the parse is testable on its own.\n * @typeParam R - what its `resolve` returns, e.g. `ResolvedMapRun`. The verb's single\n *   merge of flags + config + built-ins, each value carrying its provenance. Deliberately\n *   one type per verb: `map` has no store, no strategy and no stdin, and a shared struct\n *   whose fields are lies for half its users is not a seam, it is a coincidence.\n */\nexport interface Subcommand<I, R> {\n  /** The word on the command line — and the registry key. `'smelt'` has no word. */\n  readonly name: Verb;\n  /**\n   * The flags this verb owns. **The whole point.** Every flag outside this list is\n   * refused by one generated message (`refuseForeignFlags` in `./registry.ts`) rather\n   * than by prose the next verb has to write again. A flag silently ignored would be a\n   * setting the user believed was in force.\n   */\n  readonly flags: readonly VerbFlag[];\n  /**\n   * What this verb *is*, as one sentence — the tail of the generated refusal, and the\n   * only part of it a verb writes. It answers \"why not here?\", which is the half of\n   * the old hand-written messages worth keeping; the offending flag, this verb's name\n   * and the verb the flag does belong to are all derived from the registry.\n   */\n  readonly refusal: string;\n  /** What this verb contributes to `--help`. Rendered, never hand-arranged. */\n  readonly usage: SubcommandUsage;\n  /**\n   * The verb's own validation, over the flags it owns and the positionals it was\n   * given (index 0 is the verb word itself, except for the default verb).\n   *\n   * @throws {CliUsageError} on anything the user got wrong. Never guesses.\n   */\n  parse(values: FlagValues, positionals: readonly string[]): I;\n  /**\n   * The verb's single merge of flags + config + built-ins. Precedence for this verb\n   * lives here and nowhere else, so a precedence question is answered by one function\n   * instead of by reading two files.\n   *\n   * @throws {CliUsageError} when a required value has no source — the budget, for the\n   *   two verbs that need one.\n   */\n  resolve(invocation: I, config: ConfigSource): R;\n  /** Execute the resolved run straight-line, and return the exit code. */\n  run(resolved: R, io: CliIo): number | Promise<number>;\n}\n"]}

package/dist/cli/usage.d.ts

@@ -0,0 +1,3 @@
+/** The help text. Also the closest thing the CLI has to documentation. */
+export declare function cliUsage(): string;
+//# sourceMappingURL=usage.d.ts.map

package/dist/cli/usage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage.d.ts","sourceRoot":"","sources":["../../src/cli/usage.ts"],"names":[],"mappings":"AA2EA,0EAA0E;AAC1E,wBAAgB,QAAQ,IAAI,MAAM,CAsBjC","sourcesContent":["import { CLI_NAME } from './shell.ts';\nimport { CLI_FLAGS, FLAG_HELP } from './subcommands/flags.ts';\nimport type { FlagName } from './subcommands/flags.ts';\nimport { ownersOf, SUBCOMMAND_LIST } from './subcommands/registry.ts';\nimport { DEFAULT_VERB } from './subcommands/subcommand.ts';\n\n/**\n * The help text — rendered from the registries, never hand-arranged.\n *\n * `--strategy` has rendered `STRATEGIES` and `--harness` `HARNESS_PROFILES` for a\n * while; this module finishes the job for the rest of the page. Every subcommand's\n * USAGE line, its section, and the `map only.` / `hooks only.` prefix on the flags it\n * owns come from `SUBCOMMANDS` and `CLI_FLAGS`, so a seventh verb or an eleventh flag\n * reaches the help by existing. The help text is also the closest thing the CLI has to\n * documentation, which is exactly why it must not be able to fall behind the parser.\n *\n * `test/__snapshots__/cli-usage.help.txt` pins the rendered bytes: a help change is a\n * reviewable diff, not a thing that happens.\n */\n\n/** The column an OPTIONS entry's description starts at. */\nconst OPTION_INDENT = ' '.repeat(23);\n\n/** The USAGE block: every command's everyday forms, then the occasional ones. */\nfunction renderSynopsis(): string {\n  const everyday = SUBCOMMAND_LIST.flatMap((command) => command.usage.synopsis);\n  const occasional = SUBCOMMAND_LIST.flatMap((command) => command.usage.occasional ?? []);\n  return [...everyday, ...occasional].map((form) => `  ${CLI_NAME} ${form}`).join('\\n');\n}\n\n/**\n * The named sections, in registry order. Two verbs may declare the same heading —\n * `retrieve` and `stats` share RETRIEVE & STATS, because the loop is one story — and\n * their bodies are joined under the single heading rather than repeating it.\n */\nfunction renderSections(): string {\n  const sections = new Map<string, string[]>();\n  for (const command of SUBCOMMAND_LIST) {\n    const section = command.usage.section;\n    if (section === undefined) continue;\n    const bodies = sections.get(section.heading);\n    if (bodies === undefined) sections.set(section.heading, [section.body]);\n    else bodies.push(section.body);\n  }\n  return [...sections]\n    .map(([heading, bodies]) => `${heading}\\n${bodies.join('\\n\\n')}`)\n    .join('\\n\\n');\n}\n\n/**\n * The OPTIONS block. The description is the flag's own; the ownership sentence in\n * front of it is generated — a flag exactly one *named* verb owns reads `map only.`\n * or `hooks only.`, and one the default verb or several verbs share reads nothing,\n * because \"which verb owns this flag\" is a fact the registry already holds.\n */\nfunction renderOptions(): string {\n  return (Object.keys(CLI_FLAGS) as FlagName[])\n    .map((name) => {\n      const help = FLAG_HELP[name];\n      const [first, ...rest] = [`${ownedBy(name)}${help.body()[0] ?? ''}`, ...help.body().slice(1)];\n      return [\n        `  ${help.label.padEnd(21)}${first ?? ''}`,\n        ...rest.map((line) => `${OPTION_INDENT}${line}`),\n      ].join('\\n');\n    })\n    .join('\\n');\n}\n\n/** `map only. ` for a flag one named verb owns alone; nothing for anything else. */\nfunction ownedBy(name: FlagName): string {\n  const owners = ownersOf(name);\n  const only = owners.length === 1 ? owners[0] : undefined;\n  return only === undefined || only.name === DEFAULT_VERB ? '' : `${only.name} only. `;\n}\n\n/** The help text. Also the closest thing the CLI has to documentation. */\nexport function cliUsage(): string {\n  return `${CLI_NAME} — shrink text for a model, without lying about what was removed.\n\nUSAGE\n${renderSynopsis()}\n\nSmelted text goes to stdout and the report goes to stderr, so the two can be piped\napart:  ${CLI_NAME} big.log --budget 4000 > small.log\n\n${renderSections()}\n\nOPTIONS\n${renderOptions()}\n\nEXIT CODES\n  0  under budget (map is always under budget by construction)\n  1  over budget — the plan did not fit, and the report says so. Never silent.\n     map never exits 1; see MAP above.\n  2  usage error\n  3  ${CLI_NAME} refused (a SmeltError: an unbuilt planner, an unknown hash, a corrupt store)\n  4  unexpected internal error\n`;\n}\n"]}

package/dist/cli/usage.js

@@ -0,0 +1,95 @@
+import { CLI_NAME } from './shell.js';
+import { CLI_FLAGS, FLAG_HELP } from './subcommands/flags.js';
+import { ownersOf, SUBCOMMAND_LIST } from './subcommands/registry.js';
+import { DEFAULT_VERB } from './subcommands/subcommand.js';
+/**
+ * The help text — rendered from the registries, never hand-arranged.
+ *
+ * `--strategy` has rendered `STRATEGIES` and `--harness` `HARNESS_PROFILES` for a
+ * while; this module finishes the job for the rest of the page. Every subcommand's
+ * USAGE line, its section, and the `map only.` / `hooks only.` prefix on the flags it
+ * owns come from `SUBCOMMANDS` and `CLI_FLAGS`, so a seventh verb or an eleventh flag
+ * reaches the help by existing. The help text is also the closest thing the CLI has to
+ * documentation, which is exactly why it must not be able to fall behind the parser.
+ *
+ * `test/__snapshots__/cli-usage.help.txt` pins the rendered bytes: a help change is a
+ * reviewable diff, not a thing that happens.
+ */
+/** The column an OPTIONS entry's description starts at. */
+const OPTION_INDENT = ' '.repeat(23);
+/** The USAGE block: every command's everyday forms, then the occasional ones. */
+function renderSynopsis() {
+    const everyday = SUBCOMMAND_LIST.flatMap((command) => command.usage.synopsis);
+    const occasional = SUBCOMMAND_LIST.flatMap((command) => command.usage.occasional ?? []);
+    return [...everyday, ...occasional].map((form) => `  ${CLI_NAME} ${form}`).join('\n');
+}
+/**
+ * The named sections, in registry order. Two verbs may declare the same heading —
+ * `retrieve` and `stats` share RETRIEVE & STATS, because the loop is one story — and
+ * their bodies are joined under the single heading rather than repeating it.
+ */
+function renderSections() {
+    const sections = new Map();
+    for (const command of SUBCOMMAND_LIST) {
+        const section = command.usage.section;
+        if (section === undefined)
+            continue;
+        const bodies = sections.get(section.heading);
+        if (bodies === undefined)
+            sections.set(section.heading, [section.body]);
+        else
+            bodies.push(section.body);
+    }
+    return [...sections]
+        .map(([heading, bodies]) => `${heading}\n${bodies.join('\n\n')}`)
+        .join('\n\n');
+}
+/**
+ * The OPTIONS block. The description is the flag's own; the ownership sentence in
+ * front of it is generated — a flag exactly one *named* verb owns reads `map only.`
+ * or `hooks only.`, and one the default verb or several verbs share reads nothing,
+ * because "which verb owns this flag" is a fact the registry already holds.
+ */
+function renderOptions() {
+    return Object.keys(CLI_FLAGS)
+        .map((name) => {
+        const help = FLAG_HELP[name];
+        const [first, ...rest] = [`${ownedBy(name)}${help.body()[0] ?? ''}`, ...help.body().slice(1)];
+        return [
+            `  ${help.label.padEnd(21)}${first ?? ''}`,
+            ...rest.map((line) => `${OPTION_INDENT}${line}`),
+        ].join('\n');
+    })
+        .join('\n');
+}
+/** `map only. ` for a flag one named verb owns alone; nothing for anything else. */
+function ownedBy(name) {
+    const owners = ownersOf(name);
+    const only = owners.length === 1 ? owners[0] : undefined;
+    return only === undefined || only.name === DEFAULT_VERB ? '' : `${only.name} only. `;
+}
+/** The help text. Also the closest thing the CLI has to documentation. */
+export function cliUsage() {
+    return `${CLI_NAME} — shrink text for a model, without lying about what was removed.
+
+USAGE
+${renderSynopsis()}
+
+Smelted text goes to stdout and the report goes to stderr, so the two can be piped
+apart:  ${CLI_NAME} big.log --budget 4000 > small.log
+
+${renderSections()}
+
+OPTIONS
+${renderOptions()}
+
+EXIT CODES
+  0  under budget (map is always under budget by construction)
+  1  over budget — the plan did not fit, and the report says so. Never silent.
+     map never exits 1; see MAP above.
+  2  usage error
+  3  ${CLI_NAME} refused (a SmeltError: an unbuilt planner, an unknown hash, a corrupt store)
+  4  unexpected internal error
+`;
+}
+//# sourceMappingURL=usage.js.map

package/dist/cli/usage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage.js","sourceRoot":"","sources":["../../src/cli/usage.ts"],"names":[],"mappings":"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","sourcesContent":["import { CLI_NAME } from './shell.ts';\nimport { CLI_FLAGS, FLAG_HELP } from './subcommands/flags.ts';\nimport type { FlagName } from './subcommands/flags.ts';\nimport { ownersOf, SUBCOMMAND_LIST } from './subcommands/registry.ts';\nimport { DEFAULT_VERB } from './subcommands/subcommand.ts';\n\n/**\n * The help text — rendered from the registries, never hand-arranged.\n *\n * `--strategy` has rendered `STRATEGIES` and `--harness` `HARNESS_PROFILES` for a\n * while; this module finishes the job for the rest of the page. Every subcommand's\n * USAGE line, its section, and the `map only.` / `hooks only.` prefix on the flags it\n * owns come from `SUBCOMMANDS` and `CLI_FLAGS`, so a seventh verb or an eleventh flag\n * reaches the help by existing. The help text is also the closest thing the CLI has to\n * documentation, which is exactly why it must not be able to fall behind the parser.\n *\n * `test/__snapshots__/cli-usage.help.txt` pins the rendered bytes: a help change is a\n * reviewable diff, not a thing that happens.\n */\n\n/** The column an OPTIONS entry's description starts at. */\nconst OPTION_INDENT = ' '.repeat(23);\n\n/** The USAGE block: every command's everyday forms, then the occasional ones. */\nfunction renderSynopsis(): string {\n  const everyday = SUBCOMMAND_LIST.flatMap((command) => command.usage.synopsis);\n  const occasional = SUBCOMMAND_LIST.flatMap((command) => command.usage.occasional ?? []);\n  return [...everyday, ...occasional].map((form) => `  ${CLI_NAME} ${form}`).join('\\n');\n}\n\n/**\n * The named sections, in registry order. Two verbs may declare the same heading —\n * `retrieve` and `stats` share RETRIEVE & STATS, because the loop is one story — and\n * their bodies are joined under the single heading rather than repeating it.\n */\nfunction renderSections(): string {\n  const sections = new Map<string, string[]>();\n  for (const command of SUBCOMMAND_LIST) {\n    const section = command.usage.section;\n    if (section === undefined) continue;\n    const bodies = sections.get(section.heading);\n    if (bodies === undefined) sections.set(section.heading, [section.body]);\n    else bodies.push(section.body);\n  }\n  return [...sections]\n    .map(([heading, bodies]) => `${heading}\\n${bodies.join('\\n\\n')}`)\n    .join('\\n\\n');\n}\n\n/**\n * The OPTIONS block. The description is the flag's own; the ownership sentence in\n * front of it is generated — a flag exactly one *named* verb owns reads `map only.`\n * or `hooks only.`, and one the default verb or several verbs share reads nothing,\n * because \"which verb owns this flag\" is a fact the registry already holds.\n */\nfunction renderOptions(): string {\n  return (Object.keys(CLI_FLAGS) as FlagName[])\n    .map((name) => {\n      const help = FLAG_HELP[name];\n      const [first, ...rest] = [`${ownedBy(name)}${help.body()[0] ?? ''}`, ...help.body().slice(1)];\n      return [\n        `  ${help.label.padEnd(21)}${first ?? ''}`,\n        ...rest.map((line) => `${OPTION_INDENT}${line}`),\n      ].join('\\n');\n    })\n    .join('\\n');\n}\n\n/** `map only. ` for a flag one named verb owns alone; nothing for anything else. */\nfunction ownedBy(name: FlagName): string {\n  const owners = ownersOf(name);\n  const only = owners.length === 1 ? owners[0] : undefined;\n  return only === undefined || only.name === DEFAULT_VERB ? '' : `${only.name} only. `;\n}\n\n/** The help text. Also the closest thing the CLI has to documentation. */\nexport function cliUsage(): string {\n  return `${CLI_NAME} — shrink text for a model, without lying about what was removed.\n\nUSAGE\n${renderSynopsis()}\n\nSmelted text goes to stdout and the report goes to stderr, so the two can be piped\napart:  ${CLI_NAME} big.log --budget 4000 > small.log\n\n${renderSections()}\n\nOPTIONS\n${renderOptions()}\n\nEXIT CODES\n  0  under budget (map is always under budget by construction)\n  1  over budget — the plan did not fit, and the report says so. Never silent.\n     map never exits 1; see MAP above.\n  2  usage error\n  3  ${CLI_NAME} refused (a SmeltError: an unbuilt planner, an unknown hash, a corrupt store)\n  4  unexpected internal error\n`;\n}\n"]}

package/dist/detect.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"detect.d.ts","sourceRoot":"","sources":["../src/detect.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE/D;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,EAAE,SAAS,UAAU,EAEpD,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,gBAAgB,CAEzE"}
+{"version":3,"file":"detect.d.ts","sourceRoot":"","sources":["../src/detect.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE/D;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,EAAE,SAAS,UAAU,EAEpD,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,gBAAgB,CAEzE","sourcesContent":["import { LANGUAGE_PROFILES, profileForPath } from './lang/registry.ts';\nimport type { DetectedLanguage, LanguageId } from './types.ts';\n\n/**\n * Every language smelt has a grammar mapping for — the registry's ids, in registry\n * order. A derived view of `LANGUAGE_PROFILES`, kept as an export because tests and\n * the CLI's rendered lists read it.\n */\nexport const SUPPORTED_LANGUAGES: readonly LanguageId[] = Object.values(LANGUAGE_PROFILES).map(\n  (profile) => profile.id,\n);\n\n/**\n * Detect the language of a path, from its extension. Returns `'unknown'` for anything\n * unmapped — which is a normal outcome, not an error: it selects the lexical planner,\n * which works on anything. The extension → profile mapping itself lives on each\n * language's `LanguageProfile` (`src/lang/`); this is the id-shaped view of\n * {@link profileForPath}.\n */\nexport function detectLanguage(path: string | undefined): DetectedLanguage {\n  return profileForPath(path)?.id ?? 'unknown';\n}\n"]}

package/dist/detect.js.map

@@ -1 +1 @@
-{"version":3,"file":"detect.js","sourceRoot":"","sources":["../src/detect.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAGvE;;;;GAIG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAA0B,MAAM,CAAC,MAAM,CAAC,iBAAiB,CAAC,CAAC,GAAG,CAC5F,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,EAAE,CACxB,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,IAAwB;IACrD,OAAO,cAAc,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,SAAS,CAAC;AAC/C,CAAC"}
+{"version":3,"file":"detect.js","sourceRoot":"","sources":["../src/detect.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAGvE;;;;GAIG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAA0B,MAAM,CAAC,MAAM,CAAC,iBAAiB,CAAC,CAAC,GAAG,CAC5F,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,EAAE,CACxB,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,IAAwB;IACrD,OAAO,cAAc,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,SAAS,CAAC;AAC/C,CAAC","sourcesContent":["import { LANGUAGE_PROFILES, profileForPath } from './lang/registry.ts';\nimport type { DetectedLanguage, LanguageId } from './types.ts';\n\n/**\n * Every language smelt has a grammar mapping for — the registry's ids, in registry\n * order. A derived view of `LANGUAGE_PROFILES`, kept as an export because tests and\n * the CLI's rendered lists read it.\n */\nexport const SUPPORTED_LANGUAGES: readonly LanguageId[] = Object.values(LANGUAGE_PROFILES).map(\n  (profile) => profile.id,\n);\n\n/**\n * Detect the language of a path, from its extension. Returns `'unknown'` for anything\n * unmapped — which is a normal outcome, not an error: it selects the lexical planner,\n * which works on anything. The extension → profile mapping itself lives on each\n * language's `LanguageProfile` (`src/lang/`); this is the id-shaped view of\n * {@link profileForPath}.\n */\nexport function detectLanguage(path: string | undefined): DetectedLanguage {\n  return profileForPath(path)?.id ?? 'unknown';\n}\n"]}

package/dist/errors.d.ts

@@ -16,7 +16,7 @@ export declare class NotImplementedError extends SmeltError {
 }
 /**
  * Thrown when something in the elision path tried to reach a non-local resource.
- * v1 has no network. See docs/HANDOFF.md § "Law 1 — zero network".
+ * v1 has no network. See docs/ARCHITECTURE.md § "Law 1 — zero network".
  */
 export declare class NetworkPolicyError extends SmeltError {
     readonly name = "NetworkPolicyError";
@@ -85,4 +85,24 @@ export declare class StoreCorruptionError extends SmeltError {
 export declare class StoreFormatError extends SmeltError {
     readonly name = "StoreFormatError";
 }
+/**
+ * A filesystem call the repo map made failed: a root that is not there, a directory
+ * that cannot be listed, a file that cannot be read, a cache entry that cannot be
+ * written.
+ *
+ * It exists because of a hole in the one promise the consumer contract makes about
+ * errors — **every error smelt throws is an `instanceof SmeltError`**.
+ * `buildRepoMap({ root: '/nonexistent' })` used to throw the raw `ENOENT` that
+ * `readdirSync` raises, so a caller doing precisely what the documentation says still
+ * had a bare `Error` escaping past its `catch`. The guarantee is worth nothing with an
+ * exception to it, so every `node:fs` call under `src/repomap/` now arrives here.
+ *
+ * The message names the path, because "ENOENT" without one is a bug report nobody can
+ * act on, and the original error is kept as `cause`: wrapping is meant to bring the
+ * failure inside the contract, never to hide what Node said.
+ */
+export declare class RepoMapIoError extends SmeltError {
+    readonly name = "RepoMapIoError";
+    constructor(operation: string, path: string, cause: unknown);
+}
 //# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,qBAAa,UAAW,SAAQ,KAAK;IACnC,SAAkB,IAAI,EAAE,MAAM,CAAgB;CAC/C;AAED;;;;GAIG;AACH,qBAAa,mBAAoB,SAAQ,UAAU;IACjD,SAAkB,IAAI,yBAAyB;IAE/C,YAAY,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAKxC;CACF;AAED;;;GAGG;AACH,qBAAa,kBAAmB,SAAQ,UAAU;IAChD,SAAkB,IAAI,wBAAwB;IAE9C,YAAY,OAAO,EAAE,MAAM,EAE1B;CACF;AAED,0FAA0F;AAC1F,qBAAa,uBAAwB,SAAQ,UAAU;IACrD,SAAkB,IAAI,6BAA6B;CACpD;AAED,mEAAmE;AACnE,qBAAa,qBAAsB,SAAQ,UAAU;IACnD,SAAkB,IAAI,2BAA2B;CAClD;AAED,uEAAuE;AACvE,qBAAa,uBAAwB,SAAQ,UAAU;IACrD,SAAkB,IAAI,6BAA6B;CACpD;AAED,uEAAuE;AACvE,qBAAa,gBAAiB,SAAQ,UAAU;IAC9C,SAAkB,IAAI,sBAAsB;IAE5C,YAAY,IAAI,EAAE,MAAM,EAIvB;CACF;AAED;;;;;GAKG;AACH,qBAAa,yBAA0B,SAAQ,UAAU;IACvD,SAAkB,IAAI,+BAA+B;IAErD,YAAY,SAAS,EAAE,MAAM,EAO5B;CACF;AAED;;;;GAIG;AACH,qBAAa,aAAc,SAAQ,UAAU;IAC3C,SAAkB,IAAI,mBAAmB;CAC1C;AAED;;;;GAIG;AACH,qBAAa,kBAAmB,SAAQ,UAAU;IAChD,SAAkB,IAAI,wBAAwB;IAE9C,YAAY,IAAI,EAAE,MAAM,EAKvB;CACF;AAED;;;;;;GAMG;AACH,qBAAa,oBAAqB,SAAQ,UAAU;IAClD,SAAkB,IAAI,0BAA0B;IAEhD,YAAY,IAAI,EAAE,MAAM,EAMvB;CACF;AAED;;;;GAIG;AACH,qBAAa,gBAAiB,SAAQ,UAAU;IAC9C,SAAkB,IAAI,sBAAsB;CAC7C"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,qBAAa,UAAW,SAAQ,KAAK;IACnC,SAAkB,IAAI,EAAE,MAAM,CAAgB;CAC/C;AAED;;;;GAIG;AACH,qBAAa,mBAAoB,SAAQ,UAAU;IACjD,SAAkB,IAAI,yBAAyB;IAE/C,YAAY,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAKxC;CACF;AAED;;;GAGG;AACH,qBAAa,kBAAmB,SAAQ,UAAU;IAChD,SAAkB,IAAI,wBAAwB;IAE9C,YAAY,OAAO,EAAE,MAAM,EAE1B;CACF;AAED,0FAA0F;AAC1F,qBAAa,uBAAwB,SAAQ,UAAU;IACrD,SAAkB,IAAI,6BAA6B;CACpD;AAED,mEAAmE;AACnE,qBAAa,qBAAsB,SAAQ,UAAU;IACnD,SAAkB,IAAI,2BAA2B;CAClD;AAED,uEAAuE;AACvE,qBAAa,uBAAwB,SAAQ,UAAU;IACrD,SAAkB,IAAI,6BAA6B;CACpD;AAED,uEAAuE;AACvE,qBAAa,gBAAiB,SAAQ,UAAU;IAC9C,SAAkB,IAAI,sBAAsB;IAE5C,YAAY,IAAI,EAAE,MAAM,EAIvB;CACF;AAED;;;;;GAKG;AACH,qBAAa,yBAA0B,SAAQ,UAAU;IACvD,SAAkB,IAAI,+BAA+B;IAErD,YAAY,SAAS,EAAE,MAAM,EAO5B;CACF;AAED;;;;GAIG;AACH,qBAAa,aAAc,SAAQ,UAAU;IAC3C,SAAkB,IAAI,mBAAmB;CAC1C;AAED;;;;GAIG;AACH,qBAAa,kBAAmB,SAAQ,UAAU;IAChD,SAAkB,IAAI,wBAAwB;IAE9C,YAAY,IAAI,EAAE,MAAM,EAKvB;CACF;AAED;;;;;;GAMG;AACH,qBAAa,oBAAqB,SAAQ,UAAU;IAClD,SAAkB,IAAI,0BAA0B;IAEhD,YAAY,IAAI,EAAE,MAAM,EAMvB;CACF;AAED;;;;GAIG;AACH,qBAAa,gBAAiB,SAAQ,UAAU;IAC9C,SAAkB,IAAI,sBAAsB;CAC7C;AAED;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,cAAe,SAAQ,UAAU;IAC5C,SAAkB,IAAI,oBAAoB;IAE1C,YAAY,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAM1D;CACF","sourcesContent":["/**\n * Every error smelt throws is one of these. Consumers can `instanceof SmeltError`\n * to tell \"the library said no\" apart from \"something else blew up\".\n */\nexport class SmeltError extends Error {\n  override readonly name: string = 'SmeltError';\n}\n\n/**\n * A scaffold stub. It throws instead of returning a plausible-looking wrong answer,\n * because a context optimizer that quietly returns bad output is indistinguishable\n * from one that works. See CONTRIBUTING.md § \"Silence is the enemy\".\n */\nexport class NotImplementedError extends SmeltError {\n  override readonly name = 'NotImplementedError';\n\n  constructor(what: string, seeAlso: string) {\n    super(\n      `smelt: ${what} is not implemented yet. This is a scaffold stub — it throws rather ` +\n        `than returning a plausible wrong answer. See ${seeAlso}.`,\n    );\n  }\n}\n\n/**\n * Thrown when something in the elision path tried to reach a non-local resource.\n * v1 has no network. See docs/ARCHITECTURE.md § \"Law 1 — zero network\".\n */\nexport class NetworkPolicyError extends SmeltError {\n  override readonly name = 'NetworkPolicyError';\n\n  constructor(message: string) {\n    super(`smelt: ${message}`);\n  }\n}\n\n/** A plan asked to elide two overlapping ranges. Applying it would corrupt the output. */\nexport class OverlappingElisionError extends SmeltError {\n  override readonly name = 'OverlappingElisionError';\n}\n\n/** A plan referenced a byte range that is not inside the input. */\nexport class RangeOutOfBoundsError extends SmeltError {\n  override readonly name = 'RangeOutOfBoundsError';\n}\n\n/** A grammar was requested that is not installed or not registered. */\nexport class GrammarUnavailableError extends SmeltError {\n  override readonly name = 'GrammarUnavailableError';\n}\n\n/** `retrieve(hash)` was called with a hash the store does not hold. */\nexport class UnknownHashError extends SmeltError {\n  override readonly name = 'UnknownHashError';\n\n  constructor(hash: string) {\n    super(\n      `smelt: no stored content for hash \"${hash}\". It was never elided, or the store was reset.`,\n    );\n  }\n}\n\n/**\n * A planner was handed a `PlanInput` without `pricing`. The type makes `pricing`\n * required, so TypeScript callers cannot get here; a JS caller can, and the honest\n * answer is this error rather than a guessed marker cost — a planner pricing markers\n * itself is exactly the inversion the MarkerPricing seam removed.\n */\nexport class MissingMarkerPricingError extends SmeltError {\n  override readonly name = 'MissingMarkerPricingError';\n\n  constructor(plannerId: string) {\n    super(\n      `smelt: ${plannerId} was handed a PlanInput without \\`pricing\\`. A planner never ` +\n        `guesses what a marker costs — the applier renders markers, so the applier ` +\n        `prices them. Build one with markerPricing(language, marker) from apply.ts and ` +\n        `put it on the input; createSmelter and the CLI construct it centrally.`,\n    );\n  }\n}\n\n/**\n * The CLI was invoked wrongly — a missing `--budget`, an unknown flag, a budget that\n * is not a number. Distinct from every other `SmeltError` so the CLI can exit with a\n * usage code rather than pretending the library refused.\n */\nexport class CliUsageError extends SmeltError {\n  override readonly name = 'CliUsageError';\n}\n\n/**\n * Two different blobs hashed to the same key. Astronomically unlikely, and yet: the\n * alternative to throwing is handing the model the wrong bytes and calling it a\n * retrieval, which is precisely the silent failure this library exists to avoid.\n */\nexport class HashCollisionError extends SmeltError {\n  override readonly name = 'HashCollisionError';\n\n  constructor(hash: string) {\n    super(\n      `smelt: hash collision on \"${hash}\" — two different blobs share a key. Refusing to ` +\n        `store, because retrieving would return the wrong bytes. Please report this.`,\n    );\n  }\n}\n\n/**\n * A persistent store holds bytes under this hash, but they no longer hash to it — a\n * torn write, a truncation, an edit behind the store's back. Deliberately distinct from\n * {@link UnknownHashError}: \"we hold damaged bytes\" and \"never existed\" call for\n * different responses, and returning the damaged bytes as a retrieval would be the\n * silent wrong answer this library exists to refuse.\n */\nexport class StoreCorruptionError extends SmeltError {\n  override readonly name = 'StoreCorruptionError';\n\n  constructor(hash: string) {\n    super(\n      `smelt: the bytes stored under hash \"${hash}\" do not hash to \"${hash}\". Refusing ` +\n        `to return them — they are damaged, not merely unknown. The store directory was ` +\n        `truncated or edited outside smelt.`,\n    );\n  }\n}\n\n/**\n * A directory offered as a persistent store carries a format marker this version of\n * smelt does not understand — or no parseable marker at all. Refusing beats guessing:\n * reinterpreting an unknown layout could hand back the wrong bytes with no error.\n */\nexport class StoreFormatError extends SmeltError {\n  override readonly name = 'StoreFormatError';\n}\n\n/**\n * A filesystem call the repo map made failed: a root that is not there, a directory\n * that cannot be listed, a file that cannot be read, a cache entry that cannot be\n * written.\n *\n * It exists because of a hole in the one promise the consumer contract makes about\n * errors — **every error smelt throws is an `instanceof SmeltError`**.\n * `buildRepoMap({ root: '/nonexistent' })` used to throw the raw `ENOENT` that\n * `readdirSync` raises, so a caller doing precisely what the documentation says still\n * had a bare `Error` escaping past its `catch`. The guarantee is worth nothing with an\n * exception to it, so every `node:fs` call under `src/repomap/` now arrives here.\n *\n * The message names the path, because \"ENOENT\" without one is a bug report nobody can\n * act on, and the original error is kept as `cause`: wrapping is meant to bring the\n * failure inside the contract, never to hide what Node said.\n */\nexport class RepoMapIoError extends SmeltError {\n  override readonly name = 'RepoMapIoError';\n\n  constructor(operation: string, path: string, cause: unknown) {\n    super(\n      `smelt: could not ${operation} \"${path}\" while building the repo map: ` +\n        `${describeIoCause(cause)}.`,\n      { cause },\n    );\n  }\n}\n\n/** The `errno` code when Node supplied one, its message otherwise. Never invented. */\nfunction describeIoCause(cause: unknown): string {\n  const code = (cause as { code?: string } | null | undefined)?.code;\n  if (typeof code === 'string' && code !== '') return code;\n  if (cause instanceof Error && cause.message !== '') return cause.message;\n  return String(cause);\n}\n"]}

package/dist/errors.js

@@ -19,7 +19,7 @@ export class NotImplementedError extends SmeltError {
 }
 /**
  * Thrown when something in the elision path tried to reach a non-local resource.
- * v1 has no network. See docs/HANDOFF.md § "Law 1 — zero network".
+ * v1 has no network. See docs/ARCHITECTURE.md § "Law 1 — zero network".
  */
 export class NetworkPolicyError extends SmeltError {
     name = 'NetworkPolicyError';
@@ -104,4 +104,36 @@ export class StoreCorruptionError extends SmeltError {
 export class StoreFormatError extends SmeltError {
     name = 'StoreFormatError';
 }
+/**
+ * A filesystem call the repo map made failed: a root that is not there, a directory
+ * that cannot be listed, a file that cannot be read, a cache entry that cannot be
+ * written.
+ *
+ * It exists because of a hole in the one promise the consumer contract makes about
+ * errors — **every error smelt throws is an `instanceof SmeltError`**.
+ * `buildRepoMap({ root: '/nonexistent' })` used to throw the raw `ENOENT` that
+ * `readdirSync` raises, so a caller doing precisely what the documentation says still
+ * had a bare `Error` escaping past its `catch`. The guarantee is worth nothing with an
+ * exception to it, so every `node:fs` call under `src/repomap/` now arrives here.
+ *
+ * The message names the path, because "ENOENT" without one is a bug report nobody can
+ * act on, and the original error is kept as `cause`: wrapping is meant to bring the
+ * failure inside the contract, never to hide what Node said.
+ */
+export class RepoMapIoError extends SmeltError {
+    name = 'RepoMapIoError';
+    constructor(operation, path, cause) {
+        super(`smelt: could not ${operation} "${path}" while building the repo map: ` +
+            `${describeIoCause(cause)}.`, { cause });
+    }
+}
+/** The `errno` code when Node supplied one, its message otherwise. Never invented. */
+function describeIoCause(cause) {
+    const code = cause?.code;
+    if (typeof code === 'string' && code !== '')
+        return code;
+    if (cause instanceof Error && cause.message !== '')
+        return cause.message;
+    return String(cause);
+}
 //# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,OAAO,UAAW,SAAQ,KAAK;IACjB,IAAI,GAAW,YAAY,CAAC;CAC/C;AAED;;;;GAIG;AACH,MAAM,OAAO,mBAAoB,SAAQ,UAAU;IAC/B,IAAI,GAAG,qBAAqB,CAAC;IAE/C,YAAY,IAAY,EAAE,OAAe;QACvC,KAAK,CACH,UAAU,IAAI,sEAAsE;YAClF,gDAAgD,OAAO,GAAG,CAC7D,CAAC;IACJ,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,kBAAmB,SAAQ,UAAU;IAC9B,IAAI,GAAG,oBAAoB,CAAC;IAE9C,YAAY,OAAe;QACzB,KAAK,CAAC,UAAU,OAAO,EAAE,CAAC,CAAC;IAC7B,CAAC;CACF;AAED,0FAA0F;AAC1F,MAAM,OAAO,uBAAwB,SAAQ,UAAU;IACnC,IAAI,GAAG,yBAAyB,CAAC;CACpD;AAED,mEAAmE;AACnE,MAAM,OAAO,qBAAsB,SAAQ,UAAU;IACjC,IAAI,GAAG,uBAAuB,CAAC;CAClD;AAED,uEAAuE;AACvE,MAAM,OAAO,uBAAwB,SAAQ,UAAU;IACnC,IAAI,GAAG,yBAAyB,CAAC;CACpD;AAED,uEAAuE;AACvE,MAAM,OAAO,gBAAiB,SAAQ,UAAU;IAC5B,IAAI,GAAG,kBAAkB,CAAC;IAE5C,YAAY,IAAY;QACtB,KAAK,CACH,sCAAsC,IAAI,iDAAiD,CAC5F,CAAC;IACJ,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,OAAO,yBAA0B,SAAQ,UAAU;IACrC,IAAI,GAAG,2BAA2B,CAAC;IAErD,YAAY,SAAiB;QAC3B,KAAK,CACH,UAAU,SAAS,+DAA+D;YAChF,4EAA4E;YAC5E,gFAAgF;YAChF,wEAAwE,CAC3E,CAAC;IACJ,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,OAAO,aAAc,SAAQ,UAAU;IACzB,IAAI,GAAG,eAAe,CAAC;CAC1C;AAED;;;;GAIG;AACH,MAAM,OAAO,kBAAmB,SAAQ,UAAU;IAC9B,IAAI,GAAG,oBAAoB,CAAC;IAE9C,YAAY,IAAY;QACtB,KAAK,CACH,6BAA6B,IAAI,mDAAmD;YAClF,6EAA6E,CAChF,CAAC;IACJ,CAAC;CACF;AAED;;;;;;GAMG;AACH,MAAM,OAAO,oBAAqB,SAAQ,UAAU;IAChC,IAAI,GAAG,sBAAsB,CAAC;IAEhD,YAAY,IAAY;QACtB,KAAK,CACH,uCAAuC,IAAI,qBAAqB,IAAI,cAAc;YAChF,iFAAiF;YACjF,oCAAoC,CACvC,CAAC;IACJ,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,OAAO,gBAAiB,SAAQ,UAAU;IAC5B,IAAI,GAAG,kBAAkB,CAAC;CAC7C"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Every error smelt throws is one of these. Consumers can `instanceof SmeltError`\n * to tell \"the library said no\" apart from \"something else blew up\".\n */\nexport class SmeltError extends Error {\n  override readonly name: string = 'SmeltError';\n}\n\n/**\n * A scaffold stub. It throws instead of returning a plausible-looking wrong answer,\n * because a context optimizer that quietly returns bad output is indistinguishable\n * from one that works. See CONTRIBUTING.md § \"Silence is the enemy\".\n */\nexport class NotImplementedError extends SmeltError {\n  override readonly name = 'NotImplementedError';\n\n  constructor(what: string, seeAlso: string) {\n    super(\n      `smelt: ${what} is not implemented yet. This is a scaffold stub — it throws rather ` +\n        `than returning a plausible wrong answer. See ${seeAlso}.`,\n    );\n  }\n}\n\n/**\n * Thrown when something in the elision path tried to reach a non-local resource.\n * v1 has no network. See docs/ARCHITECTURE.md § \"Law 1 — zero network\".\n */\nexport class NetworkPolicyError extends SmeltError {\n  override readonly name = 'NetworkPolicyError';\n\n  constructor(message: string) {\n    super(`smelt: ${message}`);\n  }\n}\n\n/** A plan asked to elide two overlapping ranges. Applying it would corrupt the output. */\nexport class OverlappingElisionError extends SmeltError {\n  override readonly name = 'OverlappingElisionError';\n}\n\n/** A plan referenced a byte range that is not inside the input. */\nexport class RangeOutOfBoundsError extends SmeltError {\n  override readonly name = 'RangeOutOfBoundsError';\n}\n\n/** A grammar was requested that is not installed or not registered. */\nexport class GrammarUnavailableError extends SmeltError {\n  override readonly name = 'GrammarUnavailableError';\n}\n\n/** `retrieve(hash)` was called with a hash the store does not hold. */\nexport class UnknownHashError extends SmeltError {\n  override readonly name = 'UnknownHashError';\n\n  constructor(hash: string) {\n    super(\n      `smelt: no stored content for hash \"${hash}\". It was never elided, or the store was reset.`,\n    );\n  }\n}\n\n/**\n * A planner was handed a `PlanInput` without `pricing`. The type makes `pricing`\n * required, so TypeScript callers cannot get here; a JS caller can, and the honest\n * answer is this error rather than a guessed marker cost — a planner pricing markers\n * itself is exactly the inversion the MarkerPricing seam removed.\n */\nexport class MissingMarkerPricingError extends SmeltError {\n  override readonly name = 'MissingMarkerPricingError';\n\n  constructor(plannerId: string) {\n    super(\n      `smelt: ${plannerId} was handed a PlanInput without \\`pricing\\`. A planner never ` +\n        `guesses what a marker costs — the applier renders markers, so the applier ` +\n        `prices them. Build one with markerPricing(language, marker) from apply.ts and ` +\n        `put it on the input; createSmelter and the CLI construct it centrally.`,\n    );\n  }\n}\n\n/**\n * The CLI was invoked wrongly — a missing `--budget`, an unknown flag, a budget that\n * is not a number. Distinct from every other `SmeltError` so the CLI can exit with a\n * usage code rather than pretending the library refused.\n */\nexport class CliUsageError extends SmeltError {\n  override readonly name = 'CliUsageError';\n}\n\n/**\n * Two different blobs hashed to the same key. Astronomically unlikely, and yet: the\n * alternative to throwing is handing the model the wrong bytes and calling it a\n * retrieval, which is precisely the silent failure this library exists to avoid.\n */\nexport class HashCollisionError extends SmeltError {\n  override readonly name = 'HashCollisionError';\n\n  constructor(hash: string) {\n    super(\n      `smelt: hash collision on \"${hash}\" — two different blobs share a key. Refusing to ` +\n        `store, because retrieving would return the wrong bytes. Please report this.`,\n    );\n  }\n}\n\n/**\n * A persistent store holds bytes under this hash, but they no longer hash to it — a\n * torn write, a truncation, an edit behind the store's back. Deliberately distinct from\n * {@link UnknownHashError}: \"we hold damaged bytes\" and \"never existed\" call for\n * different responses, and returning the damaged bytes as a retrieval would be the\n * silent wrong answer this library exists to refuse.\n */\nexport class StoreCorruptionError extends SmeltError {\n  override readonly name = 'StoreCorruptionError';\n\n  constructor(hash: string) {\n    super(\n      `smelt: the bytes stored under hash \"${hash}\" do not hash to \"${hash}\". Refusing ` +\n        `to return them — they are damaged, not merely unknown. The store directory was ` +\n        `truncated or edited outside smelt.`,\n    );\n  }\n}\n\n/**\n * A directory offered as a persistent store carries a format marker this version of\n * smelt does not understand — or no parseable marker at all. Refusing beats guessing:\n * reinterpreting an unknown layout could hand back the wrong bytes with no error.\n */\nexport class StoreFormatError extends SmeltError {\n  override readonly name = 'StoreFormatError';\n}\n\n/**\n * A filesystem call the repo map made failed: a root that is not there, a directory\n * that cannot be listed, a file that cannot be read, a cache entry that cannot be\n * written.\n *\n * It exists because of a hole in the one promise the consumer contract makes about\n * errors — **every error smelt throws is an `instanceof SmeltError`**.\n * `buildRepoMap({ root: '/nonexistent' })` used to throw the raw `ENOENT` that\n * `readdirSync` raises, so a caller doing precisely what the documentation says still\n * had a bare `Error` escaping past its `catch`. The guarantee is worth nothing with an\n * exception to it, so every `node:fs` call under `src/repomap/` now arrives here.\n *\n * The message names the path, because \"ENOENT\" without one is a bug report nobody can\n * act on, and the original error is kept as `cause`: wrapping is meant to bring the\n * failure inside the contract, never to hide what Node said.\n */\nexport class RepoMapIoError extends SmeltError {\n  override readonly name = 'RepoMapIoError';\n\n  constructor(operation: string, path: string, cause: unknown) {\n    super(\n      `smelt: could not ${operation} \"${path}\" while building the repo map: ` +\n        `${describeIoCause(cause)}.`,\n      { cause },\n    );\n  }\n}\n\n/** The `errno` code when Node supplied one, its message otherwise. Never invented. */\nfunction describeIoCause(cause: unknown): string {\n  const code = (cause as { code?: string } | null | undefined)?.code;\n  if (typeof code === 'string' && code !== '') return code;\n  if (cause instanceof Error && cause.message !== '') return cause.message;\n  return String(cause);\n}\n"]}

package/dist/harness/aider.d.ts

@@ -0,0 +1,10 @@
+import type { HarnessProfile } from './profile.ts';
+/**
+ * Aider — ADVISORY tier. Instructions only, and honest about it.
+ *
+ * No usable hook API, so the whole install is the shared snippet in `CONVENTIONS.md`
+ * and one caveat: Aider auto-reads no rules file, so the human has to point it at the
+ * conventions themselves. Nothing here is enforced, and the installer says so.
+ */
+export declare const aider: HarnessProfile;
+//# sourceMappingURL=aider.d.ts.map

package/dist/harness/aider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aider.d.ts","sourceRoot":"","sources":["../../src/harness/aider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEnD;;;;;;GAMG;AACH,eAAO,MAAM,KAAK,EAAE,cAYnB,CAAC","sourcesContent":["import type { HarnessProfile } from './profile.ts';\n\n/**\n * Aider — ADVISORY tier. Instructions only, and honest about it.\n *\n * No usable hook API, so the whole install is the shared snippet in `CONVENTIONS.md`\n * and one caveat: Aider auto-reads no rules file, so the human has to point it at the\n * conventions themselves. Nothing here is enforced, and the installer says so.\n */\nexport const aider: HarnessProfile = {\n  id: 'aider',\n  name: 'Aider',\n  tier: 'advisory',\n  detect: ['.aider.conf.yml'],\n  detectHome: ['.aider.conf.yml'],\n  instructionFile: 'CONVENTIONS.md',\n  instructions: 'snippet',\n  caveats: [\n    'Aider auto-reads no rules file: add `read: CONVENTIONS.md` to .aider.conf.yml (or pass --read CONVENTIONS.md) yourself',\n  ],\n  install: [],\n};\n"]}

package/dist/harness/aider.js

@@ -0,0 +1,21 @@
+/**
+ * Aider — ADVISORY tier. Instructions only, and honest about it.
+ *
+ * No usable hook API, so the whole install is the shared snippet in `CONVENTIONS.md`
+ * and one caveat: Aider auto-reads no rules file, so the human has to point it at the
+ * conventions themselves. Nothing here is enforced, and the installer says so.
+ */
+export const aider = {
+    id: 'aider',
+    name: 'Aider',
+    tier: 'advisory',
+    detect: ['.aider.conf.yml'],
+    detectHome: ['.aider.conf.yml'],
+    instructionFile: 'CONVENTIONS.md',
+    instructions: 'snippet',
+    caveats: [
+        'Aider auto-reads no rules file: add `read: CONVENTIONS.md` to .aider.conf.yml (or pass --read CONVENTIONS.md) yourself',
+    ],
+    install: [],
+};
+//# sourceMappingURL=aider.js.map

package/dist/harness/aider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"aider.js","sourceRoot":"","sources":["../../src/harness/aider.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,KAAK,GAAmB;IACnC,EAAE,EAAE,OAAO;IACX,IAAI,EAAE,OAAO;IACb,IAAI,EAAE,UAAU;IAChB,MAAM,EAAE,CAAC,iBAAiB,CAAC;IAC3B,UAAU,EAAE,CAAC,iBAAiB,CAAC;IAC/B,eAAe,EAAE,gBAAgB;IACjC,YAAY,EAAE,SAAS;IACvB,OAAO,EAAE;QACP,wHAAwH;KACzH;IACD,OAAO,EAAE,EAAE;CACZ,CAAC","sourcesContent":["import type { HarnessProfile } from './profile.ts';\n\n/**\n * Aider — ADVISORY tier. Instructions only, and honest about it.\n *\n * No usable hook API, so the whole install is the shared snippet in `CONVENTIONS.md`\n * and one caveat: Aider auto-reads no rules file, so the human has to point it at the\n * conventions themselves. Nothing here is enforced, and the installer says so.\n */\nexport const aider: HarnessProfile = {\n  id: 'aider',\n  name: 'Aider',\n  tier: 'advisory',\n  detect: ['.aider.conf.yml'],\n  detectHome: ['.aider.conf.yml'],\n  instructionFile: 'CONVENTIONS.md',\n  instructions: 'snippet',\n  caveats: [\n    'Aider auto-reads no rules file: add `read: CONVENTIONS.md` to .aider.conf.yml (or pass --read CONVENTIONS.md) yourself',\n  ],\n  install: [],\n};\n"]}

package/dist/harness/claude-code.d.ts

@@ -0,0 +1,3 @@
+import type { ShimmedHarnessProfile } from './profile.ts';
+export declare const claudeCode: ShimmedHarnessProfile;
+//# sourceMappingURL=claude-code.d.ts.map

package/dist/harness/claude-code.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude-code.d.ts","sourceRoot":"","sources":["../../src/harness/claude-code.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAiD1D,eAAO,MAAM,UAAU,EAAE,qBAoBxB,CAAC","sourcesContent":["import type { HarnessHookSchema } from '../hooks/shim.ts';\n\nimport type { ShimmedHarnessProfile } from './profile.ts';\n\n/**\n * Claude Code — VERIFIED tier. Schema, install and removal, end to end.\n *\n * Schema per <https://code.claude.com/docs/en/hooks> (verified 2026-09-02; the deep\n * dive is docs/research/2026-09-02-agent-enforcement.md § 1):\n *\n *  - stdin: `{ hook_event_name: \"PreToolUse\", tool_name, tool_input, cwd }`. For\n *    `Read`, `tool_input.file_path` is already absolute and `offset`/`limit` mark a\n *    windowed read; for `Bash`, `tool_input.command` is the full command string, and\n *    a relative path in it resolves against the payload's `cwd` — the *session's*\n *    working directory, which after the model `cd`s differs from the hook process's\n *    own cwd.\n *  - deny: `hookSpecificOutput.permissionDecision: \"deny\"` with\n *    `permissionDecisionReason` — which is **shown to the model**, so the guard's\n *    reason (the exact replacement command, the `smelt retrieve` contract) lands in\n *    the transcript as steering.\n *  - rewrite (opt-in, `hooks.enforcement: \"rewrite\"`): `updatedInput` replaces the\n *    entire input object of the *same* tool (v2.0.10+), so a Bash command can be\n *    substituted but a Read can never become a Bash call — Reads deny in every mode.\n */\nconst HOOKS: HarnessHookSchema = {\n  readTools: ['Read'],\n  bashTools: ['Bash'],\n  toolNameKeys: ['tool_name'],\n  toolInputKeys: ['tool_input'],\n  cwdKey: 'cwd',\n  deny: (reason) => ({\n    hookSpecificOutput: {\n      hookEventName: 'PreToolUse',\n      permissionDecision: 'deny',\n      permissionDecisionReason: reason,\n    },\n  }),\n  rewrite: {\n    document: ({ input, announcement }) => ({\n      hookSpecificOutput: {\n        hookEventName: 'PreToolUse',\n        permissionDecision: 'allow',\n        permissionDecisionReason: announcement,\n        // updatedInput replaces the whole input object — unchanged fields ride along.\n        updatedInput: input,\n      },\n    }),\n    announce: 'reason',\n  },\n};\n\nexport const claudeCode: ShimmedHarnessProfile = {\n  id: 'claude-code',\n  name: 'Claude Code',\n  tier: 'verified',\n  detect: ['.claude'],\n  detectHome: ['.claude'],\n  instructionFile: 'CLAUDE.md',\n  instructions: 'snippet',\n  caveats: [],\n  hooks: HOOKS,\n  install: [\n    {\n      kind: 'json-hooks',\n      file: '.claude/settings.json',\n      event: 'PreToolUse',\n      matchers: ['Read', 'Bash'],\n      entry: 'command-list',\n      lifecycle: true,\n    },\n  ],\n};\n"]}