pi-app-server 0.1.0

package/dist/command-execution-engine.js

@@ -0,0 +1,259 @@
+import { getSessionId } from "./types.js";
+import { getCommandTimeoutPolicy } from "./command-classification.js";
+const DEFAULT_COMMAND_TIMEOUT_MS = 5 * 60 * 1e3;
+const SHORT_COMMAND_TIMEOUT_MS = 30 * 1e3;
+const DEFAULT_DEPENDENCY_WAIT_TIMEOUT_MS = 30 * 1e3;
+const DEFAULT_ABORT_HANDLERS = {
+  prompt: (session) => session.abort(),
+  steer: (session) => session.abort(),
+  follow_up: (session) => session.abort(),
+  compact: (session) => session.abortCompaction(),
+  bash: (session) => session.abortBash(),
+  new_session: (session) => session.abort(),
+  switch_session_file: (session) => session.abort(),
+  fork: (session) => session.abort()
+};
+function withTimeout(promise, timeoutMs, commandType, onTimeout) {
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const timer = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      let onTimeoutPromise;
+      try {
+        onTimeoutPromise = Promise.resolve(onTimeout?.());
+      } catch {
+        onTimeoutPromise = Promise.resolve();
+      }
+      onTimeoutPromise.catch(() => {
+      }).finally(() => {
+        reject(new Error(`Command '${commandType}' timed out after ${timeoutMs}ms`));
+      });
+    }, timeoutMs);
+    promise.then((result) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve(result);
+    }).catch((error) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      reject(error);
+    });
+  });
+}
+class CommandExecutionEngine {
+  /** Deterministic per-lane command serialization tails. */
+  laneTails = /* @__PURE__ */ new Map();
+  replayStore;
+  versionStore;
+  sessionResolver;
+  abortHandlers;
+  defaultCommandTimeoutMs;
+  shortCommandTimeoutMs;
+  dependencyWaitTimeoutMs;
+  constructor(replayStore, versionStore, sessionResolver, options = {}) {
+    this.replayStore = replayStore;
+    this.versionStore = versionStore;
+    this.sessionResolver = sessionResolver;
+    this.abortHandlers = { ...DEFAULT_ABORT_HANDLERS, ...options.abortHandlers };
+    this.defaultCommandTimeoutMs = typeof options.defaultCommandTimeoutMs === "number" && options.defaultCommandTimeoutMs > 0 ? options.defaultCommandTimeoutMs : DEFAULT_COMMAND_TIMEOUT_MS;
+    this.shortCommandTimeoutMs = typeof options.shortCommandTimeoutMs === "number" && options.shortCommandTimeoutMs > 0 ? options.shortCommandTimeoutMs : SHORT_COMMAND_TIMEOUT_MS;
+    this.dependencyWaitTimeoutMs = typeof options.dependencyWaitTimeoutMs === "number" && options.dependencyWaitTimeoutMs > 0 ? options.dependencyWaitTimeoutMs : DEFAULT_DEPENDENCY_WAIT_TIMEOUT_MS;
+  }
+  /**
+   * Get statistics about the execution engine state.
+   */
+  getStats() {
+    return { laneCount: this.laneTails.size };
+  }
+  // ==========================================================================
+  // LANE SERIALIZATION
+  // ==========================================================================
+  /**
+   * Get the lane key for a command.
+   * Session commands serialize per-session; server commands serialize together.
+   */
+  getLaneKey(command) {
+    const sessionId = getSessionId(command);
+    if (sessionId) return `session:${sessionId}`;
+    return "server";
+  }
+  /**
+   * Run a task in a deterministic serialized lane.
+   * Commands in the same lane execute sequentially.
+   */
+  async runOnLane(laneKey, task) {
+    const previousTail = this.laneTails.get(laneKey) ?? Promise.resolve();
+    let releaseCurrent;
+    const currentTail = new Promise((resolve) => {
+      releaseCurrent = resolve;
+    });
+    const laneTail = previousTail.then(
+      () => currentTail,
+      () => currentTail
+    );
+    this.laneTails.set(laneKey, laneTail);
+    await previousTail.catch((error) => {
+      if (error !== void 0) {
+        console.error(`[CommandExecutionEngine] Previous lane task failed for ${laneKey}:`, error);
+      }
+    });
+    try {
+      return await task();
+    } finally {
+      releaseCurrent?.();
+      if (this.laneTails.get(laneKey) === laneTail) {
+        this.laneTails.delete(laneKey);
+      }
+    }
+  }
+  // ==========================================================================
+  // DEPENDENCY RESOLUTION
+  // ==========================================================================
+  /**
+   * Wait for dependency commands to complete.
+   * Returns error if any dependency fails or times out.
+   *
+   * Note: Cross-lane dependency cycles (A→B, B→A) are detected by timeout
+   * rather than explicit cycle detection. This is acceptable because:
+   * 1. Cross-lane dependencies are rare
+   * 2. The dependencyWaitTimeoutMs (default 30s) prevents indefinite deadlock
+   * 3. Same-lane cycles are explicitly detected below
+   */
+  async awaitDependencies(dependsOn, laneKey) {
+    for (const dependencyId of dependsOn) {
+      if (!dependencyId) {
+        return { ok: false, error: "Dependency ID must be non-empty" };
+      }
+      const inFlight = this.replayStore.getInFlight(dependencyId);
+      if (inFlight) {
+        if (inFlight.laneKey === laneKey) {
+          return {
+            ok: false,
+            error: `Dependency '${dependencyId}' is queued in the same lane and cannot be awaited from this command`
+          };
+        }
+        try {
+          const dependencyResponse = await withTimeout(
+            inFlight.promise,
+            this.dependencyWaitTimeoutMs,
+            `dependsOn:${dependencyId}`
+          );
+          if (!dependencyResponse.success) {
+            return {
+              ok: false,
+              error: `Dependency '${dependencyId}' failed: ${dependencyResponse.error ?? "unknown error"}`
+            };
+          }
+          continue;
+        } catch (error) {
+          return {
+            ok: false,
+            error: error instanceof Error ? error.message : String(error)
+          };
+        }
+      }
+      const completed = this.replayStore.getCommandOutcome(dependencyId);
+      if (!completed) {
+        return { ok: false, error: `Dependency '${dependencyId}' is unknown` };
+      }
+      if (!completed.success) {
+        return {
+          ok: false,
+          error: `Dependency '${dependencyId}' failed: ${completed.error ?? "unknown error"}`
+        };
+      }
+    }
+    return { ok: true };
+  }
+  // ==========================================================================
+  // TIMEOUT MANAGEMENT
+  // ==========================================================================
+  /**
+   * Resolve timeout policy for a command.
+   * Returns null for commands that cannot be safely cancelled.
+   */
+  getCommandTimeoutMs(commandType) {
+    return getCommandTimeoutPolicy(commandType, {
+      defaultTimeoutMs: this.defaultCommandTimeoutMs,
+      shortTimeoutMs: this.shortCommandTimeoutMs
+    });
+  }
+  /**
+   * Best-effort cancellation for timed-out commands.
+   * Uses configured abort handlers (defaults + custom overrides).
+   */
+  async abortTimedOutCommand(command) {
+    const sessionId = getSessionId(command);
+    if (!sessionId) return;
+    const session = this.sessionResolver.getSession(sessionId);
+    if (!session) return;
+    const abortHandler = this.abortHandlers[command.type];
+    if (!abortHandler) return;
+    try {
+      await Promise.resolve(abortHandler(session));
+    } catch (error) {
+      console.error(
+        `[timeout] Failed to abort timed out command '${command.type}' for session ${sessionId}:`,
+        error
+      );
+    }
+  }
+  /**
+   * Execute a command with timeout.
+   */
+  async executeWithTimeout(commandType, promise, command) {
+    const timeoutMs = this.getCommandTimeoutMs(commandType);
+    if (timeoutMs === null) {
+      return promise;
+    }
+    return withTimeout(promise, timeoutMs, commandType, () => this.abortTimedOutCommand(command));
+  }
+  // ==========================================================================
+  // VERSION CHECKS
+  // ==========================================================================
+  /**
+   * Check if a session version matches the expected version.
+   * Returns error object if mismatch, undefined if OK.
+   *
+   * @param sessionId - The session to check
+   * @param ifSessionVersion - The expected version
+   * @param commandType - The command type for error context (preserves caller's context)
+   */
+  checkSessionVersion(sessionId, ifSessionVersion, commandType) {
+    const current = this.versionStore.getVersion(sessionId);
+    if (current === void 0) {
+      return {
+        type: "response",
+        command: commandType,
+        success: false,
+        error: `Session ${sessionId} not found for ifSessionVersion=${ifSessionVersion}`
+      };
+    }
+    if (current !== ifSessionVersion) {
+      return {
+        type: "response",
+        command: commandType,
+        success: false,
+        error: `Session version mismatch: expected ${ifSessionVersion}, got ${current}`
+      };
+    }
+    return void 0;
+  }
+  // ==========================================================================
+  // LIFECYCLE
+  // ==========================================================================
+  /**
+   * Clear all lane state (used during disposal).
+   */
+  clear() {
+    this.laneTails.clear();
+  }
+}
+export {
+  CommandExecutionEngine,
+  withTimeout
+};
+//# sourceMappingURL=command-execution-engine.js.map

package/dist/command-execution-engine.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/command-execution-engine.ts"],
+  "sourcesContent": ["/**\n * Command Execution Engine - manages lane serialization, dependency waits, and timeouts.\n *\n * Responsibilities:\n * - Deterministic per-lane command serialization\n * - Dependency resolution with timeout\n * - Command timeout orchestration with abort hooks\n * - Lifecycle event emission\n */\n\nimport type { AgentSession } from \"@mariozechner/pi-coding-agent\";\nimport type { RpcCommand, RpcResponse, SessionResolver } from \"./types.js\";\nimport { getSessionId } from \"./types.js\";\nimport type { CommandReplayStore } from \"./command-replay-store.js\";\nimport type { SessionVersionStore } from \"./session-version-store.js\";\nimport { getCommandTimeoutPolicy } from \"./command-classification.js\";\n\n/** Default timeout for session commands (5 minutes for LLM operations) */\nconst DEFAULT_COMMAND_TIMEOUT_MS = 5 * 60 * 1000;\n\n/** Short command timeout (30 seconds) */\nconst SHORT_COMMAND_TIMEOUT_MS = 30 * 1000;\n\n/** Max time to wait for a dependency command to complete. */\nconst DEFAULT_DEPENDENCY_WAIT_TIMEOUT_MS = 30 * 1000;\n\n/**\n * Abort handler for a specific command type.\n * Called when a command times out to attempt cancellation.\n */\nexport type AbortHandler = (session: AgentSession) => void | Promise<void>;\n\n/**\n * Default abort handlers for built-in command types.\n * Maps command types to their abort methods on AgentSession.\n */\nconst DEFAULT_ABORT_HANDLERS: Partial<Record<string, AbortHandler>> = {\n  prompt: (session) => session.abort(),\n  steer: (session) => session.abort(),\n  follow_up: (session) => session.abort(),\n  compact: (session) => session.abortCompaction(),\n  bash: (session) => session.abortBash(),\n  new_session: (session) => session.abort(),\n  switch_session_file: (session) => session.abort(),\n  fork: (session) => session.abort(),\n};\n\n/**\n * Wrap a promise with a timeout.\n * Returns the promise result or throws on timeout.\n */\nexport function withTimeout<T>(\n  promise: Promise<T>,\n  timeoutMs: number,\n  commandType: string,\n  onTimeout?: () => void | Promise<void>\n): Promise<T> {\n  return new Promise<T>((resolve, reject) => {\n    let settled = false;\n\n    const timer = setTimeout(() => {\n      if (settled) return;\n      settled = true;\n\n      // Wrap onTimeout in try-catch to handle both sync and async errors\n      let onTimeoutPromise: Promise<void>;\n      try {\n        onTimeoutPromise = Promise.resolve(onTimeout?.());\n      } catch {\n        onTimeoutPromise = Promise.resolve();\n      }\n\n      onTimeoutPromise\n        .catch(() => {\n          // Ignore cancellation hook errors; timeout response still returned.\n        })\n        .finally(() => {\n          reject(new Error(`Command '${commandType}' timed out after ${timeoutMs}ms`));\n        });\n    }, timeoutMs);\n\n    promise\n      .then((result) => {\n        if (settled) return;\n        settled = true;\n        clearTimeout(timer);\n        resolve(result);\n      })\n      .catch((error) => {\n        if (settled) return;\n        settled = true;\n        clearTimeout(timer);\n        reject(error);\n      });\n  });\n}\n\n/**\n * Configuration options for the execution engine.\n */\nexport interface ExecutionEngineOptions {\n  defaultCommandTimeoutMs?: number;\n  shortCommandTimeoutMs?: number;\n  dependencyWaitTimeoutMs?: number;\n  /** Custom abort handlers for command types (extends defaults) */\n  abortHandlers?: Partial<Record<string, AbortHandler>>;\n}\n\n/**\n * Command Execution Engine - manages lane serialization and dependency waits.\n *\n * Extracted from PiSessionManager to isolate:\n * - Per-lane command serialization\n * - Dependency resolution with timeout\n * - Command timeout with abort hooks\n */\nexport class CommandExecutionEngine {\n  /** Deterministic per-lane command serialization tails. */\n  private laneTails = new Map<string, Promise<void>>();\n\n  private readonly replayStore: CommandReplayStore;\n  private readonly versionStore: SessionVersionStore;\n  private readonly sessionResolver: SessionResolver;\n  private readonly abortHandlers: Partial<Record<string, AbortHandler>>;\n\n  private readonly defaultCommandTimeoutMs: number;\n  private readonly shortCommandTimeoutMs: number;\n  private readonly dependencyWaitTimeoutMs: number;\n\n  constructor(\n    replayStore: CommandReplayStore,\n    versionStore: SessionVersionStore,\n    sessionResolver: SessionResolver,\n    options: ExecutionEngineOptions = {}\n  ) {\n    this.replayStore = replayStore;\n    this.versionStore = versionStore;\n    this.sessionResolver = sessionResolver;\n\n    // Merge custom abort handlers with defaults (custom takes precedence)\n    this.abortHandlers = { ...DEFAULT_ABORT_HANDLERS, ...options.abortHandlers };\n\n    this.defaultCommandTimeoutMs =\n      typeof options.defaultCommandTimeoutMs === \"number\" && options.defaultCommandTimeoutMs > 0\n        ? options.defaultCommandTimeoutMs\n        : DEFAULT_COMMAND_TIMEOUT_MS;\n    this.shortCommandTimeoutMs =\n      typeof options.shortCommandTimeoutMs === \"number\" && options.shortCommandTimeoutMs > 0\n        ? options.shortCommandTimeoutMs\n        : SHORT_COMMAND_TIMEOUT_MS;\n    this.dependencyWaitTimeoutMs =\n      typeof options.dependencyWaitTimeoutMs === \"number\" && options.dependencyWaitTimeoutMs > 0\n        ? options.dependencyWaitTimeoutMs\n        : DEFAULT_DEPENDENCY_WAIT_TIMEOUT_MS;\n  }\n\n  /**\n   * Get statistics about the execution engine state.\n   */\n  getStats(): { laneCount: number } {\n    return { laneCount: this.laneTails.size };\n  }\n\n  // ==========================================================================\n  // LANE SERIALIZATION\n  // ==========================================================================\n\n  /**\n   * Get the lane key for a command.\n   * Session commands serialize per-session; server commands serialize together.\n   */\n  getLaneKey(command: RpcCommand): string {\n    const sessionId = getSessionId(command);\n    if (sessionId) return `session:${sessionId}`;\n    return \"server\";\n  }\n\n  /**\n   * Run a task in a deterministic serialized lane.\n   * Commands in the same lane execute sequentially.\n   */\n  async runOnLane<T>(laneKey: string, task: () => Promise<T>): Promise<T> {\n    const previousTail = this.laneTails.get(laneKey) ?? Promise.resolve();\n\n    let releaseCurrent: (() => void) | undefined;\n    const currentTail = new Promise<void>((resolve) => {\n      releaseCurrent = resolve;\n    });\n\n    // Store the lane tail promise for later comparison\n    const laneTail = previousTail.then(\n      () => currentTail,\n      () => currentTail\n    );\n    this.laneTails.set(laneKey, laneTail);\n\n    await previousTail.catch((error) => {\n      // Previous command failure should not break lane sequencing.\n      // Log for observability but continue.\n      if (error !== undefined) {\n        console.error(`[CommandExecutionEngine] Previous lane task failed for ${laneKey}:`, error);\n      }\n    });\n\n    try {\n      return await task();\n    } finally {\n      releaseCurrent?.();\n      // Only delete if our lane tail is still the current one (not replaced by another task)\n      if (this.laneTails.get(laneKey) === laneTail) {\n        this.laneTails.delete(laneKey);\n      }\n    }\n  }\n\n  // ==========================================================================\n  // DEPENDENCY RESOLUTION\n  // ==========================================================================\n\n  /**\n   * Wait for dependency commands to complete.\n   * Returns error if any dependency fails or times out.\n   *\n   * Note: Cross-lane dependency cycles (A\u2192B, B\u2192A) are detected by timeout\n   * rather than explicit cycle detection. This is acceptable because:\n   * 1. Cross-lane dependencies are rare\n   * 2. The dependencyWaitTimeoutMs (default 30s) prevents indefinite deadlock\n   * 3. Same-lane cycles are explicitly detected below\n   */\n  async awaitDependencies(\n    dependsOn: string[],\n    laneKey: string\n  ): Promise<{ ok: true } | { ok: false; error: string }> {\n    for (const dependencyId of dependsOn) {\n      if (!dependencyId) {\n        return { ok: false, error: \"Dependency ID must be non-empty\" };\n      }\n\n      const inFlight = this.replayStore.getInFlight(dependencyId);\n      if (inFlight) {\n        // Same-lane check: commands in the same lane execute sequentially,\n        // so waiting for a same-lane dependency would deadlock\n        if (inFlight.laneKey === laneKey) {\n          return {\n            ok: false,\n            error: `Dependency '${dependencyId}' is queued in the same lane and cannot be awaited from this command`,\n          };\n        }\n\n        try {\n          const dependencyResponse = await withTimeout(\n            inFlight.promise,\n            this.dependencyWaitTimeoutMs,\n            `dependsOn:${dependencyId}`\n          );\n          if (!dependencyResponse.success) {\n            return {\n              ok: false,\n              error: `Dependency '${dependencyId}' failed: ${dependencyResponse.error ?? \"unknown error\"}`,\n            };\n          }\n          continue;\n        } catch (error) {\n          return {\n            ok: false,\n            error: error instanceof Error ? error.message : String(error),\n          };\n        }\n      }\n\n      const completed = this.replayStore.getCommandOutcome(dependencyId);\n      if (!completed) {\n        return { ok: false, error: `Dependency '${dependencyId}' is unknown` };\n      }\n\n      if (!completed.success) {\n        return {\n          ok: false,\n          error: `Dependency '${dependencyId}' failed: ${completed.error ?? \"unknown error\"}`,\n        };\n      }\n    }\n\n    return { ok: true };\n  }\n\n  // ==========================================================================\n  // TIMEOUT MANAGEMENT\n  // ==========================================================================\n\n  /**\n   * Resolve timeout policy for a command.\n   * Returns null for commands that cannot be safely cancelled.\n   */\n  getCommandTimeoutMs(commandType: string): number | null {\n    return getCommandTimeoutPolicy(commandType, {\n      defaultTimeoutMs: this.defaultCommandTimeoutMs,\n      shortTimeoutMs: this.shortCommandTimeoutMs,\n    });\n  }\n\n  /**\n   * Best-effort cancellation for timed-out commands.\n   * Uses configured abort handlers (defaults + custom overrides).\n   */\n  async abortTimedOutCommand(command: RpcCommand): Promise<void> {\n    const sessionId = getSessionId(command);\n    if (!sessionId) return;\n\n    const session = this.sessionResolver.getSession(sessionId);\n    if (!session) return;\n\n    const abortHandler = this.abortHandlers[command.type];\n    if (!abortHandler) return;\n\n    try {\n      await Promise.resolve(abortHandler(session));\n    } catch (error) {\n      console.error(\n        `[timeout] Failed to abort timed out command '${command.type}' for session ${sessionId}:`,\n        error\n      );\n    }\n  }\n\n  /**\n   * Execute a command with timeout.\n   */\n  async executeWithTimeout(\n    commandType: string,\n    promise: Promise<RpcResponse>,\n    command: RpcCommand\n  ): Promise<RpcResponse> {\n    const timeoutMs = this.getCommandTimeoutMs(commandType);\n\n    if (timeoutMs === null) {\n      return promise;\n    }\n\n    return withTimeout(promise, timeoutMs, commandType, () => this.abortTimedOutCommand(command));\n  }\n\n  // ==========================================================================\n  // VERSION CHECKS\n  // ==========================================================================\n\n  /**\n   * Check if a session version matches the expected version.\n   * Returns error object if mismatch, undefined if OK.\n   *\n   * @param sessionId - The session to check\n   * @param ifSessionVersion - The expected version\n   * @param commandType - The command type for error context (preserves caller's context)\n   */\n  checkSessionVersion(\n    sessionId: string,\n    ifSessionVersion: number,\n    commandType: string\n  ): { type: \"response\"; command: string; success: false; error: string } | undefined {\n    const current = this.versionStore.getVersion(sessionId);\n    if (current === undefined) {\n      return {\n        type: \"response\",\n        command: commandType,\n        success: false,\n        error: `Session ${sessionId} not found for ifSessionVersion=${ifSessionVersion}`,\n      };\n    }\n    if (current !== ifSessionVersion) {\n      return {\n        type: \"response\",\n        command: commandType,\n        success: false,\n        error: `Session version mismatch: expected ${ifSessionVersion}, got ${current}`,\n      };\n    }\n    return undefined;\n  }\n\n  // ==========================================================================\n  // LIFECYCLE\n  // ==========================================================================\n\n  /**\n   * Clear all lane state (used during disposal).\n   */\n  clear(): void {\n    this.laneTails.clear();\n  }\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/command-replay-store.d.ts

@@ -0,0 +1,241 @@
+/**
+ * Command Replay Store - manages idempotency, duplicate detection, and outcome history.
+ *
+ * Responsibilities:
+ * - Idempotency key replay (cached responses for retry safety)
+ * - Command ID deduplication (completed outcomes + in-flight tracking)
+ * - Fingerprint conflict detection (prevent same ID with different payload)
+ * - Bounded outcome retention (LRU-style trimming)
+ */
+import type { RpcCommand, RpcResponse } from "./types.js";
+/** Reserved prefix for server-generated command IDs. Client IDs matching this are rejected. */
+export declare const SYNTHETIC_ID_PREFIX = "anon:";
+/**
+ * Record of a completed command execution.
+ * Used for dependency resolution and duplicate-id replay.
+ */
+export interface CommandOutcomeRecord {
+    commandId: string;
+    commandType: string;
+    laneKey: string;
+    fingerprint: string;
+    success: boolean;
+    error?: string;
+    response: RpcResponse;
+    sessionVersion?: number;
+    finishedAt: number;
+}
+/**
+ * Record of an in-flight command execution.
+ * Used for dependency waits and duplicate-id replay.
+ */
+export interface InFlightCommandRecord {
+    commandType: string;
+    laneKey: string;
+    fingerprint: string;
+    promise: Promise<RpcResponse>;
+}
+/**
+ * Input for caching an idempotency result.
+ */
+export interface IdempotencyCacheInput {
+    command: RpcCommand;
+    idempotencyKey: string;
+    commandType: string;
+    fingerprint: string;
+    response: RpcResponse;
+}
+export interface IdempotencyCacheEntry {
+    expiresAt: number;
+    commandType: string;
+    fingerprint: string;
+    response: RpcResponse;
+}
+/**
+ * Result of checking for replay conflicts.
+ *
+ * This discriminated union enables type-safe handling of all replay scenarios:
+ *
+ * - `proceed`: No replay possible, execute the command normally
+ * - `conflict`: Fingerprint mismatch - same ID/key but different payload
+ * - `replay_cached`: Found cached response, return it immediately
+ * - `replay_inflight`: Command with same ID is executing, await its promise
+ *
+ * @example
+ * ```typescript
+ * const result = store.checkReplay(command, fingerprint);
+ * switch (result.kind) {
+ *   case "proceed": // execute normally
+ *   case "conflict": return result.response; // error response
+ *   case "replay_cached": return result.response; // cached response
+ *   case "replay_inflight": return await result.promise; // wait for in-flight
+ * }
+ * ```
+ */
+export type ReplayCheckResult = {
+    kind: "proceed";
+} | {
+    kind: "conflict";
+    response: RpcResponse;
+} | {
+    kind: "replay_cached";
+    response: RpcResponse;
+} | {
+    kind: "replay_inflight";
+    promise: Promise<RpcResponse>;
+};
+/**
+ * Configuration options for the replay store.
+ */
+export interface ReplayStoreOptions {
+    idempotencyTtlMs?: number;
+    maxCommandOutcomes?: number;
+    /** Maximum in-flight commands to track. Excess is rejected (ADR-0001: reject, don't evict). */
+    maxInFlightCommands?: number;
+}
+/**
+ * Statistics about store state for monitoring.
+ */
+export interface ReplayStoreStats {
+    /** Number of in-flight commands being tracked */
+    inFlightCount: number;
+    /** Number of completed command outcomes stored */
+    outcomeCount: number;
+    /** Number of idempotency cache entries */
+    idempotencyCacheSize: number;
+    /** Maximum configured in-flight commands */
+    maxInFlightCommands: number;
+    /** Maximum configured command outcomes */
+    maxCommandOutcomes: number;
+    /** Count of in-flight rejections due to exceeding max (ADR-0001: reject, don't evict) */
+    inFlightRejections: number;
+}
+/**
+ * Command Replay Store - manages idempotency and duplicate detection.
+ *
+ * Extracted from PiSessionManager to isolate:
+ * - Replay semantics (idempotency keys, command IDs)
+ * - Fingerprint conflict detection
+ * - Bounded outcome history
+ */
+export declare class CommandReplayStore {
+    /** In-flight commands by command id (for dependency waits and duplicate-id replay). */
+    private commandInFlightById;
+    /** Insertion order for in-flight commands (for bounded eviction). */
+    private inFlightOrder;
+    /** Completed command outcomes (for dependency checks and duplicate-id replay). */
+    private commandOutcomes;
+    /** Bounded insertion order to trim commandOutcomes memory. */
+    private commandOutcomeOrder;
+    /** Idempotency replay cache. */
+    private idempotencyCache;
+    /** Sequence for synthetic command IDs when client omits id. */
+    private syntheticCommandSequence;
+    /** Process start time for unique synthetic IDs that don't collide after clear(). */
+    private readonly processStartTime;
+    private readonly idempotencyTtlMs;
+    private readonly maxCommandOutcomes;
+    private readonly maxInFlightCommands;
+    private inFlightRejections;
+    constructor(options?: ReplayStoreOptions);
+    /**
+     * Get statistics about store state for monitoring.
+     */
+    getStats(): ReplayStoreStats;
+    /**
+     * Get or create a deterministic command ID.
+     * Returns explicit ID if provided, otherwise generates a synthetic one.
+     *
+     * Synthetic IDs use process-start-time + sequence to guarantee uniqueness:
+     * 1. Process start time distinguishes IDs across server restarts
+     * 2. Sequence guarantees uniqueness within a process lifetime
+     * 3. Clear() resets sequence but start time stays same (collision-safe within run)
+     *
+     * NOTE: This method has a side effect (increments sequence) when generating.
+     */
+    getOrCreateCommandId(command: RpcCommand): string;
+    /**
+     * Compute a fingerprint for conflict detection.
+     * Excludes retry identity fields (id, idempotencyKey) since those
+     * don't affect semantic equivalence - only determine replay mechanics.
+     */
+    getCommandFingerprint(command: RpcCommand): string;
+    /**
+     * Build a cache key for idempotency lookup.
+     */
+    private buildIdempotencyCacheKey;
+    /**
+     * Remove expired entries from the idempotency cache.
+     */
+    cleanupIdempotencyCache(now?: number): void;
+    /**
+     * Store a response in the idempotency cache.
+     */
+    cacheIdempotencyResult(input: IdempotencyCacheInput): void;
+    /**
+     * Trim old command outcomes to bound memory.
+     */
+    private trimCommandOutcomes;
+    /**
+     * Store a completed command outcome.
+     */
+    storeCommandOutcome(outcome: CommandOutcomeRecord): void;
+    /**
+     * Get a completed command outcome by ID.
+     */
+    getCommandOutcome(commandId: string): CommandOutcomeRecord | undefined;
+    /**
+     * Check whether an in-flight command can be tracked for this command ID.
+     *
+     * Returns true if:
+     * - the command ID is already tracked (replacement/update path), OR
+     * - there is free capacity for a new tracked command.
+     */
+    canRegisterInFlight(commandId: string): boolean;
+    /**
+     * Register an in-flight command.
+     *
+     * ADR-0001: Rejects when limit exceeded instead of evicting.
+     * Eviction breaks dependency chains - if command A depends on command B,
+     * and B is evicted, A fails with "unknown dependency". Rejection preserves
+     * correctness at the cost of temporary unavailability under load.
+     *
+     * @returns true if registered, false if limit exceeded
+     */
+    registerInFlight(commandId: string, record: InFlightCommandRecord): boolean;
+    /**
+     * Unregister an in-flight command.
+     * Only removes if the record matches (prevents race conditions).
+     */
+    unregisterInFlight(commandId: string, record: InFlightCommandRecord): void;
+    /**
+     * Get an in-flight command by ID.
+     */
+    getInFlight(commandId: string): InFlightCommandRecord | undefined;
+    /**
+     * Create a conflict response for fingerprint mismatch.
+     */
+    private createConflictResponse;
+    /**
+     * Clone a cached response for a new request.
+     * Preserves or strips ID based on whether the new request has one.
+     */
+    private cloneResponseForRequest;
+    /**
+     * Check for replay opportunities or conflicts.
+     *
+     * Call this BEFORE executing a command. Returns:
+     * - "proceed": No replay possible, execute normally
+     * - "conflict": Fingerprint mismatch, return error response
+     * - "replay_cached": Found cached response, return it (with replayed: true)
+     * - "replay_inflight": Found in-flight command, await its promise
+     */
+    checkReplay(command: RpcCommand, fingerprint: string): ReplayCheckResult;
+    /**
+     * Clear all state (used during disposal).
+     * Note: Does NOT reset syntheticCommandSequence to prevent ID collisions.
+     * Process start time ensures uniqueness even after clear.
+     */
+    clear(): void;
+}
+//# sourceMappingURL=command-replay-store.d.ts.map

package/dist/command-replay-store.d.ts.map

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