taskflow-core 0.1.8 → 0.2.0

package/dist/rates.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Model rate registry — pure token-to-USD cost estimation.
+ *
+ * ## CODEX COST GAP
+ *
+ * The `codex-runner` (packages/codex-taskflow) emits NO cost field in its usage
+ * response, so `usage.cost` stays 0 on Codex even when tokens are accurately
+ * reported. This makes `budget.maxUSD` silently non-functional for Codex-hosted
+ * flows. This module fills the gap: batch 2 of the runner layer (or a post-hoc
+ * cost fill) can call `estimateCost()` to compute USD from the known model +
+ * token counts, making Codex cost-aware without changing the runner protocol.
+ *
+ * ## Link to verify.ts
+ *
+ * `verify.ts` defines `ESTIMATED_COST_PER_PHASE = 0.001` as a crude lower-bound
+ * budget guard. `FLAT_FALLBACK_PER_TOKEN` serves the same role for unknown models
+ * — a rough-order-of-magnitude per-token default (~$1/1M tokens, consistent with
+ * $0.001/1000-tokens at verify's granularity).
+ *
+ * @module
+ */
+import type { UsageStats } from "./usage.ts";
+/**
+ * Per-model pricing in USD per 1,000,000 tokens.
+ *
+ * Rates mirror the provider's published API pricing (input, output, cached
+ * input read, cached input write). Missing fields default to zero.
+ */
+export interface ModelRate {
+    /** USD per 1,000,000 input (prompt) tokens. */
+    inputPer1M: number;
+    /** USD per 1,000,000 output (completion) tokens. */
+    outputPer1M: number;
+    /** USD per 1,000,000 cached input tokens read (if applicable). */
+    cacheReadPer1M?: number;
+    /** USD per 1,000,000 cached input tokens written (if applicable). */
+    cacheWritePer1M?: number;
+}
+/**
+ * Built-in rate table keyed by **model-family prefix** (case-sensitive lookup
+ * key — matching in `resolveRate` is case-insensitive).
+ *
+ * This is a small, illustrative, SPARSE table. Hosts can inject a richer table
+ * at runtime via the optional `table` parameter to `resolveRate`/`estimateCost`.
+ *
+ * Prices are approximate and may drift from provider publishing. For production
+ * billing, always use the provider's official cost API.
+ *
+ * ```ts
+ * // Example override from a host adapter:
+ * const myRates = { ...DEFAULT_RATES, "my-model": { inputPer1M: 1, outputPer1M: 4 } };
+ * const cost = estimateCost(usage, "my-model", myRates);
+ * ```
+ */
+export declare const DEFAULT_RATES: Record<string, ModelRate>;
+/**
+ * Flat per-token USD fallback used when no model rate can be resolved.
+ *
+ * Currently set to $1 per 1,000,000 tokens (~$0.001 per 1K tokens), consistent
+ * with `verify.ts`'s `ESTIMATED_COST_PER_PHASE = 0.001` rough-order-of-magnitude
+ * estimate. This avoids silent zero-cost for unknown models while staying in the
+ * right ballpark for most hosted LLM APIs.
+ */
+export declare const FLAT_FALLBACK_PER_TOKEN = 0.000001;
+/**
+ * Resolve a model identifier to a `ModelRate` via case-insensitive prefix match
+ * against the provided table (defaults to `DEFAULT_RATES`).
+ *
+ * Matching strategy:
+ * 1. Exact case-insensitive key match.
+ * 2. Longest prefix match (case-insensitive), e.g. "gpt-4o-2024-08-06" matches
+ *    the "gpt-4o" key.
+ * 3. Falls back to single-word prefix: "claude-sonnet-4-20241022" matches
+ *    "claude-sonnet-4" (best prefix).
+ *
+ * Returns `undefined` if no match is found. Never throws.
+ *
+ * @param model      - The model identifier to look up (e.g. "gpt-4o-2024-08-06")
+ * @param table      - Optional rate table (defaults to DEFAULT_RATES)
+ * @returns The matching ModelRate, or undefined on miss
+ */
+export declare function resolveRate(model: string, table?: Record<string, ModelRate>): ModelRate | undefined;
+/**
+ * Compute estimated USD cost from token usage.
+ *
+ * ## Cache accounting contract
+ *
+ * Hosts disagree on whether `usage.input` already includes cached tokens:
+ * - **Codex**: `input_tokens` includes `cached_input_tokens` (overlap).
+ * - **Claude / OpenCode (typical)**: `input` is non-cached; `cacheRead` is
+ *   disjoint and additional.
+ *
+ * Heuristic (never double-bill, never under-bill the common cases):
+ * - If `0 < cacheRead <= input`, treat cache as a **subset** of input
+ *   (Codex-style): bill `(input - cacheRead)` at the input rate and
+ *   `cacheRead` at the cache-read rate.
+ * - Otherwise treat input and cacheRead as **disjoint**: bill full `input`
+ *   at the input rate plus `cacheRead` at the cache-read rate.
+ *
+ * Cache-write tokens are always billed separately when a write rate exists
+ * (they are never part of `input`).
+ *
+ * Formula (known rate):
+ *   nonCachedInput = (cacheRead > 0 && cacheRead <= input)
+ *                    ? input - cacheRead : input
+ *   cost = (nonCachedInput * inputRate + output * outputRate +
+ *           cacheRead * cacheReadRate + cacheWrite * cacheWriteRate) / 1_000_000
+ *
+ * If the model cannot be resolved, falls back to
+ * `FLAT_FALLBACK_PER_TOKEN * (input + output)`. Cache tokens are *not* counted
+ * in the fallback (avoids double-count when input already includes them).
+ *
+ * Pure function — no I/O, no side effects. Never throws.
+ *
+ * @param usage  - Token counts (input, output, cacheRead, cacheWrite)
+ * @param model  - Model identifier used to resolve the rate
+ * @param table  - Optional rate table override (passed through to resolveRate)
+ * @returns Estimated cost in USD
+ */
+export declare function estimateCost(usage: UsageStats, model: string, table?: Record<string, ModelRate>): number;
+//# sourceMappingURL=rates.d.ts.map

package/dist/rates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rates.d.ts","sourceRoot":"","sources":["../src/rates.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAM7C;;;;;GAKG;AACH,MAAM,WAAW,SAAS;IACzB,+CAA+C;IAC/C,UAAU,EAAE,MAAM,CAAC;IACnB,oDAAoD;IACpD,WAAW,EAAE,MAAM,CAAC;IACpB,kEAAkE;IAClE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,qEAAqE;IACrE,eAAe,CAAC,EAAE,MAAM,CAAC;CACzB;AAMD;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAkC1C,CAAC;AAMX;;;;;;;GAOG;AACH,eAAO,MAAM,uBAAuB,WAAW,CAAC;AAMhD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,WAAW,CAC1B,KAAK,EAAE,MAAM,EACb,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,GAC/B,SAAS,GAAG,SAAS,CAsBvB;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAgB,YAAY,CAC3B,KAAK,EAAE,UAAU,EACjB,KAAK,EAAE,MAAM,EACb,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,GAC/B,MAAM,CAwBR"}

package/dist/rates.js

@@ -0,0 +1,187 @@
+/**
+ * Model rate registry — pure token-to-USD cost estimation.
+ *
+ * ## CODEX COST GAP
+ *
+ * The `codex-runner` (packages/codex-taskflow) emits NO cost field in its usage
+ * response, so `usage.cost` stays 0 on Codex even when tokens are accurately
+ * reported. This makes `budget.maxUSD` silently non-functional for Codex-hosted
+ * flows. This module fills the gap: batch 2 of the runner layer (or a post-hoc
+ * cost fill) can call `estimateCost()` to compute USD from the known model +
+ * token counts, making Codex cost-aware without changing the runner protocol.
+ *
+ * ## Link to verify.ts
+ *
+ * `verify.ts` defines `ESTIMATED_COST_PER_PHASE = 0.001` as a crude lower-bound
+ * budget guard. `FLAT_FALLBACK_PER_TOKEN` serves the same role for unknown models
+ * — a rough-order-of-magnitude per-token default (~$1/1M tokens, consistent with
+ * $0.001/1000-tokens at verify's granularity).
+ *
+ * @module
+ */
+// ---------------------------------------------------------------------------
+// Default rate table
+// ---------------------------------------------------------------------------
+/**
+ * Built-in rate table keyed by **model-family prefix** (case-sensitive lookup
+ * key — matching in `resolveRate` is case-insensitive).
+ *
+ * This is a small, illustrative, SPARSE table. Hosts can inject a richer table
+ * at runtime via the optional `table` parameter to `resolveRate`/`estimateCost`.
+ *
+ * Prices are approximate and may drift from provider publishing. For production
+ * billing, always use the provider's official cost API.
+ *
+ * ```ts
+ * // Example override from a host adapter:
+ * const myRates = { ...DEFAULT_RATES, "my-model": { inputPer1M: 1, outputPer1M: 4 } };
+ * const cost = estimateCost(usage, "my-model", myRates);
+ * ```
+ */
+export const DEFAULT_RATES = {
+    // ── OpenAI ──────────────────────────────────────────────────────────
+    /** gpt-4o family (including gpt-4o-*, gpt-4o-mini) */
+    "gpt-4o": { inputPer1M: 2.50, outputPer1M: 10.00, cacheReadPer1M: 1.25 },
+    /** gpt-4o-mini (cheap, fast) */
+    "gpt-4o-mini": { inputPer1M: 0.15, outputPer1M: 0.60, cacheReadPer1M: 0.075 },
+    /** o3-mini reasoning model */
+    "o3-mini": { inputPer1M: 1.10, outputPer1M: 4.40, cacheReadPer1M: 0.55 },
+    /** o1 reasoning model */
+    o1: { inputPer1M: 15.00, outputPer1M: 60.00, cacheReadPer1M: 7.50 },
+    // ── Anthropic ───────────────────────────────────────────────────────
+    /** claude-sonnet-4 (and sonnet-4-*) */
+    "claude-sonnet-4": { inputPer1M: 3.00, outputPer1M: 15.00, cacheReadPer1M: 0.30, cacheWritePer1M: 3.75 },
+    /** claude-haiku-3.5 (and haiku-3.5-*) */
+    "claude-haiku-3.5": { inputPer1M: 0.80, outputPer1M: 4.00, cacheReadPer1M: 0.08, cacheWritePer1M: 1.00 },
+    /** claude-opus-4 (and opus-4-*) */
+    "claude-opus-4": { inputPer1M: 15.00, outputPer1M: 75.00, cacheReadPer1M: 1.50, cacheWritePer1M: 18.75 },
+    // ── DeepSeek ────────────────────────────────────────────────────────
+    /** deepseek-chat (V3) */
+    "deepseek-chat": { inputPer1M: 0.27, outputPer1M: 1.10, cacheReadPer1M: 0.07 },
+    /** deepseek-reasoner (R1) */
+    "deepseek-reasoner": { inputPer1M: 0.55, outputPer1M: 2.19, cacheReadPer1M: 0.14 },
+    // ── Google Gemini ───────────────────────────────────────────────────
+    /** gemini-2.5-flash-* */
+    "gemini-2.5-flash": { inputPer1M: 0.15, outputPer1M: 0.60, cacheReadPer1M: 0.075 },
+    /** gemini-2.5-pro-* */
+    "gemini-2.5-pro": { inputPer1M: 1.25, outputPer1M: 10.00, cacheReadPer1M: 0.3125 },
+    // ── Meta ────────────────────────────────────────────────────────────
+    /** llama-3.x (generic — actual pricing depends on host) */
+    "llama-3": { inputPer1M: 0.25, outputPer1M: 0.25 },
+};
+// ---------------------------------------------------------------------------
+// Fallback
+// ---------------------------------------------------------------------------
+/**
+ * Flat per-token USD fallback used when no model rate can be resolved.
+ *
+ * Currently set to $1 per 1,000,000 tokens (~$0.001 per 1K tokens), consistent
+ * with `verify.ts`'s `ESTIMATED_COST_PER_PHASE = 0.001` rough-order-of-magnitude
+ * estimate. This avoids silent zero-cost for unknown models while staying in the
+ * right ballpark for most hosted LLM APIs.
+ */
+export const FLAT_FALLBACK_PER_TOKEN = 0.000001; // $1/1M tokens
+// ---------------------------------------------------------------------------
+// Resolution
+// ---------------------------------------------------------------------------
+/**
+ * Resolve a model identifier to a `ModelRate` via case-insensitive prefix match
+ * against the provided table (defaults to `DEFAULT_RATES`).
+ *
+ * Matching strategy:
+ * 1. Exact case-insensitive key match.
+ * 2. Longest prefix match (case-insensitive), e.g. "gpt-4o-2024-08-06" matches
+ *    the "gpt-4o" key.
+ * 3. Falls back to single-word prefix: "claude-sonnet-4-20241022" matches
+ *    "claude-sonnet-4" (best prefix).
+ *
+ * Returns `undefined` if no match is found. Never throws.
+ *
+ * @param model      - The model identifier to look up (e.g. "gpt-4o-2024-08-06")
+ * @param table      - Optional rate table (defaults to DEFAULT_RATES)
+ * @returns The matching ModelRate, or undefined on miss
+ */
+export function resolveRate(model, table) {
+    if (!model)
+        return undefined;
+    const tbl = table ?? DEFAULT_RATES;
+    const lowerModel = model.toLowerCase();
+    // 1. Exact case-insensitive match
+    const exact = Object.keys(tbl).find((k) => k.toLowerCase() === lowerModel);
+    if (exact)
+        return tbl[exact];
+    // 2. Longest prefix match — iterate to find the key that is a prefix of the
+    //    model (case-insensitive) with the greatest length.
+    let best;
+    for (const key of Object.keys(tbl)) {
+        const lowerKey = key.toLowerCase();
+        if (lowerModel.startsWith(lowerKey) && lowerKey.length > (best?.length ?? 0)) {
+            best = { key, length: lowerKey.length };
+        }
+    }
+    if (best)
+        return tbl[best.key];
+    return undefined;
+}
+// ---------------------------------------------------------------------------
+// Cost estimation
+// ---------------------------------------------------------------------------
+/**
+ * Compute estimated USD cost from token usage.
+ *
+ * ## Cache accounting contract
+ *
+ * Hosts disagree on whether `usage.input` already includes cached tokens:
+ * - **Codex**: `input_tokens` includes `cached_input_tokens` (overlap).
+ * - **Claude / OpenCode (typical)**: `input` is non-cached; `cacheRead` is
+ *   disjoint and additional.
+ *
+ * Heuristic (never double-bill, never under-bill the common cases):
+ * - If `0 < cacheRead <= input`, treat cache as a **subset** of input
+ *   (Codex-style): bill `(input - cacheRead)` at the input rate and
+ *   `cacheRead` at the cache-read rate.
+ * - Otherwise treat input and cacheRead as **disjoint**: bill full `input`
+ *   at the input rate plus `cacheRead` at the cache-read rate.
+ *
+ * Cache-write tokens are always billed separately when a write rate exists
+ * (they are never part of `input`).
+ *
+ * Formula (known rate):
+ *   nonCachedInput = (cacheRead > 0 && cacheRead <= input)
+ *                    ? input - cacheRead : input
+ *   cost = (nonCachedInput * inputRate + output * outputRate +
+ *           cacheRead * cacheReadRate + cacheWrite * cacheWriteRate) / 1_000_000
+ *
+ * If the model cannot be resolved, falls back to
+ * `FLAT_FALLBACK_PER_TOKEN * (input + output)`. Cache tokens are *not* counted
+ * in the fallback (avoids double-count when input already includes them).
+ *
+ * Pure function — no I/O, no side effects. Never throws.
+ *
+ * @param usage  - Token counts (input, output, cacheRead, cacheWrite)
+ * @param model  - Model identifier used to resolve the rate
+ * @param table  - Optional rate table override (passed through to resolveRate)
+ * @returns Estimated cost in USD
+ */
+export function estimateCost(usage, model, table) {
+    const rate = resolveRate(model, table);
+    if (!rate) {
+        return FLAT_FALLBACK_PER_TOKEN * (usage.input + usage.output);
+    }
+    // Overlap heuristic: when cacheRead is a positive subset of input, peel it
+    // out so it is not billed at the full input rate (Codex-style hosts).
+    const nonCachedInput = usage.cacheRead > 0 && usage.cacheRead <= usage.input
+        ? usage.input - usage.cacheRead
+        : usage.input;
+    const inputCost = (nonCachedInput / 1_000_000) * rate.inputPer1M;
+    const outputCost = (usage.output / 1_000_000) * rate.outputPer1M;
+    let cacheCost = 0;
+    if (rate.cacheReadPer1M !== undefined && usage.cacheRead > 0) {
+        cacheCost += (usage.cacheRead / 1_000_000) * rate.cacheReadPer1M;
+    }
+    if (rate.cacheWritePer1M !== undefined && usage.cacheWrite > 0) {
+        cacheCost += (usage.cacheWrite / 1_000_000) * rate.cacheWritePer1M;
+    }
+    return inputCost + outputCost + cacheCost;
+}
+//# sourceMappingURL=rates.js.map

package/dist/rates.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rates.js","sourceRoot":"","sources":["../src/rates.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAyBH,8EAA8E;AAC9E,qBAAqB;AACrB,8EAA8E;AAE9E;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,aAAa,GAA8B;IACvD,uEAAuE;IACvE,sDAAsD;IACtD,QAAQ,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,cAAc,EAAE,IAAI,EAAE;IACxE,gCAAgC;IAChC,aAAa,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,cAAc,EAAE,KAAK,EAAE;IAC7E,8BAA8B;IAC9B,SAAS,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE;IACxE,yBAAyB;IACzB,EAAE,EAAE,EAAE,UAAU,EAAE,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,cAAc,EAAE,IAAI,EAAE;IAEnE,uEAAuE;IACvE,uCAAuC;IACvC,iBAAiB,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,cAAc,EAAE,IAAI,EAAE,eAAe,EAAE,IAAI,EAAE;IACxG,yCAAyC;IACzC,kBAAkB,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,eAAe,EAAE,IAAI,EAAE;IACxG,mCAAmC;IACnC,eAAe,EAAE,EAAE,UAAU,EAAE,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,cAAc,EAAE,IAAI,EAAE,eAAe,EAAE,KAAK,EAAE;IAExG,uEAAuE;IACvE,yBAAyB;IACzB,eAAe,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE;IAC9E,6BAA6B;IAC7B,mBAAmB,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE;IAElF,uEAAuE;IACvE,yBAAyB;IACzB,kBAAkB,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,cAAc,EAAE,KAAK,EAAE;IAClF,uBAAuB;IACvB,gBAAgB,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,cAAc,EAAE,MAAM,EAAE;IAElF,uEAAuE;IACvE,2DAA2D;IAC3D,SAAS,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE;CACzC,CAAC;AAEX,8EAA8E;AAC9E,WAAW;AACX,8EAA8E;AAE9E;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,QAAQ,CAAC,CAAC,eAAe;AAEhE,8EAA8E;AAC9E,aAAa;AACb,8EAA8E;AAE9E;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,WAAW,CAC1B,KAAa,EACb,KAAiC;IAEjC,IAAI,CAAC,KAAK;QAAE,OAAO,SAAS,CAAC;IAE7B,MAAM,GAAG,GAAG,KAAK,IAAI,aAAa,CAAC;IACnC,MAAM,UAAU,GAAG,KAAK,CAAC,WAAW,EAAE,CAAC;IAEvC,kCAAkC;IAClC,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,KAAK,UAAU,CAAC,CAAC;IAC3E,IAAI,KAAK;QAAE,OAAO,GAAG,CAAC,KAAK,CAAC,CAAC;IAE7B,4EAA4E;IAC5E,wDAAwD;IACxD,IAAI,IAAiD,CAAC;IACtD,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QACpC,MAAM,QAAQ,GAAG,GAAG,CAAC,WAAW,EAAE,CAAC;QACnC,IAAI,UAAU,CAAC,UAAU,CAAC,QAAQ,CAAC,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,MAAM,IAAI,CAAC,CAAC,EAAE,CAAC;YAC9E,IAAI,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC;QACzC,CAAC;IACF,CAAC;IACD,IAAI,IAAI;QAAE,OAAO,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAE/B,OAAO,SAAS,CAAC;AAClB,CAAC;AAED,8EAA8E;AAC9E,kBAAkB;AAClB,8EAA8E;AAE9E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,MAAM,UAAU,YAAY,CAC3B,KAAiB,EACjB,KAAa,EACb,KAAiC;IAEjC,MAAM,IAAI,GAAG,WAAW,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;IACvC,IAAI,CAAC,IAAI,EAAE,CAAC;QACX,OAAO,uBAAuB,GAAG,CAAC,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC;IAC/D,CAAC;IAED,2EAA2E;IAC3E,sEAAsE;IACtE,MAAM,cAAc,GACnB,KAAK,CAAC,SAAS,GAAG,CAAC,IAAI,KAAK,CAAC,SAAS,IAAI,KAAK,CAAC,KAAK;QACpD,CAAC,CAAC,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC,SAAS;QAC/B,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC;IAEhB,MAAM,SAAS,GAAG,CAAC,cAAc,GAAG,SAAS,CAAC,GAAG,IAAI,CAAC,UAAU,CAAC;IACjE,MAAM,UAAU,GAAG,CAAC,KAAK,CAAC,MAAM,GAAG,SAAS,CAAC,GAAG,IAAI,CAAC,WAAW,CAAC;IACjE,IAAI,SAAS,GAAG,CAAC,CAAC;IAClB,IAAI,IAAI,CAAC,cAAc,KAAK,SAAS,IAAI,KAAK,CAAC,SAAS,GAAG,CAAC,EAAE,CAAC;QAC9D,SAAS,IAAI,CAAC,KAAK,CAAC,SAAS,GAAG,SAAS,CAAC,GAAG,IAAI,CAAC,cAAc,CAAC;IAClE,CAAC;IACD,IAAI,IAAI,CAAC,eAAe,KAAK,SAAS,IAAI,KAAK,CAAC,UAAU,GAAG,CAAC,EAAE,CAAC;QAChE,SAAS,IAAI,CAAC,KAAK,CAAC,UAAU,GAAG,SAAS,CAAC,GAAG,IAAI,CAAC,eAAe,CAAC;IACpE,CAAC;IAED,OAAO,SAAS,GAAG,UAAU,GAAG,SAAS,CAAC;AAC3C,CAAC"}

package/dist/replay.d.ts

@@ -1,75 +1,68 @@
 /**
- * Deterministic replay — **type stub + design contract (0.1.7)**.
+ * Deterministic replay — re-fold a recorded event log under alternate **decision
+ * knobs** without calling the model (RFC §7, S3).
  *
- * Replay re-evaluates a recorded run against changed **decision knobs** (gate
- * thresholds, budget caps, model route) by reading the event trace
- * (`trace.ts`) and re-applying deterministic decision logic — **never calling
- * `runTask`**. Zero tokens, offline. Because the DAG and its verdicts are data,
- * you can re-adjudicate them against recorded evidence.
+ * **Import graph guard (structural):** this module imports only pure packages
+ * (`exec/events`, `exec/fold`, `deterministic`, `scorers`). It must NEVER import
+ * `runtime.ts` or `exec/driver` / `exec/step` (those drag process-spawning).
  *
- * **0.1.7 ships the trace foundation + this type only.** The pure `replayRun()`
- * function and the `replay` action land in 0.2.0. The `ReplayDecision` type is
- * defined now so the trace schema and the diff-report contract are fixed before
- * any events are emitted — avoiding a breaking migration later.
- *
- * The 0.2.0 `replayRun()` will import ONLY from pure modules:
- *   `trace.ts` (read), `schema.ts` (topo sort/desugar),
- *   `interpolate.ts` (condition re-eval), `deterministic.ts` (parseGateVerdict,
- *   overBudget), `scorers.ts` (pure scorer re-run).
- * It must NOT import `runtime.ts` (which drags in the process-spawning runner)
- * — the "replay never spends a token" invariant is enforced structurally by the
- * import graph.
+ * 0.1.7 shipped types only. 0.2.0 implements {@link replayRun}.
  */
+import type { Event } from "./exec/events.ts";
+import { type FoldedRun } from "./exec/fold.ts";
+import { type UsageStats } from "./usage.ts";
 /**
  * Per-phase outcome of a replay. Distinct from `RecomputeDecision` (which
- * describes a *live* recompute): only `"reused"` overlaps. Overloading
- * `RecomputeDecision.outcome` with replay-specific values would be a semantic
- * lie — replay and recompute are different operations (recorded vs. live).
+ * describes a *live* recompute): only `"reused"` overlaps.
  */
 export interface ReplayDecision {
     readonly phaseId: string;
-    readonly outcome: 
-    /** Recorded output valid → reused verbatim (zero tokens). */
-    "reused"
-    /** A gate verdict flipped under the new threshold/scorers. */
-     | "verdict-flipped"
-    /** The phase would now BLOCK the flow (e.g. gate under a stricter threshold). */
-     | "would-block"
-    /** The phase would be skipped by a tighter budget cap. */
-     | "would-exceed-budget"
-    /** Replay cannot decide — a fresh model call is required. Conservative. */
-     | "needs-live-rerun"
-    /** A `when` guard now skips a phase that previously ran (or vice-versa). */
-     | "would-skip"
-    /** A score threshold changed (verdict may or may not have flipped). */
-     | "threshold-changed"
-    /** The phase failed in the recorded run; replay does not retry. */
-     | "failed";
+    readonly outcome: "reused" | "verdict-flipped" | "would-block" | "would-exceed-budget" | "needs-live-rerun" | "would-skip" | "threshold-changed" | "failed";
     readonly reason: string;
-    /** The phase's outcome in the recorded run. */
     readonly priorOutcome?: string;
-    /** The phase's outcome under the replayed knobs. */
     readonly replayedOutcome?: string;
-    /** Upstream phases whose change caused this outcome, when applicable. */
     readonly causedBy?: readonly string[];
 }
 /**
  * Knobs a replay may override on a *copy* of the recorded definition (never the
- * stored run). v1 (0.2.0) supports the deterministic subset; anything that
- * would require re-generation (a changed task prompt) routes to
- * `needs-live-rerun`.
+ * stored run).
  */
 export interface ReplayOverrides {
-    /** `budget.maxUSD` / `budget.maxTokens` — re-tally recorded usage. */
     budgetMaxUSD?: number;
     budgetMaxTokens?: number;
-    /** `phases.<id>.score.threshold` — re-run scorers against recorded target. */
+    /** `phases.<id>.score.threshold` — re-judge recorded gate-score events. */
     thresholds?: Record<string, number>;
-    /** `phases.<id>.model` — report a cost delta only (cannot replay quality). */
+    /** `phases.<id>.model` — cost delta only (needs rates; otherwise needs-live-rerun). */
     models?: Record<string, string>;
-    /** `args.*` — only affects interpolation; changed-text phases → needs-live-rerun. */
+    /** `args.*` — text-changing args → needs-live-rerun for affected phases. */
     args?: Record<string, unknown>;
 }
-/** Sentinel: this module exports types only in 0.1.7. Implemented in 0.2.0. */
-export declare const REPLAY_NOT_YET_IMPLEMENTED = "replayRun() lands in 0.2.0; 0.1.7 ships the trace foundation + this type contract.";
+/** Result of {@link replayRun}. */
+export interface ReplayReport {
+    readonly decisions: ReplayDecision[];
+    /** Fold under recorded knobs (baseline). */
+    readonly baseline: FoldedRun;
+    /** Fold after applying overrides (may equal baseline when no knobs change). */
+    readonly replayed: FoldedRun;
+    /** True if any phase needs a live model call. */
+    readonly needsLiveRerun: boolean;
+    /** Aggregate recorded usage (for budget re-check). */
+    readonly totalUsage: UsageStats;
+}
+/**
+ * Re-evaluate a recorded event log under optional decision overrides.
+ *
+ * - **No overrides** → every completed phase is `"reused"` (consistency oracle).
+ * - **thresholds[phaseId]** → re-compare recorded `gate-score.combined` to the
+ *   new threshold; emit `verdict-flipped` / `would-block` / `threshold-changed`.
+ * - **budgetMax*** → re-tally recorded usage; phases that would not have run
+ *   under a tighter cap → `would-exceed-budget`.
+ * - **models / args** → currently `needs-live-rerun` for any phase (cannot
+ *   re-judge quality offline without more instrumentation).
+ *
+ * Never calls a model. Never throws.
+ */
+export declare function replayRun(events: readonly Event[], overrides?: ReplayOverrides): ReplayReport;
+/** @deprecated kept for 0.1.7 callers that checked the sentinel string */
+export declare const REPLAY_NOT_YET_IMPLEMENTED = "replayRun() is implemented in 0.2.0; this sentinel remains for back-compat string checks.";
 //# sourceMappingURL=replay.d.ts.map

package/dist/replay.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"replay.d.ts","sourceRoot":"","sources":["../src/replay.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO;IACf,6DAA6D;IAC3D,QAAQ;IACV,8DAA8D;OAC5D,iBAAiB;IACnB,iFAAiF;OAC/E,aAAa;IACf,0DAA0D;OACxD,qBAAqB;IACvB,2EAA2E;OACzE,kBAAkB;IACpB,4EAA4E;OAC1E,YAAY;IACd,uEAAuE;OACrE,mBAAmB;IACrB,mEAAmE;OACjE,QAAQ,CAAC;IACZ,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,+CAA+C;IAC/C,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,oDAAoD;IACpD,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,yEAAyE;IACzE,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC/B,sEAAsE;IACtE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,8EAA8E;IAC9E,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,8EAA8E;IAC9E,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,qFAAqF;IACrF,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED,+EAA+E;AAC/E,eAAO,MAAM,0BAA0B,uFAC8C,CAAC"}
+{"version":3,"file":"replay.d.ts","sourceRoot":"","sources":["../src/replay.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,KAAK,EAAiB,MAAM,kBAAkB,CAAC;AAC7D,OAAO,EAAc,KAAK,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC5D,OAAO,EAAc,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAEzD;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EACb,QAAQ,GACR,iBAAiB,GACjB,aAAa,GACb,qBAAqB,GACrB,kBAAkB,GAClB,YAAY,GACZ,mBAAmB,GACnB,QAAQ,CAAC;IACZ,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC/B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,2EAA2E;IAC3E,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,uFAAuF;IACvF,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,4EAA4E;IAC5E,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED,mCAAmC;AACnC,MAAM,WAAW,YAAY;IAC5B,QAAQ,CAAC,SAAS,EAAE,cAAc,EAAE,CAAC;IACrC,4CAA4C;IAC5C,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC;IAC7B,+EAA+E;IAC/E,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC;IAC7B,iDAAiD;IACjD,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,sDAAsD;IACtD,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;CAChC;AA6FD;;;;;;;;;;;;GAYG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,SAAS,KAAK,EAAE,EAAE,SAAS,GAAE,eAAoB,GAAG,YAAY,CAigBjG;AAED,0EAA0E;AAC1E,eAAO,MAAM,0BAA0B,8FACqD,CAAC"}