@kb-labs/core-platform 1.0.0

package/dist/serializable/index.js

@@ -0,0 +1,152 @@
+// src/serializable/types.ts
+var IPC_PROTOCOL_VERSION = 2;
+function isAdapterCall(msg) {
+  if (typeof msg !== "object" || msg === null || msg.type !== "adapter:call" || typeof msg.requestId !== "string" || typeof msg.adapter !== "string" || typeof msg.method !== "string" || !Array.isArray(msg.args)) {
+    return false;
+  }
+  if ("version" in msg && typeof msg.version !== "number") {
+    return false;
+  }
+  if (!("version" in msg)) {
+    msg.version = 1;
+  }
+  return true;
+}
+function isAdapterResponse(msg) {
+  return typeof msg === "object" && msg !== null && msg.type === "adapter:response" && typeof msg.requestId === "string";
+}
+var SerializationError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "SerializationError";
+  }
+};
+var DeserializationError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "DeserializationError";
+  }
+};
+
+// src/serializable/serializer.ts
+function serialize(value) {
+  const seen = /* @__PURE__ */ new WeakSet();
+  return serializeValue(value, seen);
+}
+function serializeValue(value, seen) {
+  if (value === null || value === void 0) {
+    return null;
+  }
+  if (typeof value === "boolean" || typeof value === "number" || typeof value === "string") {
+    return value;
+  }
+  if (typeof value === "object") {
+    if (seen.has(value)) {
+      throw new SerializationError("Circular reference detected");
+    }
+    seen.add(value);
+  }
+  if (Buffer.isBuffer(value)) {
+    return {
+      __type: "Buffer",
+      data: value.toString("base64")
+    };
+  }
+  if (value instanceof Date) {
+    if (isNaN(value.getTime())) {
+      throw new SerializationError("Cannot serialize invalid Date");
+    }
+    return {
+      __type: "Date",
+      iso: value.toISOString()
+    };
+  }
+  if (value instanceof Error) {
+    return {
+      __type: "Error",
+      name: value.name,
+      message: value.message,
+      stack: value.stack,
+      code: value.code
+    };
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => serializeValue(item, seen));
+  }
+  if (typeof value === "object" && value.constructor === Object) {
+    const result = {};
+    for (const [key, val] of Object.entries(value)) {
+      result[key] = serializeValue(val, seen);
+    }
+    return result;
+  }
+  throw new SerializationError(
+    `Cannot serialize type: ${typeof value} (constructor: ${value.constructor?.name || "unknown"})`
+  );
+}
+function deserialize(value) {
+  if (value === null) {
+    return null;
+  }
+  if (typeof value === "boolean" || typeof value === "number" || typeof value === "string") {
+    return value;
+  }
+  if (typeof value !== "object") {
+    throw new DeserializationError(`Invalid serialized value type: ${typeof value}`);
+  }
+  const obj = value;
+  if (obj.__type === "Buffer") {
+    if (typeof obj.data !== "string") {
+      throw new DeserializationError("Invalid SerializableBuffer: missing or invalid data field");
+    }
+    try {
+      return Buffer.from(obj.data, "base64");
+    } catch (error) {
+      throw new DeserializationError(`Failed to decode Buffer: ${error}`);
+    }
+  }
+  if (obj.__type === "Date") {
+    if (typeof obj.iso !== "string") {
+      throw new DeserializationError("Invalid SerializableDate: missing or invalid iso field");
+    }
+    const date = new Date(obj.iso);
+    if (isNaN(date.getTime())) {
+      throw new DeserializationError(`Invalid ISO date string: ${obj.iso}`);
+    }
+    return date;
+  }
+  if (obj.__type === "Error") {
+    if (typeof obj.message !== "string") {
+      throw new DeserializationError("Invalid SerializableError: missing or invalid message field");
+    }
+    const error = new Error(obj.message);
+    if (typeof obj.name === "string") {
+      error.name = obj.name;
+    }
+    if (typeof obj.stack === "string") {
+      error.stack = obj.stack;
+    }
+    if (obj.code !== void 0) {
+      error.code = obj.code;
+    }
+    return error;
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => deserialize(item));
+  }
+  const result = {};
+  for (const [key, val] of Object.entries(value)) {
+    result[key] = deserialize(val);
+  }
+  return result;
+}
+function serializeArgs(args) {
+  return args.map((arg) => serialize(arg));
+}
+function deserializeArgs(args) {
+  return args.map((arg) => deserialize(arg));
+}
+
+export { DeserializationError, IPC_PROTOCOL_VERSION, SerializationError, deserialize, deserializeArgs, isAdapterCall, isAdapterResponse, serialize, serializeArgs };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/serializable/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/serializable/types.ts","../../src/serializable/serializer.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * @module @kb-labs/core-platform/serializable\n * IPC serialization types for cross-process adapter communication.\n *\n * This module defines the protocol for serializing adapter method calls\n * and responses across process boundaries using IPC (Inter-Process Communication).\n *\n * @example\n * ```typescript\n * import { AdapterCall, AdapterResponse } from '@kb-labs/core-platform/serializable';\n *\n * const call: AdapterCall = {\n *   type: 'adapter:call',\n *   requestId: 'uuid-123',\n *   adapter: 'vectorStore',\n *   method: 'search',\n *   args: [[0.1, 0.2, 0.3], 10],\n *   timeout: 30000,\n * };\n * ```\n */\n\n/**\n * Special type for serialized Buffer instances.\n * Buffers are converted to base64 strings for transmission.\n */\nexport interface SerializableBuffer {\n  __type: 'Buffer';\n  data: string; // base64 encoded\n}\n\n/**\n * Special type for serialized Date instances.\n * Dates are converted to ISO 8601 strings for transmission.\n */\nexport interface SerializableDate {\n  __type: 'Date';\n  iso: string; // ISO 8601 format\n}\n\n/**\n * Special type for serialized Error instances.\n * Errors are converted to structured objects with name, message, stack, and optional code.\n */\nexport interface SerializableError {\n  __type: 'Error';\n  name: string;\n  message: string;\n  stack?: string;\n  code?: string;\n}\n\n/**\n * Values that can be safely serialized over IPC/network.\n *\n * Supports:\n * - Primitives: null, boolean, number, string\n * - Special types: Buffer, Date, Error\n * - Collections: Array, Object\n *\n * Does NOT support:\n * - Functions\n * - Symbols (except as object keys after serialization)\n * - WeakMap/WeakSet\n * - Circular references (will be detected and throw error)\n */\nexport type SerializableValue =\n  | null\n  | boolean\n  | number\n  | string\n  | SerializableBuffer\n  | SerializableDate\n  | SerializableError\n  | SerializableArray\n  | SerializableObject;\n\n/**\n * Serializable array - all elements must be SerializableValue\n */\nexport type SerializableArray = SerializableValue[];\n\n/**\n * Serializable object - all values must be SerializableValue\n */\nexport type SerializableObject = { [key: string]: SerializableValue };\n\n/**\n * Adapter types supported by the IPC protocol.\n *\n * These correspond to the adapters available in PlatformContainer:\n * - vectorStore: IVectorStore\n * - cache: ICache\n * - llm: ILLM\n * - embeddings: IEmbeddings\n * - storage: IStorage\n * - logger: ILogger\n * - analytics: IAnalytics\n * - eventBus: IEventBus\n * - invoke: IInvoke\n * - artifacts: IArtifacts\n */\nexport type AdapterType =\n  | 'vectorStore'\n  | 'cache'\n  | 'config'\n  | 'llm'\n  | 'embeddings'\n  | 'storage'\n  | 'logger'\n  | 'analytics'\n  | 'eventBus'\n  | 'invoke'\n  | 'artifacts'\n  | 'database.document'\n  | 'database.sql';\n\n/**\n * Execution context for adapter calls.\n *\n * Used for tracing, debugging, security validation, and metrics.\n * All fields are optional to maintain backward compatibility.\n */\nexport interface AdapterCallContext {\n  /** Trace ID for distributed tracing (spans entire CLI → Worker → Adapter → Service flow) */\n  traceId?: string;\n  /** Session ID for user session tracking */\n  sessionId?: string;\n  /** Plugin ID making the adapter call */\n  pluginId?: string;\n  /** Workspace ID for multi-tenant scenarios */\n  workspaceId?: string;\n  /** Tenant ID for multi-tenant quota enforcement */\n  tenantId?: string;\n  /** Plugin permissions snapshot (for adapter-level validation) */\n  permissions?: {\n    /** Allowed adapter access (e.g., ['vectorStore', 'cache']) */\n    adapters?: string[];\n    /** Allowed storage paths (e.g., ['.kb/**', 'docs/**']) */\n    storagePaths?: string[];\n    /** Allowed network hosts (e.g., ['api.openai.com']) */\n    networkHosts?: string[];\n  };\n}\n\n/**\n * IPC protocol version.\n *\n * Version history:\n * - v1: Initial implementation (requestId, adapter, method, args, timeout)\n * - v2: Added context (traceId, pluginId, sessionId, tenantId, permissions)\n *\n * When making breaking changes:\n * 1. Increment version\n * 2. Update IPCServer to handle both old and new versions\n * 3. Update ADR-0038 with migration guide\n */\nexport const IPC_PROTOCOL_VERSION = 2;\n\n/**\n * Adapter method call that can be sent over IPC.\n *\n * Represents a request from child process to parent process\n * to execute a method on an adapter.\n *\n * @example\n * ```typescript\n * const call: AdapterCall = {\n *   version: 2,\n *   type: 'adapter:call',\n *   requestId: 'uuid-123',\n *   adapter: 'vectorStore',\n *   method: 'search',\n *   args: [[0.1, 0.2, 0.3], 10, { collectionId: 'docs' }],\n *   timeout: 30000,\n *   context: {\n *     traceId: 'trace-abc',\n *     pluginId: '@kb-labs/mind',\n *     sessionId: 'session-xyz',\n *   },\n * };\n * ```\n */\nexport interface AdapterCall {\n  /** Protocol version for backward compatibility */\n  version: number;\n  type: 'adapter:call';\n  /** Unique request ID to match with response */\n  requestId: string;\n  /** Adapter to call */\n  adapter: AdapterType;\n  /** Method name to call on adapter */\n  method: string;\n  /** Serialized method arguments */\n  args: SerializableValue[];\n  /** Optional timeout in milliseconds (default: 30000) */\n  timeout?: number;\n  /** Optional execution context for tracing, debugging, security (v2+) */\n  context?: AdapterCallContext;\n}\n\n/**\n * Response from adapter method call.\n *\n * Represents a response from parent process back to child process\n * after executing an adapter method.\n *\n * Either `result` or `error` will be present, never both.\n *\n * @example Success:\n * ```typescript\n * const response: AdapterResponse = {\n *   type: 'adapter:response',\n *   requestId: 'uuid-123',\n *   result: [{ id: '1', score: 0.95, metadata: {} }],\n * };\n * ```\n *\n * @example Error:\n * ```typescript\n * const response: AdapterResponse = {\n *   type: 'adapter:response',\n *   requestId: 'uuid-123',\n *   error: {\n *     __type: 'Error',\n *     name: 'VectorStoreError',\n *     message: 'Collection not found',\n *     stack: '...',\n *   },\n * };\n * ```\n */\nexport interface AdapterResponse {\n  type: 'adapter:response';\n  /** Request ID this response corresponds to */\n  requestId: string;\n  /** Serialized result (if successful) */\n  result?: SerializableValue;\n  /** Serialized error (if failed) */\n  error?: SerializableError;\n}\n\n/**\n * All possible IPC messages.\n *\n * Child → Parent: AdapterCall\n * Parent → Child: AdapterResponse\n */\nexport type IPCMessage = AdapterCall | AdapterResponse;\n\n/**\n * Type guard to check if message is an AdapterCall.\n *\n * Supports both v1 (no version field) and v2+ (with version field)\n * for backward compatibility.\n */\nexport function isAdapterCall(msg: unknown): msg is AdapterCall {\n  if (\n    typeof msg !== 'object' ||\n    msg === null ||\n    (msg as any).type !== 'adapter:call' ||\n    typeof (msg as any).requestId !== 'string' ||\n    typeof (msg as any).adapter !== 'string' ||\n    typeof (msg as any).method !== 'string' ||\n    !Array.isArray((msg as any).args)\n  ) {\n    return false;\n  }\n\n  // If version field is present, it must be a number\n  if ('version' in (msg as any) && typeof (msg as any).version !== 'number') {\n    return false;\n  }\n\n  // v1 messages (no version field) are auto-upgraded to v2 by adding version: 1\n  if (!('version' in (msg as any))) {\n    (msg as any).version = 1; // Auto-upgrade legacy messages\n  }\n\n  return true;\n}\n\n/**\n * Type guard to check if message is an AdapterResponse.\n */\nexport function isAdapterResponse(msg: unknown): msg is AdapterResponse {\n  return (\n    typeof msg === 'object' &&\n    msg !== null &&\n    (msg as any).type === 'adapter:response' &&\n    typeof (msg as any).requestId === 'string'\n  );\n}\n\n/**\n * Error thrown when serialization fails.\n */\nexport class SerializationError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = 'SerializationError';\n  }\n}\n\n/**\n * Error thrown when deserialization fails.\n */\nexport class DeserializationError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = 'DeserializationError';\n  }\n}\n","/**\n * @module @kb-labs/core-platform/serializable\n * Serializer for cross-process communication.\n *\n * Handles serialization/deserialization of complex types:\n * - Buffer (to/from base64)\n * - Date (to/from ISO 8601)\n * - Error (with stack traces)\n * - Circular reference detection\n *\n * @example\n * ```typescript\n * import { serialize, deserialize } from '@kb-labs/core-platform/serializable';\n *\n * const data = {\n *   buffer: Buffer.from('hello'),\n *   date: new Date(),\n *   error: new Error('test'),\n *   nested: { values: [1, 2, 3] },\n * };\n *\n * const serialized = serialize(data);\n * const deserialized = deserialize(serialized);\n * ```\n */\n\nimport type {\n  SerializableValue,\n  SerializableBuffer,\n  SerializableDate,\n  SerializableError,\n  SerializableArray,\n  SerializableObject} from './types';\nimport {\n  SerializationError,\n  DeserializationError,\n} from './types';\n\n/**\n * Serialize value for IPC transmission.\n *\n * Handles special types:\n * - Buffer → base64 string\n * - Date → ISO 8601 string\n * - Error → structured object with stack\n * - Detects and throws on circular references\n *\n * @param value - Value to serialize\n * @returns Serialized value safe for JSON transmission\n * @throws SerializationError if value contains unsupported types or circular refs\n *\n * @example\n * ```typescript\n * const result = serialize({\n *   buf: Buffer.from('hello'),\n *   date: new Date('2025-01-01'),\n *   error: new Error('test'),\n * });\n * // result = {\n * //   buf: { __type: 'Buffer', data: 'aGVsbG8=' },\n * //   date: { __type: 'Date', iso: '2025-01-01T00:00:00.000Z' },\n * //   error: { __type: 'Error', name: 'Error', message: 'test', stack: '...' },\n * // }\n * ```\n */\nexport function serialize(value: unknown): SerializableValue {\n  const seen = new WeakSet<object>();\n  return serializeValue(value, seen);\n}\n\n/**\n * Internal serialization with circular reference tracking.\n */\nfunction serializeValue(value: unknown, seen: WeakSet<object>): SerializableValue {\n  // Primitives\n  if (value === null || value === undefined) {\n    return null;\n  }\n\n  if (typeof value === 'boolean' || typeof value === 'number' || typeof value === 'string') {\n    return value;\n  }\n\n  // Check for circular references\n  if (typeof value === 'object') {\n    if (seen.has(value)) {\n      throw new SerializationError('Circular reference detected');\n    }\n    seen.add(value);\n  }\n\n  // Buffer → base64\n  if (Buffer.isBuffer(value)) {\n    return {\n      __type: 'Buffer',\n      data: value.toString('base64'),\n    } as SerializableBuffer;\n  }\n\n  // Date → ISO string\n  if (value instanceof Date) {\n    if (isNaN(value.getTime())) {\n      throw new SerializationError('Cannot serialize invalid Date');\n    }\n    return {\n      __type: 'Date',\n      iso: value.toISOString(),\n    } as SerializableDate;\n  }\n\n  // Error → structured\n  if (value instanceof Error) {\n    return {\n      __type: 'Error',\n      name: value.name,\n      message: value.message,\n      stack: value.stack,\n      code: (value as any).code,\n    } as SerializableError;\n  }\n\n  // Array\n  if (Array.isArray(value)) {\n    return value.map((item) => serializeValue(item, seen)) as SerializableArray;\n  }\n\n  // Plain object\n  if (typeof value === 'object' && value.constructor === Object) {\n    const result: SerializableObject = {};\n    for (const [key, val] of Object.entries(value)) {\n      result[key] = serializeValue(val, seen);\n    }\n    return result;\n  }\n\n  // Unsupported type\n  throw new SerializationError(\n    `Cannot serialize type: ${typeof value} (constructor: ${value.constructor?.name || 'unknown'})`\n  );\n}\n\n/**\n * Deserialize value from IPC transmission.\n *\n * Reconstructs special types:\n * - base64 string → Buffer\n * - ISO 8601 string → Date\n * - structured object → Error (with stack)\n *\n * @param value - Serialized value\n * @returns Original value reconstructed from serialization\n * @throws DeserializationError if value format is invalid\n *\n * @example\n * ```typescript\n * const serialized = {\n *   buf: { __type: 'Buffer', data: 'aGVsbG8=' },\n *   date: { __type: 'Date', iso: '2025-01-01T00:00:00.000Z' },\n *   error: { __type: 'Error', name: 'Error', message: 'test' },\n * };\n *\n * const result = deserialize(serialized);\n * // result = {\n * //   buf: Buffer.from('hello'),\n * //   date: new Date('2025-01-01'),\n * //   error: Error('test'),\n * // }\n * ```\n */\nexport function deserialize(value: SerializableValue): unknown {\n  // Primitives\n  if (value === null) {\n    return null;\n  }\n\n  if (typeof value === 'boolean' || typeof value === 'number' || typeof value === 'string') {\n    return value;\n  }\n\n  // Must be object/array at this point\n  if (typeof value !== 'object') {\n    throw new DeserializationError(`Invalid serialized value type: ${typeof value}`);\n  }\n\n  // Check for special types\n  const obj = value as any;\n\n  // Buffer\n  if (obj.__type === 'Buffer') {\n    if (typeof obj.data !== 'string') {\n      throw new DeserializationError('Invalid SerializableBuffer: missing or invalid data field');\n    }\n    try {\n      return Buffer.from(obj.data, 'base64');\n    } catch (error) {\n      throw new DeserializationError(`Failed to decode Buffer: ${error}`);\n    }\n  }\n\n  // Date\n  if (obj.__type === 'Date') {\n    if (typeof obj.iso !== 'string') {\n      throw new DeserializationError('Invalid SerializableDate: missing or invalid iso field');\n    }\n    const date = new Date(obj.iso);\n    if (isNaN(date.getTime())) {\n      throw new DeserializationError(`Invalid ISO date string: ${obj.iso}`);\n    }\n    return date;\n  }\n\n  // Error\n  if (obj.__type === 'Error') {\n    if (typeof obj.message !== 'string') {\n      throw new DeserializationError('Invalid SerializableError: missing or invalid message field');\n    }\n    const error = new Error(obj.message);\n    if (typeof obj.name === 'string') {\n      error.name = obj.name;\n    }\n    if (typeof obj.stack === 'string') {\n      error.stack = obj.stack;\n    }\n    if (obj.code !== undefined) {\n      (error as any).code = obj.code;\n    }\n    return error;\n  }\n\n  // Array\n  if (Array.isArray(value)) {\n    return value.map((item) => deserialize(item));\n  }\n\n  // Plain object\n  const result: any = {};\n  for (const [key, val] of Object.entries(value)) {\n    result[key] = deserialize(val);\n  }\n  return result;\n}\n\n/**\n * Serialize multiple values (convenience for adapter method args).\n *\n * @example\n * ```typescript\n * const args = serializeArgs([\n *   Buffer.from('hello'),\n *   new Date(),\n *   { nested: { value: 42 } },\n * ]);\n * ```\n */\nexport function serializeArgs(args: unknown[]): SerializableValue[] {\n  return args.map((arg) => serialize(arg));\n}\n\n/**\n * Deserialize multiple values (convenience for adapter method args).\n *\n * @example\n * ```typescript\n * const args = deserializeArgs([\n *   { __type: 'Buffer', data: 'aGVsbG8=' },\n *   { __type: 'Date', iso: '2025-01-01T00:00:00.000Z' },\n *   { nested: { value: 42 } },\n * ]);\n * ```\n */\nexport function deserializeArgs(args: SerializableValue[]): unknown[] {\n  return args.map((arg) => deserialize(arg));\n}\n"]}