@smeltjs/core 0.1.0

package/dist/apply.js

@@ -0,0 +1,244 @@
+import { OverlappingElisionError, RangeOutOfBoundsError, UnknownHashError } from './errors.js';
+import { HASH_LENGTH } from './hash.js';
+import { LANGUAGE_PROFILES } from './lang/registry.js';
+/**
+ * The version of the marker format itself, carried **in band** in every marker.
+ *
+ * The marker is the one part of smelt a *model* sees, and it goes into prompts.
+ * Changing its shape changes model behaviour downstream and shows up as worse output
+ * with no error anywhere — this project's signature failure mode, shipped as a patch
+ * release. So the wire surface is frozen from 0.1 and treated as 1.0
+ * (`CONTRIBUTING.md` § "Two promises, not one"), and a future format is *additive and
+ * identifiable*: `smelt/v2` markers can coexist with `smelt/v1` ones, and a consumer
+ * parsing markers can tell which it is holding. A format that changed silently would
+ * be a substitution; this makes it a declaration.
+ *
+ * `test/guards/marker-format.test.ts` pins the rendered marker per version and fails if
+ * the format moves without the version moving.
+ */
+export const MARKER_FORMAT_VERSION = 'v1';
+/**
+ * The default marker.
+ *
+ * Its shape is the user-facing form of Laws 2 and 3, in one line the model reads:
+ * *which format this is* (the version), *what was removed* (the explanation), *how
+ * much* (the byte count), and *how to get it back* (the hash). Anything that cannot
+ * fill in all of those is not allowed to be an elision.
+ *
+ * `<<…>>` rather than a Unicode bracket because it survives every tokenizer, terminal,
+ * and diff tool without becoming three tokens of nothing.
+ */
+export const defaultMarker = ({ explanation, bytes, hash }) => `<<smelt/${MARKER_FORMAT_VERSION}: ${explanation} (${String(bytes)}B) — retrieve("${hash}")>>`;
+/**
+ * Line-comment leaders per language: the marker always lands as a comment in the
+ * survivor's own syntax, because a bare marker line breaks the syntax of what remains
+ * around it — in **every** grammar this was tested against, not just the indented ones.
+ *
+ * The failure classes, each verified by reparsing a bare-marker survivor:
+ *
+ *   - **python** — significant indentation means a parse error does not stay local.
+ *     The ERROR node swallows the *neighbouring definitions too* — the survivor stops
+ *     being Python at all, not just at the marker line.
+ *   - **ruby** and **bash** — the marker *begins with* `<<`, which both languages read
+ *     as a heredoc operator. A bare marker line opens a heredoc whose terminator never
+ *     arrives, and everything after it — every kept declaration — is swallowed into a
+ *     string literal.
+ *   - **php** — `<<` is an operator here too: the kept function after a bare marker is
+ *     re-typed into an anonymous-function operand inside the marker's binary
+ *     expression. The kept declaration is no longer a declaration in the survivor.
+ *   - **kotlin**, **swift**, and the rest of the brace-delimited set (typescript, tsx,
+ *     javascript, rust, go, java, c, cpp, c_sharp) — the folk claim that braces keep a
+ *     parse error local is **empirically false**: reparsing each language's fixture
+ *     survivor with its own bundled grammar shows ERROR nodes spanning the kept
+ *     declarations (a C function's signature absorbed into an ERROR, fifteen cascading
+ *     ERRORs in swift, and so on). The survivor-reparse guard in
+ *     `test/guards/structural.test.ts` now asserts the opposite property for every
+ *     structural language: the survivor reparses with no new issues.
+ *
+ * Only `'unknown'` keeps the bare marker — lexical text has no syntax to break.
+ *
+ * This does **not** move the frozen wire surface. The `<<smelt/v1: … >>` core is
+ * rendered by {@link defaultMarker}, byte-identical and still versioned in band; the
+ * leader is part of the substituted marker text, so `outputRange` covers it and
+ * reconstruction stays byte-exact. A comment leader in the survivor's own syntax is
+ * the one wrapping that cannot change what a model reads out of the marker.
+ *
+ * A derived view: each leader is the `markerLeader` fact on the language's
+ * {@link LanguageProfile} (`src/lang/`), collected here so marker construction keeps
+ * one lookup table.
+ */
+export const MARKER_LINE_COMMENT_LEADERS = Object.fromEntries(Object.values(LANGUAGE_PROFILES)
+    .filter((profile) => profile.markerLeader !== undefined)
+    .map((profile) => [profile.id, profile.markerLeader]));
+/**
+ * The marker builder for a language: {@link defaultMarker}, wrapped in the language's
+ * line-comment leader when {@link MARKER_LINE_COMMENT_LEADERS} names one — so a Python
+ * survivor still parses as Python. Everything else gets `base` unchanged.
+ */
+export function markerForLanguage(language, base = defaultMarker) {
+    const leader = MARKER_LINE_COMMENT_LEADERS[language];
+    if (leader === undefined)
+        return base;
+    return (info) => `${leader}${base(info)}`;
+}
+/**
+ * A stand-in hash of the real length, so a marker can be priced before the cut that
+ * would earn it exists. Marker cost depends on the hash's *length*, never its value.
+ */
+const PLACEHOLDER_HASH = '0'.repeat(HASH_LENGTH);
+/**
+ * The one adapter behind the {@link MarkerPricing} seam.
+ *
+ * Marker cost is this module's fact: `applyPlan` renders the marker, so only this
+ * module can price it without guessing. The pricing is built from the **exact builder
+ * `applyPlan` will use** — the same resolution, in the same order: a caller-supplied
+ * builder (`SmelterConfig.marker` / `ApplyOptions.marker`) wins wholesale, otherwise
+ * the language's leader-wrapped default via {@link markerForLanguage}.
+ *
+ * The custom-builder leg is load-bearing, not a convenience: a caller who installs a
+ * longer `MarkerBuilder` changes what every elision costs, and a planner still pricing
+ * the *default* marker would keep planning elisions the real marker makes
+ * unprofitable — cuts that grow the output, silently. Pricing with the builder's own
+ * rendering closes that hole: `costBytes` measures the marker *that builder* would
+ * emit, byte for byte.
+ *
+ * `createSmelter` (and through it, the CLI) calls this centrally, once per smelt call;
+ * a caller driving `planLexical`/`planStructural` directly builds its own and puts it
+ * on the {@link PlanInput}.
+ */
+export function markerPricing(language = 'unknown', markerBuilder) {
+    // The same resolution applyPlan performs: a supplied builder wins wholesale.
+    const build = markerBuilder ?? markerForLanguage(language);
+    return {
+        costBytes: (reason, elidedBytes) => Buffer.byteLength(build({
+            hash: PLACEHOLDER_HASH,
+            bytes: elidedBytes,
+            rule: reason.rule,
+            explanation: reason.explanation,
+        }), 'utf8'),
+    };
+}
+/**
+ * Turn a plan into text.
+ *
+ * This is the only function in smelt that removes anything, and it contains no
+ * judgement at all: it validates the plan, stores every removed run, substitutes
+ * markers, and records where each marker landed. All the deciding happens in a
+ * {@link Planner}, which is why a plan can be reviewed before a byte moves.
+ *
+ * @throws {RangeOutOfBoundsError} if a range falls outside the input's UTF-8 bytes.
+ * @throws {OverlappingElisionError} if two ranges overlap — applying both would
+ *   corrupt the output, and picking a winner would be a silent guess.
+ */
+export function applyPlan(text, plan, store, options = {}) {
+    const buildMarker = options.marker ?? markerForLanguage(plan.language);
+    const input = Buffer.from(text, 'utf8');
+    const ordered = plan.elisions.toSorted((a, b) => a.range.start - b.range.start);
+    for (const { range } of ordered)
+        assertInBounds(range, input.length);
+    for (let i = 1; i < ordered.length; i += 1) {
+        const previous = ordered[i - 1];
+        const current = ordered[i];
+        if (current.range.start < previous.range.end) {
+            throw new OverlappingElisionError(`smelt: plan from "${plan.planner}" elides overlapping ranges ` +
+                `[${previous.range.start},${previous.range.end}) and ` +
+                `[${current.range.start},${current.range.end}). A plan must be a partition.`);
+        }
+    }
+    const pieces = [];
+    const applied = [];
+    let cursor = 0;
+    let outputBytes = 0;
+    for (const { range, reason } of ordered) {
+        const kept = input.subarray(cursor, range.start);
+        pieces.push(kept);
+        outputBytes += kept.length;
+        const removed = input.subarray(range.start, range.end);
+        const removedText = removed.toString('utf8');
+        const hash = store.put(removedText);
+        const marker = buildMarker({
+            hash,
+            bytes: removed.length,
+            rule: reason.rule,
+            explanation: reason.explanation,
+        });
+        const markerBuffer = Buffer.from(marker, 'utf8');
+        pieces.push(markerBuffer);
+        applied.push({
+            hash,
+            range,
+            outputRange: { start: outputBytes, end: outputBytes + markerBuffer.length },
+            bytes: removed.length,
+            reason,
+            marker,
+        });
+        outputBytes += markerBuffer.length;
+        cursor = range.end;
+    }
+    const tail = input.subarray(cursor);
+    pieces.push(tail);
+    outputBytes += tail.length;
+    const output = Buffer.concat(pieces).toString('utf8');
+    const measure = options.measure;
+    return {
+        text: output,
+        inputBytes: input.length,
+        outputBytes,
+        planner: plan.planner,
+        language: plan.language,
+        elisions: applied,
+        ...(measure === undefined
+            ? {}
+            : {
+                measured: {
+                    measure: measure.id,
+                    unit: measure.unit,
+                    input: measure.count(text),
+                    output: measure.count(output),
+                },
+            }),
+    };
+}
+/**
+ * Put it all back. `reconstruct(smelt(x), store) === x`, byte for byte — this is Law 3
+ * expressed as an executable equation, and `test/guards/reversibility.test.ts` asserts
+ * it on every input the suite knows about.
+ *
+ * Reads through `peek`, **not** `retrieve`: `retrieveCalls` and the expansion rate
+ * exist to count *the model asking for hidden material back* — the honest signal this
+ * whole project sells. A caller reassembling the original (to diff it, to verify a
+ * round trip, to write it to disk) is not that, and counting it would inflate the one
+ * number that must never flatter. The guard in
+ * `test/guards/expansion-counter.test.ts` pins this: reconstruction leaves every
+ * counter exactly where it was.
+ *
+ * @throws {UnknownHashError} if the store no longer holds an elision's bytes.
+ */
+export function reconstruct(result, store) {
+    const output = Buffer.from(result.text, 'utf8');
+    const ordered = result.elisions.toSorted((a, b) => a.outputRange.start - b.outputRange.start);
+    const pieces = [];
+    let cursor = 0;
+    for (const elision of ordered) {
+        assertInBounds(elision.outputRange, output.length);
+        const content = store.peek(elision.hash);
+        if (content === undefined)
+            throw new UnknownHashError(elision.hash);
+        pieces.push(output.subarray(cursor, elision.outputRange.start));
+        pieces.push(Buffer.from(content, 'utf8'));
+        cursor = elision.outputRange.end;
+    }
+    pieces.push(output.subarray(cursor));
+    return Buffer.concat(pieces).toString('utf8');
+}
+function assertInBounds(range, length) {
+    if (!Number.isInteger(range.start) ||
+        !Number.isInteger(range.end) ||
+        range.start < 0 ||
+        range.end > length ||
+        range.start >= range.end) {
+        throw new RangeOutOfBoundsError(`smelt: range [${range.start},${range.end}) is not a non-empty range inside ` +
+            `${String(length)} bytes.`);
+    }
+}
+//# sourceMappingURL=apply.js.map

package/dist/apply.js.map

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

package/dist/cache/prefix.d.ts

@@ -0,0 +1,164 @@
+/**
+ * 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 declare const ANTHROPIC_PROMPT_CACHE_FACTS: {
+    /** Where every number in this object comes from, and when it was checked. */
+    readonly 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.
+     */
+    readonly prefixOrder: readonly ['tools', 'system', 'messages'];
+    /** Any byte change invalidates the cache from that byte to the end of the prefix. */
+    readonly invalidation: 'byte-exact; any change invalidates everything after it';
+    /** Minimum cacheable prefix, in tokens — approximately 1024 for most models. */
+    readonly minCacheablePrefixTokensApprox: 1024;
+    /** Maximum number of cache breakpoints per request. */
+    readonly maxCacheBreakpoints: 4;
+    /** Default time-to-live of a cache entry, in minutes. */
+    readonly defaultTtlMinutes: 5;
+    /** Optional extended time-to-live, in minutes (one hour). */
+    readonly extendedTtlMinutes: 60;
+    /** Writing a 5-minute cache entry costs 1.25x the base input-token price. */
+    readonly writeCostMultiplier5m: 1.25;
+    /** Writing a 1-hour cache entry costs 2x the base input-token price. */
+    readonly writeCostMultiplier1h: 2;
+    /** Reading a cached prefix costs approximately 0.1x the base input-token price. */
+    readonly readCostMultiplierApprox: 0.1;
+};
+/**
+ * A cache-hygiene warning. Deliberately the same two-field shape as
+ * `ElisionReason` in `types.ts`, and for the same reason: a stable id for counters, a
+ * sentence for humans, and nothing else — no patch, no replacement text, no
+ * "fixed" prompt. Warning is all this module does.
+ */
+export interface CacheWarning {
+    /** Stable machine id, e.g. `'system-timestamp'`. */
+    readonly rule: string;
+    /** Present tense, no trailing period, names the evidence. */
+    readonly explanation: string;
+}
+/** The stable rule ids this module can emit. Additive over time, never renamed. */
+export declare const CACHE_BREAKER_RULES: {
+    /** A timestamp-shaped value in the system prompt. */
+    readonly systemTimestamp: 'system-timestamp';
+    /** A UUID in the system prompt. */
+    readonly systemUuid: 'system-uuid';
+    /** An object in a tool definition whose keys are not in sorted order. */
+    readonly unsortedJsonKeys: 'unsorted-json-keys';
+    /** The tool set changed between two successive calls. */
+    readonly toolSetVaries: 'tool-set-varies';
+};
+/**
+ * The first byte where two successive prompt prefixes diverge, with a description
+ * of what changed around it. Offsets are UTF-8 **byte** offsets, because that is
+ * the unit the provider's cache matches in — a code-unit index would be a lie for
+ * any prompt containing a multi-byte character.
+ */
+export interface PrefixDivergence {
+    /** UTF-8 byte offset of the first byte at which the two prefixes differ. */
+    readonly byteOffset: number;
+    /** Bytes of `previous` from the divergence to its end — the span a cache no longer matches. */
+    readonly invalidatedBytes: number;
+    /** What changed around the divergence. Excerpts never split a multi-byte character. */
+    readonly description: string;
+}
+/**
+ * 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 declare function findPrefixDivergence(previous: string, next: string): PrefixDivergence | undefined;
+/**
+ * One tool definition as the caller sends it. Only `name` is required here —
+ * the rest of the definition is scanned structurally, whatever shape it has.
+ */
+export interface PromptTool {
+    readonly name: string;
+    readonly [key: string]: unknown;
+}
+/**
+ * The prompt structure smelt is shown for hygiene checks — the two parts that
+ * serialize ahead of the messages in the cached prefix. smelt never sees, holds,
+ * or edits the real request; the caller hands in a description and gets warnings
+ * back.
+ */
+export interface PromptStructure {
+    /** Tool definitions, in the order they are sent. */
+    readonly tools?: readonly PromptTool[];
+    /** The system prompt text. */
+    readonly system?: string;
+}
+/**
+ * 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 declare function detectCacheBreakers(current: PromptStructure, previous?: PromptStructure): readonly CacheWarning[];
+//# sourceMappingURL=prefix.d.ts.map

package/dist/cache/prefix.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prefix.d.ts","sourceRoot":"","sources":["../../src/cache/prefix.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,4BAA4B;IACvC,6EAA6E;aAC7E,MAAM,EAAE,kFAAkF;IAC1F;;;OAGG;aACH,WAAW,YAAG,OAAO,EAAE,QAAQ,EAAE,UAAU;IAC3C,qFAAqF;aACrF,YAAY,EAAE,wDAAwD;IACtE,gFAAgF;aAChF,8BAA8B,EAAE,IAAI;IACpC,uDAAuD;aACvD,mBAAmB,EAAE,CAAC;IACtB,yDAAyD;aACzD,iBAAiB,EAAE,CAAC;IACpB,6DAA6D;aAC7D,kBAAkB,EAAE,EAAE;IACtB,6EAA6E;aAC7E,qBAAqB,EAAE,IAAI;IAC3B,wEAAwE;aACxE,qBAAqB,EAAE,CAAC;IACxB,mFAAmF;aACnF,wBAAwB,EAAE,GAAG;CACrB,CAAC;AAEX;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,oDAAoD;IACpD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,6DAA6D;IAC7D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAQD,mFAAmF;AACnF,eAAO,MAAM,mBAAmB;IAC9B,qDAAqD;aACrD,eAAe,EAAE,kBAAkB;IACnC,mCAAmC;aACnC,UAAU,EAAE,aAAa;IACzB,yEAAyE;aACzE,gBAAgB,EAAE,oBAAoB;IACtC,yDAAyD;aACzD,aAAa,EAAE,iBAAiB;CACxB,CAAC;AAEX;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,4EAA4E;IAC5E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,+FAA+F;IAC/F,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,uFAAuF;IACvF,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAsBD;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS,CAuBjG;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACjC;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,oDAAoD;IACpD,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;IACvC,8BAA8B;IAC9B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AA4ND;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,eAAe,EACxB,QAAQ,CAAC,EAAE,eAAe,GACzB,SAAS,YAAY,EAAE,CASzB"}