@objectql/types 4.1.0 → 4.2.0

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";
 /**

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/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/driver.d.ts

@@ -57,22 +57,72 @@ export interface IntrospectedSchema {
     /** Map of table name to table metadata */
     tables: Record<string, IntrospectedTable>;
 }
+/**
+ * Transaction isolation levels supported by the driver.
+ */
+export type IsolationLevel = 'read-uncommitted' | 'read-committed' | 'repeatable-read' | 'serializable';
+/**
+ * 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;
+}
+/**
+ * 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;
+}
 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;
-    };
+    /** 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: 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>;
@@ -90,32 +140,22 @@ export interface Driver {
     }>, 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[]>;
+    aggregate?(objectName: string, query: any, options?: any): Promise<any[]>;
     beginTransaction?(): Promise<any>;
     commitTransaction?(transaction: any): Promise<void>;
     rollbackTransaction?(transaction: any): Promise<void>;
     init?(objects: any[]): 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>;
     /**
      * 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[];
@@ -123,9 +163,6 @@ export interface Driver {
     }>;
     /**
      * 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<{
         success: boolean;
@@ -133,11 +170,11 @@ export interface Driver {
         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?: any): Promise<any>;
     /**
-     * Direct query execution (legacy, some drivers)
+     * Direct query execution (legacy)
      */
     directQuery?(sql: string, params?: any[]): Promise<any[]>;
     query?(sql: string, params?: any[]): Promise<any[]>;

package/dist/field.d.ts

@@ -6,9 +6,10 @@
  * LICENSE file in the root directory of this source tree.
  */
 import { Data } from '@objectstack/spec';
-type ProtocolFieldType = Data.FieldType;
-type Field = Data.Field;
-type SpecSelectOption = Data.SelectOption;
+import { z } from 'zod';
+type ProtocolFieldType = z.infer<typeof Data.FieldType>;
+type Field = z.infer<typeof Data.FieldSchema>;
+type SpecSelectOption = z.infer<typeof Data.SelectOption>;
 /**
  * Re-export Protocol Types from the Constitution
  * These are the wire-protocol standard types defined in @objectstack/spec

package/dist/index.d.ts

@@ -33,3 +33,5 @@ export * from './workflow';
 export * from './formula';
 export * from './plugin';
 export * from './gateway';
+export * from './logger';
+export * from './ai';

package/dist/index.js

@@ -49,4 +49,6 @@ __exportStar(require("./workflow"), exports);
 __exportStar(require("./formula"), exports);
 __exportStar(require("./plugin"), exports);
 __exportStar(require("./gateway"), exports);
+__exportStar(require("./logger"), exports);
+__exportStar(require("./ai"), exports);
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;;;;;;;;;;;;;;;AAEH;;;;;;GAMG;AACH,0CAAwB;AACxB,2CAAyB;AACzB,2CAAyB;AACzB,0CAAwB;AACxB,6CAA2B;AAC3B,yCAAuB;AACvB,2CAAyB;AACzB,+CAA6B;AAC7B,wCAAsB;AACtB,2CAAyB;AACzB,4CAA0B;AAC1B,+CAA6B;AAC7B,+CAA6B;AAC7B,2CAAyB;AACzB,gDAA8B;AAC9B,8CAA4B;AAC5B,wCAAsB;AACtB,6CAA2B;AAC3B,4CAA0B;AAC1B,2CAAyB;AACzB,4CAA0B"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;;;;;;;;;;;;;;;AAEH;;;;;;GAMG;AACH,0CAAwB;AACxB,2CAAyB;AACzB,2CAAyB;AACzB,0CAAwB;AACxB,6CAA2B;AAC3B,yCAAuB;AACvB,2CAAyB;AACzB,+CAA6B;AAC7B,wCAAsB;AACtB,2CAAyB;AACzB,4CAA0B;AAC1B,+CAA6B;AAC7B,+CAA6B;AAC7B,2CAAyB;AACzB,gDAA8B;AAC9B,8CAA4B;AAC5B,wCAAsB;AACtB,6CAA2B;AAC3B,4CAA0B;AAC1B,2CAAyB;AACzB,4CAA0B;AAC1B,2CAAyB;AACzB,uCAAqB"}

package/dist/logger.d.ts

@@ -0,0 +1,126 @@
+/**
+ * ObjectQL - Logger Type Definitions
+ * 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.
+ *
+ * Defines the canonical Logger interface for the ObjectQL ecosystem.
+ * All packages must use this interface instead of direct console.* calls.
+ */
+/**
+ * Log severity levels (RFC 5424 Syslog)
+ */
+export type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+/**
+ * Log output format
+ */
+export type LogFormat = 'json' | 'pretty' | 'compact';
+/**
+ * Structured log entry for serialization
+ */
+export interface LogEntry {
+    /** ISO 8601 timestamp */
+    readonly timestamp: string;
+    /** Log severity level */
+    readonly level: LogLevel;
+    /** Logger name / component identifier */
+    readonly name: string;
+    /** Human-readable message */
+    readonly message: string;
+    /** Structured metadata (key-value pairs) */
+    readonly data?: Record<string, unknown>;
+    /** Error object, if applicable */
+    readonly error?: {
+        readonly name: string;
+        readonly message: string;
+        readonly stack?: string;
+    };
+}
+/**
+ * Logger configuration
+ */
+export interface LoggerConfig {
+    /** Logger name / component identifier */
+    readonly name: string;
+    /** Minimum log level to emit */
+    readonly level?: LogLevel;
+    /** Output format */
+    readonly format?: LogFormat;
+}
+/**
+ * Canonical Logger interface for the ObjectQL ecosystem
+ *
+ * All packages must program against this interface.
+ * Implementations are provided by the runtime layer (`@objectstack/core`
+ * or a custom adapter), keeping foundation packages runtime-agnostic.
+ *
+ * @example
+ * ```typescript
+ * class MyPlugin {
+ *   private logger: Logger;
+ *   constructor(logger: Logger) {
+ *     this.logger = logger;
+ *   }
+ *   async process() {
+ *     this.logger.info('Processing started', { batch: 42 });
+ *   }
+ * }
+ * ```
+ */
+export interface Logger {
+    /** Finest-grained informational events */
+    trace(message: string, data?: Record<string, unknown>): void;
+    /** Detailed debug information */
+    debug(message: string, data?: Record<string, unknown>): void;
+    /** Informational messages that highlight progress */
+    info(message: string, data?: Record<string, unknown>): void;
+    /** Potentially harmful situations */
+    warn(message: string, data?: Record<string, unknown>): void;
+    /** Error events that might still allow the application to continue */
+    error(message: string, error?: Error, data?: Record<string, unknown>): void;
+    /** Severe error events that will presumably lead to application abort */
+    fatal(message: string, error?: Error, data?: Record<string, unknown>): void;
+}
+/**
+ * Factory function signature for creating Logger instances.
+ * Typically provided by the runtime layer.
+ */
+export type LoggerFactory = (config: LoggerConfig) => Logger;
+/**
+ * Console-based Logger implementation
+ *
+ * A zero-dependency reference implementation suitable for:
+ * - Unit tests (without mocking an external logger library)
+ * - Development environments
+ * - Packages that cannot depend on `@objectstack/core`
+ *
+ * For production use, prefer the structured logger from `@objectstack/core`.
+ */
+export declare class ConsoleLogger implements Logger {
+    private readonly name;
+    private readonly level;
+    private static readonly LEVELS;
+    constructor(config: LoggerConfig);
+    private shouldLog;
+    private format;
+    trace(message: string, data?: Record<string, unknown>): void;
+    debug(message: string, data?: Record<string, unknown>): void;
+    info(message: string, data?: Record<string, unknown>): void;
+    warn(message: string, data?: Record<string, unknown>): void;
+    error(message: string, error?: Error, data?: Record<string, unknown>): void;
+    fatal(message: string, error?: Error, data?: Record<string, unknown>): void;
+}
+/**
+ * No-op Logger implementation
+ *
+ * Useful for suppressing all log output (e.g., in benchmarks or silent tests).
+ */
+export declare class NullLogger implements Logger {
+    trace(): void;
+    debug(): void;
+    info(): void;
+    warn(): void;
+    error(): void;
+    fatal(): void;
+}

package/dist/logger.js

@@ -0,0 +1,95 @@
+"use strict";
+/**
+ * ObjectQL - Logger Type Definitions
+ * 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.
+ *
+ * Defines the canonical Logger interface for the ObjectQL ecosystem.
+ * All packages must use this interface instead of direct console.* calls.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NullLogger = exports.ConsoleLogger = void 0;
+/**
+ * Console-based Logger implementation
+ *
+ * A zero-dependency reference implementation suitable for:
+ * - Unit tests (without mocking an external logger library)
+ * - Development environments
+ * - Packages that cannot depend on `@objectstack/core`
+ *
+ * For production use, prefer the structured logger from `@objectstack/core`.
+ */
+class ConsoleLogger {
+    constructor(config) {
+        var _a;
+        this.name = config.name;
+        this.level = (_a = config.level) !== null && _a !== void 0 ? _a : 'info';
+    }
+    shouldLog(level) {
+        return ConsoleLogger.LEVELS[level] >= ConsoleLogger.LEVELS[this.level];
+    }
+    format(level, message, data) {
+        const ts = new Date().toISOString();
+        const prefix = `${ts} [${level.toUpperCase().padEnd(5)}] [${this.name}]`;
+        if (data && Object.keys(data).length > 0) {
+            return `${prefix} ${message} ${JSON.stringify(data)}`;
+        }
+        return `${prefix} ${message}`;
+    }
+    trace(message, data) {
+        if (this.shouldLog('trace'))
+            console.debug(this.format('trace', message, data));
+    }
+    debug(message, data) {
+        if (this.shouldLog('debug'))
+            console.debug(this.format('debug', message, data));
+    }
+    info(message, data) {
+        if (this.shouldLog('info'))
+            console.log(this.format('info', message, data));
+    }
+    warn(message, data) {
+        if (this.shouldLog('warn'))
+            console.warn(this.format('warn', message, data));
+    }
+    error(message, error, data) {
+        if (this.shouldLog('error')) {
+            console.error(this.format('error', message, data));
+            if (error === null || error === void 0 ? void 0 : error.stack)
+                console.error(error.stack);
+        }
+    }
+    fatal(message, error, data) {
+        if (this.shouldLog('fatal')) {
+            console.error(this.format('fatal', message, data));
+            if (error === null || error === void 0 ? void 0 : error.stack)
+                console.error(error.stack);
+        }
+    }
+}
+exports.ConsoleLogger = ConsoleLogger;
+ConsoleLogger.LEVELS = {
+    trace: 0,
+    debug: 1,
+    info: 2,
+    warn: 3,
+    error: 4,
+    fatal: 5,
+};
+/**
+ * No-op Logger implementation
+ *
+ * Useful for suppressing all log output (e.g., in benchmarks or silent tests).
+ */
+class NullLogger {
+    trace() { }
+    debug() { }
+    info() { }
+    warn() { }
+    error() { }
+    fatal() { }
+}
+exports.NullLogger = NullLogger;
+//# sourceMappingURL=logger.js.map

package/dist/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"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"}

package/dist/object.d.ts

@@ -5,9 +5,24 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
+import { Data, Automation } from '@objectstack/spec';
+import { z } from 'zod';
 import { FieldConfig } from './field';
 import { ActionConfig } from './action';
 import { AnyValidationRule } from './validation';
+/**
+ * Re-export Protocol Types from @objectstack/spec 1.1.0
+ * State Machine, Object Ownership, and Object Extension types.
+ */
+export type StateMachineConfig = z.infer<typeof Automation.StateMachineSchema>;
+export type StateNodeConfig = z.infer<typeof Automation.StateNodeSchema>;
+export type Transition = z.infer<typeof Automation.TransitionSchema>;
+export type ActionRef = z.infer<typeof Automation.ActionRefSchema>;
+export type ObjectOwnership = z.infer<typeof Data.ObjectOwnershipEnum>;
+export type ObjectExtension = z.infer<typeof Data.ObjectExtensionSchema>;
+export type ServiceObject = z.infer<typeof Data.ObjectSchema>;
+/** Re-export Zod schemas for validation */
+export { Data, Automation };
 /**
  * RUNTIME-SPECIFIC TYPES
  * The following types extend or complement the Protocol Constitution
@@ -104,6 +119,18 @@ export interface ObjectConfig {
     /**
      * RUNTIME EXTENSIONS BELOW
      */
+    /**
+     * State Machine definition for object lifecycle management.
+     * Follows the @objectstack/spec StateMachineConfig protocol.
+     * Enables declarative state transitions, guards, and entry/exit actions.
+     */
+    stateMachine?: StateMachineConfig;
+    /**
+     * Named state machines for multi-field lifecycle.
+     * Each key is a state machine identifier, useful when an object
+     * has multiple independent state fields.
+     */
+    stateMachines?: Record<string, StateMachineConfig>;
     /** AI capabilities configuration (RUNTIME ONLY) */
     ai?: ObjectAiConfig;
     /** Custom actions (RUNTIME ONLY) */

package/dist/object.js

@@ -7,4 +7,8 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.Automation = exports.Data = void 0;
+const spec_1 = require("@objectstack/spec");
+Object.defineProperty(exports, "Data", { enumerable: true, get: function () { return spec_1.Data; } });
+Object.defineProperty(exports, "Automation", { enumerable: true, get: function () { return spec_1.Automation; } });
 //# sourceMappingURL=object.js.map

package/dist/object.js.map

@@ -1 +1 @@
-{"version":3,"file":"object.js","sourceRoot":"","sources":["../src/object.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG"}
+{"version":3,"file":"object.js","sourceRoot":"","sources":["../src/object.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;;AAEH,4CAAqD;AAmB5C,qFAnBA,WAAI,OAmBA;AAAE,2FAnBA,iBAAU,OAmBA"}

package/dist/plugin.d.ts

@@ -78,6 +78,11 @@ export interface RuntimePlugin {
      * Example: '1.0.0', '2.1.3-beta'
      */
     version?: string;
+    /**
+     * Initialize the plugin
+     * Called when the plugin is loaded into the kernel
+     */
+    init?(ctx: RuntimeContext): Promise<void>;
     /**
      * Install hook - called during kernel initialization
      *

package/dist/query.d.ts

@@ -6,22 +6,27 @@
  * LICENSE file in the root directory of this source tree.
  */
 import { Data } from '@objectstack/spec';
-type FilterCondition = Data.FilterCondition;
+import { z } from 'zod';
+export type Filter = z.infer<typeof Data.FilterCondition>;
+export type SortNode = z.infer<typeof Data.SortNodeSchema>;
+export type AggregationFunctionType = z.infer<typeof Data.AggregationFunction>;
+export type AggregationNode = z.infer<typeof Data.AggregationNodeSchema>;
 /**
- * Modern Query Filter using @objectstack/spec FilterCondition
- *
- * Supports MongoDB/Prisma-style object-based syntax:
- * - Implicit equality: { field: value }
- * - Explicit operators: { field: { $eq: value, $gt: 10 } }
- * - Logical operators: { $and: [...], $or: [...] }
- * - String operators: { name: { $contains: "text" } }
- * - Range operators: { age: { $gte: 18, $lte: 65 } }
- * - Set operators: { status: { $in: ["active", "pending"] } }
- * - Null checks: { field: { $null: true } }
+ * Unified Query Interface - Standard Protocol Format
  *
- * Note: $not operator is not supported. Use $ne for field-level negation.
+ * Uses @objectstack/spec QuerySchema inference directly.
+ * We make 'object' optional because in many contexts (like Repository.find),
+ * the object is implicit.
+ */
+type SpecQuery = z.infer<typeof Data.QuerySchema>;
+export interface UnifiedQuery extends Omit<SpecQuery, 'object'> {
+    object?: string;
+}
+/**
+ * Standard QueryAST definition.
+ * Aliased to UnifiedQuery for backward compatibility and consistency.
  */
-export type Filter = FilterCondition;
+export type QueryAST = UnifiedQuery;
 /** @deprecated Use AggregationFunctionType instead */
 export type AggregateFunction = AggregationFunctionType;
 /** @deprecated Use AggregationNode instead */
@@ -30,62 +35,4 @@ export interface AggregateOption {
     field: string;
     alias?: string;
 }
-/**
- * Sort Node - Standard Protocol Format
- * Represents an "Order By" clause.
- */
-export interface SortNode {
-    /** Field name to sort by */
-    field: string;
-    /** Sort direction - defaults to 'asc' */
-    order: 'asc' | 'desc';
-}
-/**
- * Aggregation Function - Standard Protocol Format
- */
-export type AggregationFunctionType = 'count' | 'sum' | 'avg' | 'min' | 'max' | 'count_distinct' | 'array_agg' | 'string_agg';
-/**
- * Aggregation Node - Standard Protocol Format
- * Represents an aggregated field with function.
- */
-export interface AggregationNode {
-    /** Aggregation function to apply */
-    function: AggregationFunctionType;
-    /** Field to aggregate (optional for count) */
-    field?: string;
-    /** Alias for the result field */
-    alias: string;
-    /** Apply DISTINCT to the field before aggregation */
-    distinct?: boolean;
-    /** Optional filter condition for this aggregation */
-    filter?: Filter;
-}
-/**
- * Unified Query Interface - Standard Protocol Format
- *
- * Uses @objectstack/spec QueryAST format directly.
- * This is the single source of truth for query structure.
- */
-export interface UnifiedQuery {
-    /** Field selection - specify which fields to return */
-    fields?: string[];
-    /** Filter conditions using standard FilterCondition syntax (was: filters) */
-    where?: Filter;
-    /** Sort order - array of SortNode objects (was: sort as tuples) */
-    orderBy?: SortNode[];
-    /** Pagination - number of records to skip (was: skip) */
-    offset?: number;
-    /** Pagination - maximum number of records to return */
-    limit?: number;
-    /** Relation expansion - load related records */
-    expand?: Record<string, UnifiedQuery>;
-    /** Aggregation - group by fields */
-    groupBy?: string[];
-    /** Aggregation - aggregate functions to apply (was: aggregate with func) */
-    aggregations?: AggregationNode[];
-    /** Filter for aggregated results (HAVING clause) */
-    having?: Filter;
-    /** Enable distinct results */
-    distinct?: boolean;
-}
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@objectql/types",
-  "version": "4.1.0",
+  "version": "4.2.0",
   "description": "Pure TypeScript type definitions and interfaces for the ObjectQL protocol - The Contract",
   "keywords": [
     "objectql",
@@ -17,6 +17,12 @@
   "license": "MIT",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
   "files": [
     "dist",
     "schemas"
@@ -24,12 +30,11 @@
   "scripts": {
     "build": "tsc",
     "generate:schemas": "node scripts/generate-schemas.js",
-    "test": "jest --passWithNoTests"
-  },
-  "dependencies": {
-    "@objectstack/spec": "^1.0.0"
+    "test": "vitest run"
   },
+  "dependencies": {},
   "devDependencies": {
+    "@objectstack/spec": "^1.1.0",
     "ts-json-schema-generator": "^2.4.0",
     "zod": "^3.23.8"
   }