pi-app-server 0.1.0

package/dist/session-version-store.js

@@ -0,0 +1,117 @@
+import { getSessionId } from "./types.js";
+import { isMutationCommand } from "./command-classification.js";
+class SessionVersionStore {
+  /** Monotonic per-session version counter. */
+  sessionVersions = /* @__PURE__ */ new Map();
+  // ==========================================================================
+  // VERSION ACCESS
+  // ==========================================================================
+  /**
+   * Get the current version for a session.
+   * Returns undefined if session has no version (doesn't exist).
+   */
+  getVersion(sessionId) {
+    return this.sessionVersions.get(sessionId);
+  }
+  /**
+   * Check if a session has a version record.
+   */
+  hasVersion(sessionId) {
+    return this.sessionVersions.has(sessionId);
+  }
+  /**
+   * Get statistics about the store state.
+   */
+  getStats() {
+    return { sessionCount: this.sessionVersions.size };
+  }
+  // ==========================================================================
+  // VERSION MUTATION
+  // ==========================================================================
+  /**
+   * Initialize version for a new session (starts at 0).
+   */
+  initialize(sessionId) {
+    this.sessionVersions.set(sessionId, 0);
+  }
+  /**
+   * Increment version for a session.
+   * Returns the new version number.
+   */
+  increment(sessionId) {
+    const current = this.sessionVersions.get(sessionId) ?? 0;
+    const next = current + 1;
+    this.sessionVersions.set(sessionId, next);
+    return next;
+  }
+  /**
+   * Set version for a session explicitly.
+   */
+  set(sessionId, version) {
+    this.sessionVersions.set(sessionId, version);
+  }
+  /**
+   * Remove version record for a session.
+   */
+  delete(sessionId) {
+    this.sessionVersions.delete(sessionId);
+  }
+  /**
+   * Clear all version records.
+   */
+  clear() {
+    this.sessionVersions.clear();
+  }
+  // ==========================================================================
+  // COMMAND CLASSIFICATION
+  // ==========================================================================
+  /**
+   * Check if a command type mutates session state.
+   * Delegates to command-classification.ts for single source of truth.
+   * Mutating commands advance the session version.
+   */
+  isMutation(commandType) {
+    return isMutationCommand(commandType);
+  }
+  // ==========================================================================
+  // RESPONSE VERSIONING
+  // ==========================================================================
+  /**
+   * Apply session version to a response.
+   *
+   * For successful responses:
+   * - create_session: initialize new session at version 0
+   * - load_session: initialize loaded session at version 0
+   * - delete_session: remove version record
+   * - other session commands: increment if mutating
+   *
+   * Failed responses are returned unchanged.
+   */
+  applyVersion(command, response) {
+    if (!response.success) return response;
+    if (command.type === "create_session" && response.command === "create_session" && response.success) {
+      const createdSessionId = response.data.sessionId;
+      this.sessionVersions.set(createdSessionId, 0);
+      return { ...response, sessionVersion: 0 };
+    }
+    if (command.type === "load_session" && response.command === "load_session" && response.success) {
+      const loadedSessionId = response.data.sessionId;
+      this.sessionVersions.set(loadedSessionId, 0);
+      return { ...response, sessionVersion: 0 };
+    }
+    if (command.type === "delete_session" && response.command === "delete_session" && response.success) {
+      this.sessionVersions.delete(command.sessionId);
+      return response;
+    }
+    const sessionId = getSessionId(command);
+    if (!sessionId) return response;
+    const current = this.sessionVersions.get(sessionId) ?? 0;
+    const next = this.isMutation(command.type) ? current + 1 : current;
+    this.sessionVersions.set(sessionId, next);
+    return { ...response, sessionVersion: next };
+  }
+}
+export {
+  SessionVersionStore
+};
+//# sourceMappingURL=session-version-store.js.map

package/dist/session-version-store.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/session-version-store.ts"],
+  "sourcesContent": ["/**\n * Session Version Store - manages monotonic version counters per session.\n *\n * Responsibilities:\n * - Track session version numbers (for optimistic concurrency)\n * - Apply version increments to responses\n *\n * Note: Mutation classification is delegated to command-classification.ts\n * to maintain single source of truth.\n */\n\nimport type { RpcCommand, RpcResponse } from \"./types.js\";\nimport { getSessionId } from \"./types.js\";\nimport { isMutationCommand } from \"./command-classification.js\";\n\n/**\n * Statistics about the session version store.\n */\nexport interface SessionVersionStoreStats {\n  /** Number of sessions being tracked */\n  sessionCount: number;\n}\n\n/**\n * Session Version Store - manages monotonic version counters.\n *\n * Extracted from PiSessionManager to isolate:\n * - Version initialization (create session)\n * - Version deletion (delete session)\n * - Version increment logic (mutation classification)\n */\nexport class SessionVersionStore {\n  /** Monotonic per-session version counter. */\n  private sessionVersions = new Map<string, number>();\n\n  // ==========================================================================\n  // VERSION ACCESS\n  // ==========================================================================\n\n  /**\n   * Get the current version for a session.\n   * Returns undefined if session has no version (doesn't exist).\n   */\n  getVersion(sessionId: string): number | undefined {\n    return this.sessionVersions.get(sessionId);\n  }\n\n  /**\n   * Check if a session has a version record.\n   */\n  hasVersion(sessionId: string): boolean {\n    return this.sessionVersions.has(sessionId);\n  }\n\n  /**\n   * Get statistics about the store state.\n   */\n  getStats(): SessionVersionStoreStats {\n    return { sessionCount: this.sessionVersions.size };\n  }\n\n  // ==========================================================================\n  // VERSION MUTATION\n  // ==========================================================================\n\n  /**\n   * Initialize version for a new session (starts at 0).\n   */\n  initialize(sessionId: string): void {\n    this.sessionVersions.set(sessionId, 0);\n  }\n\n  /**\n   * Increment version for a session.\n   * Returns the new version number.\n   */\n  increment(sessionId: string): number {\n    const current = this.sessionVersions.get(sessionId) ?? 0;\n    const next = current + 1;\n    this.sessionVersions.set(sessionId, next);\n    return next;\n  }\n\n  /**\n   * Set version for a session explicitly.\n   */\n  set(sessionId: string, version: number): void {\n    this.sessionVersions.set(sessionId, version);\n  }\n\n  /**\n   * Remove version record for a session.\n   */\n  delete(sessionId: string): void {\n    this.sessionVersions.delete(sessionId);\n  }\n\n  /**\n   * Clear all version records.\n   */\n  clear(): void {\n    this.sessionVersions.clear();\n  }\n\n  // ==========================================================================\n  // COMMAND CLASSIFICATION\n  // ==========================================================================\n\n  /**\n   * Check if a command type mutates session state.\n   * Delegates to command-classification.ts for single source of truth.\n   * Mutating commands advance the session version.\n   */\n  isMutation(commandType: string): boolean {\n    return isMutationCommand(commandType);\n  }\n\n  // ==========================================================================\n  // RESPONSE VERSIONING\n  // ==========================================================================\n\n  /**\n   * Apply session version to a response.\n   *\n   * For successful responses:\n   * - create_session: initialize new session at version 0\n   * - load_session: initialize loaded session at version 0\n   * - delete_session: remove version record\n   * - other session commands: increment if mutating\n   *\n   * Failed responses are returned unchanged.\n   */\n  applyVersion(command: RpcCommand, response: RpcResponse): RpcResponse {\n    if (!response.success) return response;\n\n    // Handle create_session specially\n    if (\n      command.type === \"create_session\" &&\n      response.command === \"create_session\" &&\n      response.success\n    ) {\n      const createdSessionId = response.data.sessionId;\n      this.sessionVersions.set(createdSessionId, 0);\n      return { ...response, sessionVersion: 0 };\n    }\n\n    // Handle load_session specially\n    if (\n      command.type === \"load_session\" &&\n      response.command === \"load_session\" &&\n      response.success\n    ) {\n      const loadedSessionId = response.data.sessionId;\n      this.sessionVersions.set(loadedSessionId, 0);\n      return { ...response, sessionVersion: 0 };\n    }\n\n    // Handle delete_session specially\n    if (\n      command.type === \"delete_session\" &&\n      response.command === \"delete_session\" &&\n      response.success\n    ) {\n      this.sessionVersions.delete(command.sessionId);\n      return response;\n    }\n\n    // Regular session commands\n    const sessionId = getSessionId(command);\n    if (!sessionId) return response;\n\n    const current = this.sessionVersions.get(sessionId) ?? 0;\n    const next = this.isMutation(command.type) ? current + 1 : current;\n    this.sessionVersions.set(sessionId, next);\n\n    return { ...response, sessionVersion: next };\n  }\n}\n"],
+  "mappings": "AAYA,SAAS,oBAAoB;AAC7B,SAAS,yBAAyB;AAkB3B,MAAM,oBAAoB;AAAA;AAAA,EAEvB,kBAAkB,oBAAI,IAAoB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAUlD,WAAW,WAAuC;AAChD,WAAO,KAAK,gBAAgB,IAAI,SAAS;AAAA,EAC3C;AAAA;AAAA;AAAA;AAAA,EAKA,WAAW,WAA4B;AACrC,WAAO,KAAK,gBAAgB,IAAI,SAAS;AAAA,EAC3C;AAAA;AAAA;AAAA;AAAA,EAKA,WAAqC;AACnC,WAAO,EAAE,cAAc,KAAK,gBAAgB,KAAK;AAAA,EACnD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,WAAW,WAAyB;AAClC,SAAK,gBAAgB,IAAI,WAAW,CAAC;AAAA,EACvC;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,UAAU,WAA2B;AACnC,UAAM,UAAU,KAAK,gBAAgB,IAAI,SAAS,KAAK;AACvD,UAAM,OAAO,UAAU;AACvB,SAAK,gBAAgB,IAAI,WAAW,IAAI;AACxC,WAAO;AAAA,EACT;AAAA;AAAA;AAAA;AAAA,EAKA,IAAI,WAAmB,SAAuB;AAC5C,SAAK,gBAAgB,IAAI,WAAW,OAAO;AAAA,EAC7C;AAAA;AAAA;AAAA;AAAA,EAKA,OAAO,WAAyB;AAC9B,SAAK,gBAAgB,OAAO,SAAS;AAAA,EACvC;AAAA;AAAA;AAAA;AAAA,EAKA,QAAc;AACZ,SAAK,gBAAgB,MAAM;AAAA,EAC7B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAWA,WAAW,aAA8B;AACvC,WAAO,kBAAkB,WAAW;AAAA,EACtC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAiBA,aAAa,SAAqB,UAAoC;AACpE,QAAI,CAAC,SAAS,QAAS,QAAO;AAG9B,QACE,QAAQ,SAAS,oBACjB,SAAS,YAAY,oBACrB,SAAS,SACT;AACA,YAAM,mBAAmB,SAAS,KAAK;AACvC,WAAK,gBAAgB,IAAI,kBAAkB,CAAC;AAC5C,aAAO,EAAE,GAAG,UAAU,gBAAgB,EAAE;AAAA,IAC1C;AAGA,QACE,QAAQ,SAAS,kBACjB,SAAS,YAAY,kBACrB,SAAS,SACT;AACA,YAAM,kBAAkB,SAAS,KAAK;AACtC,WAAK,gBAAgB,IAAI,iBAAiB,CAAC;AAC3C,aAAO,EAAE,GAAG,UAAU,gBAAgB,EAAE;AAAA,IAC1C;AAGA,QACE,QAAQ,SAAS,oBACjB,SAAS,YAAY,oBACrB,SAAS,SACT;AACA,WAAK,gBAAgB,OAAO,QAAQ,SAAS;AAC7C,aAAO;AAAA,IACT;AAGA,UAAM,YAAY,aAAa,OAAO;AACtC,QAAI,CAAC,UAAW,QAAO;AAEvB,UAAM,UAAU,KAAK,gBAAgB,IAAI,SAAS,KAAK;AACvD,UAAM,OAAO,KAAK,WAAW,QAAQ,IAAI,IAAI,UAAU,IAAI;AAC3D,SAAK,gBAAgB,IAAI,WAAW,IAAI;AAExC,WAAO,EAAE,GAAG,UAAU,gBAAgB,KAAK;AAAA,EAC7C;AACF;",
+  "names": []
+}

package/dist/type-guards.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Type guards and accessor functions for RPC commands and responses.
+ *
+ * Extracted from types.ts to keep type definitions separate from runtime utilities.
+ * These functions provide type-safe access to command fields and response discrimination.
+ */
+import type { SessionInfo } from "./types.js";
+import type { RpcCommand, RpcResponse, RpcResponseBase, SessionCommand } from "./types.js";
+/**
+ * Get the optional command ID from any RpcCommand.
+ */
+export declare function getCommandId(cmd: RpcCommand): string | undefined;
+/**
+ * Get the command type as a string.
+ */
+export declare function getCommandType(cmd: RpcCommand): string;
+/**
+ * Get the sessionId from a command, if present.
+ * Returns undefined for server commands that don't have sessionId.
+ */
+export declare function getSessionId(cmd: RpcCommand): string | undefined;
+/**
+ * Optional causal dependencies for command ordering.
+ */
+export declare function getCommandDependsOn(cmd: RpcCommand): string[] | undefined;
+/**
+ * Optional optimistic concurrency precondition.
+ */
+export declare function getCommandIfSessionVersion(cmd: RpcCommand): number | undefined;
+/**
+ * Optional idempotency key for replay-safe command retries.
+ */
+export declare function getCommandIdempotencyKey(cmd: RpcCommand): string | undefined;
+/**
+ * Type guard: true if command targets a session (has sessionId).
+ */
+export declare function isSessionCommand(cmd: RpcCommand): cmd is SessionCommand;
+/**
+ * Type guard: true if response is a successful create_session response.
+ */
+export declare function isCreateSessionResponse(response: RpcResponse): response is RpcResponseBase & {
+    command: "create_session";
+    success: true;
+    data: {
+        sessionId: string;
+        sessionInfo: SessionInfo;
+    };
+};
+/**
+ * Type guard: true if response is a successful switch_session response.
+ */
+export declare function isSwitchSessionResponse(response: RpcResponse): response is RpcResponseBase & {
+    command: "switch_session";
+    success: true;
+    data: {
+        sessionInfo: SessionInfo;
+    };
+};
+//# sourceMappingURL=type-guards.d.ts.map

package/dist/type-guards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"type-guards.d.ts","sourceRoot":"","sources":["../src/type-guards.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAM3F;;GAEG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,GAAG,SAAS,CAEhE;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,CAEtD;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,GAAG,SAAS,CAGhE;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,EAAE,GAAG,SAAS,CAIzE;AAED;;GAEG;AACH,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,GAAG,SAAS,CAE9E;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,GAAG,SAAS,CAE5E;AAMD;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,UAAU,GAAG,GAAG,IAAI,cAAc,CAEvE;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,WAAW,GAAG,QAAQ,IAAI,eAAe,GAAG;IAC5F,OAAO,EAAE,gBAAgB,CAAC;IAC1B,OAAO,EAAE,IAAI,CAAC;IACd,IAAI,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,WAAW,CAAA;KAAE,CAAC;CACvD,CAEA;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,WAAW,GAAG,QAAQ,IAAI,eAAe,GAAG;IAC5F,OAAO,EAAE,gBAAgB,CAAC;IAC1B,OAAO,EAAE,IAAI,CAAC;IACd,IAAI,EAAE;QAAE,WAAW,EAAE,WAAW,CAAA;KAAE,CAAC;CACpC,CAEA"}

package/dist/type-guards.js

@@ -0,0 +1,40 @@
+function getCommandId(cmd) {
+  return cmd.id;
+}
+function getCommandType(cmd) {
+  return cmd.type;
+}
+function getSessionId(cmd) {
+  if ("sessionId" in cmd) return cmd.sessionId;
+  return void 0;
+}
+function getCommandDependsOn(cmd) {
+  return Array.isArray(cmd.dependsOn) ? cmd.dependsOn.filter((value) => typeof value === "string") : void 0;
+}
+function getCommandIfSessionVersion(cmd) {
+  return typeof cmd.ifSessionVersion === "number" ? cmd.ifSessionVersion : void 0;
+}
+function getCommandIdempotencyKey(cmd) {
+  return typeof cmd.idempotencyKey === "string" ? cmd.idempotencyKey : void 0;
+}
+function isSessionCommand(cmd) {
+  return "sessionId" in cmd;
+}
+function isCreateSessionResponse(response) {
+  return response.success && response.command === "create_session";
+}
+function isSwitchSessionResponse(response) {
+  return response.success && response.command === "switch_session";
+}
+export {
+  getCommandDependsOn,
+  getCommandId,
+  getCommandIdempotencyKey,
+  getCommandIfSessionVersion,
+  getCommandType,
+  getSessionId,
+  isCreateSessionResponse,
+  isSessionCommand,
+  isSwitchSessionResponse
+};
+//# sourceMappingURL=type-guards.js.map

package/dist/type-guards.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/type-guards.ts"],
+  "sourcesContent": ["/**\n * Type guards and accessor functions for RPC commands and responses.\n *\n * Extracted from types.ts to keep type definitions separate from runtime utilities.\n * These functions provide type-safe access to command fields and response discrimination.\n */\n\nimport type { SessionInfo } from \"./types.js\";\nimport type { RpcCommand, RpcResponse, RpcResponseBase, SessionCommand } from \"./types.js\";\n\n// =============================================================================\n// COMMAND ACCESSORS\n// =============================================================================\n\n/**\n * Get the optional command ID from any RpcCommand.\n */\nexport function getCommandId(cmd: RpcCommand): string | undefined {\n  return cmd.id;\n}\n\n/**\n * Get the command type as a string.\n */\nexport function getCommandType(cmd: RpcCommand): string {\n  return cmd.type;\n}\n\n/**\n * Get the sessionId from a command, if present.\n * Returns undefined for server commands that don't have sessionId.\n */\nexport function getSessionId(cmd: RpcCommand): string | undefined {\n  if (\"sessionId\" in cmd) return cmd.sessionId;\n  return undefined;\n}\n\n/**\n * Optional causal dependencies for command ordering.\n */\nexport function getCommandDependsOn(cmd: RpcCommand): string[] | undefined {\n  return Array.isArray(cmd.dependsOn)\n    ? cmd.dependsOn.filter((value): value is string => typeof value === \"string\")\n    : undefined;\n}\n\n/**\n * Optional optimistic concurrency precondition.\n */\nexport function getCommandIfSessionVersion(cmd: RpcCommand): number | undefined {\n  return typeof cmd.ifSessionVersion === \"number\" ? cmd.ifSessionVersion : undefined;\n}\n\n/**\n * Optional idempotency key for replay-safe command retries.\n */\nexport function getCommandIdempotencyKey(cmd: RpcCommand): string | undefined {\n  return typeof cmd.idempotencyKey === \"string\" ? cmd.idempotencyKey : undefined;\n}\n\n// =============================================================================\n// TYPE GUARDS\n// =============================================================================\n\n/**\n * Type guard: true if command targets a session (has sessionId).\n */\nexport function isSessionCommand(cmd: RpcCommand): cmd is SessionCommand {\n  return \"sessionId\" in cmd;\n}\n\n/**\n * Type guard: true if response is a successful create_session response.\n */\nexport function isCreateSessionResponse(response: RpcResponse): response is RpcResponseBase & {\n  command: \"create_session\";\n  success: true;\n  data: { sessionId: string; sessionInfo: SessionInfo };\n} {\n  return response.success && response.command === \"create_session\";\n}\n\n/**\n * Type guard: true if response is a successful switch_session response.\n */\nexport function isSwitchSessionResponse(response: RpcResponse): response is RpcResponseBase & {\n  command: \"switch_session\";\n  success: true;\n  data: { sessionInfo: SessionInfo };\n} {\n  return response.success && response.command === \"switch_session\";\n}\n"],
+  "mappings": "AAiBO,SAAS,aAAa,KAAqC;AAChE,SAAO,IAAI;AACb;AAKO,SAAS,eAAe,KAAyB;AACtD,SAAO,IAAI;AACb;AAMO,SAAS,aAAa,KAAqC;AAChE,MAAI,eAAe,IAAK,QAAO,IAAI;AACnC,SAAO;AACT;AAKO,SAAS,oBAAoB,KAAuC;AACzE,SAAO,MAAM,QAAQ,IAAI,SAAS,IAC9B,IAAI,UAAU,OAAO,CAAC,UAA2B,OAAO,UAAU,QAAQ,IAC1E;AACN;AAKO,SAAS,2BAA2B,KAAqC;AAC9E,SAAO,OAAO,IAAI,qBAAqB,WAAW,IAAI,mBAAmB;AAC3E;AAKO,SAAS,yBAAyB,KAAqC;AAC5E,SAAO,OAAO,IAAI,mBAAmB,WAAW,IAAI,iBAAiB;AACvE;AASO,SAAS,iBAAiB,KAAwC;AACvE,SAAO,eAAe;AACxB;AAKO,SAAS,wBAAwB,UAItC;AACA,SAAO,SAAS,WAAW,SAAS,YAAY;AAClD;AAKO,SAAS,wBAAwB,UAItC;AACA,SAAO,SAAS,WAAW,SAAS,YAAY;AAClD;",
+  "names": []
+}