@kb-labs/core-platform 1.0.0

package/dist/serializable/index.d.cts

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

package/dist/serializable/index.d.ts

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