@pellux/goodvibes-sdk 0.18.3 → 0.18.12

package/dist/_internal/platform/core/adaptive-planner.js

@@ -0,0 +1,288 @@
+/**
+ * Adaptive Execution Planner.
+ *
+ * Scores and selects execution strategies based on risk, latency, and
+ * capability inputs. Emits typed reason codes for every decision and
+ * maintains an explicit override path that is logged in full.
+ *
+ * Commands: /plan mode auto|single|cohort|background|remote
+ *           /plan explain
+ *           /plan override <strategy>
+ */
+import { logger } from '../utils/logger.js';
+/** All valid strategy names (including 'auto'). Exported for use in command handlers. */
+export const VALID_STRATEGIES = ['auto', 'single', 'cohort', 'background', 'remote'];
+// ---------------------------------------------------------------------------
+// Reason code explanations
+// ---------------------------------------------------------------------------
+const REASON_EXPLANATIONS = {
+    OVERRIDE_IN_EFFECT: 'A user-supplied /plan override is in effect. The planner\'s automatic '
+        + 'selection is bypassed until the override is cleared.',
+    HIGH_RISK_SINGLE_PREFERRED: 'The task risk score exceeds the threshold for parallel execution (>0.7). '
+        + 'Single-agent execution is preferred to limit blast radius.',
+    LOW_LATENCY_SINGLE: 'The latency budget is tight (<5 s). Single-call execution avoids '
+        + 'coordination overhead.',
+    COHORT_CAPABLE: 'The task is classified as multi-step and the risk score is low enough '
+        + 'for coordinated agent fan-out.',
+    BACKGROUND_DEFERRED: 'The task is eligible for background execution: no latency constraint '
+        + 'and backgroundEligible is true.',
+    REMOTE_CAPABLE: 'A remote agent endpoint is available and the task is not high risk.',
+    AUTO_FALLBACK_SINGLE: 'Auto mode found no strong signal for parallelism; defaulting to single.',
+    USER_OVERRIDE: 'The strategy was set explicitly by the user via /plan override.',
+    FLAG_DISABLED: 'The adaptive-execution-planner feature flag is disabled; using single.',
+    INVALID_STRATEGY: 'The supplied strategy name is not recognised. No change was made.',
+};
+// ---------------------------------------------------------------------------
+// Scorer
+// ---------------------------------------------------------------------------
+/**
+ * Score a single strategy candidate given the current planner inputs.
+ *
+ * Returns a numeric score (0-100, higher = preferred) and the primary reason
+ * code that drove the score.
+ */
+function scoreStrategy(strategy, inputs) {
+    const { riskScore, latencyBudgetMs, isMultiStep, remoteAvailable, backgroundEligible, } = inputs;
+    switch (strategy) {
+        case 'single': {
+            // Preferred when risk is high or latency budget is tight
+            let s = 50;
+            if (riskScore > 0.7)
+                s += 30;
+            if (latencyBudgetMs < 5_000)
+                s += 20;
+            if (!isMultiStep)
+                s += 10;
+            const reasonCode = riskScore > 0.7
+                ? 'HIGH_RISK_SINGLE_PREFERRED'
+                : latencyBudgetMs < 5_000
+                    ? 'LOW_LATENCY_SINGLE'
+                    : 'AUTO_FALLBACK_SINGLE';
+            return { score: Math.min(s, 100), reasonCode };
+        }
+        case 'cohort': {
+            // Good when multi-step and low risk
+            if (!isMultiStep)
+                return { score: 0, reasonCode: 'AUTO_FALLBACK_SINGLE' };
+            if (riskScore > 0.7)
+                return { score: 5, reasonCode: 'HIGH_RISK_SINGLE_PREFERRED' };
+            const s = 70 + (1 - riskScore) * 20;
+            return { score: Math.min(s, 100), reasonCode: 'COHORT_CAPABLE' };
+        }
+        case 'background': {
+            if (!backgroundEligible)
+                return { score: 0, reasonCode: 'AUTO_FALLBACK_SINGLE' };
+            if (riskScore > 0.6)
+                return { score: 10, reasonCode: 'HIGH_RISK_SINGLE_PREFERRED' };
+            const s = 60 + (latencyBudgetMs === Infinity ? 20 : 0);
+            return { score: Math.min(s, 100), reasonCode: 'BACKGROUND_DEFERRED' };
+        }
+        case 'remote': {
+            if (!remoteAvailable)
+                return { score: 0, reasonCode: 'AUTO_FALLBACK_SINGLE' };
+            if (riskScore > 0.7)
+                return { score: 5, reasonCode: 'HIGH_RISK_SINGLE_PREFERRED' };
+            const s = 65 + (1 - riskScore) * 15;
+            return { score: Math.min(s, 100), reasonCode: 'REMOTE_CAPABLE' };
+        }
+        case 'auto':
+            // 'auto' itself is not scored as a candidate — it triggers evaluation of others
+            return { score: -1, reasonCode: 'AUTO_FALLBACK_SINGLE' };
+    }
+}
+// ---------------------------------------------------------------------------
+// AdaptivePlanner
+// ---------------------------------------------------------------------------
+export class AdaptivePlanner {
+    /** Current user override, or null when the planner runs freely. */
+    overrideStrategy = null;
+    /** Current operating mode (default: auto). */
+    mode = 'auto';
+    /** Audit log of all decisions, capped at MAX_HISTORY entries. */
+    history = [];
+    static MAX_HISTORY = 100;
+    // -------------------------------------------------------------------------
+    // Public API
+    // -------------------------------------------------------------------------
+    /**
+     * Select the best execution strategy for the given inputs.
+     *
+     * - If a user override is active, it is returned immediately with reason
+     *   `OVERRIDE_IN_EFFECT`.
+     * - If mode is not `auto`, the mode itself is returned (as a pinned choice).
+     * - Otherwise all concrete strategies are scored and the highest wins.
+     *
+     * The decision is appended to the history log.
+     */
+    select(inputs) {
+        const validated = this._validateInputs(inputs);
+        const ts = Date.now();
+        // Use validated inputs from here on
+        // eslint-disable-next-line no-param-reassign
+        inputs = validated;
+        // User override takes absolute precedence
+        if (this.overrideStrategy !== null) {
+            const decision = {
+                selected: this.overrideStrategy,
+                reasonCode: 'OVERRIDE_IN_EFFECT',
+                candidates: [{ strategy: this.overrideStrategy, score: 100, reasonCode: 'USER_OVERRIDE' }],
+                overrideActive: true,
+                timestamp: ts,
+                inputs,
+            };
+            this._appendHistory(decision);
+            logger.debug('[AdaptivePlanner] override in effect', { strategy: this.overrideStrategy });
+            return decision;
+        }
+        // Pinned mode (not auto)
+        if (this.mode !== 'auto') {
+            const { score, reasonCode } = scoreStrategy(this.mode, inputs);
+            const decision = {
+                selected: this.mode,
+                reasonCode,
+                candidates: [{ strategy: this.mode, score, reasonCode }],
+                overrideActive: false,
+                timestamp: ts,
+                inputs,
+            };
+            this._appendHistory(decision);
+            return decision;
+        }
+        // Auto: score all concrete strategies
+        const candidates = ['single', 'cohort', 'background', 'remote']
+            .map((s) => {
+            const { score, reasonCode } = scoreStrategy(s, inputs);
+            return { strategy: s, score, reasonCode };
+        })
+            .sort((a, b) => b.score - a.score);
+        const best = candidates[0];
+        const decision = {
+            selected: best.strategy,
+            reasonCode: best.reasonCode,
+            candidates,
+            overrideActive: false,
+            timestamp: ts,
+            inputs,
+        };
+        this._appendHistory(decision);
+        logger.debug('[AdaptivePlanner] auto-selected', {
+            strategy: best.strategy,
+            reasonCode: best.reasonCode,
+            score: best.score,
+        });
+        return decision;
+    }
+    /**
+     * Set the operating mode for future calls to `select()`.
+     *
+     * Setting to `'auto'` clears any pinned mode (but does NOT clear a user
+     * override — use `clearOverride()` for that).
+     */
+    setMode(mode) {
+        this.mode = mode;
+        logger.info('[AdaptivePlanner] mode set', { mode });
+    }
+    /** Get the current operating mode. */
+    getMode() {
+        return this.mode;
+    }
+    /**
+     * Apply an explicit user override. Overrides are stronger than mode: even
+     * in `auto` mode the override strategy is always returned until cleared.
+     *
+     * Returns `false` with reason `INVALID_STRATEGY` if the strategy name is
+     * not recognised.
+     */
+    override(strategy) {
+        if (!VALID_STRATEGIES.includes(strategy)) {
+            logger.warn('[AdaptivePlanner] invalid override strategy', { strategy });
+            return { ok: false, reasonCode: 'INVALID_STRATEGY' };
+        }
+        const s = strategy;
+        this.overrideStrategy = s === 'auto' ? null : s;
+        logger.info('[AdaptivePlanner] user override applied', { strategy: s });
+        return { ok: true, strategy: s };
+    }
+    /** Clear any active user override. */
+    clearOverride() {
+        this.overrideStrategy = null;
+        logger.info('[AdaptivePlanner] user override cleared');
+    }
+    /** Whether a user override is currently active. */
+    hasOverride() {
+        return this.overrideStrategy !== null;
+    }
+    /** Return the active override strategy, or null. */
+    getOverride() {
+        return this.overrideStrategy;
+    }
+    /**
+     * Return a human-readable explanation of the most recent decision, or of
+     * a specific reason code.
+     */
+    explain(reasonCode) {
+        if (reasonCode) {
+            return REASON_EXPLANATIONS[reasonCode] ?? `Unknown reason code: ${reasonCode}`;
+        }
+        const last = this.history[this.history.length - 1];
+        if (!last)
+            return 'No decisions have been made yet.';
+        return this._formatDecisionExplanation(last);
+    }
+    /** Return the full static explanation for a reason code. */
+    static explainReasonCode(code) {
+        return REASON_EXPLANATIONS[code] ?? `Unknown reason code: ${code}`;
+    }
+    /** Return the N most recent decisions (default: 20). */
+    getHistory(limit = 20) {
+        return this.history.slice(-limit);
+    }
+    /** Return the most recent decision, or null. */
+    getLatest() {
+        return this.history[this.history.length - 1] ?? null;
+    }
+    // -------------------------------------------------------------------------
+    // Private helpers
+    // -------------------------------------------------------------------------
+    /**
+     * Validate and clamp PlannerInputs to safe ranges.
+     * Logs a debug warning if any value is out of range.
+     */
+    _validateInputs(inputs) {
+        const out = { ...inputs };
+        if (isNaN(out.riskScore) || out.riskScore < 0 || out.riskScore > 1) {
+            logger.debug('[AdaptivePlanner] riskScore out of range, clamping', { riskScore: out.riskScore });
+            out.riskScore = isNaN(out.riskScore) ? 0 : Math.max(0, Math.min(1, out.riskScore));
+        }
+        if (out.latencyBudgetMs < 0) {
+            logger.debug('[AdaptivePlanner] latencyBudgetMs negative, clamping to 0', { latencyBudgetMs: out.latencyBudgetMs });
+            out.latencyBudgetMs = 0;
+        }
+        return out;
+    }
+    _appendHistory(decision) {
+        this.history.push(decision);
+        if (this.history.length > AdaptivePlanner.MAX_HISTORY) {
+            this.history.shift();
+        }
+    }
+    _formatDecisionExplanation(decision) {
+        const ts = new Date(decision.timestamp).toISOString();
+        const override = decision.overrideActive ? ' [USER OVERRIDE]' : '';
+        const lines = [
+            `Strategy: ${decision.selected.toUpperCase()}${override}`,
+            `Reason:   ${decision.reasonCode}`,
+            `          ${REASON_EXPLANATIONS[decision.reasonCode]}`,
+            `At:       ${ts}`,
+            '',
+            'Candidate rankings:',
+            ...decision.candidates.map((c) => `  ${String(c.score).padStart(3)}  ${c.strategy.padEnd(12)} ${c.reasonCode}`),
+        ];
+        const inputs = decision.inputs;
+        lines.push('', 'Inputs:', `  riskScore:         ${inputs.riskScore.toFixed(2)}`, `  latencyBudgetMs:   ${inputs.latencyBudgetMs === Infinity ? '∞' : inputs.latencyBudgetMs}`, `  isMultiStep:       ${inputs.isMultiStep}`, `  remoteAvailable:   ${inputs.remoteAvailable}`, `  backgroundEligible: ${inputs.backgroundEligible}`);
+        if (inputs.taskDescription) {
+            lines.push(`  task:              ${inputs.taskDescription.slice(0, 80)}`);
+        }
+        return lines.join('\n');
+    }
+}

package/dist/_internal/platform/core/circuit-breaker.d.ts

@@ -0,0 +1,19 @@
+/** SDK-owned platform module. This implementation is maintained in goodvibes-sdk. */
+/**
+ * Shared circuit breaker for consecutive all-error turn detection.
+ *
+ * These thresholds are intentionally fixed constants for now.
+ * Thresholds are hardcoded; could be made configurable via configManager in the future.
+ */
+export declare const CONSECUTIVE_ERROR_WARN = 5;
+export declare const CONSECUTIVE_ERROR_BREAK = 10;
+export declare class ConsecutiveErrorBreaker {
+    private count;
+    /** Record an all-failed turn. Returns 'warn' at WARN threshold, 'break' at BREAK threshold, 'ok' otherwise. */
+    recordAllFailed(): 'ok' | 'warn' | 'break';
+    /** Reset counter on any success. */
+    recordSuccess(): void;
+    /** Current consecutive error count. */
+    get consecutiveErrors(): number;
+}
+//# sourceMappingURL=circuit-breaker.d.ts.map

package/dist/_internal/platform/core/circuit-breaker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"circuit-breaker.d.ts","sourceRoot":"","sources":["../../../../src/_internal/platform/core/circuit-breaker.ts"],"names":[],"mappings":"AAAA,qFAAqF;AAErF;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,IAAI,CAAC;AACxC,eAAO,MAAM,uBAAuB,KAAK,CAAC;AAE1C,qBAAa,uBAAuB;IAClC,OAAO,CAAC,KAAK,CAAK;IAElB,+GAA+G;IAC/G,eAAe,IAAI,IAAI,GAAG,MAAM,GAAG,OAAO;IAQ1C,oCAAoC;IACpC,aAAa,IAAI,IAAI;IAErB,uCAAuC;IACvC,IAAI,iBAAiB,IAAI,MAAM,CAAuB;CACvD"}

package/dist/_internal/platform/core/circuit-breaker.js

@@ -0,0 +1,26 @@
+/** SDK-owned platform module. This implementation is maintained in goodvibes-sdk. */
+/**
+ * Shared circuit breaker for consecutive all-error turn detection.
+ *
+ * These thresholds are intentionally fixed constants for now.
+ * Thresholds are hardcoded; could be made configurable via configManager in the future.
+ */
+export const CONSECUTIVE_ERROR_WARN = 5;
+export const CONSECUTIVE_ERROR_BREAK = 10;
+export class ConsecutiveErrorBreaker {
+    count = 0;
+    /** Record an all-failed turn. Returns 'warn' at WARN threshold, 'break' at BREAK threshold, 'ok' otherwise. */
+    recordAllFailed() {
+        this.count++;
+        this.count = Math.min(this.count, CONSECUTIVE_ERROR_BREAK);
+        if (this.count >= CONSECUTIVE_ERROR_BREAK)
+            return 'break';
+        if (this.count >= CONSECUTIVE_ERROR_WARN)
+            return 'warn';
+        return 'ok';
+    }
+    /** Reset counter on any success. */
+    recordSuccess() { this.count = 0; }
+    /** Current consecutive error count. */
+    get consecutiveErrors() { return this.count; }
+}

package/dist/_internal/platform/core/conversation-follow-ups.d.ts

@@ -0,0 +1,8 @@
+/** SDK-owned platform module. This implementation is maintained in goodvibes-sdk. */
+export interface ConversationFollowUpItem {
+    readonly key: string;
+    readonly summary: string;
+}
+export declare function normalizeConversationFollowUpItems(items: readonly ConversationFollowUpItem[]): ConversationFollowUpItem[];
+export declare function buildConversationFollowUpPrompt(items: readonly ConversationFollowUpItem[]): string;
+//# sourceMappingURL=conversation-follow-ups.d.ts.map

package/dist/_internal/platform/core/conversation-follow-ups.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversation-follow-ups.d.ts","sourceRoot":"","sources":["../../../../src/_internal/platform/core/conversation-follow-ups.ts"],"names":[],"mappings":"AAAA,qFAAqF;AAErF,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAWD,wBAAgB,kCAAkC,CAChD,KAAK,EAAE,SAAS,wBAAwB,EAAE,GACzC,wBAAwB,EAAE,CAQ5B;AAED,wBAAgB,+BAA+B,CAC7C,KAAK,EAAE,SAAS,wBAAwB,EAAE,GACzC,MAAM,CAaR"}

package/dist/_internal/platform/core/conversation-follow-ups.js

@@ -0,0 +1,33 @@
+/** SDK-owned platform module. This implementation is maintained in goodvibes-sdk. */
+const MAX_BATCH_SIZE = 6;
+const MAX_SUMMARY_LENGTH = 240;
+function normalizeSummary(summary) {
+    const compact = summary.replace(/\s+/g, ' ').trim();
+    if (compact.length <= MAX_SUMMARY_LENGTH)
+        return compact;
+    return `${compact.slice(0, MAX_SUMMARY_LENGTH - 1)}…`;
+}
+export function normalizeConversationFollowUpItems(items) {
+    const deduped = new Map();
+    for (const item of items) {
+        const summary = normalizeSummary(item.summary);
+        if (!summary)
+            continue;
+        deduped.set(item.key, { key: item.key, summary });
+    }
+    return [...deduped.values()].slice(0, MAX_BATCH_SIZE);
+}
+export function buildConversationFollowUpPrompt(items) {
+    const normalized = normalizeConversationFollowUpItems(items);
+    const bullets = normalized.map((item, index) => `${index + 1}. ${item.summary}`);
+    return [
+        'Background milestones completed since your last reply:',
+        ...bullets,
+        '',
+        'Write 1-2 short sentences for the user acknowledging the update.',
+        'Do not ask questions.',
+        'Do not mention internal routing, follow-ups, or hidden notifications.',
+        'Do not call tools.',
+        'Be concise and factual.',
+    ].join('\n');
+}

package/dist/_internal/platform/core/deterministic-replay.d.ts

@@ -0,0 +1,201 @@
+import type { LedgerEntry } from '../runtime/telemetry/exporters/local-ledger.js';
+import type { RuntimeStateSnapshot } from '../runtime/diagnostics/types.js';
+/**
+ * Category of a mismatch between expected and replayed state.
+ *
+ * - `missing_event`    : an event expected at this revision was absent.
+ * - `extra_event`      : an event appeared that was not in the recording.
+ * - `payload_mismatch` : event name matched but payload differed.
+ * - `ordering`         : events arrived in different order than recorded.
+ * - `state_divergence` : domain state diverged after applying event.
+ */
+export type MismatchClass = 'missing_event' | 'extra_event' | 'payload_mismatch' | 'ordering' | 'state_divergence';
+export type ReplayMismatchOwnerDomain = 'turn' | 'tasks' | 'tools' | 'providers' | 'session' | 'conversation' | 'agents' | 'workflows' | 'permissions' | 'transport' | 'unknown';
+export type ReplayMismatchFailureMode = 'missing_event' | 'extra_event' | 'ordering_violation' | 'payload_schema_mismatch' | 'payload_type_mismatch' | 'payload_value_mismatch' | 'missing_terminal_summary' | 'terminal_outcome_diverged' | 'stop_reason_diverged';
+/**
+ * A single actionable mismatch entry produced by diff mode.
+ */
+export interface ReplayMismatch {
+    /** The revision at which the mismatch was detected. */
+    readonly rev: number;
+    /** Mismatch classifier. */
+    readonly kind: MismatchClass;
+    /** Human-readable description — sufficient to act on without raw dumps. */
+    readonly description: string;
+    /** The event name involved, if applicable. */
+    readonly eventName?: string;
+    /** Key fields from the recorded payload, if applicable. */
+    readonly recordedSummary?: string;
+    /** Key fields from the replayed payload, if applicable. */
+    readonly replayedSummary?: string;
+    /** Likely owning runtime domain for the divergence. */
+    readonly ownerDomain?: ReplayMismatchOwnerDomain;
+    /** Narrower replay failure mode for operator triage. */
+    readonly failureMode?: ReplayMismatchFailureMode;
+    /** Related turn ID when the divergence can be tied to a single turn. */
+    readonly relatedTurnId?: string;
+}
+export type ReplayTurnOutcome = 'completed' | 'failed' | 'cancelled';
+export interface ReplayTurnSummary {
+    readonly turnId: string;
+    readonly outcome: ReplayTurnOutcome;
+    readonly terminalEvent: 'PREFLIGHT_FAIL' | 'TURN_COMPLETED' | 'TURN_ERROR' | 'TURN_CANCEL';
+    readonly startedRev?: number;
+    readonly terminalRev: number;
+    readonly stopReason?: string;
+    readonly message?: string;
+}
+/**
+ * The replay-local state tree at a given revision.
+ *
+ * Built by folding ledger entries over the initial snapshot; each step
+ * produces a new immutable frame.
+ */
+export interface ReplayFrame {
+    /** The revision this frame represents (0 = initial snapshot). */
+    readonly rev: number;
+    /** The event that produced this frame (absent for the initial snapshot). */
+    readonly entry?: LedgerEntry;
+    /** Domain state at this revision — merged from snapshot + events applied so far. */
+    readonly domains: Record<string, Record<string, unknown>>;
+}
+export type ReplayStatus = 'idle' | 'loaded' | 'running' | 'exhausted';
+/**
+ * Snapshot of engine state for the Replay panel.
+ */
+export interface ReplayEngineSnapshot {
+    readonly status: ReplayStatus;
+    readonly runId: string | null;
+    readonly currentRev: number;
+    readonly totalRevisions: number;
+    readonly currentFrame: ReplayFrame | null;
+    readonly mismatches: readonly ReplayMismatch[];
+    readonly turnSummaries: readonly ReplayTurnSummary[];
+}
+/**
+ * DeterministicReplayEngine.
+ *
+ * Usage:
+ * ```ts
+ * const engine = new DeterministicReplayEngine('/path/to/project');
+ * engine.load(runId, snapshot, ledgerEntries);
+ * engine.step();          // advance one event
+ * engine.step(5);         // advance five events
+ * engine.seek(10);        // jump to rev 10
+ * const report = engine.diff();  // compare current to recorded
+ * engine.export('/tmp/replay.json');  // write report to file
+ * ```
+ */
+export declare class DeterministicReplayEngine {
+    private readonly _projectRoot;
+    private _status;
+    private _runId;
+    private _snapshot;
+    /**
+     * Returns the initial snapshot that was loaded, or null if no run is loaded.
+     */
+    getInitialSnapshot(): RuntimeStateSnapshot | null;
+    private _entries;
+    private _frames;
+    private _currentFrameIndex;
+    private _mismatches;
+    private _turnSummaries;
+    private readonly _subscribers;
+    constructor(projectRoot: string);
+    /**
+     * Load a run for replay.
+     *
+     * Replaces any currently loaded run. The engine is positioned at rev 0
+     * (the initial snapshot) after loading.
+     *
+     * @param runId    - The run identifier.
+     * @param snapshot - The initial state snapshot captured at run start.
+     * @param entries  - All ledger entries for this run, in any order (sorted internally).
+     */
+    load(runId: string, snapshot: RuntimeStateSnapshot, entries: LedgerEntry[]): void;
+    /**
+     * Advance the replay cursor by `n` steps (default: 1).
+     *
+     * Returns the frames that were stepped over.
+     * If fewer than `n` events remain, steps to the end.
+     *
+     * @param n - Number of steps to advance.
+     * @returns The frames produced by the steps.
+     */
+    step(n?: number): ReplayFrame[];
+    /**
+     * Seek to a specific revision.
+     *
+     * Valid revisions are 0 (initial snapshot) through `totalRevisions`.
+     * Clamped to valid range.
+     *
+     * @param targetRev - Target revision number.
+     */
+    seek(targetRev: number): void;
+    /**
+     * Run diff mode: compare each replayed frame against the recorded sequence.
+     *
+     * Produces a list of `ReplayMismatch` entries that identify divergences
+     * with actionable classifiers and descriptions — not raw payload dumps.
+     *
+     * Diff analysis covers:
+     * - Missing events (recorded entry has no corresponding replayed frame)
+     * - Extra events (frame exists past the recorded sequence)
+     * - Payload mismatches (event name matches, but key payload fields differ)
+     * - Ordering violations (same events, different rev sequence)
+     *
+     * @returns Ordered list of mismatches (by rev).
+     */
+    diff(): ReplayMismatch[];
+    /**
+     * Export the current replay report (frames + mismatches) to a JSON file.
+     *
+     * The exported object contains:
+     * - `runId`
+     * - `exportedAt` (epoch ms)
+     * - `totalRevisions`
+     * - `currentRev`
+     * - `mismatches`
+     * - `frames` (condensed: rev, eventName, domainNames only — no full state)
+     *
+     * @param filePath - Absolute path to write the JSON report.
+     * @returns A promise that resolves when the file is written.
+     */
+    export(filePath: string): Promise<void>;
+    /**
+     * Get a snapshot of engine state for the Replay panel.
+     */
+    getSnapshot(): ReplayEngineSnapshot;
+    /**
+     * Register a callback invoked when engine state changes.
+     * @returns An unsubscribe function.
+     */
+    subscribe(callback: () => void): () => void;
+    /** Reset to idle — clears all loaded state. */
+    reset(): void;
+    /**
+     * Convert a RuntimeStateSnapshot into a flat domain map.
+     */
+    private _snapshotToDomains;
+    /**
+     * Apply a single ledger entry to the previous frame, producing a new frame.
+     *
+     * Event payloads are merged into the domain state by convention:
+     * the payload is treated as a partial update to the event's implied domain
+     * (derived from the event name prefix, e.g. "turn:" → "turn" domain).
+     * Unknown domain prefixes are collected into a synthetic "_events" domain.
+     */
+    private _applyEntry;
+    /**
+     * Compare two payloads at a key-level and return a mismatch if they diverge.
+     *
+     * Reports only the first differing key to keep the output actionable.
+     */
+    private _diffPayloads;
+    private _deriveTurnSummaries;
+    private _diffTurnSummaries;
+    private _extractTurnId;
+    private _inferOwnerDomain;
+    private _notify;
+}
+//# sourceMappingURL=deterministic-replay.d.ts.map

package/dist/_internal/platform/core/deterministic-replay.d.ts.map

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