pi-app-server 0.1.0

package/dist/command-replay-store.js

@@ -0,0 +1,306 @@
+import { getCommandId, getCommandIdempotencyKey, getSessionId } from "./types.js";
+const DEFAULT_IDEMPOTENCY_TTL_MS = 10 * 60 * 1e3;
+const DEFAULT_MAX_COMMAND_OUTCOMES = 2e3;
+const DEFAULT_MAX_IN_FLIGHT_COMMANDS = 1e4;
+const SYNTHETIC_ID_PREFIX = "anon:";
+class CommandReplayStore {
+  /** In-flight commands by command id (for dependency waits and duplicate-id replay). */
+  commandInFlightById = /* @__PURE__ */ new Map();
+  /** Insertion order for in-flight commands (for bounded eviction). */
+  inFlightOrder = [];
+  /** Completed command outcomes (for dependency checks and duplicate-id replay). */
+  commandOutcomes = /* @__PURE__ */ new Map();
+  /** Bounded insertion order to trim commandOutcomes memory. */
+  commandOutcomeOrder = [];
+  /** Idempotency replay cache. */
+  idempotencyCache = /* @__PURE__ */ new Map();
+  /** Sequence for synthetic command IDs when client omits id. */
+  syntheticCommandSequence = 0;
+  /** Process start time for unique synthetic IDs that don't collide after clear(). */
+  processStartTime = Date.now();
+  idempotencyTtlMs;
+  maxCommandOutcomes;
+  maxInFlightCommands;
+  inFlightRejections = 0;
+  constructor(options = {}) {
+    this.idempotencyTtlMs = typeof options.idempotencyTtlMs === "number" && options.idempotencyTtlMs > 0 ? options.idempotencyTtlMs : DEFAULT_IDEMPOTENCY_TTL_MS;
+    this.maxCommandOutcomes = typeof options.maxCommandOutcomes === "number" && options.maxCommandOutcomes > 0 ? options.maxCommandOutcomes : DEFAULT_MAX_COMMAND_OUTCOMES;
+    this.maxInFlightCommands = typeof options.maxInFlightCommands === "number" && options.maxInFlightCommands > 0 ? options.maxInFlightCommands : DEFAULT_MAX_IN_FLIGHT_COMMANDS;
+  }
+  /**
+   * Get statistics about store state for monitoring.
+   */
+  getStats() {
+    return {
+      inFlightCount: this.commandInFlightById.size,
+      outcomeCount: this.commandOutcomes.size,
+      idempotencyCacheSize: this.idempotencyCache.size,
+      maxInFlightCommands: this.maxInFlightCommands,
+      maxCommandOutcomes: this.maxCommandOutcomes,
+      inFlightRejections: this.inFlightRejections
+    };
+  }
+  // ==========================================================================
+  // COMMAND ID GENERATION
+  // ==========================================================================
+  /**
+   * 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) {
+    const explicitId = getCommandId(command);
+    if (explicitId) return explicitId;
+    this.syntheticCommandSequence += 1;
+    return `${SYNTHETIC_ID_PREFIX}${this.processStartTime}:${this.syntheticCommandSequence}`;
+  }
+  // ==========================================================================
+  // FINGERPRINTING
+  // ==========================================================================
+  /**
+   * 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) {
+    const { id: _id, idempotencyKey: _key, ...rest } = command;
+    return JSON.stringify(rest);
+  }
+  // ==========================================================================
+  // IDEMPOTENCY KEY CACHE
+  // ==========================================================================
+  /**
+   * Build a cache key for idempotency lookup.
+   */
+  buildIdempotencyCacheKey(command, key) {
+    const sessionId = getSessionId(command) ?? "_server_";
+    return `${sessionId}:${key}`;
+  }
+  /**
+   * Remove expired entries from the idempotency cache.
+   */
+  cleanupIdempotencyCache(now = Date.now()) {
+    for (const [key, entry] of this.idempotencyCache) {
+      if (entry.expiresAt <= now) {
+        this.idempotencyCache.delete(key);
+      }
+    }
+  }
+  /**
+   * Store a response in the idempotency cache.
+   */
+  cacheIdempotencyResult(input) {
+    const cacheKey = this.buildIdempotencyCacheKey(input.command, input.idempotencyKey);
+    this.idempotencyCache.set(cacheKey, {
+      expiresAt: Date.now() + this.idempotencyTtlMs,
+      commandType: input.commandType,
+      fingerprint: input.fingerprint,
+      response: input.response
+    });
+  }
+  // ==========================================================================
+  // COMMAND OUTCOMES
+  // ==========================================================================
+  /**
+   * Trim old command outcomes to bound memory.
+   */
+  trimCommandOutcomes() {
+    while (this.commandOutcomeOrder.length > this.maxCommandOutcomes) {
+      const oldest = this.commandOutcomeOrder.shift();
+      if (!oldest) break;
+      this.commandOutcomes.delete(oldest);
+    }
+  }
+  /**
+   * Store a completed command outcome.
+   */
+  storeCommandOutcome(outcome) {
+    const existed = this.commandOutcomes.has(outcome.commandId);
+    this.commandOutcomes.set(outcome.commandId, outcome);
+    if (!existed) {
+      this.commandOutcomeOrder.push(outcome.commandId);
+      this.trimCommandOutcomes();
+    }
+  }
+  /**
+   * Get a completed command outcome by ID.
+   */
+  getCommandOutcome(commandId) {
+    return this.commandOutcomes.get(commandId);
+  }
+  // ==========================================================================
+  // IN-FLIGHT TRACKING
+  // ==========================================================================
+  /**
+   * 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) {
+    const existed = this.commandInFlightById.has(commandId);
+    return existed || this.inFlightOrder.length < this.maxInFlightCommands;
+  }
+  /**
+   * 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, record) {
+    const existed = this.commandInFlightById.has(commandId);
+    if (!existed && this.inFlightOrder.length >= this.maxInFlightCommands) {
+      this.inFlightRejections++;
+      return false;
+    }
+    this.commandInFlightById.set(commandId, record);
+    if (!existed) {
+      this.inFlightOrder.push(commandId);
+    }
+    return true;
+  }
+  /**
+   * Unregister an in-flight command.
+   * Only removes if the record matches (prevents race conditions).
+   */
+  unregisterInFlight(commandId, record) {
+    if (this.commandInFlightById.get(commandId) === record) {
+      this.commandInFlightById.delete(commandId);
+      const idx = this.inFlightOrder.indexOf(commandId);
+      if (idx !== -1) {
+        this.inFlightOrder.splice(idx, 1);
+      }
+    }
+  }
+  /**
+   * Get an in-flight command by ID.
+   */
+  getInFlight(commandId) {
+    return this.commandInFlightById.get(commandId);
+  }
+  // ==========================================================================
+  // REPLAY CHECK (MAIN API)
+  // ==========================================================================
+  /**
+   * Create a conflict response for fingerprint mismatch.
+   */
+  createConflictResponse(id, commandType, conflictType, value, originalType) {
+    return {
+      id,
+      type: "response",
+      command: commandType,
+      success: false,
+      error: `Conflicting ${conflictType} '${value}': previously used for '${originalType}', now used for '${commandType}'`
+    };
+  }
+  /**
+   * Clone a cached response for a new request.
+   * Preserves or strips ID based on whether the new request has one.
+   */
+  cloneResponseForRequest(response, requestId) {
+    if (requestId === void 0) {
+      const { id: _oldId, ...rest } = response;
+      return { ...rest };
+    }
+    return { ...response, id: requestId };
+  }
+  /**
+   * 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, fingerprint) {
+    const id = getCommandId(command);
+    const commandType = command.type;
+    const idempotencyKey = getCommandIdempotencyKey(command);
+    if (idempotencyKey) {
+      const cacheKey = this.buildIdempotencyCacheKey(command, idempotencyKey);
+      const cached = this.idempotencyCache.get(cacheKey);
+      if (cached) {
+        if (cached.fingerprint !== fingerprint) {
+          return {
+            kind: "conflict",
+            response: this.createConflictResponse(
+              id,
+              commandType,
+              "idempotencyKey",
+              idempotencyKey,
+              cached.commandType
+            )
+          };
+        }
+        return {
+          kind: "replay_cached",
+          response: this.cloneResponseForRequest({ ...cached.response, replayed: true }, id)
+        };
+      }
+    }
+    if (id) {
+      const completed = this.commandOutcomes.get(id);
+      if (completed) {
+        if (completed.fingerprint !== fingerprint) {
+          return {
+            kind: "conflict",
+            response: this.createConflictResponse(id, commandType, "id", id, completed.commandType)
+          };
+        }
+        return {
+          kind: "replay_cached",
+          response: this.cloneResponseForRequest({ ...completed.response, replayed: true }, id)
+        };
+      }
+      const inFlight = this.commandInFlightById.get(id);
+      if (inFlight) {
+        if (inFlight.fingerprint !== fingerprint) {
+          return {
+            kind: "conflict",
+            response: this.createConflictResponse(id, commandType, "id", id, inFlight.commandType)
+          };
+        }
+        return {
+          kind: "replay_inflight",
+          promise: inFlight.promise.then(
+            (response) => this.cloneResponseForRequest({ ...response, replayed: true }, id)
+          )
+        };
+      }
+    }
+    return { kind: "proceed" };
+  }
+  // ==========================================================================
+  // LIFECYCLE
+  // ==========================================================================
+  /**
+   * Clear all state (used during disposal).
+   * Note: Does NOT reset syntheticCommandSequence to prevent ID collisions.
+   * Process start time ensures uniqueness even after clear.
+   */
+  clear() {
+    this.commandInFlightById.clear();
+    this.inFlightOrder = [];
+    this.commandOutcomes.clear();
+    this.commandOutcomeOrder = [];
+    this.idempotencyCache.clear();
+    this.inFlightRejections = 0;
+  }
+}
+export {
+  CommandReplayStore,
+  SYNTHETIC_ID_PREFIX
+};
+//# sourceMappingURL=command-replay-store.js.map

package/dist/command-replay-store.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/command-replay-store.ts"],
+  "sourcesContent": ["/**\n * Command Replay Store - manages idempotency, duplicate detection, and outcome history.\n *\n * Responsibilities:\n * - Idempotency key replay (cached responses for retry safety)\n * - Command ID deduplication (completed outcomes + in-flight tracking)\n * - Fingerprint conflict detection (prevent same ID with different payload)\n * - Bounded outcome retention (LRU-style trimming)\n */\n\nimport type { RpcCommand, RpcResponse } from \"./types.js\";\nimport { getCommandId, getCommandIdempotencyKey, getSessionId } from \"./types.js\";\n\n/** How long idempotency results are replayable (10 minutes). */\nconst DEFAULT_IDEMPOTENCY_TTL_MS = 10 * 60 * 1000;\n\n/** Maximum number of retained command outcomes for dependency checks. */\nconst DEFAULT_MAX_COMMAND_OUTCOMES = 2000;\n\n/** Maximum number of in-flight commands to track (prevents unbounded memory). */\nconst DEFAULT_MAX_IN_FLIGHT_COMMANDS = 10000;\n\n/** Reserved prefix for server-generated command IDs. Client IDs matching this are rejected. */\nexport const SYNTHETIC_ID_PREFIX = \"anon:\";\n\n/**\n * Record of a completed command execution.\n * Used for dependency resolution and duplicate-id replay.\n */\nexport interface CommandOutcomeRecord {\n  commandId: string;\n  commandType: string;\n  laneKey: string;\n  fingerprint: string;\n  success: boolean;\n  error?: string;\n  response: RpcResponse;\n  sessionVersion?: number;\n  finishedAt: number;\n}\n\n/**\n * Record of an in-flight command execution.\n * Used for dependency waits and duplicate-id replay.\n */\nexport interface InFlightCommandRecord {\n  commandType: string;\n  laneKey: string;\n  fingerprint: string;\n  promise: Promise<RpcResponse>;\n}\n\n/**\n * Input for caching an idempotency result.\n */\nexport interface IdempotencyCacheInput {\n  command: RpcCommand;\n  idempotencyKey: string;\n  commandType: string;\n  fingerprint: string;\n  response: RpcResponse;\n}\nexport interface IdempotencyCacheEntry {\n  expiresAt: number;\n  commandType: string;\n  fingerprint: string;\n  response: RpcResponse;\n}\n\n/**\n * Result of checking for replay conflicts.\n *\n * This discriminated union enables type-safe handling of all replay scenarios:\n *\n * - `proceed`: No replay possible, execute the command normally\n * - `conflict`: Fingerprint mismatch - same ID/key but different payload\n * - `replay_cached`: Found cached response, return it immediately\n * - `replay_inflight`: Command with same ID is executing, await its promise\n *\n * @example\n * ```typescript\n * const result = store.checkReplay(command, fingerprint);\n * switch (result.kind) {\n *   case \"proceed\": // execute normally\n *   case \"conflict\": return result.response; // error response\n *   case \"replay_cached\": return result.response; // cached response\n *   case \"replay_inflight\": return await result.promise; // wait for in-flight\n * }\n * ```\n */\nexport type ReplayCheckResult =\n  | { kind: \"proceed\" }\n  | { kind: \"conflict\"; response: RpcResponse }\n  | { kind: \"replay_cached\"; response: RpcResponse }\n  | { kind: \"replay_inflight\"; promise: Promise<RpcResponse> };\n\n/**\n * Configuration options for the replay store.\n */\nexport interface ReplayStoreOptions {\n  idempotencyTtlMs?: number;\n  maxCommandOutcomes?: number;\n  /** Maximum in-flight commands to track. Excess is rejected (ADR-0001: reject, don't evict). */\n  maxInFlightCommands?: number;\n}\n\n/**\n * Statistics about store state for monitoring.\n */\nexport interface ReplayStoreStats {\n  /** Number of in-flight commands being tracked */\n  inFlightCount: number;\n  /** Number of completed command outcomes stored */\n  outcomeCount: number;\n  /** Number of idempotency cache entries */\n  idempotencyCacheSize: number;\n  /** Maximum configured in-flight commands */\n  maxInFlightCommands: number;\n  /** Maximum configured command outcomes */\n  maxCommandOutcomes: number;\n  /** Count of in-flight rejections due to exceeding max (ADR-0001: reject, don't evict) */\n  inFlightRejections: number;\n}\n\n/**\n * Command Replay Store - manages idempotency and duplicate detection.\n *\n * Extracted from PiSessionManager to isolate:\n * - Replay semantics (idempotency keys, command IDs)\n * - Fingerprint conflict detection\n * - Bounded outcome history\n */\nexport class CommandReplayStore {\n  /** In-flight commands by command id (for dependency waits and duplicate-id replay). */\n  private commandInFlightById = new Map<string, InFlightCommandRecord>();\n  /** Insertion order for in-flight commands (for bounded eviction). */\n  private inFlightOrder: string[] = [];\n\n  /** Completed command outcomes (for dependency checks and duplicate-id replay). */\n  private commandOutcomes = new Map<string, CommandOutcomeRecord>();\n\n  /** Bounded insertion order to trim commandOutcomes memory. */\n  private commandOutcomeOrder: string[] = [];\n\n  /** Idempotency replay cache. */\n  private idempotencyCache = new Map<string, IdempotencyCacheEntry>();\n\n  /** Sequence for synthetic command IDs when client omits id. */\n  private syntheticCommandSequence = 0;\n  /** Process start time for unique synthetic IDs that don't collide after clear(). */\n  private readonly processStartTime = Date.now();\n\n  private readonly idempotencyTtlMs: number;\n  private readonly maxCommandOutcomes: number;\n  private readonly maxInFlightCommands: number;\n  private inFlightRejections = 0;\n\n  constructor(options: ReplayStoreOptions = {}) {\n    this.idempotencyTtlMs =\n      typeof options.idempotencyTtlMs === \"number\" && options.idempotencyTtlMs > 0\n        ? options.idempotencyTtlMs\n        : DEFAULT_IDEMPOTENCY_TTL_MS;\n    this.maxCommandOutcomes =\n      typeof options.maxCommandOutcomes === \"number\" && options.maxCommandOutcomes > 0\n        ? options.maxCommandOutcomes\n        : DEFAULT_MAX_COMMAND_OUTCOMES;\n    this.maxInFlightCommands =\n      typeof options.maxInFlightCommands === \"number\" && options.maxInFlightCommands > 0\n        ? options.maxInFlightCommands\n        : DEFAULT_MAX_IN_FLIGHT_COMMANDS;\n  }\n\n  /**\n   * Get statistics about store state for monitoring.\n   */\n  getStats(): ReplayStoreStats {\n    return {\n      inFlightCount: this.commandInFlightById.size,\n      outcomeCount: this.commandOutcomes.size,\n      idempotencyCacheSize: this.idempotencyCache.size,\n      maxInFlightCommands: this.maxInFlightCommands,\n      maxCommandOutcomes: this.maxCommandOutcomes,\n      inFlightRejections: this.inFlightRejections,\n    };\n  }\n\n  // ==========================================================================\n  // COMMAND ID GENERATION\n  // ==========================================================================\n\n  /**\n   * Get or create a deterministic command ID.\n   * Returns explicit ID if provided, otherwise generates a synthetic one.\n   *\n   * Synthetic IDs use process-start-time + sequence to guarantee uniqueness:\n   * 1. Process start time distinguishes IDs across server restarts\n   * 2. Sequence guarantees uniqueness within a process lifetime\n   * 3. Clear() resets sequence but start time stays same (collision-safe within run)\n   *\n   * NOTE: This method has a side effect (increments sequence) when generating.\n   */\n  getOrCreateCommandId(command: RpcCommand): string {\n    const explicitId = getCommandId(command);\n    if (explicitId) return explicitId;\n\n    this.syntheticCommandSequence += 1;\n    return `${SYNTHETIC_ID_PREFIX}${this.processStartTime}:${this.syntheticCommandSequence}`;\n  }\n\n  // ==========================================================================\n  // FINGERPRINTING\n  // ==========================================================================\n\n  /**\n   * Compute a fingerprint for conflict detection.\n   * Excludes retry identity fields (id, idempotencyKey) since those\n   * don't affect semantic equivalence - only determine replay mechanics.\n   */\n  getCommandFingerprint(command: RpcCommand): string {\n    const { id: _id, idempotencyKey: _key, ...rest } = command;\n    return JSON.stringify(rest);\n  }\n\n  // ==========================================================================\n  // IDEMPOTENCY KEY CACHE\n  // ==========================================================================\n\n  /**\n   * Build a cache key for idempotency lookup.\n   */\n  private buildIdempotencyCacheKey(command: RpcCommand, key: string): string {\n    const sessionId = getSessionId(command) ?? \"_server_\";\n    return `${sessionId}:${key}`;\n  }\n\n  /**\n   * Remove expired entries from the idempotency cache.\n   */\n  cleanupIdempotencyCache(now = Date.now()): void {\n    for (const [key, entry] of this.idempotencyCache) {\n      if (entry.expiresAt <= now) {\n        this.idempotencyCache.delete(key);\n      }\n    }\n  }\n\n  /**\n   * Store a response in the idempotency cache.\n   */\n  cacheIdempotencyResult(input: IdempotencyCacheInput): void {\n    const cacheKey = this.buildIdempotencyCacheKey(input.command, input.idempotencyKey);\n    this.idempotencyCache.set(cacheKey, {\n      expiresAt: Date.now() + this.idempotencyTtlMs,\n      commandType: input.commandType,\n      fingerprint: input.fingerprint,\n      response: input.response,\n    });\n  }\n\n  // ==========================================================================\n  // COMMAND OUTCOMES\n  // ==========================================================================\n\n  /**\n   * Trim old command outcomes to bound memory.\n   */\n  private trimCommandOutcomes(): void {\n    while (this.commandOutcomeOrder.length > this.maxCommandOutcomes) {\n      const oldest = this.commandOutcomeOrder.shift();\n      if (!oldest) break;\n      this.commandOutcomes.delete(oldest);\n    }\n  }\n\n  /**\n   * Store a completed command outcome.\n   */\n  storeCommandOutcome(outcome: CommandOutcomeRecord): void {\n    const existed = this.commandOutcomes.has(outcome.commandId);\n    this.commandOutcomes.set(outcome.commandId, outcome);\n\n    if (!existed) {\n      this.commandOutcomeOrder.push(outcome.commandId);\n      this.trimCommandOutcomes();\n    }\n  }\n\n  /**\n   * Get a completed command outcome by ID.\n   */\n  getCommandOutcome(commandId: string): CommandOutcomeRecord | undefined {\n    return this.commandOutcomes.get(commandId);\n  }\n\n  // ==========================================================================\n  // IN-FLIGHT TRACKING\n  // ==========================================================================\n\n  /**\n   * Check whether an in-flight command can be tracked for this command ID.\n   *\n   * Returns true if:\n   * - the command ID is already tracked (replacement/update path), OR\n   * - there is free capacity for a new tracked command.\n   */\n  canRegisterInFlight(commandId: string): boolean {\n    const existed = this.commandInFlightById.has(commandId);\n    return existed || this.inFlightOrder.length < this.maxInFlightCommands;\n  }\n\n  /**\n   * Register an in-flight command.\n   *\n   * ADR-0001: Rejects when limit exceeded instead of evicting.\n   * Eviction breaks dependency chains - if command A depends on command B,\n   * and B is evicted, A fails with \"unknown dependency\". Rejection preserves\n   * correctness at the cost of temporary unavailability under load.\n   *\n   * @returns true if registered, false if limit exceeded\n   */\n  registerInFlight(commandId: string, record: InFlightCommandRecord): boolean {\n    const existed = this.commandInFlightById.has(commandId);\n\n    // Reject if at capacity and this is a new entry\n    if (!existed && this.inFlightOrder.length >= this.maxInFlightCommands) {\n      this.inFlightRejections++;\n      return false;\n    }\n\n    this.commandInFlightById.set(commandId, record);\n\n    if (!existed) {\n      this.inFlightOrder.push(commandId);\n    }\n    return true;\n  }\n\n  /**\n   * Unregister an in-flight command.\n   * Only removes if the record matches (prevents race conditions).\n   */\n  unregisterInFlight(commandId: string, record: InFlightCommandRecord): void {\n    if (this.commandInFlightById.get(commandId) === record) {\n      this.commandInFlightById.delete(commandId);\n      // Remove from order array\n      const idx = this.inFlightOrder.indexOf(commandId);\n      if (idx !== -1) {\n        this.inFlightOrder.splice(idx, 1);\n      }\n    }\n  }\n\n  /**\n   * Get an in-flight command by ID.\n   */\n  getInFlight(commandId: string): InFlightCommandRecord | undefined {\n    return this.commandInFlightById.get(commandId);\n  }\n\n  // ==========================================================================\n  // REPLAY CHECK (MAIN API)\n  // ==========================================================================\n\n  /**\n   * Create a conflict response for fingerprint mismatch.\n   */\n  private createConflictResponse(\n    id: string | undefined,\n    commandType: string,\n    conflictType: \"id\" | \"idempotencyKey\",\n    value: string,\n    originalType: string\n  ): RpcResponse {\n    return {\n      id,\n      type: \"response\",\n      command: commandType,\n      success: false,\n      error: `Conflicting ${conflictType} '${value}': previously used for '${originalType}', now used for '${commandType}'`,\n    };\n  }\n\n  /**\n   * Clone a cached response for a new request.\n   * Preserves or strips ID based on whether the new request has one.\n   */\n  private cloneResponseForRequest(\n    response: RpcResponse,\n    requestId: string | undefined\n  ): RpcResponse {\n    if (requestId === undefined) {\n      const { id: _oldId, ...rest } = response;\n      return { ...rest };\n    }\n    return { ...response, id: requestId };\n  }\n\n  /**\n   * Check for replay opportunities or conflicts.\n   *\n   * Call this BEFORE executing a command. Returns:\n   * - \"proceed\": No replay possible, execute normally\n   * - \"conflict\": Fingerprint mismatch, return error response\n   * - \"replay_cached\": Found cached response, return it (with replayed: true)\n   * - \"replay_inflight\": Found in-flight command, await its promise\n   */\n  checkReplay(command: RpcCommand, fingerprint: string): ReplayCheckResult {\n    const id = getCommandId(command);\n    const commandType = command.type;\n    const idempotencyKey = getCommandIdempotencyKey(command);\n\n    // 1. Check idempotency key cache\n    if (idempotencyKey) {\n      const cacheKey = this.buildIdempotencyCacheKey(command, idempotencyKey);\n      const cached = this.idempotencyCache.get(cacheKey);\n      if (cached) {\n        // Fingerprint conflict?\n        if (cached.fingerprint !== fingerprint) {\n          return {\n            kind: \"conflict\",\n            response: this.createConflictResponse(\n              id,\n              commandType,\n              \"idempotencyKey\",\n              idempotencyKey,\n              cached.commandType\n            ),\n          };\n        }\n\n        // Replay cached response\n        return {\n          kind: \"replay_cached\",\n          response: this.cloneResponseForRequest({ ...cached.response, replayed: true }, id),\n        };\n      }\n    }\n\n    // 2. Check for explicit command ID\n    if (id) {\n      // 2a. Check completed outcomes\n      const completed = this.commandOutcomes.get(id);\n      if (completed) {\n        // Fingerprint conflict?\n        if (completed.fingerprint !== fingerprint) {\n          return {\n            kind: \"conflict\",\n            response: this.createConflictResponse(id, commandType, \"id\", id, completed.commandType),\n          };\n        }\n\n        // Replay completed response\n        return {\n          kind: \"replay_cached\",\n          response: this.cloneResponseForRequest({ ...completed.response, replayed: true }, id),\n        };\n      }\n\n      // 2b. Check in-flight commands\n      const inFlight = this.commandInFlightById.get(id);\n      if (inFlight) {\n        // Fingerprint conflict?\n        if (inFlight.fingerprint !== fingerprint) {\n          return {\n            kind: \"conflict\",\n            response: this.createConflictResponse(id, commandType, \"id\", id, inFlight.commandType),\n          };\n        }\n\n        // Wait for in-flight to complete and replay\n        return {\n          kind: \"replay_inflight\",\n          promise: inFlight.promise.then((response) =>\n            this.cloneResponseForRequest({ ...response, replayed: true }, id)\n          ),\n        };\n      }\n    }\n\n    // No replay possible, proceed with execution\n    return { kind: \"proceed\" };\n  }\n\n  // ==========================================================================\n  // LIFECYCLE\n  // ==========================================================================\n\n  /**\n   * Clear all state (used during disposal).\n   * Note: Does NOT reset syntheticCommandSequence to prevent ID collisions.\n   * Process start time ensures uniqueness even after clear.\n   */\n  clear(): void {\n    this.commandInFlightById.clear();\n    this.inFlightOrder = [];\n    this.commandOutcomes.clear();\n    this.commandOutcomeOrder = [];\n    this.idempotencyCache.clear();\n    // Don't reset syntheticCommandSequence - processStartTime ensures uniqueness\n    this.inFlightRejections = 0;\n  }\n}\n"],
+  "mappings": "AAWA,SAAS,cAAc,0BAA0B,oBAAoB;AAGrE,MAAM,6BAA6B,KAAK,KAAK;AAG7C,MAAM,+BAA+B;AAGrC,MAAM,iCAAiC;AAGhC,MAAM,sBAAsB;AA6G5B,MAAM,mBAAmB;AAAA;AAAA,EAEtB,sBAAsB,oBAAI,IAAmC;AAAA;AAAA,EAE7D,gBAA0B,CAAC;AAAA;AAAA,EAG3B,kBAAkB,oBAAI,IAAkC;AAAA;AAAA,EAGxD,sBAAgC,CAAC;AAAA;AAAA,EAGjC,mBAAmB,oBAAI,IAAmC;AAAA;AAAA,EAG1D,2BAA2B;AAAA;AAAA,EAElB,mBAAmB,KAAK,IAAI;AAAA,EAE5B;AAAA,EACA;AAAA,EACA;AAAA,EACT,qBAAqB;AAAA,EAE7B,YAAY,UAA8B,CAAC,GAAG;AAC5C,SAAK,mBACH,OAAO,QAAQ,qBAAqB,YAAY,QAAQ,mBAAmB,IACvE,QAAQ,mBACR;AACN,SAAK,qBACH,OAAO,QAAQ,uBAAuB,YAAY,QAAQ,qBAAqB,IAC3E,QAAQ,qBACR;AACN,SAAK,sBACH,OAAO,QAAQ,wBAAwB,YAAY,QAAQ,sBAAsB,IAC7E,QAAQ,sBACR;AAAA,EACR;AAAA;AAAA;AAAA;AAAA,EAKA,WAA6B;AAC3B,WAAO;AAAA,MACL,eAAe,KAAK,oBAAoB;AAAA,MACxC,cAAc,KAAK,gBAAgB;AAAA,MACnC,sBAAsB,KAAK,iBAAiB;AAAA,MAC5C,qBAAqB,KAAK;AAAA,MAC1B,oBAAoB,KAAK;AAAA,MACzB,oBAAoB,KAAK;AAAA,IAC3B;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAiBA,qBAAqB,SAA6B;AAChD,UAAM,aAAa,aAAa,OAAO;AACvC,QAAI,WAAY,QAAO;AAEvB,SAAK,4BAA4B;AACjC,WAAO,GAAG,mBAAmB,GAAG,KAAK,gBAAgB,IAAI,KAAK,wBAAwB;AAAA,EACxF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAWA,sBAAsB,SAA6B;AACjD,UAAM,EAAE,IAAI,KAAK,gBAAgB,MAAM,GAAG,KAAK,IAAI;AACnD,WAAO,KAAK,UAAU,IAAI;AAAA,EAC5B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASQ,yBAAyB,SAAqB,KAAqB;AACzE,UAAM,YAAY,aAAa,OAAO,KAAK;AAC3C,WAAO,GAAG,SAAS,IAAI,GAAG;AAAA,EAC5B;AAAA;AAAA;AAAA;AAAA,EAKA,wBAAwB,MAAM,KAAK,IAAI,GAAS;AAC9C,eAAW,CAAC,KAAK,KAAK,KAAK,KAAK,kBAAkB;AAChD,UAAI,MAAM,aAAa,KAAK;AAC1B,aAAK,iBAAiB,OAAO,GAAG;AAAA,MAClC;AAAA,IACF;AAAA,EACF;AAAA;AAAA;AAAA;AAAA,EAKA,uBAAuB,OAAoC;AACzD,UAAM,WAAW,KAAK,yBAAyB,MAAM,SAAS,MAAM,cAAc;AAClF,SAAK,iBAAiB,IAAI,UAAU;AAAA,MAClC,WAAW,KAAK,IAAI,IAAI,KAAK;AAAA,MAC7B,aAAa,MAAM;AAAA,MACnB,aAAa,MAAM;AAAA,MACnB,UAAU,MAAM;AAAA,IAClB,CAAC;AAAA,EACH;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASQ,sBAA4B;AAClC,WAAO,KAAK,oBAAoB,SAAS,KAAK,oBAAoB;AAChE,YAAM,SAAS,KAAK,oBAAoB,MAAM;AAC9C,UAAI,CAAC,OAAQ;AACb,WAAK,gBAAgB,OAAO,MAAM;AAAA,IACpC;AAAA,EACF;AAAA;AAAA;AAAA;AAAA,EAKA,oBAAoB,SAAqC;AACvD,UAAM,UAAU,KAAK,gBAAgB,IAAI,QAAQ,SAAS;AAC1D,SAAK,gBAAgB,IAAI,QAAQ,WAAW,OAAO;AAEnD,QAAI,CAAC,SAAS;AACZ,WAAK,oBAAoB,KAAK,QAAQ,SAAS;AAC/C,WAAK,oBAAoB;AAAA,IAC3B;AAAA,EACF;AAAA;AAAA;AAAA;AAAA,EAKA,kBAAkB,WAAqD;AACrE,WAAO,KAAK,gBAAgB,IAAI,SAAS;AAAA,EAC3C;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAaA,oBAAoB,WAA4B;AAC9C,UAAM,UAAU,KAAK,oBAAoB,IAAI,SAAS;AACtD,WAAO,WAAW,KAAK,cAAc,SAAS,KAAK;AAAA,EACrD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAYA,iBAAiB,WAAmB,QAAwC;AAC1E,UAAM,UAAU,KAAK,oBAAoB,IAAI,SAAS;AAGtD,QAAI,CAAC,WAAW,KAAK,cAAc,UAAU,KAAK,qBAAqB;AACrE,WAAK;AACL,aAAO;AAAA,IACT;AAEA,SAAK,oBAAoB,IAAI,WAAW,MAAM;AAE9C,QAAI,CAAC,SAAS;AACZ,WAAK,cAAc,KAAK,SAAS;AAAA,IACnC;AACA,WAAO;AAAA,EACT;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,mBAAmB,WAAmB,QAAqC;AACzE,QAAI,KAAK,oBAAoB,IAAI,SAAS,MAAM,QAAQ;AACtD,WAAK,oBAAoB,OAAO,SAAS;AAEzC,YAAM,MAAM,KAAK,cAAc,QAAQ,SAAS;AAChD,UAAI,QAAQ,IAAI;AACd,aAAK,cAAc,OAAO,KAAK,CAAC;AAAA,MAClC;AAAA,IACF;AAAA,EACF;AAAA;AAAA;AAAA;AAAA,EAKA,YAAY,WAAsD;AAChE,WAAO,KAAK,oBAAoB,IAAI,SAAS;AAAA,EAC/C;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASQ,uBACN,IACA,aACA,cACA,OACA,cACa;AACb,WAAO;AAAA,MACL;AAAA,MACA,MAAM;AAAA,MACN,SAAS;AAAA,MACT,SAAS;AAAA,MACT,OAAO,eAAe,YAAY,KAAK,KAAK,2BAA2B,YAAY,oBAAoB,WAAW;AAAA,IACpH;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA,EAMQ,wBACN,UACA,WACa;AACb,QAAI,cAAc,QAAW;AAC3B,YAAM,EAAE,IAAI,QAAQ,GAAG,KAAK,IAAI;AAChC,aAAO,EAAE,GAAG,KAAK;AAAA,IACnB;AACA,WAAO,EAAE,GAAG,UAAU,IAAI,UAAU;AAAA,EACtC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAWA,YAAY,SAAqB,aAAwC;AACvE,UAAM,KAAK,aAAa,OAAO;AAC/B,UAAM,cAAc,QAAQ;AAC5B,UAAM,iBAAiB,yBAAyB,OAAO;AAGvD,QAAI,gBAAgB;AAClB,YAAM,WAAW,KAAK,yBAAyB,SAAS,cAAc;AACtE,YAAM,SAAS,KAAK,iBAAiB,IAAI,QAAQ;AACjD,UAAI,QAAQ;AAEV,YAAI,OAAO,gBAAgB,aAAa;AACtC,iBAAO;AAAA,YACL,MAAM;AAAA,YACN,UAAU,KAAK;AAAA,cACb;AAAA,cACA;AAAA,cACA;AAAA,cACA;AAAA,cACA,OAAO;AAAA,YACT;AAAA,UACF;AAAA,QACF;AAGA,eAAO;AAAA,UACL,MAAM;AAAA,UACN,UAAU,KAAK,wBAAwB,EAAE,GAAG,OAAO,UAAU,UAAU,KAAK,GAAG,EAAE;AAAA,QACnF;AAAA,MACF;AAAA,IACF;AAGA,QAAI,IAAI;AAEN,YAAM,YAAY,KAAK,gBAAgB,IAAI,EAAE;AAC7C,UAAI,WAAW;AAEb,YAAI,UAAU,gBAAgB,aAAa;AACzC,iBAAO;AAAA,YACL,MAAM;AAAA,YACN,UAAU,KAAK,uBAAuB,IAAI,aAAa,MAAM,IAAI,UAAU,WAAW;AAAA,UACxF;AAAA,QACF;AAGA,eAAO;AAAA,UACL,MAAM;AAAA,UACN,UAAU,KAAK,wBAAwB,EAAE,GAAG,UAAU,UAAU,UAAU,KAAK,GAAG,EAAE;AAAA,QACtF;AAAA,MACF;AAGA,YAAM,WAAW,KAAK,oBAAoB,IAAI,EAAE;AAChD,UAAI,UAAU;AAEZ,YAAI,SAAS,gBAAgB,aAAa;AACxC,iBAAO;AAAA,YACL,MAAM;AAAA,YACN,UAAU,KAAK,uBAAuB,IAAI,aAAa,MAAM,IAAI,SAAS,WAAW;AAAA,UACvF;AAAA,QACF;AAGA,eAAO;AAAA,UACL,MAAM;AAAA,UACN,SAAS,SAAS,QAAQ;AAAA,YAAK,CAAC,aAC9B,KAAK,wBAAwB,EAAE,GAAG,UAAU,UAAU,KAAK,GAAG,EAAE;AAAA,UAClE;AAAA,QACF;AAAA,MACF;AAAA,IACF;AAGA,WAAO,EAAE,MAAM,UAAU;AAAA,EAC3B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAWA,QAAc;AACZ,SAAK,oBAAoB,MAAM;AAC/B,SAAK,gBAAgB,CAAC;AACtB,SAAK,gBAAgB,MAAM;AAC3B,SAAK,sBAAsB,CAAC;AAC5B,SAAK,iBAAiB,MAAM;AAE5B,SAAK,qBAAqB;AAAA,EAC5B;AACF;",
+  "names": []
+}

package/dist/command-router.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Command Router - extensible command dispatch via handler map.
+ *
+ * Each handler is a self-contained function that takes a session and command,
+ * executes against the session, and returns a response.
+ *
+ * This replaces the giant switch statement, enabling:
+ * - Easy addition of new commands
+ * - Isolated testing of handlers
+ * - Clear separation of concerns
+ */
+import { type AgentSession } from "@mariozechner/pi-coding-agent";
+import type { RpcResponse, SessionInfo } from "./types.js";
+export type CommandHandler = (session: AgentSession, command: any, getSessionInfo: (sessionId: string) => SessionInfo | undefined) => Promise<RpcResponse> | RpcResponse;
+export declare const sessionCommandHandlers: Record<string, CommandHandler>;
+/**
+ * Route a session command to the appropriate handler.
+ * Returns a response or undefined if no handler exists (unknown command).
+ */
+export declare function routeSessionCommand(session: AgentSession, command: any, getSessionInfo: (sessionId: string) => SessionInfo | undefined): Promise<RpcResponse> | RpcResponse | undefined;
+/**
+ * Get list of supported session command types.
+ */
+export declare function getSupportedSessionCommands(): string[];
+//# sourceMappingURL=command-router.d.ts.map

package/dist/command-router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-router.d.ts","sourceRoot":"","sources":["../src/command-router.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,EAAE,KAAK,YAAY,EAAkB,MAAM,+BAA+B,CAAC;AAClF,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAM3D,MAAM,MAAM,cAAc,GAAG,CAC3B,OAAO,EAAE,YAAY,EACrB,OAAO,EAAE,GAAG,EACZ,cAAc,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,WAAW,GAAG,SAAS,KAC3D,OAAO,CAAC,WAAW,CAAC,GAAG,WAAW,CAAC;AA+WxC,eAAO,MAAM,sBAAsB,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAkCjE,CAAC;AAMF;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,YAAY,EACrB,OAAO,EAAE,GAAG,EACZ,cAAc,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,WAAW,GAAG,SAAS,GAC7D,OAAO,CAAC,WAAW,CAAC,GAAG,WAAW,GAAG,SAAS,CAMhD;AAED;;GAEG;AACH,wBAAgB,2BAA2B,IAAI,MAAM,EAAE,CAEtD"}