@objectstack/spec 2.0.5 → 2.0.7

package/dist/index-CmY8tgpL.d.ts

@@ -0,0 +1,2102 @@
+import { Q as QueryAST, a as FieldSchema } from './field.zod-DuaF0Lcl.js';
+import { D as DataEngineQueryOptions, a as DataEngineInsertOptions, b as DataEngineUpdateOptions, c as DataEngineDeleteOptions, d as DataEngineCountOptions, e as DataEngineAggregateOptions, f as DataEngineRequest, g as DriverOptions, h as DriverCapabilities, O as ObjectSchema } from './driver.zod-B3Q0oLlF.js';
+import { z } from 'zod';
+
+/**
+ * Logger Contract
+ *
+ * Defines the interface for logging in ObjectStack.
+ * Compatible with both browser console and structured logging systems.
+ */
+interface Logger {
+    /**
+     * Log a debug message
+     * @param message - The message to log
+     * @param meta - Optional metadata to include
+     */
+    debug(message: string, meta?: Record<string, any>): void;
+    /**
+     * Log an informational message
+     * @param message - The message to log
+     * @param meta - Optional metadata to include
+     */
+    info(message: string, meta?: Record<string, any>): void;
+    /**
+     * Log a warning message
+     * @param message - The message to log
+     * @param meta - Optional metadata to include
+     */
+    warn(message: string, meta?: Record<string, any>): void;
+    /**
+     * Log an error message
+     * @param message - The message to log
+     * @param error - Optional error object
+     * @param meta - Optional metadata to include
+     */
+    error(message: string, error?: Error, meta?: Record<string, any>): void;
+    /**
+     * Log a fatal error message
+     * @param message - The message to log
+     * @param error - Optional error object
+     * @param meta - Optional metadata to include
+     */
+    fatal?(message: string, error?: Error, meta?: Record<string, any>): void;
+    /**
+     * Create a child logger with additional context
+     * @param context - Context to add to all logs from this child
+     */
+    child?(context: Record<string, any>): Logger;
+    /**
+     * Set trace context for distributed tracing
+     * @param traceId - Trace identifier
+     * @param spanId - Span identifier
+     */
+    withTrace?(traceId: string, spanId?: string): Logger;
+    /**
+     * Compatibility method for console.log usage
+     * @param message - The message to log
+     * @param args - Additional arguments
+     */
+    log?(message: string, ...args: any[]): void;
+    /**
+     * Cleanup resources (close file streams, etc.)
+     * Should be called when the logger is no longer needed
+     */
+    destroy?(): Promise<void>;
+}
+
+/**
+ * IDataEngine - Standard Data Engine Interface
+ *
+ * Abstract interface for data persistence capabilities.
+ * Following the Dependency Inversion Principle - plugins depend on this interface,
+ * not on concrete database implementations.
+ *
+ * Aligned with 'src/data/data-engine.zod.ts' in @objectstack/spec.
+ */
+interface IDataEngine {
+    find(objectName: string, query?: DataEngineQueryOptions): Promise<any[]>;
+    findOne(objectName: string, query?: DataEngineQueryOptions): Promise<any>;
+    insert(objectName: string, data: any | any[], options?: DataEngineInsertOptions): Promise<any>;
+    update(objectName: string, data: any, options?: DataEngineUpdateOptions): Promise<any>;
+    delete(objectName: string, options?: DataEngineDeleteOptions): Promise<any>;
+    count(objectName: string, query?: DataEngineCountOptions): Promise<number>;
+    aggregate(objectName: string, query: DataEngineAggregateOptions): Promise<any[]>;
+    /**
+     * Vector Search (AI/RAG)
+     */
+    vectorFind?(objectName: string, vector: number[], options?: {
+        filter?: any;
+        limit?: number;
+        select?: string[];
+        threshold?: number;
+    }): Promise<any[]>;
+    /**
+     * Batch Operations (Transactional)
+     */
+    batch?(requests: DataEngineRequest[], options?: {
+        transaction?: boolean;
+    }): Promise<any[]>;
+    /**
+     * Execute raw command (Escape hatch)
+     */
+    execute?(command: any, options?: Record<string, any>): Promise<any>;
+}
+interface DriverInterface {
+    name: string;
+    version: string;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    find(object: string, query: QueryAST, options?: DriverOptions): Promise<any[]>;
+    findOne(object: string, query: QueryAST, options?: DriverOptions): Promise<any>;
+    create(object: string, data: any, options?: DriverOptions): Promise<any>;
+    update(object: string, id: any, data: any, options?: DriverOptions): Promise<any>;
+    delete(object: string, id: any, options?: DriverOptions): Promise<any>;
+    /**
+     * Bulk & Batch Operations
+     */
+    bulkCreate?(object: string, data: any[], options?: DriverOptions): Promise<any>;
+    updateMany?(object: string, query: QueryAST, data: any, options?: DriverOptions): Promise<any>;
+    deleteMany?(object: string, query: QueryAST, options?: DriverOptions): Promise<any>;
+    count?(object: string, query: QueryAST, options?: DriverOptions): Promise<number>;
+    /**
+     * Raw Execution
+     */
+    execute?(command: any, params?: any, options?: DriverOptions): Promise<any>;
+}
+
+/**
+ * IDataDriver - Comprehensive Database Driver Interface
+ *
+ * Pure TypeScript interface for all storage adapters (Postgres, Mongo, Excel, Salesforce).
+ * Mirrors the capabilities described in `data/driver.zod.ts` (DriverInterfaceSchema) but
+ * expressed as a TypeScript interface for type-safe implementation contracts.
+ *
+ * This is the contract that all ObjectStack database drivers MUST implement.
+ * Use `DriverCapabilitiesSchema` / `DriverConfigSchema` from `data/driver.zod.ts` for
+ * runtime capability detection and configuration validation.
+ *
+ * @see DriverCapabilitiesSchema for runtime capability flags
+ * @see DriverConfigSchema for driver configuration validation
+ */
+interface IDataDriver {
+    /** Driver unique name (e.g., 'postgresql', 'mongodb', 'rest_api') */
+    readonly name: string;
+    /** Driver version */
+    readonly version: string;
+    /** Capabilities descriptor */
+    readonly supports: DriverCapabilities;
+    /** Initialize connection pool or authenticate */
+    connect(): Promise<void>;
+    /** Close connections and cleanup resources */
+    disconnect(): Promise<void>;
+    /** Check connection health */
+    checkHealth(): Promise<boolean>;
+    /** Get connection pool statistics (optional) */
+    getPoolStats?(): {
+        total: number;
+        idle: number;
+        active: number;
+        waiting: number;
+    } | undefined;
+    /**
+     * Execute a raw command/query native to the driver.
+     *
+     * @param command - Raw command (SQL string, shell command, or API payload)
+     * @param parameters - Bound parameters for safe execution
+     * @param options - Driver options (transaction context, timeout)
+     * @returns Raw result from the driver
+     */
+    execute(command: unknown, parameters?: unknown[], options?: DriverOptions): Promise<unknown>;
+    /**
+     * Find multiple records matching the structured query.
+     * MUST return `id` as string. MUST NOT return implementation details like `_id`.
+     */
+    find(object: string, query: QueryAST, options?: DriverOptions): Promise<Record<string, unknown>[]>;
+    /**
+     * Stream records matching the structured query.
+     * Optimized for large datasets to avoid memory overflow.
+     * Returns an AsyncIterable or ReadableStream.
+     */
+    findStream(object: string, query: QueryAST, options?: DriverOptions): unknown;
+    /**
+     * Find a single record by query.
+     * MUST return `id` as string. MUST NOT return implementation details like `_id`.
+     */
+    findOne(object: string, query: QueryAST, options?: DriverOptions): Promise<Record<string, unknown> | null>;
+    /**
+     * Create a new record.
+     * MUST return `id` as string. MUST NOT return implementation details like `_id`.
+     */
+    create(object: string, data: Record<string, unknown>, options?: DriverOptions): Promise<Record<string, unknown>>;
+    /**
+     * Update an existing record by ID.
+     * MUST return `id` as string. MUST NOT return implementation details like `_id`.
+     */
+    update(object: string, id: string | number, data: Record<string, unknown>, options?: DriverOptions): Promise<Record<string, unknown>>;
+    /**
+     * Upsert (Update or Insert) a record.
+     */
+    upsert(object: string, data: Record<string, unknown>, conflictKeys?: string[], options?: DriverOptions): Promise<Record<string, unknown>>;
+    /**
+     * Delete a record by ID.
+     * @returns True if deleted, false if not found.
+     */
+    delete(object: string, id: string | number, options?: DriverOptions): Promise<boolean>;
+    /**
+     * Count records matching a query.
+     */
+    count(object: string, query?: QueryAST, options?: DriverOptions): Promise<number>;
+    /** Create multiple records in a single batch */
+    bulkCreate(object: string, dataArray: Record<string, unknown>[], options?: DriverOptions): Promise<Record<string, unknown>[]>;
+    /** Update multiple records in a single batch */
+    bulkUpdate(object: string, updates: Array<{
+        id: string | number;
+        data: Record<string, unknown>;
+    }>, options?: DriverOptions): Promise<Record<string, unknown>[]>;
+    /** Delete multiple records in a single batch */
+    bulkDelete(object: string, ids: Array<string | number>, options?: DriverOptions): Promise<void>;
+    /** Update multiple records matching a query (optional) */
+    updateMany?(object: string, query: QueryAST, data: Record<string, unknown>, options?: DriverOptions): Promise<number>;
+    /** Delete multiple records matching a query (optional) */
+    deleteMany?(object: string, query: QueryAST, options?: DriverOptions): Promise<number>;
+    /**
+     * Begin a new database transaction.
+     * @returns A transaction handle to pass via `options.transaction`.
+     */
+    beginTransaction(options?: {
+        isolationLevel?: string;
+    }): Promise<unknown>;
+    /** Commit the transaction */
+    commit(transaction: unknown): Promise<void>;
+    /** Rollback the transaction */
+    rollback(transaction: unknown): Promise<void>;
+    /**
+     * Synchronize the database schema with the Object definition.
+     * Idempotent: creates tables if missing, adds columns, updates indexes.
+     */
+    syncSchema(object: string, schema: unknown, options?: DriverOptions): Promise<void>;
+    /** Drop the underlying table or collection (destructive) */
+    dropTable(object: string, options?: DriverOptions): Promise<void>;
+    /**
+     * Analyze query performance.
+     * Returns execution plan without executing the query (optional).
+     */
+    explain?(object: string, query: QueryAST, options?: DriverOptions): Promise<unknown>;
+}
+
+/**
+ * IHttpServer - Standard HTTP Server Interface
+ *
+ * Abstract interface for HTTP server capabilities.
+ * This allows plugins to interact with HTTP servers without knowing
+ * the underlying implementation (Express, Fastify, Hono, etc.).
+ *
+ * Follows Dependency Inversion Principle - plugins depend on this interface,
+ * not on concrete HTTP framework implementations.
+ */
+/**
+ * Generic HTTP Request type
+ * Abstraction over framework-specific request objects
+ */
+interface IHttpRequest {
+    /** Request path parameters */
+    params: Record<string, string>;
+    /** Request query parameters */
+    query: Record<string, string | string[]>;
+    /** Request body */
+    body?: any;
+    /** Request headers */
+    headers: Record<string, string | string[]>;
+    /** HTTP method */
+    method: string;
+    /** Request path */
+    path: string;
+}
+/**
+ * Generic HTTP Response type
+ * Abstraction over framework-specific response objects
+ */
+interface IHttpResponse {
+    /**
+     * Send a JSON response
+     * @param data - Data to send
+     */
+    json(data: any): void | Promise<void>;
+    /**
+     * Send a text/html response
+     * @param data - Data to send
+     */
+    send(data: string): void | Promise<void>;
+    /**
+     * Set HTTP status code
+     * @param code - HTTP status code
+     */
+    status(code: number): IHttpResponse;
+    /**
+     * Set response header
+     * @param name - Header name
+     * @param value - Header value (string or array of strings for multi-value headers)
+     */
+    header(name: string, value: string | string[]): IHttpResponse;
+}
+/**
+ * Route handler function
+ */
+type RouteHandler = (req: IHttpRequest, res: IHttpResponse) => void | Promise<void>;
+/**
+ * Middleware function
+ */
+type Middleware = (req: IHttpRequest, res: IHttpResponse, next: () => void | Promise<void>) => void | Promise<void>;
+/**
+ * IHttpServer - HTTP Server capability interface
+ *
+ * Defines the contract for HTTP server implementations.
+ * Concrete implementations (Express, Fastify, Hono) should implement this interface.
+ */
+interface IHttpServer {
+    /**
+     * Register a GET route handler
+     * @param path - Route path (e.g., '/api/users/:id')
+     * @param handler - Route handler function
+     */
+    get(path: string, handler: RouteHandler): void;
+    /**
+     * Register a POST route handler
+     * @param path - Route path
+     * @param handler - Route handler function
+     */
+    post(path: string, handler: RouteHandler): void;
+    /**
+     * Register a PUT route handler
+     * @param path - Route path
+     * @param handler - Route handler function
+     */
+    put(path: string, handler: RouteHandler): void;
+    /**
+     * Register a DELETE route handler
+     * @param path - Route path
+     * @param handler - Route handler function
+     */
+    delete(path: string, handler: RouteHandler): void;
+    /**
+     * Register a PATCH route handler
+     * @param path - Route path
+     * @param handler - Route handler function
+     */
+    patch(path: string, handler: RouteHandler): void;
+    /**
+     * Register middleware
+     * @param path - Optional path to apply middleware to (if omitted, applies globally)
+     * @param handler - Middleware function
+     */
+    use(path: string | Middleware, handler?: Middleware): void;
+    /**
+     * Start the HTTP server
+     * @param port - Port number to listen on
+     * @returns Promise that resolves when server is ready
+     */
+    listen(port: number): Promise<void>;
+    /**
+     * Stop the HTTP server
+     * @returns Promise that resolves when server is stopped
+     */
+    close?(): Promise<void>;
+}
+
+/**
+ * IServiceRegistry - Service Registry Interface
+ *
+ * Abstract interface for managing service registration and lookup.
+ * This provides a single source of truth for all services in the system.
+ *
+ * Following the Dependency Inversion Principle - both kernel implementations
+ * and plugins depend on this interface, not on concrete implementations.
+ */
+interface IServiceRegistry {
+    /**
+     * Register a service with a unique name
+     * @param name - Unique service identifier
+     * @param service - The service instance to register
+     * @throws Error if service name is already registered
+     */
+    register<T>(name: string, service: T): void;
+    /**
+     * Get a registered service by name (synchronous)
+     * @param name - Service identifier
+     * @returns The registered service
+     * @throws Error if service is not found
+     */
+    get<T>(name: string): T;
+    /**
+     * Get a registered service by name (asynchronous)
+     * Useful for lazy-loaded or async-initialized services
+     * @param name - Service identifier
+     * @param scopeId - Optional scope identifier for scoped services
+     * @returns Promise resolving to the registered service
+     * @throws Error if service is not found
+     */
+    getAsync<T>(name: string, scopeId?: string): Promise<T>;
+    /**
+     * Check if a service is registered
+     * @param name - Service identifier
+     * @returns True if service is registered, false otherwise
+     */
+    has(name: string): boolean;
+    /**
+     * Unregister a service
+     * @param name - Service identifier
+     * @returns True if service was unregistered, false if it wasn't registered
+     */
+    unregister(name: string): boolean;
+    /**
+     * Get all registered service names
+     * @returns Array of service names
+     */
+    getServiceNames?(): string[];
+    /**
+     * Clear all registered services
+     * Useful for cleanup in tests or during shutdown
+     */
+    clear?(): void;
+}
+/**
+ * BasicServiceRegistry - Simple synchronous implementation
+ * Used by ObjectKernel for basic service management
+ */
+interface IBasicServiceRegistry extends IServiceRegistry {
+}
+/**
+ * AdvancedServiceRegistry - Enhanced implementation with additional features
+ * Used by ObjectKernel for advanced service management
+ */
+interface IAdvancedServiceRegistry extends IServiceRegistry {
+    /**
+     * Register a factory function that creates services on-demand
+     * @param name - Service identifier
+     * @param factory - Factory function that creates the service
+     * @param singleton - If true, factory is called once and result is cached
+     */
+    registerFactory?<T>(name: string, factory: () => T | Promise<T>, singleton?: boolean): void;
+    /**
+     * Register a scoped service (per-request, per-session, etc.)
+     * @param name - Service identifier
+     * @param factory - Factory function that creates the service
+     * @param scopeType - Type of scope ('request', 'session', 'transaction', etc.)
+     */
+    registerScoped?<T>(name: string, factory: (scopeId: string) => T | Promise<T>, scopeType: string): void;
+    /**
+     * Create a new scope for scoped services
+     * @param scopeType - Type of scope
+     * @returns Scope identifier
+     */
+    createScope?(scopeType: string): string;
+    /**
+     * Dispose a scope and cleanup scoped services
+     * @param scopeId - Scope identifier
+     */
+    disposeScope?(scopeId: string): Promise<void>;
+}
+
+/**
+ * IPluginValidator - Plugin Validator Interface
+ *
+ * Abstract interface for validating plugins before registration and startup.
+ * Extracted from PluginLoader to follow Single Responsibility Principle.
+ */
+/**
+ * Validation result for a plugin
+ */
+interface ValidationResult {
+    /**
+     * Whether the plugin passed validation
+     */
+    valid: boolean;
+    /**
+     * Validation errors (if any)
+     */
+    errors?: Array<{
+        field: string;
+        message: string;
+        code?: string;
+    }>;
+    /**
+     * Validation warnings (non-fatal issues)
+     */
+    warnings?: Array<{
+        field: string;
+        message: string;
+        code?: string;
+    }>;
+}
+/**
+ * Plugin metadata for validation
+ */
+interface Plugin {
+    /**
+     * Unique plugin identifier
+     */
+    name: string;
+    /**
+     * Plugin version (semver)
+     */
+    version?: string;
+    /**
+     * Plugin dependencies
+     */
+    dependencies?: string[];
+    /**
+     * Plugin initialization function
+     */
+    init?: (context: any) => void | Promise<void>;
+    /**
+     * Plugin startup function
+     */
+    start?: (context: any) => void | Promise<void>;
+    /**
+     * Plugin destruction function
+     */
+    destroy?: (context: any) => void | Promise<void>;
+    /**
+     * Plugin signature for verification (optional)
+     */
+    signature?: string;
+    /**
+     * Additional plugin metadata
+     */
+    [key: string]: any;
+}
+/**
+ * IPluginValidator - Plugin validation interface
+ */
+interface IPluginValidator {
+    /**
+     * Validate a plugin object structure
+     * @param plugin - Plugin to validate
+     * @returns Validation result
+     */
+    validate(plugin: unknown): ValidationResult;
+    /**
+     * Validate plugin version format (semver)
+     * @param version - Version string to validate
+     * @returns True if version is valid, false otherwise
+     */
+    validateVersion(version: string): boolean;
+    /**
+     * Validate plugin cryptographic signature (optional)
+     * Used for plugin security verification
+     * @param plugin - Plugin to validate
+     * @returns Promise resolving to true if signature is valid
+     */
+    validateSignature?(plugin: Plugin): Promise<boolean>;
+    /**
+     * Validate plugin dependencies are satisfied
+     * @param plugin - Plugin to validate
+     * @param registry - Map of already registered plugins
+     * @throws Error if dependencies are not satisfied
+     */
+    validateDependencies(plugin: Plugin, registry: Map<string, Plugin>): void;
+    /**
+     * Validate plugin has required lifecycle methods
+     * @param plugin - Plugin to validate
+     * @returns True if plugin has valid lifecycle methods
+     */
+    validateLifecycle?(plugin: Plugin): boolean;
+}
+
+/**
+ * IStartupOrchestrator - Startup Orchestrator Interface
+ *
+ * Abstract interface for orchestrating plugin startup with advanced features:
+ * - Timeout handling
+ * - Rollback on failure
+ * - Health checks
+ * - Startup metrics
+ *
+ * Extracted from PluginLoader to follow Single Responsibility Principle.
+ */
+/**
+ * Startup options for orchestration
+ */
+interface StartupOptions {
+    /**
+     * Maximum time (ms) to wait for each plugin to start
+     * @default 30000 (30 seconds)
+     */
+    timeout?: number;
+    /**
+     * Whether to rollback (destroy) already-started plugins on failure
+     * @default true
+     */
+    rollbackOnFailure?: boolean;
+    /**
+     * Whether to run health checks after startup
+     * @default false
+     */
+    healthCheck?: boolean;
+    /**
+     * Whether to run plugins in parallel (if dependencies allow)
+     * @default false (sequential startup)
+     */
+    parallel?: boolean;
+    /**
+     * Custom context to pass to plugin lifecycle methods
+     */
+    context?: any;
+}
+/**
+ * Plugin startup result
+ */
+interface PluginStartupResult {
+    /**
+     * Plugin that was started
+     */
+    plugin: Plugin;
+    /**
+     * Whether startup was successful
+     */
+    success: boolean;
+    /**
+     * Time taken to start (milliseconds)
+     */
+    duration: number;
+    /**
+     * Error if startup failed
+     */
+    error?: Error;
+    /**
+     * Health status after startup (if healthCheck enabled)
+     */
+    health?: HealthStatus;
+}
+/**
+ * Health status for a plugin
+ */
+interface HealthStatus {
+    /**
+     * Whether the plugin is healthy
+     */
+    healthy: boolean;
+    /**
+     * Health check timestamp
+     */
+    timestamp: number;
+    /**
+     * Optional health details
+     */
+    details?: Record<string, any>;
+    /**
+     * Optional error message if unhealthy
+     */
+    message?: string;
+}
+/**
+ * IStartupOrchestrator - Plugin startup orchestration interface
+ */
+interface IStartupOrchestrator {
+    /**
+     * Orchestrate startup of multiple plugins
+     * Handles timeout, rollback, and health checks
+     * @param plugins - Array of plugins to start (in dependency order)
+     * @param options - Startup options
+     * @returns Promise resolving to startup results for each plugin
+     */
+    orchestrateStartup(plugins: Plugin[], options: StartupOptions): Promise<PluginStartupResult[]>;
+    /**
+     * Rollback (destroy) a set of plugins
+     * Used when startup fails and rollback is enabled
+     * @param startedPlugins - Plugins that were successfully started
+     * @returns Promise that resolves when rollback is complete
+     */
+    rollback(startedPlugins: Plugin[]): Promise<void>;
+    /**
+     * Check health of a single plugin
+     * @param plugin - Plugin to check
+     * @returns Promise resolving to health status
+     */
+    checkHealth(plugin: Plugin): Promise<HealthStatus>;
+    /**
+     * Wait for a plugin to start with timeout
+     * @param plugin - Plugin to start
+     * @param context - Plugin context
+     * @param timeoutMs - Maximum time to wait (milliseconds)
+     * @returns Promise resolving when plugin starts or rejecting on timeout
+     */
+    startWithTimeout?(plugin: Plugin, context: any, timeoutMs: number): Promise<void>;
+}
+
+/**
+ * IPluginLifecycleEvents - Typed Plugin Lifecycle Events
+ *
+ * Type-safe event definitions for plugin and kernel lifecycle.
+ * Provides strong typing for event emitters and listeners.
+ *
+ * This replaces the generic Map<string, any[]> approach with typed events.
+ */
+/**
+ * Plugin lifecycle event types and their payloads
+ */
+interface IPluginLifecycleEvents {
+    /**
+     * Emitted when kernel is ready (all plugins initialized)
+     * Payload: []
+     */
+    'kernel:ready': [];
+    /**
+     * Emitted when kernel is shutting down
+     * Payload: []
+     */
+    'kernel:shutdown': [];
+    /**
+     * Emitted before kernel initialization starts
+     * Payload: []
+     */
+    'kernel:before-init': [];
+    /**
+     * Emitted after kernel initialization completes
+     * Payload: [duration: number (milliseconds)]
+     */
+    'kernel:after-init': [duration: number];
+    /**
+     * Emitted when a plugin is registered
+     * Payload: [pluginName: string]
+     */
+    'plugin:registered': [pluginName: string];
+    /**
+     * Emitted before a plugin's init method is called
+     * Payload: [pluginName: string]
+     */
+    'plugin:before-init': [pluginName: string];
+    /**
+     * Emitted when a plugin has been initialized
+     * Payload: [pluginName: string]
+     */
+    'plugin:init': [pluginName: string];
+    /**
+     * Emitted after a plugin's init method completes
+     * Payload: [pluginName: string, duration: number (milliseconds)]
+     */
+    'plugin:after-init': [pluginName: string, duration: number];
+    /**
+     * Emitted before a plugin's start method is called
+     * Payload: [pluginName: string]
+     */
+    'plugin:before-start': [pluginName: string];
+    /**
+     * Emitted when a plugin has started successfully
+     * Payload: [pluginName: string, duration: number (milliseconds)]
+     */
+    'plugin:started': [pluginName: string, duration: number];
+    /**
+     * Emitted after a plugin's start method completes
+     * Payload: [pluginName: string, duration: number (milliseconds)]
+     */
+    'plugin:after-start': [pluginName: string, duration: number];
+    /**
+     * Emitted before a plugin's destroy method is called
+     * Payload: [pluginName: string]
+     */
+    'plugin:before-destroy': [pluginName: string];
+    /**
+     * Emitted when a plugin has been destroyed
+     * Payload: [pluginName: string]
+     */
+    'plugin:destroyed': [pluginName: string];
+    /**
+     * Emitted after a plugin's destroy method completes
+     * Payload: [pluginName: string, duration: number (milliseconds)]
+     */
+    'plugin:after-destroy': [pluginName: string, duration: number];
+    /**
+     * Emitted when a plugin encounters an error
+     * Payload: [pluginName: string, error: Error, phase: 'init' | 'start' | 'destroy']
+     */
+    'plugin:error': [pluginName: string, error: Error, phase: 'init' | 'start' | 'destroy'];
+    /**
+     * Emitted when a service is registered
+     * Payload: [serviceName: string]
+     */
+    'service:registered': [serviceName: string];
+    /**
+     * Emitted when a service is unregistered
+     * Payload: [serviceName: string]
+     */
+    'service:unregistered': [serviceName: string];
+    /**
+     * Emitted when a hook is registered
+     * Payload: [hookName: string, handlerCount: number]
+     */
+    'hook:registered': [hookName: string, handlerCount: number];
+    /**
+     * Emitted when a hook is triggered
+     * Payload: [hookName: string, args: any[]]
+     */
+    'hook:triggered': [hookName: string, args: any[]];
+}
+/**
+ * Type-safe event emitter interface
+ * Provides compile-time type checking for event names and payloads
+ */
+interface ITypedEventEmitter<Events extends Record<string, any[]>> {
+    /**
+     * Register an event listener
+     * @param event - Event name (type-checked)
+     * @param handler - Event handler (type-checked against event payload)
+     */
+    on<K extends keyof Events>(event: K, handler: (...args: Events[K]) => void | Promise<void>): void;
+    /**
+     * Unregister an event listener
+     * @param event - Event name (type-checked)
+     * @param handler - Event handler to remove
+     */
+    off<K extends keyof Events>(event: K, handler: (...args: Events[K]) => void | Promise<void>): void;
+    /**
+     * Emit an event with type-checked payload
+     * @param event - Event name (type-checked)
+     * @param args - Event payload (type-checked)
+     */
+    emit<K extends keyof Events>(event: K, ...args: Events[K]): Promise<void>;
+    /**
+     * Register a one-time event listener
+     * @param event - Event name (type-checked)
+     * @param handler - Event handler (type-checked against event payload)
+     */
+    once?<K extends keyof Events>(event: K, handler: (...args: Events[K]) => void | Promise<void>): void;
+    /**
+     * Get the number of listeners for an event
+     * @param event - Event name
+     * @returns Number of registered listeners
+     */
+    listenerCount?<K extends keyof Events>(event: K): number;
+    /**
+     * Remove all listeners for an event (or all events if not specified)
+     * @param event - Optional event name
+     */
+    removeAllListeners?<K extends keyof Events>(event?: K): void;
+}
+
+type DataField = z.infer<typeof FieldSchema>;
+type DataObject = z.infer<typeof ObjectSchema>;
+/**
+ * Interface for Data Definition Language (DDL) operations.
+ * Drivers should implement this to support automatic migrations.
+ */
+interface ISchemaDriver {
+    createCollection(objectName: string, schema?: DataObject): Promise<void>;
+    dropCollection(objectName: string): Promise<void>;
+    addColumn(objectName: string, fieldName: string, field: DataField): Promise<void>;
+    modifyColumn(objectName: string, fieldName: string, field: DataField): Promise<void>;
+    dropColumn(objectName: string, fieldName: string): Promise<void>;
+    createIndex(objectName: string, indexName: string, fields: string[]): Promise<void>;
+    dropIndex(objectName: string, indexName: string): Promise<void>;
+    executeRaw(statement: string): Promise<any>;
+}
+
+/**
+ * ICacheService - Cache Service Contract
+ *
+ * Defines the interface for cache operations in ObjectStack.
+ * Concrete implementations (Redis, Memory, etc.) should implement this interface.
+ *
+ * Follows Dependency Inversion Principle - plugins depend on this interface,
+ * not on concrete cache implementations.
+ *
+ * Aligned with CoreServiceName 'cache' in core-services.zod.ts.
+ */
+/**
+ * Cache statistics for monitoring and observability
+ */
+interface CacheStats {
+    /** Total number of cache hits */
+    hits: number;
+    /** Total number of cache misses */
+    misses: number;
+    /** Number of keys currently stored */
+    keyCount: number;
+    /** Memory usage in bytes (if available) */
+    memoryUsage?: number;
+}
+interface ICacheService {
+    /**
+     * Get a cached value by key
+     * @param key - Cache key
+     * @returns The cached value, or undefined if not found
+     */
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    /**
+     * Set a value in the cache
+     * @param key - Cache key
+     * @param value - Value to cache
+     * @param ttl - Optional time-to-live in seconds
+     */
+    set<T = unknown>(key: string, value: T, ttl?: number): Promise<void>;
+    /**
+     * Delete a cached value by key
+     * @param key - Cache key
+     * @returns True if the key was deleted, false if it did not exist
+     */
+    delete(key: string): Promise<boolean>;
+    /**
+     * Check if a key exists in the cache
+     * @param key - Cache key
+     * @returns True if the key exists
+     */
+    has(key: string): Promise<boolean>;
+    /**
+     * Clear all entries from the cache
+     */
+    clear(): Promise<void>;
+    /**
+     * Get cache statistics
+     * @returns Cache stats including hits, misses, and key count
+     */
+    stats(): Promise<CacheStats>;
+}
+
+/**
+ * ISearchService - Search Service Contract
+ *
+ * Defines the interface for full-text search capabilities in ObjectStack.
+ * Concrete implementations (Elasticsearch, MeiliSearch, Typesense, etc.)
+ * should implement this interface.
+ *
+ * Follows Dependency Inversion Principle - plugins depend on this interface,
+ * not on concrete search engine implementations.
+ *
+ * Aligned with CoreServiceName 'search' in core-services.zod.ts.
+ */
+/**
+ * Options for search queries
+ */
+interface SearchOptions {
+    /** Filter conditions to narrow results */
+    filter?: Record<string, unknown>;
+    /** Maximum number of results to return */
+    limit?: number;
+    /** Offset for pagination */
+    offset?: number;
+    /** Fields to sort by */
+    sort?: string[];
+    /** Fields to include in results */
+    select?: string[];
+    /** Facet fields to aggregate */
+    facets?: string[];
+    /** Enable highlighting of matching terms */
+    highlight?: boolean;
+}
+/**
+ * A single search result hit
+ */
+interface SearchHit {
+    /** Document ID */
+    id: string;
+    /** Relevance score */
+    score: number;
+    /** The matched document */
+    document: Record<string, unknown>;
+    /** Highlighted fields (if requested) */
+    highlights?: Record<string, string[]>;
+}
+/**
+ * Search result set
+ */
+interface SearchResult {
+    /** Matched documents */
+    hits: SearchHit[];
+    /** Total number of matching documents */
+    totalHits: number;
+    /** Query processing time in milliseconds */
+    processingTimeMs?: number;
+    /** Facet counts (if requested) */
+    facets?: Record<string, Record<string, number>>;
+}
+interface ISearchService {
+    /**
+     * Index a document for search
+     * @param object - Object/collection name
+     * @param id - Document identifier
+     * @param document - Document data to index
+     */
+    index(object: string, id: string, document: Record<string, unknown>): Promise<void>;
+    /**
+     * Remove a document from the search index
+     * @param object - Object/collection name
+     * @param id - Document identifier
+     */
+    remove(object: string, id: string): Promise<void>;
+    /**
+     * Search for documents
+     * @param object - Object/collection name
+     * @param query - Search query string
+     * @param options - Search options (filters, pagination, etc.)
+     * @returns Search results with hits, total count, and optional facets
+     */
+    search(object: string, query: string, options?: SearchOptions): Promise<SearchResult>;
+    /**
+     * Bulk index multiple documents at once
+     * @param object - Object/collection name
+     * @param documents - Array of documents with id and data
+     */
+    bulkIndex?(object: string, documents: Array<{
+        id: string;
+        document: Record<string, unknown>;
+    }>): Promise<void>;
+    /**
+     * Delete all documents in an index
+     * @param object - Object/collection name
+     */
+    deleteIndex?(object: string): Promise<void>;
+}
+
+/**
+ * IQueueService - Message Queue Service Contract
+ *
+ * Defines the interface for asynchronous message queue operations in ObjectStack.
+ * Concrete implementations (BullMQ, Redis Pub/Sub, Kafka, etc.)
+ * should implement this interface.
+ *
+ * Follows Dependency Inversion Principle - plugins depend on this interface,
+ * not on concrete queue implementations.
+ *
+ * Aligned with CoreServiceName 'queue' in core-services.zod.ts.
+ */
+/**
+ * Options for publishing a message to a queue
+ */
+interface QueuePublishOptions {
+    /** Delay before the message becomes available (in milliseconds) */
+    delay?: number;
+    /** Message priority (lower = higher priority) */
+    priority?: number;
+    /** Number of retry attempts on failure */
+    retries?: number;
+}
+/**
+ * A message received from a queue
+ */
+interface QueueMessage<T = unknown> {
+    /** Unique message identifier */
+    id: string;
+    /** The message payload */
+    data: T;
+    /** Number of times this message has been attempted */
+    attempts: number;
+    /** Timestamp when the message was published */
+    timestamp: number;
+}
+/**
+ * Handler function for processing queue messages
+ */
+type QueueHandler<T = unknown> = (message: QueueMessage<T>) => Promise<void>;
+interface IQueueService {
+    /**
+     * Publish a message to a named queue
+     * @param queue - Queue name
+     * @param data - Message payload
+     * @param options - Publish options (delay, priority, retries)
+     * @returns The message identifier
+     */
+    publish<T = unknown>(queue: string, data: T, options?: QueuePublishOptions): Promise<string>;
+    /**
+     * Subscribe to messages from a named queue
+     * @param queue - Queue name
+     * @param handler - Message handler function
+     */
+    subscribe<T = unknown>(queue: string, handler: QueueHandler<T>): Promise<void>;
+    /**
+     * Unsubscribe from a named queue
+     * @param queue - Queue name
+     */
+    unsubscribe(queue: string): Promise<void>;
+    /**
+     * Get the number of messages waiting in a queue
+     * @param queue - Queue name
+     * @returns Number of pending messages
+     */
+    getQueueSize?(queue: string): Promise<number>;
+    /**
+     * Purge all messages from a queue
+     * @param queue - Queue name
+     */
+    purge?(queue: string): Promise<void>;
+}
+
+/**
+ * INotificationService - Notification Service Contract
+ *
+ * Defines the interface for sending notifications in ObjectStack.
+ * Concrete implementations (Email, Push, SMS, Slack, etc.)
+ * should implement this interface.
+ *
+ * Follows Dependency Inversion Principle - plugins depend on this interface,
+ * not on concrete notification provider implementations.
+ *
+ * Aligned with CoreServiceName 'notification' in core-services.zod.ts.
+ */
+/**
+ * Supported notification delivery channels
+ */
+type NotificationChannel = 'email' | 'sms' | 'push' | 'in-app' | 'slack' | 'teams' | 'webhook';
+/**
+ * A notification message to be sent
+ */
+interface NotificationMessage {
+    /** Notification channel to use */
+    channel: NotificationChannel;
+    /** Recipient identifier (email, phone, user ID, etc.) */
+    to: string | string[];
+    /** Notification subject/title */
+    subject?: string;
+    /** Notification body content */
+    body: string;
+    /** Template identifier (if using a pre-defined template) */
+    templateId?: string;
+    /** Template variable values */
+    templateData?: Record<string, unknown>;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Result of sending a notification
+ */
+interface NotificationResult {
+    /** Whether the notification was sent successfully */
+    success: boolean;
+    /** Unique identifier for tracking */
+    messageId?: string;
+    /** Error message if sending failed */
+    error?: string;
+}
+interface INotificationService {
+    /**
+     * Send a notification
+     * @param message - The notification message to send
+     * @returns Result indicating success or failure
+     */
+    send(message: NotificationMessage): Promise<NotificationResult>;
+    /**
+     * Send multiple notifications in a batch
+     * @param messages - Array of notification messages
+     * @returns Array of results for each message
+     */
+    sendBatch?(messages: NotificationMessage[]): Promise<NotificationResult[]>;
+    /**
+     * List available notification channels
+     * @returns Array of supported channel names
+     */
+    getChannels?(): NotificationChannel[];
+}
+
+/**
+ * IStorageService - File Storage Service Contract
+ *
+ * Defines the interface for file/object storage in ObjectStack.
+ * Concrete implementations (S3, Azure Blob, Local FS, etc.)
+ * should implement this interface.
+ *
+ * Follows Dependency Inversion Principle - plugins depend on this interface,
+ * not on concrete storage implementations.
+ *
+ * Aligned with CoreServiceName 'file-storage' in core-services.zod.ts.
+ */
+/**
+ * Options for uploading a file
+ */
+interface StorageUploadOptions {
+    /** MIME content type */
+    contentType?: string;
+    /** Custom metadata key-value pairs */
+    metadata?: Record<string, string>;
+    /** Access control level */
+    acl?: 'private' | 'public-read';
+}
+/**
+ * Metadata about a stored file
+ */
+interface StorageFileInfo {
+    /** File key/path */
+    key: string;
+    /** File size in bytes */
+    size: number;
+    /** MIME content type */
+    contentType?: string;
+    /** Last modified timestamp */
+    lastModified: Date;
+    /** Custom metadata */
+    metadata?: Record<string, string>;
+}
+interface IStorageService {
+    /**
+     * Upload a file to storage
+     * @param key - Storage key/path for the file
+     * @param data - File content as Buffer or readable stream
+     * @param options - Upload options (content type, metadata, ACL)
+     */
+    upload(key: string, data: Buffer | ReadableStream, options?: StorageUploadOptions): Promise<void>;
+    /**
+     * Download a file from storage
+     * @param key - Storage key/path
+     * @returns File content as Buffer
+     */
+    download(key: string): Promise<Buffer>;
+    /**
+     * Delete a file from storage
+     * @param key - Storage key/path
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Check if a file exists in storage
+     * @param key - Storage key/path
+     * @returns True if the file exists
+     */
+    exists(key: string): Promise<boolean>;
+    /**
+     * Get metadata about a stored file
+     * @param key - Storage key/path
+     * @returns File info including size, content type, and last modified date
+     */
+    getInfo(key: string): Promise<StorageFileInfo>;
+    /**
+     * List files in a directory/prefix
+     * @param prefix - Key prefix to list
+     * @returns Array of file info objects
+     */
+    list?(prefix: string): Promise<StorageFileInfo[]>;
+    /**
+     * Generate a pre-signed URL for temporary access
+     * @param key - Storage key/path
+     * @param expiresIn - URL expiration time in seconds
+     * @returns Pre-signed URL string
+     */
+    getSignedUrl?(key: string, expiresIn: number): Promise<string>;
+}
+
+/**
+ * IMetadataService - Metadata Service Contract
+ *
+ * Defines the async interface for managing object/field definitions in ObjectStack.
+ * Concrete implementations (SchemaRegistry, Database-backed, etc.)
+ * should implement this interface.
+ *
+ * All methods are async to support database-backed persistence via datasource.
+ *
+ * Follows Dependency Inversion Principle - plugins depend on this interface,
+ * not on concrete metadata storage implementations.
+ *
+ * Aligned with CoreServiceName 'metadata' in core-services.zod.ts.
+ */
+interface IMetadataService {
+    /**
+     * Register/save a metadata item by type
+     * @param type - Metadata type (e.g. 'object', 'view', 'flow')
+     * @param name - Item name/identifier (snake_case)
+     * @param data - The metadata definition to register
+     */
+    register(type: string, name: string, data: unknown): Promise<void>;
+    /**
+     * Get a metadata item by type and name
+     * @param type - Metadata type
+     * @param name - Item name/identifier
+     * @returns The metadata definition, or undefined if not found
+     */
+    get(type: string, name: string): Promise<unknown | undefined>;
+    /**
+     * List all metadata items of a given type
+     * @param type - Metadata type
+     * @returns Array of metadata definitions
+     */
+    list(type: string): Promise<unknown[]>;
+    /**
+     * Unregister/remove a metadata item by type and name
+     * @param type - Metadata type
+     * @param name - Item name/identifier
+     */
+    unregister(type: string, name: string): Promise<void>;
+    /**
+     * Check if a metadata item exists
+     * @param type - Metadata type
+     * @param name - Item name/identifier
+     * @returns True if the item exists
+     */
+    exists(type: string, name: string): Promise<boolean>;
+    /**
+     * List all names of metadata items of a given type
+     * @param type - Metadata type
+     * @returns Array of item names
+     */
+    listNames(type: string): Promise<string[]>;
+    /**
+     * Convenience: get an object definition by name
+     * @param name - Object name (snake_case)
+     * @returns The object definition, or undefined if not found
+     */
+    getObject(name: string): Promise<unknown | undefined>;
+    /**
+     * Convenience: list all object definitions
+     * @returns Array of object definitions
+     */
+    listObjects(): Promise<unknown[]>;
+    /**
+     * Unregister all metadata items from a specific package
+     * @param packageName - The package name whose items should be removed
+     */
+    unregisterPackage?(packageName: string): Promise<void>;
+}
+
+/**
+ * IAuthService - Authentication Service Contract
+ *
+ * Defines the interface for authentication and session management in ObjectStack.
+ * Concrete implementations (better-auth, custom, LDAP, etc.)
+ * should implement this interface.
+ *
+ * Follows Dependency Inversion Principle - plugins depend on this interface,
+ * not on concrete auth provider implementations.
+ *
+ * Aligned with CoreServiceName 'auth' in core-services.zod.ts.
+ */
+/**
+ * Authenticated session user information
+ */
+interface AuthUser {
+    /** User identifier */
+    id: string;
+    /** Email address */
+    email: string;
+    /** Display name */
+    name: string;
+    /** Assigned role identifiers */
+    roles?: string[];
+    /** Current tenant identifier (multi-tenant) */
+    tenantId?: string;
+}
+/**
+ * Active session information
+ */
+interface AuthSession {
+    /** Session identifier */
+    id: string;
+    /** Associated user identifier */
+    userId: string;
+    /** Session expiry (ISO 8601) */
+    expiresAt: string;
+    /** Bearer token (if not using cookies) */
+    token?: string;
+}
+/**
+ * Authentication result returned by login/verify operations
+ */
+interface AuthResult {
+    /** Whether authentication succeeded */
+    success: boolean;
+    /** Authenticated user (if success) */
+    user?: AuthUser;
+    /** Active session (if success) */
+    session?: AuthSession;
+    /** Error message (if failure) */
+    error?: string;
+}
+interface IAuthService {
+    /**
+     * Handle an incoming HTTP authentication request
+     * @param request - Standard Request object
+     * @returns Standard Response object
+     */
+    handleRequest(request: Request): Promise<Response>;
+    /**
+     * Verify a session token or cookie and return the user
+     * @param token - Bearer token or session identifier
+     * @returns Auth result with user and session if valid
+     */
+    verify(token: string): Promise<AuthResult>;
+    /**
+     * Invalidate a session (logout)
+     * @param sessionId - Session identifier to invalidate
+     */
+    logout?(sessionId: string): Promise<void>;
+    /**
+     * Get the current user from a request
+     * @param request - Standard Request object
+     * @returns Authenticated user or undefined
+     */
+    getCurrentUser?(request: Request): Promise<AuthUser | undefined>;
+}
+
+/**
+ * IAutomationService - Automation Service Contract
+ *
+ * Defines the interface for flow/script execution in ObjectStack.
+ * Concrete implementations (Flow Engine, Script Runner, etc.)
+ * should implement this interface.
+ *
+ * Follows Dependency Inversion Principle - plugins depend on this interface,
+ * not on concrete automation engine implementations.
+ *
+ * Aligned with CoreServiceName 'automation' in core-services.zod.ts.
+ */
+/**
+ * Context passed to a flow/script execution
+ */
+interface AutomationContext {
+    /** Record that triggered the automation (if applicable) */
+    record?: Record<string, unknown>;
+    /** Object name the record belongs to */
+    object?: string;
+    /** Trigger event type (e.g. 'on_create', 'on_update') */
+    event?: string;
+    /** User who triggered the automation */
+    userId?: string;
+    /** Additional contextual data */
+    params?: Record<string, unknown>;
+}
+/**
+ * Result of an automation execution
+ */
+interface AutomationResult {
+    /** Whether the automation completed successfully */
+    success: boolean;
+    /** Output data from the automation */
+    output?: unknown;
+    /** Error message if execution failed */
+    error?: string;
+    /** Execution duration in milliseconds */
+    durationMs?: number;
+}
+interface IAutomationService {
+    /**
+     * Execute a named flow or script
+     * @param flowName - Flow/script identifier (snake_case)
+     * @param context - Execution context with trigger data
+     * @returns Automation result
+     */
+    execute(flowName: string, context?: AutomationContext): Promise<AutomationResult>;
+    /**
+     * List all registered automation flows
+     * @returns Array of flow names
+     */
+    listFlows(): Promise<string[]>;
+    /**
+     * Register a flow definition
+     * @param name - Flow name (snake_case)
+     * @param definition - Flow definition object
+     */
+    registerFlow?(name: string, definition: unknown): void;
+    /**
+     * Unregister a flow by name
+     * @param name - Flow name (snake_case)
+     */
+    unregisterFlow?(name: string): void;
+}
+
+/**
+ * IGraphQLService - GraphQL Service Contract
+ *
+ * Defines the interface for GraphQL schema and query execution in ObjectStack.
+ * Concrete implementations (Apollo, Yoga, Mercurius, etc.)
+ * should implement this interface.
+ *
+ * Follows Dependency Inversion Principle - plugins depend on this interface,
+ * not on concrete GraphQL server implementations.
+ *
+ * Aligned with CoreServiceName 'graphql' in core-services.zod.ts.
+ */
+/**
+ * A GraphQL execution request
+ */
+interface GraphQLRequest {
+    /** GraphQL query or mutation string */
+    query: string;
+    /** Operation name (when document contains multiple operations) */
+    operationName?: string;
+    /** Variables for the operation */
+    variables?: Record<string, unknown>;
+}
+/**
+ * A GraphQL execution response
+ */
+interface GraphQLResponse {
+    /** Query result data */
+    data?: Record<string, unknown> | null;
+    /** Errors encountered during execution */
+    errors?: Array<{
+        message: string;
+        locations?: Array<{
+            line: number;
+            column: number;
+        }>;
+        path?: Array<string | number>;
+        extensions?: Record<string, unknown>;
+    }>;
+}
+interface IGraphQLService {
+    /**
+     * Execute a GraphQL query or mutation
+     * @param request - The GraphQL request
+     * @param context - Optional execution context (e.g. auth user)
+     * @returns GraphQL response with data and/or errors
+     */
+    execute(request: GraphQLRequest, context?: Record<string, unknown>): Promise<GraphQLResponse>;
+    /**
+     * Handle an incoming HTTP request for GraphQL
+     * @param request - Standard Request object
+     * @returns Standard Response object
+     */
+    handleRequest?(request: Request): Promise<Response>;
+    /**
+     * Get the current GraphQL schema as SDL string
+     * @returns SDL schema string
+     */
+    getSchema?(): string;
+}
+
+/**
+ * IAnalyticsService - Analytics / BI Service Contract
+ *
+ * Defines the interface for analytical query execution and semantic layer
+ * metadata discovery in ObjectStack. Concrete implementations (Cube.js, custom, etc.)
+ * should implement this interface.
+ *
+ * Follows Dependency Inversion Principle - plugins depend on this interface,
+ * not on concrete analytics engine implementations.
+ *
+ * Aligned with CoreServiceName 'analytics' in core-services.zod.ts.
+ */
+/**
+ * An analytical query definition
+ */
+interface AnalyticsQuery {
+    /** Target cube name */
+    cube: string;
+    /** Measures to compute (e.g. ['orders.count', 'orders.totalRevenue']) */
+    measures?: string[];
+    /** Dimensions to group by (e.g. ['orders.status', 'orders.createdAt']) */
+    dimensions?: string[];
+    /** Filter conditions */
+    filters?: Array<{
+        member: string;
+        operator: string;
+        values?: string[];
+    }>;
+    /** Time dimension configuration */
+    timeDimensions?: Array<{
+        dimension: string;
+        granularity?: string;
+        dateRange?: string | string[];
+    }>;
+    /** Result limit */
+    limit?: number;
+    /** Result offset */
+    offset?: number;
+}
+/**
+ * Analytics query result
+ */
+interface AnalyticsResult {
+    /** Result rows */
+    rows: Record<string, unknown>[];
+    /** Column metadata */
+    fields: Array<{
+        name: string;
+        type: string;
+    }>;
+    /** Generated SQL (if available) */
+    sql?: string;
+}
+/**
+ * Cube metadata for discovery
+ */
+interface CubeMeta {
+    /** Cube name */
+    name: string;
+    /** Human-readable title */
+    title?: string;
+    /** Available measures */
+    measures: Array<{
+        name: string;
+        type: string;
+        title?: string;
+    }>;
+    /** Available dimensions */
+    dimensions: Array<{
+        name: string;
+        type: string;
+        title?: string;
+    }>;
+}
+interface IAnalyticsService {
+    /**
+     * Execute an analytical query
+     * @param query - The analytics query definition
+     * @returns Query results with rows and field metadata
+     */
+    query(query: AnalyticsQuery): Promise<AnalyticsResult>;
+    /**
+     * Get available cube metadata for discovery
+     * @param cubeName - Optional cube name to filter (returns all if omitted)
+     * @returns Array of cube metadata definitions
+     */
+    getMeta(cubeName?: string): Promise<CubeMeta[]>;
+    /**
+     * Generate SQL for a query without executing it (dry-run)
+     * @param query - The analytics query definition
+     * @returns Generated SQL string and parameters
+     */
+    generateSql?(query: AnalyticsQuery): Promise<{
+        sql: string;
+        params: unknown[];
+    }>;
+}
+
+/**
+ * IRealtimeService - Realtime / PubSub Service Contract
+ *
+ * Defines the interface for realtime event subscription and publishing
+ * in ObjectStack. Concrete implementations (WebSocket, SSE, Socket.IO, etc.)
+ * should implement this interface.
+ *
+ * Follows Dependency Inversion Principle - plugins depend on this interface,
+ * not on concrete realtime transport implementations.
+ *
+ * Aligned with CoreServiceName 'realtime' in core-services.zod.ts.
+ */
+/**
+ * A realtime event payload
+ */
+interface RealtimeEventPayload {
+    /** Event type (e.g. 'record.created', 'record.updated') */
+    type: string;
+    /** Object name the event relates to */
+    object?: string;
+    /** Event data */
+    payload: Record<string, unknown>;
+    /** Timestamp (ISO 8601) */
+    timestamp: string;
+}
+/**
+ * Handler function for realtime event subscriptions
+ */
+type RealtimeEventHandler = (event: RealtimeEventPayload) => void | Promise<void>;
+/**
+ * Subscription options for filtering events
+ */
+interface RealtimeSubscriptionOptions {
+    /** Object name to filter events for */
+    object?: string;
+    /** Event types to listen for */
+    eventTypes?: string[];
+    /** Additional filter conditions */
+    filter?: Record<string, unknown>;
+}
+interface IRealtimeService {
+    /**
+     * Publish an event to all subscribers
+     * @param event - The event to publish
+     */
+    publish(event: RealtimeEventPayload): Promise<void>;
+    /**
+     * Subscribe to realtime events
+     * @param channel - Channel/topic name
+     * @param handler - Event handler function
+     * @param options - Optional subscription filters
+     * @returns Subscription identifier for unsubscribing
+     */
+    subscribe(channel: string, handler: RealtimeEventHandler, options?: RealtimeSubscriptionOptions): Promise<string>;
+    /**
+     * Unsubscribe from a channel
+     * @param subscriptionId - Subscription identifier returned by subscribe()
+     */
+    unsubscribe(subscriptionId: string): Promise<void>;
+    /**
+     * Handle an incoming HTTP upgrade request (WebSocket handshake)
+     * @param request - Standard Request object
+     * @returns Standard Response object
+     */
+    handleUpgrade?(request: Request): Promise<Response>;
+}
+
+/**
+ * IJobService - Background Job Service Contract
+ *
+ * Defines the interface for scheduling and managing background jobs
+ * in ObjectStack. Concrete implementations (BullMQ, node-cron, etc.)
+ * should implement this interface.
+ *
+ * Follows Dependency Inversion Principle - plugins depend on this interface,
+ * not on concrete job scheduler implementations.
+ *
+ * Aligned with CoreServiceName 'job' in core-services.zod.ts.
+ */
+/**
+ * Schedule definition for a job
+ */
+interface JobSchedule {
+    /** Schedule type */
+    type: 'cron' | 'interval' | 'once';
+    /** Cron expression (when type is 'cron') */
+    expression?: string;
+    /** Timezone for cron (when type is 'cron') */
+    timezone?: string;
+    /** Interval in milliseconds (when type is 'interval') */
+    intervalMs?: number;
+    /** ISO 8601 datetime (when type is 'once') */
+    at?: string;
+}
+/**
+ * Job handler function
+ */
+type JobHandler = (context: {
+    jobId: string;
+    data?: unknown;
+}) => Promise<void>;
+/**
+ * Status of a job execution
+ */
+interface JobExecution {
+    /** Job identifier */
+    jobId: string;
+    /** Execution status */
+    status: 'running' | 'success' | 'failed' | 'timeout';
+    /** Start time (ISO 8601) */
+    startedAt: string;
+    /** Completion time (ISO 8601) */
+    completedAt?: string;
+    /** Error message if failed */
+    error?: string;
+    /** Duration in milliseconds */
+    durationMs?: number;
+}
+interface IJobService {
+    /**
+     * Schedule a recurring or one-time job
+     * @param name - Job name (snake_case)
+     * @param schedule - Schedule configuration
+     * @param handler - Job handler function
+     */
+    schedule(name: string, schedule: JobSchedule, handler: JobHandler): Promise<void>;
+    /**
+     * Cancel a scheduled job
+     * @param name - Job name
+     */
+    cancel(name: string): Promise<void>;
+    /**
+     * Trigger a job to run immediately (outside its normal schedule)
+     * @param name - Job name
+     * @param data - Optional data to pass to the handler
+     */
+    trigger(name: string, data?: unknown): Promise<void>;
+    /**
+     * Get the status of recent job executions
+     * @param name - Job name
+     * @param limit - Maximum number of executions to return
+     * @returns Array of job execution records
+     */
+    getExecutions?(name: string, limit?: number): Promise<JobExecution[]>;
+    /**
+     * List all registered job names
+     * @returns Array of job names
+     */
+    listJobs?(): Promise<string[]>;
+}
+
+/**
+ * IAIService - AI Engine Service Contract
+ *
+ * Defines the interface for AI capabilities (NLQ, chat, suggestions, embeddings)
+ * in ObjectStack. Concrete implementations (OpenAI, Anthropic, Ollama, etc.)
+ * should implement this interface.
+ *
+ * Follows Dependency Inversion Principle - plugins depend on this interface,
+ * not on concrete AI/LLM provider implementations.
+ *
+ * Aligned with CoreServiceName 'ai' in core-services.zod.ts.
+ */
+/**
+ * A chat message in a conversation
+ */
+interface AIMessage {
+    /** Message role */
+    role: 'system' | 'user' | 'assistant';
+    /** Message content */
+    content: string;
+}
+/**
+ * Options for AI completion/chat requests
+ */
+interface AIRequestOptions {
+    /** Model identifier to use */
+    model?: string;
+    /** Sampling temperature (0-2) */
+    temperature?: number;
+    /** Maximum tokens to generate */
+    maxTokens?: number;
+    /** Stop sequences */
+    stop?: string[];
+}
+/**
+ * Result of an AI completion/chat request
+ */
+interface AIResult {
+    /** Generated text content */
+    content: string;
+    /** Model used for generation */
+    model?: string;
+    /** Token usage statistics */
+    usage?: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+}
+interface IAIService {
+    /**
+     * Generate a chat completion from a conversation
+     * @param messages - Array of conversation messages
+     * @param options - Optional request configuration
+     * @returns AI-generated response
+     */
+    chat(messages: AIMessage[], options?: AIRequestOptions): Promise<AIResult>;
+    /**
+     * Generate a text completion from a prompt
+     * @param prompt - Input prompt string
+     * @param options - Optional request configuration
+     * @returns AI-generated response
+     */
+    complete(prompt: string, options?: AIRequestOptions): Promise<AIResult>;
+    /**
+     * Generate embeddings for a text input
+     * @param input - Text or array of texts to embed
+     * @param model - Optional embedding model identifier
+     * @returns Array of embedding vectors
+     */
+    embed?(input: string | string[], model?: string): Promise<number[][]>;
+    /**
+     * List available models
+     * @returns Array of model identifiers
+     */
+    listModels?(): Promise<string[]>;
+}
+
+/**
+ * II18nService - Internationalization Service Contract
+ *
+ * Defines the interface for translation and locale management in ObjectStack.
+ * Concrete implementations (i18next, custom, etc.)
+ * should implement this interface.
+ *
+ * Follows Dependency Inversion Principle - plugins depend on this interface,
+ * not on concrete i18n library implementations.
+ *
+ * Aligned with CoreServiceName 'i18n' in core-services.zod.ts.
+ */
+interface II18nService {
+    /**
+     * Translate a message key for a given locale
+     * @param key - Translation key (e.g. 'objects.account.label')
+     * @param locale - BCP-47 locale code (e.g. 'en-US', 'zh-CN')
+     * @param params - Optional interpolation parameters
+     * @returns Translated string, or the key itself if not found
+     */
+    t(key: string, locale: string, params?: Record<string, unknown>): string;
+    /**
+     * Get all translations for a locale
+     * @param locale - BCP-47 locale code
+     * @returns Translation data map
+     */
+    getTranslations(locale: string): Record<string, unknown>;
+    /**
+     * Load translations for a locale
+     * @param locale - BCP-47 locale code
+     * @param translations - Translation key-value data
+     */
+    loadTranslations(locale: string, translations: Record<string, unknown>): void;
+    /**
+     * List available locales
+     * @returns Array of BCP-47 locale codes
+     */
+    getLocales(): string[];
+    /**
+     * Get the current default locale
+     * @returns BCP-47 locale code
+     */
+    getDefaultLocale?(): string;
+    /**
+     * Set the default locale
+     * @param locale - BCP-47 locale code
+     */
+    setDefaultLocale?(locale: string): void;
+}
+
+/**
+ * IUIService - UI Metadata Service Contract
+ *
+ * Defines the interface for managing UI metadata (views, dashboards, layouts)
+ * in ObjectStack. Concrete implementations (database-backed, in-memory, etc.)
+ * should implement this interface.
+ *
+ * Follows Dependency Inversion Principle - plugins depend on this interface,
+ * not on concrete UI metadata storage implementations.
+ *
+ * Aligned with CoreServiceName 'ui' in core-services.zod.ts.
+ */
+interface IUIService {
+    /**
+     * Get a view definition by name
+     * @param name - View name (snake_case)
+     * @returns View definition, or undefined if not found
+     */
+    getView(name: string): unknown | undefined;
+    /**
+     * List view definitions, optionally filtered by object
+     * @param object - Optional object name to filter views for
+     * @returns Array of view definitions
+     */
+    listViews(object?: string): unknown[];
+    /**
+     * Get a dashboard definition by name
+     * @param name - Dashboard name (snake_case)
+     * @returns Dashboard definition, or undefined if not found
+     */
+    getDashboard?(name: string): unknown | undefined;
+    /**
+     * List all dashboard definitions
+     * @returns Array of dashboard definitions
+     */
+    listDashboards?(): unknown[];
+    /**
+     * Register a view definition
+     * @param name - View name (snake_case)
+     * @param definition - View definition object
+     */
+    registerView?(name: string, definition: unknown): void;
+    /**
+     * Register a dashboard definition
+     * @param name - Dashboard name (snake_case)
+     * @param definition - Dashboard definition object
+     */
+    registerDashboard?(name: string, definition: unknown): void;
+}
+
+/**
+ * IWorkflowService - Workflow State Machine Service Contract
+ *
+ * Defines the interface for workflow state management and approval processes
+ * in ObjectStack. Concrete implementations (state machine engines, BPMN, etc.)
+ * should implement this interface.
+ *
+ * Follows Dependency Inversion Principle - plugins depend on this interface,
+ * not on concrete workflow engine implementations.
+ *
+ * Aligned with CoreServiceName 'workflow' in core-services.zod.ts.
+ */
+/**
+ * A state transition request
+ */
+interface WorkflowTransition {
+    /** Record identifier */
+    recordId: string;
+    /** Object name the record belongs to */
+    object: string;
+    /** Target state to transition to */
+    targetState: string;
+    /** Optional comment for the transition */
+    comment?: string;
+    /** User performing the transition */
+    userId?: string;
+}
+/**
+ * Result of a transition attempt
+ */
+interface WorkflowTransitionResult {
+    /** Whether the transition succeeded */
+    success: boolean;
+    /** The new current state (if success) */
+    currentState?: string;
+    /** Error or rejection reason (if failure) */
+    error?: string;
+}
+/**
+ * Status of a workflow instance
+ */
+interface WorkflowStatus {
+    /** Record identifier */
+    recordId: string;
+    /** Object name */
+    object: string;
+    /** Current state */
+    currentState: string;
+    /** Available transitions from the current state */
+    availableTransitions: string[];
+}
+interface IWorkflowService {
+    /**
+     * Transition a record to a new workflow state
+     * @param transition - Transition request details
+     * @returns Transition result
+     */
+    transition(transition: WorkflowTransition): Promise<WorkflowTransitionResult>;
+    /**
+     * Get the current workflow status of a record
+     * @param object - Object name
+     * @param recordId - Record identifier
+     * @returns Current workflow status with available transitions
+     */
+    getStatus(object: string, recordId: string): Promise<WorkflowStatus>;
+    /**
+     * Get transition history for a record
+     * @param object - Object name
+     * @param recordId - Record identifier
+     * @returns Array of historical transitions
+     */
+    getHistory?(object: string, recordId: string): Promise<Array<{
+        fromState: string;
+        toState: string;
+        userId?: string;
+        comment?: string;
+        timestamp: string;
+    }>>;
+}
+
+/**
+ * ObjectStack Contracts
+ *
+ * Core interface definitions following "Protocol First" principle.
+ * All interfaces should be defined in @objectstack/spec to avoid circular dependencies.
+ */
+
+type index_AIMessage = AIMessage;
+type index_AIRequestOptions = AIRequestOptions;
+type index_AIResult = AIResult;
+type index_AnalyticsQuery = AnalyticsQuery;
+type index_AnalyticsResult = AnalyticsResult;
+type index_AuthResult = AuthResult;
+type index_AuthSession = AuthSession;
+type index_AuthUser = AuthUser;
+type index_AutomationContext = AutomationContext;
+type index_AutomationResult = AutomationResult;
+type index_CacheStats = CacheStats;
+type index_CubeMeta = CubeMeta;
+type index_DriverInterface = DriverInterface;
+type index_GraphQLRequest = GraphQLRequest;
+type index_GraphQLResponse = GraphQLResponse;
+type index_HealthStatus = HealthStatus;
+type index_IAIService = IAIService;
+type index_IAdvancedServiceRegistry = IAdvancedServiceRegistry;
+type index_IAnalyticsService = IAnalyticsService;
+type index_IAuthService = IAuthService;
+type index_IAutomationService = IAutomationService;
+type index_IBasicServiceRegistry = IBasicServiceRegistry;
+type index_ICacheService = ICacheService;
+type index_IDataDriver = IDataDriver;
+type index_IDataEngine = IDataEngine;
+type index_IGraphQLService = IGraphQLService;
+type index_IHttpRequest = IHttpRequest;
+type index_IHttpResponse = IHttpResponse;
+type index_IHttpServer = IHttpServer;
+type index_II18nService = II18nService;
+type index_IJobService = IJobService;
+type index_IMetadataService = IMetadataService;
+type index_INotificationService = INotificationService;
+type index_IPluginLifecycleEvents = IPluginLifecycleEvents;
+type index_IPluginValidator = IPluginValidator;
+type index_IQueueService = IQueueService;
+type index_IRealtimeService = IRealtimeService;
+type index_ISchemaDriver = ISchemaDriver;
+type index_ISearchService = ISearchService;
+type index_IServiceRegistry = IServiceRegistry;
+type index_IStartupOrchestrator = IStartupOrchestrator;
+type index_IStorageService = IStorageService;
+type index_ITypedEventEmitter<Events extends Record<string, any[]>> = ITypedEventEmitter<Events>;
+type index_IUIService = IUIService;
+type index_IWorkflowService = IWorkflowService;
+type index_JobExecution = JobExecution;
+type index_JobHandler = JobHandler;
+type index_JobSchedule = JobSchedule;
+type index_Logger = Logger;
+type index_Middleware = Middleware;
+type index_NotificationChannel = NotificationChannel;
+type index_NotificationMessage = NotificationMessage;
+type index_NotificationResult = NotificationResult;
+type index_Plugin = Plugin;
+type index_PluginStartupResult = PluginStartupResult;
+type index_QueueHandler<T = unknown> = QueueHandler<T>;
+type index_QueueMessage<T = unknown> = QueueMessage<T>;
+type index_QueuePublishOptions = QueuePublishOptions;
+type index_RealtimeEventHandler = RealtimeEventHandler;
+type index_RealtimeEventPayload = RealtimeEventPayload;
+type index_RealtimeSubscriptionOptions = RealtimeSubscriptionOptions;
+type index_RouteHandler = RouteHandler;
+type index_SearchHit = SearchHit;
+type index_SearchOptions = SearchOptions;
+type index_SearchResult = SearchResult;
+type index_StartupOptions = StartupOptions;
+type index_StorageFileInfo = StorageFileInfo;
+type index_StorageUploadOptions = StorageUploadOptions;
+type index_ValidationResult = ValidationResult;
+type index_WorkflowStatus = WorkflowStatus;
+type index_WorkflowTransition = WorkflowTransition;
+type index_WorkflowTransitionResult = WorkflowTransitionResult;
+declare namespace index {
+  export type { index_AIMessage as AIMessage, index_AIRequestOptions as AIRequestOptions, index_AIResult as AIResult, index_AnalyticsQuery as AnalyticsQuery, index_AnalyticsResult as AnalyticsResult, index_AuthResult as AuthResult, index_AuthSession as AuthSession, index_AuthUser as AuthUser, index_AutomationContext as AutomationContext, index_AutomationResult as AutomationResult, index_CacheStats as CacheStats, index_CubeMeta as CubeMeta, index_DriverInterface as DriverInterface, index_GraphQLRequest as GraphQLRequest, index_GraphQLResponse as GraphQLResponse, index_HealthStatus as HealthStatus, index_IAIService as IAIService, index_IAdvancedServiceRegistry as IAdvancedServiceRegistry, index_IAnalyticsService as IAnalyticsService, index_IAuthService as IAuthService, index_IAutomationService as IAutomationService, index_IBasicServiceRegistry as IBasicServiceRegistry, index_ICacheService as ICacheService, index_IDataDriver as IDataDriver, index_IDataEngine as IDataEngine, index_IGraphQLService as IGraphQLService, index_IHttpRequest as IHttpRequest, index_IHttpResponse as IHttpResponse, index_IHttpServer as IHttpServer, index_II18nService as II18nService, index_IJobService as IJobService, index_IMetadataService as IMetadataService, index_INotificationService as INotificationService, index_IPluginLifecycleEvents as IPluginLifecycleEvents, index_IPluginValidator as IPluginValidator, index_IQueueService as IQueueService, index_IRealtimeService as IRealtimeService, index_ISchemaDriver as ISchemaDriver, index_ISearchService as ISearchService, index_IServiceRegistry as IServiceRegistry, index_IStartupOrchestrator as IStartupOrchestrator, index_IStorageService as IStorageService, index_ITypedEventEmitter as ITypedEventEmitter, index_IUIService as IUIService, index_IWorkflowService as IWorkflowService, index_JobExecution as JobExecution, index_JobHandler as JobHandler, index_JobSchedule as JobSchedule, index_Logger as Logger, index_Middleware as Middleware, index_NotificationChannel as NotificationChannel, index_NotificationMessage as NotificationMessage, index_NotificationResult as NotificationResult, index_Plugin as Plugin, index_PluginStartupResult as PluginStartupResult, index_QueueHandler as QueueHandler, index_QueueMessage as QueueMessage, index_QueuePublishOptions as QueuePublishOptions, index_RealtimeEventHandler as RealtimeEventHandler, index_RealtimeEventPayload as RealtimeEventPayload, index_RealtimeSubscriptionOptions as RealtimeSubscriptionOptions, index_RouteHandler as RouteHandler, index_SearchHit as SearchHit, index_SearchOptions as SearchOptions, index_SearchResult as SearchResult, index_StartupOptions as StartupOptions, index_StorageFileInfo as StorageFileInfo, index_StorageUploadOptions as StorageUploadOptions, index_ValidationResult as ValidationResult, index_WorkflowStatus as WorkflowStatus, index_WorkflowTransition as WorkflowTransition, index_WorkflowTransitionResult as WorkflowTransitionResult };
+}
+
+export { type CubeMeta as $, type StorageFileInfo as A, type IStorageService as B, type CacheStats as C, type DriverInterface as D, type IMetadataService as E, type AuthUser as F, type AuthSession as G, type HealthStatus as H, type IDataEngine as I, type AuthResult as J, type IAuthService as K, type Logger as L, type Middleware as M, type NotificationChannel as N, type AutomationContext as O, type Plugin as P, type QueuePublishOptions as Q, type RouteHandler as R, type StartupOptions as S, type AutomationResult as T, type IAutomationService as U, type ValidationResult as V, type GraphQLRequest as W, type GraphQLResponse as X, type IGraphQLService as Y, type AnalyticsQuery as Z, type AnalyticsResult as _, type IDataDriver as a, type IAnalyticsService as a0, type RealtimeEventPayload as a1, type RealtimeEventHandler as a2, type RealtimeSubscriptionOptions as a3, type IRealtimeService as a4, type JobSchedule as a5, type JobHandler as a6, type JobExecution as a7, type IJobService as a8, type AIMessage as a9, type AIRequestOptions as aa, type AIResult as ab, type IAIService as ac, type II18nService as ad, type IUIService as ae, type WorkflowTransition as af, type WorkflowTransitionResult as ag, type WorkflowStatus as ah, type IWorkflowService as ai, type IHttpRequest as b, type IHttpResponse as c, type IHttpServer as d, type IServiceRegistry as e, type IBasicServiceRegistry as f, type IAdvancedServiceRegistry as g, type IPluginValidator as h, index as i, type PluginStartupResult as j, type IStartupOrchestrator as k, type IPluginLifecycleEvents as l, type ITypedEventEmitter as m, type ISchemaDriver as n, type ICacheService as o, type SearchOptions as p, type SearchHit as q, type SearchResult as r, type ISearchService as s, type QueueMessage as t, type QueueHandler as u, type IQueueService as v, type NotificationMessage as w, type NotificationResult as x, type INotificationService as y, type StorageUploadOptions as z };