@vauban-org/agent-sdk 0.16.0

package/dist/registry/agent-registry.js

@@ -0,0 +1,277 @@
+/**
+ * AgentRegistry — plugin registration API for Vauban agent descriptors.
+ *
+ * Phase 1: register/get/list with validation.
+ * Phase 2: discover() scans pnpm workspace packages for the
+ * "@vauban/agent-plugin" keyword, dynamically imports each one,
+ * and auto-registers its default export.
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import YAML from "yaml";
+// ─── Validation ───────────────────────────────────────────────────────────
+const AGENT_ID_REGEX = /^[a-z][a-z0-9-]{0,61}[a-z0-9]$|^[a-z]$/;
+const SEMVER_REGEX = /^\d+\.\d+\.\d+$/;
+function validateDescriptor(desc) {
+    if (!AGENT_ID_REGEX.test(desc.id)) {
+        throw new Error(`AgentRegistry: id "${desc.id}" must be kebab-case, 1-63 chars, starting with a letter`);
+    }
+    if (!SEMVER_REGEX.test(desc.version)) {
+        throw new Error(`AgentRegistry: version "${desc.version}" must be semver (e.g. "0.1.0")`);
+    }
+    if (desc.budget_monthly_usd < 0 ||
+        !Number.isFinite(desc.budget_monthly_usd)) {
+        throw new Error(`AgentRegistry: budget_monthly_usd for "${desc.id}" must be a non-negative finite number`);
+    }
+    if (typeof desc.handler !== "function") {
+        throw new Error(`AgentRegistry: handler for "${desc.id}" must be a function`);
+    }
+}
+// ─── Registry ─────────────────────────────────────────────────────────────
+export class AgentRegistry {
+    agents = new Map();
+    capabilities = new Map();
+    /**
+     * Register an agent descriptor. Validates the descriptor and throws on
+     * duplicate id or invalid fields.
+     */
+    register(desc) {
+        validateDescriptor(desc);
+        if (this.agents.has(desc.id)) {
+            throw new Error(`AgentRegistry: agent "${desc.id}" is already registered`);
+        }
+        this.agents.set(desc.id, { ...desc });
+    }
+    /** Get a registered agent by id. Returns undefined if not found. */
+    get(id) {
+        return this.agents.get(id);
+    }
+    /** List all registered agent descriptors. */
+    list() {
+        return Array.from(this.agents.values());
+    }
+    /** Number of registered agents. */
+    get size() {
+        return this.agents.size;
+    }
+    /**
+     * Unregister an agent by id. Returns true if removed, false if not found.
+     */
+    unregister(id) {
+        return this.agents.delete(id);
+    }
+    // ─── Multi-kind capability API ─────────────────────────────────────────
+    /**
+     * Register (or upsert) an AgentCapabilityCard keyed by agentId.
+     * Re-registering the same agentId replaces the previous card atomically.
+     */
+    registerCapability(card) {
+        this.capabilities.set(card.agentId, { ...card });
+    }
+    /**
+     * Return all capability cards whose `kind` matches the given value.
+     * Returns shallow copies — mutations do not affect registry state.
+     */
+    discoverByKind(kind) {
+        const result = [];
+        for (const card of this.capabilities.values()) {
+            if (card.kind === kind)
+                result.push({ ...card });
+        }
+        return result;
+    }
+    /**
+     * Return capability cards that match the given skill tags.
+     * Returns shallow copies — mutations do not affect registry state.
+     *
+     * @param skills - Tags to match against `card.skills` (lowercased by caller).
+     * @param opts.kind - Optional kind filter applied before skill matching.
+     * @param opts.matchAll - When true, ALL skills must be present (AND logic).
+     *   Defaults to false (OR logic: at least one skill matches).
+     */
+    discoverBySkills(skills, opts) {
+        const matchAll = opts?.matchAll ?? false;
+        const result = [];
+        for (const card of this.capabilities.values()) {
+            if (opts?.kind !== undefined && card.kind !== opts.kind)
+                continue;
+            const matched = matchAll
+                ? skills.every((s) => card.skills.includes(s))
+                : skills.some((s) => card.skills.includes(s));
+            if (matched)
+                result.push({ ...card });
+        }
+        return result;
+    }
+    /**
+     * Scan the pnpm workspace at `workspaceRoot` for packages whose
+     * `package.json` `keywords` array includes `"@vauban/agent-plugin"`,
+     * dynamically import each one, and register the default export
+     * (an `AgentDescriptor`).
+     *
+     * Idempotent: if a plugin is already registered, skips it silently.
+     * Malformed plugins (missing default export, non-descriptor shape)
+     * are skipped with a warning — discover() never throws.
+     *
+     * @param workspaceRoot  Absolute path to the workspace root containing pnpm-workspace.yaml.
+     * @returns The descriptors that were newly registered by this call.
+     */
+    async discover(workspaceRoot) {
+        const packageDirs = await resolveWorkspacePackageDirs(workspaceRoot);
+        const discovered = [];
+        for (const dir of packageDirs) {
+            const pkgJsonPath = path.join(dir, "package.json");
+            let pkgJsonRaw;
+            try {
+                pkgJsonRaw = await fs.readFile(pkgJsonPath, "utf-8");
+            }
+            catch {
+                continue;
+            }
+            let pkg;
+            try {
+                pkg = JSON.parse(pkgJsonRaw);
+            }
+            catch {
+                continue;
+            }
+            if (typeof pkg.name !== "string" ||
+                !Array.isArray(pkg.keywords) ||
+                !pkg.keywords.includes("@vauban/agent-plugin")) {
+                continue;
+            }
+            // Resolve the plugin's entry point. Prefer `exports["."]` (string
+            // form), fall back to `main`, then `index.js`. Dynamic import via
+            // file URL avoids bare-specifier resolution that may fail in test
+            // sandboxes that do not have the plugin symlinked into the caller's
+            // node_modules.
+            const entryRel = resolvePackageEntry(pkg);
+            const entryAbs = path.join(dir, entryRel);
+            let imported;
+            try {
+                imported = (await import(pathToFileURL(entryAbs).href));
+            }
+            catch (err) {
+                // eslint-disable-next-line no-console
+                console.warn(`[agent-registry] failed to import plugin "${pkg.name}": ${err instanceof Error ? err.message : String(err)}`);
+                continue;
+            }
+            const descriptor = imported.default;
+            if (!isAgentDescriptorShape(descriptor)) {
+                // eslint-disable-next-line no-console
+                console.warn(`[agent-registry] plugin "${pkg.name}" has no default export AgentDescriptor — skipping`);
+                continue;
+            }
+            if (this.agents.has(descriptor.id)) {
+                // Already registered (e.g. manual register() before discover()).
+                continue;
+            }
+            try {
+                this.register(descriptor);
+                discovered.push(descriptor);
+            }
+            catch (err) {
+                // eslint-disable-next-line no-console
+                console.warn(`[agent-registry] plugin "${pkg.name}" rejected by register(): ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        return discovered;
+    }
+}
+// ─── Helpers (unexported) ─────────────────────────────────────────────────
+/**
+ * Resolve the absolute directory of every package declared in the
+ * root `pnpm-workspace.yaml` globs. Glob patterns supported:
+ * literal path (`packages/foo`) and single-segment wildcard
+ * (`packages/*`, `apps/agents/*`).
+ */
+async function resolveWorkspacePackageDirs(workspaceRoot) {
+    const wsYamlPath = path.join(workspaceRoot, "pnpm-workspace.yaml");
+    let raw;
+    try {
+        raw = await fs.readFile(wsYamlPath, "utf-8");
+    }
+    catch {
+        return [];
+    }
+    let parsed;
+    try {
+        parsed = YAML.parse(raw);
+    }
+    catch {
+        return [];
+    }
+    if (typeof parsed !== "object" || parsed === null)
+        return [];
+    const wsCfg = parsed;
+    if (!Array.isArray(wsCfg.packages))
+        return [];
+    const dirs = [];
+    for (const pattern of wsCfg.packages) {
+        if (typeof pattern !== "string")
+            continue;
+        if (pattern.endsWith("/*")) {
+            const parent = path.join(workspaceRoot, pattern.slice(0, -2));
+            let entries;
+            try {
+                entries = await fs.readdir(parent);
+            }
+            catch {
+                continue;
+            }
+            for (const entry of entries) {
+                const full = path.join(parent, entry);
+                try {
+                    const stat = await fs.stat(full);
+                    if (stat.isDirectory())
+                        dirs.push(full);
+                }
+                catch {
+                    /* skip unreadable entries */
+                }
+            }
+        }
+        else {
+            dirs.push(path.join(workspaceRoot, pattern));
+        }
+    }
+    return dirs;
+}
+/**
+ * Pick the entry-point path declared in a package.json, using the
+ * precedence: exports["."] (string) > main > "index.js".
+ */
+function resolvePackageEntry(pkg) {
+    if (typeof pkg.exports === "string")
+        return pkg.exports;
+    if (typeof pkg.exports === "object" && pkg.exports !== null) {
+        const dot = pkg.exports["."];
+        if (typeof dot === "string")
+            return dot;
+        if (typeof dot === "object" && dot !== null) {
+            const candidate = dot.default ??
+                dot.import;
+            if (typeof candidate === "string")
+                return candidate;
+        }
+    }
+    if (typeof pkg.main === "string")
+        return pkg.main;
+    return "index.js";
+}
+/** Structural check: value is shaped like an AgentDescriptor. */
+function isAgentDescriptorShape(v) {
+    if (typeof v !== "object" || v === null)
+        return false;
+    const d = v;
+    return (typeof d.id === "string" &&
+        typeof d.version === "string" &&
+        (d.loop === "minimal" || d.loop === "sdk") &&
+        typeof d.budget_monthly_usd === "number" &&
+        typeof d.description === "string" &&
+        typeof d.handler === "function");
+}
+/** Default singleton registry for process-level use. */
+export const agentRegistry = new AgentRegistry();
+//# sourceMappingURL=agent-registry.js.map

package/dist/registry/agent-registry.js.map

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

package/dist/registry/index.d.ts

@@ -0,0 +1,7 @@
+export { AgentRegistry, agentRegistry } from "./agent-registry.js";
+export type { AgentDescriptor, AgentHandler, AgentContext, AgentResult, } from "./agent-registry.js";
+export { AGENT_IDS, AGENT_ID_NAMESPACE, getAgentId, agentFromId, } from "./agent-ids.js";
+export type { AgentType } from "./agent-ids.js";
+export { AGENT_KINDS } from "./agent-capability.js";
+export type { AgentKind, AgentCapabilityCard, CostTier, LatencyTier, } from "./agent-capability.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/registry/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACnE,YAAY,EACV,eAAe,EACf,YAAY,EACZ,YAAY,EACZ,WAAW,GACZ,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,SAAS,EACT,kBAAkB,EAClB,UAAU,EACV,WAAW,GACZ,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACpD,YAAY,EACV,SAAS,EACT,mBAAmB,EACnB,QAAQ,EACR,WAAW,GACZ,MAAM,uBAAuB,CAAC"}

package/dist/registry/index.js

@@ -0,0 +1,4 @@
+export { AgentRegistry, agentRegistry } from "./agent-registry.js";
+export { AGENT_IDS, AGENT_ID_NAMESPACE, getAgentId, agentFromId, } from "./agent-ids.js";
+export { AGENT_KINDS } from "./agent-capability.js";
+//# sourceMappingURL=index.js.map

package/dist/registry/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/registry/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAQnE,OAAO,EACL,SAAS,EACT,kBAAkB,EAClB,UAAU,EACV,WAAW,GACZ,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/replay/clock.d.ts

@@ -0,0 +1,69 @@
+/**
+ * ClockPort — virtualized wall-clock for deterministic replay.
+ *
+ * - RealClock: delegates to Date.now() for production use.
+ * - RecordedClock: replays a fixed sequence of timestamps from an original run.
+ *   Throws ClockExhaustedError when all recorded timestamps are consumed.
+ *
+ * Usage during replay:
+ *   const clock = new RecordedClock(originalRun.timestamps);
+ *   // Pass clock to the agent harness instead of RealClock.
+ *   // Every clock.now() call returns the next recorded value in order.
+ *
+ * @module replay/clock
+ */
+/**
+ * Abstract wall-clock port.
+ * Inject a concrete implementation into the agent harness at boot time.
+ */
+export interface ClockPort {
+    /** Returns the current time as Unix epoch milliseconds. */
+    now(): number;
+}
+/**
+ * Production implementation: delegates to Date.now().
+ * Non-deterministic by design — do NOT use during replay.
+ */
+export declare class RealClock implements ClockPort {
+    now(): number;
+}
+/**
+ * Thrown by RecordedClock when the cursor exceeds the recorded timestamps array.
+ * Signals that the replay agent made more clock calls than the original run —
+ * a sign of non-deterministic branching in the agent code.
+ */
+export declare class ClockExhaustedError extends Error {
+    constructor(recorded: number, requested: number);
+}
+/**
+ * Replay implementation: replays timestamps from an original run in order.
+ *
+ * Each call to now() returns the next recorded timestamp.
+ * Throws ClockExhaustedError if the replay makes more clock calls
+ * than were recorded in the original run.
+ *
+ * Thread safety: not thread-safe — single-agent use only.
+ */
+export declare class RecordedClock implements ClockPort {
+    private readonly recordedTs;
+    private cursor;
+    constructor(recordedTs: readonly number[]);
+    now(): number;
+    /** Returns the current cursor position (number of timestamps consumed). */
+    getCursor(): number;
+    /** Resets the cursor to zero so the same sequence can be replayed again. */
+    reset(): void;
+    /**
+     * Returns a new RecordedClock that shares the same underlying timestamp array
+     * and starts at the CURRENT cursor position. Advancing either clone or the
+     * original advances only its own cursor — the arrays are shared (read-only),
+     * but cursors are independent. Use for cross-cycle propagation where the child
+     * cycle consumes the NEXT timestamps in the same sequence.
+     *
+     * Clone invariant: clone.now() returns the same value as `this.now()` would
+     * at the moment clone() is called, and both consume subsequent timestamps
+     * in the same order from the same array.
+     */
+    clone(): RecordedClock;
+}
+//# sourceMappingURL=clock.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"clock.d.ts","sourceRoot":"","sources":["../../src/replay/clock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,2DAA2D;IAC3D,GAAG,IAAI,MAAM,CAAC;CACf;AAID;;;GAGG;AACH,qBAAa,SAAU,YAAW,SAAS;IACzC,GAAG,IAAI,MAAM;CAGd;AAID;;;;GAIG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;gBAChC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM;CAMhD;AAID;;;;;;;;GAQG;AACH,qBAAa,aAAc,YAAW,SAAS;IAGjC,OAAO,CAAC,QAAQ,CAAC,UAAU;IAFvC,OAAO,CAAC,MAAM,CAAK;gBAEU,UAAU,EAAE,SAAS,MAAM,EAAE;IAE1D,GAAG,IAAI,MAAM;IAOb,2EAA2E;IAC3E,SAAS,IAAI,MAAM;IAInB,4EAA4E;IAC5E,KAAK,IAAI,IAAI;IAIb;;;;;;;;;;OAUG;IACH,KAAK,IAAI,aAAa;CAKvB"}

package/dist/replay/clock.js

@@ -0,0 +1,84 @@
+/**
+ * ClockPort — virtualized wall-clock for deterministic replay.
+ *
+ * - RealClock: delegates to Date.now() for production use.
+ * - RecordedClock: replays a fixed sequence of timestamps from an original run.
+ *   Throws ClockExhaustedError when all recorded timestamps are consumed.
+ *
+ * Usage during replay:
+ *   const clock = new RecordedClock(originalRun.timestamps);
+ *   // Pass clock to the agent harness instead of RealClock.
+ *   // Every clock.now() call returns the next recorded value in order.
+ *
+ * @module replay/clock
+ */
+// ─── RealClock ────────────────────────────────────────────────────────────────
+/**
+ * Production implementation: delegates to Date.now().
+ * Non-deterministic by design — do NOT use during replay.
+ */
+export class RealClock {
+    now() {
+        return Date.now();
+    }
+}
+// ─── ClockExhaustedError ──────────────────────────────────────────────────────
+/**
+ * Thrown by RecordedClock when the cursor exceeds the recorded timestamps array.
+ * Signals that the replay agent made more clock calls than the original run —
+ * a sign of non-deterministic branching in the agent code.
+ */
+export class ClockExhaustedError extends Error {
+    constructor(recorded, requested) {
+        super(`Clock exhausted: ${recorded} timestamps recorded, ${requested + 1} requested`);
+        this.name = "ClockExhaustedError";
+    }
+}
+// ─── RecordedClock ────────────────────────────────────────────────────────────
+/**
+ * Replay implementation: replays timestamps from an original run in order.
+ *
+ * Each call to now() returns the next recorded timestamp.
+ * Throws ClockExhaustedError if the replay makes more clock calls
+ * than were recorded in the original run.
+ *
+ * Thread safety: not thread-safe — single-agent use only.
+ */
+export class RecordedClock {
+    recordedTs;
+    cursor = 0;
+    constructor(recordedTs) {
+        this.recordedTs = recordedTs;
+    }
+    now() {
+        if (this.cursor >= this.recordedTs.length) {
+            throw new ClockExhaustedError(this.recordedTs.length, this.cursor);
+        }
+        return this.recordedTs[this.cursor++];
+    }
+    /** Returns the current cursor position (number of timestamps consumed). */
+    getCursor() {
+        return this.cursor;
+    }
+    /** Resets the cursor to zero so the same sequence can be replayed again. */
+    reset() {
+        this.cursor = 0;
+    }
+    /**
+     * Returns a new RecordedClock that shares the same underlying timestamp array
+     * and starts at the CURRENT cursor position. Advancing either clone or the
+     * original advances only its own cursor — the arrays are shared (read-only),
+     * but cursors are independent. Use for cross-cycle propagation where the child
+     * cycle consumes the NEXT timestamps in the same sequence.
+     *
+     * Clone invariant: clone.now() returns the same value as `this.now()` would
+     * at the moment clone() is called, and both consume subsequent timestamps
+     * in the same order from the same array.
+     */
+    clone() {
+        const child = new RecordedClock(this.recordedTs);
+        child.cursor = this.cursor;
+        return child;
+    }
+}
+//# sourceMappingURL=clock.js.map

package/dist/replay/clock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clock.js","sourceRoot":"","sources":["../../src/replay/clock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAaH,iFAAiF;AAEjF;;;GAGG;AACH,MAAM,OAAO,SAAS;IACpB,GAAG;QACD,OAAO,IAAI,CAAC,GAAG,EAAE,CAAC;IACpB,CAAC;CACF;AAED,iFAAiF;AAEjF;;;;GAIG;AACH,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IAC5C,YAAY,QAAgB,EAAE,SAAiB;QAC7C,KAAK,CACH,oBAAoB,QAAQ,yBAAyB,SAAS,GAAG,CAAC,YAAY,CAC/E,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;IACpC,CAAC;CACF;AAED,iFAAiF;AAEjF;;;;;;;;GAQG;AACH,MAAM,OAAO,aAAa;IAGK;IAFrB,MAAM,GAAG,CAAC,CAAC;IAEnB,YAA6B,UAA6B;QAA7B,eAAU,GAAV,UAAU,CAAmB;IAAG,CAAC;IAE9D,GAAG;QACD,IAAI,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,UAAU,CAAC,MAAM,EAAE,CAAC;YAC1C,MAAM,IAAI,mBAAmB,CAAC,IAAI,CAAC,UAAU,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;QACrE,CAAC;QACD,OAAO,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;IACxC,CAAC;IAED,2EAA2E;IAC3E,SAAS;QACP,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED,4EAA4E;IAC5E,KAAK;QACH,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC;IAClB,CAAC;IAED;;;;;;;;;;OAUG;IACH,KAAK;QACH,MAAM,KAAK,GAAG,IAAI,aAAa,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QACjD,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC3B,OAAO,KAAK,CAAC;IACf,CAAC;CACF"}

package/dist/replay/cross-cycle.d.ts

@@ -0,0 +1,143 @@
+/**
+ * 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 type { ReplayMode, ReplayContext, ReplayLoader, ReplayRunner, ReplayResult } from "./replay.js";
+/**
+ * Extends ReplayContext with chain-ancestry metadata for cross-cycle replay.
+ *
+ * Chain invariant:
+ *   chainRootRunId is constant across all cycles in the chain.
+ *   chainDepth is 0 for the root cycle, 1 for direct children, etc.
+ *   parentRunId is undefined only for the root cycle (depth === 0).
+ */
+export interface ChainedReplayContext extends ReplayContext {
+    /**
+     * runId of the direct parent cycle.
+     * Undefined for the root cycle (chainDepth === 0).
+     */
+    readonly parentRunId?: string;
+    /**
+     * Zero-based depth in the spawning chain.
+     * Root cycle = 0. Each delegation increments by 1.
+     */
+    readonly chainDepth: number;
+    /**
+     * runId of the root (depth-0) cycle in this chain.
+     * Same for all cycles in a chain — used as the chain correlation key.
+     */
+    readonly chainRootRunId: string;
+}
+/**
+ * Summary of all cycles replayed in a chain.
+ * Used by callers to verify the full ancestry post-replay.
+ */
+export interface ChainCorrelation {
+    /** runId of the root (depth-0) cycle. */
+    rootRunId: string;
+    /** Each cycle entry in replay order (root first, deepest child last). */
+    chain: {
+        runId: string;
+        parentRunId?: string;
+        depth: number;
+        /** rootHash produced by this cycle's replay. */
+        rootHash: string;
+    }[];
+}
+/**
+ * Result of replaying an entire chain of N cycles.
+ *
+ * match === true iff ALL cycles in the chain matched their original rootHash.
+ * results contains individual ReplayResult per cycle (in chain order).
+ * correlation contains the ancestry summary.
+ */
+export interface ChainReplayResult {
+    /** True iff every cycle in the chain is byte-identical to its original. */
+    match: boolean;
+    /** Per-cycle replay results in chain order (root first). */
+    results: ReplayResult[];
+    /** Chain correlation summary. */
+    correlation: ChainCorrelation;
+}
+/**
+ * Thrown by replayChain when a non-root cycle references a parentRunId that
+ * is not present in the runIds list.
+ */
+export declare class MissingParentRunError extends Error {
+    readonly runId: string;
+    readonly parentRunId: string;
+    constructor(runId: string, parentRunId: string);
+}
+/**
+ * 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 declare function propagateContext(parentCtx: ChainedReplayContext, childRunId: string): ChainedReplayContext;
+/**
+ * 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 declare function replayChain(runIds: string[], loader: ReplayLoader, runner: ReplayRunner, opts?: {
+    mode?: ReplayMode;
+}): Promise<ChainReplayResult>;
+/**
+ * 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 declare function replayFromWithParent(runId: string, loader: ReplayLoader, runner: ReplayRunner, opts?: {
+    mode?: ReplayMode;
+    parentCtx?: ChainedReplayContext;
+}): Promise<ReplayResult>;
+//# sourceMappingURL=cross-cycle.d.ts.map

package/dist/replay/cross-cycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cross-cycle.d.ts","sourceRoot":"","sources":["../../src/replay/cross-cycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AASvG;;;;;;;GAOG;AACH,MAAM,WAAW,oBAAqB,SAAQ,aAAa;IACzD;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAE9B;;;OAGG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B;;;OAGG;IACH,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAID;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,yCAAyC;IACzC,SAAS,EAAE,MAAM,CAAC;IAClB,yEAAyE;IACzE,KAAK,EAAE;QACL,KAAK,EAAE,MAAM,CAAC;QACd,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,KAAK,EAAE,MAAM,CAAC;QACd,gDAAgD;QAChD,QAAQ,EAAE,MAAM,CAAC;KAClB,EAAE,CAAC;CACL;AAID;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC,2EAA2E;IAC3E,KAAK,EAAE,OAAO,CAAC;IACf,4DAA4D;IAC5D,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,iCAAiC;IACjC,WAAW,EAAE,gBAAgB,CAAC;CAC/B;AAID;;;GAGG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;aAClB,KAAK,EAAE,MAAM;aAAkB,WAAW,EAAE,MAAM;gBAAlD,KAAK,EAAE,MAAM,EAAkB,WAAW,EAAE,MAAM;CAQ/E;AAID;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,oBAAoB,EAC/B,UAAU,EAAE,MAAM,GACjB,oBAAoB,CAkCtB;AA2CD;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,MAAM,EAAE,EAChB,MAAM,EAAE,YAAY,EACpB,MAAM,EAAE,YAAY,EACpB,IAAI,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,UAAU,CAAA;CAAE,GAC3B,OAAO,CAAC,iBAAiB,CAAC,CA+F5B;AAsCD;;;;;;;;;;GAUG;AACH,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,YAAY,EACpB,MAAM,EAAE,YAAY,EACpB,IAAI,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,UAAU,CAAC;IAAC,SAAS,CAAC,EAAE,oBAAoB,CAAA;CAAE,GAC7D,OAAO,CAAC,YAAY,CAAC,CAmBvB"}