@pellux/goodvibes-sdk 0.18.3 → 0.18.11

package/dist/platform/runtime/health/cascade-timing.js

@@ -0,0 +1,96 @@
+/**
+ * CascadeTimer — timing instrumentation for cascade rule evaluations.
+ *
+ * Wraps CascadeEngine.evaluate() to measure evaluation latency and attach
+ * timing metadata (latencyMs, severity, remediationPlaybookIds) to each
+ * CascadeResult before returning them to callers.
+ *
+ * The timer is transparent to the cascade engine — it delegates evaluation
+ * and annotates results without modifying engine state.
+ */
+import { CASCADE_PLAYBOOK_MAP } from './cascade-playbook-map.js';
+/**
+ * Derive a severity level from a cascade result's effect type and recovery state.
+ */
+export function deriveCascadeSeverity(result) {
+    const { effect, target } = result;
+    // Session unrecoverable cascades to ALL — always critical
+    if (effect.type === 'EMIT_EVENT' && effect.eventType === 'SESSION_UNRECOVERABLE') {
+        return 'critical';
+    }
+    if (target === 'ALL') {
+        return 'critical';
+    }
+    switch (effect.type) {
+        case 'CANCEL_INFLIGHT':
+        case 'BLOCK_NEW':
+            return 'high';
+        case 'BLOCK_DISPATCH':
+            return result.recoveryExhausted ? 'medium' : 'high';
+        case 'MARK_CHILDREN':
+            return 'high';
+        case 'DEREGISTER_TOOLS':
+            return 'medium';
+        case 'EMIT_EVENT':
+            return 'low';
+        default:
+            return 'low';
+    }
+}
+/**
+ * Annotate a CascadeResult with timing and remediation metadata.
+ */
+function annotate(result, latencyMs) {
+    return {
+        ...result,
+        latencyMs,
+        severity: deriveCascadeSeverity(result),
+        remediationPlaybookIds: CASCADE_PLAYBOOK_MAP.get(result.ruleId) ?? [],
+    };
+}
+/**
+ * CascadeTimer — instruments CascadeEngine.evaluate() with latency tracking.
+ *
+ * Wrap the cascade engine with this class to get TimedCascadeResult objects
+ * that include per-result latency, severity, and remediation playbook IDs.
+ *
+ * @example
+ * ```ts
+ * const timer = new CascadeTimer(cascadeEngine);
+ * const { cascades, totalLatencyMs } = timer.evaluate('mcp', 'failed');
+ * // cascades[0].latencyMs — evaluation latency
+ * // cascades[0].severity  — 'high' | 'critical' etc.
+ * // cascades[0].remediationPlaybookIds — ['reconnect-failure']
+ * ```
+ */
+export class CascadeTimer {
+    engine;
+    clock;
+    constructor(engine, clock = Date.now) {
+        this.engine = engine;
+        this.clock = clock;
+    }
+    /**
+     * Evaluate cascade rules for a domain health transition, measuring latency.
+     *
+     * Each returned result is annotated with:
+     * - `latencyMs`: wall-clock cost of evaluating this specific domain+status pair
+     * - `severity`: derived criticality tier
+     * - `remediationPlaybookIds`: playbook IDs mapped for this rule
+     *
+     * @param domain - The domain whose health changed.
+     * @param newStatus - The new health status.
+     * @param sourceContext - Optional entity context (e.g. `{ pluginId }`).
+     */
+    evaluate(domain, newStatus, sourceContext) {
+        const start = this.clock();
+        const result = this.engine.evaluate(domain, newStatus, sourceContext);
+        const end = this.clock();
+        const totalLatencyMs = end - start;
+        return {
+            cascades: result.cascades.map((r) => annotate(r, totalLatencyMs)),
+            pendingRecovery: result.pendingRecovery.map((r) => annotate(r, totalLatencyMs)),
+            totalLatencyMs,
+        };
+    }
+}

package/dist/platform/runtime/health/types.d.ts

@@ -0,0 +1,176 @@
+/**
+ * Core health types for the goodvibes-sdk runtime health monitoring system.
+ * These types model domain health status, composite system health, cascade rules,
+ * and the effects that propagate when a domain transitions to a degraded or failed state.
+ */
+/** Health status for a single domain */
+export type HealthStatus = 'healthy' | 'degraded' | 'failed' | 'unknown';
+/**
+ * All domains that participate in runtime health tracking.
+ * Each domain maps to a subsystem or machine in the runtime.
+ */
+export type HealthDomain = 'turn' | 'toolExecution' | 'permissions' | 'tasks' | 'agents' | 'plugins' | 'mcp' | 'transport' | 'session' | 'compaction' | 'conversation' | 'model' | 'panels' | 'overlays' | 'providerHealth' | 'daemon' | 'acp' | 'integrations' | 'telemetry' | 'git' | 'discovery' | 'intelligence' | 'surfacePerf';
+/** Per-domain health record capturing current status and recovery metadata */
+export interface DomainHealth {
+    /** The domain this record belongs to */
+    domain: HealthDomain;
+    /** Current health status */
+    status: HealthStatus;
+    /** Unix timestamp (ms) of the last status transition */
+    lastTransitionAt: number;
+    /** Capabilities reduced when the domain is degraded (not failed) */
+    degradedCapabilities?: string[];
+    /** Human-readable reason for the current failure, if any */
+    failureReason?: string;
+    /** Number of recovery attempts made since last failure */
+    recoveryAttempts: number;
+    /** Maximum recovery attempts allowed before cascading */
+    maxRecoveryAttempts: number;
+}
+/** Composite system health derived from all domain states */
+export interface CompositeHealth {
+    /** Overall system health: failed > degraded > healthy; unknown if no domains are known */
+    overall: HealthStatus;
+    /** Health record for every tracked domain */
+    domains: Map<HealthDomain, DomainHealth>;
+    /** Domains currently in degraded state */
+    degradedDomains: HealthDomain[];
+    /** Domains currently in failed state */
+    failedDomains: HealthDomain[];
+    /** Unix timestamp (ms) of the last update to any domain */
+    lastUpdatedAt: number;
+}
+/**
+ * What happens when a cascade rule fires.
+ * Each variant encodes the effect type and any scope or metadata needed to apply it.
+ */
+export type CascadeEffect = {
+    type: 'CANCEL_INFLIGHT';
+    scope: string;
+} | {
+    type: 'BLOCK_DISPATCH';
+    scope: string;
+    queueable: boolean;
+} | {
+    type: 'MARK_CHILDREN';
+    status: 'failed' | 'blocked';
+    notifyParent: boolean;
+} | {
+    type: 'DEREGISTER_TOOLS';
+    pluginId?: string;
+} | {
+    type: 'EMIT_EVENT';
+    eventType: string;
+} | {
+    type: 'BLOCK_NEW';
+    scope: string;
+};
+/**
+ * A single declarative cascade rule.
+ * When the source domain reaches sourceState, the effect is applied to the target domain.
+ * Rules are data-driven — adding a new rule requires only adding to the rules array.
+ */
+export interface CascadeRule {
+    /** Unique rule identifier */
+    id: string;
+    /** The domain whose health change triggers this rule */
+    source: HealthDomain;
+    /** The health status of the source domain that triggers this rule */
+    sourceState: HealthStatus;
+    /** The domain (or 'ALL') affected by the cascade */
+    target: HealthDomain | 'ALL';
+    /** The effect to apply to the target */
+    effect: CascadeEffect;
+    /** Human-readable description of why this cascade exists */
+    description: string;
+    /** If true, a recovery attempt must be made before cascading */
+    recoveryFirst: boolean;
+}
+/** Result of evaluating a single cascade rule */
+export interface CascadeResult {
+    /** ID of the rule that fired */
+    ruleId: string;
+    /** Source domain that triggered the cascade */
+    source: HealthDomain;
+    /** Target domain (or 'ALL') that receives the effect */
+    target: HealthDomain | 'ALL';
+    /** The effect that was (or should be) applied */
+    effect: CascadeEffect;
+    /** Unix timestamp (ms) when this result was produced */
+    timestamp: number;
+    /**
+     * True when recovery was attempted and exhausted before cascading.
+     * "We tried recovery, it failed, cascade anyway."
+     * False for rules that do not use recoveryFirst.
+     */
+    recoveryExhausted: boolean;
+    /** Optional context about the entity that triggered the cascade (e.g. { pluginId: 'foo' }) */
+    sourceContext?: Record<string, string>;
+    /**
+     * Wall-clock latency (ms) of the cascade rule evaluation that produced this result.
+     * Populated by CascadeTimer; undefined when evaluated directly via CascadeEngine.
+     */
+    latencyMs?: number;
+    /**
+     * Severity tier derived from the cascade effect type and recovery state.
+     * Populated by CascadeTimer; undefined when evaluated directly via CascadeEngine.
+     */
+    severity?: string;
+    /**
+     * Playbook IDs providing remediation actions for this cascade type.
+     * Populated by CascadeTimer; empty when evaluated directly via CascadeEngine.
+     */
+    remediationPlaybookIds?: readonly string[];
+}
+/**
+ * Return value of CascadeEngine.evaluate().
+ * Separates actionable cascades from those still awaiting recovery.
+ */
+export interface EvaluateResult {
+    /** Cascades that are actionable — apply these effects now */
+    cascades: CascadeResult[];
+    /** Recovery still in progress — do not apply these effects yet */
+    pendingRecovery: CascadeResult[];
+}
+/**
+ * Event emitted when a cascade effect is applied.
+ * Health diagnostics types for the runtime.
+ */
+export interface CascadeAppliedEvent {
+    type: 'CASCADE_APPLIED';
+    /** ID of the rule that fired */
+    ruleId: string;
+    /** Source domain that triggered the cascade */
+    source: HealthDomain;
+    /** Target domain (or 'ALL') that received the effect */
+    target: HealthDomain | 'ALL';
+    /** The effect that was applied */
+    effect: CascadeEffect;
+    /** Unix timestamp (ms) when the event was produced */
+    timestamp: number;
+    /** Whether recovery was exhausted before this cascade was applied */
+    recoveryExhausted: boolean;
+    /** Optional context about the entity that triggered the cascade */
+    sourceContext?: Record<string, string>;
+    /**
+     * Wall-clock latency (ms) of the cascade evaluation that produced this event.
+     * Populated when the event is created from a TimedCascadeResult.
+     */
+    latencyMs?: number;
+    /**
+     * Severity tier of this cascade event.
+     * Populated when the event is created from a TimedCascadeResult.
+     */
+    severity?: string;
+    /**
+     * Playbook IDs that provide remediation actions for this cascade type.
+     * Populated when the event is created from a TimedCascadeResult.
+     */
+    remediationPlaybookIds?: readonly string[];
+}
+/**
+ * Create a CascadeAppliedEvent from a CascadeResult.
+ * Call this after applying a cascade effect to produce a trace event.
+ */
+export declare function createCascadeAppliedEvent(result: CascadeResult): CascadeAppliedEvent;
+//# sourceMappingURL=types.d.ts.map

package/dist/platform/runtime/health/types.d.ts.map

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

package/dist/platform/runtime/health/types.js

@@ -0,0 +1,24 @@
+/**
+ * Core health types for the goodvibes-sdk runtime health monitoring system.
+ * These types model domain health status, composite system health, cascade rules,
+ * and the effects that propagate when a domain transitions to a degraded or failed state.
+ */
+/**
+ * Create a CascadeAppliedEvent from a CascadeResult.
+ * Call this after applying a cascade effect to produce a trace event.
+ */
+export function createCascadeAppliedEvent(result) {
+    return {
+        type: 'CASCADE_APPLIED',
+        ruleId: result.ruleId,
+        source: result.source,
+        target: result.target,
+        effect: result.effect,
+        timestamp: result.timestamp,
+        recoveryExhausted: result.recoveryExhausted,
+        sourceContext: result.sourceContext,
+        latencyMs: result.latencyMs,
+        severity: result.severity,
+        remediationPlaybookIds: result.remediationPlaybookIds,
+    };
+}

package/dist/platform/runtime/idempotency/index.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Idempotency — store and key generation.
+ *
+ * Provides an in-process idempotency store for tool-call deduplication across
+ * replay, reconnect, and restart scenarios. Keys are deterministic (derived from
+ * session + turn + call identifiers) so the same logical call always maps to the
+ * same key regardless of when it is submitted.
+ *
+ * Lifecycle:
+ *   1. Before executing a tool, call `checkAndRecord(key)`.
+ *      - `'new'`       → proceed with execution.
+ *      - `'in-flight'` → a prior submission is still running; reject or wait.
+ *      - `'duplicate'` → a prior submission completed; return cached result.
+ *   2. On success, call `markComplete(key, result)` to cache the result.
+ *   3. On failure, call `markFailed(key)` to allow a retry on the next attempt.
+ *
+ * TTL-based eviction runs automatically whenever the store exceeds `maxRecords`.
+ * In-flight records are never evicted.
+ */
+import type { IdempotencyKeyContext, IdempotencyRecord, IdempotencyStoreConfig } from './types.js';
+export type { IdempotencyKeyContext, IdempotencyRecord, IdempotencyStoreConfig } from './types.js';
+export type { IdempotencyStatus } from './types.js';
+/**
+ * IdempotencyStore — bounded, TTL-evicted in-process store.
+ *
+ * Thread safety: Node.js is single-threaded; no locking is required.
+ * Suitable for in-process use within a single runtime session.
+ *
+ * @example
+ * ```ts
+ * const store = new IdempotencyStore({ ttlMs: 5 * 60_000 });
+ * const key = store.generateKey({ sessionId, turnId, callId });
+ * const check = store.checkAndRecord(key);
+ * if (check.status === 'new') {
+ *   const result = await doWork();
+ *   store.markComplete(key, result);
+ *   return result;
+ * } else if (check.status === 'duplicate') {
+ *   return check.record.result; // cached
+ * } else {
+ *   throw new Error('Tool call already in-flight');
+ * }
+ * ```
+ */
+export declare class IdempotencyStore {
+    private readonly store;
+    private readonly ttlMs;
+    private readonly maxRecords;
+    constructor(config?: IdempotencyStoreConfig);
+    /**
+     * Generate a deterministic idempotency key from a call context.
+     *
+     * Uses a SHA-256 hash of `sessionId:turnId:callId` to produce a compact,
+     * collision-resistant key that is stable across restarts (given the same inputs).
+     *
+     * @param context - Session, turn, and call identifiers.
+     * @returns Hex-encoded SHA-256 digest (64 characters).
+     */
+    generateKey(context: IdempotencyKeyContext): string;
+    /**
+     * Check whether a key has been seen before and record it as `in-flight` if new.
+     *
+     * Returns a discriminated union:
+     * - `{ status: 'new' }`        — key is unseen; record created and marked in-flight.
+     * - `{ status: 'in-flight' }`  — a prior submission is still running.
+     * - `{ status: 'duplicate', record }` — prior submission completed; record holds cached result.
+     *
+     * @param key - Idempotency key from `generateKey`.
+     */
+    checkAndRecord(key: string): {
+        readonly status: 'new';
+    } | {
+        readonly status: 'in-flight';
+        readonly record: IdempotencyRecord;
+    } | {
+        readonly status: 'duplicate';
+        readonly record: IdempotencyRecord;
+    };
+    /**
+     * Mark a previously recorded key as `completed` and cache the result.
+     *
+     * No-op if the key is not in the store (e.g. evicted before completion).
+     *
+     * @param key    - Idempotency key.
+     * @param result - Optional result to cache for duplicate callers.
+     */
+    markComplete(key: string, result?: unknown): void;
+    /**
+     * Mark a previously recorded key as `failed`, allowing a subsequent retry.
+     *
+     * The record transitions from `in-flight` → `failed`. On the next call to
+     * `checkAndRecord` with the same key the failed record is deleted and the
+     * caller receives `'new'`, allowing a fresh retry.
+     *
+     * No-op if the key is not in the store.
+     *
+     * @param key - Idempotency key.
+     */
+    markFailed(key: string): void;
+    /**
+     * Look up a record by key without changing its state.
+     *
+     * @param key - Idempotency key.
+     * @returns The record, or `undefined` if not found or already evicted.
+     */
+    getRecord(key: string): IdempotencyRecord | undefined;
+    /**
+     * Returns the current number of records in the store (including in-flight).
+     */
+    get size(): number;
+    /**
+     * Evict completed and failed records whose age exceeds the configured TTL.
+     *
+     * Called automatically by `checkAndRecord` when the store is near capacity.
+     * May also be called explicitly (e.g. on a periodic timer).
+     *
+     * In-flight records are never evicted.
+     */
+    sweep(): void;
+    /** Trigger a sweep when the store reaches 80% of the configured maximum. */
+    private _maybeSweep;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/platform/runtime/idempotency/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/platform/runtime/idempotency/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,KAAK,EACV,qBAAqB,EACrB,iBAAiB,EACjB,sBAAsB,EACvB,MAAM,YAAY,CAAC;AAEpB,YAAY,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AACnG,YAAY,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAQpD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAwC;IAC9D,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;gBAExB,MAAM,GAAE,sBAA2B;IAS/C;;;;;;;;OAQG;IACH,WAAW,CAAC,OAAO,EAAE,qBAAqB,GAAG,MAAM;IAUnD;;;;;;;;;OASG;IACH,cAAc,CACZ,GAAG,EAAE,MAAM,GAET;QAAE,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAA;KAAE,GAC1B;QAAE,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAA;KAAE,GACpE;QAAE,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAA;KAAE;IA4BxE;;;;;;;OAOG;IACH,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,GAAG,IAAI;IAUjD;;;;;;;;;;OAUG;IACH,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAW7B;;;;;OAKG;IACH,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS;IAIrD;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAMD;;;;;;;OAOG;IACH,KAAK,IAAI,IAAI;IAcb,4EAA4E;IAC5E,OAAO,CAAC,WAAW;CAKpB"}

package/dist/platform/runtime/idempotency/index.js

@@ -0,0 +1,193 @@
+/**
+ * Idempotency — store and key generation.
+ *
+ * Provides an in-process idempotency store for tool-call deduplication across
+ * replay, reconnect, and restart scenarios. Keys are deterministic (derived from
+ * session + turn + call identifiers) so the same logical call always maps to the
+ * same key regardless of when it is submitted.
+ *
+ * Lifecycle:
+ *   1. Before executing a tool, call `checkAndRecord(key)`.
+ *      - `'new'`       → proceed with execution.
+ *      - `'in-flight'` → a prior submission is still running; reject or wait.
+ *      - `'duplicate'` → a prior submission completed; return cached result.
+ *   2. On success, call `markComplete(key, result)` to cache the result.
+ *   3. On failure, call `markFailed(key)` to allow a retry on the next attempt.
+ *
+ * TTL-based eviction runs automatically whenever the store exceeds `maxRecords`.
+ * In-flight records are never evicted.
+ */
+import { createHash } from 'node:crypto';
+/** Default TTL: 5 minutes. */
+const DEFAULT_TTL_MS = 5 * 60 * 1_000;
+/** Default maximum stored records before eviction sweep. */
+const DEFAULT_MAX_RECORDS = 5_000;
+/**
+ * IdempotencyStore — bounded, TTL-evicted in-process store.
+ *
+ * Thread safety: Node.js is single-threaded; no locking is required.
+ * Suitable for in-process use within a single runtime session.
+ *
+ * @example
+ * ```ts
+ * const store = new IdempotencyStore({ ttlMs: 5 * 60_000 });
+ * const key = store.generateKey({ sessionId, turnId, callId });
+ * const check = store.checkAndRecord(key);
+ * if (check.status === 'new') {
+ *   const result = await doWork();
+ *   store.markComplete(key, result);
+ *   return result;
+ * } else if (check.status === 'duplicate') {
+ *   return check.record.result; // cached
+ * } else {
+ *   throw new Error('Tool call already in-flight');
+ * }
+ * ```
+ */
+export class IdempotencyStore {
+    store = new Map();
+    ttlMs;
+    maxRecords;
+    constructor(config = {}) {
+        this.ttlMs = config.ttlMs ?? DEFAULT_TTL_MS;
+        this.maxRecords = config.maxRecords ?? DEFAULT_MAX_RECORDS;
+    }
+    // ---------------------------------------------------------------------------
+    // Key generation
+    // ---------------------------------------------------------------------------
+    /**
+     * Generate a deterministic idempotency key from a call context.
+     *
+     * Uses a SHA-256 hash of `sessionId:turnId:callId` to produce a compact,
+     * collision-resistant key that is stable across restarts (given the same inputs).
+     *
+     * @param context - Session, turn, and call identifiers.
+     * @returns Hex-encoded SHA-256 digest (64 characters).
+     */
+    generateKey(context) {
+        return createHash('sha256')
+            .update(`${context.sessionId}:${context.turnId}:${context.callId}`)
+            .digest('hex');
+    }
+    // ---------------------------------------------------------------------------
+    // Core operations
+    // ---------------------------------------------------------------------------
+    /**
+     * Check whether a key has been seen before and record it as `in-flight` if new.
+     *
+     * Returns a discriminated union:
+     * - `{ status: 'new' }`        — key is unseen; record created and marked in-flight.
+     * - `{ status: 'in-flight' }`  — a prior submission is still running.
+     * - `{ status: 'duplicate', record }` — prior submission completed; record holds cached result.
+     *
+     * @param key - Idempotency key from `generateKey`.
+     */
+    checkAndRecord(key) {
+        const existing = this.store.get(key);
+        if (existing) {
+            if (existing.status === 'in-flight') {
+                return { status: 'in-flight', record: existing };
+            }
+            if (existing.status === 'failed') {
+                // Failed records allow retry — delete and fall through to register as new.
+                this.store.delete(key);
+            }
+            else {
+                // completed — return cached result to duplicate callers
+                return { status: 'duplicate', record: existing };
+            }
+        }
+        // New key — record as in-flight
+        const record = {
+            key,
+            status: 'in-flight',
+            createdAt: Date.now(),
+        };
+        this.store.set(key, record);
+        this._maybeSweep();
+        return { status: 'new' };
+    }
+    /**
+     * Mark a previously recorded key as `completed` and cache the result.
+     *
+     * No-op if the key is not in the store (e.g. evicted before completion).
+     *
+     * @param key    - Idempotency key.
+     * @param result - Optional result to cache for duplicate callers.
+     */
+    markComplete(key, result) {
+        const record = this.store.get(key);
+        if (!record)
+            return; // evicted — treat as best-effort
+        record.status = 'completed';
+        record.completedAt = Date.now();
+        if (result !== undefined) {
+            record.result = result;
+        }
+    }
+    /**
+     * Mark a previously recorded key as `failed`, allowing a subsequent retry.
+     *
+     * The record transitions from `in-flight` → `failed`. On the next call to
+     * `checkAndRecord` with the same key the failed record is deleted and the
+     * caller receives `'new'`, allowing a fresh retry.
+     *
+     * No-op if the key is not in the store.
+     *
+     * @param key - Idempotency key.
+     */
+    markFailed(key) {
+        const record = this.store.get(key);
+        if (!record)
+            return;
+        record.status = 'failed';
+        record.completedAt = Date.now();
+    }
+    // ---------------------------------------------------------------------------
+    // Inspection
+    // ---------------------------------------------------------------------------
+    /**
+     * Look up a record by key without changing its state.
+     *
+     * @param key - Idempotency key.
+     * @returns The record, or `undefined` if not found or already evicted.
+     */
+    getRecord(key) {
+        return this.store.get(key);
+    }
+    /**
+     * Returns the current number of records in the store (including in-flight).
+     */
+    get size() {
+        return this.store.size;
+    }
+    // ---------------------------------------------------------------------------
+    // TTL eviction
+    // ---------------------------------------------------------------------------
+    /**
+     * Evict completed and failed records whose age exceeds the configured TTL.
+     *
+     * Called automatically by `checkAndRecord` when the store is near capacity.
+     * May also be called explicitly (e.g. on a periodic timer).
+     *
+     * In-flight records are never evicted.
+     */
+    sweep() {
+        const now = Date.now();
+        const cutoff = now - this.ttlMs;
+        for (const [key, record] of this.store) {
+            if (record.status !== 'in-flight' && record.createdAt < cutoff) {
+                this.store.delete(key);
+            }
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Private helpers
+    // ---------------------------------------------------------------------------
+    /** Trigger a sweep when the store reaches 80% of the configured maximum. */
+    _maybeSweep() {
+        if (this.store.size >= Math.floor(this.maxRecords * 0.8)) {
+            this.sweep();
+        }
+    }
+}