Merge pull request #358 from objectstack-ai/copilot/update-packages-according-spec

Author: hotlong

packages/drivers/pg-wasm/src/index.ts

@@ -57,7 +57,7 @@ export class PgWasmDriver implements Driver {
         bulkDelete: true,
         transactions: true,
         savepoints: true,
-        isolationLevels: ['read-uncommitted', 'read-committed', 'repeatable-read', 'serializable'],
+        isolationLevels: ['read_uncommitted', 'read_committed', 'repeatable_read', 'serializable'],
         queryFilters: true,
         queryAggregations: true,
         querySorting: true,
@@ -76,9 +76,7 @@ export class PgWasmDriver implements Driver {
         indexes: true,
         connectionPooling: false,
         preparedStatements: true,
-        queryCache: false,
-        mutationLog: true,
-        changeTracking: true
+        queryCache: false
     };
 
     private config: Required<PgWasmDriverConfig>;

packages/drivers/pg-wasm/test/index.test.ts

@@ -96,9 +96,9 @@ describe('PgWasmDriver - Capabilities', () => {
     });
 
     it('should support all isolation levels', () => {
-        expect(driver.supports.isolationLevels).toContain('read-uncommitted');
-        expect(driver.supports.isolationLevels).toContain('read-committed');
-        expect(driver.supports.isolationLevels).toContain('repeatable-read');
+        expect(driver.supports.isolationLevels).toContain('read_uncommitted');
+        expect(driver.supports.isolationLevels).toContain('read_committed');
+        expect(driver.supports.isolationLevels).toContain('repeatable_read');
         expect(driver.supports.isolationLevels).toContain('serializable');
     });
 

packages/drivers/sqlite-wasm/src/index.ts

@@ -73,9 +73,7 @@ export class SqliteWasmDriver implements Driver {
         indexes: true,
         connectionPooling: false,
         preparedStatements: true,
-        queryCache: false,
-        mutationLog: true,
-        changeTracking: true
+        queryCache: false
     };
 
     private config: SqliteWasmDriverConfig;

packages/foundation/types/src/driver.ts

@@ -68,8 +68,10 @@ export interface IntrospectedSchema {
 
 /**
  * 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';
+export type IsolationLevel = 'read_uncommitted' | 'read_committed' | 'repeatable_read' | 'serializable' | 'snapshot';
 
 /**
  * Driver Capabilities
@@ -131,8 +133,18 @@ export interface DriverCapabilities {
     readonly connectionPooling?: boolean;
     readonly preparedStatements?: boolean;
     readonly queryCache?: boolean;
+}
 
-    // Sync support (Q3 — Offline-First Sync Protocol)
+/**
+ * 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 */
@@ -190,8 +202,14 @@ export interface Driver {
 
     // Transaction support
     beginTransaction?(): Promise<any>;
+    /** @deprecated Use `commit` — aligned with @objectstack/spec DriverInterfaceSchema. Will be removed in v5.0. */
     commitTransaction?(transaction: any): Promise<void>;
+    /** @deprecated Use `rollback` — aligned with @objectstack/spec DriverInterfaceSchema. Will be removed in v5.0. */
     rollbackTransaction?(transaction: any): Promise<void>;
+    /** Commit a transaction (spec-aligned name) */
+    commit?(transaction: any): Promise<void>;
+    /** Rollback a transaction (spec-aligned name) */
+    rollback?(transaction: any): Promise<void>;
 
     // Schema / Lifecycle
     init?(objects: any[]): Promise<void>;
@@ -229,5 +247,67 @@ export interface Driver {
      */
     directQuery?(sql: string, params?: any[]): Promise<any[]>;
     query?(sql: string, params?: any[]): Promise<any[]>;
+
+    // ========================================================================
+    // Methods from @objectstack/spec DriverInterfaceSchema
+    // ========================================================================
+
+    /**
+     * 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?: any): Promise<any>;
+
+    /**
+     * 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: any, options?: any): AsyncIterable<any> | any;
+
+    /**
+     * 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: any[], options?: any): Promise<void>;
+
+    /**
+     * Drop a table/collection by name.
+     * 
+     * @param objectName - The name of the object/table to drop.
+     * @param options - Driver options.
+     */
+    dropTable?(objectName: string, options?: any): Promise<void>;
+
+    /**
+     * 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.
+     */
+    explain?(objectName: string, query: any, options?: any): Promise<any>;
 }
 

packages/foundation/types/src/field.ts

@@ -87,14 +87,12 @@ export interface ImageAttachmentData extends AttachmentData {
  * Runtime Field Type
  * 
  * Extends the Protocol FieldType with runtime-specific types.
- * The Protocol Constitution defines the core field types.
- * We add runtime-specific types like 'vector', 'grid', 'location', 'object' here.
+ * The Protocol Constitution defines the core field types (including 'location' and 'vector').
+ * We add runtime-specific types like 'grid' and 'object' here.
  */
 export type FieldType = 
     | ProtocolFieldType
-    | 'location'    // Runtime: Geographic location
     | 'object'      // Runtime: Nested object/JSON
-    | 'vector'      // Runtime: Vector embeddings for AI
     | 'grid';       // Runtime: Inline grid/table
 
 /**