@smeltjs/core 0.1.0

package/dist/cache/prefix.js

@@ -0,0 +1,361 @@
+/**
+ * Cache-prefix hygiene — Slice 6. **Detect and warn, never rewrite.**
+ *
+ * **This module is a consumer-facing surface**, exported from the package
+ * entrypoint and stable in intent: hand it your prompt structure, get warnings
+ * back, decide for yourself. It composes with nothing else in smelt — no planner
+ * calls it, no store holds its output — because cache hygiene is a property of the
+ * *request* a consumer assembles, which smelt never sees or intercepts. Use it
+ * from your own send path:
+ *
+ * ```ts
+ * // Both functions come from the package entrypoint:
+ * //   detectCacheBreakers, findPrefixDivergence
+ *
+ * // Before sending: name the silent cache-breakers in what you are about to send.
+ * const warnings = detectCacheBreakers(
+ *   { tools, system },           // this call
+ *   { tools: previousTools },    // optional: the previous call, for tool-set drift
+ * );
+ * // → [{ rule: 'system-timestamp', explanation: 'system prompt contains …' }, …]
+ *
+ * // Between calls: where exactly did the cached prefix stop matching, and what
+ * // did the change cost? `undefined` means intact (identical, or a pure append).
+ * const divergence = findPrefixDivergence(previousPrefix, nextPrefix);
+ * // → { byteOffset, invalidatedBytes, description } | undefined
+ * ```
+ *
+ * Nothing is ever rewritten on your behalf, and no rate is ever claimed — the
+ * paragraphs below say why both refusals are load-bearing.
+ *
+ * Provider prompt caches match the request prefix byte for byte, so a context
+ * optimizer that reorders or rewrites a prompt prefix to "help" a cache can cost
+ * more than it saves — and worse, a reordering that changes model behaviour is an
+ * unexplainable elision wearing a different hat. Headroom's CacheAligner made the
+ * same call: it detects prefix volatility and warns; it never edits the prompt.
+ * Neither does this module. Every function here is a pure read over its inputs:
+ * nothing is mutated, and nothing "fixed" is ever returned. That is not a comment,
+ * it is a guarantee — `test/guards/cache-hygiene.test.ts` asserts it on frozen
+ * inputs, and `pnpm mutate` proves the guard goes red when a helpful in-place fix
+ * appears.
+ *
+ * Warnings follow the `ElisionReason` two-field discipline from `types.ts`:
+ * a stable `rule` id for counters, and an `explanation` a human reads. A warning
+ * that cannot be written as a sentence is a rule nobody understands.
+ */
+/**
+ * Facts about Anthropic's prompt cache, as published in Anthropic's prompt-caching
+ * documentation (docs.anthropic.com), verified 2026-09-01.
+ *
+ * These are *cited provider facts*, not smelt measurements — the only numbers Law 4
+ * permits are someone else's, with their source and date named. In particular this
+ * module claims nothing about how often anyone's cache hits: the price multipliers
+ * below are prices, and a price is not a frequency.
+ */
+export const ANTHROPIC_PROMPT_CACHE_FACTS = {
+    /** Where every number in this object comes from, and when it was checked. */
+    source: 'Anthropic prompt-caching documentation (docs.anthropic.com), verified 2026-09-01',
+    /**
+     * The cached prefix is matched byte for byte over the request in this order.
+     * A byte change in `tools` therefore invalidates `system` and `messages` too.
+     */
+    prefixOrder: ['tools', 'system', 'messages'],
+    /** Any byte change invalidates the cache from that byte to the end of the prefix. */
+    invalidation: 'byte-exact; any change invalidates everything after it',
+    /** Minimum cacheable prefix, in tokens — approximately 1024 for most models. */
+    minCacheablePrefixTokensApprox: 1024,
+    /** Maximum number of cache breakpoints per request. */
+    maxCacheBreakpoints: 4,
+    /** Default time-to-live of a cache entry, in minutes. */
+    defaultTtlMinutes: 5,
+    /** Optional extended time-to-live, in minutes (one hour). */
+    extendedTtlMinutes: 60,
+    /** Writing a 5-minute cache entry costs 1.25x the base input-token price. */
+    writeCostMultiplier5m: 1.25,
+    /** Writing a 1-hour cache entry costs 2x the base input-token price. */
+    writeCostMultiplier1h: 2,
+    /** Reading a cached prefix costs approximately 0.1x the base input-token price. */
+    readCostMultiplierApprox: 0.1,
+};
+/**
+ * The provider's serialization order, rendered as prose from the cited constant
+ * above — so the sentence in a warning can never drift from the fact it cites.
+ */
+const PREFIX_ORDER_PROSE = ANTHROPIC_PROMPT_CACHE_FACTS.prefixOrder.join(' → ');
+/** The stable rule ids this module can emit. Additive over time, never renamed. */
+export const CACHE_BREAKER_RULES = {
+    /** A timestamp-shaped value in the system prompt. */
+    systemTimestamp: 'system-timestamp',
+    /** A UUID in the system prompt. */
+    systemUuid: 'system-uuid',
+    /** An object in a tool definition whose keys are not in sorted order. */
+    unsortedJsonKeys: 'unsorted-json-keys',
+    /** The tool set changed between two successive calls. */
+    toolSetVaries: 'tool-set-varies',
+};
+/** Code points around the code point containing `byteOffset` — never a split character. */
+function excerptAroundByte(text, byteOffset, radius = 16) {
+    const points = [...text];
+    let index = points.length;
+    let bytes = 0;
+    for (const [i, point] of points.entries()) {
+        const width = Buffer.byteLength(point, 'utf8');
+        if (byteOffset < bytes + width) {
+            index = i;
+            break;
+        }
+        bytes += width;
+    }
+    const start = Math.max(0, index - radius);
+    const end = Math.min(points.length, index + radius);
+    const head = start > 0 ? '…' : '';
+    const tail = end < points.length ? '…' : '';
+    return head + points.slice(start, end).join('') + tail;
+}
+/**
+ * Compare two successive prompt prefixes the way the provider's cache does: byte
+ * for byte, in UTF-8.
+ *
+ * Returns `undefined` when `next` starts with every byte of `previous` — identical
+ * prefixes, or a pure append, both of which leave a cached prefix intact. Anything
+ * else returns the first divergent byte offset and a description of what changed
+ * around it. This function reports; it does not repair.
+ */
+export function findPrefixDivergence(previous, next) {
+    const previousBytes = Buffer.from(previous, 'utf8');
+    const nextBytes = Buffer.from(next, 'utf8');
+    const limit = Math.min(previousBytes.length, nextBytes.length);
+    let byteOffset = 0;
+    while (byteOffset < limit && previousBytes[byteOffset] === nextBytes[byteOffset]) {
+        byteOffset += 1;
+    }
+    if (byteOffset === previousBytes.length)
+        return undefined;
+    const invalidatedBytes = previousBytes.length - byteOffset;
+    const previousExcerpt = JSON.stringify(excerptAroundByte(previous, byteOffset));
+    const description = byteOffset === nextBytes.length
+        ? `next ends at byte ${String(byteOffset)}, where previous continued with ` +
+            `${previousExcerpt}; the ${String(invalidatedBytes)} bytes previous carried from ` +
+            `there are gone from the prefix`
+        : `first divergence at byte ${String(byteOffset)}: previous has ${previousExcerpt} ` +
+            `where next has ${JSON.stringify(excerptAroundByte(next, byteOffset))}; a byte-matched ` +
+            `cache stops matching here, so the ${String(invalidatedBytes)} bytes after this ` +
+            `point are re-sent cold`;
+    return { byteOffset, invalidatedBytes, description };
+}
+/** ISO-8601-shaped dates and datetimes — the values that move with the clock. */
+const TIMESTAMP_PATTERN = /\b\d{4}-\d{2}-\d{2}(?:[T ]\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:?\d{2})?)?\b/g;
+/** RFC 4122 textual UUIDs — the values that are fresh per process or per call. */
+const UUID_PATTERN = /\b[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}\b/g;
+function byteOffsetOf(text, index) {
+    return Buffer.byteLength(text.slice(0, index), 'utf8');
+}
+function scanSystemPrompt(system) {
+    const warnings = [];
+    const timestamps = [...system.matchAll(TIMESTAMP_PATTERN)];
+    const firstTimestamp = timestamps[0];
+    if (firstTimestamp !== undefined) {
+        warnings.push({
+            rule: CACHE_BREAKER_RULES.systemTimestamp,
+            explanation: `system prompt contains ${String(timestamps.length)} timestamp-shaped ` +
+                `value${timestamps.length === 1 ? '' : 's'}, first "${firstTimestamp[0]}" at byte ` +
+                `${String(byteOffsetOf(system, firstTimestamp.index))}; a value that moves with ` +
+                `the clock changes bytes between calls and silently invalidates the cached ` +
+                `prefix from that byte`,
+        });
+    }
+    const uuids = [...system.matchAll(UUID_PATTERN)];
+    const firstUuid = uuids[0];
+    if (firstUuid !== undefined) {
+        warnings.push({
+            rule: CACHE_BREAKER_RULES.systemUuid,
+            explanation: `system prompt contains ${String(uuids.length)} UUID${uuids.length === 1 ? '' : 's'}, ` +
+                `first "${firstUuid[0]}" at byte ${String(byteOffsetOf(system, firstUuid.index))}; ` +
+                `an id minted per session or per call changes bytes between calls and silently ` +
+                `invalidates the cached prefix from that byte`,
+        });
+    }
+    return warnings;
+}
+/**
+ * Keys that JavaScript treats as array indices. Their enumeration position is
+ * fixed by the language (ascending numeric, ahead of every string key), so they
+ * are not "reorderable" in any sense a serializer could act on.
+ */
+const INTEGER_LIKE_KEY = /^(?:0|[1-9]\d*)$/;
+/** The first object (depth-first) whose own keys are not in sorted order. Read-only walk. */
+function findUnsortedKeys(value, path) {
+    if (Array.isArray(value)) {
+        for (const [i, item] of value.entries()) {
+            const found = findUnsortedKeys(item, `${path}[${String(i)}]`);
+            if (found !== undefined)
+                return found;
+        }
+        return undefined;
+    }
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    const record = value;
+    const keys = Object.keys(record);
+    // Array-index-like keys are excluded from the order check: JavaScript enumerates
+    // them first, in ascending numeric order, regardless of how they were written or
+    // inserted — so no serializer walking the object can emit them differently
+    // between calls, and their fixed numeric order ("2" before "10") is exactly what
+    // a lexicographic check would flag. A warning about an order the caller cannot
+    // change would be a warning nobody can act on.
+    const reorderable = keys.filter((key) => !INTEGER_LIKE_KEY.test(key));
+    for (let i = 1; i < reorderable.length; i += 1) {
+        if (reorderable[i - 1] > reorderable[i]) {
+            return { path, before: reorderable[i - 1], after: reorderable[i] };
+        }
+    }
+    for (const key of keys) {
+        const found = findUnsortedKeys(record[key], `${path}.${key}`);
+        if (found !== undefined)
+            return found;
+    }
+    return undefined;
+}
+function scanToolKeyOrder(tools) {
+    const warnings = [];
+    for (const tool of tools) {
+        const found = findUnsortedKeys(tool, `tool "${tool.name}"`);
+        if (found !== undefined) {
+            warnings.push({
+                rule: CACHE_BREAKER_RULES.unsortedJsonKeys,
+                explanation: `${found.path} has JSON keys out of sorted order ("${found.before}" before ` +
+                    `"${found.after}"); a serializer with no canonical key order can emit them ` +
+                    `differently between calls, changing bytes in the cached prefix with the ` +
+                    `content unchanged`,
+            });
+        }
+    }
+    return warnings;
+}
+const quoteNames = (names) => names.map((name) => `"${name}"`).join(', ');
+/**
+ * Stable canonical serialization of one value, for comparing tool definitions
+ * between calls the way the cache experiences them: by content. Keys are sorted at
+ * every depth, so the comparison is independent of enumeration order — an
+ * *ordering* a serializer might vary is `unsorted-json-keys`' concern — while any
+ * content change at all (a description edit, a schema tweak, a new field) compares
+ * different even when every tool name is unchanged.
+ */
+function canonicalize(value) {
+    if (Array.isArray(value))
+        return `[${value.map((item) => canonicalize(item)).join(',')}]`;
+    if (typeof value === 'object' && value !== null) {
+        const record = value;
+        const body = Object.keys(record)
+            .toSorted()
+            .map((key) => `${JSON.stringify(key)}:${canonicalize(record[key])}`)
+            .join(',');
+        return `{${body}}`;
+    }
+    return JSON.stringify(value) ?? 'undefined';
+}
+/** How many times each tool name appears — duplicates are counted, not collapsed. */
+function countByName(tools) {
+    const counts = new Map();
+    for (const tool of tools)
+        counts.set(tool.name, (counts.get(tool.name) ?? 0) + 1);
+    return counts;
+}
+/**
+ * Describe a count change for one name truthfully. When the name also exists on
+ * the other side, what changed is the number of copies — saying `added "x"` about
+ * a duplicate, or claiming "same tools" when a duplicate went away, would
+ * misstate what the cache saw.
+ */
+function describeCopies(name, delta, otherSideHasIt) {
+    if (!otherSideHasIt)
+        return delta === 1 ? `"${name}"` : `${String(delta)} copies of "${name}"`;
+    return delta === 1 ? `a duplicate of "${name}"` : `${String(delta)} duplicates of "${name}"`;
+}
+function compareToolSets(previous, current) {
+    // Content comparison, not name comparison: the cache matches serialized bytes,
+    // so a rewritten description under an unchanged name breaks it just as surely as
+    // a renamed tool does.
+    const previousCanonical = previous.map((tool) => canonicalize(tool));
+    const currentCanonical = current.map((tool) => canonicalize(tool));
+    const identical = previousCanonical.length === currentCanonical.length &&
+        previousCanonical.every((tool, i) => tool === currentCanonical[i]);
+    if (identical)
+        return undefined;
+    const previousCounts = countByName(previous);
+    const currentCounts = countByName(current);
+    const added = [];
+    for (const [name, count] of currentCounts) {
+        const delta = count - (previousCounts.get(name) ?? 0);
+        if (delta > 0)
+            added.push(describeCopies(name, delta, previousCounts.has(name)));
+    }
+    const removed = [];
+    for (const [name, count] of previousCounts) {
+        const delta = count - (currentCounts.get(name) ?? 0);
+        if (delta > 0)
+            removed.push(describeCopies(name, delta, currentCounts.has(name)));
+    }
+    const changes = [];
+    if (added.length > 0)
+        changes.push(`added ${added.join(', ')}`);
+    if (removed.length > 0)
+        changes.push(`removed ${removed.join(', ')}`);
+    if (changes.length === 0) {
+        // Every name appears the same number of times on both sides, so what differs
+        // is order, content, or both.
+        const sameNameOrder = previous.length === current.length &&
+            previous.every((tool, i) => tool.name === current[i].name);
+        const sameContent = previousCanonical.toSorted().join('') === currentCanonical.toSorted().join('');
+        if (!sameNameOrder) {
+            changes.push(sameContent
+                ? 'same tools, different order'
+                : 'same tool names in a different order, with definitions changed');
+        }
+        else {
+            const changed = [
+                ...new Set(current
+                    .filter((_tool, i) => currentCanonical[i] !== previousCanonical[i])
+                    .map((tool) => tool.name)),
+            ];
+            const plural = changed.length === 1 ? '' : 's';
+            changes.push(`definition${plural} of ${quoteNames(changed)} changed with the name${plural} unchanged`);
+        }
+    }
+    return {
+        rule: CACHE_BREAKER_RULES.toolSetVaries,
+        explanation: `tool set changed between calls (${changes.join('; ')}); tools serialize first in ` +
+            `the cached prefix (${PREFIX_ORDER_PROSE}), so this invalidates the entire ` +
+            `cache including the system prompt and every message`,
+    };
+}
+/**
+ * Detect the named silent cache-breakers in a prompt structure.
+ *
+ * Three rules over `current` and, when `previous` is supplied, one across the pair:
+ *
+ * - `system-timestamp` — a timestamp-shaped value in the system prompt
+ * - `system-uuid` — a UUID in the system prompt
+ * - `unsorted-json-keys` — a tool-definition object whose keys are not sorted
+ * - `tool-set-varies` — the tools differ from the previous call's, by content:
+ *   an added, removed or duplicated tool, a reorder, or a definition rewritten
+ *   under an unchanged name
+ *
+ * Pure and read-only: inputs are never mutated, and the return value is warnings
+ * only — never a corrected prompt. Deciding what to do about a warning is the
+ * caller's call, in the caller's code.
+ */
+export function detectCacheBreakers(current, previous) {
+    const warnings = [];
+    if (current.system !== undefined)
+        warnings.push(...scanSystemPrompt(current.system));
+    if (current.tools !== undefined)
+        warnings.push(...scanToolKeyOrder(current.tools));
+    if (previous !== undefined) {
+        const varies = compareToolSets(previous.tools ?? [], current.tools ?? []);
+        if (varies !== undefined)
+            warnings.push(varies);
+    }
+    return warnings;
+}
+//# sourceMappingURL=prefix.js.map

package/dist/cache/prefix.js.map

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

package/dist/cli/args.d.ts

@@ -0,0 +1,71 @@
+import type { Strategy } from '../plan/planners.ts';
+import type { DetectedLanguage } from '../types.ts';
+/** The command people type. Independent of the package name. */
+export declare const CLI_NAME = "smelt";
+/** What the CLI was asked to do. Pure data, so the parse is testable on its own. */
+export interface SmeltInvocation {
+    readonly mode: 'smelt' | 'reconstruct' | 'help' | 'version' | 'init';
+    /** Path to read. `undefined` means stdin. */
+    readonly file?: string;
+    /**
+     * UTF-8 bytes. `undefined` in `'smelt'` mode means the flag was not given; the
+     * runner then consults `smelt.config.json` and errors if that has no default either.
+     */
+    readonly budgetBytes?: number;
+    readonly focus: readonly string[];
+    readonly language?: DetectedLanguage;
+    /** `undefined` means the flag was not given — the config default may apply. */
+    readonly strategy?: Strategy;
+    readonly json: boolean;
+}
+/**
+ * `smelt map <dir>` — the repo-map subcommand, parsed. A separate shape rather than
+ * more optional fields on {@link SmeltInvocation}, because the two commands share
+ * almost nothing: a map has a directory instead of a file/stdin, an ignore list and
+ * a cache directory instead of a language and a strategy.
+ */
+export interface MapInvocation {
+    readonly mode: 'map';
+    /** The repository root to map. Always present — `map` without a directory is a usage error. */
+    readonly dir: string;
+    /** `undefined` means the flag was not given — the config default may apply. */
+    readonly budgetBytes?: number;
+    readonly focus: readonly string[];
+    /** `--ignore` entries, replacing the built-in default list when non-empty. */
+    readonly ignore: readonly string[];
+    /** `--cache <dir>`: only when given does the map write to disk. */
+    readonly cacheDir?: string;
+    readonly json: boolean;
+}
+/**
+ * `smelt retrieve <hash>` — the marker's `retrieve("hash")` as a real command, parsed.
+ * A {@link MapInvocation}-style sibling: nothing but the hash, because the command's
+ * whole contract is "hash in, exact bytes out" — the same contract as the
+ * `smelt_retrieve` tool, reachable from a shell.
+ */
+export interface RetrieveInvocation {
+    readonly mode: 'retrieve';
+    /** The hash exactly as the marker printed it. Validated by the store, not here. */
+    readonly hash: string;
+}
+/** `smelt stats` — the store's counters, read without touching them. */
+export interface StatsInvocation {
+    readonly mode: 'stats';
+    readonly json: boolean;
+}
+/** Everything `parseSmeltArgs` can return. Narrow on `mode`. */
+export type CliInvocation = SmeltInvocation | MapInvocation | RetrieveInvocation | StatsInvocation;
+/**
+ * Argument parsing on `node:util.parseArgs` — stable since Node 20, which `engines`
+ * already requires.
+ *
+ * The CLI ships as a `bin` on the library rather than as a second package, and this
+ * import is the reason that is free: it adds no dependency, so the argument the second
+ * package existed to win — keeping the library's dependency tree small — is already won.
+ *
+ * @throws {CliUsageError} on anything the user got wrong. Never guesses.
+ */
+export declare function parseSmeltArgs(argv: readonly string[]): CliInvocation;
+/** The help text. Also the closest thing the CLI has to documentation. */
+export declare function cliUsage(): string;
+//# sourceMappingURL=args.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"args.d.ts","sourceRoot":"","sources":["../../src/cli/args.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAEpD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEpD,gEAAgE;AAChE,eAAO,MAAM,QAAQ,UAAU,CAAC;AAEhC,oFAAoF;AACpF,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,aAAa,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,CAAC;IACrE,6CAA6C;IAC7C,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IACrC,+EAA+E;IAC/E,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;CACxB;AAED;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IACrB,+FAA+F;IAC/F,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,+EAA+E;IAC/E,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,8EAA8E;IAC9E,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,mEAAmE;IACnE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;CACxB;AAED;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,mFAAmF;IACnF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,wEAAwE;AACxE,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;CACxB;AAED,gEAAgE;AAChE,MAAM,MAAM,aAAa,GAAG,eAAe,GAAG,aAAa,GAAG,kBAAkB,GAAG,eAAe,CAAC;AAEnG;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,aAAa,CA0GrE;AAuJD,0EAA0E;AAC1E,wBAAgB,QAAQ,IAAI,MAAM,CA8FjC"}