@vauban-org/agent-sdk 0.16.0

package/dist/constitution/types.d.ts

@@ -0,0 +1,295 @@
+/**
+ * src/constitution/types.ts
+ *
+ * Shared types for the constitution module.
+ * CycleSnapshot is a lightweight view of one agent run cycle for scoring purposes.
+ * It adapts Trace fields and adds budget / scope context needed by the gate.
+ *
+ * @module constitution/types
+ */
+import { z } from "zod";
+export interface SignalPoint {
+    /** Axiom-scoped label for this signal (e.g. "timeout_configured"). */
+    label: string;
+    /**
+     * Weight in [−1, 1].
+     * Positive = evidence the axiom is satisfied.
+     * Negative = evidence the axiom is violated.
+     */
+    weight: number;
+    /** Human-readable evidence string for audit trail. */
+    evidence: string;
+}
+export type AxiomId = "Institutionnel" | "SOTA" | "Robuste" | "AntiFragile" | "Profitable";
+export type GateSeverity = "block";
+export interface GateViolation {
+    axiom: AxiomId;
+    severity: GateSeverity;
+    rule: string;
+    rationale: string;
+}
+/** A single recorded step within a cycle, simplified for constitution use. */
+export interface CycleStep {
+    /** Zero-based monotone index. */
+    index: number;
+    /** Phase of this step (mirrors TraceStep.phase). */
+    phase: string;
+    /** Type of this step (mirrors TraceStep.type). */
+    type: string;
+    /** Serialised (and potentially redacted) output payload. Used for secret scanning. */
+    output?: unknown;
+    /** Stored input payload (mirrors TraceStep.storedInput). Used for PII detection. */
+    storedInput?: unknown;
+    /** LLM model that produced this step, if any. */
+    model?: {
+        provider: string;
+        name: string;
+        version: string;
+    };
+    /** Name of the tool invoked, for 'tool_call' steps. */
+    toolName?: string;
+    /** Estimated cost in USD for this step. */
+    costUsd?: number;
+}
+/** Arbitrary metadata the host attaches to the cycle at submission time. */
+export interface CycleMetadata {
+    /** If true the RSO has issued a veto on this cycle before evaluation. */
+    rso_veto?: boolean;
+    /** Hash primitive used by the agent (e.g. "poseidon", "keccak256"). */
+    hash_primitive?: string;
+    /** Whether a fallback path exists for this cycle (resilience signal). */
+    has_fallback?: boolean;
+    /** Whether the cycle's primary operation is idempotent. */
+    is_idempotent?: boolean;
+    /** Number of independent data / funding sources. */
+    source_count?: number;
+    /** Model provider name for recency analysis. */
+    model_provider?: string;
+    /** Model name for recency analysis. */
+    model_name?: string;
+    /** Whether SLSA supply-chain level ≥ 3 artefacts were used. */
+    slsa_level?: number;
+    /** Whether explicit timeouts are configured on all external calls. */
+    timeouts_configured?: boolean;
+    /** Whether error paths are explicit (no silent swallowing). */
+    error_paths_explicit?: boolean;
+    /** Whether cross-agent payloads with PII have been redacted. */
+    pii_redacted?: boolean;
+    /**
+     * Explicit audit-trail completeness flag.
+     * When true, the host asserts all steps are recorded and the rootHash is finalized.
+     */
+    audit_trail_complete?: boolean;
+    /**
+     * Regulatory scope this cycle operates under.
+     * Well-known values: "eIDAS", "gdpr", "ai-act-art-14".
+     * Used by the Institutionnel scorer to reward explicit regulatory alignment.
+     */
+    regulatory_scope?: string;
+    /**
+     * Opaque field bag — any additional host-side metadata.
+     */
+    [key: string]: unknown;
+}
+/**
+ * CycleSnapshot — the unit of analysis for constitutional scoring.
+ *
+ * Designed to be a strict subset of Trace (re-using `rootHash` and `steps`
+ * semantics) with additional budget / scope fields required by the gate.
+ */
+export interface CycleSnapshot {
+    /** Unique run identifier (mirrors Trace.runId). */
+    runId: string;
+    /** Parent run identifier when this is a child cycle. */
+    parentRunId?: string;
+    /** Ordered steps of this cycle. */
+    steps: CycleStep[];
+    /**
+     * Maximum allowed budget in USD for this cycle.
+     * Gate blocks child cycles that exceed the parent's budget.
+     */
+    budgetUsdMax: number;
+    /** Actual USD spent so far in this cycle. */
+    budgetUsdSpent: number;
+    /** Scope identifier — must be within parent's allowed_scope_ids. */
+    scope_id?: string;
+    /** Arbitrary metadata from the host. */
+    metadata?: CycleMetadata;
+    /**
+     * SHA-256 root hash of the step chain (mirrors Trace.rootHash).
+     * Presence confirms the cycle was finalized with integrity.
+     */
+    rootHash: string;
+}
+export declare const cycleSnapshotSchema: z.ZodObject<{
+    runId: z.ZodString;
+    parentRunId: z.ZodOptional<z.ZodString>;
+    steps: z.ZodArray<z.ZodObject<{
+        index: z.ZodNumber;
+        phase: z.ZodString;
+        type: z.ZodString;
+        output: z.ZodOptional<z.ZodUnknown>;
+        storedInput: z.ZodOptional<z.ZodUnknown>;
+        model: z.ZodOptional<z.ZodObject<{
+            provider: z.ZodString;
+            name: z.ZodString;
+            version: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            provider: string;
+            name: string;
+            version: string;
+        }, {
+            provider: string;
+            name: string;
+            version: string;
+        }>>;
+        toolName: z.ZodOptional<z.ZodString>;
+        costUsd: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        type: string;
+        index: number;
+        phase: string;
+        model?: {
+            provider: string;
+            name: string;
+            version: string;
+        } | undefined;
+        output?: unknown;
+        storedInput?: unknown;
+        toolName?: string | undefined;
+        costUsd?: number | undefined;
+    }, {
+        type: string;
+        index: number;
+        phase: string;
+        model?: {
+            provider: string;
+            name: string;
+            version: string;
+        } | undefined;
+        output?: unknown;
+        storedInput?: unknown;
+        toolName?: string | undefined;
+        costUsd?: number | undefined;
+    }>, "many">;
+    budgetUsdMax: z.ZodNumber;
+    budgetUsdSpent: z.ZodNumber;
+    scope_id: z.ZodOptional<z.ZodString>;
+    metadata: z.ZodOptional<z.ZodObject<{
+        rso_veto: z.ZodOptional<z.ZodBoolean>;
+        hash_primitive: z.ZodOptional<z.ZodString>;
+        has_fallback: z.ZodOptional<z.ZodBoolean>;
+        is_idempotent: z.ZodOptional<z.ZodBoolean>;
+        source_count: z.ZodOptional<z.ZodNumber>;
+        model_provider: z.ZodOptional<z.ZodString>;
+        model_name: z.ZodOptional<z.ZodString>;
+        slsa_level: z.ZodOptional<z.ZodNumber>;
+        timeouts_configured: z.ZodOptional<z.ZodBoolean>;
+        error_paths_explicit: z.ZodOptional<z.ZodBoolean>;
+        pii_redacted: z.ZodOptional<z.ZodBoolean>;
+        audit_trail_complete: z.ZodOptional<z.ZodBoolean>;
+        regulatory_scope: z.ZodOptional<z.ZodString>;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        rso_veto: z.ZodOptional<z.ZodBoolean>;
+        hash_primitive: z.ZodOptional<z.ZodString>;
+        has_fallback: z.ZodOptional<z.ZodBoolean>;
+        is_idempotent: z.ZodOptional<z.ZodBoolean>;
+        source_count: z.ZodOptional<z.ZodNumber>;
+        model_provider: z.ZodOptional<z.ZodString>;
+        model_name: z.ZodOptional<z.ZodString>;
+        slsa_level: z.ZodOptional<z.ZodNumber>;
+        timeouts_configured: z.ZodOptional<z.ZodBoolean>;
+        error_paths_explicit: z.ZodOptional<z.ZodBoolean>;
+        pii_redacted: z.ZodOptional<z.ZodBoolean>;
+        audit_trail_complete: z.ZodOptional<z.ZodBoolean>;
+        regulatory_scope: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        rso_veto: z.ZodOptional<z.ZodBoolean>;
+        hash_primitive: z.ZodOptional<z.ZodString>;
+        has_fallback: z.ZodOptional<z.ZodBoolean>;
+        is_idempotent: z.ZodOptional<z.ZodBoolean>;
+        source_count: z.ZodOptional<z.ZodNumber>;
+        model_provider: z.ZodOptional<z.ZodString>;
+        model_name: z.ZodOptional<z.ZodString>;
+        slsa_level: z.ZodOptional<z.ZodNumber>;
+        timeouts_configured: z.ZodOptional<z.ZodBoolean>;
+        error_paths_explicit: z.ZodOptional<z.ZodBoolean>;
+        pii_redacted: z.ZodOptional<z.ZodBoolean>;
+        audit_trail_complete: z.ZodOptional<z.ZodBoolean>;
+        regulatory_scope: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough">>>;
+    rootHash: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    runId: string;
+    steps: {
+        type: string;
+        index: number;
+        phase: string;
+        model?: {
+            provider: string;
+            name: string;
+            version: string;
+        } | undefined;
+        output?: unknown;
+        storedInput?: unknown;
+        toolName?: string | undefined;
+        costUsd?: number | undefined;
+    }[];
+    budgetUsdMax: number;
+    budgetUsdSpent: number;
+    rootHash: string;
+    metadata?: z.objectOutputType<{
+        rso_veto: z.ZodOptional<z.ZodBoolean>;
+        hash_primitive: z.ZodOptional<z.ZodString>;
+        has_fallback: z.ZodOptional<z.ZodBoolean>;
+        is_idempotent: z.ZodOptional<z.ZodBoolean>;
+        source_count: z.ZodOptional<z.ZodNumber>;
+        model_provider: z.ZodOptional<z.ZodString>;
+        model_name: z.ZodOptional<z.ZodString>;
+        slsa_level: z.ZodOptional<z.ZodNumber>;
+        timeouts_configured: z.ZodOptional<z.ZodBoolean>;
+        error_paths_explicit: z.ZodOptional<z.ZodBoolean>;
+        pii_redacted: z.ZodOptional<z.ZodBoolean>;
+        audit_trail_complete: z.ZodOptional<z.ZodBoolean>;
+        regulatory_scope: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough"> | undefined;
+    parentRunId?: string | undefined;
+    scope_id?: string | undefined;
+}, {
+    runId: string;
+    steps: {
+        type: string;
+        index: number;
+        phase: string;
+        model?: {
+            provider: string;
+            name: string;
+            version: string;
+        } | undefined;
+        output?: unknown;
+        storedInput?: unknown;
+        toolName?: string | undefined;
+        costUsd?: number | undefined;
+    }[];
+    budgetUsdMax: number;
+    budgetUsdSpent: number;
+    rootHash: string;
+    metadata?: z.objectInputType<{
+        rso_veto: z.ZodOptional<z.ZodBoolean>;
+        hash_primitive: z.ZodOptional<z.ZodString>;
+        has_fallback: z.ZodOptional<z.ZodBoolean>;
+        is_idempotent: z.ZodOptional<z.ZodBoolean>;
+        source_count: z.ZodOptional<z.ZodNumber>;
+        model_provider: z.ZodOptional<z.ZodString>;
+        model_name: z.ZodOptional<z.ZodString>;
+        slsa_level: z.ZodOptional<z.ZodNumber>;
+        timeouts_configured: z.ZodOptional<z.ZodBoolean>;
+        error_paths_explicit: z.ZodOptional<z.ZodBoolean>;
+        pii_redacted: z.ZodOptional<z.ZodBoolean>;
+        audit_trail_complete: z.ZodOptional<z.ZodBoolean>;
+        regulatory_scope: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough"> | undefined;
+    parentRunId?: string | undefined;
+    scope_id?: string | undefined;
+}>;
+//# sourceMappingURL=types.d.ts.map

package/dist/constitution/types.d.ts.map

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

package/dist/constitution/types.js

@@ -0,0 +1,59 @@
+/**
+ * src/constitution/types.ts
+ *
+ * Shared types for the constitution module.
+ * CycleSnapshot is a lightweight view of one agent run cycle for scoring purposes.
+ * It adapts Trace fields and adds budget / scope context needed by the gate.
+ *
+ * @module constitution/types
+ */
+import { z } from "zod";
+// ---------------------------------------------------------------------------
+// Zod schema for CycleSnapshot — used by gate input validation
+// ---------------------------------------------------------------------------
+const cycleStepSchema = z.object({
+    index: z.number().int().nonnegative(),
+    phase: z.string(),
+    type: z.string(),
+    output: z.unknown().optional(),
+    storedInput: z.unknown().optional(),
+    model: z
+        .object({
+        provider: z.string(),
+        name: z.string(),
+        version: z.string(),
+    })
+        .optional(),
+    toolName: z.string().optional(),
+    costUsd: z.number().optional(),
+});
+const cycleMetadataSchema = z
+    .object({
+    rso_veto: z.boolean().optional(),
+    hash_primitive: z.string().optional(),
+    has_fallback: z.boolean().optional(),
+    is_idempotent: z.boolean().optional(),
+    source_count: z.number().optional(),
+    model_provider: z.string().optional(),
+    model_name: z.string().optional(),
+    slsa_level: z.number().optional(),
+    timeouts_configured: z.boolean().optional(),
+    error_paths_explicit: z.boolean().optional(),
+    pii_redacted: z.boolean().optional(),
+    audit_trail_complete: z.boolean().optional(),
+    regulatory_scope: z.string().optional(),
+})
+    .passthrough();
+export const cycleSnapshotSchema = z
+    .object({
+    runId: z.string().min(1),
+    parentRunId: z.string().optional(),
+    steps: z.array(cycleStepSchema),
+    budgetUsdMax: z.number().nonnegative(),
+    budgetUsdSpent: z.number().nonnegative(),
+    scope_id: z.string().optional(),
+    metadata: cycleMetadataSchema.optional(),
+    rootHash: z.string().min(1),
+})
+    .strict();
+//# sourceMappingURL=types.js.map

package/dist/constitution/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/constitution/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAsIxB,8EAA8E;AAC9E,+DAA+D;AAC/D,8EAA8E;AAE9E,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC;IAC/B,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;IACrC,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;IACjB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,MAAM,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;IAC9B,WAAW,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;IACnC,KAAK,EAAE,CAAC;SACL,MAAM,CAAC;QACN,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;QACpB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;QAChB,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;KACpB,CAAC;SACD,QAAQ,EAAE;IACb,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC/B,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAC/B,CAAC,CAAC;AAEH,MAAM,mBAAmB,GAAG,CAAC;KAC1B,MAAM,CAAC;IACN,QAAQ,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;IAChC,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACrC,YAAY,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;IACpC,aAAa,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;IACrC,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACnC,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACrC,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACjC,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACjC,mBAAmB,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;IAC3C,oBAAoB,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;IAC5C,YAAY,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;IACpC,oBAAoB,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;IAC5C,gBAAgB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CACxC,CAAC;KACD,WAAW,EAAE,CAAC;AAEjB,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC;KACjC,MAAM,CAAC;IACN,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACxB,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAClC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,eAAe,CAAC;IAC/B,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,WAAW,EAAE;IACtC,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,WAAW,EAAE;IACxC,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC/B,QAAQ,EAAE,mBAAmB,CAAC,QAAQ,EAAE;IACxC,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;CAC5B,CAAC;KACD,MAAM,EAAE,CAAC"}

package/dist/counterfactual/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @vauban-org/agent-sdk — Counterfactual replay module public API.
+ *
+ * OFFLINE TOOL. NOT a centerpiece. Use for ex-post analysis only —
+ * never wire into live runtime.
+ *
+ * @module counterfactual
+ */
+export { replayCounterfactual, InvalidStrategyNameError, } from "./replay-with-alt.js";
+export type { ComputeStrategyName, CounterfactualOptions, CounterfactualResult, CounterfactualReplayContext, } from "./replay-with-alt.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/counterfactual/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/counterfactual/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EACL,oBAAoB,EACpB,wBAAwB,GACzB,MAAM,sBAAsB,CAAC;AAE9B,YAAY,EACV,mBAAmB,EACnB,qBAAqB,EACrB,oBAAoB,EACpB,2BAA2B,GAC5B,MAAM,sBAAsB,CAAC"}

package/dist/counterfactual/index.js

@@ -0,0 +1,10 @@
+/**
+ * @vauban-org/agent-sdk — Counterfactual replay module public API.
+ *
+ * OFFLINE TOOL. NOT a centerpiece. Use for ex-post analysis only —
+ * never wire into live runtime.
+ *
+ * @module counterfactual
+ */
+export { replayCounterfactual, InvalidStrategyNameError, } from "./replay-with-alt.js";
+//# sourceMappingURL=index.js.map

package/dist/counterfactual/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/counterfactual/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EACL,oBAAoB,EACpB,wBAAwB,GACzB,MAAM,sBAAsB,CAAC"}

package/dist/counterfactual/replay-with-alt.d.ts

@@ -0,0 +1,137 @@
+/**
+ * OFFLINE TOOL. NOT a centerpiece. Use for ex-post analysis only —
+ * never wire into live runtime.
+ *
+ * replayCounterfactual — counterfactual replay primitive.
+ *
+ * Given an original runId, replays the same cycle with an alternative compute
+ * strategy (or verifier / temperature override). The original run's
+ * clock/random/cache are kept fixed — only the compute strategy is swapped.
+ *
+ * Purpose: offline "what-if" analysis. E.g. "what if this cycle had used
+ * best-of-n instead of single-shot?"
+ *
+ * Design invariants:
+ *   - Does NOT mutate the original trace or any live execution path.
+ *   - ReplayRunner.run() receives a ReplayContext augmented with strategyOverride
+ *     injected into the runner's compute config.
+ *   - "outputsCoherent" = same runtime type AND same top-level keys (for objects).
+ *   - "outputsIdentical" = deep structural equality via JSON serialisation.
+ *
+ * @module counterfactual/replay-with-alt
+ */
+import type { ReplayLoader, ReplayRunner, ReplayContext } from "../replay/replay.js";
+import type { Verifier } from "../compute/verifier.js";
+/**
+ * Canonical strategy names accepted by the runner's strategyOverride field.
+ * Callers passing an unknown name will get an InvalidStrategyNameError.
+ */
+export type ComputeStrategyName = "single-shot" | "best-of-n" | "bon-mav";
+/**
+ * Options for replayCounterfactual.
+ * At least one of alt_strategy, alt_verifier, or alt_temperature should differ
+ * from the original run to produce a meaningful counterfactual.
+ */
+export interface CounterfactualOptions {
+    /** Swap the compute strategy (e.g. "best-of-n" instead of "single-shot"). */
+    alt_strategy?: ComputeStrategyName;
+    /** Replace the verifier used by the strategy (e.g. swap to a stricter judge). */
+    alt_verifier?: Verifier;
+    /** Replace the generation temperature (0–2 range; host-interpreted). */
+    alt_temperature?: number;
+}
+/**
+ * Result of a counterfactual replay run.
+ *
+ * outputsCoherent:
+ *   true when both outputs have the same runtime type AND, if both are plain
+ *   objects, the same set of top-level keys. This is a structural compatibility
+ *   check — not a value comparison.
+ *
+ * outputsIdentical:
+ *   true when JSON.stringify(original) === JSON.stringify(counterfactual).
+ *   Guarantees deep value equality for JSON-serialisable outputs.
+ */
+export interface CounterfactualResult {
+    /** runId of the original run that was replayed. */
+    originalRunId: string;
+    /** runId assigned to the counterfactual replay run. */
+    counterfactualRunId: string;
+    /** Output produced by replaying with the original strategy / settings. */
+    originalOutput: unknown;
+    /** Output produced by replaying with the altered strategy / settings. */
+    counterfactualOutput: unknown;
+    /**
+     * true iff both outputs are structurally compatible:
+     *   - Same typeof (or both null).
+     *   - If both are plain objects: same set of top-level keys (order-independent).
+     */
+    outputsCoherent: boolean;
+    /**
+     * true iff both outputs are byte-identical under JSON serialisation.
+     * Implies outputsCoherent === true.
+     */
+    outputsIdentical: boolean;
+    metadata: {
+        /** Strategy swap details, present when alt_strategy was supplied. */
+        strategySwapped?: {
+            from: string;
+            to: ComputeStrategyName;
+        };
+        /**
+         * Difference in reported cost_usd between the two runs.
+         * Positive = counterfactual was more expensive.
+         * undefined when the runner does not populate cost_usd.
+         */
+        cost_delta_usd?: number;
+        /**
+         * Difference in wall-clock latency in milliseconds.
+         * Positive = counterfactual was slower.
+         */
+        latency_delta_ms?: number;
+        /** Number of LLM cache hits during the counterfactual run. */
+        cacheHits: number;
+        /** Number of LLM cache misses during the counterfactual run. */
+        cacheMisses: number;
+    };
+}
+/**
+ * Thrown when alt_strategy is not one of the known ComputeStrategyName values.
+ */
+export declare class InvalidStrategyNameError extends Error {
+    readonly name: string;
+    constructor(name: string);
+}
+/**
+ * Internal extension of ReplayContext carrying counterfactual overrides.
+ * Passed to ReplayRunner.run() — the runner inspects these fields to swap
+ * its compute configuration for the counterfactual execution.
+ */
+export interface CounterfactualReplayContext extends ReplayContext {
+    /** When present, the runner MUST override its compute strategy with this name. */
+    readonly strategyOverride?: ComputeStrategyName;
+    /** When present, the runner SHOULD swap its verifier with this instance. */
+    readonly verifierOverride?: Verifier;
+    /** When present, the runner SHOULD apply this temperature value. */
+    readonly temperatureOverride?: number;
+}
+/**
+ * Replay the original cycle twice — once with its original config, once with
+ * the alt overrides — and compare outputs.
+ *
+ * Both runs use the SAME virtualized clock, random, and LLM cache derived from
+ * the original run's recorded artifacts. Only the compute strategy (and optional
+ * verifier / temperature) differs.
+ *
+ * OFFLINE TOOL. Do NOT call from any live execution path.
+ *
+ * @param originalRunId  runId of the run to analyse counterfactually.
+ * @param loader         Loader for the original trace + recorded artifacts.
+ * @param runner         Runner that accepts CounterfactualReplayContext.
+ *                       Contract: runner.run() MUST honour ctx.strategyOverride
+ *                       when present.
+ * @param opts           Counterfactual overrides (at least one should differ
+ *                       from the original to be meaningful).
+ */
+export declare function replayCounterfactual(originalRunId: string, loader: ReplayLoader, runner: ReplayRunner, opts: CounterfactualOptions): Promise<CounterfactualResult>;
+//# sourceMappingURL=replay-with-alt.d.ts.map

package/dist/counterfactual/replay-with-alt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay-with-alt.d.ts","sourceRoot":"","sources":["../../src/counterfactual/replay-with-alt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAGrF,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAIvD;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAAG,aAAa,GAAG,WAAW,GAAG,SAAS,CAAC;AAW1E;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,6EAA6E;IAC7E,YAAY,CAAC,EAAE,mBAAmB,CAAC;IACnC,iFAAiF;IACjF,YAAY,CAAC,EAAE,QAAQ,CAAC;IACxB,wEAAwE;IACxE,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAID;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,oBAAoB;IACnC,mDAAmD;IACnD,aAAa,EAAE,MAAM,CAAC;IACtB,uDAAuD;IACvD,mBAAmB,EAAE,MAAM,CAAC;IAC5B,0EAA0E;IAC1E,cAAc,EAAE,OAAO,CAAC;IACxB,yEAAyE;IACzE,oBAAoB,EAAE,OAAO,CAAC;IAC9B;;;;OAIG;IACH,eAAe,EAAE,OAAO,CAAC;IACzB;;;OAGG;IACH,gBAAgB,EAAE,OAAO,CAAC;IAC1B,QAAQ,EAAE;QACR,qEAAqE;QACrE,eAAe,CAAC,EAAE;YAChB,IAAI,EAAE,MAAM,CAAC;YACb,EAAE,EAAE,mBAAmB,CAAC;SACzB,CAAC;QACF;;;;WAIG;QACH,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB;;;WAGG;QACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,8DAA8D;QAC9D,SAAS,EAAE,MAAM,CAAC;QAClB,gEAAgE;QAChE,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC;CACH;AAID;;GAEG;AACH,qBAAa,wBAAyB,SAAQ,KAAK;aACrB,IAAI,EAAE,MAAM;gBAAZ,IAAI,EAAE,MAAM;CAOzC;AAID;;;;GAIG;AACH,MAAM,WAAW,2BAA4B,SAAQ,aAAa;IAChE,kFAAkF;IAClF,QAAQ,CAAC,gBAAgB,CAAC,EAAE,mBAAmB,CAAC;IAChD,4EAA4E;IAC5E,QAAQ,CAAC,gBAAgB,CAAC,EAAE,QAAQ,CAAC;IACrC,oEAAoE;IACpE,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;CACvC;AA8DD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,oBAAoB,CACxC,aAAa,EAAE,MAAM,EACrB,MAAM,EAAE,YAAY,EACpB,MAAM,EAAE,YAAY,EACpB,IAAI,EAAE,qBAAqB,GAC1B,OAAO,CAAC,oBAAoB,CAAC,CA6H/B"}