@vauban-org/agent-sdk 0.16.0

package/dist/replay/llm-cache.js

@@ -0,0 +1,114 @@
+/**
+ * LLMResponseCache — content-addressed in-memory cache for LLM responses.
+ *
+ * Cache key: SHA-256(canonical({provider, model, messages, temperature, seed?}))
+ * This makes the cache deterministic across runs given identical inputs,
+ * enabling replay of LLM responses without hitting the actual provider.
+ *
+ * Production adapters (pgsql, Redis) belong to the B-series tasks.
+ * This module ships the in-memory implementation + the hash utility.
+ *
+ * @module replay/llm-cache
+ */
+import { canonicalize } from "../trace/canonical.js";
+// ─── hashLLMCacheKey ──────────────────────────────────────────────────────────
+/**
+ * Compute the SHA-256 hex hash of a canonical LLMCacheKey.
+ *
+ * Uses Web Crypto API (globalThis.crypto.subtle) — zero external dependencies.
+ * Requires Node >= 20 or any modern browser.
+ *
+ * Array order in `messages` is significant: two arrays with the same elements
+ * in different order will produce different hashes.
+ */
+export async function hashLLMCacheKey(key) {
+    const canonical = canonicalize(key);
+    const encoded = new TextEncoder().encode(canonical);
+    const hashBuffer = await globalThis.crypto.subtle.digest("SHA-256", encoded);
+    return bufferToHex(hashBuffer);
+}
+function bufferToHex(buffer) {
+    return Array.from(new Uint8Array(buffer))
+        .map((b) => b.toString(16).padStart(2, "0"))
+        .join("");
+}
+// ─── InMemoryLLMResponseCache ─────────────────────────────────────────────────
+/**
+ * In-memory LLM response cache keyed by SHA-256(canonical(LLMCacheKey)).
+ *
+ * Intended for:
+ *   - Unit and integration tests (deterministic, zero I/O).
+ *   - Development replay (fast, ephemeral).
+ *
+ * NOT intended for production: data is lost on process restart.
+ * Production replay should use the PostgreSQL adapter (B-series).
+ */
+export class InMemoryLLMResponseCache {
+    store = new Map();
+    async get(key) {
+        const hash = await hashLLMCacheKey(key);
+        return this.store.get(hash);
+    }
+    async put(key, response) {
+        const hash = await hashLLMCacheKey(key);
+        this.store.set(hash, {
+            key: hash,
+            response,
+            recordedAt: Date.now(),
+        });
+    }
+    clear() {
+        this.store.clear();
+    }
+}
+// ─── CompositeLLMResponseCache ────────────────────────────────────────────────
+/**
+ * Composite (two-level) LLM response cache.
+ *
+ * Lookup order: child cache first, then parent cache (lookup-through).
+ * Writes go only to the child cache. In replay mode the child is typically
+ * read-only (no new entries), so `put()` is a no-op — pass `readOnly: true`.
+ *
+ * Use `withParent()` to construct a child cache that inherits responses from a
+ * parent cycle without polluting the parent's store.
+ */
+export class CompositeLLMResponseCache {
+    child;
+    parent;
+    readOnly;
+    constructor(child, parent, readOnly = false) {
+        this.child = child;
+        this.parent = parent;
+        this.readOnly = readOnly;
+    }
+    async get(key) {
+        // Child takes priority (own cycle entries override parent)
+        const childHit = await this.child.get(key);
+        if (childHit !== undefined)
+            return childHit;
+        return this.parent.get(key);
+    }
+    async put(key, response) {
+        if (this.readOnly)
+            return;
+        await this.child.put(key, response);
+    }
+    clear() {
+        if (!this.readOnly && typeof this.child.clear === "function") {
+            this.child.clear();
+        }
+    }
+}
+/**
+ * Factory: creates a composite cache that looks up `parentCache` on miss.
+ * The child is a fresh InMemoryLLMResponseCache — writes do NOT propagate to
+ * the parent (write-back disabled in replay mode by default).
+ *
+ * @param parentCache  The parent cycle's cache (read-only access).
+ * @param readOnly     When true, put() is a no-op (replay write-back disabled).
+ *                     Defaults to true for replay safety.
+ */
+export function withParent(parentCache, readOnly = true) {
+    return new CompositeLLMResponseCache(new InMemoryLLMResponseCache(), parentCache, readOnly);
+}
+//# sourceMappingURL=llm-cache.js.map

package/dist/replay/llm-cache.js.map

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

package/dist/replay/random.d.ts

@@ -0,0 +1,114 @@
+/**
+ * RandomPort — dual-API random number source for deterministic replay.
+ *
+ * CH4 DUAL API DESIGN:
+ *   Two distinct APIs with different guarantees — never conflate them:
+ *
+ *   Deterministic (replay-safe, NON SECURITY-GRADE):
+ *     next()   — float in [0, 1) via xorshift32 seeded PRNG
+ *     uuid()   — deterministic v4-like UUID from xorshift32 (NOT crypto-strong)
+ *
+ *   Crypto-strong (NON REPLAY-SAFE by design — security trumps audit):
+ *     crypto(bytes)  — random bytes via globalThis.crypto.getRandomValues
+ *     cryptoUuid()   — crypto-strong UUID via globalThis.crypto.randomUUID
+ *
+ * Use next()/uuid() for application logic that needs to be replayable.
+ * Use crypto()/cryptoUuid() for security-critical values (tokens, nonces, keys)
+ * that MUST NOT be replayable.
+ *
+ * During replay, calling crypto()/cryptoUuid() on RecordedRandom in strict mode
+ * throws CryptoRandomDuringReplayError to surface the violation at the boundary.
+ *
+ * @module replay/random
+ */
+/**
+ * Abstract random source with a dual API:
+ * - Deterministic arm (next/uuid): seedable, replay-safe, NON SECURITY-GRADE.
+ * - Crypto arm (crypto/cryptoUuid): crypto-strong, NON REPLAY-SAFE by design.
+ */
+export interface RandomPort {
+    /**
+     * Returns a float in [0, 1) via the deterministic PRNG.
+     * NON SECURITY-GRADE — use for application logic only.
+     */
+    next(): number;
+    /**
+     * Returns a deterministic v4-like UUID from the seeded PRNG.
+     * Format: xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx
+     * NON SECURITY-GRADE — use for replayable correlation IDs only.
+     */
+    uuid(): string;
+    /**
+     * Returns `bytes` cryptographically random bytes via globalThis.crypto.
+     * NON REPLAY-SAFE by design — security trumps audit.
+     */
+    crypto(bytes: number): Promise<Uint8Array>;
+    /**
+     * Returns a cryptographically strong UUID via globalThis.crypto.randomUUID.
+     * NON REPLAY-SAFE by design.
+     */
+    cryptoUuid(): string;
+}
+/**
+ * Thrown by RecordedRandom in 'strict' mode when crypto()/cryptoUuid() is called.
+ * Signals that the agent called a non-replayable code path during replay —
+ * a violation of the deterministic replay contract.
+ */
+export declare class CryptoRandomDuringReplayError extends Error {
+    constructor();
+}
+/**
+ * Production implementation:
+ * - next()/uuid(): xorshift32 seeded PRNG (deterministic if seed is fixed).
+ * - crypto()/cryptoUuid(): globalThis.crypto (non-deterministic, crypto-strong).
+ *
+ * Pass a fixed seed to make next()/uuid() deterministic across runs.
+ * Default seed: Date.now() XOR a random 32-bit value (non-deterministic).
+ */
+export declare class RealRandom implements RandomPort {
+    private readonly state;
+    constructor(seed?: number);
+    next(): number;
+    uuid(): string;
+    crypto(bytes: number): Promise<Uint8Array>;
+    cryptoUuid(): string;
+}
+/**
+ * Replay implementation: replays recorded next()/uuid() sequences.
+ *
+ * - next(): returns the next value from recordedNext (throws RangeError when exhausted).
+ * - uuid(): returns the next value from recordedUuids (throws RangeError when exhausted).
+ * - crypto(): throws CryptoRandomDuringReplayError in 'strict' mode;
+ *             returns fresh crypto bytes in 'tolerant' mode.
+ * - cryptoUuid(): throws CryptoRandomDuringReplayError in 'strict' mode;
+ *                 returns fresh crypto UUID in 'tolerant' mode.
+ */
+export declare class RecordedRandom implements RandomPort {
+    private readonly recordedNext;
+    private readonly recordedUuids;
+    private readonly mode;
+    private nextCursor;
+    private uuidCursor;
+    constructor(recordedNext: readonly number[], recordedUuids: readonly string[], mode?: "strict" | "tolerant");
+    next(): number;
+    uuid(): string;
+    crypto(bytes: number): Promise<Uint8Array>;
+    cryptoUuid(): string;
+    /**
+     * Returns a new RecordedRandom that shares the same underlying recorded arrays
+     * and starts at the CURRENT cursor positions (nextCursor + uuidCursor). Each
+     * clone maintains its own independent cursors — arrays are shared (read-only).
+     *
+     * Use for cross-cycle propagation: child cycle picks up exactly where the
+     * parent left off in both the next() and uuid() sequences.
+     *
+     * Clone invariant: clone.next() returns the same value as `this.next()` would
+     * at the moment clone() is called.
+     */
+    clone(): RecordedRandom;
+    /** Returns current nextCursor (number of next() values consumed). */
+    getNextCursor(): number;
+    /** Returns current uuidCursor (number of uuid() values consumed). */
+    getUuidCursor(): number;
+}
+//# sourceMappingURL=random.d.ts.map

package/dist/replay/random.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"random.d.ts","sourceRoot":"","sources":["../../src/replay/random.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAIH;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB;;;OAGG;IACH,IAAI,IAAI,MAAM,CAAC;IAEf;;;;OAIG;IACH,IAAI,IAAI,MAAM,CAAC;IAEf;;;OAGG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAE3C;;;OAGG;IACH,UAAU,IAAI,MAAM,CAAC;CACtB;AAID;;;;GAIG;AACH,qBAAa,6BAA8B,SAAQ,KAAK;;CASvD;AAwCD;;;;;;;GAOG;AACH,qBAAa,UAAW,YAAW,UAAU;IAC3C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAc;gBAExB,IAAI,CAAC,EAAE,MAAM;IASzB,IAAI,IAAI,MAAM;IAKd,IAAI,IAAI,MAAM;IAQR,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAMhD,UAAU,IAAI,MAAM;CAGrB;AAID;;;;;;;;;GASG;AACH,qBAAa,cAAe,YAAW,UAAU;IAK7C,OAAO,CAAC,QAAQ,CAAC,YAAY;IAC7B,OAAO,CAAC,QAAQ,CAAC,aAAa;IAC9B,OAAO,CAAC,QAAQ,CAAC,IAAI;IANvB,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,UAAU,CAAK;gBAGJ,YAAY,EAAE,SAAS,MAAM,EAAE,EAC/B,aAAa,EAAE,SAAS,MAAM,EAAE,EAChC,IAAI,GAAE,QAAQ,GAAG,UAAqB;IAGzD,IAAI,IAAI,MAAM;IAUd,IAAI,IAAI,MAAM;IAUR,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAUhD,UAAU,IAAI,MAAM;IAOpB;;;;;;;;;;OAUG;IACH,KAAK,IAAI,cAAc;IAWvB,qEAAqE;IACrE,aAAa,IAAI,MAAM;IAIvB,qEAAqE;IACrE,aAAa,IAAI,MAAM;CAGxB"}

package/dist/replay/random.js

@@ -0,0 +1,183 @@
+/**
+ * RandomPort — dual-API random number source for deterministic replay.
+ *
+ * CH4 DUAL API DESIGN:
+ *   Two distinct APIs with different guarantees — never conflate them:
+ *
+ *   Deterministic (replay-safe, NON SECURITY-GRADE):
+ *     next()   — float in [0, 1) via xorshift32 seeded PRNG
+ *     uuid()   — deterministic v4-like UUID from xorshift32 (NOT crypto-strong)
+ *
+ *   Crypto-strong (NON REPLAY-SAFE by design — security trumps audit):
+ *     crypto(bytes)  — random bytes via globalThis.crypto.getRandomValues
+ *     cryptoUuid()   — crypto-strong UUID via globalThis.crypto.randomUUID
+ *
+ * Use next()/uuid() for application logic that needs to be replayable.
+ * Use crypto()/cryptoUuid() for security-critical values (tokens, nonces, keys)
+ * that MUST NOT be replayable.
+ *
+ * During replay, calling crypto()/cryptoUuid() on RecordedRandom in strict mode
+ * throws CryptoRandomDuringReplayError to surface the violation at the boundary.
+ *
+ * @module replay/random
+ */
+// ─── CryptoRandomDuringReplayError ────────────────────────────────────────────
+/**
+ * Thrown by RecordedRandom in 'strict' mode when crypto()/cryptoUuid() is called.
+ * Signals that the agent called a non-replayable code path during replay —
+ * a violation of the deterministic replay contract.
+ */
+export class CryptoRandomDuringReplayError extends Error {
+    constructor() {
+        super("crypto() / cryptoUuid() called during replay. " +
+            "Crypto random is NON-REPLAY-SAFE by design (security trumps audit). " +
+            "Use random.next() / random.uuid() for replayable values.");
+        this.name = "CryptoRandomDuringReplayError";
+    }
+}
+// ─── xorshift32 PRNG ─────────────────────────────────────────────────────────
+/**
+ * xorshift32 — minimal seedable PRNG.
+ * Period: 2^32 - 1. Passes BigCrush for basic applications.
+ * NOT cryptographically secure — use only for deterministic application logic.
+ *
+ * Reference: Marsaglia, G. (2003). "Xorshift RNGs". Journal of Statistical Software.
+ */
+function xorshift32(state) {
+    let x = state[0];
+    x ^= x << 13;
+    x ^= x >>> 17;
+    x ^= x << 5;
+    state[0] = x >>> 0; // force unsigned 32-bit
+    return x >>> 0;
+}
+/** Convert 4 uint32 nibbles to a standard UUID v4-like hex string. */
+function nibblesToUuid(a, b, c, d) {
+    const hex = (n, len) => n.toString(16).padStart(len, "0");
+    // v4-like: set version bits (4) and variant bits (10xx)
+    const timeLow = hex(a, 8);
+    const timeMid = hex((b >>> 16) & 0xffff, 4);
+    // version nibble: force 4
+    const timeHiAndVersion = hex(((b & 0x0fff) | 0x4000), 4);
+    // variant: force 10xx
+    const clockSeqHiAndRes = hex(((c >>> 24) & 0x3f) | 0x80, 2);
+    const clockSeqLow = hex((c >>> 16) & 0xff, 2);
+    const node = hex(((c & 0xffff) * 0x100000000 + d) >>> 0, 12).padStart(12, "0");
+    return `${timeLow}-${timeMid}-${timeHiAndVersion}-${clockSeqHiAndRes}${clockSeqLow}-${node}`;
+}
+// ─── RealRandom ───────────────────────────────────────────────────────────────
+/**
+ * Production implementation:
+ * - next()/uuid(): xorshift32 seeded PRNG (deterministic if seed is fixed).
+ * - crypto()/cryptoUuid(): globalThis.crypto (non-deterministic, crypto-strong).
+ *
+ * Pass a fixed seed to make next()/uuid() deterministic across runs.
+ * Default seed: Date.now() XOR a random 32-bit value (non-deterministic).
+ */
+export class RealRandom {
+    state;
+    constructor(seed) {
+        const s = seed !== undefined
+            ? seed >>> 0 // coerce to uint32
+            : (Date.now() ^ Math.floor(Math.random() * 2 ** 32)) >>> 0;
+        // xorshift32 must not start with 0
+        this.state = new Uint32Array([s === 0 ? 1 : s]);
+    }
+    next() {
+        // xorshift32 returns uint32; divide by 2^32 to get [0, 1)
+        return xorshift32(this.state) / 0x100000000;
+    }
+    uuid() {
+        const a = xorshift32(this.state);
+        const b = xorshift32(this.state);
+        const c = xorshift32(this.state);
+        const d = xorshift32(this.state);
+        return nibblesToUuid(a, b, c, d);
+    }
+    async crypto(bytes) {
+        const buf = new Uint8Array(bytes);
+        globalThis.crypto.getRandomValues(buf);
+        return buf;
+    }
+    cryptoUuid() {
+        return globalThis.crypto.randomUUID();
+    }
+}
+// ─── RecordedRandom ───────────────────────────────────────────────────────────
+/**
+ * Replay implementation: replays recorded next()/uuid() sequences.
+ *
+ * - next(): returns the next value from recordedNext (throws RangeError when exhausted).
+ * - uuid(): returns the next value from recordedUuids (throws RangeError when exhausted).
+ * - crypto(): throws CryptoRandomDuringReplayError in 'strict' mode;
+ *             returns fresh crypto bytes in 'tolerant' mode.
+ * - cryptoUuid(): throws CryptoRandomDuringReplayError in 'strict' mode;
+ *                 returns fresh crypto UUID in 'tolerant' mode.
+ */
+export class RecordedRandom {
+    recordedNext;
+    recordedUuids;
+    mode;
+    nextCursor = 0;
+    uuidCursor = 0;
+    constructor(recordedNext, recordedUuids, mode = "strict") {
+        this.recordedNext = recordedNext;
+        this.recordedUuids = recordedUuids;
+        this.mode = mode;
+    }
+    next() {
+        if (this.nextCursor >= this.recordedNext.length) {
+            throw new RangeError(`RecordedRandom.next() exhausted: ${this.recordedNext.length} values recorded, ` +
+                `${this.nextCursor + 1} requested`);
+        }
+        return this.recordedNext[this.nextCursor++];
+    }
+    uuid() {
+        if (this.uuidCursor >= this.recordedUuids.length) {
+            throw new RangeError(`RecordedRandom.uuid() exhausted: ${this.recordedUuids.length} values recorded, ` +
+                `${this.uuidCursor + 1} requested`);
+        }
+        return this.recordedUuids[this.uuidCursor++];
+    }
+    async crypto(bytes) {
+        if (this.mode === "strict") {
+            throw new CryptoRandomDuringReplayError();
+        }
+        // tolerant: return fresh crypto bytes (non-deterministic but not fatal)
+        const buf = new Uint8Array(bytes);
+        globalThis.crypto.getRandomValues(buf);
+        return buf;
+    }
+    cryptoUuid() {
+        if (this.mode === "strict") {
+            throw new CryptoRandomDuringReplayError();
+        }
+        return globalThis.crypto.randomUUID();
+    }
+    /**
+     * Returns a new RecordedRandom that shares the same underlying recorded arrays
+     * and starts at the CURRENT cursor positions (nextCursor + uuidCursor). Each
+     * clone maintains its own independent cursors — arrays are shared (read-only).
+     *
+     * Use for cross-cycle propagation: child cycle picks up exactly where the
+     * parent left off in both the next() and uuid() sequences.
+     *
+     * Clone invariant: clone.next() returns the same value as `this.next()` would
+     * at the moment clone() is called.
+     */
+    clone() {
+        const child = new RecordedRandom(this.recordedNext, this.recordedUuids, this.mode);
+        child.nextCursor = this.nextCursor;
+        child.uuidCursor = this.uuidCursor;
+        return child;
+    }
+    /** Returns current nextCursor (number of next() values consumed). */
+    getNextCursor() {
+        return this.nextCursor;
+    }
+    /** Returns current uuidCursor (number of uuid() values consumed). */
+    getUuidCursor() {
+        return this.uuidCursor;
+    }
+}
+//# sourceMappingURL=random.js.map

package/dist/replay/random.js.map

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

package/dist/replay/replay.d.ts

@@ -0,0 +1,160 @@
+/**
+ * replayFrom — deterministic agent run replay.
+ *
+ * Given a runId, a ReplayLoader (fetches original trace + recorded artifacts),
+ * and a ReplayRunner (re-executes the agent with virtualized dependencies),
+ * replayFrom produces a ReplayResult containing:
+ *   - The replayed trace.
+ *   - A match flag: true iff rootHash of replay === rootHash of original.
+ *   - A diff array listing step-level field mismatches (when match is false).
+ *
+ * Design invariant:
+ *   Replay proves byte-identical traces when ClockPort, RandomPort, and
+ *   LLMResponseCache are virtualized. It does NOT prove LLM provider-side
+ *   determinism — the provider may return different tokens under identical
+ *   inputs (temperature, context window, batching).
+ *
+ * @module replay/replay
+ */
+import type { Trace, TraceStep } from "../trace/schema.js";
+import type { ClockPort } from "./clock.js";
+import type { RandomPort } from "./random.js";
+import type { LLMResponseCache } from "./llm-cache.js";
+/**
+ * Controls strictness of the replay session.
+ *
+ * - 'strict': crypto()/cryptoUuid() throws CryptoRandomDuringReplayError.
+ *             Any non-deterministic call is surfaced immediately.
+ * - 'tolerant': crypto()/cryptoUuid() returns fresh bytes (non-fatal).
+ *               Useful for runs that legitimately mix deterministic + crypto calls.
+ */
+export type ReplayMode = "strict" | "tolerant";
+/**
+ * Virtualised execution context for a replay run.
+ * Pass this to ReplayRunner.run() in place of the production context.
+ */
+export interface ReplayContext {
+    /** runId of the original run being replayed. */
+    readonly originalRunId: string;
+    /**
+     * A distinct runId for this replay run.
+     * Must differ from originalRunId — replay runs are traceable separately.
+     */
+    readonly replayRunId: string;
+    /** Strictness mode for crypto calls. */
+    readonly mode: ReplayMode;
+    /** Virtualized clock replaying the original run's timestamps. */
+    readonly clock: ClockPort;
+    /** Virtualized PRNG replaying the original run's random values. */
+    readonly random: RandomPort;
+    /** Virtualized LLM cache replaying the original run's responses. */
+    readonly cache: LLMResponseCache;
+}
+/**
+ * Result of a replay execution.
+ *
+ * match === true  → replay is byte-identical to the original (rootHash matches).
+ * match === false → at least one step diverged; see diff for details.
+ */
+export interface ReplayResult {
+    /** The replay run identifier. */
+    replayRunId: string;
+    /** The trace produced by the replay run. */
+    trace: Trace;
+    /**
+     * True iff the rootHash of the replay trace equals the rootHash of the
+     * original trace. This is the primary audit assertion.
+     */
+    match: boolean;
+    /**
+     * Step-level field mismatches, populated when match is false.
+     * Empty array when match is true.
+     */
+    diff?: {
+        stepIndex: number;
+        field: keyof TraceStep;
+        original: unknown;
+        replayed: unknown;
+    }[];
+}
+/**
+ * Port for loading the artifacts needed to replay a run.
+ * The host provides a concrete implementation (e.g. pgsql, file system).
+ */
+export interface ReplayLoader {
+    /**
+     * Fetch the original Trace for the given runId.
+     * Throws if the run is not found.
+     */
+    loadOriginalTrace(runId: string): Promise<Trace>;
+    /**
+     * Fetch all recorded artifacts for the given runId:
+     *   - recordedTs: timestamps array for RecordedClock
+     *   - recordedNext: float array for RecordedRandom.next()
+     *   - recordedUuids: UUID array for RecordedRandom.uuid()
+     *   - cache: LLMResponseCache populated with the original run's responses
+     */
+    loadCacheEntries(runId: string): Promise<{
+        recordedTs: number[];
+        recordedNext: number[];
+        recordedUuids: string[];
+        cache: LLMResponseCache;
+    }>;
+}
+/**
+ * Port for re-executing the agent with a virtualised context.
+ * The host provides a concrete implementation that wires the agent
+ * to the virtualised ClockPort, RandomPort, and LLMResponseCache.
+ *
+ * Extended contract (counterfactual support):
+ *   Implementations MAY inspect `(ctx as { strategyOverride?: string }).strategyOverride`
+ *   to swap their compute strategy for offline counterfactual analysis.
+ *   This field is injected exclusively by `replayCounterfactual` (offline tool) —
+ *   it is never present in production replay contexts.
+ */
+export interface ReplayRunner {
+    /**
+     * Re-execute the agent using ctx (virtual clock/random/cache)
+     * starting from the state described in originalTrace.
+     *
+     * Returns the new Trace produced by the replay.
+     *
+     * @param ctx           Virtualised execution context. When ctx carries a
+     *                      `strategyOverride` field (injected by replayCounterfactual),
+     *                      the implementation SHOULD honour it by swapping its
+     *                      compute strategy accordingly. This parameter is optional
+     *                      on the interface — existing implementations that do not
+     *                      inspect it remain fully compatible.
+     * @param originalTrace Original trace providing the starting state.
+     */
+    run(ctx: ReplayContext, originalTrace: Trace): Promise<Trace>;
+}
+/**
+ * Thrown when strict-mode replay detects a non-deterministic deviation
+ * that cannot be represented as a diff (e.g. step count mismatch, missing steps).
+ *
+ * For field-level mismatches, see ReplayResult.diff instead.
+ */
+export declare class NonDeterministicReplayError extends Error {
+    readonly stepIndex: number;
+    readonly reason: string;
+    constructor(stepIndex: number, reason: string);
+}
+/**
+ * Main replay entry point.
+ *
+ * 1. Loads the original trace and recorded artifacts via ReplayLoader.
+ * 2. Builds a ReplayContext with RecordedClock, RecordedRandom, and LLM cache.
+ * 3. Re-executes the agent via ReplayRunner.run().
+ * 4. Compares rootHashes and computes a step-level diff if they differ.
+ *
+ * @param runId   The original run identifier to replay.
+ * @param loader  Host-provided loader for trace + artifacts.
+ * @param runner  Host-provided runner that wires the agent to virtualised deps.
+ * @param opts    Optional overrides: replay mode, step index to replay from.
+ */
+export declare function replayFrom(runId: string, loader: ReplayLoader, runner: ReplayRunner, opts?: {
+    mode?: ReplayMode;
+    fromStepIndex?: number;
+}): Promise<ReplayResult>;
+//# sourceMappingURL=replay.d.ts.map

package/dist/replay/replay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay.d.ts","sourceRoot":"","sources":["../../src/replay/replay.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAIvD;;;;;;;GAOG;AACH,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,UAAU,CAAC;AAI/C;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,gDAAgD;IAChD,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B;;;OAGG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,wCAAwC;IACxC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,iEAAiE;IACjE,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,mEAAmE;IACnE,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,oEAAoE;IACpE,QAAQ,CAAC,KAAK,EAAE,gBAAgB,CAAC;CAClC;AAID;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,iCAAiC;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,4CAA4C;IAC5C,KAAK,EAAE,KAAK,CAAC;IACb;;;OAGG;IACH,KAAK,EAAE,OAAO,CAAC;IACf;;;OAGG;IACH,IAAI,CAAC,EAAE;QACL,SAAS,EAAE,MAAM,CAAC;QAClB,KAAK,EAAE,MAAM,SAAS,CAAC;QACvB,QAAQ,EAAE,OAAO,CAAC;QAClB,QAAQ,EAAE,OAAO,CAAC;KACnB,EAAE,CAAC;CACL;AAID;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;IAEjD;;;;;;OAMG;IACH,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;QACvC,UAAU,EAAE,MAAM,EAAE,CAAC;QACrB,YAAY,EAAE,MAAM,EAAE,CAAC;QACvB,aAAa,EAAE,MAAM,EAAE,CAAC;QACxB,KAAK,EAAE,gBAAgB,CAAC;KACzB,CAAC,CAAC;CACJ;AAID;;;;;;;;;;GAUG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;;;;;;;;;;OAaG;IACH,GAAG,CAAC,GAAG,EAAE,aAAa,EAAE,aAAa,EAAE,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;CAC/D;AAID;;;;;GAKG;AACH,qBAAa,2BAA4B,SAAQ,KAAK;aAElC,SAAS,EAAE,MAAM;aACjB,MAAM,EAAE,MAAM;gBADd,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM;CAKjC;AA2CD;;;;;;;;;;;;GAYG;AACH,wBAAsB,UAAU,CAC9B,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,YAAY,EACpB,MAAM,EAAE,YAAY,EACpB,IAAI,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,UAAU,CAAC;IAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAAE,GACnD,OAAO,CAAC,YAAY,CAAC,CA4CvB"}