From 6a9627d1bf430e5318d5aa3672f73ed635ba6e97 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 9 Feb 2026 12:47:58 +0000 Subject: [PATCH 1/3] Initial plan From b6653c83ac1fdd6e1408df5363f7fe27d71500dd Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 9 Feb 2026 13:00:54 +0000 Subject: [PATCH 2/3] fix: align types with @objectstack/spec v2.0.1 protocol - Fix IsolationLevel to use snake_case per spec (read_uncommitted, read_committed, repeatable_read) and add missing 'snapshot' - Move mutationLog/changeTracking to RuntimeDriverCapabilities (not in spec's DriverCapabilitiesSchema which has additionalProperties: false) - Remove redundant 'location' and 'vector' from FieldType extension (now in spec's FieldType enum) - Add spec-aligned Driver methods: commit, rollback, upsert, findStream, getPoolStats, syncSchema, dropTable, explain - Mark commitTransaction/rollbackTransaction as deprecated in favor of spec-aligned commit/rollback - Update pg-wasm driver isolation levels to snake_case - Remove mutationLog/changeTracking from pg-wasm and sqlite-wasm drivers - Update pg-wasm tests for snake_case isolation levels Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com> --- packages/drivers/pg-wasm/src/index.ts | 6 +- packages/drivers/pg-wasm/test/index.test.ts | 6 +- packages/drivers/sqlite-wasm/src/index.ts | 4 +- packages/foundation/types/src/driver.ts | 82 ++++++++++++++++++++- packages/foundation/types/src/field.ts | 6 +- 5 files changed, 88 insertions(+), 16 deletions(-) diff --git a/packages/drivers/pg-wasm/src/index.ts b/packages/drivers/pg-wasm/src/index.ts index c9b7d96f..1f8a98f1 100644 --- a/packages/drivers/pg-wasm/src/index.ts +++ b/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; diff --git a/packages/drivers/pg-wasm/test/index.test.ts b/packages/drivers/pg-wasm/test/index.test.ts index 03052202..b65f29d9 100644 --- a/packages/drivers/pg-wasm/test/index.test.ts +++ b/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'); }); diff --git a/packages/drivers/sqlite-wasm/src/index.ts b/packages/drivers/sqlite-wasm/src/index.ts index d4f0e3f6..b8e471eb 100644 --- a/packages/drivers/sqlite-wasm/src/index.ts +++ b/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; diff --git a/packages/foundation/types/src/driver.ts b/packages/foundation/types/src/driver.ts index cbb43ea4..93e58ffb 100644 --- a/packages/foundation/types/src/driver.ts +++ b/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; + /** @deprecated Use `commit` — aligned with @objectstack/spec DriverInterfaceSchema */ commitTransaction?(transaction: any): Promise; + /** @deprecated Use `rollback` — aligned with @objectstack/spec DriverInterfaceSchema */ rollbackTransaction?(transaction: any): Promise; + /** Commit a transaction (spec-aligned name) */ + commit?(transaction: any): Promise; + /** Rollback a transaction (spec-aligned name) */ + rollback?(transaction: any): Promise; // Schema / Lifecycle init?(objects: any[]): Promise; @@ -229,5 +247,65 @@ export interface Driver { */ directQuery?(sql: string, params?: any[]): Promise; query?(sql: string, params?: any[]): Promise; + + // ======================================================================== + // 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, options?: any): Promise; + + /** + * 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; + + /** + * Get connection pool statistics. + * Useful for monitoring database load. + */ + 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; + + /** + * 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; + + /** + * 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; } diff --git a/packages/foundation/types/src/field.ts b/packages/foundation/types/src/field.ts index cfbc2782..e33f2a6e 100644 --- a/packages/foundation/types/src/field.ts +++ b/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 /** From 12c1ac1236cb07962abd80c6d50cac795c62c7ff Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 9 Feb 2026 13:01:51 +0000 Subject: [PATCH 3/3] fix: improve deprecation comments per code review feedback Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com> --- packages/foundation/types/src/driver.ts | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/packages/foundation/types/src/driver.ts b/packages/foundation/types/src/driver.ts index 93e58ffb..04f73946 100644 --- a/packages/foundation/types/src/driver.ts +++ b/packages/foundation/types/src/driver.ts @@ -202,9 +202,9 @@ export interface Driver { // Transaction support beginTransaction?(): Promise; - /** @deprecated Use `commit` — aligned with @objectstack/spec DriverInterfaceSchema */ + /** @deprecated Use `commit` — aligned with @objectstack/spec DriverInterfaceSchema. Will be removed in v5.0. */ commitTransaction?(transaction: any): Promise; - /** @deprecated Use `rollback` — aligned with @objectstack/spec DriverInterfaceSchema */ + /** @deprecated Use `rollback` — aligned with @objectstack/spec DriverInterfaceSchema. Will be removed in v5.0. */ rollbackTransaction?(transaction: any): Promise; /** Commit a transaction (spec-aligned name) */ commit?(transaction: any): Promise; @@ -277,6 +277,8 @@ export interface Driver { /** * 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;