test: add canonical QueryOptionsV2 and offset() alias tests, update ROADMAP.md

Agent-Logs-Url: https://github.com/objectstack-ai/spec/sessions/d243fae5-51a7-4440-926f-46f040744cb0

Co-authored-by: xuyushun441-sys <255036401+xuyushun441-sys@users.noreply.github.com>

Author: Copilot

ROADMAP.md

@@ -1,6 +1,6 @@
 # ObjectStack Protocol — Road Map
 
-> **Last Updated:** 2026-02-28  
+> **Last Updated:** 2026-03-27  
 > **Current Version:** v3.0.11  
 > **Status:** Protocol Specification Complete · Runtime Implementation In Progress
 
@@ -129,6 +129,7 @@ This strategy ensures rapid iteration while maintaining a clear path to producti
 | Dispatcher async `getService` bug fix | ✅ | All `getService`/`getObjectQLService` calls in `http-dispatcher.ts` now properly `await` async service factories. Covers `handleAnalytics`, `handleAuth`, `handleStorage`, `handleAutomation`, `handleMetadata`, `handleUi`, `handlePackages`. All 7 framework adapters (Express, Fastify, Hono, Next.js, SvelteKit, NestJS, Nuxt) updated to use `getServiceAsync()` for auth service resolution. |
 | Analytics `getMetadata` → `getMeta` naming fix | ✅ | `handleAnalytics` in `http-dispatcher.ts` called `getMetadata({ request })` which didn't match the `IAnalyticsService` contract (`getMeta(cubeName?: string)`). Renamed to `getMeta()` and aligned call signature. Updated test mocks accordingly. |
 | Unified ID/audit/tenant field naming | ✅ | Eliminated `_id`/`modified_at`/`modified_by`/`space_id` from protocol layer. All protocol code uses `id`, `updated_at`, `updated_by`, `tenant_id` per `SystemFieldName`. Storage-layer (NoSQL driver internals) retains `_id` for MongoDB/Mingo compat. |
+| **Query syntax canonical unification** | ✅ | All layers (Client SDK, React Hooks, Studio QueryBuilder, HTTP Dispatcher, docs) unified to Spec canonical field names (`where`/`fields`/`orderBy`/`limit`/`offset`/`expand`). `QueryOptionsV2` interface added. Legacy names (`filter`/`select`/`sort`/`top`/`skip`) accepted with `@deprecated` markers. HTTP Dispatcher normalizes transport params to canonical QueryAST before broker dispatch. |
 
 ---
 

packages/client/src/client.test.ts

@@ -827,3 +827,73 @@ describe('ObjectStackClient.automation', () => {
         expect(client.capabilities!.search).toBe(true);
     });
 });
+
+// ==========================================
+// QueryOptionsV2 (Canonical Query Syntax) Tests
+// ==========================================
+
+describe('QueryOptionsV2 — canonical find()', () => {
+    it('should accept canonical field names (where, fields, orderBy, limit, offset)', async () => {
+        const { client, fetchMock } = createMockClient({
+            success: true,
+            data: { object: 'account', records: [], total: 0 }
+        });
+
+        await client.data.find('account', {
+            where: { status: 'active' },
+            fields: ['name', 'email'],
+            orderBy: ['-created_at'],
+            limit: 10,
+            offset: 5,
+        });
+
+        const url = fetchMock.mock.calls[0][0] as string;
+        // V2 canonical options are normalized to HTTP transport params
+        expect(url).toContain('top=10');
+        expect(url).toContain('skip=5');
+        expect(url).toContain('select=name%2Cemail');
+        expect(url).toContain('sort=-created_at');
+        // where → filter as JSON
+        expect(url).toContain('status=active');
+    });
+
+    it('should still accept legacy field names (filter, select, sort, top, skip)', async () => {
+        const { client, fetchMock } = createMockClient({
+            success: true,
+            data: { object: 'account', records: [], total: 0 }
+        });
+
+        await client.data.find('account', {
+            filter: { industry: 'Tech' },
+            select: ['name'],
+            sort: ['-revenue'],
+            top: 20,
+            skip: 0,
+        });
+
+        const url = fetchMock.mock.calls[0][0] as string;
+        expect(url).toContain('top=20');
+        expect(url).toContain('select=name');
+        expect(url).toContain('sort=-revenue');
+        expect(url).toContain('industry=Tech');
+    });
+});
+
+describe('QueryBuilder — offset() alias', () => {
+    it('should set offset via .offset() method', () => {
+        const q = createQuery('task')
+            .limit(10)
+            .offset(20)
+            .build();
+        expect(q.limit).toBe(10);
+        expect(q.offset).toBe(20);
+    });
+
+    it('should set offset via deprecated .skip() method', () => {
+        const q = createQuery('task')
+            .limit(10)
+            .skip(30)
+            .build();
+        expect(q.offset).toBe(30);
+    });
+});