@objectql/types 4.1.0 → 4.2.1

package/dist/action.d.ts

@@ -6,7 +6,8 @@
  * LICENSE file in the root directory of this source tree.
  */
 import { UI } from '@objectstack/spec';
-type Action = UI.Action;
+import { z } from 'zod';
+type Action = z.infer<typeof UI.ActionSchema>;
 import { FieldConfig } from "./field";
 import { HookAPI } from "./hook";
 /**
@@ -35,7 +36,7 @@ export type ActionInputDefinition = Record<string, FieldConfig>;
  *
  * RUNTIME TYPE: Used during action execution.
  */
-export interface ActionContext<BaseT = any, InputT = any> {
+export interface ActionContext<_BaseT = Record<string, unknown>, InputT = Record<string, unknown>> {
     /** The object this action belongs to. */
     objectName: string;
     /** The name of the action being executed. */
@@ -58,7 +59,7 @@ export interface ActionContext<BaseT = any, InputT = any> {
      */
     user?: {
         id: string | number;
-        [key: string]: any;
+        [key: string]: unknown;
     };
 }
 /**
@@ -100,10 +101,10 @@ export interface ActionConfig {
  *
  * RUNTIME TYPE: Includes the handler function for execution.
  */
-export interface ActionDefinition<BaseT = any, InputT = any, ReturnT = any> extends ActionConfig {
+export interface ActionDefinition<BaseT = Record<string, unknown>, InputT = Record<string, unknown>, ReturnT = unknown> extends ActionConfig {
     /**
      * The business logic implementation.
      */
     handler: (ctx: ActionContext<BaseT, InputT>) => Promise<ReturnT>;
 }
-export type ActionHandler<BaseT = any, InputT = any, ReturnT = any> = (ctx: ActionContext<BaseT, InputT>) => Promise<ReturnT>;
+export type ActionHandler<BaseT = Record<string, unknown>, InputT = Record<string, unknown>, ReturnT = unknown> = (ctx: ActionContext<BaseT, InputT>) => Promise<ReturnT>;

package/dist/ai.d.ts

@@ -0,0 +1,118 @@
+/**
+ * ObjectQL - AI Namespace Types
+ * Copyright (c) 2026-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * RUNTIME EXTENSIONS: Not part of the wire protocol.
+ * These types define stable integration points for AI features.
+ */
+/** AI model task types */
+export type AiModelType = 'chat' | 'embedding' | 'rerank' | 'completion' | 'tool';
+/** Model capability flags */
+export interface AiModelCapabilities {
+    readonly chat?: boolean;
+    readonly embedding?: boolean;
+    readonly rerank?: boolean;
+    readonly toolCalling?: boolean;
+    readonly vision?: boolean;
+}
+/** AI model definition for registry */
+export interface AiModelDefinition {
+    /** Unique identifier for registry lookup */
+    readonly id: string;
+    /** Provider name (e.g., openai, anthropic, local) */
+    readonly provider: string;
+    /** Provider model name */
+    readonly model: string;
+    /** Task type */
+    readonly type: AiModelType;
+    /** Optional display name */
+    readonly displayName?: string;
+    /** Max output tokens for generation */
+    readonly maxTokens?: number;
+    /** Context window size */
+    readonly contextWindow?: number;
+    /** Embedding dimensions (if embedding model) */
+    readonly embeddingDimensions?: number;
+    /** Capability flags */
+    readonly capabilities?: AiModelCapabilities;
+    /** Arbitrary metadata */
+    readonly metadata?: Record<string, unknown>;
+}
+/** Registry for AI models */
+export interface ModelRegistry {
+    register(model: AiModelDefinition): void;
+    get(id: string): AiModelDefinition | undefined;
+    list(): readonly AiModelDefinition[];
+    remove(id: string): void;
+}
+/** Prompt template definition */
+export interface PromptTemplate {
+    /** Stable prompt identifier */
+    readonly id: string;
+    /** Optional semantic version tag */
+    readonly version?: string;
+    /** Optional display name */
+    readonly name?: string;
+    /** Prompt template string */
+    readonly template: string;
+    /** Declared variables for the template */
+    readonly variables?: readonly string[];
+    /** Optional description */
+    readonly description?: string;
+    /** Arbitrary metadata */
+    readonly metadata?: Record<string, unknown>;
+}
+/** Registry for prompt templates */
+export interface PromptRegistry {
+    register(template: PromptTemplate): void;
+    get(id: string, version?: string): PromptTemplate | undefined;
+    list(id?: string): readonly PromptTemplate[];
+    remove(id: string, version?: string): void;
+}
+/** Document for RAG indexing */
+export interface RagDocument {
+    readonly id: string;
+    readonly content: string;
+    readonly metadata?: Record<string, unknown>;
+}
+/** RAG search options */
+export interface RagSearchOptions {
+    readonly topK?: number;
+    readonly filter?: Record<string, unknown>;
+    readonly minScore?: number;
+    readonly namespace?: string;
+}
+/** RAG search result */
+export interface RagSearchResult {
+    readonly document: RagDocument;
+    readonly score: number;
+}
+/** Embedding provider interface */
+export interface EmbeddingProvider {
+    embed(texts: readonly string[], modelId: string, options?: {
+        readonly dimensions?: number;
+    }): Promise<number[][]>;
+}
+/** Vector store interface for RAG */
+export interface VectorStore {
+    upsert(documents: readonly RagDocument[], embeddings?: number[][], options?: {
+        readonly namespace?: string;
+    }): Promise<void>;
+    query(embedding: number[], options?: RagSearchOptions): Promise<RagSearchResult[]>;
+    delete(ids: readonly string[], options?: {
+        readonly namespace?: string;
+    }): Promise<void>;
+    clear(options?: {
+        readonly namespace?: string;
+    }): Promise<void>;
+}
+/** AI registry surface for runtime */
+export interface AiRegistry {
+    readonly models: ModelRegistry;
+    readonly prompts: PromptRegistry;
+    readonly embeddings?: EmbeddingProvider;
+    readonly vectorStore?: VectorStore;
+}

package/dist/ai.js

@@ -0,0 +1,13 @@
+"use strict";
+/**
+ * ObjectQL - AI Namespace Types
+ * Copyright (c) 2026-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * RUNTIME EXTENSIONS: Not part of the wire protocol.
+ * These types define stable integration points for AI features.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=ai.js.map

package/dist/ai.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai.js","sourceRoot":"","sources":["../src/ai.ts"],"names":[],"mappings":";AAAA;;;;;;;;;GASG"}

package/dist/api.d.ts

@@ -27,7 +27,23 @@ export declare enum ApiErrorCode {
     CONFLICT = "CONFLICT",
     INTERNAL_ERROR = "INTERNAL_ERROR",
     DATABASE_ERROR = "DATABASE_ERROR",
-    RATE_LIMIT_EXCEEDED = "RATE_LIMIT_EXCEEDED"
+    RATE_LIMIT_EXCEEDED = "RATE_LIMIT_EXCEEDED",
+    DRIVER_ERROR = "DRIVER_ERROR",
+    DRIVER_CONNECTION_FAILED = "DRIVER_CONNECTION_FAILED",
+    DRIVER_QUERY_FAILED = "DRIVER_QUERY_FAILED",
+    DRIVER_TRANSACTION_FAILED = "DRIVER_TRANSACTION_FAILED",
+    DRIVER_UNSUPPORTED_OPERATION = "DRIVER_UNSUPPORTED_OPERATION",
+    PROTOCOL_ERROR = "PROTOCOL_ERROR",
+    PROTOCOL_INVALID_REQUEST = "PROTOCOL_INVALID_REQUEST",
+    PROTOCOL_METHOD_NOT_FOUND = "PROTOCOL_METHOD_NOT_FOUND",
+    PROTOCOL_BATCH_ERROR = "PROTOCOL_BATCH_ERROR",
+    TENANT_ISOLATION_VIOLATION = "TENANT_ISOLATION_VIOLATION",
+    TENANT_NOT_FOUND = "TENANT_NOT_FOUND",
+    WORKFLOW_TRANSITION_DENIED = "WORKFLOW_TRANSITION_DENIED",
+    FORMULA_EVALUATION_ERROR = "FORMULA_EVALUATION_ERROR",
+    CONFIG_ERROR = "CONFIG_ERROR",
+    SCAFFOLD_ERROR = "SCAFFOLD_ERROR",
+    MIGRATION_ERROR = "MIGRATION_ERROR"
 }
 /**
  * Error details structure with optional field-specific information
@@ -79,7 +95,7 @@ export interface PaginationMeta {
 /**
  * Base response structure for Data API operations
  */
-export interface DataApiResponse<T = unknown> {
+export interface DataApiResponse<_T = unknown> {
     /** Error information if the operation failed */
     error?: ApiError;
     /** Additional response fields for successful operations */
@@ -185,7 +201,7 @@ export interface DataApiDeleteResponse extends DataApiResponse {
 /**
  * Base response structure for Metadata API operations
  */
-export interface MetadataApiResponse<T = unknown> {
+export interface MetadataApiResponse<_T = unknown> {
     /** Error information if the operation failed */
     error?: ApiError;
     /** Additional response fields */

package/dist/api.js

@@ -26,6 +26,26 @@ var ApiErrorCode;
     ApiErrorCode["INTERNAL_ERROR"] = "INTERNAL_ERROR";
     ApiErrorCode["DATABASE_ERROR"] = "DATABASE_ERROR";
     ApiErrorCode["RATE_LIMIT_EXCEEDED"] = "RATE_LIMIT_EXCEEDED";
+    // Driver error codes
+    ApiErrorCode["DRIVER_ERROR"] = "DRIVER_ERROR";
+    ApiErrorCode["DRIVER_CONNECTION_FAILED"] = "DRIVER_CONNECTION_FAILED";
+    ApiErrorCode["DRIVER_QUERY_FAILED"] = "DRIVER_QUERY_FAILED";
+    ApiErrorCode["DRIVER_TRANSACTION_FAILED"] = "DRIVER_TRANSACTION_FAILED";
+    ApiErrorCode["DRIVER_UNSUPPORTED_OPERATION"] = "DRIVER_UNSUPPORTED_OPERATION";
+    // Protocol error codes
+    ApiErrorCode["PROTOCOL_ERROR"] = "PROTOCOL_ERROR";
+    ApiErrorCode["PROTOCOL_INVALID_REQUEST"] = "PROTOCOL_INVALID_REQUEST";
+    ApiErrorCode["PROTOCOL_METHOD_NOT_FOUND"] = "PROTOCOL_METHOD_NOT_FOUND";
+    ApiErrorCode["PROTOCOL_BATCH_ERROR"] = "PROTOCOL_BATCH_ERROR";
+    // Plugin error codes
+    ApiErrorCode["TENANT_ISOLATION_VIOLATION"] = "TENANT_ISOLATION_VIOLATION";
+    ApiErrorCode["TENANT_NOT_FOUND"] = "TENANT_NOT_FOUND";
+    ApiErrorCode["WORKFLOW_TRANSITION_DENIED"] = "WORKFLOW_TRANSITION_DENIED";
+    ApiErrorCode["FORMULA_EVALUATION_ERROR"] = "FORMULA_EVALUATION_ERROR";
+    // CLI/Tool error codes
+    ApiErrorCode["CONFIG_ERROR"] = "CONFIG_ERROR";
+    ApiErrorCode["SCAFFOLD_ERROR"] = "SCAFFOLD_ERROR";
+    ApiErrorCode["MIGRATION_ERROR"] = "MIGRATION_ERROR";
 })(ApiErrorCode || (exports.ApiErrorCode = ApiErrorCode = {}));
 /**
  * ObjectQL Error class for throwing structured errors

package/dist/api.js.map

@@ -1 +1 @@
-{"version":3,"file":"api.js","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;;AA6jBH,4CASC;AAxjBD,+EAA+E;AAC/E,uBAAuB;AACvB,+EAA+E;AAE/E;;GAEG;AACH,IAAY,YAUX;AAVD,WAAY,YAAY;IACpB,mDAAmC,CAAA;IACnC,qDAAqC,CAAA;IACrC,6CAA6B,CAAA;IAC7B,uCAAuB,CAAA;IACvB,uCAAuB,CAAA;IACvB,qCAAqB,CAAA;IACrB,iDAAiC,CAAA;IACjC,iDAAiC,CAAA;IACjC,2DAA2C,CAAA;AAC/C,CAAC,EAVW,YAAY,4BAAZ,YAAY,QAUvB;AAwBD;;GAEG;AACH,MAAa,aAAc,SAAQ,KAAK;IAIpC,YAAY,KAAkF;QAC1F,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACrB,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;QAC5B,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC;QACvB,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;QAE7B,uDAAuD;QACvD,MAAM,gBAAgB,GAAG,KAA2F,CAAC;QACrH,IAAI,OAAO,gBAAgB,CAAC,iBAAiB,KAAK,UAAU,EAAE,CAAC;YAC3D,gBAAgB,CAAC,iBAAiB,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC;QAC5D,CAAC;IACL,CAAC;CACJ;AAhBD,sCAgBC;AAqeD;;GAEG;AACU,QAAA,kBAAkB,GAA2B;IACtD,GAAG,EAAE,eAAe;IACpB,IAAI,EAAE,WAAW;IACjB,QAAQ,EAAE,eAAe;IACzB,KAAK,EAAE,YAAY;CACtB,CAAC;AAEF;;;GAGG;AACH,SAAgB,gBAAgB,CAAC,MAAuB;;IACpD,MAAM,aAAa,GAAG,CAAC,IAAY,EAAU,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC;IAEzF,OAAO;QACH,GAAG,EAAE,aAAa,CAAC,MAAA,MAAM,aAAN,MAAM,uBAAN,MAAM,CAAE,GAAG,mCAAI,0BAAkB,CAAC,GAAG,CAAC;QACzD,IAAI,EAAE,aAAa,CAAC,MAAA,MAAM,aAAN,MAAM,uBAAN,MAAM,CAAE,IAAI,mCAAI,0BAAkB,CAAC,IAAI,CAAC;QAC5D,QAAQ,EAAE,aAAa,CAAC,MAAA,MAAM,aAAN,MAAM,uBAAN,MAAM,CAAE,QAAQ,mCAAI,0BAAkB,CAAC,QAAQ,CAAC;QACxE,KAAK,EAAE,aAAa,CAAC,MAAA,MAAM,aAAN,MAAM,uBAAN,MAAM,CAAE,KAAK,mCAAI,0BAAkB,CAAC,KAAK,CAAC;KAClE,CAAC;AACN,CAAC"}
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;;AAqlBH,4CASC;AAhlBD,+EAA+E;AAC/E,uBAAuB;AACvB,+EAA+E;AAE/E;;GAEG;AACH,IAAY,YAkCX;AAlCD,WAAY,YAAY;IACpB,mDAAmC,CAAA;IACnC,qDAAqC,CAAA;IACrC,6CAA6B,CAAA;IAC7B,uCAAuB,CAAA;IACvB,uCAAuB,CAAA;IACvB,qCAAqB,CAAA;IACrB,iDAAiC,CAAA;IACjC,iDAAiC,CAAA;IACjC,2DAA2C,CAAA;IAE3C,qBAAqB;IACrB,6CAA6B,CAAA;IAC7B,qEAAqD,CAAA;IACrD,2DAA2C,CAAA;IAC3C,uEAAuD,CAAA;IACvD,6EAA6D,CAAA;IAE7D,uBAAuB;IACvB,iDAAiC,CAAA;IACjC,qEAAqD,CAAA;IACrD,uEAAuD,CAAA;IACvD,6DAA6C,CAAA;IAE7C,qBAAqB;IACrB,yEAAyD,CAAA;IACzD,qDAAqC,CAAA;IACrC,yEAAyD,CAAA;IACzD,qEAAqD,CAAA;IAErD,uBAAuB;IACvB,6CAA6B,CAAA;IAC7B,iDAAiC,CAAA;IACjC,mDAAmC,CAAA;AACvC,CAAC,EAlCW,YAAY,4BAAZ,YAAY,QAkCvB;AAwBD;;GAEG;AACH,MAAa,aAAc,SAAQ,KAAK;IAIpC,YAAY,KAAkF;QAC1F,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACrB,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;QAC5B,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC;QACvB,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;QAE7B,uDAAuD;QACvD,MAAM,gBAAgB,GAAG,KAA8G,CAAC;QACxI,IAAI,OAAO,gBAAgB,CAAC,iBAAiB,KAAK,UAAU,EAAE,CAAC;YAC3D,gBAAgB,CAAC,iBAAiB,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC;QAC5D,CAAC;IACL,CAAC;CACJ;AAhBD,sCAgBC;AAqeD;;GAEG;AACU,QAAA,kBAAkB,GAA2B;IACtD,GAAG,EAAE,eAAe;IACpB,IAAI,EAAE,WAAW;IACjB,QAAQ,EAAE,eAAe;IACzB,KAAK,EAAE,YAAY;CACtB,CAAC;AAEF;;;GAGG;AACH,SAAgB,gBAAgB,CAAC,MAAuB;;IACpD,MAAM,aAAa,GAAG,CAAC,IAAY,EAAU,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC;IAEzF,OAAO;QACH,GAAG,EAAE,aAAa,CAAC,MAAA,MAAM,aAAN,MAAM,uBAAN,MAAM,CAAE,GAAG,mCAAI,0BAAkB,CAAC,GAAG,CAAC;QACzD,IAAI,EAAE,aAAa,CAAC,MAAA,MAAM,aAAN,MAAM,uBAAN,MAAM,CAAE,IAAI,mCAAI,0BAAkB,CAAC,IAAI,CAAC;QAC5D,QAAQ,EAAE,aAAa,CAAC,MAAA,MAAM,aAAN,MAAM,uBAAN,MAAM,CAAE,QAAQ,mCAAI,0BAAkB,CAAC,QAAQ,CAAC;QACxE,KAAK,EAAE,aAAa,CAAC,MAAA,MAAM,aAAN,MAAM,uBAAN,MAAM,CAAE,KAAK,mCAAI,0BAAkB,CAAC,KAAK,CAAC;KAClE,CAAC;AACN,CAAC"}

package/dist/app.d.ts

@@ -22,10 +22,10 @@ export interface IObjectQL {
     on(event: HookName, objectName: string, handler: HookHandler): void;
     triggerHook(event: HookName, objectName: string, ctx: HookContext): Promise<void>;
     registerAction(objectName: string, actionName: string, handler: ActionHandler): void;
-    executeAction(objectName: string, actionName: string, ctx: ActionContext): Promise<any>;
+    executeAction(objectName: string, actionName: string, ctx: ActionContext): Promise<unknown>;
     /**
      * Get the underlying ObjectKernel instance
      * @returns The ObjectKernel instance
      */
-    getKernel(): any;
+    getKernel(): unknown;
 }

package/dist/application.d.ts

@@ -41,5 +41,5 @@ export interface AppConfig {
     /**
      * Custom metadata/settings
      */
-    [key: string]: any;
+    [key: string]: unknown;
 }

package/dist/config.d.ts

@@ -9,6 +9,7 @@ import { MetadataRegistry } from "./registry";
 import { Driver } from "./driver";
 import { ObjectConfig } from "./object";
 import type { RuntimePlugin } from "./plugin";
+import type { Logger } from "./logger";
 export interface ObjectQLConfig {
     registry?: MetadataRegistry;
     datasources?: Record<string, Driver>;
@@ -46,4 +47,9 @@ export interface ObjectQLConfig {
      * e.g. ["http://user-service:3000", "http://order-service:3000"]
      */
     remotes?: string[];
+    /**
+     * Optional structured logger instance.
+     * If not provided, a ConsoleLogger with level 'info' is used.
+     */
+    logger?: Logger;
 }

package/dist/context.d.ts

@@ -23,7 +23,7 @@ export interface ObjectQLContext {
      * Execute a function within a transaction.
      * The callback receives a new context 'trxCtx' which inherits userId, spaceId from this context.
      */
-    transaction(callback: (trxCtx: ObjectQLContext) => Promise<any>): Promise<any>;
+    transaction(callback: (trxCtx: ObjectQLContext) => Promise<unknown>): Promise<unknown>;
     /**
      * Returns a new context with system privileges (isSystem: true).
      * It shares the same transaction scope as the current context.
@@ -32,7 +32,7 @@ export interface ObjectQLContext {
     /**
      * Internal: Driver-specific transaction handle.
      */
-    transactionHandle?: any;
+    transactionHandle?: unknown;
 }
 export interface ObjectQLContextOptions {
     userId?: string;

package/dist/driver.d.ts

@@ -16,7 +16,7 @@ export interface IntrospectedColumn {
     /** Whether the column is nullable */
     nullable: boolean;
     /** Default value if any */
-    defaultValue?: any;
+    defaultValue?: unknown;
     /** Whether this is a primary key */
     isPrimary?: boolean;
     /** Whether this column has a unique constraint */
@@ -57,88 +57,214 @@ export interface IntrospectedSchema {
     /** Map of table name to table metadata */
     tables: Record<string, IntrospectedTable>;
 }
+/**
+ * Transaction isolation levels supported by the driver.
+ *
+ * Aligned with @objectstack/spec DriverCapabilitiesSchema — uses snake_case per protocol convention.
+ */
+export type IsolationLevel = 'read_uncommitted' | 'read_committed' | 'repeatable_read' | 'serializable' | 'snapshot';
+/**
+ * Driver Capabilities
+ *
+ * Declares what features a driver supports. Aligned with the canonical
+ * DriverCapabilitiesSchema from @objectstack/spec.
+ *
+ * All boolean fields default to `false`. Drivers only set `true` for supported features.
+ */
+export interface DriverCapabilities {
+    readonly create?: boolean;
+    readonly read?: boolean;
+    readonly update?: boolean;
+    readonly delete?: boolean;
+    readonly bulkCreate?: boolean;
+    readonly bulkUpdate?: boolean;
+    readonly bulkDelete?: boolean;
+    readonly transactions?: boolean;
+    readonly savepoints?: boolean;
+    readonly isolationLevels?: readonly IsolationLevel[];
+    readonly queryFilters?: boolean;
+    readonly queryAggregations?: boolean;
+    readonly querySorting?: boolean;
+    readonly queryPagination?: boolean;
+    readonly queryWindowFunctions?: boolean;
+    readonly querySubqueries?: boolean;
+    readonly queryCTE?: boolean;
+    readonly joins?: boolean;
+    readonly fullTextSearch?: boolean;
+    readonly jsonQuery?: boolean;
+    readonly geospatialQuery?: boolean;
+    readonly streaming?: boolean;
+    readonly jsonFields?: boolean;
+    readonly arrayFields?: boolean;
+    readonly vectorSearch?: boolean;
+    /** @deprecated Use `geospatialQuery` instead */
+    readonly geoSpatial?: boolean;
+    readonly schemaSync?: boolean;
+    readonly migrations?: boolean;
+    readonly indexes?: boolean;
+    readonly connectionPooling?: boolean;
+    readonly preparedStatements?: boolean;
+    readonly queryCache?: boolean;
+}
+/**
+ * Runtime Driver Capabilities (extends spec with sync-specific properties)
+ *
+ * These properties are NOT part of the @objectstack/spec DriverCapabilitiesSchema
+ * (which sets additionalProperties: false). They are runtime-only extensions
+ * used by the Offline-First Sync Protocol (Q3).
+ *
+ * Use this interface for drivers that need sync capabilities.
+ */
+export interface RuntimeDriverCapabilities extends DriverCapabilities {
+    /** Driver can record mutations to an append-only log for offline sync */
+    readonly mutationLog?: boolean;
+    /** Driver supports checkpoint-based change tracking */
+    readonly changeTracking?: boolean;
+}
+/**
+ * Driver type discriminator — aligned with @objectstack/spec DriverConfigSchema.
+ */
+export type DriverType = 'sql' | 'nosql' | 'cache' | 'search' | 'graph' | 'timeseries';
+/**
+ * Base driver configuration common to all drivers.
+ * Individual drivers extend this with driver-specific fields.
+ */
+export interface BaseDriverConfig {
+    /** Driver type discriminator */
+    readonly type?: DriverType;
+}
+/**
+ * Database driver interface. All storage backends implement this contract.
+ *
+ * Type strategy:
+ * - `Record<string, unknown>` for data payloads (plain field-value maps)
+ * - `object` for query/filter/command parameters that may receive named interfaces
+ *   (e.g., UnifiedQuery, Filter) which lack implicit index signatures
+ * - `unknown` for opaque values (transaction handles, heterogeneous returns)
+ */
 export interface Driver {
-    name?: string;
-    version?: string;
-    supports?: {
-        transactions?: boolean;
-        joins?: boolean;
-        fullTextSearch?: boolean;
-        jsonFields?: boolean;
-        arrayFields?: boolean;
-        queryFilters?: boolean;
-        queryAggregations?: boolean;
-        querySorting?: boolean;
-        queryPagination?: boolean;
-        queryWindowFunctions?: boolean;
-        querySubqueries?: boolean;
-    };
-    find(objectName: string, query: any, options?: any): Promise<any[]>;
-    findOne(objectName: string, id: string | number, query?: any, options?: any): Promise<any>;
-    create(objectName: string, data: any, options?: any): Promise<any>;
-    update(objectName: string, id: string | number, data: any, options?: any): Promise<any>;
-    delete(objectName: string, id: string | number, options?: any): Promise<any>;
-    count(objectName: string, filters: any, options?: any): Promise<number>;
+    /** Driver identifier (e.g., 'memory', 'sql', 'mongo') */
+    readonly name?: string;
+    /** Driver version (semver) */
+    readonly version?: string;
+    /** Capabilities declaration — what this driver supports */
+    readonly supports?: DriverCapabilities;
+    find(objectName: string, query: object, options?: Record<string, unknown>): Promise<Record<string, unknown>[]>;
+    findOne(objectName: string, id: string | number, query?: object, options?: Record<string, unknown>): Promise<Record<string, unknown> | null>;
+    create(objectName: string, data: Record<string, unknown>, options?: Record<string, unknown>): Promise<Record<string, unknown>>;
+    update(objectName: string, id: string | number, data: Record<string, unknown>, options?: Record<string, unknown>): Promise<Record<string, unknown>>;
+    delete(objectName: string, id: string | number, options?: Record<string, unknown>): Promise<unknown>;
+    count(objectName: string, filters: object, options?: Record<string, unknown>): Promise<number>;
     connect?(): Promise<void>;
     disconnect?(): Promise<void>;
     checkHealth?(): Promise<boolean>;
-    execute?(command: any, parameters?: any[], options?: any): Promise<any>;
-    bulkCreate?(objectName: string, data: any[], options?: any): Promise<any>;
+    execute?(command: object, parameters?: unknown[], options?: Record<string, unknown>): Promise<unknown>;
+    bulkCreate?(objectName: string, data: Record<string, unknown>[], options?: Record<string, unknown>): Promise<unknown>;
     bulkUpdate?(objectName: string, updates: Array<{
         id: string | number;
-        data: any;
-    }>, options?: any): Promise<any>;
-    bulkDelete?(objectName: string, ids: Array<string | number>, options?: any): Promise<any>;
-    distinct?(objectName: string, field: string, filters?: any, options?: any): Promise<any[]>;
-    aggregate?(objectName: string, aggregations: any[], filters?: any, options?: any): Promise<any[]>;
-    beginTransaction?(): Promise<any>;
-    commitTransaction?(transaction: any): Promise<void>;
-    rollbackTransaction?(transaction: any): Promise<void>;
-    init?(objects: any[]): Promise<void>;
+        data: Record<string, unknown>;
+    }>, options?: Record<string, unknown>): Promise<unknown>;
+    bulkDelete?(objectName: string, ids: Array<string | number>, options?: Record<string, unknown>): Promise<unknown>;
+    distinct?(objectName: string, field: string, filters?: object, options?: Record<string, unknown>): Promise<unknown[]>;
+    aggregate?(objectName: string, query: object, options?: Record<string, unknown>): Promise<Record<string, unknown>[]>;
+    beginTransaction?(): Promise<unknown>;
+    /** @deprecated Use `commit` — aligned with @objectstack/spec DriverInterfaceSchema. Will be removed in v5.0. */
+    commitTransaction?(transaction: unknown): Promise<void>;
+    /** @deprecated Use `rollback` — aligned with @objectstack/spec DriverInterfaceSchema. Will be removed in v5.0. */
+    rollbackTransaction?(transaction: unknown): Promise<void>;
+    /** Commit a transaction (spec-aligned name) */
+    commit?(transaction: unknown): Promise<void>;
+    /** Rollback a transaction (spec-aligned name) */
+    rollback?(transaction: unknown): Promise<void>;
+    init?(objects: object[]): Promise<void>;
     /**
      * Introspect the database schema to discover existing tables, columns, and relationships.
-     * This allows connecting to an existing database without defining metadata.
      * @returns Complete schema information including tables, columns, and foreign keys
      */
     introspectSchema?(): Promise<IntrospectedSchema>;
-    aggregate?(objectName: string, query: any, options?: any): Promise<any>;
-    distinct?(objectName: string, field: string, filters?: any, options?: any): Promise<any[]>;
-    createMany?(objectName: string, data: any[], options?: any): Promise<any>;
-    updateMany?(objectName: string, filters: any, data: any, options?: any): Promise<any>;
-    deleteMany?(objectName: string, filters: any, options?: any): Promise<any>;
-    findOneAndUpdate?(objectName: string, filters: any, update: any, options?: any): Promise<any>;
-    beginTransaction?(): Promise<any>;
-    commitTransaction?(trx: any): Promise<void>;
-    rollbackTransaction?(trx: any): Promise<void>;
-    disconnect?(): Promise<void>;
+    createMany?(objectName: string, data: Record<string, unknown>[], options?: Record<string, unknown>): Promise<unknown>;
+    updateMany?(objectName: string, filters: object, data: Record<string, unknown>, options?: Record<string, unknown>): Promise<unknown>;
+    deleteMany?(objectName: string, filters: object, options?: Record<string, unknown>): Promise<unknown>;
+    findOneAndUpdate?(objectName: string, filters: object, update: Record<string, unknown>, options?: Record<string, unknown>): Promise<Record<string, unknown> | null>;
     /**
      * Execute a query using QueryAST format (DriverInterface v4.0)
-     * @param ast - The QueryAST to execute
-     * @param options - Driver-specific options
-     * @returns Query result with value and optional count
      */
-    executeQuery?(ast: any, options?: any): Promise<{
-        value: any[];
+    executeQuery?(ast: object, options?: Record<string, unknown>): Promise<{
+        value: Record<string, unknown>[];
         count?: number;
     }>;
     /**
      * Execute a command using Command format (DriverInterface v4.0)
-     * @param command - The command to execute (create/update/delete/bulk operations)
-     * @param options - Driver-specific options
-     * @returns Command result with success status and affected count
      */
-    executeCommand?(command: any, options?: any): Promise<{
+    executeCommand?(command: object, options?: Record<string, unknown>): Promise<{
         success: boolean;
-        data?: any;
+        data?: unknown;
         affected: number;
     }>;
     /**
-     * Alternative method names for findOne (some drivers use 'get')
+     * Alternative method name for findOne (some drivers use 'get')
+     */
+    get?(objectName: string, id: string, options?: Record<string, unknown>): Promise<Record<string, unknown> | null>;
+    /**
+     * Direct query execution (legacy)
+     */
+    directQuery?(sql: string, params?: unknown[]): Promise<Record<string, unknown>[]>;
+    query?(sql: string, params?: unknown[]): Promise<Record<string, unknown>[]>;
+    /**
+     * Upsert (create or update) a record.
+     * If the record exists (matched by ID or unique key), update it; otherwise, create it.
+     *
+     * @param objectName - The object name.
+     * @param data - Key-value map of field data (must include ID or unique key).
+     * @param options - Driver options.
+     * @returns The upserted record.
+     */
+    upsert?(objectName: string, data: Record<string, unknown>, options?: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /**
+     * Stream records matching the structured query.
+     * Optimized for large datasets to avoid memory overflow.
+     *
+     * @param objectName - The name of the object.
+     * @param query - The structured QueryAST.
+     * @param options - Driver options.
+     * @returns AsyncIterable/ReadableStream of records.
+     */
+    findStream?(objectName: string, query: object, options?: Record<string, unknown>): AsyncIterable<Record<string, unknown>> | unknown;
+    /**
+     * Get connection pool statistics.
+     * Useful for monitoring database load.
+     *
+     * @returns Pool stats object, or undefined if pooling is not supported by the driver.
+     */
+    getPoolStats?(): {
+        total: number;
+        idle: number;
+        active: number;
+        waiting: number;
+    } | undefined;
+    /**
+     * Synchronize the schema for one or more objects.
+     * Creates or alters tables/collections to match the object definitions.
+     *
+     * @param objects - Object definitions to synchronize.
+     * @param options - Driver options.
+     */
+    syncSchema?(objects: object[], options?: Record<string, unknown>): Promise<void>;
+    /**
+     * Drop a table/collection by name.
+     *
+     * @param objectName - The name of the object/table to drop.
+     * @param options - Driver options.
      */
-    get?(objectName: string, id: string, options?: any): Promise<any>;
+    dropTable?(objectName: string, options?: Record<string, unknown>): Promise<void>;
     /**
-     * Direct query execution (legacy, some drivers)
+     * Explain the execution plan for a query.
+     * Useful for debugging and performance optimization.
+     *
+     * @param objectName - The name of the object.
+     * @param query - The structured QueryAST.
+     * @param options - Driver options.
+     * @returns Execution plan details.
      */
-    directQuery?(sql: string, params?: any[]): Promise<any[]>;
-    query?(sql: string, params?: any[]): Promise<any[]>;
+    explain?(objectName: string, query: object, options?: Record<string, unknown>): Promise<unknown>;
 }