@smeltjs/core 0.2.0 → 0.3.0

package/dist/cli/subcommands/smelt.js

@@ -0,0 +1,304 @@
+import { reconstruct } from '../../apply.js';
+import { SUPPORTED_LANGUAGES } from '../../detect.js';
+import { CliUsageError, SmeltError } from '../../errors.js';
+import { budgetRequired, openStore, readBlob, resolveStrategy } from '../../ops/inputs.js';
+import { smeltBlob } from '../../ops/verbs.js';
+import { isStrategy, STRATEGIES } from '../../plan/planners.js';
+import { MemoryElisionStore } from '../../store.js';
+import { CONFIG_FILE_NAME, configuredStore } from '../config.js';
+import { formatReport } from '../report.js';
+import { CLI_NAME, EXIT } from '../shell.js';
+import { flagList, parseBudget, VERB_FLAGS } from './flags.js';
+/**
+ * The `--json` envelope format, versioned like the marker for the same reason: this is
+ * a surface other programs parse, so a change to it has to be identifiable rather than
+ * silent.
+ */
+export const CLI_JSON_FORMAT = 'smelt-cli/v1';
+export const smeltCommand = {
+    name: 'smelt',
+    flags: ['budget', 'focus', 'language', 'strategy', 'json', 'reconstruct'],
+    refusal: `A single-blob run reads one file or stdin; there is no tree to walk, ` +
+        `nothing to cache, and no harness to install into.`,
+    usage: {
+        synopsis: [
+            '<file> --budget <bytes> [--focus <term>]...',
+            '--budget <bytes> [--focus <term>]... < input',
+        ],
+        occasional: ['--reconstruct <result.json>', '--reconstruct < result.json'],
+    },
+    parse(values, positionals) {
+        if (positionals.length > 1) {
+            throw new CliUsageError(`${CLI_NAME}: expected at most one file, got ${String(positionals.length)} ` +
+                `(${positionals.join(', ')}). smelt reads one blob at a time.`);
+        }
+        const file = positionals[0];
+        if (values.reconstruct === true) {
+            refuseReconstructFlags(values);
+            return {
+                mode: 'reconstruct',
+                ...(file === undefined ? {} : { file }),
+                focus: [],
+                json: false,
+            };
+        }
+        const budgetBytes = parseBudget(values.budget);
+        const chosenStrategy = parseStrategy(values.strategy);
+        return {
+            mode: 'smelt',
+            ...(file === undefined ? {} : { file }),
+            ...(budgetBytes === undefined ? {} : { budgetBytes }),
+            focus: values.focus ?? [],
+            ...(values.language === undefined ? {} : { language: parseLanguage(values.language) }),
+            ...(chosenStrategy === undefined ? {} : { strategy: chosenStrategy }),
+            json: values.json === true,
+        };
+    },
+    resolve(invocation, config) {
+        if (invocation.mode === 'reconstruct') {
+            return {
+                kind: 'reconstruct',
+                ...(invocation.file === undefined ? {} : { file: invocation.file }),
+            };
+        }
+        return { kind: 'smelt', run: resolveRun(invocation, config()) };
+    },
+    run(resolved, io) {
+        if (resolved.kind === 'reconstruct') {
+            return runReconstruct(readInput(resolved.file, io), io);
+        }
+        return runSmelt(resolved.run, io);
+    },
+};
+/**
+ * Every flag this verb owns that `--reconstruct` cannot honour, with the reason each
+ * one makes no sense — the second job's flag ownership, which the registry cannot
+ * express because both jobs are the same verb.
+ *
+ * `refuseForeignFlags` refuses a flag no verb owns *here*; it cannot refuse `--focus`
+ * on a single-blob run, because a single-blob run is exactly where `--focus` belongs.
+ * So the ones the round trip ignores are named here instead, and named exhaustively:
+ * every flag on `smeltCommand.flags` except `--reconstruct` itself has an entry, which
+ * `test/guards/subcommand-registry.test.ts` crosses. A flag added to this verb and
+ * forgotten here would be silently ignored by half of the verb's runs — the failure
+ * this table exists to make impossible.
+ *
+ * Key order is the flag table's order, so a refusal lists flags the way every other
+ * refusal does.
+ */
+const RECONSTRUCT_REFUSALS = {
+    budget: `Reconstruction puts every byte back; there is nothing to fit.`,
+    focus: `Focus decides what survives a cut, and the cut has already been made — ` +
+        `the envelope names every elision it took.`,
+    language: `Nothing is detected or parsed on the way back: the envelope carries the ` +
+        `bytes and the ranges the cut recorded.`,
+    strategy: `No planner runs on the way back — the elisions come from the envelope.`,
+    json: `--reconstruct reads a --json envelope and prints the original text; ` +
+        `there is no second envelope to write.`,
+};
+/**
+ * Refuse every flag `--reconstruct` would otherwise ignore, in one message shaped like
+ * the ownership refusals: the flags named, then why not here. A {@link CliUsageError},
+ * so it exits 2 exactly as every other refusal does.
+ *
+ * @throws {CliUsageError} naming each offending flag and what the round trip does instead.
+ */
+function refuseReconstructFlags(values) {
+    const reasons = RECONSTRUCT_REFUSALS;
+    const offending = VERB_FLAGS.filter((flag) => reasons[flag] !== undefined && values[flag] !== undefined);
+    if (offending.length === 0)
+        return;
+    const verb = offending.length === 1 ? 'makes' : 'make';
+    const why = offending.map((flag) => reasons[flag] ?? '').join(' ');
+    throw new CliUsageError(`${CLI_NAME}: ${flagList(offending)} ${verb} no sense with --reconstruct. ${why}`);
+}
+/**
+ * Merge one `'smelt'`-mode invocation with the loaded config (or `undefined` when no
+ * `smelt.config.json` exists) and the built-in defaults.
+ *
+ * The precedence is strict and one-directional: an explicit flag always wins over the
+ * config, and the config only fills what the flags left unsaid. Built-ins fill last,
+ * and only where a built-in exists at all — the budget deliberately has none, so a run
+ * with no budget from either source is refused here, in the one function that owns that
+ * error.
+ *
+ * @throws {CliUsageError} when neither `--budget` nor the config names a budget.
+ */
+export function resolveRun(invocation, config) {
+    const budgetBytes = invocation.budgetBytes ?? config?.config.defaultBudgetBytes;
+    if (budgetBytes === undefined) {
+        throw new CliUsageError(`${CLI_NAME}: ` +
+            budgetRequired({
+                knob: '--budget',
+                stake: 'your context to throw away',
+                advice: `Pass --budget, or set defaultBudgetBytes in ${CONFIG_FILE_NAME} ` +
+                    `(\`${CLI_NAME} init\` writes one).\n` +
+                    `  ${CLI_NAME} src/server.ts --budget 4000 --focus handleRequest`,
+            }));
+    }
+    const strategy = resolveStrategy(invocation.strategy, config?.config.strategy);
+    return {
+        budgetBytes,
+        budgetSource: invocation.budgetBytes !== undefined ? 'flag' : 'config',
+        strategy: strategy.strategy,
+        strategySource: strategy.source,
+        store: configuredStore(config),
+        ...(invocation.file === undefined ? {} : { file: invocation.file }),
+        focus: invocation.focus,
+        ...(invocation.language === undefined ? {} : { language: invocation.language }),
+        json: invocation.json,
+    };
+}
+/**
+ * One smelt run: read the input, hand the resolved values to {@link smeltBlob}, render.
+ *
+ * All merging — flags versus `smelt.config.json` versus built-ins, including the
+ * budget-required refusal — happens in {@link resolveRun}, which is the only place
+ * precedence lives. This function reads the resolved object and never consults a flag
+ * or a config field directly. The cut itself belongs to no front door: `smeltBlob` in
+ * `ops/verbs.ts` builds the smelter and returns the values this function prints, and
+ * the `smelt_file` tool calls the same op with its own arguments.
+ */
+async function runSmelt(run, io) {
+    const inputText = readInput(run.file, io);
+    const outcome = await smeltBlob({
+        text: inputText,
+        source: run.file ?? '<stdin>',
+        budgetBytes: run.budgetBytes,
+        strategy: run.strategy,
+        store: openStore(run.store),
+        ...(run.file === undefined ? {} : { path: run.file }),
+        ...(run.language === undefined ? {} : { language: run.language }),
+        focus: run.focus,
+    });
+    if (run.json) {
+        io.stdout(`${JSON.stringify(envelope(outcome.result, outcome.store), null, 2)}\n`);
+    }
+    else {
+        io.stdout(outcome.result.text);
+    }
+    io.stderr(formatReport(outcome));
+    return outcome.result.outputBytes > run.budgetBytes ? EXIT.overBudget : EXIT.ok;
+}
+/**
+ * Law 3, from a shell.
+ *
+ * This is deliberately not "print the text and hope": it rebuilds the store from the
+ * envelope, checks every hash against the bytes it claims to key, and checks the
+ * reconstructed length against the `inputBytes` the result recorded at the time of the
+ * cut. A round trip that quietly returns almost-right text is the failure this whole
+ * repository is arranged against.
+ */
+function runReconstruct(text, io) {
+    const { result, elided } = parseEnvelope(text);
+    const store = new MemoryElisionStore();
+    for (const [hash, content] of Object.entries(elided)) {
+        const actual = store.put(content);
+        if (actual !== hash) {
+            throw new CliUsageError(`${CLI_NAME}: envelope is not self-consistent — it stores bytes under ` +
+                `"${hash}" that actually hash to "${actual}". Refusing to reconstruct from it.`);
+        }
+    }
+    for (const elision of result.elisions) {
+        if (!store.has(elision.hash)) {
+            throw new CliUsageError(`${CLI_NAME}: envelope is missing the bytes for "${elision.hash}". A result ` +
+                `without its elided bytes cannot be reconstructed; re-run with --json.`);
+        }
+    }
+    const original = reconstruct(result, store);
+    const bytes = Buffer.byteLength(original, 'utf8');
+    if (bytes !== result.inputBytes) {
+        throw new SmeltError(`${CLI_NAME}: reconstruction produced ${String(bytes)} bytes but the result ` +
+            `recorded ${String(result.inputBytes)}. The round trip did not close.`);
+    }
+    io.stdout(original);
+    io.stderr(`${CLI_NAME}  reconstructed ${String(result.inputBytes)} B from ` +
+        `${String(result.elisions.length)} elisions — byte for byte\n`);
+    return EXIT.ok;
+}
+/** `peek`, not `retrieve`: writing a file is not the model asking for anything back. */
+function envelope(result, store) {
+    const elided = {};
+    for (const elision of result.elisions) {
+        const content = store.peek(elision.hash);
+        if (content === undefined) {
+            throw new SmeltError(`${CLI_NAME}: the store does not hold "${elision.hash}", which its own result ` +
+                `says it elided. Refusing to write an envelope that cannot round-trip.`);
+        }
+        elided[elision.hash] = content;
+    }
+    return { format: CLI_JSON_FORMAT, result, elided };
+}
+function parseEnvelope(text) {
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch (cause) {
+        throw new CliUsageError(`${CLI_NAME}: --reconstruct expected a --json envelope, and this is not JSON: ` +
+            `${cause instanceof Error ? cause.message : String(cause)}`);
+    }
+    if (typeof value !== 'object' || value === null) {
+        throw new CliUsageError(`${CLI_NAME}: --reconstruct expected a JSON object.`);
+    }
+    const fields = value;
+    if (fields['format'] !== CLI_JSON_FORMAT) {
+        throw new CliUsageError(`${CLI_NAME}: this envelope says format "${String(fields['format'])}"; this build ` +
+            `reads "${CLI_JSON_FORMAT}". Formats are versioned so a mismatch is visible ` +
+            `instead of being half-understood.`);
+    }
+    const result = fields['result'];
+    if (typeof result !== 'object' || result === null) {
+        throw new CliUsageError(`${CLI_NAME}: envelope has no \`result\` object.`);
+    }
+    const resultFields = result;
+    if (typeof resultFields['text'] !== 'string' ||
+        typeof resultFields['inputBytes'] !== 'number' ||
+        !Array.isArray(resultFields['elisions'])) {
+        throw new CliUsageError(`${CLI_NAME}: envelope's \`result\` is missing text, inputBytes or elisions.`);
+    }
+    const elided = fields['elided'];
+    if (typeof elided !== 'object' || elided === null) {
+        throw new CliUsageError(`${CLI_NAME}: envelope has no \`elided\` map.`);
+    }
+    for (const [hash, content] of Object.entries(elided)) {
+        if (typeof content !== 'string') {
+            throw new CliUsageError(`${CLI_NAME}: envelope's \`elided["${hash}"]\` is not a string.`);
+        }
+    }
+    return {
+        format: CLI_JSON_FORMAT,
+        result: result,
+        elided: elided,
+    };
+}
+/**
+ * The blob to work on: stdin when no file was named, otherwise the file — read
+ * through the ops law, so "cannot read X" says the same thing here and in the
+ * `smelt_file` tool. Only the stdin leg is the CLI's own; a tool has no stdin.
+ */
+function readInput(file, io) {
+    if (file === undefined)
+        return io.stdin();
+    const read = readBlob(file, file);
+    if (!read.ok)
+        throw new CliUsageError(`${CLI_NAME}: ${read.refusal}`);
+    return read.value;
+}
+function parseLanguage(raw) {
+    const known = [...SUPPORTED_LANGUAGES, 'unknown'];
+    if (!known.includes(raw)) {
+        throw new CliUsageError(`${CLI_NAME}: unknown --language "${raw}". Known: ${known.join(', ')}.`);
+    }
+    return raw;
+}
+/** Membership in the {@link PLANNERS} registry is the whole validation. */
+function parseStrategy(raw) {
+    if (raw === undefined)
+        return undefined;
+    if (!isStrategy(raw)) {
+        throw new CliUsageError(`${CLI_NAME}: unknown --strategy "${raw}". Known: ${STRATEGIES.join(', ')}.`);
+    }
+    return raw;
+}
+//# sourceMappingURL=smelt.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"smelt.js","sourceRoot":"","sources":["../../../src/cli/subcommands/smelt.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC5D,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC3F,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC/C,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAEhE,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAEpD,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAEjE,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAG7C,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAuE/D;;;;GAIG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,cAAc,CAAC;AAkB9C,MAAM,CAAC,MAAM,YAAY,GAAsD;IAC7E,IAAI,EAAE,OAAO;IACb,KAAK,EAAE,CAAC,QAAQ,EAAE,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,EAAE,aAAa,CAAC;IACzE,OAAO,EACL,uEAAuE;QACvE,mDAAmD;IACrD,KAAK,EAAE;QACL,QAAQ,EAAE;YACR,6CAA6C;YAC7C,8CAA8C;SAC/C;QACD,UAAU,EAAE,CAAC,6BAA6B,EAAE,6BAA6B,CAAC;KAC3E;IAED,KAAK,CAAC,MAAkB,EAAE,WAA8B;QACtD,IAAI,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC3B,MAAM,IAAI,aAAa,CACrB,GAAG,QAAQ,oCAAoC,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,GAAG;gBAC1E,IAAI,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,oCAAoC,CACjE,CAAC;QACJ,CAAC;QACD,MAAM,IAAI,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC;QAE5B,IAAI,MAAM,CAAC,WAAW,KAAK,IAAI,EAAE,CAAC;YAChC,sBAAsB,CAAC,MAAM,CAAC,CAAC;YAC/B,OAAO;gBACL,IAAI,EAAE,aAAa;gBACnB,GAAG,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC;gBACvC,KAAK,EAAE,EAAE;gBACT,IAAI,EAAE,KAAK;aACZ,CAAC;QACJ,CAAC;QAED,MAAM,WAAW,GAAG,WAAW,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QAC/C,MAAM,cAAc,GAAG,aAAa,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QACtD,OAAO;YACL,IAAI,EAAE,OAAO;YACb,GAAG,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC;YACvC,GAAG,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC;YACrD,KAAK,EAAE,MAAM,CAAC,KAAK,IAAI,EAAE;YACzB,GAAG,CAAC,MAAM,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,aAAa,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC;YACtF,GAAG,CAAC,cAAc,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,cAAc,EAAE,CAAC;YACrE,IAAI,EAAE,MAAM,CAAC,IAAI,KAAK,IAAI;SAC3B,CAAC;IACJ,CAAC;IAED,OAAO,CAAC,UAA2B,EAAE,MAAoB;QACvD,IAAI,UAAU,CAAC,IAAI,KAAK,aAAa,EAAE,CAAC;YACtC,OAAO;gBACL,IAAI,EAAE,aAAa;gBACnB,GAAG,CAAC,UAAU,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,UAAU,CAAC,IAAI,EAAE,CAAC;aACpE,CAAC;QACJ,CAAC;QACD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,UAAU,CAAC,UAAU,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC;IAClE,CAAC;IAED,GAAG,CAAC,QAA8B,EAAE,EAAS;QAC3C,IAAI,QAAQ,CAAC,IAAI,KAAK,aAAa,EAAE,CAAC;YACpC,OAAO,cAAc,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;QAC1D,CAAC;QACD,OAAO,QAAQ,CAAC,QAAQ,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;IACpC,CAAC;CACF,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,MAAM,oBAAoB,GAAG;IAC3B,MAAM,EAAE,+DAA+D;IACvE,KAAK,EACH,yEAAyE;QACzE,2CAA2C;IAC7C,QAAQ,EACN,0EAA0E;QAC1E,wCAAwC;IAC1C,QAAQ,EAAE,wEAAwE;IAClF,IAAI,EACF,sEAAsE;QACtE,uCAAuC;CACW,CAAC;AAEvD;;;;;;GAMG;AACH,SAAS,sBAAsB,CAAC,MAAkB;IAChD,MAAM,OAAO,GAAsC,oBAAoB,CAAC;IACxE,MAAM,SAAS,GAAG,UAAU,CAAC,MAAM,CACjC,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,SAAS,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,SAAS,CACpE,CAAC;IACF,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO;IAEnC,MAAM,IAAI,GAAG,SAAS,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC;IACvD,MAAM,GAAG,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACnE,MAAM,IAAI,aAAa,CACrB,GAAG,QAAQ,KAAK,QAAQ,CAAC,SAAS,CAAC,IAAI,IAAI,iCAAiC,GAAG,EAAE,CAClF,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,UAAU,CACxB,UAA2B,EAC3B,MAAgC;IAEhC,MAAM,WAAW,GAAG,UAAU,CAAC,WAAW,IAAI,MAAM,EAAE,MAAM,CAAC,kBAAkB,CAAC;IAChF,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;QAC9B,MAAM,IAAI,aAAa,CACrB,GAAG,QAAQ,IAAI;YACb,cAAc,CAAC;gBACb,IAAI,EAAE,UAAU;gBAChB,KAAK,EAAE,4BAA4B;gBACnC,MAAM,EACJ,+CAA+C,gBAAgB,GAAG;oBAClE,MAAM,QAAQ,wBAAwB;oBACtC,KAAK,QAAQ,oDAAoD;aACpE,CAAC,CACL,CAAC;IACJ,CAAC;IAED,MAAM,QAAQ,GAAG,eAAe,CAAC,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC;IAE/E,OAAO;QACL,WAAW;QACX,YAAY,EAAE,UAAU,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ;QACtE,QAAQ,EAAE,QAAQ,CAAC,QAAQ;QAC3B,cAAc,EAAE,QAAQ,CAAC,MAAM;QAC/B,KAAK,EAAE,eAAe,CAAC,MAAM,CAAC;QAC9B,GAAG,CAAC,UAAU,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,UAAU,CAAC,IAAI,EAAE,CAAC;QACnE,KAAK,EAAE,UAAU,CAAC,KAAK;QACvB,GAAG,CAAC,UAAU,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,UAAU,CAAC,QAAQ,EAAE,CAAC;QAC/E,IAAI,EAAE,UAAU,CAAC,IAAI;KACtB,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,KAAK,UAAU,QAAQ,CAAC,GAAgB,EAAE,EAAS;IACjD,MAAM,SAAS,GAAG,SAAS,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;IAE1C,MAAM,OAAO,GAAG,MAAM,SAAS,CAAC;QAC9B,IAAI,EAAE,SAAS;QACf,MAAM,EAAE,GAAG,CAAC,IAAI,IAAI,SAAS;QAC7B,WAAW,EAAE,GAAG,CAAC,WAAW;QAC5B,QAAQ,EAAE,GAAG,CAAC,QAAQ;QACtB,KAAK,EAAE,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC;QAC3B,GAAG,CAAC,GAAG,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,CAAC;QACrD,GAAG,CAAC,GAAG,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,GAAG,CAAC,QAAQ,EAAE,CAAC;QACjE,KAAK,EAAE,GAAG,CAAC,KAAK;KACjB,CAAC,CAAC;IAEH,IAAI,GAAG,CAAC,IAAI,EAAE,CAAC;QACb,EAAE,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;IACrF,CAAC;SAAM,CAAC;QACN,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACjC,CAAC;IACD,EAAE,CAAC,MAAM,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC;IAEjC,OAAO,OAAO,CAAC,MAAM,CAAC,WAAW,GAAG,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC;AAClF,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,cAAc,CAAC,IAAY,EAAE,EAAS;IAC7C,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;IAC/C,MAAM,KAAK,GAAG,IAAI,kBAAkB,EAAE,CAAC;IAEvC,KAAK,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QACrD,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QAClC,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;YACpB,MAAM,IAAI,aAAa,CACrB,GAAG,QAAQ,4DAA4D;gBACrE,IAAI,IAAI,4BAA4B,MAAM,qCAAqC,CAClF,CAAC;QACJ,CAAC;IACH,CAAC;IACD,KAAK,MAAM,OAAO,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;QACtC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;YAC7B,MAAM,IAAI,aAAa,CACrB,GAAG,QAAQ,wCAAwC,OAAO,CAAC,IAAI,cAAc;gBAC3E,uEAAuE,CAC1E,CAAC;QACJ,CAAC;IACH,CAAC;IAED,MAAM,QAAQ,GAAG,WAAW,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAC5C,MAAM,KAAK,GAAG,MAAM,CAAC,UAAU,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IAClD,IAAI,KAAK,KAAK,MAAM,CAAC,UAAU,EAAE,CAAC;QAChC,MAAM,IAAI,UAAU,CAClB,GAAG,QAAQ,6BAA6B,MAAM,CAAC,KAAK,CAAC,wBAAwB;YAC3E,YAAY,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,iCAAiC,CACzE,CAAC;IACJ,CAAC;IAED,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IACpB,EAAE,CAAC,MAAM,CACP,GAAG,QAAQ,mBAAmB,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,UAAU;QAC/D,GAAG,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,6BAA6B,CACjE,CAAC;IACF,OAAO,IAAI,CAAC,EAAE,CAAC;AACjB,CAAC;AAED,wFAAwF;AACxF,SAAS,QAAQ,CAAC,MAAmB,EAAE,KAAmB;IACxD,MAAM,MAAM,GAA2B,EAAE,CAAC;IAC1C,KAAK,MAAM,OAAO,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;QACtC,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QACzC,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YAC1B,MAAM,IAAI,UAAU,CAClB,GAAG,QAAQ,8BAA8B,OAAO,CAAC,IAAI,0BAA0B;gBAC7E,uEAAuE,CAC1E,CAAC;QACJ,CAAC;QACD,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC;IACjC,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;AACrD,CAAC;AAED,SAAS,aAAa,CAAC,IAAY;IACjC,IAAI,KAAc,CAAC;IACnB,IAAI,CAAC;QACH,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC3B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,aAAa,CACrB,GAAG,QAAQ,oEAAoE;YAC7E,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAC9D,CAAC;IACJ,CAAC;IAED,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QAChD,MAAM,IAAI,aAAa,CAAC,GAAG,QAAQ,yCAAyC,CAAC,CAAC;IAChF,CAAC;IACD,MAAM,MAAM,GAAG,KAAgC,CAAC;IAEhD,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,eAAe,EAAE,CAAC;QACzC,MAAM,IAAI,aAAa,CACrB,GAAG,QAAQ,gCAAgC,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,gBAAgB;YACjF,UAAU,eAAe,oDAAoD;YAC7E,mCAAmC,CACtC,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC;IAChC,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;QAClD,MAAM,IAAI,aAAa,CAAC,GAAG,QAAQ,sCAAsC,CAAC,CAAC;IAC7E,CAAC;IACD,MAAM,YAAY,GAAG,MAAiC,CAAC;IACvD,IACE,OAAO,YAAY,CAAC,MAAM,CAAC,KAAK,QAAQ;QACxC,OAAO,YAAY,CAAC,YAAY,CAAC,KAAK,QAAQ;QAC9C,CAAC,KAAK,CAAC,OAAO,CAAC,YAAY,CAAC,UAAU,CAAC,CAAC,EACxC,CAAC;QACD,MAAM,IAAI,aAAa,CACrB,GAAG,QAAQ,kEAAkE,CAC9E,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC;IAChC,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;QAClD,MAAM,IAAI,aAAa,CAAC,GAAG,QAAQ,mCAAmC,CAAC,CAAC;IAC1E,CAAC;IACD,KAAK,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QACrD,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;YAChC,MAAM,IAAI,aAAa,CAAC,GAAG,QAAQ,0BAA0B,IAAI,uBAAuB,CAAC,CAAC;QAC5F,CAAC;IACH,CAAC;IAED,OAAO;QACL,MAAM,EAAE,eAAe;QACvB,MAAM,EAAE,MAAgC;QACxC,MAAM,EAAE,MAAgC;KACzC,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,SAAS,SAAS,CAAC,IAAwB,EAAE,EAAS;IACpD,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC;IAC1C,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAClC,IAAI,CAAC,IAAI,CAAC,EAAE;QAAE,MAAM,IAAI,aAAa,CAAC,GAAG,QAAQ,KAAK,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;IACtE,OAAO,IAAI,CAAC,KAAK,CAAC;AACpB,CAAC;AAED,SAAS,aAAa,CAAC,GAAW;IAChC,MAAM,KAAK,GAAsB,CAAC,GAAG,mBAAmB,EAAE,SAAS,CAAC,CAAC;IACrE,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,aAAa,CACrB,GAAG,QAAQ,yBAAyB,GAAG,aAAa,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CACxE,CAAC;IACJ,CAAC;IACD,OAAO,GAAuB,CAAC;AACjC,CAAC;AAED,2EAA2E;AAC3E,SAAS,aAAa,CAAC,GAAuB;IAC5C,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IACxC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QACrB,MAAM,IAAI,aAAa,CACrB,GAAG,QAAQ,yBAAyB,GAAG,aAAa,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAC7E,CAAC;IACJ,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC","sourcesContent":["import { reconstruct } from '../../apply.ts';\nimport { SUPPORTED_LANGUAGES } from '../../detect.ts';\nimport { CliUsageError, SmeltError } from '../../errors.ts';\nimport { budgetRequired, openStore, readBlob, resolveStrategy } from '../../ops/inputs.ts';\nimport { smeltBlob } from '../../ops/verbs.ts';\nimport { isStrategy, STRATEGIES } from '../../plan/planners.ts';\nimport type { Strategy } from '../../plan/planners.ts';\nimport { MemoryElisionStore } from '../../store.ts';\nimport type { DetectedLanguage, ElisionStore, SmeltResult } from '../../types.ts';\nimport { CONFIG_FILE_NAME, configuredStore } from '../config.ts';\nimport type { ConfiguredStore, LoadedConfig } from '../config.ts';\nimport { formatReport } from '../report.ts';\nimport { CLI_NAME, EXIT } from '../shell.ts';\nimport type { CliIo } from '../shell.ts';\n\nimport { flagList, parseBudget, VERB_FLAGS } from './flags.ts';\nimport type { FlagValues, VerbFlag } from './flags.ts';\nimport type { ConfigSource, Subcommand } from './subcommand.ts';\n\n/**\n * The default verb: `smelt <file>` and `smelt < input`, plus the `--reconstruct` round\n * trip that reads one of its own `--json` envelopes back.\n *\n * Two jobs, one verb, which is why USAGE lists it twice: `--reconstruct` reads a file\n * this command wrote and puts every byte back, so it takes no budget, no focus and no\n * strategy — but it is the same front door, and giving it a subcommand word would\n * break every script that types `smelt --reconstruct`.\n */\n\n/** What the CLI was asked to do. Pure data, so the parse is testable on its own. */\nexport interface SmeltInvocation {\n  readonly mode: 'smelt' | 'reconstruct' | 'help' | 'version' | 'init';\n  /** Path to read. `undefined` means stdin. */\n  readonly file?: string;\n  /**\n   * UTF-8 bytes. `undefined` in `'smelt'` mode means the flag was not given; the\n   * runner then consults `smelt.config.json` and errors if that has no default either.\n   */\n  readonly budgetBytes?: number;\n  readonly focus: readonly string[];\n  readonly language?: DetectedLanguage;\n  /** `undefined` means the flag was not given — the config default may apply. */\n  readonly strategy?: Strategy;\n  readonly json: boolean;\n}\n\n/**\n * Everything one smelt run needs, fully merged — with a receipt for where each\n * merged value came from.\n *\n * This is the verb's single merge of flags + config + built-ins. Precedence lives\n * here and nowhere else: `resolveRun` is the only code that may look at a flag and a\n * config default side by side, so a precedence question is always answered by one\n * function instead of by reading two files. `runSmelt` executes this object\n * straight-line, without a `??` of its own.\n */\nexport interface ResolvedRun {\n  readonly budgetBytes: number;\n  /** Where the budget came from. A missing budget never gets here — it throws. */\n  readonly budgetSource: 'flag' | 'config';\n  readonly strategy: Strategy;\n  readonly strategySource: 'flag' | 'config' | 'builtin';\n  /**\n   * The store decision, with `path` already resolved against the config file's\n   * directory. `'memory'` is the built-in default — a fresh in-memory store per run.\n   */\n  readonly store: ConfiguredStore;\n  /** Path to read. `undefined` means stdin. Flags only; the config has no say. */\n  readonly file?: string;\n  readonly focus: readonly string[];\n  readonly language?: DetectedLanguage;\n  readonly json: boolean;\n}\n\n/**\n * The default verb's two resolved shapes.\n *\n * `--reconstruct` merges nothing: there is no budget to default, no strategy to pick\n * and no store to choose, because the envelope carries its own bytes. Saying that in\n * the type is cheaper than a {@link ResolvedRun} whose every field would be a lie for\n * half of this verb's runs.\n */\nexport type ResolvedSmeltCommand =\n  | { readonly kind: 'smelt'; readonly run: ResolvedRun }\n  | { readonly kind: 'reconstruct'; readonly file?: string };\n\n/**\n * The `--json` envelope format, versioned like the marker for the same reason: this is\n * a surface other programs parse, so a change to it has to be identifiable rather than\n * silent.\n */\nexport const CLI_JSON_FORMAT = 'smelt-cli/v1';\n\n/**\n * What `--json` prints, and what `--reconstruct` reads back.\n *\n * `result` is the {@link SmeltResult} **verbatim** — nothing renamed, nothing dropped —\n * so it can be diffed in a test. `elided` is the other half, and it is here because a\n * result on its own is *not* reconstructible: Law 3 is a property of the result plus\n * the store that holds its bytes, and a file claiming to prove the round trip while\n * carrying only half of it would prove nothing.\n */\nexport interface CliJsonEnvelope {\n  readonly format: string;\n  readonly result: SmeltResult;\n  /** hash → the exact elided bytes. Keys match `result.elisions[].hash`. */\n  readonly elided: Readonly<Record<string, string>>;\n}\n\nexport const smeltCommand: Subcommand<SmeltInvocation, ResolvedSmeltCommand> = {\n  name: 'smelt',\n  flags: ['budget', 'focus', 'language', 'strategy', 'json', 'reconstruct'],\n  refusal:\n    `A single-blob run reads one file or stdin; there is no tree to walk, ` +\n    `nothing to cache, and no harness to install into.`,\n  usage: {\n    synopsis: [\n      '<file> --budget <bytes> [--focus <term>]...',\n      '--budget <bytes> [--focus <term>]... < input',\n    ],\n    occasional: ['--reconstruct <result.json>', '--reconstruct < result.json'],\n  },\n\n  parse(values: FlagValues, positionals: readonly string[]): SmeltInvocation {\n    if (positionals.length > 1) {\n      throw new CliUsageError(\n        `${CLI_NAME}: expected at most one file, got ${String(positionals.length)} ` +\n          `(${positionals.join(', ')}). smelt reads one blob at a time.`,\n      );\n    }\n    const file = positionals[0];\n\n    if (values.reconstruct === true) {\n      refuseReconstructFlags(values);\n      return {\n        mode: 'reconstruct',\n        ...(file === undefined ? {} : { file }),\n        focus: [],\n        json: false,\n      };\n    }\n\n    const budgetBytes = parseBudget(values.budget);\n    const chosenStrategy = parseStrategy(values.strategy);\n    return {\n      mode: 'smelt',\n      ...(file === undefined ? {} : { file }),\n      ...(budgetBytes === undefined ? {} : { budgetBytes }),\n      focus: values.focus ?? [],\n      ...(values.language === undefined ? {} : { language: parseLanguage(values.language) }),\n      ...(chosenStrategy === undefined ? {} : { strategy: chosenStrategy }),\n      json: values.json === true,\n    };\n  },\n\n  resolve(invocation: SmeltInvocation, config: ConfigSource): ResolvedSmeltCommand {\n    if (invocation.mode === 'reconstruct') {\n      return {\n        kind: 'reconstruct',\n        ...(invocation.file === undefined ? {} : { file: invocation.file }),\n      };\n    }\n    return { kind: 'smelt', run: resolveRun(invocation, config()) };\n  },\n\n  run(resolved: ResolvedSmeltCommand, io: CliIo): number | Promise<number> {\n    if (resolved.kind === 'reconstruct') {\n      return runReconstruct(readInput(resolved.file, io), io);\n    }\n    return runSmelt(resolved.run, io);\n  },\n};\n\n/**\n * Every flag this verb owns that `--reconstruct` cannot honour, with the reason each\n * one makes no sense — the second job's flag ownership, which the registry cannot\n * express because both jobs are the same verb.\n *\n * `refuseForeignFlags` refuses a flag no verb owns *here*; it cannot refuse `--focus`\n * on a single-blob run, because a single-blob run is exactly where `--focus` belongs.\n * So the ones the round trip ignores are named here instead, and named exhaustively:\n * every flag on `smeltCommand.flags` except `--reconstruct` itself has an entry, which\n * `test/guards/subcommand-registry.test.ts` crosses. A flag added to this verb and\n * forgotten here would be silently ignored by half of the verb's runs — the failure\n * this table exists to make impossible.\n *\n * Key order is the flag table's order, so a refusal lists flags the way every other\n * refusal does.\n */\nconst RECONSTRUCT_REFUSALS = {\n  budget: `Reconstruction puts every byte back; there is nothing to fit.`,\n  focus:\n    `Focus decides what survives a cut, and the cut has already been made — ` +\n    `the envelope names every elision it took.`,\n  language:\n    `Nothing is detected or parsed on the way back: the envelope carries the ` +\n    `bytes and the ranges the cut recorded.`,\n  strategy: `No planner runs on the way back — the elisions come from the envelope.`,\n  json:\n    `--reconstruct reads a --json envelope and prints the original text; ` +\n    `there is no second envelope to write.`,\n} as const satisfies Partial<Record<VerbFlag, string>>;\n\n/**\n * Refuse every flag `--reconstruct` would otherwise ignore, in one message shaped like\n * the ownership refusals: the flags named, then why not here. A {@link CliUsageError},\n * so it exits 2 exactly as every other refusal does.\n *\n * @throws {CliUsageError} naming each offending flag and what the round trip does instead.\n */\nfunction refuseReconstructFlags(values: FlagValues): void {\n  const reasons: Partial<Record<VerbFlag, string>> = RECONSTRUCT_REFUSALS;\n  const offending = VERB_FLAGS.filter(\n    (flag) => reasons[flag] !== undefined && values[flag] !== undefined,\n  );\n  if (offending.length === 0) return;\n\n  const verb = offending.length === 1 ? 'makes' : 'make';\n  const why = offending.map((flag) => reasons[flag] ?? '').join(' ');\n  throw new CliUsageError(\n    `${CLI_NAME}: ${flagList(offending)} ${verb} no sense with --reconstruct. ${why}`,\n  );\n}\n\n/**\n * Merge one `'smelt'`-mode invocation with the loaded config (or `undefined` when no\n * `smelt.config.json` exists) and the built-in defaults.\n *\n * The precedence is strict and one-directional: an explicit flag always wins over the\n * config, and the config only fills what the flags left unsaid. Built-ins fill last,\n * and only where a built-in exists at all — the budget deliberately has none, so a run\n * with no budget from either source is refused here, in the one function that owns that\n * error.\n *\n * @throws {CliUsageError} when neither `--budget` nor the config names a budget.\n */\nexport function resolveRun(\n  invocation: SmeltInvocation,\n  config: LoadedConfig | undefined,\n): ResolvedRun {\n  const budgetBytes = invocation.budgetBytes ?? config?.config.defaultBudgetBytes;\n  if (budgetBytes === undefined) {\n    throw new CliUsageError(\n      `${CLI_NAME}: ` +\n        budgetRequired({\n          knob: '--budget',\n          stake: 'your context to throw away',\n          advice:\n            `Pass --budget, or set defaultBudgetBytes in ${CONFIG_FILE_NAME} ` +\n            `(\\`${CLI_NAME} init\\` writes one).\\n` +\n            `  ${CLI_NAME} src/server.ts --budget 4000 --focus handleRequest`,\n        }),\n    );\n  }\n\n  const strategy = resolveStrategy(invocation.strategy, config?.config.strategy);\n\n  return {\n    budgetBytes,\n    budgetSource: invocation.budgetBytes !== undefined ? 'flag' : 'config',\n    strategy: strategy.strategy,\n    strategySource: strategy.source,\n    store: configuredStore(config),\n    ...(invocation.file === undefined ? {} : { file: invocation.file }),\n    focus: invocation.focus,\n    ...(invocation.language === undefined ? {} : { language: invocation.language }),\n    json: invocation.json,\n  };\n}\n\n/**\n * One smelt run: read the input, hand the resolved values to {@link smeltBlob}, render.\n *\n * All merging — flags versus `smelt.config.json` versus built-ins, including the\n * budget-required refusal — happens in {@link resolveRun}, which is the only place\n * precedence lives. This function reads the resolved object and never consults a flag\n * or a config field directly. The cut itself belongs to no front door: `smeltBlob` in\n * `ops/verbs.ts` builds the smelter and returns the values this function prints, and\n * the `smelt_file` tool calls the same op with its own arguments.\n */\nasync function runSmelt(run: ResolvedRun, io: CliIo): Promise<number> {\n  const inputText = readInput(run.file, io);\n\n  const outcome = await smeltBlob({\n    text: inputText,\n    source: run.file ?? '<stdin>',\n    budgetBytes: run.budgetBytes,\n    strategy: run.strategy,\n    store: openStore(run.store),\n    ...(run.file === undefined ? {} : { path: run.file }),\n    ...(run.language === undefined ? {} : { language: run.language }),\n    focus: run.focus,\n  });\n\n  if (run.json) {\n    io.stdout(`${JSON.stringify(envelope(outcome.result, outcome.store), null, 2)}\\n`);\n  } else {\n    io.stdout(outcome.result.text);\n  }\n  io.stderr(formatReport(outcome));\n\n  return outcome.result.outputBytes > run.budgetBytes ? EXIT.overBudget : EXIT.ok;\n}\n\n/**\n * Law 3, from a shell.\n *\n * This is deliberately not \"print the text and hope\": it rebuilds the store from the\n * envelope, checks every hash against the bytes it claims to key, and checks the\n * reconstructed length against the `inputBytes` the result recorded at the time of the\n * cut. A round trip that quietly returns almost-right text is the failure this whole\n * repository is arranged against.\n */\nfunction runReconstruct(text: string, io: CliIo): number {\n  const { result, elided } = parseEnvelope(text);\n  const store = new MemoryElisionStore();\n\n  for (const [hash, content] of Object.entries(elided)) {\n    const actual = store.put(content);\n    if (actual !== hash) {\n      throw new CliUsageError(\n        `${CLI_NAME}: envelope is not self-consistent — it stores bytes under ` +\n          `\"${hash}\" that actually hash to \"${actual}\". Refusing to reconstruct from it.`,\n      );\n    }\n  }\n  for (const elision of result.elisions) {\n    if (!store.has(elision.hash)) {\n      throw new CliUsageError(\n        `${CLI_NAME}: envelope is missing the bytes for \"${elision.hash}\". A result ` +\n          `without its elided bytes cannot be reconstructed; re-run with --json.`,\n      );\n    }\n  }\n\n  const original = reconstruct(result, store);\n  const bytes = Buffer.byteLength(original, 'utf8');\n  if (bytes !== result.inputBytes) {\n    throw new SmeltError(\n      `${CLI_NAME}: reconstruction produced ${String(bytes)} bytes but the result ` +\n        `recorded ${String(result.inputBytes)}. The round trip did not close.`,\n    );\n  }\n\n  io.stdout(original);\n  io.stderr(\n    `${CLI_NAME}  reconstructed ${String(result.inputBytes)} B from ` +\n      `${String(result.elisions.length)} elisions — byte for byte\\n`,\n  );\n  return EXIT.ok;\n}\n\n/** `peek`, not `retrieve`: writing a file is not the model asking for anything back. */\nfunction envelope(result: SmeltResult, store: ElisionStore): CliJsonEnvelope {\n  const elided: Record<string, string> = {};\n  for (const elision of result.elisions) {\n    const content = store.peek(elision.hash);\n    if (content === undefined) {\n      throw new SmeltError(\n        `${CLI_NAME}: the store does not hold \"${elision.hash}\", which its own result ` +\n          `says it elided. Refusing to write an envelope that cannot round-trip.`,\n      );\n    }\n    elided[elision.hash] = content;\n  }\n  return { format: CLI_JSON_FORMAT, result, elided };\n}\n\nfunction parseEnvelope(text: string): CliJsonEnvelope {\n  let value: unknown;\n  try {\n    value = JSON.parse(text);\n  } catch (cause) {\n    throw new CliUsageError(\n      `${CLI_NAME}: --reconstruct expected a --json envelope, and this is not JSON: ` +\n        `${cause instanceof Error ? cause.message : String(cause)}`,\n    );\n  }\n\n  if (typeof value !== 'object' || value === null) {\n    throw new CliUsageError(`${CLI_NAME}: --reconstruct expected a JSON object.`);\n  }\n  const fields = value as Record<string, unknown>;\n\n  if (fields['format'] !== CLI_JSON_FORMAT) {\n    throw new CliUsageError(\n      `${CLI_NAME}: this envelope says format \"${String(fields['format'])}\"; this build ` +\n        `reads \"${CLI_JSON_FORMAT}\". Formats are versioned so a mismatch is visible ` +\n        `instead of being half-understood.`,\n    );\n  }\n\n  const result = fields['result'];\n  if (typeof result !== 'object' || result === null) {\n    throw new CliUsageError(`${CLI_NAME}: envelope has no \\`result\\` object.`);\n  }\n  const resultFields = result as Record<string, unknown>;\n  if (\n    typeof resultFields['text'] !== 'string' ||\n    typeof resultFields['inputBytes'] !== 'number' ||\n    !Array.isArray(resultFields['elisions'])\n  ) {\n    throw new CliUsageError(\n      `${CLI_NAME}: envelope's \\`result\\` is missing text, inputBytes or elisions.`,\n    );\n  }\n\n  const elided = fields['elided'];\n  if (typeof elided !== 'object' || elided === null) {\n    throw new CliUsageError(`${CLI_NAME}: envelope has no \\`elided\\` map.`);\n  }\n  for (const [hash, content] of Object.entries(elided)) {\n    if (typeof content !== 'string') {\n      throw new CliUsageError(`${CLI_NAME}: envelope's \\`elided[\"${hash}\"]\\` is not a string.`);\n    }\n  }\n\n  return {\n    format: CLI_JSON_FORMAT,\n    result: result as unknown as SmeltResult,\n    elided: elided as Record<string, string>,\n  };\n}\n\n/**\n * The blob to work on: stdin when no file was named, otherwise the file — read\n * through the ops law, so \"cannot read X\" says the same thing here and in the\n * `smelt_file` tool. Only the stdin leg is the CLI's own; a tool has no stdin.\n */\nfunction readInput(file: string | undefined, io: CliIo): string {\n  if (file === undefined) return io.stdin();\n  const read = readBlob(file, file);\n  if (!read.ok) throw new CliUsageError(`${CLI_NAME}: ${read.refusal}`);\n  return read.value;\n}\n\nfunction parseLanguage(raw: string): DetectedLanguage {\n  const known: readonly string[] = [...SUPPORTED_LANGUAGES, 'unknown'];\n  if (!known.includes(raw)) {\n    throw new CliUsageError(\n      `${CLI_NAME}: unknown --language \"${raw}\". Known: ${known.join(', ')}.`,\n    );\n  }\n  return raw as DetectedLanguage;\n}\n\n/** Membership in the {@link PLANNERS} registry is the whole validation. */\nfunction parseStrategy(raw: string | undefined): Strategy | undefined {\n  if (raw === undefined) return undefined;\n  if (!isStrategy(raw)) {\n    throw new CliUsageError(\n      `${CLI_NAME}: unknown --strategy \"${raw}\". Known: ${STRATEGIES.join(', ')}.`,\n    );\n  }\n  return raw;\n}\n"]}

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

@@ -0,0 +1,43 @@
+import type { RetrieveStats } from '../../types.ts';
+import type { ResolvedStoreRun } from './retrieve.ts';
+import type { Subcommand } from './subcommand.ts';
+/**
+ * `smelt stats` — the store's counters, without touching them.
+ *
+ * Reading stats does NOT count as a retrieval: `stats()` folds the journal and scans
+ * the blobs, journaling nothing, so watching the expansion rate can never move it —
+ * an observer that inflated its own metric would make the honest signal dishonest.
+ *
+ * The plain form is one `name value` per line, greppable and stable; `--json` emits
+ * the {@link RetrieveStats} verbatim in its own versioned envelope
+ * ({@link CLI_STATS_JSON_FORMAT}), like every other machine-read surface here.
+ *
+ * It resolves through `retrieve`'s {@link resolveStoreRun} because the two verbs
+ * share one merge — the store leg, and the same refusal when that store cannot
+ * outlive a run. Sharing the function is the point; sharing a struct with a hash
+ * field `stats` would never read is not.
+ */
+/** `smelt stats` — the store's counters, read without touching them. */
+export interface StatsInvocation {
+    readonly mode: 'stats';
+    readonly json: boolean;
+}
+/** What `stats` runs on: the shared store leg, plus how to print it. */
+export interface ResolvedStatsRun {
+    readonly store: ResolvedStoreRun;
+    readonly json: boolean;
+}
+/**
+ * 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 declare const CLI_STATS_JSON_FORMAT = "smelt-stats-cli/v1";
+/** What `smelt stats --json` prints: the {@link RetrieveStats} verbatim, versioned. */
+export interface CliStatsJsonEnvelope {
+    readonly format: string;
+    /** The {@link RetrieveStats} exactly as the store's `stats()` returned them. */
+    readonly stats: RetrieveStats;
+}
+export declare const statsCommand: Subcommand<StatsInvocation, ResolvedStatsRun>;
+//# sourceMappingURL=stats.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"stats.d.ts","sourceRoot":"","sources":["../../../src/cli/subcommands/stats.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAMpD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACtD,OAAO,KAAK,EAAgB,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAEhE;;;;;;;;;;;;;;;GAeG;AAEH,wEAAwE;AACxE,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;CACxB;AAED,wEAAwE;AACxE,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,gBAAgB,CAAC;IACjC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;CACxB;AAED;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,uBAAuB,CAAC;AAE1D,uFAAuF;AACvF,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,gFAAgF;IAChF,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;CAC/B;AAED,eAAO,MAAM,YAAY,EAAE,UAAU,CAAC,eAAe,EAAE,gBAAgB,CA2DtE,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/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';
+/** 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,CAAC;AAE7E,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';\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