@dxos/echo-pipeline 0.8.3 → 0.8.4-main.03d5cd7b56

package/src/query/query-planner.test.ts

@@ -1,15 +1,19 @@
+//
+// Copyright 2025 example.com
+//
+
 //
 // Copyright 2025 DXOS.org
 //
 
 import { describe, expect, test } from 'vitest';
 
-import { Filter, Query } from '@dxos/echo';
+import { Filter, Order, Query } from '@dxos/echo';
 import { type QueryAST } from '@dxos/echo-protocol';
-import { SpaceId } from '@dxos/keys';
+import { TestSchema } from '@dxos/echo/testing';
+import { DXN, SpaceId } from '@dxos/keys';
 
 import { QueryPlanner } from './query-planner';
-import { TestSchema } from '../testing';
 
 describe('QueryPlanner', () => {
   const planner = new QueryPlanner();
@@ -23,21 +27,90 @@ describe('QueryPlanner', () => {
         "steps": [
           {
             "_tag": "SelectStep",
+            "scope": {
+              "spaceIds": [
+                "B2NJDFNVZIW77OQSXUBNAD7BUMBD3G5PO",
+              ],
+            },
             "selector": {
               "_tag": "TypeSelector",
               "inverted": false,
               "typename": [
-                "dxn:type:dxos.org/type/Person:0.1.0",
+                "dxn:type:com.example.type.person:0.1.0",
               ],
             },
-            "spaces": [
-              "B2NJDFNVZIW77OQSXUBNAD7BUMBD3G5PO",
+          },
+          {
+            "_tag": "FilterDeletedStep",
+            "mode": "only-non-deleted",
+          },
+          {
+            "_tag": "FilterStep",
+            "filter": {
+              "id": undefined,
+              "props": {},
+              "type": "object",
+              "typename": "dxn:type:com.example.type.person:0.1.0",
+            },
+          },
+          {
+            "_tag": "OrderStep",
+            "order": [
+              {
+                "kind": "natural",
+              },
             ],
           },
+        ],
+      }
+    `);
+  });
+
+  test('get all people ordered by name', () => {
+    const query = Query.select(Filter.type(TestSchema.Person)).orderBy(Order.property('name', 'asc'));
+
+    const plan = planner.createPlan(withSpaceIdOptions(query.ast));
+    expect(plan).toMatchInlineSnapshot(`
+      {
+        "steps": [
+          {
+            "_tag": "SelectStep",
+            "scope": {
+              "spaceIds": [
+                "B2NJDFNVZIW77OQSXUBNAD7BUMBD3G5PO",
+              ],
+            },
+            "selector": {
+              "_tag": "TypeSelector",
+              "inverted": false,
+              "typename": [
+                "dxn:type:com.example.type.person:0.1.0",
+              ],
+            },
+          },
           {
             "_tag": "FilterDeletedStep",
             "mode": "only-non-deleted",
           },
+          {
+            "_tag": "FilterStep",
+            "filter": {
+              "id": undefined,
+              "props": {},
+              "type": "object",
+              "typename": "dxn:type:com.example.type.person:0.1.0",
+            },
+          },
+          {
+            "_tag": "OrderStep",
+            "order": [
+              {
+                "direction": "asc",
+                "kind": "property",
+                "property": "name",
+              },
+            ],
+          },
         ],
       }
     `);
@@ -52,16 +125,18 @@ describe('QueryPlanner', () => {
         "steps": [
           {
             "_tag": "SelectStep",
+            "scope": {
+              "spaceIds": [
+                "B2NJDFNVZIW77OQSXUBNAD7BUMBD3G5PO",
+              ],
+            },
             "selector": {
               "_tag": "TypeSelector",
               "inverted": false,
               "typename": [
-                "dxn:type:dxos.org/type/Person:0.1.0",
+                "dxn:type:com.example.type.person:0.1.0",
               ],
             },
-            "spaces": [
-              "B2NJDFNVZIW77OQSXUBNAD7BUMBD3G5PO",
-            ],
           },
           {
             "_tag": "FilterDeletedStep",
@@ -79,9 +154,17 @@ describe('QueryPlanner', () => {
                 },
               },
               "type": "object",
-              "typename": null,
+              "typename": "dxn:type:com.example.type.person:0.1.0",
             },
           },
+          {
+            "_tag": "OrderStep",
+            "order": [
+              {
+                "kind": "natural",
+              },
+            ],
+          },
         ],
       }
     `);
@@ -89,7 +172,9 @@ describe('QueryPlanner', () => {
 
   test('get all orgs Fred worked for since 2020', () => {
     const query = Query.select(Filter.type(TestSchema.Person, { id: '01JVS9YYT5VMVJW0GGTM1YHCCH' }))
-      .sourceOf(TestSchema.WorksFor, { since: Filter.gt('2020') })
+      .sourceOf(TestSchema.EmployedBy, {
+        since: Filter.gt<string | undefined>('2020'),
+      })
       .target();
 
     const plan = planner.createPlan(withSpaceIdOptions(query.ast));
@@ -98,15 +183,17 @@ describe('QueryPlanner', () => {
         "steps": [
           {
             "_tag": "SelectStep",
+            "scope": {
+              "spaceIds": [
+                "B2NJDFNVZIW77OQSXUBNAD7BUMBD3G5PO",
+              ],
+            },
             "selector": {
               "_tag": "IdSelector",
               "objectIds": [
                 "01JVS9YYT5VMVJW0GGTM1YHCCH",
               ],
             },
-            "spaces": [
-              "B2NJDFNVZIW77OQSXUBNAD7BUMBD3G5PO",
-            ],
           },
           {
             "_tag": "FilterDeletedStep",
@@ -118,7 +205,7 @@ describe('QueryPlanner', () => {
               "id": undefined,
               "props": {},
               "type": "object",
-              "typename": "dxn:type:dxos.org/type/Person:0.1.0",
+              "typename": "dxn:type:com.example.type.person:0.1.0",
             },
           },
           {
@@ -144,7 +231,7 @@ describe('QueryPlanner', () => {
                 },
               },
               "type": "object",
-              "typename": "dxn:type:dxos.org/type/WorksFor:0.1.0",
+              "typename": "dxn:type:com.example.type.employed-by:0.1.0",
             },
           },
           {
@@ -158,6 +245,14 @@ describe('QueryPlanner', () => {
             "_tag": "FilterDeletedStep",
             "mode": "only-non-deleted",
           },
+          {
+            "_tag": "OrderStep",
+            "order": [
+              {
+                "kind": "natural",
+              },
+            ],
+          },
         ],
       }
     `);
@@ -175,15 +270,17 @@ describe('QueryPlanner', () => {
         "steps": [
           {
             "_tag": "SelectStep",
+            "scope": {
+              "spaceIds": [
+                "B2NJDFNVZIW77OQSXUBNAD7BUMBD3G5PO",
+              ],
+            },
             "selector": {
               "_tag": "IdSelector",
               "objectIds": [
                 "01JVS9YYT7H6A6DXRN56RSHT6Z",
               ],
             },
-            "spaces": [
-              "B2NJDFNVZIW77OQSXUBNAD7BUMBD3G5PO",
-            ],
           },
           {
             "_tag": "FilterDeletedStep",
@@ -195,7 +292,7 @@ describe('QueryPlanner', () => {
               "id": undefined,
               "props": {},
               "type": "object",
-              "typename": "dxn:type:dxos.org/type/Person:0.1.0",
+              "typename": "dxn:type:com.example.type.person:0.1.0",
             },
           },
           {
@@ -215,9 +312,17 @@ describe('QueryPlanner', () => {
             "filter": {
               "props": {},
               "type": "object",
-              "typename": "dxn:type:dxos.org/type/Task:0.1.0",
+              "typename": "dxn:type:com.example.type.task:0.1.0",
             },
           },
+          {
+            "_tag": "OrderStep",
+            "order": [
+              {
+                "kind": "natural",
+              },
+            ],
+          },
         ],
       }
     `);
@@ -225,7 +330,7 @@ describe('QueryPlanner', () => {
 
   test('get all tasks for employees of Cyberdyne', () => {
     const query = Query.select(Filter.type(TestSchema.Organization, { name: 'Cyberdyne' }))
-      .targetOf(TestSchema.WorksFor)
+      .targetOf(TestSchema.EmployedBy)
       .source()
       .referencedBy(TestSchema.Task, 'assignee');
 
@@ -235,16 +340,18 @@ describe('QueryPlanner', () => {
         "steps": [
           {
             "_tag": "SelectStep",
+            "scope": {
+              "spaceIds": [
+                "B2NJDFNVZIW77OQSXUBNAD7BUMBD3G5PO",
+              ],
+            },
             "selector": {
               "_tag": "TypeSelector",
               "inverted": false,
               "typename": [
-                "dxn:type:dxos.org/type/Organization:0.1.0",
+                "dxn:type:com.example.type.organization:0.1.0",
               ],
             },
-            "spaces": [
-              "B2NJDFNVZIW77OQSXUBNAD7BUMBD3G5PO",
-            ],
           },
           {
             "_tag": "FilterDeletedStep",
@@ -262,7 +369,7 @@ describe('QueryPlanner', () => {
                 },
               },
               "type": "object",
-              "typename": null,
+              "typename": "dxn:type:com.example.type.organization:0.1.0",
             },
           },
           {
@@ -282,7 +389,7 @@ describe('QueryPlanner', () => {
               "id": undefined,
               "props": {},
               "type": "object",
-              "typename": "dxn:type:dxos.org/type/WorksFor:0.1.0",
+              "typename": "dxn:type:com.example.type.employed-by:0.1.0",
             },
           },
           {
@@ -313,9 +420,17 @@ describe('QueryPlanner', () => {
             "filter": {
               "props": {},
               "type": "object",
-              "typename": "dxn:type:dxos.org/type/Task:0.1.0",
+              "typename": "dxn:type:com.example.type.task:0.1.0",
             },
           },
+          {
+            "_tag": "OrderStep",
+            "order": [
+              {
+                "kind": "natural",
+              },
+            ],
+          },
         ],
       }
     `);
@@ -338,46 +453,92 @@ describe('QueryPlanner', () => {
                 "steps": [
                   {
                     "_tag": "SelectStep",
+                    "scope": {
+                      "spaceIds": [
+                        "B2NJDFNVZIW77OQSXUBNAD7BUMBD3G5PO",
+                      ],
+                    },
                     "selector": {
                       "_tag": "TypeSelector",
                       "inverted": false,
                       "typename": [
-                        "dxn:type:dxos.org/type/Person:0.1.0",
+                        "dxn:type:com.example.type.person:0.1.0",
                       ],
                     },
-                    "spaces": [
-                      "B2NJDFNVZIW77OQSXUBNAD7BUMBD3G5PO",
-                    ],
                   },
                   {
                     "_tag": "FilterDeletedStep",
                     "mode": "only-non-deleted",
                   },
+                  {
+                    "_tag": "FilterStep",
+                    "filter": {
+                      "id": undefined,
+                      "props": {},
+                      "type": "object",
+                      "typename": "dxn:type:com.example.type.person:0.1.0",
+                    },
+                  },
+                  {
+                    "_tag": "OrderStep",
+                    "order": [
+                      {
+                        "kind": "natural",
+                      },
+                    ],
+                  },
                 ],
               },
               {
                 "steps": [
                   {
                     "_tag": "SelectStep",
+                    "scope": {
+                      "spaceIds": [
+                        "B2NJDFNVZIW77OQSXUBNAD7BUMBD3G5PO",
+                      ],
+                    },
                     "selector": {
                       "_tag": "TypeSelector",
                       "inverted": false,
                       "typename": [
-                        "dxn:type:dxos.org/type/Organization:0.1.0",
+                        "dxn:type:com.example.type.organization:0.1.0",
                       ],
                     },
-                    "spaces": [
-                      "B2NJDFNVZIW77OQSXUBNAD7BUMBD3G5PO",
-                    ],
                   },
                   {
                     "_tag": "FilterDeletedStep",
                     "mode": "only-non-deleted",
                   },
+                  {
+                    "_tag": "FilterStep",
+                    "filter": {
+                      "id": undefined,
+                      "props": {},
+                      "type": "object",
+                      "typename": "dxn:type:com.example.type.organization:0.1.0",
+                    },
+                  },
+                  {
+                    "_tag": "OrderStep",
+                    "order": [
+                      {
+                        "kind": "natural",
+                      },
+                    ],
+                  },
                 ],
               },
             ],
           },
+          {
+            "_tag": "OrderStep",
+            "order": [
+              {
+                "kind": "natural",
+              },
+            ],
+          },
         ],
       }
     `);
@@ -386,7 +547,7 @@ describe('QueryPlanner', () => {
   test('get all people not in orgs', () => {
     const query = Query.without(
       Query.select(Filter.type(TestSchema.Person)),
-      Query.select(Filter.type(TestSchema.Person)).sourceOf(TestSchema.WorksFor).source(),
+      Query.select(Filter.type(TestSchema.Person)).sourceOf(TestSchema.EmployedBy).source(),
     );
 
     const plan = planner.createPlan(withSpaceIdOptions(query.ast));
@@ -399,16 +560,18 @@ describe('QueryPlanner', () => {
               "steps": [
                 {
                   "_tag": "SelectStep",
+                  "scope": {
+                    "spaceIds": [
+                      "B2NJDFNVZIW77OQSXUBNAD7BUMBD3G5PO",
+                    ],
+                  },
                   "selector": {
                     "_tag": "TypeSelector",
                     "inverted": false,
                     "typename": [
-                      "dxn:type:dxos.org/type/Person:0.1.0",
+                      "dxn:type:com.example.type.person:0.1.0",
                     ],
                   },
-                  "spaces": [
-                    "B2NJDFNVZIW77OQSXUBNAD7BUMBD3G5PO",
-                  ],
                 },
                 {
                   "_tag": "FilterDeletedStep",
@@ -420,7 +583,7 @@ describe('QueryPlanner', () => {
                     "id": undefined,
                     "props": {},
                     "type": "object",
-                    "typename": null,
+                    "typename": "dxn:type:com.example.type.person:0.1.0",
                   },
                 },
                 {
@@ -440,7 +603,7 @@ describe('QueryPlanner', () => {
                     "id": undefined,
                     "props": {},
                     "type": "object",
-                    "typename": "dxn:type:dxos.org/type/WorksFor:0.1.0",
+                    "typename": "dxn:type:com.example.type.employed-by:0.1.0",
                   },
                 },
                 {
@@ -454,22 +617,32 @@ describe('QueryPlanner', () => {
                   "_tag": "FilterDeletedStep",
                   "mode": "only-non-deleted",
                 },
+                {
+                  "_tag": "OrderStep",
+                  "order": [
+                    {
+                      "kind": "natural",
+                    },
+                  ],
+                },
               ],
             },
             "source": {
               "steps": [
                 {
                   "_tag": "SelectStep",
+                  "scope": {
+                    "spaceIds": [
+                      "B2NJDFNVZIW77OQSXUBNAD7BUMBD3G5PO",
+                    ],
+                  },
                   "selector": {
                     "_tag": "TypeSelector",
                     "inverted": false,
                     "typename": [
-                      "dxn:type:dxos.org/type/Person:0.1.0",
+                      "dxn:type:com.example.type.person:0.1.0",
                     ],
                   },
-                  "spaces": [
-                    "B2NJDFNVZIW77OQSXUBNAD7BUMBD3G5PO",
-                  ],
                 },
                 {
                   "_tag": "FilterDeletedStep",
@@ -481,19 +654,39 @@ describe('QueryPlanner', () => {
                     "id": undefined,
                     "props": {},
                     "type": "object",
-                    "typename": null,
+                    "typename": "dxn:type:com.example.type.person:0.1.0",
                   },
                 },
+                {
+                  "_tag": "OrderStep",
+                  "order": [
+                    {
+                      "kind": "natural",
+                    },
+                  ],
+                },
               ],
             },
           },
+          {
+            "_tag": "OrderStep",
+            "order": [
+              {
+                "kind": "natural",
+              },
+            ],
+          },
         ],
       }
     `);
   });
 
   test('get assignees of all tasks created after 2020', () => {
-    const query = Query.select(Filter.type(TestSchema.Task, { createdAt: Filter.gt('2020') })).reference('assignee');
+    const query = Query.select(
+      Filter.type(TestSchema.Task, {
+        deadline: Filter.gt<string | undefined>('2020'),
+      }),
+    ).reference('assignee');
 
     const plan = planner.createPlan(withSpaceIdOptions(query.ast));
     expect(plan).toMatchInlineSnapshot(`
@@ -501,16 +694,18 @@ describe('QueryPlanner', () => {
         "steps": [
           {
             "_tag": "SelectStep",
+            "scope": {
+              "spaceIds": [
+                "B2NJDFNVZIW77OQSXUBNAD7BUMBD3G5PO",
+              ],
+            },
             "selector": {
               "_tag": "TypeSelector",
               "inverted": false,
               "typename": [
-                "dxn:type:dxos.org/type/Task:0.1.0",
+                "dxn:type:com.example.type.task:0.1.0",
               ],
             },
-            "spaces": [
-              "B2NJDFNVZIW77OQSXUBNAD7BUMBD3G5PO",
-            ],
           },
           {
             "_tag": "FilterDeletedStep",
@@ -521,14 +716,14 @@ describe('QueryPlanner', () => {
             "filter": {
               "id": undefined,
               "props": {
-                "createdAt": {
+                "deadline": {
                   "operator": "gt",
                   "type": "compare",
                   "value": "2020",
                 },
               },
               "type": "object",
-              "typename": null,
+              "typename": "dxn:type:com.example.type.task:0.1.0",
             },
           },
           {
@@ -543,6 +738,14 @@ describe('QueryPlanner', () => {
             "_tag": "FilterDeletedStep",
             "mode": "only-non-deleted",
           },
+          {
+            "_tag": "OrderStep",
+            "order": [
+              {
+                "kind": "natural",
+              },
+            ],
+          },
         ],
       }
     `);
@@ -557,14 +760,17 @@ describe('QueryPlanner', () => {
         "steps": [
           {
             "_tag": "SelectStep",
+            "scope": {
+              "spaceIds": [
+                "B2NJDFNVZIW77OQSXUBNAD7BUMBD3G5PO",
+              ],
+            },
             "selector": {
               "_tag": "TextSelector",
               "searchKind": "full-text",
               "text": "Bill",
+              "typename": null,
             },
-            "spaces": [
-              "B2NJDFNVZIW77OQSXUBNAD7BUMBD3G5PO",
-            ],
           },
           {
             "_tag": "FilterDeletedStep",
@@ -576,9 +782,17 @@ describe('QueryPlanner', () => {
               "id": undefined,
               "props": {},
               "type": "object",
-              "typename": "dxn:type:dxos.org/type/Person:0.1.0",
+              "typename": "dxn:type:com.example.type.person:0.1.0",
             },
           },
+          {
+            "_tag": "OrderStep",
+            "order": [
+              {
+                "kind": "natural",
+              },
+            ],
+          },
         ],
       }
     `);
@@ -593,19 +807,30 @@ describe('QueryPlanner', () => {
         "steps": [
           {
             "_tag": "SelectStep",
+            "scope": {
+              "spaceIds": [
+                "B2NJDFNVZIW77OQSXUBNAD7BUMBD3G5PO",
+              ],
+            },
             "selector": {
               "_tag": "TextSelector",
               "searchKind": "vector",
               "text": "Bill",
+              "typename": null,
             },
-            "spaces": [
-              "B2NJDFNVZIW77OQSXUBNAD7BUMBD3G5PO",
-            ],
           },
           {
             "_tag": "FilterDeletedStep",
             "mode": "only-non-deleted",
           },
+          {
+            "_tag": "OrderStep",
+            "order": [
+              {
+                "kind": "natural",
+              },
+            ],
+          },
         ],
       }
     `);
@@ -620,22 +845,52 @@ describe('QueryPlanner', () => {
         "steps": [
           {
             "_tag": "SelectStep",
+            "scope": {
+              "spaceIds": [
+                "B2NJDFNVZIW77OQSXUBNAD7BUMBD3G5PO",
+              ],
+            },
             "selector": {
               "_tag": "TypeSelector",
               "inverted": false,
               "typename": [
-                "dxn:type:dxos.org/type/Organization:0.1.0",
-                "dxn:type:dxos.org/type/Person:0.1.0",
+                "dxn:type:com.example.type.organization:0.1.0",
+                "dxn:type:com.example.type.person:0.1.0",
               ],
             },
-            "spaces": [
-              "B2NJDFNVZIW77OQSXUBNAD7BUMBD3G5PO",
-            ],
           },
           {
             "_tag": "FilterDeletedStep",
             "mode": "only-non-deleted",
           },
+          {
+            "_tag": "FilterStep",
+            "filter": {
+              "filters": [
+                {
+                  "id": undefined,
+                  "props": {},
+                  "type": "object",
+                  "typename": "dxn:type:com.example.type.organization:0.1.0",
+                },
+                {
+                  "id": undefined,
+                  "props": {},
+                  "type": "object",
+                  "typename": "dxn:type:com.example.type.person:0.1.0",
+                },
+              ],
+              "type": "or",
+            },
+          },
+          {
+            "_tag": "OrderStep",
+            "order": [
+              {
+                "kind": "natural",
+              },
+            ],
+          },
         ],
       }
     `);
@@ -660,22 +915,52 @@ describe('QueryPlanner', () => {
         "steps": [
           {
             "_tag": "SelectStep",
+            "scope": {
+              "spaceIds": [
+                "B2NJDFNVZIW77OQSXUBNAD7BUMBD3G5PO",
+              ],
+            },
             "selector": {
               "_tag": "TypeSelector",
               "inverted": true,
               "typename": [
-                "dxn:type:dxos.org/type/Organization:0.1.0",
-                "dxn:type:dxos.org/type/Person:0.1.0",
+                "dxn:type:com.example.type.organization:0.1.0",
+                "dxn:type:com.example.type.person:0.1.0",
               ],
             },
-            "spaces": [
-              "B2NJDFNVZIW77OQSXUBNAD7BUMBD3G5PO",
-            ],
           },
           {
             "_tag": "FilterDeletedStep",
             "mode": "only-non-deleted",
           },
+          {
+            "_tag": "FilterStep",
+            "filter": {
+              "filters": [
+                {
+                  "id": undefined,
+                  "props": {},
+                  "type": "object",
+                  "typename": "dxn:type:com.example.type.organization:0.1.0",
+                },
+                {
+                  "id": undefined,
+                  "props": {},
+                  "type": "object",
+                  "typename": "dxn:type:com.example.type.person:0.1.0",
+                },
+              ],
+              "type": "or",
+            },
+          },
+          {
+            "_tag": "OrderStep",
+            "order": [
+              {
+                "kind": "natural",
+              },
+            ],
+          },
         ],
       }
     `);
@@ -690,33 +975,660 @@ describe('QueryPlanner', () => {
         "steps": [
           {
             "_tag": "SelectStep",
+            "scope": {
+              "spaceIds": [
+                "B2NJDFNVZIW77OQSXUBNAD7BUMBD3G5PO",
+              ],
+            },
             "selector": {
               "_tag": "TypeSelector",
               "inverted": false,
               "typename": [
-                "dxn:type:dxos.org/type/Task:0.1.0",
+                "dxn:type:com.example.type.task:0.1.0",
               ],
             },
-            "spaces": [
-              "B2NJDFNVZIW77OQSXUBNAD7BUMBD3G5PO",
-            ],
           },
           {
             "_tag": "FilterDeletedStep",
             "mode": "only-deleted",
           },
+          {
+            "_tag": "FilterStep",
+            "filter": {
+              "id": undefined,
+              "props": {},
+              "type": "object",
+              "typename": "dxn:type:com.example.type.task:0.1.0",
+            },
+          },
+          {
+            "_tag": "OrderStep",
+            "order": [
+              {
+                "kind": "natural",
+              },
+            ],
+          },
+        ],
+      }
+    `);
+  });
+
+  test('select items from a specific queue', () => {
+    const query = Query.select(Filter.type(TestSchema.Task)).from({ queues: [QUEUE_DXN] });
+
+    const plan = planner.createPlan(query.ast);
+    expect(plan).toMatchInlineSnapshot(`
+      {
+        "steps": [
+          {
+            "_tag": "SelectStep",
+            "scope": {
+              "queues": [
+                "dxn:queue:data:B2NJDFNVZIW77OQSXUBNAD7BUMBD3G5PO:01JJRA86VK4H1TEB6QQVSWXP0E",
+              ],
+            },
+            "selector": {
+              "_tag": "TypeSelector",
+              "inverted": false,
+              "typename": [
+                "dxn:type:com.example.type.task:0.1.0",
+              ],
+            },
+          },
+          {
+            "_tag": "FilterDeletedStep",
+            "mode": "only-non-deleted",
+          },
+          {
+            "_tag": "FilterStep",
+            "filter": {
+              "id": undefined,
+              "props": {},
+              "type": "object",
+              "typename": "dxn:type:com.example.type.task:0.1.0",
+            },
+          },
+          {
+            "_tag": "OrderStep",
+            "order": [
+              {
+                "kind": "natural",
+              },
+            ],
+          },
         ],
       }
     `);
   });
+
+  test('select items from all queues in a space', () => {
+    const query = Query.select(Filter.type(TestSchema.Task)).from({
+      spaceIds: [SPACE_ID],
+      allQueuesFromSpaces: true,
+    });
+
+    const plan = planner.createPlan(query.ast);
+    expect(plan).toMatchInlineSnapshot(`
+      {
+        "steps": [
+          {
+            "_tag": "SelectStep",
+            "scope": {
+              "allQueuesFromSpaces": true,
+              "spaceIds": [
+                "B2NJDFNVZIW77OQSXUBNAD7BUMBD3G5PO",
+              ],
+            },
+            "selector": {
+              "_tag": "TypeSelector",
+              "inverted": false,
+              "typename": [
+                "dxn:type:com.example.type.task:0.1.0",
+              ],
+            },
+          },
+          {
+            "_tag": "FilterDeletedStep",
+            "mode": "only-non-deleted",
+          },
+          {
+            "_tag": "FilterStep",
+            "filter": {
+              "id": undefined,
+              "props": {},
+              "type": "object",
+              "typename": "dxn:type:com.example.type.task:0.1.0",
+            },
+          },
+          {
+            "_tag": "OrderStep",
+            "order": [
+              {
+                "kind": "natural",
+              },
+            ],
+          },
+        ],
+      }
+    `);
+  });
+
+  test('limit results', () => {
+    const query = Query.select(Filter.type(TestSchema.Task)).limit(10);
+
+    const plan = planner.createPlan(withSpaceIdOptions(query.ast));
+    expect(plan).toMatchInlineSnapshot(`
+      {
+        "steps": [
+          {
+            "_tag": "SelectStep",
+            "limit": 10,
+            "scope": {
+              "spaceIds": [
+                "B2NJDFNVZIW77OQSXUBNAD7BUMBD3G5PO",
+              ],
+            },
+            "selector": {
+              "_tag": "TypeSelector",
+              "inverted": false,
+              "typename": [
+                "dxn:type:com.example.type.task:0.1.0",
+              ],
+            },
+          },
+          {
+            "_tag": "FilterDeletedStep",
+            "mode": "only-non-deleted",
+          },
+          {
+            "_tag": "FilterStep",
+            "filter": {
+              "id": undefined,
+              "props": {},
+              "type": "object",
+              "typename": "dxn:type:com.example.type.task:0.1.0",
+            },
+          },
+          {
+            "_tag": "OrderStep",
+            "limit": 10,
+            "order": [
+              {
+                "kind": "natural",
+              },
+            ],
+          },
+        ],
+      }
+    `);
+  });
+
+  test('ordered and limited results', () => {
+    const query = Query.select(Filter.type(TestSchema.Task)).orderBy(Order.property('title', 'asc')).limit(10);
+
+    const plan = planner.createPlan(withSpaceIdOptions(query.ast));
+    expect(plan).toMatchInlineSnapshot(`
+      {
+        "steps": [
+          {
+            "_tag": "SelectStep",
+            "limit": 10,
+            "scope": {
+              "spaceIds": [
+                "B2NJDFNVZIW77OQSXUBNAD7BUMBD3G5PO",
+              ],
+            },
+            "selector": {
+              "_tag": "TypeSelector",
+              "inverted": false,
+              "typename": [
+                "dxn:type:com.example.type.task:0.1.0",
+              ],
+            },
+          },
+          {
+            "_tag": "FilterDeletedStep",
+            "mode": "only-non-deleted",
+          },
+          {
+            "_tag": "FilterStep",
+            "filter": {
+              "id": undefined,
+              "props": {},
+              "type": "object",
+              "typename": "dxn:type:com.example.type.task:0.1.0",
+            },
+          },
+          {
+            "_tag": "OrderStep",
+            "limit": 10,
+            "order": [
+              {
+                "direction": "asc",
+                "kind": "property",
+                "property": "title",
+              },
+            ],
+          },
+        ],
+      }
+    `);
+  });
+
+  test('union of limited queries', () => {
+    const query = Query.all(
+      Query.select(Filter.type(TestSchema.Person)).limit(5),
+      Query.select(Filter.type(TestSchema.Organization)).limit(5),
+    );
+
+    const plan = planner.createPlan(withSpaceIdOptions(query.ast));
+    expect(plan).toMatchInlineSnapshot(`
+      {
+        "steps": [
+          {
+            "_tag": "UnionStep",
+            "plans": [
+              {
+                "steps": [
+                  {
+                    "_tag": "SelectStep",
+                    "limit": 5,
+                    "scope": {
+                      "spaceIds": [
+                        "B2NJDFNVZIW77OQSXUBNAD7BUMBD3G5PO",
+                      ],
+                    },
+                    "selector": {
+                      "_tag": "TypeSelector",
+                      "inverted": false,
+                      "typename": [
+                        "dxn:type:com.example.type.person:0.1.0",
+                      ],
+                    },
+                  },
+                  {
+                    "_tag": "FilterDeletedStep",
+                    "mode": "only-non-deleted",
+                  },
+                  {
+                    "_tag": "FilterStep",
+                    "filter": {
+                      "id": undefined,
+                      "props": {},
+                      "type": "object",
+                      "typename": "dxn:type:com.example.type.person:0.1.0",
+                    },
+                  },
+                  {
+                    "_tag": "OrderStep",
+                    "limit": 5,
+                    "order": [
+                      {
+                        "kind": "natural",
+                      },
+                    ],
+                  },
+                ],
+              },
+              {
+                "steps": [
+                  {
+                    "_tag": "SelectStep",
+                    "limit": 5,
+                    "scope": {
+                      "spaceIds": [
+                        "B2NJDFNVZIW77OQSXUBNAD7BUMBD3G5PO",
+                      ],
+                    },
+                    "selector": {
+                      "_tag": "TypeSelector",
+                      "inverted": false,
+                      "typename": [
+                        "dxn:type:com.example.type.organization:0.1.0",
+                      ],
+                    },
+                  },
+                  {
+                    "_tag": "FilterDeletedStep",
+                    "mode": "only-non-deleted",
+                  },
+                  {
+                    "_tag": "FilterStep",
+                    "filter": {
+                      "id": undefined,
+                      "props": {},
+                      "type": "object",
+                      "typename": "dxn:type:com.example.type.organization:0.1.0",
+                    },
+                  },
+                  {
+                    "_tag": "OrderStep",
+                    "limit": 5,
+                    "order": [
+                      {
+                        "kind": "natural",
+                      },
+                    ],
+                  },
+                ],
+              },
+            ],
+          },
+          {
+            "_tag": "OrderStep",
+            "order": [
+              {
+                "kind": "natural",
+              },
+            ],
+          },
+        ],
+      }
+    `);
+  });
+  test('throws when query has no from clause', () => {
+    const query = Query.select(Filter.type(TestSchema.Person));
+    expect(() => planner.createPlan(query.ast)).toThrow('Query must be scoped with a from() clause');
+  });
+
+  test('from all accessible spaces', () => {
+    const query = Query.select(Filter.type(TestSchema.Person)).from('all-accessible-spaces');
+
+    const plan = planner.createPlan(query.ast);
+    expect(plan).toMatchInlineSnapshot(`
+      {
+        "steps": [
+          {
+            "_tag": "SelectStep",
+            "scope": {},
+            "selector": {
+              "_tag": "TypeSelector",
+              "inverted": false,
+              "typename": [
+                "dxn:type:com.example.type.person:0.1.0",
+              ],
+            },
+          },
+          {
+            "_tag": "FilterDeletedStep",
+            "mode": "only-non-deleted",
+          },
+          {
+            "_tag": "FilterStep",
+            "filter": {
+              "id": undefined,
+              "props": {},
+              "type": "object",
+              "typename": "dxn:type:com.example.type.person:0.1.0",
+            },
+          },
+          {
+            "_tag": "OrderStep",
+            "order": [
+              {
+                "kind": "natural",
+              },
+            ],
+          },
+        ],
+      }
+    `);
+  });
+
+  test('from all accessible spaces with feeds', () => {
+    const query = Query.select(Filter.type(TestSchema.Person)).from('all-accessible-spaces', {
+      includeFeeds: true,
+    });
+
+    const plan = planner.createPlan(query.ast);
+    expect(plan).toMatchInlineSnapshot(`
+      {
+        "steps": [
+          {
+            "_tag": "SelectStep",
+            "scope": {
+              "allQueuesFromSpaces": true,
+            },
+            "selector": {
+              "_tag": "TypeSelector",
+              "inverted": false,
+              "typename": [
+                "dxn:type:com.example.type.person:0.1.0",
+              ],
+            },
+          },
+          {
+            "_tag": "FilterDeletedStep",
+            "mode": "only-non-deleted",
+          },
+          {
+            "_tag": "FilterStep",
+            "filter": {
+              "id": undefined,
+              "props": {},
+              "type": "object",
+              "typename": "dxn:type:com.example.type.person:0.1.0",
+            },
+          },
+          {
+            "_tag": "OrderStep",
+            "order": [
+              {
+                "kind": "natural",
+              },
+            ],
+          },
+        ],
+      }
+    `);
+  });
+
+  test('from specific feed via queues scope', () => {
+    const query = Query.select(Filter.type(TestSchema.Task)).from({ queues: [QUEUE_DXN] });
+
+    const plan = planner.createPlan(query.ast);
+    expect(plan.steps[0]).toMatchObject({
+      _tag: 'SelectStep',
+      scope: { queues: [QUEUE_DXN] },
+    });
+  });
+
+  test('from specific space with feeds', () => {
+    const query = Query.select(Filter.type(TestSchema.Person)).from({
+      spaceIds: [SPACE_ID],
+      allQueuesFromSpaces: true,
+    });
+
+    const plan = planner.createPlan(query.ast);
+    expect(plan.steps[0]).toMatchObject({
+      _tag: 'SelectStep',
+      scope: { spaceIds: [SPACE_ID], allQueuesFromSpaces: true },
+    });
+  });
+
+  test('from subquery flattens into filter on subquery results', () => {
+    // Query.select(Filter.props({ name: 'Alice' })).from(Query.select(Filter.type(Person)))
+    // Should flatten to: select type Person -> filter props { name: 'Alice' }.
+    const subquery = Query.select(Filter.type(TestSchema.Person)).from({ spaceIds: [SPACE_ID] });
+    const query = Query.select(Filter.props<TestSchema.Person>({ name: 'Alice' })).from(subquery);
+
+    const plan = planner.createPlan(query.ast);
+    expect(plan).toMatchInlineSnapshot(`
+      {
+        "steps": [
+          {
+            "_tag": "SelectStep",
+            "scope": {
+              "spaceIds": [
+                "B2NJDFNVZIW77OQSXUBNAD7BUMBD3G5PO",
+              ],
+            },
+            "selector": {
+              "_tag": "TypeSelector",
+              "inverted": false,
+              "typename": [
+                "dxn:type:com.example.type.person:0.1.0",
+              ],
+            },
+          },
+          {
+            "_tag": "FilterDeletedStep",
+            "mode": "only-non-deleted",
+          },
+          {
+            "_tag": "FilterStep",
+            "filter": {
+              "id": undefined,
+              "props": {},
+              "type": "object",
+              "typename": "dxn:type:com.example.type.person:0.1.0",
+            },
+          },
+          {
+            "_tag": "FilterStep",
+            "filter": {
+              "id": undefined,
+              "props": {
+                "name": {
+                  "operator": "eq",
+                  "type": "compare",
+                  "value": "Alice",
+                },
+              },
+              "type": "object",
+              "typename": null,
+            },
+          },
+          {
+            "_tag": "OrderStep",
+            "order": [
+              {
+                "kind": "natural",
+              },
+            ],
+          },
+        ],
+      }
+    `);
+  });
+
+  test('from subquery with reference traversal', () => {
+    // Query.select(Filter.type(Task)).reference('assignee').from(subquery)
+    // The reference traversal wraps the outer select; flattening should still work.
+    const subquery = Query.select(Filter.type(TestSchema.Person)).from({ spaceIds: [SPACE_ID] });
+    const query = Query.select(Filter.type(TestSchema.Task)).reference('assignee').from(subquery);
+
+    const plan = planner.createPlan(query.ast);
+    expect(plan).toMatchInlineSnapshot(`
+      {
+        "steps": [
+          {
+            "_tag": "SelectStep",
+            "scope": {
+              "spaceIds": [
+                "B2NJDFNVZIW77OQSXUBNAD7BUMBD3G5PO",
+              ],
+            },
+            "selector": {
+              "_tag": "TypeSelector",
+              "inverted": false,
+              "typename": [
+                "dxn:type:com.example.type.person:0.1.0",
+              ],
+            },
+          },
+          {
+            "_tag": "FilterDeletedStep",
+            "mode": "only-non-deleted",
+          },
+          {
+            "_tag": "FilterStep",
+            "filter": {
+              "id": undefined,
+              "props": {},
+              "type": "object",
+              "typename": "dxn:type:com.example.type.person:0.1.0",
+            },
+          },
+          {
+            "_tag": "FilterStep",
+            "filter": {
+              "id": undefined,
+              "props": {},
+              "type": "object",
+              "typename": "dxn:type:com.example.type.task:0.1.0",
+            },
+          },
+          {
+            "_tag": "TraverseStep",
+            "traversal": {
+              "_tag": "ReferenceTraversal",
+              "direction": "outgoing",
+              "property": "assignee",
+            },
+          },
+          {
+            "_tag": "FilterDeletedStep",
+            "mode": "only-non-deleted",
+          },
+          {
+            "_tag": "OrderStep",
+            "order": [
+              {
+                "kind": "natural",
+              },
+            ],
+          },
+        ],
+      }
+    `);
+  });
+
+  test('from subquery inherits scope from inner query', () => {
+    // The outer query has no scope — the subquery carries the scope.
+    const subquery = Query.select(Filter.type(TestSchema.Task)).from({ spaceIds: [SPACE_ID] });
+    const query = Query.select(Filter.props<TestSchema.Task>({ title: 'Test' })).from(subquery);
+
+    const plan = planner.createPlan(query.ast);
+    const selectStep = plan.steps.find((step) => step._tag === 'SelectStep');
+    expect(selectStep).toMatchObject({
+      _tag: 'SelectStep',
+      scope: { spaceIds: [SPACE_ID] },
+    });
+  });
+
+  test('and(type, compare, timestamp) throws descriptive error about timestamp limitation', () => {
+    const query = Query.select(
+      Filter.and(
+        Filter.type(TestSchema.Person),
+        Filter.type(TestSchema.Person, { name: 'Alice' }),
+        Filter.updated({ after: Date.now() }),
+      ),
+    );
+    expect(() => planner.createPlan(withSpaceIdOptions(query.ast))).toThrow(/[Tt]imestamp/);
+  });
+
+  test('and(type, timestamp) produces valid plan', () => {
+    const query = Query.select(Filter.and(Filter.type(TestSchema.Person), Filter.updated({ after: Date.now() })));
+    const plan = planner.createPlan(withSpaceIdOptions(query.ast));
+    const hasTimestampFilter = plan.steps.some(
+      (step) => step._tag === 'FilterStep' && JSON.stringify(step.filter).includes('timestamp'),
+    );
+    expect(hasTimestampFilter).toBe(true);
+  });
 });
 
 const SPACE_ID = SpaceId.make('B2NJDFNVZIW77OQSXUBNAD7BUMBD3G5PO'); // Stable id for inline snapshots.
+const QUEUE_DXN = DXN.parse('dxn:queue:data:B2NJDFNVZIW77OQSXUBNAD7BUMBD3G5PO:01JJRA86VK4H1TEB6QQVSWXP0E').toString(); // Stable queue DXN for inline snapshots.
 
 const withSpaceIdOptions = (query: QueryAST.Query): QueryAST.Query => ({
-  type: 'options',
+  type: 'from',
   query,
-  options: {
-    spaceIds: [SPACE_ID],
+  from: {
+    _tag: 'scope',
+    scope: {
+      spaceIds: [SPACE_ID],
+    },
   },
 });