fix: normalize top→limit in protocol, add changeset, fix studio integration tests

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>
Agent-Logs-Url: https://github.com/objectstack-ai/spec/sessions/4edae9dd-77f3-4fb8-b504-51c1ee902836

Author: Copilot

.changeset/queryast-convergence.md

@@ -0,0 +1,20 @@
+---
+"@objectstack/spec": minor
+"@objectstack/core": minor
+"@objectstack/objectql": minor
+"@objectstack/client": minor
+"@objectstack/runtime": patch
+"@objectstack/plugin-auth": patch
+---
+
+Deprecate DataEngineQueryOptions in favor of QueryAST-aligned EngineQueryOptions.
+
+Engine, Protocol, and Client now use standard QueryAST parameter names:
+- `filter` → `where`
+- `select` → `fields`
+- `sort` → `orderBy`
+- `skip` → `offset`
+- `populate` → `expand`
+- `top` → `limit`
+
+The old DataEngine* schemas and types are preserved with `@deprecated` markers for backward compatibility.

packages/objectql/src/engine.ts

@@ -752,6 +752,11 @@ export class ObjectQL implements IDataEngine {
     const ast: QueryAST = { object, ...query };
     // Remove context from the AST — it's not a driver concern
     delete (ast as any).context;
+    // Normalize OData `top` alias → standard `limit`
+    if ((ast as any).top != null && ast.limit == null) {
+      ast.limit = (ast as any).top;
+    }
+    delete (ast as any).top;
 
     const opCtx: OperationContext = {
       object,
@@ -799,8 +804,9 @@ export class ObjectQL implements IDataEngine {
     this.logger.debug('FindOne operation', { objectName });
     const driver = this.getDriver(objectName);
     const ast: QueryAST = { object: objectName, ...query, limit: 1 };
-    // Remove context from the AST — it's not a driver concern
+    // Remove context and top alias from the AST
     delete (ast as any).context;
+    delete (ast as any).top;
 
     const opCtx: OperationContext = {
       object: objectName,

packages/objectql/src/protocol-data.test.ts

@@ -118,7 +118,7 @@ describe('ObjectStackProtocolImplementation - Data Operations', () => {
             expect(mockEngine.find).toHaveBeenCalledWith(
                 'task',
                 expect.objectContaining({
-                    top: 10,
+                    limit: 10,
                     offset: 20,
                 }),
             );

packages/objectql/src/protocol.ts

@@ -283,10 +283,15 @@ export class ObjectStackProtocolImplementation implements ObjectStackProtocol {
         // Normalize legacy params → QueryAST standard (where/fields/orderBy/offset/expand)
         // ====================================================================
 
-        // Numeric fields
-        if (options.top != null) options.top = Number(options.top);
-        if (options.skip != null) options.offset = Number(options.skip);
-        delete options.skip;
+        // Numeric fields — normalize top → limit, skip → offset
+        if (options.top != null) {
+            options.limit = Number(options.top);
+            delete options.top;
+        }
+        if (options.skip != null) {
+            options.offset = Number(options.skip);
+            delete options.skip;
+        }
         if (options.limit != null) options.limit = Number(options.limit);
         if (options.offset != null) options.offset = Number(options.offset);