@vauban-org/agent-sdk 0.16.0

package/dist/replay/cross-cycle.js

@@ -0,0 +1,271 @@
+/**
+ * Cross-cycle replay propagation.
+ *
+ * When a parent cycle spawns a child cycle (via mesh.delegate or compute
+ * strategy), the child must inherit a deterministic-replay context that — on
+ * replay — reproduces the SAME outputs as the original chain.
+ *
+ * Design:
+ *   ChainedReplayContext extends ReplayContext with chain-ancestry metadata.
+ *   propagateContext() derives a child ctx from a parent ctx:
+ *     - Clock: cloned at the parent's current cursor position (child picks up
+ *       where parent left off — continuous, non-resetting).
+ *     - Random: cloned at the parent's current cursor positions.
+ *     - LLMCache: composite (withParent) — child looks up parent on miss,
+ *       writes disabled in replay mode.
+ *   replayChain() drives a multi-cycle chain replay end-to-end.
+ *
+ * Invariant:
+ *   A child cycle replayed with propagateContext(parentCtx, childRunId) produces
+ *   the same rootHash as the original child cycle IF AND ONLY IF the parent ctx
+ *   has consumed the same number of clock/random values that the original parent
+ *   had consumed at the point it spawned the child.
+ *
+ * @module replay/cross-cycle
+ */
+import { RecordedClock } from "./clock.js";
+import { RecordedRandom } from "./random.js";
+import { withParent } from "./llm-cache.js";
+import { replayFrom } from "./replay.js";
+// ─── MissingParentRunError ────────────────────────────────────────────────────
+/**
+ * Thrown by replayChain when a non-root cycle references a parentRunId that
+ * is not present in the runIds list.
+ */
+export class MissingParentRunError extends Error {
+    runId;
+    parentRunId;
+    constructor(runId, parentRunId) {
+        super(`Cross-cycle replay: cycle "${runId}" references parent "${parentRunId}" ` +
+            `which is not in the provided runIds list. ` +
+            `Ensure all cycles in the chain are loaded in order.`);
+        this.runId = runId;
+        this.parentRunId = parentRunId;
+        this.name = "MissingParentRunError";
+    }
+}
+// ─── propagateContext ─────────────────────────────────────────────────────────
+/**
+ * Derive a child ChainedReplayContext from a parent ChainedReplayContext.
+ *
+ * - clock: cloned at parent's current cursor position (child inherits NEXT timestamps).
+ * - random: cloned at parent's current cursor positions (continuous stream).
+ * - cache: composite cache — child looks up parent on miss, writes disabled.
+ * - chainDepth: parent.chainDepth + 1.
+ * - chainRootRunId: inherited unchanged from parent.
+ *
+ * IMPORTANT: call this AFTER the parent runner has finished executing (so the
+ * parent's clock/random cursors reflect all timestamps consumed during the
+ * parent cycle). If called mid-parent-execution the cursors will be wrong.
+ *
+ * @param parentCtx   The finished parent cycle's ChainedReplayContext.
+ * @param childRunId  The originalRunId of the child cycle being replayed.
+ */
+export function propagateContext(parentCtx, childRunId) {
+    // Obtain concrete RecordedClock/RecordedRandom for cloning.
+    // The parent ctx.clock/random are ClockPort/RandomPort interfaces; we must
+    // narrow them to the concrete recording types to call clone().
+    // If the caller provides a non-RecordedClock (e.g. RealClock) in a
+    // ChainedReplayContext, it is a mis-use — surface it clearly.
+    if (!(parentCtx.clock instanceof RecordedClock)) {
+        throw new TypeError("propagateContext: parentCtx.clock must be a RecordedClock instance. " +
+            "Chained replay requires virtualized clocks.");
+    }
+    if (!(parentCtx.random instanceof RecordedRandom)) {
+        throw new TypeError("propagateContext: parentCtx.random must be a RecordedRandom instance. " +
+            "Chained replay requires virtualized randoms.");
+    }
+    const childClock = parentCtx.clock.clone();
+    const childRandom = parentCtx.random.clone();
+    const childCache = withParent(parentCtx.cache, true);
+    return {
+        originalRunId: childRunId,
+        replayRunId: globalThis.crypto.randomUUID(),
+        mode: parentCtx.mode,
+        clock: childClock,
+        random: childRandom,
+        cache: childCache,
+        parentRunId: parentCtx.originalRunId,
+        chainDepth: parentCtx.chainDepth + 1,
+        chainRootRunId: parentCtx.chainRootRunId,
+    };
+}
+// ─── buildRootContext ─────────────────────────────────────────────────────────
+/**
+ * Build a root ChainedReplayContext (depth === 0, no parent).
+ * This is the equivalent of the per-cycle context built inside replayFrom,
+ * but typed as ChainedReplayContext so it can be passed to propagateContext.
+ */
+async function buildRootContext(rootRunId, loader, mode) {
+    const [originalTrace, artifacts] = await Promise.all([
+        loader.loadOriginalTrace(rootRunId),
+        loader.loadCacheEntries(rootRunId),
+    ]);
+    const clock = new RecordedClock(artifacts.recordedTs);
+    const random = new RecordedRandom(artifacts.recordedNext, artifacts.recordedUuids, mode);
+    const ctx = {
+        originalRunId: rootRunId,
+        replayRunId: globalThis.crypto.randomUUID(),
+        mode,
+        clock,
+        random,
+        cache: artifacts.cache,
+        parentRunId: undefined,
+        chainDepth: 0,
+        chainRootRunId: rootRunId,
+    };
+    return { ctx, originalTrace };
+}
+// ─── replayChain ──────────────────────────────────────────────────────────────
+/**
+ * Replay a chain of N cycles using shared virtualized dependencies.
+ *
+ * Cycles are replayed in the order provided by `runIds`. Each cycle after the
+ * first inherits its context from the preceding cycle via `propagateContext`.
+ *
+ * The chain structure is: runIds[0] is the root (depth 0), runIds[1] is its
+ * direct child (depth 1), etc. This matches linear delegation chains. For
+ * tree-shaped chains (one parent spawning multiple children) call replayChain
+ * once per branch.
+ *
+ * @param runIds   Ordered list of original runIds — root first.
+ * @param loader   Loader for traces + artifacts. Must be able to load all runIds.
+ * @param runner   Runner that executes each cycle with its virtualised context.
+ * @param opts     Optional mode override (default: "strict").
+ */
+export async function replayChain(runIds, loader, runner, opts) {
+    if (runIds.length === 0) {
+        throw new RangeError("replayChain: runIds must contain at least one runId.");
+    }
+    const mode = opts?.mode ?? "strict";
+    const results = [];
+    const correlationChain = [];
+    // Validate that all runIds are unique and non-empty
+    const seen = new Set();
+    for (const id of runIds) {
+        if (!id)
+            throw new RangeError("replayChain: runIds contains empty string.");
+        if (seen.has(id)) {
+            throw new RangeError(`replayChain: duplicate runId "${id}" in chain.`);
+        }
+        seen.add(id);
+    }
+    // Build root context
+    const rootRunId = runIds[0];
+    const { ctx: rootCtx, originalTrace: rootTrace } = await buildRootContext(rootRunId, loader, mode);
+    // Replay root cycle
+    const rootReplayTrace = await runner.run(rootCtx, rootTrace);
+    const rootMatch = rootTrace.rootHash === rootReplayTrace.rootHash;
+    const rootResult = {
+        replayRunId: rootCtx.replayRunId,
+        trace: rootReplayTrace,
+        match: rootMatch,
+        diff: rootMatch ? [] : computeDiff(rootTrace, rootReplayTrace),
+    };
+    results.push(rootResult);
+    correlationChain.push({
+        runId: rootRunId,
+        parentRunId: undefined,
+        depth: 0,
+        rootHash: rootReplayTrace.rootHash,
+    });
+    // Replay child cycles using propagated contexts
+    let prevCtx = rootCtx;
+    for (let i = 1; i < runIds.length; i++) {
+        const childRunId = runIds[i];
+        const parentRunId = runIds[i - 1];
+        // Validate parent is present in our tracked list (belt-and-suspenders)
+        const parentIdx = runIds.indexOf(parentRunId);
+        if (parentIdx === -1) {
+            throw new MissingParentRunError(childRunId, parentRunId);
+        }
+        // Load child's original trace + artifacts for the loader
+        // (propagateContext builds the ctx, but replayFrom also loads artifacts
+        // internally — we bypass replayFrom here to use the propagated ctx directly)
+        const [childOriginalTrace] = await Promise.all([
+            loader.loadOriginalTrace(childRunId),
+        ]);
+        const childCtx = propagateContext(prevCtx, childRunId);
+        const childReplayTrace = await runner.run(childCtx, childOriginalTrace);
+        const childMatch = childOriginalTrace.rootHash === childReplayTrace.rootHash;
+        results.push({
+            replayRunId: childCtx.replayRunId,
+            trace: childReplayTrace,
+            match: childMatch,
+            diff: childMatch ? [] : computeDiff(childOriginalTrace, childReplayTrace),
+        });
+        correlationChain.push({
+            runId: childRunId,
+            parentRunId,
+            depth: i,
+            rootHash: childReplayTrace.rootHash,
+        });
+        prevCtx = childCtx;
+    }
+    const allMatch = results.every((r) => r.match);
+    return {
+        match: allMatch,
+        results,
+        correlation: {
+            rootRunId,
+            chain: correlationChain,
+        },
+    };
+}
+// ─── Internal: computeDiff ────────────────────────────────────────────────────
+/**
+ * Minimal step-level diff (mirrors diffTraces from replay.ts — inlined to
+ * avoid circular import since replay.ts is not exported at module level).
+ */
+function computeDiff(original, replayed) {
+    const diffs = [];
+    const minLen = Math.min(original.steps.length, replayed.steps.length);
+    for (let i = 0; i < minLen; i++) {
+        const o = original.steps[i];
+        const r = replayed.steps[i];
+        for (const field of Object.keys(o)) {
+            if (JSON.stringify(o[field]) !== JSON.stringify(r[field])) {
+                diffs.push({ stepIndex: i, field, original: o[field], replayed: r[field] });
+            }
+        }
+    }
+    if (original.steps.length !== replayed.steps.length) {
+        diffs.push({
+            stepIndex: minLen,
+            field: "index",
+            original: original.steps.length,
+            replayed: replayed.steps.length,
+        });
+    }
+    return diffs;
+}
+// ─── Re-export replayFrom with optional parentCtx ────────────────────────────
+/**
+ * Extended replayFrom that accepts an optional parentCtx.
+ *
+ * When parentCtx is supplied, the child run inherits clock/random/cache from
+ * the parent via propagateContext instead of loading fresh artifacts.
+ * This enables replaying a single child cycle in isolation when the parent
+ * context is already available (e.g. for targeted debugging of a specific cycle).
+ *
+ * The loader is still called for the child's originalTrace.
+ * loadCacheEntries is skipped — the parent ctx provides the cache.
+ */
+export async function replayFromWithParent(runId, loader, runner, opts) {
+    if (!opts?.parentCtx) {
+        // Delegate to the standard single-cycle replayFrom
+        return replayFrom(runId, loader, runner, { mode: opts?.mode });
+    }
+    const parentCtx = opts.parentCtx;
+    const originalTrace = await loader.loadOriginalTrace(runId);
+    const childCtx = propagateContext(parentCtx, runId);
+    const replayTrace = await runner.run(childCtx, originalTrace);
+    const match = originalTrace.rootHash === replayTrace.rootHash;
+    return {
+        replayRunId: childCtx.replayRunId,
+        trace: replayTrace,
+        match,
+        diff: match ? [] : computeDiff(originalTrace, replayTrace),
+    };
+}
+//# sourceMappingURL=cross-cycle.js.map

package/dist/replay/cross-cycle.js.map

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

package/dist/replay/http-vcr.d.ts

@@ -0,0 +1,46 @@
+/**
+ * VCR HTTP cassettes — record/replay for replay-safe HTTP tools.
+ *
+ * Sprint-563: B9 — Node.js native HTTP recording (no nock dependency).
+ * Cassettes stored by hash(URL + method + body), served on strict replay.
+ *
+ * Mode 'record': store the real HTTP response for later replay.
+ * Mode 'replay': serve cassettes; throw on miss in strict mode.
+ */
+export type VCRMode = "record" | "replay";
+export interface VCRCassette {
+    url: string;
+    method: string;
+    requestBody: string | null;
+    status: number;
+    statusText: string;
+    headers: Record<string, string>;
+    body: string;
+    timestamp: number;
+}
+export interface VCRStats {
+    hits: number;
+    misses: number;
+    recorded: number;
+}
+export declare class UndeterministicSideEffectError extends Error {
+    constructor(url: string, method: string);
+}
+/**
+ * In-memory HTTP VCR for deterministic replay of HTTP side effects.
+ */
+export declare class HttpVCR {
+    private cassettes;
+    mode: VCRMode;
+    stats: VCRStats;
+    static key(url: string, method: string, body: string | null): string;
+    /** Record or replay an HTTP call. In record mode, captures the real response. */
+    intercept(url: string, method: string, body: string | null, realFetch: () => Promise<Response>): Promise<Response>;
+    /** Load cassettes from a previous recording (for replay mode). */
+    load(cassettes: VCRCassette[]): void;
+    /** Export all cassettes for storage. */
+    export(): VCRCassette[];
+    /** Clear all cassettes. */
+    clear(): void;
+}
+//# sourceMappingURL=http-vcr.d.ts.map

package/dist/replay/http-vcr.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-vcr.d.ts","sourceRoot":"","sources":["../../src/replay/http-vcr.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,MAAM,MAAM,OAAO,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE1C,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,qBAAa,8BAA+B,SAAQ,KAAK;gBAC3C,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAMxC;AAED;;GAEG;AACH,qBAAa,OAAO;IAClB,OAAO,CAAC,SAAS,CAAkC;IACnD,IAAI,EAAE,OAAO,CAAY;IACzB,KAAK,EAAE,QAAQ,CAAuC;IAEtD,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM;IAOpE,iFAAiF;IAC3E,SAAS,CACb,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,GAAG,IAAI,EACnB,SAAS,EAAE,MAAM,OAAO,CAAC,QAAQ,CAAC,GACjC,OAAO,CAAC,QAAQ,CAAC;IA4CpB,kEAAkE;IAClE,IAAI,CAAC,SAAS,EAAE,WAAW,EAAE,GAAG,IAAI;IAMpC,wCAAwC;IACxC,MAAM,IAAI,WAAW,EAAE;IAIvB,2BAA2B;IAC3B,KAAK,IAAI,IAAI;CAId"}

package/dist/replay/http-vcr.js

@@ -0,0 +1,87 @@
+/**
+ * VCR HTTP cassettes — record/replay for replay-safe HTTP tools.
+ *
+ * Sprint-563: B9 — Node.js native HTTP recording (no nock dependency).
+ * Cassettes stored by hash(URL + method + body), served on strict replay.
+ *
+ * Mode 'record': store the real HTTP response for later replay.
+ * Mode 'replay': serve cassettes; throw on miss in strict mode.
+ */
+import { createHash } from "node:crypto";
+export class UndeterministicSideEffectError extends Error {
+    constructor(url, method) {
+        super(`Replay mode (strict): HTTP ${method} ${url} has no cassette. Record first or use tolerant mode.`);
+        this.name = "UndeterministicSideEffectError";
+    }
+}
+/**
+ * In-memory HTTP VCR for deterministic replay of HTTP side effects.
+ */
+export class HttpVCR {
+    cassettes = new Map();
+    mode = "record";
+    stats = { hits: 0, misses: 0, recorded: 0 };
+    static key(url, method, body) {
+        const hash = createHash("sha256");
+        hash.update(`${method}:${url}`);
+        if (body)
+            hash.update(`:${body}`);
+        return hash.digest("hex");
+    }
+    /** Record or replay an HTTP call. In record mode, captures the real response. */
+    async intercept(url, method, body, realFetch) {
+        const key = HttpVCR.key(url, method, body);
+        if (this.mode === "replay") {
+            const cassette = this.cassettes.get(key);
+            if (cassette) {
+                this.stats.hits++;
+                return new Response(cassette.body, {
+                    status: cassette.status,
+                    statusText: cassette.statusText,
+                    headers: cassette.headers,
+                });
+            }
+            this.stats.misses++;
+            throw new UndeterministicSideEffectError(url, method);
+        }
+        // Record mode
+        const response = await realFetch();
+        const responseBody = await response.text();
+        const responseHeaders = {};
+        response.headers.forEach((v, k) => {
+            responseHeaders[k] = v;
+        });
+        this.cassettes.set(key, {
+            url,
+            method,
+            requestBody: body,
+            status: response.status,
+            statusText: response.statusText,
+            headers: responseHeaders,
+            body: responseBody,
+            timestamp: Date.now(),
+        });
+        this.stats.recorded++;
+        return new Response(responseBody, {
+            status: response.status,
+            statusText: response.statusText,
+            headers: responseHeaders,
+        });
+    }
+    /** Load cassettes from a previous recording (for replay mode). */
+    load(cassettes) {
+        for (const c of cassettes) {
+            this.cassettes.set(HttpVCR.key(c.url, c.method, c.requestBody), c);
+        }
+    }
+    /** Export all cassettes for storage. */
+    export() {
+        return [...this.cassettes.values()];
+    }
+    /** Clear all cassettes. */
+    clear() {
+        this.cassettes.clear();
+        this.stats = { hits: 0, misses: 0, recorded: 0 };
+    }
+}
+//# sourceMappingURL=http-vcr.js.map

package/dist/replay/http-vcr.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-vcr.js","sourceRoot":"","sources":["../../src/replay/http-vcr.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAqBzC,MAAM,OAAO,8BAA+B,SAAQ,KAAK;IACvD,YAAY,GAAW,EAAE,MAAc;QACrC,KAAK,CACH,8BAA8B,MAAM,IAAI,GAAG,sDAAsD,CAClG,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,gCAAgC,CAAC;IAC/C,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,OAAO;IACV,SAAS,GAAG,IAAI,GAAG,EAAuB,CAAC;IACnD,IAAI,GAAY,QAAQ,CAAC;IACzB,KAAK,GAAa,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC;IAEtD,MAAM,CAAC,GAAG,CAAC,GAAW,EAAE,MAAc,EAAE,IAAmB;QACzD,MAAM,IAAI,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC;QAClC,IAAI,CAAC,MAAM,CAAC,GAAG,MAAM,IAAI,GAAG,EAAE,CAAC,CAAC;QAChC,IAAI,IAAI;YAAE,IAAI,CAAC,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC;QAClC,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC5B,CAAC;IAED,iFAAiF;IACjF,KAAK,CAAC,SAAS,CACb,GAAW,EACX,MAAc,EACd,IAAmB,EACnB,SAAkC;QAElC,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC;QAE3C,IAAI,IAAI,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC3B,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACzC,IAAI,QAAQ,EAAE,CAAC;gBACb,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;gBAClB,OAAO,IAAI,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE;oBACjC,MAAM,EAAE,QAAQ,CAAC,MAAM;oBACvB,UAAU,EAAE,QAAQ,CAAC,UAAU;oBAC/B,OAAO,EAAE,QAAQ,CAAC,OAAO;iBAC1B,CAAC,CAAC;YACL,CAAC;YACD,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;YACpB,MAAM,IAAI,8BAA8B,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QACxD,CAAC;QAED,cAAc;QACd,MAAM,QAAQ,GAAG,MAAM,SAAS,EAAE,CAAC;QACnC,MAAM,YAAY,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;QAC3C,MAAM,eAAe,GAA2B,EAAE,CAAC;QACnD,QAAQ,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;YAChC,eAAe,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;QACzB,CAAC,CAAC,CAAC;QAEH,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,EAAE;YACtB,GAAG;YACH,MAAM;YACN,WAAW,EAAE,IAAI;YACjB,MAAM,EAAE,QAAQ,CAAC,MAAM;YACvB,UAAU,EAAE,QAAQ,CAAC,UAAU;YAC/B,OAAO,EAAE,eAAe;YACxB,IAAI,EAAE,YAAY;YAClB,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;SACtB,CAAC,CAAC;QACH,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC;QAEtB,OAAO,IAAI,QAAQ,CAAC,YAAY,EAAE;YAChC,MAAM,EAAE,QAAQ,CAAC,MAAM;YACvB,UAAU,EAAE,QAAQ,CAAC,UAAU;YAC/B,OAAO,EAAE,eAAe;SACzB,CAAC,CAAC;IACL,CAAC;IAED,kEAAkE;IAClE,IAAI,CAAC,SAAwB;QAC3B,KAAK,MAAM,CAAC,IAAI,SAAS,EAAE,CAAC;YAC1B,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,CAAC;QACrE,CAAC;IACH,CAAC;IAED,wCAAwC;IACxC,MAAM;QACJ,OAAO,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,CAAC,CAAC;IACtC,CAAC;IAED,2BAA2B;IAC3B,KAAK;QACH,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC;QACvB,IAAI,CAAC,KAAK,GAAG,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC;IACnD,CAAC;CACF"}

package/dist/replay/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @vauban-org/agent-sdk — Replay module public API.
+ *
+ * Exports all public types and implementations for deterministic replay.
+ *
+ * @module replay
+ */
+export { RealClock, RecordedClock, ClockExhaustedError, } from "./clock.js";
+export type { ClockPort } from "./clock.js";
+export { RealRandom, RecordedRandom, CryptoRandomDuringReplayError, } from "./random.js";
+export type { RandomPort } from "./random.js";
+export { InMemoryLLMResponseCache, CompositeLLMResponseCache, hashLLMCacheKey, withParent, } from "./llm-cache.js";
+export type { LLMCacheKey, LLMCacheEntry, LLMResponseCache, } from "./llm-cache.js";
+export { replayFrom, NonDeterministicReplayError, } from "./replay.js";
+export type { ReplayMode, ReplayContext, ReplayResult, ReplayLoader, ReplayRunner, } from "./replay.js";
+export { propagateContext, replayChain, replayFromWithParent, MissingParentRunError, } from "./cross-cycle.js";
+export type { ChainedReplayContext, ChainCorrelation, ChainReplayResult, } from "./cross-cycle.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/replay/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EACL,SAAS,EACT,aAAa,EACb,mBAAmB,GACpB,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAG5C,OAAO,EACL,UAAU,EACV,cAAc,EACd,6BAA6B,GAC9B,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAG9C,OAAO,EACL,wBAAwB,EACxB,yBAAyB,EACzB,eAAe,EACf,UAAU,GACX,MAAM,gBAAgB,CAAC;AACxB,YAAY,EACV,WAAW,EACX,aAAa,EACb,gBAAgB,GACjB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EACL,UAAU,EACV,2BAA2B,GAC5B,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,UAAU,EACV,aAAa,EACb,YAAY,EACZ,YAAY,EACZ,YAAY,GACb,MAAM,aAAa,CAAC;AAGrB,OAAO,EACL,gBAAgB,EAChB,WAAW,EACX,oBAAoB,EACpB,qBAAqB,GACtB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EACV,oBAAoB,EACpB,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,kBAAkB,CAAC"}

package/dist/replay/index.js

@@ -0,0 +1,18 @@
+/**
+ * @vauban-org/agent-sdk — Replay module public API.
+ *
+ * Exports all public types and implementations for deterministic replay.
+ *
+ * @module replay
+ */
+// Clock virtualization
+export { RealClock, RecordedClock, ClockExhaustedError, } from "./clock.js";
+// Random virtualization (CH4 dual API)
+export { RealRandom, RecordedRandom, CryptoRandomDuringReplayError, } from "./random.js";
+// LLM response cache
+export { InMemoryLLMResponseCache, CompositeLLMResponseCache, hashLLMCacheKey, withParent, } from "./llm-cache.js";
+// Replay orchestration
+export { replayFrom, NonDeterministicReplayError, } from "./replay.js";
+// Cross-cycle propagation
+export { propagateContext, replayChain, replayFromWithParent, MissingParentRunError, } from "./cross-cycle.js";
+//# sourceMappingURL=index.js.map

package/dist/replay/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/replay/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,uBAAuB;AACvB,OAAO,EACL,SAAS,EACT,aAAa,EACb,mBAAmB,GACpB,MAAM,YAAY,CAAC;AAGpB,uCAAuC;AACvC,OAAO,EACL,UAAU,EACV,cAAc,EACd,6BAA6B,GAC9B,MAAM,aAAa,CAAC;AAGrB,qBAAqB;AACrB,OAAO,EACL,wBAAwB,EACxB,yBAAyB,EACzB,eAAe,EACf,UAAU,GACX,MAAM,gBAAgB,CAAC;AAOxB,uBAAuB;AACvB,OAAO,EACL,UAAU,EACV,2BAA2B,GAC5B,MAAM,aAAa,CAAC;AASrB,0BAA0B;AAC1B,OAAO,EACL,gBAAgB,EAChB,WAAW,EACX,oBAAoB,EACpB,qBAAqB,GACtB,MAAM,kBAAkB,CAAC"}

package/dist/replay/llm-cache.d.ts

@@ -0,0 +1,126 @@
+/**
+ * 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
+ */
+/**
+ * Canonical key for an LLM response cache entry.
+ * All fields are included in the SHA-256 hash — changing any field
+ * produces a different cache key (cache miss).
+ */
+export interface LLMCacheKey {
+    /** LLM provider identifier (e.g. "openai", "groq", "anthropic"). */
+    provider: string;
+    /** Model identifier (e.g. "gpt-4o", "llama-3.3-70b"). */
+    model: string;
+    /**
+     * Message array passed to the LLM. Array order matters: a different
+     * ordering of the same messages will produce a different hash.
+     */
+    messages: unknown;
+    /** Sampling temperature. Included in key — same prompt at different temps yields different responses. */
+    temperature: number;
+    /**
+     * Optional provider-side seed for deterministic sampling.
+     * When present, influences the cache key to distinguish seeded from unseeded calls.
+     */
+    seed?: number;
+}
+/**
+ * A single cache entry: the hash key, the stored response, and when it was recorded.
+ */
+export interface LLMCacheEntry {
+    /** SHA-256(canonical(LLMCacheKey)) — hex-encoded. */
+    key: string;
+    /** Full serialized response payload from the LLM provider. */
+    response: unknown;
+    /** Unix epoch milliseconds when this entry was recorded. */
+    recordedAt: number;
+}
+/**
+ * Content-addressed store for LLM responses.
+ *
+ * Implementations:
+ *   - InMemoryLLMResponseCache (this module) — for tests and dev.
+ *   - PostgreSQL adapter (B-series tasks) — for production replay.
+ */
+export interface LLMResponseCache {
+    /**
+     * Look up a cached response for the given key.
+     * Returns undefined on a cache miss.
+     */
+    get(key: LLMCacheKey): Promise<LLMCacheEntry | undefined>;
+    /**
+     * Store a response for the given key.
+     * Overwrites any existing entry with the same hash.
+     */
+    put(key: LLMCacheKey, response: unknown): Promise<void>;
+    /**
+     * Test helper: wipe the entire in-memory store.
+     * Optional — production adapters may omit this.
+     */
+    clear?(): void;
+}
+/**
+ * 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 declare function hashLLMCacheKey(key: LLMCacheKey): Promise<string>;
+/**
+ * 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 declare class InMemoryLLMResponseCache implements LLMResponseCache {
+    private readonly store;
+    get(key: LLMCacheKey): Promise<LLMCacheEntry | undefined>;
+    put(key: LLMCacheKey, response: unknown): Promise<void>;
+    clear(): void;
+}
+/**
+ * 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 declare class CompositeLLMResponseCache implements LLMResponseCache {
+    private readonly child;
+    private readonly parent;
+    private readonly readOnly;
+    constructor(child: LLMResponseCache, parent: LLMResponseCache, readOnly?: boolean);
+    get(key: LLMCacheKey): Promise<LLMCacheEntry | undefined>;
+    put(key: LLMCacheKey, response: unknown): Promise<void>;
+    clear(): void;
+}
+/**
+ * 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 declare function withParent(parentCache: LLMResponseCache, readOnly?: boolean): LLMResponseCache;
+//# sourceMappingURL=llm-cache.d.ts.map

package/dist/replay/llm-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm-cache.d.ts","sourceRoot":"","sources":["../../src/replay/llm-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAMH;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,oEAAoE;IACpE,QAAQ,EAAE,MAAM,CAAC;IACjB,yDAAyD;IACzD,KAAK,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,QAAQ,EAAE,OAAO,CAAC;IAClB,yGAAyG;IACzG,WAAW,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAID;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,qDAAqD;IACrD,GAAG,EAAE,MAAM,CAAC;IACZ,8DAA8D;IAC9D,QAAQ,EAAE,OAAO,CAAC;IAClB,4DAA4D;IAC5D,UAAU,EAAE,MAAM,CAAC;CACpB;AAID;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,GAAG,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CAAC;IAE1D;;;OAGG;IACH,GAAG,CAAC,GAAG,EAAE,WAAW,EAAE,QAAQ,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAExD;;;OAGG;IACH,KAAK,CAAC,IAAI,IAAI,CAAC;CAChB;AAID;;;;;;;;GAQG;AACH,wBAAsB,eAAe,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAKvE;AAUD;;;;;;;;;GASG;AACH,qBAAa,wBAAyB,YAAW,gBAAgB;IAC/D,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAoC;IAEpD,GAAG,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC;IAKzD,GAAG,CAAC,GAAG,EAAE,WAAW,EAAE,QAAQ,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAS7D,KAAK,IAAI,IAAI;CAGd;AAID;;;;;;;;;GASG;AACH,qBAAa,yBAA0B,YAAW,gBAAgB;IAE9D,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBAFR,KAAK,EAAE,gBAAgB,EACvB,MAAM,EAAE,gBAAgB,EACxB,QAAQ,GAAE,OAAe;IAGtC,GAAG,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC;IAOzD,GAAG,CAAC,GAAG,EAAE,WAAW,EAAE,QAAQ,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAK7D,KAAK,IAAI,IAAI;CAKd;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CACxB,WAAW,EAAE,gBAAgB,EAC7B,QAAQ,UAAO,GACd,gBAAgB,CAMlB"}