@kb-labs/core-platform 1.0.0

package/dist/snapshot-provider--COac4P-.d.ts

@@ -0,0 +1,923 @@
+import { L as LogRecord, a as LogQuery } from './artifacts-DrVnkLzu.js';
+import { I as ISQLDatabase } from './database-DGV6a1nj.js';
+
+/**
+ * @module @kb-labs/core-platform/adapters/adapter-manifest
+ * Adapter manifest schema for dependency management and extension points.
+ */
+/**
+ * Adapter type classification.
+ *
+ * - core: Primary adapter implementing a platform interface (e.g., logger, db)
+ * - extension: Adapter that extends another adapter via hooks (e.g., log persistence)
+ * - proxy: Adapter that wraps/delegates to another adapter (e.g., IPC proxy)
+ */
+type AdapterType = "core" | "extension" | "proxy";
+/**
+ * Adapter dependency specification.
+ *
+ * Short form: runtime adapter token (config key in `platform.adapters`)
+ * Long form: { id, alias } where alias is used in factory deps parameter
+ */
+type AdapterDependency = string | {
+    id: string;
+    alias?: string;
+};
+/**
+ * Extension point configuration.
+ *
+ * Describes how this adapter extends another adapter:
+ * - adapter: Target adapter ID (e.g., "logger")
+ * - hook: Method name on target adapter (e.g., "onLog")
+ * - method: Method name on this adapter to call (e.g., "write")
+ * - priority: Call order (higher = called first, default: 0)
+ */
+interface AdapterExtension {
+    /** Target adapter ID to extend */
+    adapter: string;
+    /** Hook method on target adapter (e.g., "onLog") */
+    hook: string;
+    /** Method on this adapter to call when hook fires (e.g., "write") */
+    method: string;
+    /**
+     * Priority for extension ordering.
+     * Higher values are called first.
+     * Default: 0
+     * Ties resolved by registration order.
+     */
+    priority?: number;
+}
+/**
+ * Adapter capabilities declaration.
+ *
+ * Describes what features this adapter supports.
+ * Used for adapter selection and runtime feature detection.
+ */
+interface AdapterCapabilities {
+    /** Supports streaming/realtime data */
+    streaming?: boolean;
+    /** Supports batch operations */
+    batch?: boolean;
+    /** Supports search/query operations */
+    search?: boolean;
+    /** Supports transactions */
+    transactions?: boolean;
+    /** Custom capabilities (adapter-specific) */
+    custom?: Record<string, unknown>;
+}
+/**
+ * Adapter manifest.
+ *
+ * Every adapter exports a manifest describing its:
+ * - Identity (id, name, version)
+ * - Type (core/extension/proxy)
+ * - Interface implementation (implements: "ILogger")
+ * - Dependencies (requires, optional)
+ * - Extension points (extends: { adapter, hook, method })
+ * - Capabilities (streaming, batch, search, etc.)
+ *
+ * @example Core adapter (Pino logger)
+ * ```typescript
+ * export const manifest: AdapterManifest = {
+ *   manifestVersion: '1.0.0',
+ *   id: 'pino-logger',
+ *   name: 'Pino Logger',
+ *   version: '1.0.0',
+ *   type: 'core',
+ *   implements: 'ILogger',
+ *   optional: { adapters: ['analytics'] },
+ *   capabilities: { streaming: true }
+ * };
+ * ```
+ *
+ * @example Extension adapter (Ring buffer)
+ * ```typescript
+ * export const manifest: AdapterManifest = {
+ *   manifestVersion: '1.0.0',
+ *   id: 'log-ringbuffer',
+ *   name: 'Log Ring Buffer',
+ *   version: '1.0.0',
+ *   type: 'extension',
+ *   implements: 'ILogRingBuffer',
+ *   extends: {
+ *     adapter: 'logger',
+ *     hook: 'onLog',
+ *     method: 'append',
+ *     priority: 10
+ *   },
+ *   capabilities: { streaming: true }
+ * };
+ * ```
+ *
+ * @example Extension with dependency (SQLite persistence)
+ * ```typescript
+ * export const manifest: AdapterManifest = {
+ *   manifestVersion: '1.0.0',
+ *   id: 'log-persistence',
+ *   name: 'SQLite Log Persistence',
+ *   version: '1.0.0',
+ *   type: 'extension',
+ *   implements: 'ILogPersistence',
+ *   requires: {
+ *     adapters: [{ id: 'db', alias: 'database' }],
+ *     platform: '>= 1.0.0'
+ *   },
+ *   extends: {
+ *     adapter: 'logger',
+ *     hook: 'onLog',
+ *     method: 'write',
+ *     priority: 5
+ *   },
+ *   capabilities: { batch: true, search: true, transactions: true }
+ * };
+ * ```
+ */
+interface AdapterManifest {
+    /**
+     * Manifest schema version.
+     * Used for compatibility checking and evolution.
+     * Format: semver (e.g., "1.0.0")
+     */
+    manifestVersion: string;
+    /**
+     * Unique adapter identifier.
+     * Used in dependency resolution and configuration.
+     * Convention: kebab-case (e.g., "pino-logger", "log-ringbuffer")
+     */
+    id: string;
+    /**
+     * Human-readable adapter name.
+     * Shown in logs, UI, documentation.
+     */
+    name: string;
+    /**
+     * Adapter version.
+     * Format: semver (e.g., "1.0.0")
+     */
+    version: string;
+    /**
+     * Adapter description (optional).
+     * Brief explanation of what this adapter does.
+     */
+    description?: string;
+    /**
+     * Author information (optional).
+     */
+    author?: string;
+    /**
+     * License (optional).
+     * SPDX identifier (e.g., "MIT", "Apache-2.0")
+     */
+    license?: string;
+    /**
+     * Homepage URL (optional).
+     * Link to documentation or repository.
+     */
+    homepage?: string;
+    /**
+     * Adapter type.
+     * - core: Primary adapter implementing a platform interface
+     * - extension: Extends another adapter via hooks
+     * - proxy: Wraps/delegates to another adapter
+     */
+    type: AdapterType;
+    /**
+     * Interface this adapter implements.
+     * Convention: PascalCase interface name (e.g., "ILogger", "ILogRingBuffer")
+     *
+     * This is informational - TypeScript provides compile-time type safety.
+     * No runtime type checking is performed.
+     */
+    implements: string;
+    /**
+     * Required dependencies.
+     *
+     * If any required dependency is missing, adapter load fails immediately.
+     *
+     * @example
+     * ```typescript
+     * requires: {
+     *   adapters: ['db'],                          // Runtime token from config
+     *   adapters: [{ id: 'db', alias: 'database' }], // Runtime token + factory alias
+     *   platform: '>= 1.0.0'                       // Semver range
+     * }
+     * ```
+     */
+    requires?: {
+        /**
+         * Required adapters by runtime token (config key), NOT by `manifest.id`.
+         *
+         * Example:
+         * - `platform.adapters.cache = "@kb-labs/adapters-redis"`
+         * - runtime token is `cache`
+         * - provider manifest id can be `redis-cache`
+         * - dependency must reference `cache`, not `redis-cache`
+         *
+         * Each will be passed to factory function in `deps` parameter.
+         */
+        adapters?: AdapterDependency[];
+        /**
+         * Required platform version (semver range).
+         * Example: ">= 1.0.0", "^1.2.0", "~1.2.3"
+         */
+        platform?: string;
+    };
+    /**
+     * Optional dependencies.
+     *
+     * If optional dependency is missing, adapter still loads (no error).
+     * Factory function receives `undefined` for missing optional deps.
+     *
+     * @example
+     * ```typescript
+     * optional: {
+     *   adapters: ['analytics', 'metrics']
+     * }
+     * ```
+     */
+    optional?: {
+        /** Optional adapters (by ID) */
+        adapters?: string[];
+    };
+    /**
+     * Requested runtime contexts.
+     *
+     * Specifies which runtime contexts this adapter needs.
+     * Requested contexts are injected into the adapter's config by the loader.
+     *
+     * Available contexts:
+     * - 'workspace': { cwd: string } - Workspace directory path
+     * - 'analytics': AnalyticsContext - Analytics enrichment context (source, actor, runId)
+     * - 'tenant': TenantContext - Multi-tenancy context (future)
+     * - 'request': RequestContext - HTTP request context (future)
+     *
+     * @example
+     * ```typescript
+     * contexts: ['workspace', 'analytics']
+     * ```
+     */
+    contexts?: string[];
+    /**
+     * Extension point configuration.
+     *
+     * If present, this adapter extends another adapter via a hook.
+     * The platform automatically connects the extension after all adapters load.
+     *
+     * @example
+     * ```typescript
+     * extends: {
+     *   adapter: 'logger',     // Target adapter
+     *   hook: 'onLog',         // Hook method on target
+     *   method: 'write',       // Method on this adapter
+     *   priority: 5            // Call order (optional)
+     * }
+     * ```
+     */
+    extends?: AdapterExtension;
+    /**
+     * Adapter capabilities.
+     *
+     * Describes what features this adapter supports.
+     * Used for adapter selection and runtime feature detection.
+     *
+     * @example
+     * ```typescript
+     * capabilities: {
+     *   streaming: true,
+     *   batch: true,
+     *   search: true,
+     *   transactions: true,
+     *   custom: { maxBatchSize: 1000 }
+     * }
+     * ```
+     */
+    capabilities?: AdapterCapabilities;
+    /**
+     * Configuration options schema (optional).
+     *
+     * Declares what configuration options this adapter accepts.
+     * Useful for:
+     * - Auto-generating documentation
+     * - IDE auto-completion
+     * - Configuration validation tools
+     * - UI configuration builders
+     *
+     * This is informational only - TypeScript provides compile-time validation.
+     *
+     * @example
+     * ```typescript
+     * configSchema: {
+     *   level: {
+     *     type: 'string',
+     *     enum: ['trace', 'debug', 'info', 'warn', 'error'],
+     *     default: 'info',
+     *     description: 'Minimum log level'
+     *   },
+     *   pretty: {
+     *     type: 'boolean',
+     *     default: false,
+     *     description: 'Enable pretty printing'
+     *   },
+     *   batchSize: {
+     *     type: 'number',
+     *     default: 100,
+     *     description: 'Number of logs per batch'
+     *   }
+     * }
+     * ```
+     */
+    configSchema?: Record<string, {
+        type: "string" | "number" | "boolean" | "object" | "array";
+        description?: string;
+        default?: unknown;
+        required?: boolean;
+        enum?: unknown[];
+        properties?: Record<string, unknown>;
+    }>;
+}
+/**
+ * Adapter factory function signature.
+ *
+ * Every adapter exports a createAdapter function that:
+ * - Accepts adapter-specific config
+ * - Receives dependencies via deps parameter
+ * - Returns adapter instance implementing the declared interface
+ *
+ * @template TConfig - Adapter configuration type
+ * @template TDeps - Dependencies object type (from manifest.requires)
+ * @template TAdapter - Adapter interface type (from manifest.implements)
+ *
+ * @example
+ * ```typescript
+ * export function createAdapter(
+ *   config: PinoConfig,
+ *   deps: { analytics?: IAnalytics }
+ * ): ILogger {
+ *   return new PinoAdapter(config, deps);
+ * }
+ * ```
+ */
+type AdapterFactory<TConfig = unknown, TDeps = Record<string, unknown>, TAdapter = unknown> = (config: TConfig, deps: TDeps) => TAdapter | Promise<TAdapter>;
+
+/**
+ * @module @kb-labs/core-platform/adapters/log-persistence
+ * Persistent log storage adapter interface.
+ *
+ * Purpose:
+ * - Long-term log storage (database, files, etc.)
+ * - Cross-process log aggregation
+ * - Advanced querying (search, filters, pagination)
+ *
+ * Not for:
+ * - Real-time streaming (use ILogRingBuffer)
+ * - Low-latency access to recent logs
+ */
+
+/**
+ * Persistent log storage for historical queries.
+ *
+ * Design:
+ * - Writes logs to database (SQLite, PostgreSQL, etc.)
+ * - Supports batch writes with auto-flush
+ * - Full-text search support
+ * - Retention policy support (delete old logs)
+ * - Pagination for large result sets
+ *
+ * @example
+ * ```typescript
+ * const persistence = await createPersistenceAdapter({
+ *   database: platform.db,
+ *   batchSize: 100,
+ *   flushInterval: 5000,
+ * });
+ *
+ * // Write logs
+ * await persistence.write({ timestamp: Date.now(), level: 'info', message: 'Hello' });
+ *
+ * // Query logs
+ * const result = await persistence.query(
+ *   { level: 'error', startTime: Date.now() - 3600000 },
+ *   { limit: 50, offset: 0 }
+ * );
+ *
+ * // Search logs
+ * const searchResults = await persistence.search('authentication failed');
+ * ```
+ */
+interface ILogPersistence {
+    /**
+     * Write log record to persistent storage.
+     * Logs are buffered and flushed in batches.
+     *
+     * @param record - Log record to persist
+     * @returns Promise that resolves when write is queued (not necessarily flushed)
+     */
+    write(record: LogRecord): Promise<void>;
+    /**
+     * Write multiple log records in batch.
+     * More efficient than multiple write() calls.
+     *
+     * @param records - Array of log records
+     * @returns Promise that resolves when all writes are queued
+     */
+    writeBatch(records: LogRecord[]): Promise<void>;
+    /**
+     * Query logs from persistent storage.
+     *
+     * @param query - Query parameters (time range, level, source)
+     * @param options - Pagination and sorting options
+     * @returns Promise with logs and pagination info
+     *
+     * @example
+     * ```typescript
+     * // Get last 50 error logs
+     * const result = await persistence.query(
+     *   { level: 'error' },
+     *   { limit: 50, sortBy: 'timestamp', sortOrder: 'desc' }
+     * );
+     *
+     * console.log(result.logs); // Array of 50 logs
+     * console.log(result.total); // Total matching logs
+     * console.log(result.hasMore); // true if more pages exist
+     * ```
+     */
+    query(query: LogQuery, options?: {
+        /** Maximum number of logs to return (default: 100) */
+        limit?: number;
+        /** Number of logs to skip (default: 0) */
+        offset?: number;
+        /** Sort by field (default: 'timestamp') */
+        sortBy?: "timestamp" | "level";
+        /** Sort order (default: 'desc') */
+        sortOrder?: "asc" | "desc";
+    }): Promise<{
+        /** Logs matching query */
+        logs: LogRecord[];
+        /** Total number of logs matching query (ignoring limit/offset) */
+        total: number;
+        /** True if more results are available (offset + logs.length < total) */
+        hasMore: boolean;
+    }>;
+    /**
+     * Get single log record by ID.
+     *
+     * @param id - Log record ID
+     * @returns Promise with log record or null if not found
+     */
+    getById(id: string): Promise<LogRecord | null>;
+    /**
+     * Search logs by text query (full-text search).
+     * Searches message field using database FTS capabilities.
+     *
+     * @param searchText - Search query (supports database-specific syntax)
+     * @param options - Pagination options
+     * @returns Promise with matching logs
+     *
+     * @example
+     * ```typescript
+     * // Simple search
+     * const results = await persistence.search('authentication failed');
+     *
+     * // Advanced search (SQLite FTS5 syntax)
+     * const results = await persistence.search('auth* AND (error OR warn)');
+     * ```
+     */
+    search(searchText: string, options?: {
+        /** Maximum number of logs to return (default: 100) */
+        limit?: number;
+        /** Number of logs to skip (default: 0) */
+        offset?: number;
+    }): Promise<{
+        /** Logs matching search query */
+        logs: LogRecord[];
+        /** Total number of logs matching search */
+        total: number;
+        /** True if more results are available */
+        hasMore: boolean;
+    }>;
+    /**
+     * Delete logs older than specified timestamp.
+     * Used for implementing retention policies.
+     *
+     * @param beforeTimestamp - Delete logs before this timestamp (milliseconds)
+     * @returns Promise with number of deleted logs
+     *
+     * @example
+     * ```typescript
+     * // Delete logs older than 30 days
+     * const thirtyDaysAgo = Date.now() - 30 * 24 * 60 * 60 * 1000;
+     * const deleted = await persistence.deleteOlderThan(thirtyDaysAgo);
+     * console.log(`Deleted ${deleted} old logs`);
+     * ```
+     */
+    deleteOlderThan(beforeTimestamp: number): Promise<number>;
+    /**
+     * Get statistics about stored logs.
+     *
+     * @returns Promise with log storage statistics
+     */
+    getStats(): Promise<{
+        /** Total number of logs in storage */
+        totalLogs: number;
+        /** Timestamp of oldest log (0 if empty) */
+        oldestTimestamp: number;
+        /** Timestamp of newest log (0 if empty) */
+        newestTimestamp: number;
+        /** Storage size in bytes */
+        sizeBytes: number;
+    }>;
+    /**
+     * Close persistence adapter and flush pending writes.
+     * Should be called during application shutdown.
+     *
+     * @returns Promise that resolves when all pending writes are flushed
+     */
+    close?(): Promise<void>;
+}
+/**
+ * Configuration for log persistence adapter.
+ */
+interface LogPersistenceConfig {
+    /**
+     * Database adapter for storage.
+     * Must be ISQLDatabase (SQLite, PostgreSQL, etc.)
+     */
+    database: ISQLDatabase;
+    /**
+     * Table name for logs.
+     * @default 'logs'
+     */
+    tableName?: string;
+    /**
+     * Batch size for bulk writes.
+     * Logs are buffered and written in batches for performance.
+     * @default 100
+     */
+    batchSize?: number;
+    /**
+     * Flush interval in milliseconds.
+     * Pending logs are flushed at this interval even if batch is not full.
+     * @default 5000 (5 seconds)
+     */
+    flushInterval?: number;
+}
+
+/**
+ * @module @kb-labs/core-platform/adapters/execution
+ * Execution backend interface (plugin execution layer).
+ */
+/**
+ * Execution backend interface.
+ * Handles plugin execution (in-process, worker-pool, or remote).
+ *
+ * Implementations:
+ * - InProcessBackend: Same process, no isolation (dev mode)
+ * - WorkerPoolBackend: Worker pool with fault isolation (production)
+ * - RemoteExecutionBackend: Remote executor service (Phase 3)
+ */
+interface IExecutionBackend {
+    /**
+     * Execute a plugin handler.
+     *
+     * @param request - Execution request with descriptor, pluginRoot, handlerRef
+     * @param options - Optional execution options (signal, etc.)
+     * @returns Execution result with data/error
+     */
+    execute(request: ExecutionRequest, options?: ExecuteOptions): Promise<ExecutionResult>;
+    /**
+     * Shutdown execution backend gracefully.
+     * Closes worker pool, cleanup resources.
+     */
+    shutdown(): Promise<void>;
+}
+/**
+ * Execution options (optional).
+ */
+interface ExecuteOptions {
+    /** Abort signal for cancellation */
+    signal?: AbortSignal;
+    /** Additional options */
+    [key: string]: unknown;
+}
+/**
+ * Execution request - minimal interface for core-platform.
+ * Full implementation in @kb-labs/plugin-execution.
+ */
+interface ExecutionRequest {
+    /** Unique execution ID */
+    executionId: string;
+    /**
+     * Runtime descriptor containing execution context.
+     *
+     * Type is `any` to allow implementations to use their concrete descriptor types
+     * (e.g., PluginContextDescriptor from @kb-labs/plugin-contracts).
+     *
+     * This is intentional for interface contracts - concrete type determined by implementation.
+     */
+    descriptor: any;
+    /** Plugin root directory (absolute path) */
+    pluginRoot: string;
+    /** Handler reference (relative path) */
+    handlerRef: string;
+    /** Input data passed to handler */
+    input: unknown;
+    /** Execution timeout in milliseconds */
+    timeoutMs?: number;
+    /** Optional execution target affinity */
+    target?: {
+        environmentId?: string;
+        workspaceId?: string;
+        namespace?: string;
+        workdir?: string;
+    };
+    /** Additional configuration */
+    [key: string]: unknown;
+}
+/**
+ * Execution result - minimal interface for core-platform.
+ * Full implementation in @kb-labs/plugin-execution.
+ */
+interface ExecutionResult {
+    /** Success flag */
+    ok: boolean;
+    /** Result data (if ok) */
+    data?: unknown;
+    /**
+     * Error details (if !ok).
+     * Type is `any` to allow implementations to use their own error types.
+     * Expected to have at least { message: string } structure.
+     */
+    error?: any;
+    /** Execution time in milliseconds */
+    executionTimeMs: number;
+    /**
+     * Execution metadata (optional).
+     * Contains backend-specific info, timing, plugin info.
+     * Type is `any` to allow implementations to extend with their own metadata types.
+     */
+    metadata?: any;
+    /** Additional fields allowed for extensibility */
+    [key: string]: unknown;
+}
+
+/**
+ * @module @kb-labs/core-platform/environment/environment-provider
+ * Environment lifecycle abstraction.
+ *
+ * This port manages long-lived execution environments (container/pod/vm/sandbox).
+ * It intentionally does NOT execute plugin jobs directly.
+ */
+/**
+ * Environment status in lifecycle.
+ */
+type EnvironmentStatus = "pending" | "provisioning" | "ready" | "degraded" | "terminating" | "terminated" | "failed";
+/**
+ * Environment resource limits.
+ */
+interface EnvironmentResources {
+    cpu?: string;
+    memory?: string;
+    disk?: string;
+    gpu?: string;
+}
+/**
+ * Environment lease metadata.
+ */
+interface EnvironmentLease {
+    leaseId: string;
+    acquiredAt: string;
+    expiresAt: string;
+    owner?: string;
+}
+/**
+ * Environment network endpoint descriptor.
+ */
+interface EnvironmentEndpoint {
+    name: string;
+    protocol?: "http" | "https" | "tcp" | "udp" | "unix";
+    host?: string;
+    port?: number;
+    path?: string;
+}
+/**
+ * Environment creation request.
+ */
+interface CreateEnvironmentRequest {
+    tenantId?: string;
+    namespace?: string;
+    runId?: string;
+    templateId?: string;
+    image?: string;
+    workspacePath?: string;
+    command?: string[];
+    env?: Record<string, string>;
+    resources?: EnvironmentResources;
+    ttlMs?: number;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Created environment descriptor.
+ */
+interface EnvironmentDescriptor {
+    environmentId: string;
+    provider: string;
+    status: EnvironmentStatus;
+    createdAt: string;
+    updatedAt: string;
+    lease?: EnvironmentLease;
+    endpoints?: EnvironmentEndpoint[];
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Environment status result.
+ */
+interface EnvironmentStatusResult {
+    environmentId: string;
+    status: EnvironmentStatus;
+    reason?: string;
+    updatedAt: string;
+    lease?: EnvironmentLease;
+}
+/**
+ * Environment provider capabilities.
+ */
+interface EnvironmentProviderCapabilities {
+    supportsLeaseRenewal?: boolean;
+    supportsSnapshots?: boolean;
+    supportsExecProbe?: boolean;
+    supportsLogs?: boolean;
+    custom?: Record<string, unknown>;
+}
+/**
+ * Long-lived environment provider abstraction.
+ *
+ * Responsibilities:
+ * - Provision, inspect, and destroy environments
+ * - Manage lease lifecycle
+ *
+ * Non-responsibilities:
+ * - Plugin/job dispatch and horizontal runner scaling (ExecutionBackend)
+ */
+interface IEnvironmentProvider {
+    /**
+     * Create a new environment instance.
+     */
+    create(request: CreateEnvironmentRequest): Promise<EnvironmentDescriptor>;
+    /**
+     * Get current status for an environment.
+     */
+    getStatus(environmentId: string): Promise<EnvironmentStatusResult>;
+    /**
+     * Destroy environment and release resources.
+     * Must be idempotent.
+     */
+    destroy(environmentId: string, reason?: string): Promise<void>;
+    /**
+     * Renew environment lease (if provider supports it).
+     */
+    renewLease?(environmentId: string, ttlMs: number): Promise<EnvironmentLease>;
+    /**
+     * Provider capability declaration.
+     */
+    getCapabilities?(): EnvironmentProviderCapabilities;
+}
+
+/**
+ * @module @kb-labs/core-platform/workspace/workspace-provider
+ * Workspace lifecycle abstraction.
+ *
+ * This port manages workspace materialization and attach/release lifecycle.
+ */
+type WorkspaceStatus = "pending" | "materializing" | "ready" | "attaching" | "attached" | "releasing" | "released" | "failed";
+interface WorkspaceMount {
+    hostPath?: string;
+    mountPath?: string;
+    readOnly?: boolean;
+}
+interface MaterializeWorkspaceRequest {
+    workspaceId?: string;
+    tenantId?: string;
+    namespace?: string;
+    sourceRef?: string;
+    basePath?: string;
+    metadata?: Record<string, unknown>;
+}
+interface WorkspaceDescriptor {
+    workspaceId: string;
+    provider: string;
+    status: WorkspaceStatus;
+    rootPath?: string;
+    mount?: WorkspaceMount;
+    createdAt: string;
+    updatedAt: string;
+    metadata?: Record<string, unknown>;
+}
+interface AttachWorkspaceRequest {
+    workspaceId: string;
+    environmentId: string;
+    mountPath?: string;
+    readOnly?: boolean;
+}
+interface WorkspaceAttachment {
+    workspaceId: string;
+    environmentId: string;
+    mountPath?: string;
+    attachedAt: string;
+    metadata?: Record<string, unknown>;
+}
+interface WorkspaceStatusResult {
+    workspaceId: string;
+    status: WorkspaceStatus;
+    reason?: string;
+    updatedAt: string;
+}
+interface WorkspaceProviderCapabilities {
+    supportsAttach?: boolean;
+    supportsRelease?: boolean;
+    supportsReadOnlyMounts?: boolean;
+    custom?: Record<string, unknown>;
+}
+interface IWorkspaceProvider {
+    materialize(request: MaterializeWorkspaceRequest): Promise<WorkspaceDescriptor>;
+    attach(request: AttachWorkspaceRequest): Promise<WorkspaceAttachment>;
+    release(workspaceId: string, environmentId?: string): Promise<void>;
+    getStatus(workspaceId: string): Promise<WorkspaceStatusResult>;
+    getCapabilities?(): WorkspaceProviderCapabilities;
+}
+
+/**
+ * @module @kb-labs/core-platform/snapshot/snapshot-provider
+ * Snapshot lifecycle abstraction.
+ *
+ * This port captures/restores point-in-time workspace or environment state.
+ */
+type SnapshotStatus = "pending" | "capturing" | "ready" | "restoring" | "deleted" | "failed";
+interface CaptureSnapshotRequest {
+    snapshotId?: string;
+    workspaceId?: string;
+    environmentId?: string;
+    sourcePath?: string;
+    namespace?: string;
+    metadata?: Record<string, unknown>;
+}
+interface SnapshotDescriptor {
+    snapshotId: string;
+    provider: string;
+    status: SnapshotStatus;
+    createdAt: string;
+    updatedAt: string;
+    workspaceId?: string;
+    environmentId?: string;
+    sizeBytes?: number;
+    metadata?: Record<string, unknown>;
+}
+interface RestoreSnapshotRequest {
+    snapshotId: string;
+    workspaceId?: string;
+    environmentId?: string;
+    targetPath?: string;
+    overwrite?: boolean;
+    metadata?: Record<string, unknown>;
+}
+interface RestoreSnapshotResult {
+    snapshotId: string;
+    restoredAt: string;
+    workspaceId?: string;
+    environmentId?: string;
+    targetPath?: string;
+    metadata?: Record<string, unknown>;
+}
+interface SnapshotStatusResult {
+    snapshotId: string;
+    status: SnapshotStatus;
+    reason?: string;
+    updatedAt: string;
+}
+interface SnapshotGarbageCollectRequest {
+    namespace?: string;
+    before?: string;
+    limit?: number;
+    dryRun?: boolean;
+}
+interface SnapshotGarbageCollectResult {
+    scanned: number;
+    deleted: number;
+    dryRun: boolean;
+}
+interface SnapshotProviderCapabilities {
+    supportsWorkspaceSnapshots?: boolean;
+    supportsEnvironmentSnapshots?: boolean;
+    supportsGarbageCollection?: boolean;
+    supportsIncrementalSnapshots?: boolean;
+    custom?: Record<string, unknown>;
+}
+interface ISnapshotProvider {
+    capture(request: CaptureSnapshotRequest): Promise<SnapshotDescriptor>;
+    restore(request: RestoreSnapshotRequest): Promise<RestoreSnapshotResult>;
+    getStatus(snapshotId: string): Promise<SnapshotStatusResult>;
+    delete(snapshotId: string): Promise<void>;
+    garbageCollect?(request: SnapshotGarbageCollectRequest): Promise<SnapshotGarbageCollectResult>;
+    getCapabilities?(): SnapshotProviderCapabilities;
+}
+
+export type { AdapterManifest as A, RestoreSnapshotResult as B, CreateEnvironmentRequest as C, SnapshotStatusResult as D, ExecutionRequest as E, SnapshotGarbageCollectRequest as F, SnapshotGarbageCollectResult as G, SnapshotProviderCapabilities as H, ILogPersistence as I, LogPersistenceConfig as L, MaterializeWorkspaceRequest as M, RestoreSnapshotRequest as R, SnapshotStatus as S, WorkspaceStatus as W, AdapterType as a, AdapterDependency as b, AdapterExtension as c, AdapterCapabilities as d, AdapterFactory as e, IExecutionBackend as f, ExecutionResult as g, ExecuteOptions as h, IEnvironmentProvider as i, EnvironmentStatus as j, EnvironmentResources as k, EnvironmentLease as l, EnvironmentEndpoint as m, EnvironmentDescriptor as n, EnvironmentStatusResult as o, EnvironmentProviderCapabilities as p, IWorkspaceProvider as q, WorkspaceMount as r, WorkspaceDescriptor as s, AttachWorkspaceRequest as t, WorkspaceAttachment as u, WorkspaceStatusResult as v, WorkspaceProviderCapabilities as w, ISnapshotProvider as x, CaptureSnapshotRequest as y, SnapshotDescriptor as z };