@runtime-digital-twin/sdk 1.0.0

package/dist/invariants.d.ts

@@ -0,0 +1,58 @@
+/**
+ * State Invariant Checking
+ *
+ * Lightweight contract checking that emits state.invariant events
+ * without throwing by default (observe mode).
+ */
+export interface InvariantDetails {
+    paths?: string[];
+    expected?: string;
+    observed?: string;
+}
+export interface EmitInvariantOptions {
+    name: string;
+    passed: boolean;
+    severity: "warn" | "error";
+    details?: InvariantDetails;
+}
+/**
+ * Emit a state.invariant event
+ *
+ * Uses the current trace context if available. If no trace context is available,
+ * the event is silently dropped (fail-open behavior).
+ *
+ * @param options - Invariant options
+ * @param explicitSpanId - Optional explicit spanId (overrides trace context)
+ * @param explicitParentSpanId - Optional explicit parentSpanId (overrides trace context)
+ */
+export declare function emitInvariant(options: EmitInvariantOptions, explicitSpanId?: string, explicitParentSpanId?: string | null): Promise<void>;
+/**
+ * Assert that a value is not null/undefined
+ *
+ * @param path - JSONPath-like path to the value (e.g., "pricing.price")
+ * @param value - Value to check
+ * @param options - Optional details
+ */
+export declare function assertNonNull(path: string, value: unknown, options?: {
+    expected?: string;
+    observed?: string;
+}): Promise<void>;
+/**
+ * Assert that an object has all required keys
+ *
+ * @param keys - Array of required key names
+ * @param obj - Object to check
+ * @param path - Optional JSONPath-like path prefix (e.g., "response")
+ */
+export declare function assertHasKeys(keys: string[], obj: Record<string, unknown> | null | undefined, path?: string): Promise<void>;
+/**
+ * Assert that a numeric value is within a range
+ *
+ * @param name - Name of the invariant (e.g., "pricing.price_range")
+ * @param value - Value to check
+ * @param min - Minimum value (inclusive)
+ * @param max - Maximum value (inclusive)
+ * @param path - Optional JSONPath-like path to the value
+ */
+export declare function assertInRange(name: string, value: number | null | undefined, min: number, max: number, path?: string): Promise<void>;
+//# sourceMappingURL=invariants.d.ts.map

package/dist/invariants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invariants.d.ts","sourceRoot":"","sources":["../src/invariants.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,MAAM,WAAW,gBAAgB;IAC/B,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,CAAC;IAChB,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;IAC3B,OAAO,CAAC,EAAE,gBAAgB,CAAC;CAC5B;AAED;;;;;;;;;GASG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,oBAAoB,EAC7B,cAAc,CAAC,EAAE,MAAM,EACvB,oBAAoB,CAAC,EAAE,MAAM,GAAG,IAAI,GACnC,OAAO,CAAC,IAAI,CAAC,CA0Df;AAED;;;;;;GAMG;AACH,wBAAsB,aAAa,CACjC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,OAAO,EACd,OAAO,CAAC,EAAE;IACR,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GACA,OAAO,CAAC,IAAI,CAAC,CAyBf;AAED;;;;;;GAMG;AACH,wBAAsB,aAAa,CACjC,IAAI,EAAE,MAAM,EAAE,EACd,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,EAC/C,IAAI,CAAC,EAAE,MAAM,GACZ,OAAO,CAAC,IAAI,CAAC,CA8Bf;AAED;;;;;;;;GAQG;AACH,wBAAsB,aAAa,CACjC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAChC,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE,MAAM,GACZ,OAAO,CAAC,IAAI,CAAC,CAyCf"}

package/dist/invariants.js

@@ -0,0 +1,192 @@
+"use strict";
+/**
+ * State Invariant Checking
+ *
+ * Lightweight contract checking that emits state.invariant events
+ * without throwing by default (observe mode).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.emitInvariant = emitInvariant;
+exports.assertNonNull = assertNonNull;
+exports.assertHasKeys = assertHasKeys;
+exports.assertInRange = assertInRange;
+const http_wrapper_1 = require("./http-wrapper");
+/**
+ * Emit a state.invariant event
+ *
+ * Uses the current trace context if available. If no trace context is available,
+ * the event is silently dropped (fail-open behavior).
+ *
+ * @param options - Invariant options
+ * @param explicitSpanId - Optional explicit spanId (overrides trace context)
+ * @param explicitParentSpanId - Optional explicit parentSpanId (overrides trace context)
+ */
+async function emitInvariant(options, explicitSpanId, explicitParentSpanId) {
+    const { name, passed, severity, details } = options;
+    const { bundle, spanId: contextSpanId } = (0, http_wrapper_1.getTraceContext)();
+    // Use explicit spanId if provided, otherwise use context
+    const spanId = explicitSpanId || contextSpanId;
+    if (process.env.DEBUG_HTTP_SENTINELS) {
+        console.log('[INVARIANTS] emitInvariant called:', {
+            name,
+            passed,
+            severity,
+            explicitSpanId,
+            contextSpanId,
+            finalSpanId: spanId,
+            hasBundle: !!bundle,
+        });
+    }
+    // If no trace context and no explicit spanId, silently skip (fail-open)
+    if (!bundle || !spanId) {
+        if (process.env.DEBUG_HTTP_SENTINELS) {
+            console.warn('[INVARIANTS] No trace context or spanId, skipping invariant');
+        }
+        return;
+    }
+    // Use explicit parentSpanId if provided, otherwise null
+    const parentSpanId = explicitParentSpanId !== undefined ? explicitParentSpanId : null;
+    try {
+        const event = {
+            type: "state.invariant",
+            timestamp: Date.now(),
+            spanId,
+            parentSpanId,
+            name,
+            passed,
+            severity,
+            ...(details && { details }),
+        };
+        if (process.env.DEBUG_HTTP_SENTINELS) {
+            console.log('[INVARIANTS] Writing invariant event:', event);
+        }
+        await bundle.writeEvent(event);
+        if (process.env.DEBUG_HTTP_SENTINELS) {
+            console.log('[INVARIANTS] Invariant event written successfully');
+        }
+    }
+    catch (error) {
+        // Fail-open: log error but don't throw
+        console.error(`[SDK] Failed to emit invariant event: ${error}`);
+        if (process.env.DEBUG_HTTP_SENTINELS) {
+            console.error('[INVARIANTS] Error details:', error);
+        }
+    }
+}
+/**
+ * Assert that a value is not null/undefined
+ *
+ * @param path - JSONPath-like path to the value (e.g., "pricing.price")
+ * @param value - Value to check
+ * @param options - Optional details
+ */
+async function assertNonNull(path, value, options) {
+    const passed = value !== null && value !== undefined;
+    if (!passed) {
+        await emitInvariant({
+            name: `${path}.non_null`,
+            passed: false,
+            severity: "error",
+            details: {
+                paths: [path],
+                expected: options?.expected || "non-null value",
+                observed: options?.observed || "null or undefined",
+            },
+        });
+    }
+    else {
+        // Also emit passed invariants for completeness (optional, can be filtered)
+        await emitInvariant({
+            name: `${path}.non_null`,
+            passed: true,
+            severity: "warn", // Lower severity for passed checks
+            details: {
+                paths: [path],
+            },
+        });
+    }
+}
+/**
+ * Assert that an object has all required keys
+ *
+ * @param keys - Array of required key names
+ * @param obj - Object to check
+ * @param path - Optional JSONPath-like path prefix (e.g., "response")
+ */
+async function assertHasKeys(keys, obj, path) {
+    if (!obj || typeof obj !== "object") {
+        await emitInvariant({
+            name: path ? `${path}.has_keys` : "object.has_keys",
+            passed: false,
+            severity: "error",
+            details: {
+                paths: path ? [path] : undefined,
+                expected: `object with keys: ${keys.join(", ")}`,
+                observed: obj === null ? "null" : obj === undefined ? "undefined" : typeof obj,
+            },
+        });
+        return;
+    }
+    const missingKeys = keys.filter((key) => !(key in obj));
+    const passed = missingKeys.length === 0;
+    await emitInvariant({
+        name: path ? `${path}.has_keys` : "object.has_keys",
+        passed,
+        severity: passed ? "warn" : "error",
+        details: {
+            paths: path ? missingKeys.map((key) => `${path}.${key}`) : missingKeys,
+            expected: `object with keys: ${keys.join(", ")}`,
+            observed: passed
+                ? `object has all required keys`
+                : `missing keys: ${missingKeys.join(", ")}`,
+        },
+    });
+}
+/**
+ * Assert that a numeric value is within a range
+ *
+ * @param name - Name of the invariant (e.g., "pricing.price_range")
+ * @param value - Value to check
+ * @param min - Minimum value (inclusive)
+ * @param max - Maximum value (inclusive)
+ * @param path - Optional JSONPath-like path to the value
+ */
+async function assertInRange(name, value, min, max, path) {
+    if (value === null || value === undefined) {
+        await emitInvariant({
+            name,
+            passed: false,
+            severity: "error",
+            details: {
+                paths: path ? [path] : undefined,
+                expected: `number in range [${min}, ${max}]`,
+                observed: value === null ? "null" : "undefined",
+            },
+        });
+        return;
+    }
+    if (typeof value !== "number" || isNaN(value)) {
+        await emitInvariant({
+            name,
+            passed: false,
+            severity: "error",
+            details: {
+                paths: path ? [path] : undefined,
+                expected: `number in range [${min}, ${max}]`,
+                observed: `not a number: ${typeof value}`,
+            },
+        });
+        return;
+    }
+    const passed = value >= min && value <= max;
+    await emitInvariant({
+        name,
+        passed,
+        severity: passed ? "warn" : "error",
+        details: {
+            paths: path ? [path] : undefined,
+            expected: `value in range [${min}, ${max}]`,
+            observed: passed ? `value ${value} is in range` : `value ${value} is out of range`,
+        },
+    });
+}

package/dist/multi-service-edge-builder.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Multi-service edge builder
+ *
+ * Analyzes trace events to build edges between services for distributed tracing.
+ * An edge represents a call from one service to another.
+ */
+export interface TraceEvent {
+    type: string;
+    timestamp: number;
+    traceId: string;
+    spanId: string;
+    parentSpanId: string | null;
+    serviceName: string;
+    method?: string;
+    url?: string;
+    urlTemplate?: string | null;
+    peerHost?: string | null;
+    peerService?: string | null;
+    statusCode?: number | null;
+    path?: string;
+    route?: string;
+    error?: {
+        name?: string;
+        message?: string;
+        stack?: string;
+    };
+    responseShapeDigest?: {
+        kind: string;
+        hash?: string;
+        nullPaths?: string[];
+        keys?: string[];
+        topLevelType?: string;
+    };
+    name?: string;
+    passed?: boolean;
+    severity?: "warn" | "error";
+    details?: {
+        paths?: string[];
+        expected?: string;
+        observed?: string;
+    };
+}
+export interface ServiceEdge {
+    traceId: string;
+    fromService: string;
+    fromSpanId: string;
+    fromOperation: string;
+    toService: string;
+    toSpanId: string;
+    toOperation: string;
+    statusCode: number | null;
+    timestampOut: number;
+    timestampIn: number;
+}
+/**
+ * Build service edges from trace events
+ *
+ * An edge is formed when:
+ * - outbound.type == "http.request.outbound"
+ * - inbound.type == "http.request.inbound"
+ * - inbound.traceId == outbound.traceId
+ * - inbound.parentSpanId == outbound.spanId
+ *
+ * @param events - Array of trace events (all from the same traceId)
+ * @returns Array of service edges, sorted by timestampOut
+ */
+export declare function buildEdges(events: TraceEvent[]): ServiceEdge[];
+/**
+ * Build edges from a traceId by loading events
+ *
+ * This is a convenience function that loads events from a trace directory
+ * and calls buildEdges. For now, this requires the caller to provide events.
+ * In the future, this could load from file system or storage.
+ *
+ * @param traceId - The trace ID
+ * @param events - Array of trace events for this traceId
+ * @returns Array of service edges
+ */
+export declare function buildEdgesForTrace(traceId: string, events: TraceEvent[]): ServiceEdge[];
+//# sourceMappingURL=multi-service-edge-builder.d.ts.map

package/dist/multi-service-edge-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"multi-service-edge-builder.d.ts","sourceRoot":"","sources":["../src/multi-service-edge-builder.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,WAAW,EAAE,MAAM,CAAC;IAEpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAE3B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,KAAK,CAAC,EAAE;QACN,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC;IAEF,mBAAmB,CAAC,EAAE;QACpB,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;QACrB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;QAChB,YAAY,CAAC,EAAE,MAAM,CAAC;KACvB,CAAC;IAEF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAC5B,OAAO,CAAC,EAAE;QACR,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;QACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,CAAC;CACH;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;CACrB;AA6BD;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,UAAU,EAAE,GAAG,WAAW,EAAE,CAuD9D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,GAAG,WAAW,EAAE,CAIvF"}

package/dist/multi-service-edge-builder.js

@@ -0,0 +1,107 @@
+"use strict";
+/**
+ * Multi-service edge builder
+ *
+ * Analyzes trace events to build edges between services for distributed tracing.
+ * An edge represents a call from one service to another.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildEdges = buildEdges;
+exports.buildEdgesForTrace = buildEdgesForTrace;
+/**
+ * Build operation string for inbound event
+ */
+function buildInboundOperation(event) {
+    const method = event.method || 'UNKNOWN';
+    const path = event.route || event.path || 'unknown';
+    return `${method} ${path}`;
+}
+/**
+ * Build operation string for outbound event
+ */
+function buildOutboundOperation(event) {
+    const method = event.method || 'UNKNOWN';
+    // Prefer urlTemplate, fallback to peerHost, then "unknown"
+    if (event.urlTemplate) {
+        return `${method} ${event.urlTemplate}`;
+    }
+    if (event.peerHost) {
+        return `${method} ${event.peerHost}`;
+    }
+    return `${method} unknown`;
+}
+/**
+ * Build service edges from trace events
+ *
+ * An edge is formed when:
+ * - outbound.type == "http.request.outbound"
+ * - inbound.type == "http.request.inbound"
+ * - inbound.traceId == outbound.traceId
+ * - inbound.parentSpanId == outbound.spanId
+ *
+ * @param events - Array of trace events (all from the same traceId)
+ * @returns Array of service edges, sorted by timestampOut
+ */
+function buildEdges(events) {
+    const edges = [];
+    // Index outbound events by spanId for fast lookup
+    const outboundBySpanId = new Map();
+    for (const event of events) {
+        if (event.type === 'http.request.outbound') {
+            outboundBySpanId.set(event.spanId, event);
+        }
+    }
+    // Find inbound events and match them with outbound events
+    for (const inboundEvent of events) {
+        if (inboundEvent.type !== 'http.request.inbound') {
+            continue;
+        }
+        // Check if this inbound event has a parentSpanId that matches an outbound event
+        if (!inboundEvent.parentSpanId) {
+            // Root span - no parent outbound event
+            continue;
+        }
+        const outboundEvent = outboundBySpanId.get(inboundEvent.parentSpanId);
+        if (!outboundEvent) {
+            // No matching outbound event found - downstream service not instrumented
+            continue;
+        }
+        // Verify traceIds match (should always be true if events are from same trace)
+        if (inboundEvent.traceId !== outboundEvent.traceId) {
+            continue;
+        }
+        // Build edge
+        const edge = {
+            traceId: inboundEvent.traceId,
+            fromService: outboundEvent.serviceName,
+            fromSpanId: outboundEvent.spanId,
+            fromOperation: buildOutboundOperation(outboundEvent),
+            toService: inboundEvent.serviceName,
+            toSpanId: inboundEvent.spanId,
+            toOperation: buildInboundOperation(inboundEvent),
+            statusCode: outboundEvent.statusCode ?? null,
+            timestampOut: outboundEvent.timestamp,
+            timestampIn: inboundEvent.timestamp,
+        };
+        edges.push(edge);
+    }
+    // Sort edges by timestampOut (chronological order)
+    edges.sort((a, b) => a.timestampOut - b.timestampOut);
+    return edges;
+}
+/**
+ * Build edges from a traceId by loading events
+ *
+ * This is a convenience function that loads events from a trace directory
+ * and calls buildEdges. For now, this requires the caller to provide events.
+ * In the future, this could load from file system or storage.
+ *
+ * @param traceId - The trace ID
+ * @param events - Array of trace events for this traceId
+ * @returns Array of service edges
+ */
+function buildEdgesForTrace(traceId, events) {
+    // Filter events to only include those for this traceId
+    const traceEvents = events.filter(e => e.traceId === traceId);
+    return buildEdges(traceEvents);
+}

package/dist/outbound-matcher.d.ts

@@ -0,0 +1,192 @@
+import type { ReplayLogger } from "./replay-logger";
+/**
+ * Replay modes for outbound call matching
+ */
+export type ReplayMode = "strict" | "explain";
+/**
+ * Structured failure for outbound request mismatch
+ */
+export interface OutboundRequestMismatch {
+    type: "outbound_request_mismatch";
+    location: string;
+    expected: string;
+    actual: string;
+    hint: string;
+    callIndex: number;
+    diff: {
+        field: string;
+        expected: string | null;
+        actual: string | null;
+    }[];
+}
+/**
+ * Structured failure for unexpected outbound call (call occurred but no recorded match)
+ */
+export interface UnexpectedOutboundCall {
+    type: "unexpected_outbound_call";
+    location: string;
+    expected: string;
+    actual: string;
+    hint: string;
+    callIndex: number;
+    service: string;
+    spanId: string | null;
+    call: OutboundCallSignature;
+}
+/**
+ * Structured failure for missing outbound call (recorded call never happened)
+ */
+export interface MissingOutboundCall {
+    type: "missing_outbound_call";
+    location: string;
+    expected: string;
+    actual: string;
+    hint: string;
+    callIndex: number;
+    service: string;
+    spanId: string;
+    recordedCall: RecordedOutboundCall;
+}
+/**
+ * Union type for all outbound call failures
+ */
+export type OutboundCallFailure = OutboundRequestMismatch | UnexpectedOutboundCall | MissingOutboundCall;
+/**
+ * Divergence event emitted in explain mode
+ */
+export interface OutboundDivergence {
+    type: "divergence";
+    severity: "warning" | "error";
+    callIndex: number;
+    message: string;
+    expected: RecordedOutboundCall | null;
+    actual: OutboundCallSignature;
+    recoverable: boolean;
+}
+/**
+ * Recorded outbound HTTP call from trace
+ */
+export interface RecordedOutboundCall {
+    spanId: string;
+    method: string;
+    url: string;
+    normalizedUrl: string;
+    headers: Record<string, string>;
+    bodyHash: string | null;
+    response: {
+        statusCode: number;
+        headers: Record<string, string>;
+        bodyHash: string | null;
+        bodyBlob: string | null;
+    } | null;
+}
+/**
+ * Signature used to match an outbound call
+ */
+export interface OutboundCallSignature {
+    method: string;
+    url: string;
+    headers: Record<string, string>;
+    bodyHash: string | null;
+}
+/**
+ * Normalize URL for matching: pathname + sorted query params
+ */
+export declare function normalizeUrl(url: string): string;
+/**
+ * Normalize headers for matching: lowercase keys, filter to matching headers
+ */
+export declare function normalizeHeaders(headers: Record<string, string>): Record<string, string>;
+/**
+ * Compute body hash from content
+ */
+export declare function computeBodyHash(body: string | Buffer | object | null | undefined): string | null;
+/**
+ * Compute match signature for comparison
+ */
+export declare function computeMatchSignature(call: OutboundCallSignature): string;
+/**
+ * Compare two calls and return differences
+ */
+export declare function compareOutboundCalls(expected: RecordedOutboundCall, actual: OutboundCallSignature): {
+    matches: boolean;
+    diffs: {
+        field: string;
+        expected: string | null;
+        actual: string | null;
+    }[];
+};
+/**
+ * Ordered outbound call matcher for replay
+ */
+export declare class OutboundMatcher {
+    private recordedCalls;
+    private currentIndex;
+    private mode;
+    private traceDir;
+    private divergences;
+    private logger;
+    constructor(recordedCalls: RecordedOutboundCall[], mode: ReplayMode, traceDir: string, logger?: ReplayLogger);
+    /**
+     * Set the logger for structured replay logging
+     */
+    setLogger(logger: ReplayLogger): void;
+    /**
+     * Get all recorded divergences (for explain mode)
+     */
+    getDivergences(): OutboundDivergence[];
+    /**
+     * Get current call index
+     */
+    getCurrentIndex(): number;
+    /**
+     * Get total recorded calls
+     */
+    getTotalCalls(): number;
+    /**
+     * Match the next outbound call against the recorded sequence
+     *
+     * In strict mode: throws OutboundRequestMismatch on any mismatch
+     * In explain mode: emits divergence and returns best-effort match
+     */
+    matchNext(actual: OutboundCallSignature): RecordedOutboundCall;
+    /**
+     * Check if all recorded calls have been matched
+     */
+    isComplete(): boolean;
+    /**
+     * Get summary of unmatched calls (calls that were recorded but not replayed)
+     */
+    getUnmatchedCalls(): RecordedOutboundCall[];
+    /**
+     * Finalize replay and check for missing outbound calls.
+     * Should be called at the end of replay to detect any recorded calls that never happened.
+     *
+     * In strict mode: throws MissingOutboundCall[] if any calls are missing
+     * In explain mode: emits divergences and returns the missing calls
+     *
+     * @returns Array of MissingOutboundCall failures (empty if all calls matched)
+     */
+    finalize(): MissingOutboundCall[];
+}
+/**
+ * Parse recorded outbound calls from trace events
+ */
+export declare function parseRecordedOutboundCalls(events: any[]): RecordedOutboundCall[];
+/**
+ * Format OutboundRequestMismatch for CLI output
+ */
+export declare function formatOutboundMismatch(failure: OutboundRequestMismatch): string;
+/**
+ * Format UnexpectedOutboundCall for CLI output
+ */
+export declare function formatUnexpectedOutboundCall(failure: UnexpectedOutboundCall): string;
+/**
+ * Format MissingOutboundCall for CLI output
+ */
+export declare function formatMissingOutboundCall(failure: MissingOutboundCall): string;
+/**
+ * Format any outbound call failure for CLI output
+ */
+export declare function formatOutboundCallFailure(failure: OutboundCallFailure): string;
+//# sourceMappingURL=outbound-matcher.d.ts.map

package/dist/outbound-matcher.d.ts.map

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