patchwork-os 0.2.0-beta.10.canary.99 → 0.2.0-beta.11

package/dist/recipes/runBudget.d.ts

@@ -1,30 +1,29 @@
 /**
- * Per-recipe token budget — PR2b.
+ * Per-recipe budget — PR2b (tokens) + cost-routing Phase 3 (USD).
  *
- * Built on PR2a's `AgentResult.usage` plumbing. The runner constructs
- * one `RunBudget` per recipe execution; agent steps consult it before
- * dispatch (admission) and reconcile actual consumption after the call
- * returns. On breach the run halts at the *next* admission check (we
- * never retroactively fail a step that succeeded — the user's tokens
- * are already spent, halting after-the-fact would just confuse the
- * audit trail).
+ * Built on PR2a's `AgentResult.usage` plumbing. The runner constructs one
+ * `RunBudget` per recipe execution; agent steps consult it before dispatch
+ * (admission) and reconcile actual consumption after the call returns. On
+ * breach the run halts at the *next* admission check (we never retroactively
+ * fail a step that succeeded — the user's tokens/dollars are already spent;
+ * halting after-the-fact would just confuse the audit trail).
  *
- * Subscription drivers (Claude CLI, provider subprocess CLIs) don't
- * surface per-call token counts. `RunBudget` tracks which drivers were
- * unmeasured and exposes a deduped warnings list — fail-open with a
- * single notice per driver per run, never block.
+ * Two independent caps, either or both:
+ *   - `tokensMax` — cumulative input + output tokens.
+ *   - `usdMax`    — cumulative USD, priced from token usage via the Phase 2
+ *                   price table (`costUsd`).
  *
- * Scope (PR2b only):
- *   - cumulative token enforcement (input + output)
- *   - halt-on-breach OR warn-on-breach via `BudgetPolicy.onBreach`
- *   - subscription-driver fail-open with warning
- *
- * Out of scope (future):
- *   - per-step caps (extend `BudgetPolicy` or add `AgentStep.tokensMax`)
- *   - `usdMax` (needs a price table; subscription drivers complicate)
- *   - `wallClockMs` (orthogonal to tokens, separate accounting)
+ * Subscription drivers (Claude CLI, provider subprocess CLIs) don't surface
+ * per-call token counts, and a model with no price-table entry can't be
+ * costed. Both cases FAIL OPEN: `RunBudget` records a deduped one-time
+ * warning and never blocks. So a USD cap enforces for *measured + priced*
+ * (API) drivers and is a no-op-with-notice for everything else — never a
+ * silent or a surprise halt on the token-blind default driver. (The opt-in
+ * estimate-the-unmeasured path is a planned follow-up; absent it, unmeasured
+ * = fail-open, which is the conservative default the design calls for.)
  */
-import type { AgentUsage } from "./agentExecutor.js";
+import { type AgentUsage } from "./agentExecutor.js";
+import { type PriceTable } from "./pricing/priceTable.js";
 import type { BudgetPolicy } from "./schema.js";
 export interface BudgetAdmission {
     /** True = step may proceed. False = budget exhausted. */
@@ -36,35 +35,86 @@ export interface BudgetTotals {
     inputTokens: number;
     outputTokens: number;
     total: number;
-    /** Remaining tokens before breach. Undefined when no limit is set. */
+    /** Remaining tokens before breach. Undefined when no token limit is set. */
     remaining?: number;
-    /** True once total >= tokensMax. */
+    /** Cumulative measured USD. Undefined when no USD limit is set. */
+    usd?: number;
+    /** Remaining USD before breach. Undefined when no USD limit is set. */
+    usdRemaining?: number;
+    /**
+     * Notional list-price USD estimated for unmeasured (subscription) calls when
+     * `estimateUnmeasured` is on. A label ONLY — never counted toward `usd` or
+     * `usdMax`, never halts. Present only when > 0.
+     */
+    usdEstimated?: number;
+    /** True once total tokens >= tokensMax (false when no token limit). */
     breached: boolean;
+    /** True once measured usd >= usdMax (false when no USD limit). */
+    usdBreached: boolean;
     /** Whether the configured policy halts on breach (vs warn). */
     haltOnBreach: boolean;
 }
 export declare class RunBudget {
     private readonly tokensMax?;
+    private readonly usdMax?;
     private readonly haltOnBreach;
+    private readonly estimateUnmeasured;
+    private readonly priceTable?;
     private inputTokens;
     private outputTokens;
-    /** Drivers that returned `usage: undefined` during this run, deduped. */
-    private readonly unmeasuredDrivers;
+    private usdSpent;
+    /** Notional list-price USD for unmeasured calls (warn-only; never enforced). */
+    private usdEstimated;
+    /** Dedup keys for one-time warnings (unmeasured driver, breach, etc.). */
+    private readonly warnedKeys;
     /** Free-form warnings surfaced via the run log. */
     private readonly warningList;
-    constructor(policy?: BudgetPolicy);
+    /**
+     * @param policy   recipe budget block.
+     * @param priceTable  optional injected table (tests); otherwise loaded once
+     *                    here when a USD cap is set (file/env override aware).
+     */
+    constructor(policy?: BudgetPolicy, priceTable?: PriceTable);
+    /** True when neither cap is configured — reconcile/admit are no-ops. */
+    private get hasBudget();
     /** Cheap admission check before dispatching an agent step. */
     admit(): BudgetAdmission;
     /**
-     * Record the actual usage reported by an agent call. `usage` may be
-     * undefined when the driver doesn't surface token counts — we record
-     * the driver name once per run and continue (fail-open).
+     * Record the actual usage reported by an agent call. `usage` is undefined
+     * when the driver doesn't surface token counts — record the driver once and
+     * continue (fail-open). `model` is the resolved model (from `servedBy`) used
+     * to price USD; an unpriced model fails open with a one-time notice.
      */
-    reconcile(driver: string, usage: AgentUsage | undefined): void;
+    reconcile(driver: string, usage: AgentUsage | undefined, model?: string, estimate?: {
+        inputChars: number;
+        outputChars: number;
+    }): void;
     /** Snapshot of current totals + breach state. */
     totals(): BudgetTotals;
     /** Warnings collected so the runner can surface them in the run log. */
     warnings(): string[];
+    /**
+     * Run-completion warnings: the live `warnings()` plus a one-line ≈$ summary
+     * of the notional cost estimated for unmeasured calls (only when
+     * `estimateUnmeasured` produced one). Use at run end; `warnings()` is the
+     * live per-driver list without the (end-of-run-only) summary.
+     */
+    finalWarnings(): string[];
+    /**
+     * USD remaining before the cap, or undefined when no USD cap is set.
+     * Cost-aware routing (Phase 4) uses this to decide when to downshift.
+     */
+    remainingUsd(): number | undefined;
+    /**
+     * Pre-dispatch USD estimate for a prospective (driver, model) call, or
+     * undefined when it would NOT be USD-enforced: no USD cap, a non-billable
+     * driver (local / subscription), or an unpriced model. Mirrors exactly the
+     * enforcement rule in `reconcile`, so a candidate the router treats as
+     * "free" is precisely one `reconcile` would not charge.
+     */
+    quoteUsd(driver: string | undefined, model: string | undefined, inputTokens: number, outputTokens: number): number | undefined;
+    private pushOnce;
     private totalTokens;
-    private breached;
+    private tokenBreached;
+    private usdMaxBreached;
 }

package/dist/recipes/runBudget.js

@@ -1,83 +1,149 @@
 /**
- * Per-recipe token budget — PR2b.
+ * Per-recipe budget — PR2b (tokens) + cost-routing Phase 3 (USD).
  *
- * Built on PR2a's `AgentResult.usage` plumbing. The runner constructs
- * one `RunBudget` per recipe execution; agent steps consult it before
- * dispatch (admission) and reconcile actual consumption after the call
- * returns. On breach the run halts at the *next* admission check (we
- * never retroactively fail a step that succeeded — the user's tokens
- * are already spent, halting after-the-fact would just confuse the
- * audit trail).
+ * Built on PR2a's `AgentResult.usage` plumbing. The runner constructs one
+ * `RunBudget` per recipe execution; agent steps consult it before dispatch
+ * (admission) and reconcile actual consumption after the call returns. On
+ * breach the run halts at the *next* admission check (we never retroactively
+ * fail a step that succeeded — the user's tokens/dollars are already spent;
+ * halting after-the-fact would just confuse the audit trail).
  *
- * Subscription drivers (Claude CLI, provider subprocess CLIs) don't
- * surface per-call token counts. `RunBudget` tracks which drivers were
- * unmeasured and exposes a deduped warnings list — fail-open with a
- * single notice per driver per run, never block.
+ * Two independent caps, either or both:
+ *   - `tokensMax` — cumulative input + output tokens.
+ *   - `usdMax`    — cumulative USD, priced from token usage via the Phase 2
+ *                   price table (`costUsd`).
  *
- * Scope (PR2b only):
- *   - cumulative token enforcement (input + output)
- *   - halt-on-breach OR warn-on-breach via `BudgetPolicy.onBreach`
- *   - subscription-driver fail-open with warning
- *
- * Out of scope (future):
- *   - per-step caps (extend `BudgetPolicy` or add `AgentStep.tokensMax`)
- *   - `usdMax` (needs a price table; subscription drivers complicate)
- *   - `wallClockMs` (orthogonal to tokens, separate accounting)
+ * Subscription drivers (Claude CLI, provider subprocess CLIs) don't surface
+ * per-call token counts, and a model with no price-table entry can't be
+ * costed. Both cases FAIL OPEN: `RunBudget` records a deduped one-time
+ * warning and never blocks. So a USD cap enforces for *measured + priced*
+ * (API) drivers and is a no-op-with-notice for everything else — never a
+ * silent or a surprise halt on the token-blind default driver. (The opt-in
+ * estimate-the-unmeasured path is a planned follow-up; absent it, unmeasured
+ * = fail-open, which is the conservative default the design calls for.)
+ */
+import { DEFAULT_MODEL } from "./agentExecutor.js";
+import { costUsd, loadPriceTable, } from "./pricing/priceTable.js";
+/**
+ * Drivers that incur real, metered, per-token API billing — the ONLY ones a
+ * USD cap is enforced against. Includes the metered Gemini API driver
+ * (stamped "gemini"); the subscription/CLI subprocess drivers report no usage
+ * and never reach the pricing path; `local`
+ * (self-hosted Ollama / LM Studio) DOES report usage but costs no real money,
+ * so it must not be priced at notional API rates and halted on spend that
+ * never happened. Anything not in this set fails open with a one-time notice.
  */
+const BILLABLE_DRIVERS = new Set(["anthropic", "openai", "grok", "gemini"]);
+/** Rough chars-per-token used for the opt-in unmeasured-driver USD estimate. */
+const ESTIMATE_CHARS_PER_TOKEN = 4;
 export class RunBudget {
     tokensMax;
+    usdMax;
     haltOnBreach;
+    estimateUnmeasured;
+    priceTable;
     inputTokens = 0;
     outputTokens = 0;
-    /** Drivers that returned `usage: undefined` during this run, deduped. */
-    unmeasuredDrivers = new Set();
+    usdSpent = 0;
+    /** Notional list-price USD for unmeasured calls (warn-only; never enforced). */
+    usdEstimated = 0;
+    /** Dedup keys for one-time warnings (unmeasured driver, breach, etc.). */
+    warnedKeys = new Set();
     /** Free-form warnings surfaced via the run log. */
     warningList = [];
-    constructor(policy) {
+    /**
+     * @param policy   recipe budget block.
+     * @param priceTable  optional injected table (tests); otherwise loaded once
+     *                    here when a USD cap is set (file/env override aware).
+     */
+    constructor(policy, priceTable) {
         this.tokensMax = policy?.tokensMax;
+        this.usdMax = policy?.usdMax;
         this.haltOnBreach = (policy?.onBreach ?? "halt") === "halt";
+        this.estimateUnmeasured = policy?.estimateUnmeasured ?? false;
+        if (this.usdMax !== undefined) {
+            this.priceTable = priceTable ?? loadPriceTable();
+        }
+    }
+    /** True when neither cap is configured — reconcile/admit are no-ops. */
+    get hasBudget() {
+        return this.tokensMax !== undefined || this.usdMax !== undefined;
     }
     /** Cheap admission check before dispatching an agent step. */
     admit() {
-        if (this.tokensMax === undefined)
+        // warn-mode never blocks; the breach warning was emitted at reconcile.
+        if (!this.haltOnBreach)
             return { admitted: true };
-        if (this.breached()) {
-            if (!this.haltOnBreach) {
-                // warn-mode: never block, just keep going. The warning was
-                // already emitted on the post-call reconcile that breached.
-                return { admitted: true };
-            }
+        if (this.tokenBreached()) {
             return {
                 admitted: false,
-                reason: `Run exceeded its token budget — budget_exceeded: total=${this.totalTokens()} > tokensMax=${this.tokensMax}.`,
+                reason: `Run exceeded its token budget — budget_exceeded: total=${this.totalTokens()} >= tokensMax=${this.tokensMax}.`,
+            };
+        }
+        if (this.usdMaxBreached()) {
+            return {
+                admitted: false,
+                reason: `Run exceeded its USD budget — budget_exceeded: usd=$${this.usdSpent.toFixed(4)} >= usdMax=$${this.usdMax}.`,
             };
         }
         return { admitted: true };
     }
     /**
-     * Record the actual usage reported by an agent call. `usage` may be
-     * undefined when the driver doesn't surface token counts — we record
-     * the driver name once per run and continue (fail-open).
+     * Record the actual usage reported by an agent call. `usage` is undefined
+     * when the driver doesn't surface token counts — record the driver once and
+     * continue (fail-open). `model` is the resolved model (from `servedBy`) used
+     * to price USD; an unpriced model fails open with a one-time notice.
      */
-    reconcile(driver, usage) {
-        if (this.tokensMax === undefined)
+    reconcile(driver, usage, model, estimate) {
+        if (!this.hasBudget)
             return;
         if (!usage) {
-            if (!this.unmeasuredDrivers.has(driver)) {
-                this.unmeasuredDrivers.add(driver);
-                this.warningList.push(`Driver "${driver}" does not report token usage — budget enforcement skipped for its calls. Set recipe.budget.onBreach="warn" or move to an API driver to fix.`);
+            if (this.usdMax !== undefined && this.estimateUnmeasured && estimate) {
+                // OPT-IN notional estimate for an unmeasured (subscription) driver.
+                // WARN-ONLY: accumulates into usdEstimated, NEVER usdSpent, and never
+                // affects admit() — a flat-rate subscription call is not real money out,
+                // and halting on a ~4-chars/token guess would be wrong.
+                const estModel = model ?? DEFAULT_MODEL;
+                const estCost = costUsd(estModel, {
+                    inputTokens: Math.ceil(estimate.inputChars / ESTIMATE_CHARS_PER_TOKEN),
+                    outputTokens: Math.ceil(estimate.outputChars / ESTIMATE_CHARS_PER_TOKEN),
+                }, this.priceTable);
+                if (estCost !== undefined && Number.isFinite(estCost)) {
+                    this.usdEstimated += estCost;
+                    this.pushOnce(`estimate:${driver}`, `Driver "${driver}" reports no usage — estimating notional list-price cost (≈, never enforced; see usdEstimated).`);
+                    return;
+                }
             }
+            this.pushOnce(`unmeasured:${driver}`, `Driver "${driver}" does not report token usage — budget enforcement skipped for its calls. Set recipe.budget.onBreach="warn" or move to an API driver to fix.`);
             return;
         }
         this.inputTokens += usage.inputTokens;
         this.outputTokens += usage.outputTokens;
-        if (this.breached() && !this.haltOnBreach) {
-            // warn-mode: emit a single in-band warning the first time we
-            // cross the line. Subsequent steps continue running.
-            const breachKey = "warn-breach-emitted";
-            if (!this.unmeasuredDrivers.has(breachKey)) {
-                this.unmeasuredDrivers.add(breachKey);
-                this.warningList.push(`Token budget exceeded (total=${this.totalTokens()}, tokensMax=${this.tokensMax}) but onBreach="warn" — continuing.`);
+        if (this.usdMax !== undefined) {
+            if (!BILLABLE_DRIVERS.has(driver)) {
+                // Not a metered-API driver (local / subscription) — a USD cap here
+                // would be notional, not real money out. Fail open with a notice.
+                this.pushOnce(`notbilled:${driver}`, `Driver "${driver}" does not incur metered API cost — usdMax is not enforced for its calls.`);
+            }
+            else {
+                const cost = costUsd(model ?? "", usage, this.priceTable);
+                // `cost === undefined` (unpriced model) OR a non-finite cost (defends
+                // against a malformed price entry) → fail open, never poison usdSpent.
+                if (cost === undefined || !Number.isFinite(cost)) {
+                    this.pushOnce(`unpriced:${model ?? "(no model)"}`, `Model "${model ?? "(unspecified)"}" is not in the price table — USD budget enforcement skipped for its calls. Add it to ~/.patchwork/prices.json or set the agent step's model.`);
+                }
+                else {
+                    this.usdSpent += cost;
+                }
+            }
+        }
+        // warn-mode: emit a single in-band notice the first time we cross a cap.
+        if (!this.haltOnBreach) {
+            if (this.tokenBreached()) {
+                this.pushOnce("warn-token-breach", `Token budget exceeded (total=${this.totalTokens()}, tokensMax=${this.tokensMax}) but onBreach="warn" — continuing.`);
+            }
+            if (this.usdMaxBreached()) {
+                this.pushOnce("warn-usd-breach", `USD budget exceeded (usd=$${this.usdSpent.toFixed(4)}, usdMax=$${this.usdMax}) but onBreach="warn" — continuing.`);
             }
         }
     }
@@ -91,7 +157,13 @@ export class RunBudget {
             ...(this.tokensMax !== undefined && {
                 remaining: Math.max(0, this.tokensMax - total),
             }),
-            breached: this.breached(),
+            ...(this.usdMax !== undefined && {
+                usd: this.usdSpent,
+                usdRemaining: Math.max(0, this.usdMax - this.usdSpent),
+            }),
+            ...(this.usdEstimated > 0 && { usdEstimated: this.usdEstimated }),
+            breached: this.tokenBreached(),
+            usdBreached: this.usdMaxBreached(),
             haltOnBreach: this.haltOnBreach,
         };
     }
@@ -99,11 +171,72 @@ export class RunBudget {
     warnings() {
         return [...this.warningList];
     }
+    /**
+     * Run-completion warnings: the live `warnings()` plus a one-line ≈$ summary
+     * of the notional cost estimated for unmeasured calls (only when
+     * `estimateUnmeasured` produced one). Use at run end; `warnings()` is the
+     * live per-driver list without the (end-of-run-only) summary.
+     */
+    finalWarnings() {
+        const out = [...this.warningList];
+        if (this.usdEstimated > 0) {
+            out.push(`Unmeasured (subscription) calls would cost ≈$${this.usdEstimated.toFixed(4)} at list prices — estimate only, never enforced.`);
+        }
+        return out;
+    }
+    /**
+     * USD remaining before the cap, or undefined when no USD cap is set.
+     * Cost-aware routing (Phase 4) uses this to decide when to downshift.
+     */
+    remainingUsd() {
+        if (this.usdMax === undefined)
+            return undefined;
+        return Math.max(0, this.usdMax - this.usdSpent);
+    }
+    /**
+     * Pre-dispatch USD estimate for a prospective (driver, model) call, or
+     * undefined when it would NOT be USD-enforced: no USD cap, a non-billable
+     * driver (local / subscription), or an unpriced model. Mirrors exactly the
+     * enforcement rule in `reconcile`, so a candidate the router treats as
+     * "free" is precisely one `reconcile` would not charge.
+     */
+    quoteUsd(driver, model, inputTokens, outputTokens) {
+        if (this.usdMax === undefined)
+            return undefined;
+        // Mirror executeAgent/reconcile resolution so a candidate the router calls
+        // "free" is EXACTLY one reconcile would not charge:
+        //   - "api"/"claude" select the billable Anthropic path (→ "anthropic").
+        //   - undefined optimistically assumes auto-detect lands on a metered API
+        //     driver (usually anthropic); if it actually resolves to a subscription
+        //     driver the call is free and the cap simply isn't enforced there.
+        const resolvedDriver = driver === "api" || driver === "claude" ? "anthropic" : driver;
+        if (resolvedDriver !== undefined && !BILLABLE_DRIVERS.has(resolvedDriver)) {
+            return undefined;
+        }
+        // The anthropic path bills DEFAULT_MODEL when the step omits `model`.
+        // (Provider drivers default internally to a model unknowable pre-dispatch,
+        // so an omitted model there stays unpriced → not routed on.)
+        const onAnthropicPath = resolvedDriver === "anthropic" || resolvedDriver === undefined;
+        const resolvedModel = model ?? (onAnthropicPath ? DEFAULT_MODEL : undefined);
+        if (!resolvedModel)
+            return undefined;
+        const cost = costUsd(resolvedModel, { inputTokens, outputTokens }, this.priceTable);
+        return cost !== undefined && Number.isFinite(cost) ? cost : undefined;
+    }
+    pushOnce(key, msg) {
+        if (this.warnedKeys.has(key))
+            return;
+        this.warnedKeys.add(key);
+        this.warningList.push(msg);
+    }
     totalTokens() {
         return this.inputTokens + this.outputTokens;
     }
-    breached() {
+    tokenBreached() {
         return this.tokensMax !== undefined && this.totalTokens() >= this.tokensMax;
     }
+    usdMaxBreached() {
+        return this.usdMax !== undefined && this.usdSpent >= this.usdMax;
+    }
 }
 //# sourceMappingURL=runBudget.js.map

package/dist/recipes/runBudget.js.map

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

package/dist/recipes/schema.d.ts

@@ -115,20 +115,41 @@ export interface ErrorPolicy {
  * drivers (Anthropic API, OpenAI/Gemini/Grok subprocess that surfaces
  * usage, local LLM adapters) get full enforcement.
  *
- * Nested object (not flat `tokensMax`) so future siblings — `usdMax`,
- * `wallClockMs`, `stepsMax` — don't churn the schema again.
+ * Nested object (not flat `tokensMax`) so siblings — `usdMax` (added in
+ * cost-routing Phase 3), and future `wallClockMs` / `stepsMax` — don't churn
+ * the schema again.
  */
 export interface BudgetPolicy {
     /** Cumulative input + output tokens allowed across the whole run. */
     tokensMax?: number;
     /**
-     * What to do when the budget is breached. `halt` (default) stops the
+     * Cumulative USD allowed across the whole run, priced from token usage via
+     * the model price table (`src/recipes/pricing`). Enforced for measured +
+     * priced (API) drivers; a subscription driver that reports no tokens, or a
+     * model with no price-table entry, FAILS OPEN with a one-time warning and
+     * never halts on it. Same `onBreach` semantics as `tokensMax`. A USD cap on
+     * a subscription driver would be notional, not real money out — so it is
+     * deliberately not enforced there.
+     */
+    usdMax?: number;
+    /**
+     * What to do when a budget is breached. `halt` (default) stops the
      * run on the next admission check with a `budget_exceeded` halt
      * reason. `warn` continues the run but emits a warning + records the
      * breach in the run log; useful for tuning budgets without breaking
-     * production cron recipes.
+     * production cron recipes. Applies to both `tokensMax` and `usdMax`.
      */
     onBreach?: "halt" | "warn";
+    /**
+     * OPT-IN, default **false**. When true, the runner ESTIMATES the notional USD
+     * a subscription/unmeasured driver call would have cost at list prices (from
+     * the prompt + output length) and surfaces a `≈$X` figure. This is a label
+     * ONLY — estimated spend is tracked separately from `usdMax` and can NEVER
+     * halt a run (subscription spend is flat-rate, not real money out; halting on
+     * a ~4-chars/token guess would be wrong). Requires `usdMax` to be set (it
+     * reuses the price table). Default false preserves the fail-open invariant.
+     */
+    estimateUnmeasured?: boolean;
 }
 export interface Recipe {
     name: string;

package/dist/recipes/schemaGenerator.d.ts

@@ -22,6 +22,15 @@ export declare function generateSchemaSet(): SchemaSet;
  * should pin on `schemaVersion` and validate against this.
  */
 export declare function generateDryRunPlanSchema(): unknown;
+/**
+ * JSON Schema for the What-If Preview `RecipeSimulationReport`
+ * (`src/recipes/simulation/types.ts`), the output of
+ * `GET /recipes/:name/simulate` and `patchwork recipe simulate`. A superset of
+ * the dry-run plan; consumers pin on `schemaVersion`. Standalone (not part of
+ * `generateSchemaSet`/`writeSchemas`) — served on demand to consumers that want
+ * to validate the wire contract.
+ */
+export declare function generateSimulationSchema(): unknown;
 /**
  * Write schema files to disk.
  */