@dxos/echo-pipeline 0.8.4-main.ae835ea → 0.8.4-main.bc2380dfbc

package/src/query/query-executor.ts

@@ -3,31 +3,39 @@
 //
 
 import type { AutomergeUrl, DocumentId } from '@automerge/automerge-repo';
-import * as Match from 'effect/Match';
-import * as Predicate from 'effect/Predicate';
-
-import { Context, ContextDisposedError, LifecycleState, Resource } from '@dxos/context';
-import { DatabaseDirectory, ObjectStructure, type QueryAST, isEncodedReference } from '@dxos/echo-protocol';
-import { EscapedPropPath, type FindResult, type Indexer } from '@dxos/indexing';
+import type * as SqlClient from '@effect/sql/SqlClient';
+import type * as Effect from 'effect/Effect';
+import * as Runtime from 'effect/Runtime';
+
+import { ContextDisposedError, LifecycleState, Resource } from '@dxos/context';
+import { type Obj, Query } from '@dxos/echo';
+import {
+  DatabaseDirectory,
+  EncodedReference,
+  type ObjectPropPath,
+  ObjectStructure,
+  type QueryAST,
+  isEncodedReference,
+} from '@dxos/echo-protocol';
+import { ATTR_PARENT, ATTR_RELATION_SOURCE, ATTR_RELATION_TARGET } from '@dxos/echo/internal';
+import { type RuntimeProvider, runAndForwardErrors, unwrapExit } from '@dxos/effect';
+import { EscapedPropPath, type IndexEngine, type ObjectMeta, type ReverseRef } from '@dxos/index-core';
 import { invariant } from '@dxos/invariant';
-import { DXN, type ObjectId, PublicKey, type SpaceId } from '@dxos/keys';
+import { DXN, type ObjectId, type SpaceId } from '@dxos/keys';
 import { log } from '@dxos/log';
-import { objectPointerCodec } from '@dxos/protocols';
 import { type QueryReactivity, type QueryResult } from '@dxos/protocols/proto/dxos/echo/query';
-import { getDeep, isNonNullable } from '@dxos/util';
+import { compositeKey, getDeep, isNonNullable } from '@dxos/util';
 
 import type { AutomergeHost } from '../automerge';
-import { createIdFromSpaceKey } from '../common';
-import type { SpaceStateManager } from '../db-host';
-import { filterMatchObject } from '../filter';
-
+import type { InvalidationHint, SpaceStateManager } from '../db-host';
+import { filterMatchObject, filterMatchObjectJSON } from '../filter';
+import { QueryError } from './errors';
 import type { QueryPlan } from './plan';
 import { QueryPlanner } from './query-planner';
 
-const isNullable: Predicate.Refinement<unknown, null | undefined> = Predicate.isNullable;
-
 type QueryExecutorOptions = {
-  indexer: Indexer;
+  indexEngine: IndexEngine;
+  runtime: RuntimeProvider.RuntimeProvider<SqlClient.SqlClient>;
   automergeHost: AutomergeHost;
   spaceStateManager: SpaceStateManager;
 
@@ -48,11 +56,84 @@ type QueryExecutionResult = {
  */
 type QueryItem = {
   objectId: ObjectId;
-  documentId: DocumentId;
+
   spaceId: SpaceId;
-  doc: ObjectStructure;
+  queueId: ObjectId | null;
+  queueNamespace: string | null;
+
+  // For objects from automerge documents.
+  documentId: DocumentId | null;
+
+  // For objects from automerge documents.
+  doc: ObjectStructure | null;
+
+  // For objects from queues.
+  data: Obj.JSON | null;
+
+  /**
+   * Relevance rank for this item.
+   * Higher values indicate better matches for FTS/vector searches.
+   * Defaults to 1 for non-ranked queries (predicate matches).
+   */
+  rank: number;
 };
 
+const QueryItem = Object.freeze({
+  /**
+   * Checks if the item is deleted.
+   * Only applies to this item, not its parents.
+   */
+  isDeleted: (item: QueryItem) => {
+    if (item.doc) {
+      return ObjectStructure.isDeleted(item.doc);
+    } else if (item.data) {
+      return item.data['@deleted'] === true;
+    } else {
+      throw new Error('Invalid query item');
+    }
+  },
+
+  getProperty: (item: QueryItem, property: ObjectPropPath) => {
+    if (item.doc) {
+      return getDeep(item.doc.data, property);
+    } else if (item.data) {
+      return getDeep(item.data, property);
+    } else {
+      throw new Error('Invalid query item');
+    }
+  },
+
+  getParent: (item: QueryItem): DXN.String | undefined => {
+    if (item.doc) {
+      return ObjectStructure.getParent(item.doc)?.['/'] as DXN.String | undefined;
+    } else if (item.data) {
+      return item.data[ATTR_PARENT] as DXN.String;
+    } else {
+      throw new Error('Invalid query item');
+    }
+  },
+
+  getRelationSource: (item: QueryItem): DXN.String | undefined => {
+    if (item.doc) {
+      return ObjectStructure.getRelationSource(item.doc)?.['/'] as DXN.String | undefined;
+    } else if (item.data) {
+      return item.data[ATTR_RELATION_SOURCE] as DXN.String;
+    } else {
+      throw new Error('Invalid query item');
+    }
+  },
+
+  getRelationTarget: (item: QueryItem): DXN.String | undefined => {
+    if (item.doc) {
+      return ObjectStructure.getRelationTarget(item.doc)?.['/'] as DXN.String | undefined;
+    } else if (item.data) {
+      return item.data[ATTR_RELATION_TARGET] as DXN.String;
+    } else {
+      throw new Error('Invalid query item');
+    }
+  },
+});
+
 /**
  * Recursive data structure that represents the execution trace of a query.
  */
@@ -135,10 +216,167 @@ type StepExecutionResult = {
   trace: ExecutionTrace;
 };
 
-const TRACE_QUERY_EXECUTION = false;
+declare global {
+  interface ImportMeta {
+    env: ImportMetaEnv;
+  }
+
+  interface ImportMetaEnv {
+    DX_TRACE_QUERY_EXECUTION: string;
+  }
+}
+
+const TRACE_QUERY_EXECUTION = !!import.meta.env?.DX_TRACE_QUERY_EXECUTION;
+
+const MAX_DEPTH_FOR_DELETION_TRACING = 10;
+const MAX_DEPTH_FOR_CHILD_OF_TRACING = 10;
 
 /**
- * Executes query plans against the Indexer and AutomergeHost.
+ * Cached scope constraints extracted from a query plan.
+ * Used to quickly determine whether an invalidation hint can affect this query.
+ *
+ * A null dimension means the query is unconstrained on that dimension (matches any value).
+ */
+type QueryScopes = {
+  /**
+   * False for text-search, traversal, union, set-difference, or child-of queries.
+   * When false, matchesHint always returns true (conservative: always re-execute).
+   */
+  isSimple: boolean;
+  spaceIds: Set<SpaceId> | null;
+  queueIds: Set<ObjectId> | null;
+  typenames: Set<string> | null;
+  objectIds: Set<ObjectId> | null;
+};
+
+const extractScopes = (plan: QueryPlan.Plan): QueryScopes => {
+  const scopes: QueryScopes = {
+    isSimple: true,
+    spaceIds: null,
+    queueIds: null,
+    typenames: null,
+    objectIds: null,
+  };
+
+  for (const step of plan.steps) {
+    switch (step._tag) {
+      case 'SelectStep': {
+        // Extract spaceIds from scope.
+        if (step.scope.spaceIds && step.scope.spaceIds.length > 0) {
+          if (!scopes.spaceIds) {
+            scopes.spaceIds = new Set();
+          }
+          for (const spaceId of step.scope.spaceIds) {
+            scopes.spaceIds.add(spaceId as SpaceId);
+          }
+        }
+
+        // Extract queueIds from explicit feed DXNs (queue-kinded) and derive spaceIds from them.
+        if (step.scope.feeds && step.scope.feeds.length > 0 && !step.scope.allFeedsFromSpaces) {
+          let parseFailed = false;
+          const derivedQueueIds = new Set<ObjectId>();
+          const derivedSpaceIds = new Set<SpaceId>();
+          for (const queueDxnStr of step.scope.feeds as DXN.String[]) {
+            try {
+              const queueDXN = DXN.parse(queueDxnStr).asQueueDXN();
+              if (queueDXN) {
+                derivedQueueIds.add(queueDXN.queueId as ObjectId);
+                derivedSpaceIds.add(queueDXN.spaceId as SpaceId);
+              }
+            } catch {
+              parseFailed = true;
+            }
+          }
+
+          if (!parseFailed) {
+            if (derivedQueueIds.size > 0) {
+              scopes.queueIds ??= new Set<ObjectId>();
+              for (const id of derivedQueueIds) {
+                scopes.queueIds.add(id);
+              }
+            }
+            if (derivedSpaceIds.size > 0) {
+              scopes.spaceIds ??= new Set<SpaceId>();
+              for (const id of derivedSpaceIds) {
+                // Derive spaceId from the queue DXN so space-scoped hints can skip this query.
+                scopes.spaceIds.add(id);
+              }
+            }
+          }
+          // On any parse error, leave queue-derived dimensions unconstrained.
+        }
+
+        // Extract typename / objectId constraints from selector.
+        switch (step.selector._tag) {
+          case 'TypeSelector': {
+            if (step.selector.inverted) {
+              // Inverted type selectors come from Filter.not — mark as non-simple.
+              scopes.isSimple = false;
+            } else {
+              if (!scopes.typenames) {
+                scopes.typenames = new Set();
+              }
+              for (const typename of step.selector.typename) {
+                scopes.typenames.add(typename as string);
+              }
+            }
+            break;
+          }
+          case 'IdSelector': {
+            if (!scopes.objectIds) {
+              scopes.objectIds = new Set();
+            }
+            for (const id of step.selector.objectIds) {
+              scopes.objectIds.add(id);
+            }
+            break;
+          }
+          case 'TextSelector': {
+            scopes.isSimple = false;
+            break;
+          }
+          default:
+            // WildcardSelector, TimestampSelector — no type/id constraint.
+            break;
+        }
+        break;
+      }
+      case 'FilterStep': {
+        // child-of filters require transitive parent traversal which can't be hinted.
+        if (step.filter.type === 'child-of') {
+          scopes.isSimple = false;
+        }
+        break;
+      }
+      case 'TraverseStep':
+      case 'UnionStep':
+      case 'SetDifferenceStep':
+        scopes.isSimple = false;
+        break;
+      default:
+        // ClearWorkingSetStep, FilterDeletedStep, OrderStep, LimitStep are fine.
+        break;
+    }
+  }
+
+  return scopes;
+};
+
+const setsOverlap = <T>(a: ReadonlySet<T>, b: ReadonlySet<T>): boolean => {
+  const [smaller, larger]: [ReadonlySet<T>, ReadonlySet<T>] = a.size <= b.size ? [a, b] : [b, a];
+  for (const item of smaller) {
+    if (larger.has(item)) {
+      return true;
+    }
+  }
+  return false;
+};
+
+const overlapsOrUnconstrained = <T>(hintSet: ReadonlySet<T> | undefined, scopeSet: Set<T> | null): boolean =>
+  hintSet === undefined || scopeSet === null || setsOverlap(hintSet, scopeSet);
+
+/**
+ * Executes query plans against the IndexEngine and AutomergeHost.
  *
  * The QueryExecutor is responsible for:
  * - Executing query plans step by step
@@ -148,7 +386,8 @@ const TRACE_QUERY_EXECUTION = false;
  * - Handling different types of query operations (select, filter, traverse, etc.)
  */
 export class QueryExecutor extends Resource {
-  private readonly _indexer: Indexer;
+  private readonly _indexEngine: IndexEngine;
+  private readonly _runtime: RuntimeProvider.RuntimeProvider<SqlClient.SqlClient>;
   private readonly _automergeHost: AutomergeHost;
   private readonly _spaceStateManager: SpaceStateManager;
   /**
@@ -160,13 +399,15 @@ export class QueryExecutor extends Resource {
   private readonly _reactivity: QueryReactivity;
 
   private _plan: QueryPlan.Plan;
+  #scopes: QueryScopes;
   private _trace: ExecutionTrace = ExecutionTrace.makeEmpty();
   private _lastResultSet: QueryItem[] = [];
 
   constructor(options: QueryExecutorOptions) {
     super();
 
-    this._indexer = options.indexer;
+    this._indexEngine = options.indexEngine;
+    this._runtime = options.runtime;
     this._automergeHost = options.automergeHost;
     this._spaceStateManager = options.spaceStateManager;
 
@@ -176,6 +417,11 @@ export class QueryExecutor extends Resource {
 
     const queryPlanner = new QueryPlanner();
     this._plan = queryPlanner.createPlan(this._query);
+    this.#scopes = extractScopes(this._plan);
+  }
+
+  get queryId(): string {
+    return this._id;
   }
 
   get query(): QueryAST.Query {
@@ -190,31 +436,54 @@ export class QueryExecutor extends Resource {
     return this._trace;
   }
 
-  protected override async _open(ctx: Context): Promise<void> {}
-
-  protected override async _close(ctx: Context): Promise<void> {}
-
   getResults(): QueryResult[] {
     return this._lastResultSet.map(
       (item): QueryResult => ({
         id: item.objectId,
-        documentId: item.documentId,
+        documentId: item.documentId ?? undefined,
+        queueId: item.queueId ?? undefined,
+        queueNamespace: item.queueNamespace ?? undefined,
         spaceId: item.spaceId,
 
-        // TODO(dmaretskyi): Plumb through the rank.
-        rank: 0,
+        rank: item.rank,
+
+        documentJson: item.doc ? JSON.stringify(item.doc) : item.data ? JSON.stringify(item.data) : undefined,
       }),
     );
   }
 
+  /**
+   * Returns true if the given invalidation hint could affect this query's result set.
+   * When false, the query can safely be skipped for this invalidation cycle.
+   *
+   * Conservative: returns true for complex queries (traversals, text-search, unions) and
+   * for any dimension where either the hint or the query is unconstrained.
+   */
+  matchesHint(hint: InvalidationHint): boolean {
+    if (!this.#scopes.isSimple) {
+      return true;
+    }
+    return (
+      overlapsOrUnconstrained(hint.spaceIds, this.#scopes.spaceIds) &&
+      overlapsOrUnconstrained(hint.queueIds, this.#scopes.queueIds) &&
+      overlapsOrUnconstrained(hint.typenames, this.#scopes.typenames) &&
+      overlapsOrUnconstrained(hint.objectIds, this.#scopes.objectIds)
+    );
+  }
+
   async execQuery(): Promise<QueryExecutionResult> {
     invariant(this._lifecycleState === LifecycleState.OPEN);
 
+    log('exec query', {
+      queryId: this._id,
+      query: Query.pretty(Query.fromAst(this._query)),
+    });
+
     const prevResultSet = this._lastResultSet;
     const { workingSet, trace } = await this._execPlan(this._plan, []);
     this._lastResultSet = workingSet;
     trace.name = 'Root';
-    trace.details = JSON.stringify({ id: this._id });
+    trace.details = JSON.stringify({ id: this._id, query: Query.pretty(Query.fromAst(this._query)) });
     this._trace = trace;
 
     const changed =
@@ -223,13 +492,16 @@ export class QueryExecutor extends Resource {
         (item, index) =>
           workingSet[index].objectId !== item.objectId ||
           workingSet[index].spaceId !== item.spaceId ||
-          workingSet[index].documentId !== item.documentId,
+          workingSet[index].documentId !== item.documentId ||
+          workingSet[index].queueId !== item.queueId ||
+          workingSet[index].queueNamespace !== item.queueNamespace,
       );
 
     // Disabled because concurrent queries don't print hierarchies correctly.
     // ExecutionTrace.putOnPerformanceTimeline(trace);
 
     if (TRACE_QUERY_EXECUTION) {
+      // eslint-disable-next-line no-console
       console.log(ExecutionTrace.format(trace));
     }
 
@@ -240,7 +512,6 @@ export class QueryExecutor extends Resource {
 
   private async _execPlan(plan: QueryPlan.Plan, workingSet: QueryItem[]): Promise<StepExecutionResult> {
     const trace = ExecutionTrace.makeEmpty();
-    const begin = performance.now();
     for (const step of plan.steps) {
       if (this._ctx.disposed) {
         throw new ContextDisposedError();
@@ -288,6 +559,9 @@ export class QueryExecutor extends Resource {
       case 'OrderStep':
         ({ workingSet: newWorkingSet, trace } = await this._execOrderStep(step, workingSet));
         break;
+      case 'LimitStep':
+        ({ workingSet: newWorkingSet, trace } = await this._execLimitStep(step, workingSet));
+        break;
       default:
         throw new Error(`Unknown step type: ${(step as any)._tag}`);
     }
@@ -300,6 +574,10 @@ export class QueryExecutor extends Resource {
   private async _execSelectStep(step: QueryPlan.SelectStep, workingSet: QueryItem[]): Promise<StepExecutionResult> {
     workingSet = [...workingSet];
 
+    const spaces = (step.scope.spaceIds ?? []) as SpaceId[];
+    const queues = (step.scope.feeds ?? []) as DXN.String[];
+    const allQueuesFromSpaces = step.scope.allFeedsFromSpaces ?? false;
+
     const trace: ExecutionTrace = {
       ...ExecutionTrace.makeEmpty(),
       name: 'Select',
@@ -310,11 +588,9 @@ export class QueryExecutor extends Resource {
     switch (step.selector._tag) {
       case 'WildcardSelector': {
         const beginIndexQuery = performance.now();
-        const indexHits = await this._indexer.execQuery({
-          typenames: [],
-          inverted: false,
-        });
-        trace.indexHits = +indexHits.length;
+        const queueIds = extractQueueIds(queues);
+        const metas = await this._queryAllFromSqlIndex(spaces, allQueuesFromSpaces, queueIds);
+        trace.indexHits = metas.length;
         trace.indexQueryTime += performance.now() - beginIndexQuery;
 
         if (this._ctx.disposed) {
@@ -322,11 +598,11 @@ export class QueryExecutor extends Resource {
         }
 
         const documentLoadStart = performance.now();
-        const results = await this._loadDocumentsAfterIndexQuery(indexHits);
+        const results = await this._loadDocumentsAfterSqlQuery(metas);
         trace.documentsLoaded += results.length;
         trace.documentLoadTime += performance.now() - documentLoadStart;
 
-        workingSet.push(...results.filter(isNonNullable).filter((item) => step.spaces.includes(item.spaceId)));
+        workingSet.push(...results.filter(isNonNullable));
         trace.objectCount = workingSet.length;
 
         break;
@@ -334,10 +610,18 @@ export class QueryExecutor extends Resource {
 
       case 'IdSelector': {
         const beginLoad = performance.now();
+
         const items = await Promise.all(
-          step.selector.objectIds.map((id) =>
-            this._loadFromDXN(DXN.fromLocalObjectId(id), { sourceSpaceId: step.spaces[0] }),
-          ),
+          step.selector.objectIds.map((id) => {
+            if (queues.length > 0) {
+              const { spaceId } = DXN.parse(queues[0]).asQueueDXN()!;
+              return this._loadFromDXN(DXN.parse(queues[0]).extend([id]), { sourceSpaceId: spaceId });
+            } else if (spaces.length > 0) {
+              return this._loadFromDXN(DXN.fromLocalObjectId(id), { sourceSpaceId: spaces[0] });
+            } else {
+              return null; // Unknown scope.
+            }
+          }),
         );
         trace.documentLoadTime += performance.now() - beginLoad;
 
@@ -348,11 +632,15 @@ export class QueryExecutor extends Resource {
 
       case 'TypeSelector': {
         const beginIndexQuery = performance.now();
-        const indexHits = await this._indexer.execQuery({
-          typenames: step.selector.typename,
-          inverted: step.selector.inverted,
-        });
-        trace.indexHits = +indexHits.length;
+        const queueIds = extractQueueIds(queues);
+        const metas = await this._queryTypesFromSqlIndex(
+          spaces,
+          step.selector.typename,
+          step.selector.inverted,
+          allQueuesFromSpaces,
+          queueIds,
+        );
+        trace.indexHits = metas.length;
         trace.indexQueryTime += performance.now() - beginIndexQuery;
 
         if (this._ctx.disposed) {
@@ -360,43 +648,144 @@ export class QueryExecutor extends Resource {
         }
 
         const documentLoadStart = performance.now();
-        const results = await this._loadDocumentsAfterIndexQuery(indexHits);
+        const results = await this._loadDocumentsAfterSqlQuery(metas);
         trace.documentsLoaded += results.length;
         trace.documentLoadTime += performance.now() - documentLoadStart;
 
-        workingSet.push(...results.filter(isNonNullable).filter((item) => step.spaces.includes(item.spaceId)));
+        workingSet.push(...results.filter(isNonNullable));
+        trace.objectCount = workingSet.length;
+
+        break;
+      }
+
+      case 'TimestampSelector': {
+        const beginIndexQuery = performance.now();
+        const queueIds = extractQueueIds(queues);
+        const metas = await this._runInRuntime(
+          this._indexEngine.queryByTimeRange({
+            spaceIds: spaces,
+            updatedAfter: step.selector.updatedAfter,
+            updatedBefore: step.selector.updatedBefore,
+            createdAfter: step.selector.createdAfter,
+            createdBefore: step.selector.createdBefore,
+            includeAllQueues: allQueuesFromSpaces,
+            queueIds,
+          }),
+        );
+        trace.indexHits = metas.length;
+        trace.indexQueryTime += performance.now() - beginIndexQuery;
+
+        if (this._ctx.disposed) {
+          return { workingSet, trace };
+        }
+
+        const documentLoadStart = performance.now();
+        const results = await this._loadDocumentsAfterSqlQuery(metas);
+        trace.documentsLoaded += results.length;
+        trace.documentLoadTime += performance.now() - documentLoadStart;
+
+        workingSet.push(...results.filter(isNonNullable));
         trace.objectCount = workingSet.length;
 
         break;
       }
 
       case 'TextSelector': {
+        // TODO(dmaretskyi): type + FTS queries would be very common so we should support those, maybe chunk the fts index.
+        // TODO(dmaretskyi): nice to have matched text snippets/highlighting.
+        if (step.selector.searchKind === 'vector') {
+          // Vector search is not currently supported.
+          log.warn('Vector search is not supported');
+          break;
+        }
+
+        // Full-text search using SQLite FTS5.
         const beginIndexQuery = performance.now();
-        const indexHits = await this._indexer.execQuery({
-          typenames: [],
-          text: {
+        invariant(spaces.length <= 1, 'Multiple spaces are not supported for full-text search');
+        const queueIds = extractQueueIds(queues);
+        const textResults = await this._runInRuntime(
+          this._indexEngine.queryText({
             query: step.selector.text,
-            kind: Match.type<QueryPlan.TextSearchKind>().pipe(
-              Match.withReturnType<'text' | 'vector'>(),
-              Match.when('full-text', () => 'text'),
-              Match.when('vector', () => 'vector'),
-              Match.orElseAbsurd,
-            )(step.selector.searchKind),
-          },
-        });
-        trace.indexHits = +indexHits.length;
+            spaceId: spaces,
+            includeAllQueues: allQueuesFromSpaces,
+            queueIds,
+          }),
+        );
+        trace.indexHits = textResults.length;
         trace.indexQueryTime += performance.now() - beginIndexQuery;
 
         if (this._ctx.disposed) {
           return { workingSet, trace };
         }
 
+        // Load documents from the results.
         const documentLoadStart = performance.now();
-        const results = await this._loadDocumentsAfterIndexQuery(indexHits);
-        trace.documentsLoaded += results.length;
+
+        // Separate queue items from space items.
+        const queueResults = textResults.filter((r) => r.queueId);
+        const spaceResults = textResults.filter((r) => !r.queueId);
+
+        // Build a map from recordId to rank for all FTS results.
+        const rankMap = new Map(textResults.map((r) => [r.recordId, r.rank]));
+
+        // Load queue items from indexed snapshots.
+        let queueItems: QueryItem[] = [];
+        if (queueResults.length > 0) {
+          const snapshots = await this._runInRuntime(
+            this._indexEngine.querySnapshotsJSON(queueResults.map((r) => r.recordId)),
+          );
+          const snapshotMap = new Map(snapshots.map((s) => [s.recordId, s.snapshot]));
+          queueItems = queueResults
+            .map((result): QueryItem | null => {
+              const snapshot = snapshotMap.get(result.recordId);
+              if (!snapshot || typeof snapshot !== 'object') {
+                return null;
+              }
+              return {
+                objectId: result.objectId as ObjectId,
+                spaceId: result.spaceId as SpaceId,
+                queueId: result.queueId as ObjectId,
+                queueNamespace: result.queueNamespace || null,
+                documentId: null,
+                doc: null,
+                data: snapshot as Obj.JSON,
+                rank: rankMap.get(result.recordId) ?? 1,
+              };
+            })
+            .filter(isNonNullable);
+        }
+
+        // Load space items from documents.
+        const spaceItems = await Promise.all(
+          spaceResults.map(async (result): Promise<QueryItem | null> => {
+            const dxn = DXN.fromLocalObjectId(result.objectId);
+            const item = await this._loadFromDXN(dxn, { sourceSpaceId: result.spaceId as SpaceId });
+            if (item) {
+              // Override the default rank with the FTS rank.
+              item.rank = rankMap.get(result.recordId) ?? 1;
+            }
+            return item;
+          }),
+        );
+
+        const items = [...queueItems, ...spaceItems.filter(isNonNullable)];
+        trace.documentsLoaded += items.length;
         trace.documentLoadTime += performance.now() - documentLoadStart;
 
-        workingSet.push(...results.filter(isNonNullable).filter((item) => step.spaces.includes(item.spaceId)));
+        workingSet.push(
+          ...items.filter((item) => {
+            if (spaces.includes(item.spaceId)) {
+              return true;
+            }
+            if (item.queueId) {
+              return queues.some((dxn) => {
+                const { queueId, spaceId } = DXN.parse(dxn).asQueueDXN()!;
+                return queueId === item.queueId && spaceId === item.spaceId;
+              });
+            }
+            return false;
+          }),
+        );
         trace.objectCount = workingSet.length;
         break;
       }
@@ -405,17 +794,46 @@ export class QueryExecutor extends Resource {
         throw new Error(`Unknown selector type: ${(step.selector as any)._tag}`);
     }
 
+    // Apply limit if specified on the select step.
+    if (step.limit !== undefined && workingSet.length > step.limit) {
+      workingSet = workingSet.slice(0, step.limit);
+      trace.objectCount = workingSet.length;
+    }
+
     return { workingSet, trace };
   }
 
   private async _execFilterStep(step: QueryPlan.FilterStep, workingSet: QueryItem[]): Promise<StepExecutionResult> {
-    const result = workingSet.filter((item) =>
-      filterMatchObject(step.filter, {
-        id: item.objectId,
-        spaceId: item.spaceId,
-        doc: item.doc,
-      }),
-    );
+    if (step.filter.type === 'child-of') {
+      return this._execChildOfFilterStep(step.filter, workingSet);
+    }
+
+    const timestampParams = extractTimestampParams(step.filter);
+    if (timestampParams !== null) {
+      return this._execTimestampFilterStep(step, workingSet, timestampParams);
+    }
+
+    if (filterContainsTimestamp(step.filter)) {
+      throw new QueryError({
+        message:
+          'Timestamp filter in unsupported composition (not, or). Use Filter.updated/Filter.created with explicit range instead.',
+        context: {},
+      });
+    }
+
+    const result = workingSet.filter((item) => {
+      if (item.doc) {
+        return filterMatchObject(step.filter, {
+          id: item.objectId,
+          spaceId: item.spaceId,
+          doc: item.doc,
+        });
+      } else if (item.data) {
+        return filterMatchObjectJSON(step.filter, item.data);
+      } else {
+        return false;
+      }
+    });
 
     return {
       workingSet: result,
@@ -428,12 +846,52 @@ export class QueryExecutor extends Resource {
     };
   }
 
+  private async _execTimestampFilterStep(
+    step: QueryPlan.FilterStep,
+    workingSet: QueryItem[],
+    params: { updatedAfter?: number; updatedBefore?: number; createdAfter?: number; createdBefore?: number },
+  ): Promise<StepExecutionResult> {
+    const spaces = [...new Set(workingSet.map((item) => item.spaceId).filter(isNonNullable))];
+    const metas = await this._runInRuntime(
+      this._indexEngine.queryByTimeRange({
+        spaceIds: spaces,
+        ...params,
+        includeAllQueues: false,
+        queueIds: [],
+      }),
+    );
+    const matchingIds = new Set(metas.map((m) => m.objectId));
+    const result = workingSet.filter((item) => matchingIds.has(item.objectId));
+    return {
+      workingSet: result,
+      trace: {
+        ...ExecutionTrace.makeEmpty(),
+        name: 'Filter(timestamp)',
+        details: JSON.stringify(params),
+        objectCount: result.length,
+      },
+    };
+  }
+
   private async _execFilterDeletedStep(
     step: QueryPlan.FilterDeletedStep,
     workingSet: QueryItem[],
   ): Promise<StepExecutionResult> {
     const expected = step.mode === 'only-deleted';
-    const result = workingSet.filter((item) => ObjectStructure.isDeleted(item.doc) === expected);
+
+    const deletedState = workingSet.map((item) => QueryItem.isDeleted(item));
+    await Promise.all(
+      workingSet.map(async (item, index) => {
+        if (deletedState[index]) {
+          return;
+        }
+        deletedState[index] ||= await this._getTransitiveDeletionState(item, MAX_DEPTH_FOR_DELETION_TRACING);
+      }),
+    );
+
+    const result = workingSet.filter((item, index) => deletedState[index] === expected);
+
+    // TODO(dmaretskyi): How do we handle items with parents and cascade deletions? -- perhaps we forbid queue items from having parents -- i.e. queue is their parent.
     return {
       workingSet: result,
       trace: {
@@ -445,6 +903,78 @@ export class QueryExecutor extends Resource {
     };
   }
 
+  private async _execChildOfFilterStep(
+    filter: QueryAST.FilterChildOf,
+    workingSet: QueryItem[],
+  ): Promise<StepExecutionResult> {
+    const parentObjectIds = new Set<string>();
+    for (const parentDxnStr of filter.parents) {
+      const dxn = DXN.parse(parentDxnStr);
+      const echoDXN = dxn.asEchoDXN();
+      if (echoDXN) {
+        parentObjectIds.add(echoDXN.echoId);
+      }
+    }
+    const maxDepth = filter.transitive ? MAX_DEPTH_FOR_CHILD_OF_TRACING : 1;
+
+    const matches = await Promise.all(
+      workingSet.map(async (item) => this._isChildOfAny(item, parentObjectIds, maxDepth)),
+    );
+    const result = workingSet.filter((_item, index) => matches[index]);
+
+    return {
+      workingSet: result,
+      trace: {
+        ...ExecutionTrace.makeEmpty(),
+        name: 'Filter(child-of)',
+        details: JSON.stringify({ parents: filter.parents, transitive: filter.transitive }),
+        objectCount: result.length,
+      },
+    };
+  }
+
+  /**
+   * Checks if an item is a child of any of the given parent object IDs.
+   * Walks up the parent chain (and feed ownership for queue items) until a match is found or depth is exhausted.
+   */
+  private async _isChildOfAny(item: QueryItem, parentObjectIds: Set<string>, remainingDepth: number): Promise<boolean> {
+    if (remainingDepth <= 0) {
+      return false;
+    }
+
+    const parentRefs: { dxnStr: string; objectId: string }[] = [];
+
+    const directParent = QueryItem.getParent(item);
+    if (directParent) {
+      const echoDXN = DXN.parse(directParent).asEchoDXN();
+      if (echoDXN) {
+        parentRefs.push({ dxnStr: directParent, objectId: echoDXN.echoId });
+      }
+    }
+
+    if (item.queueId && !directParent) {
+      parentRefs.push({
+        dxnStr: DXN.fromSpaceAndObjectId(item.spaceId, item.queueId).toString(),
+        objectId: item.queueId,
+      });
+    }
+
+    for (const ref of parentRefs) {
+      if (parentObjectIds.has(ref.objectId)) {
+        return true;
+      }
+    }
+
+    for (const ref of parentRefs) {
+      const parentItem = await this._loadFromDXN(DXN.parse(ref.dxnStr), { sourceSpaceId: item.spaceId });
+      if (parentItem && (await this._isChildOfAny(parentItem, parentObjectIds, remainingDepth - 1))) {
+        return true;
+      }
+    }
+
+    return false;
+  }
+
   // TODO(dmaretskyi): This needs to be completed.
   private async _execTraverseStep(step: QueryPlan.TraverseStep, workingSet: QueryItem[]): Promise<StepExecutionResult> {
     const trace: ExecutionTrace = {
@@ -459,11 +989,12 @@ export class QueryExecutor extends Resource {
       case 'ReferenceTraversal': {
         switch (step.traversal.direction) {
           case 'outgoing': {
+            invariant(step.traversal.property !== null, 'Outgoing reference traversal requires a property');
             const property = EscapedPropPath.unescape(step.traversal.property);
 
             const refs = workingSet
               .flatMap((item) => {
-                const ref = getDeep(item.doc.data, property);
+                const ref = QueryItem.getProperty(item, property);
                 const refs = Array.isArray(ref) ? ref : [ref];
                 return refs.map((ref) => {
                   try {
@@ -493,19 +1024,13 @@ export class QueryExecutor extends Resource {
             break;
           }
           case 'incoming': {
-            const indexHits = await this._indexer.execQuery({
-              typenames: [],
-              inverted: false,
-              graph: {
-                kind: 'inbound-reference',
-                property: step.traversal.property,
-                anchors: workingSet.map((item) => item.objectId),
-              },
-            });
-            trace.indexHits += indexHits.length;
+            const beginIndexQuery = performance.now();
+            const metas = await this._queryIncomingReferencesFromSqlIndex(workingSet, step.traversal.property);
+            trace.indexHits += metas.length;
+            trace.indexQueryTime += performance.now() - beginIndexQuery;
 
             const documentLoadStart = performance.now();
-            const results = await this._loadDocumentsAfterIndexQuery(indexHits);
+            const results = await this._loadDocumentsAfterSqlQuery(metas);
             trace.documentsLoaded += results.length;
             trace.documentLoadTime += performance.now() - documentLoadStart;
 
@@ -523,21 +1048,20 @@ export class QueryExecutor extends Resource {
           case 'relation-to-target': {
             const refs = workingSet
               .map((item) => {
-                const ref =
+                const dxn =
                   step.traversal.direction === 'relation-to-source'
-                    ? ObjectStructure.getRelationSource(item.doc)
-                    : ObjectStructure.getRelationTarget(item.doc);
-
-                if (!isEncodedReference(ref)) {
+                    ? QueryItem.getRelationSource(item)
+                    : QueryItem.getRelationTarget(item);
+                if (!dxn) {
                   return null;
                 }
                 try {
                   return {
-                    ref: DXN.parse(ref['/']),
+                    ref: DXN.parse(dxn),
                     spaceId: item.spaceId,
                   };
                 } catch {
-                  log.warn('invalid reference', { ref: ref['/'] });
+                  log.warn('invalid reference', { ref: dxn });
                   return null;
                 }
               })
@@ -557,20 +1081,16 @@ export class QueryExecutor extends Resource {
 
           case 'source-to-relation':
           case 'target-to-relation': {
-            const indexHits = await this._indexer.execQuery({
-              typenames: [],
-              inverted: false,
-              graph: {
-                kind: step.traversal.direction === 'source-to-relation' ? 'relation-source' : 'relation-target',
-                anchors: workingSet.map((item) => item.objectId),
-                property: null,
-              },
-            });
-
-            trace.indexHits += indexHits.length;
+            const beginIndexQuery = performance.now();
+            const metas = await this._queryRelationsFromSqlIndex(
+              workingSet,
+              step.traversal.direction === 'source-to-relation' ? 'source' : 'target',
+            );
+            trace.indexHits += metas.length;
+            trace.indexQueryTime += performance.now() - beginIndexQuery;
 
             const documentLoadStart = performance.now();
-            const results = await this._loadDocumentsAfterIndexQuery(indexHits);
+            const results = await this._loadDocumentsAfterSqlQuery(metas);
             trace.documentsLoaded += results.length;
             trace.documentLoadTime += performance.now() - documentLoadStart;
 
@@ -582,6 +1102,80 @@ export class QueryExecutor extends Resource {
         }
         break;
       }
+      case 'HierarchyTraversal': {
+        switch (step.traversal.direction) {
+          case 'to-parent': {
+            // Traverse from child to parent using the parent reference in the document.
+            const refs = workingSet
+              .map((item) => {
+                if (!item.doc) {
+                  return null; // TODO(dmaretskyi): Queue items not supported here.
+                }
+                const ref = ObjectStructure.getParent(item.doc);
+                if (!EncodedReference.isEncodedReference(ref)) {
+                  return null;
+                }
+                try {
+                  return {
+                    ref: DXN.parse(ref['/']),
+                    spaceId: item.spaceId,
+                  };
+                } catch {
+                  log.warn('invalid parent reference', { ref: ref['/'] });
+                  return null;
+                }
+              })
+              .filter(isNonNullable);
+
+            const beginLoad = performance.now();
+            const items = await Promise.all(
+              refs.map(({ ref, spaceId }) => this._loadFromDXN(ref, { sourceSpaceId: spaceId })),
+            );
+            trace.documentLoadTime += performance.now() - beginLoad;
+
+            newWorkingSet.push(...items.filter(isNonNullable));
+            trace.objectCount = newWorkingSet.length;
+            break;
+          }
+
+          case 'to-children': {
+            // Traverse from parent to children using the SQL index.
+            // Covers both standard parent/child hierarchy (via the `parent` field) and
+            // feed -> queue items (via the `queueId` field — a feed's queue id matches the feed's object id).
+            // Group working set by spaceId.
+            const bySpace = new Map<SpaceId, ObjectId[]>();
+            for (const item of workingSet) {
+              const existing = bySpace.get(item.spaceId);
+              if (existing) {
+                existing.push(item.objectId);
+              } else {
+                bySpace.set(item.spaceId, [item.objectId]);
+              }
+            }
+
+            const beginIndexQuery = performance.now();
+            const allMetas: ObjectMeta[] = [];
+            for (const [spaceId, parentIds] of bySpace) {
+              const children = await this._runInRuntime(
+                this._indexEngine.queryChildren({ spaceId: [spaceId], parentIds }),
+              );
+              allMetas.push(...children);
+            }
+            trace.indexHits += allMetas.length;
+            trace.indexQueryTime += performance.now() - beginIndexQuery;
+
+            const documentLoadStart = performance.now();
+            const results = await this._loadDocumentsAfterSqlQuery(allMetas);
+            trace.documentsLoaded += results.filter(isNonNullable).length;
+            trace.documentLoadTime += performance.now() - documentLoadStart;
+
+            newWorkingSet.push(...results.filter(isNonNullable));
+            trace.objectCount = newWorkingSet.length;
+            break;
+          }
+        }
+        break;
+      }
       default:
         throw new Error(`Unknown traversal type: ${(step.traversal as any)._tag}`);
     }
@@ -603,7 +1197,7 @@ export class QueryExecutor extends Resource {
     for (const resultSet of resultSets) {
       for (const item of resultSet.workingSet) {
         // Could be duplicate object ids in different spaces or in different epochs of the same space.
-        results.set(`${item.spaceId}:${item.documentId}:${item.objectId}`, item);
+        results.set(compositeKey(item.spaceId, String(item.documentId), item.objectId), item);
       }
       trace.children.push(resultSet.trace);
     }
@@ -637,19 +1231,38 @@ export class QueryExecutor extends Resource {
   }
 
   private async _execOrderStep(step: QueryPlan.OrderStep, workingSet: QueryItem[]): Promise<StepExecutionResult> {
-    const sortedWorkingSet = [...workingSet].sort((a, b) => this._compareMultiOrder(a, b, step.order));
+    let sortedWorkingSet = [...workingSet].sort((a, b) => this._compareMultiOrder(a, b, step.order));
+
+    // Apply limit if specified on the order step.
+    if (step.limit !== undefined && sortedWorkingSet.length > step.limit) {
+      sortedWorkingSet = sortedWorkingSet.slice(0, step.limit);
+    }
 
     return {
       workingSet: sortedWorkingSet,
       trace: {
         ...ExecutionTrace.makeEmpty(),
         name: 'Order',
-        details: JSON.stringify(step.order),
+        details: JSON.stringify({ order: step.order, limit: step.limit }),
         objectCount: sortedWorkingSet.length,
       },
     };
   }
 
+  private async _execLimitStep(step: QueryPlan.LimitStep, workingSet: QueryItem[]): Promise<StepExecutionResult> {
+    const limitedWorkingSet = workingSet.slice(0, step.limit);
+
+    return {
+      workingSet: limitedWorkingSet,
+      trace: {
+        ...ExecutionTrace.makeEmpty(),
+        name: 'Limit',
+        details: JSON.stringify({ limit: step.limit }),
+        objectCount: limitedWorkingSet.length,
+      },
+    };
+  }
+
   private _compareMultiOrder(a: QueryItem, b: QueryItem, orders: readonly QueryAST.Order[]): number {
     // Short circuit for common cases.
     if (orders.length === 0) {
@@ -675,15 +1288,20 @@ export class QueryExecutor extends Resource {
         const comparison = this._compareByProperty(a, b, order.property);
         return order.direction === 'desc' ? -comparison : comparison;
       }
+      case 'rank': {
+        // Higher rank = better match. By default, descending order (best first).
+        const comparison = a.rank - b.rank;
+        return order.direction === 'desc' ? -comparison : comparison;
+      }
       default:
-        // Should never reach here with proper TypeScript types
+        // Should never reach here with proper TypeScript types.
         return 0;
     }
   }
 
   private _compareByProperty(a: QueryItem, b: QueryItem, property: string): number {
-    const aValue = a.doc.data[property];
-    const bValue = b.doc.data[property];
+    const aValue = QueryItem.getProperty(a, [property]);
+    const bValue = QueryItem.getProperty(b, [property]);
 
     // Both null or undefined
     if (aValue == null && bValue == null) {
@@ -719,103 +1337,377 @@ export class QueryExecutor extends Resource {
     return String(aValue).localeCompare(String(bValue));
   }
 
-  private async _loadDocumentsAfterIndexQuery(indexHits: FindResult[]): Promise<(QueryItem | null)[]> {
-    return Promise.all(
-      indexHits.map(async (hit): Promise<QueryItem | null> => {
-        return this._loadFromIndexHit(hit);
-      }),
+  private async _runInRuntime<T>(effect: Effect.Effect<T, unknown, SqlClient.SqlClient>): Promise<T> {
+    const runtimeProvider = this._runtime;
+    invariant(runtimeProvider, 'SQL runtime is required.');
+    const runtime = await runAndForwardErrors(runtimeProvider);
+    return await unwrapExit(await effect.pipe(Runtime.runPromiseExit(runtime)));
+  }
+
+  private async _queryAllFromSqlIndex(
+    spaceIds: readonly SpaceId[],
+    includeAllQueues: boolean,
+    queueIds: readonly ObjectId[] | null,
+  ): Promise<readonly ObjectMeta[]> {
+    return await this._runInRuntime(this._indexEngine.queryAll({ spaceIds, includeAllQueues, queueIds }));
+  }
+
+  private async _queryTypesFromSqlIndex(
+    spaceIds: readonly SpaceId[],
+    typeDxns: readonly string[],
+    inverted: boolean,
+    includeAllQueues: boolean,
+    queueIds: readonly ObjectId[] | null,
+  ): Promise<readonly ObjectMeta[]> {
+    return await this._runInRuntime(
+      this._indexEngine.queryTypes({ spaceIds, typeDxns, inverted, includeAllQueues, queueIds }),
     );
   }
 
+  private async _queryIncomingReferencesFromSqlIndex(
+    workingSet: QueryItem[],
+    property: EscapedPropPath | null,
+  ): Promise<readonly ObjectMeta[]> {
+    const anchorDxns = workingSet.map((item) => DXN.fromLocalObjectId(item.objectId).toString());
+    const rows: readonly ReverseRef[] = (
+      await Promise.all(
+        anchorDxns.map((targetDXN) => this._runInRuntime(this._indexEngine.queryReverseRef({ targetDXN }))),
+      )
+    ).flat();
+
+    const recordIds = rows
+      .filter((row) => {
+        if (property === null) {
+          return true;
+        }
+
+        const queryPath = EscapedPropPath.unescape(property);
+        const rowPath = EscapedPropPath.unescape(row.propPath);
+        return QueryExecutor._matchesReferencePropertyPath(rowPath, queryPath);
+      })
+      .map((row) => row.recordId);
+
+    const uniqueRecordIds = Array.from(new Set<number>(recordIds));
+    return await this._runInRuntime(this._indexEngine.lookupByRecordIds(uniqueRecordIds));
+  }
+
   /**
-   * Space key hex -> SpaceId.
+   * Matches a reverse-reference row path against a query property path.
+   * Allows numeric segments in the row path (array indices) that are not present in the query.
+   *
+   * Examples:
+   * - query: ['assignee'] matches row: ['assignee'] and ['assignee', '0'].
+   * - query: ['items', 'assignee'] matches row: ['items', '0', 'assignee'].
+   * - query: ['a', 'b'] does NOT match row: ['a'].
+   * - query: ['a'] does NOT match row: ['a', 'b'].
    */
-  private readonly _spaceIdCache = new Map<string, SpaceId>();
+  private static _matchesReferencePropertyPath(rowPath: readonly string[], queryPath: readonly string[]): boolean {
+    const isNumericSegment = (segment: string) => /^[0-9]+$/.test(segment);
 
-  private async _loadFromIndexHit(hit: FindResult): Promise<QueryItem | null> {
-    const { objectId, documentId, spaceKey: spaceKeyInIndex } = objectPointerCodec.decode(hit.id);
+    let i = 0; // queryPath index.
+    let j = 0; // rowPath index.
 
-    const handle = await this._automergeHost.loadDoc<DatabaseDirectory>(Context.default(), documentId as DocumentId);
-    const doc = handle.doc();
-    if (!doc) {
-      return null;
+    while (i < queryPath.length && j < rowPath.length) {
+      if (rowPath[j] === queryPath[i]) {
+        i++;
+        j++;
+        continue;
+      }
+
+      // Row may contain array indices that aren't present in the query path.
+      if (isNumericSegment(rowPath[j])) {
+        j++;
+        continue;
+      }
+
+      return false;
     }
 
-    const spaceKey = spaceKeyInIndex ?? DatabaseDirectory.getSpaceKey(doc);
-    if (!spaceKey) {
-      return null;
+    // Must consume full query path.
+    if (i !== queryPath.length) {
+      return false;
     }
 
-    let spaceId = this._spaceIdCache.get(spaceKey);
-    if (!spaceId) {
-      spaceId = await createIdFromSpaceKey(PublicKey.from(spaceKey));
-      this._spaceIdCache.set(spaceKey, spaceId);
+    // Any remaining row segments must be numeric (array indices).
+    for (; j < rowPath.length; j++) {
+      if (!isNumericSegment(rowPath[j])) {
+        return false;
+      }
     }
 
-    const object = DatabaseDirectory.getInlineObject(doc, objectId);
-    if (!object) {
+    return true;
+  }
+
+  private async _queryRelationsFromSqlIndex(
+    workingSet: QueryItem[],
+    endpoint: 'source' | 'target',
+  ): Promise<readonly ObjectMeta[]> {
+    const anchorDxns = workingSet.map((item) => DXN.fromLocalObjectId(item.objectId).toString());
+    return await this._runInRuntime(this._indexEngine.queryRelations({ endpoint, anchorDxns }));
+  }
+
+  private async _loadDocumentsAfterSqlQuery(metas: readonly ObjectMeta[]): Promise<(QueryItem | null)[]> {
+    const snapshotMap = await this._loadQueueSnapshotMap(metas);
+    return await Promise.all(
+      metas.map(async (meta) => {
+        // Branch 1: Document-backed object.
+        if (meta.documentId) {
+          return this._loadFromAutomerge(meta);
+        }
+
+        // Branch 2: Queue-backed object.
+        if (meta.queueId) {
+          return this._loadFromQueue(meta, snapshotMap);
+        }
+
+        return null;
+      }),
+    );
+  }
+
+  private async _loadQueueSnapshotMap(metas: readonly ObjectMeta[]): Promise<Map<number, unknown>> {
+    const queueMetas = metas.filter((meta) => !meta.documentId && !!meta.queueId);
+    if (queueMetas.length === 0) {
+      return new Map();
+    }
+
+    const snapshots = await this._runInRuntime(
+      this._indexEngine.querySnapshotsJSON(queueMetas.map((meta) => meta.recordId)),
+    );
+    return new Map(snapshots.map((s) => [s.recordId, s.snapshot]));
+  }
+
+  /**
+   * Loads a queue-backed object from an indexed snapshot (by `recordId`).
+   * Returns `null` when the snapshot is missing or is not a JSON object.
+   */
+  private _loadFromQueue(meta: ObjectMeta, snapshotMap: Map<number, unknown>): QueryItem | null {
+    const snapshot = snapshotMap.get(meta.recordId);
+    if (!snapshot || typeof snapshot !== 'object') {
       return null;
     }
 
     return {
-      objectId,
-      documentId: documentId as DocumentId,
-      spaceId,
-      doc: object,
+      objectId: meta.objectId as ObjectId,
+      spaceId: meta.spaceId as SpaceId,
+      queueId: meta.queueId as ObjectId,
+      queueNamespace: meta.queueNamespace || null,
+      documentId: null,
+      doc: null,
+      data: snapshot as Obj.JSON,
+      rank: 1,
     };
   }
 
-  private async _loadFromDXN(dxn: DXN, { sourceSpaceId }: { sourceSpaceId: SpaceId }): Promise<QueryItem | null> {
-    const echoDxn = dxn.asEchoDXN();
-    if (!echoDxn) {
-      log.warn('unable to resolve DXN', { dxn });
+  /**
+   * Loads a document-backed object from an Automerge `DatabaseDirectory`.
+   * Returns `null` if the document can't be loaded, the inline object isn't present, or if the meta does not have a
+   * document id (e.g. queue-backed objects).
+   */
+  private async _loadFromAutomerge(meta: ObjectMeta): Promise<QueryItem | null> {
+    if (!meta.documentId) {
       return null;
     }
-
-    const spaceId = echoDxn.spaceId ?? sourceSpaceId;
-
-    const spaceRoot = this._spaceStateManager.getRootBySpaceId(spaceId);
-    if (!spaceRoot) {
-      log.warn('no space state found for', { spaceId });
+    const handle = await this._automergeHost.loadDoc<DatabaseDirectory>(this._ctx, meta.documentId as DocumentId, {
+      fetchFromNetwork: false,
+    });
+    if (!handle) {
       return null;
     }
-    const dbDirectory = spaceRoot.doc();
-    if (!dbDirectory) {
-      log.warn('no space state found for', { spaceId });
+    const object = DatabaseDirectory.getInlineObject(handle.doc(), meta.objectId);
+    if (!object) {
       return null;
     }
+    return {
+      objectId: meta.objectId,
+      documentId: meta.documentId as DocumentId,
+      spaceId: meta.spaceId as SpaceId,
+      queueId: null,
+      queueNamespace: null,
+      doc: object,
+      data: null,
+      rank: 1,
+    };
+  }
+
+  private async _loadFromDXN(dxn: DXN, { sourceSpaceId }: { sourceSpaceId: SpaceId }): Promise<QueryItem | null> {
+    switch (dxn.kind) {
+      case DXN.kind.ECHO: {
+        const echoDXN = dxn.asEchoDXN();
+        if (!echoDXN) {
+          log.warn('unable to resolve DXN', { dxn });
+          return null;
+        }
+
+        const spaceId = echoDXN.spaceId ?? sourceSpaceId;
 
-    const inlineObject = DatabaseDirectory.getInlineObject(dbDirectory, echoDxn.echoId);
-    if (inlineObject) {
-      return {
-        objectId: echoDxn.echoId,
-        documentId: spaceRoot.documentId,
-        spaceId,
-        doc: inlineObject,
-      };
+        const spaceRoot = this._spaceStateManager.getRootBySpaceId(spaceId);
+        if (!spaceRoot) {
+          log.warn('no space state found for', { spaceId });
+          return null;
+        }
+        const dbDirectory = spaceRoot.doc();
+        if (!dbDirectory) {
+          log.warn('no space state found for', { spaceId });
+          return null;
+        }
+
+        const inlineObject = DatabaseDirectory.getInlineObject(dbDirectory, echoDXN.echoId);
+        if (inlineObject) {
+          return {
+            objectId: echoDXN.echoId,
+            documentId: spaceRoot.documentId,
+            spaceId,
+            queueId: null,
+            queueNamespace: null,
+            data: null,
+            doc: inlineObject,
+            rank: 1,
+          };
+        }
+
+        const link = DatabaseDirectory.getLink(dbDirectory, echoDXN.echoId);
+        if (!link) {
+          return null;
+        }
+
+        const handle = await this._automergeHost.loadDoc<DatabaseDirectory>(this._ctx, link as AutomergeUrl, {
+          fetchFromNetwork: false,
+        });
+        if (!handle) {
+          return null;
+        }
+        const object = DatabaseDirectory.getInlineObject(handle.doc(), echoDXN.echoId);
+        if (!object) {
+          return null;
+        }
+
+        return {
+          objectId: echoDXN.echoId,
+          documentId: handle.documentId,
+          spaceId,
+          queueId: null,
+          queueNamespace: null,
+          data: null,
+          doc: object,
+          rank: 1,
+        };
+        break;
+      }
+      case DXN.kind.QUEUE: {
+        const queueDXN = dxn.asQueueDXN();
+        if (!queueDXN || !queueDXN.objectId) {
+          log.warn('unable to resolve queue DXN', { dxn });
+          return null;
+        }
+
+        const { spaceId, queueId, objectId } = queueDXN;
+        const meta = await this._runInRuntime(
+          this._indexEngine.lookupByObjectId({
+            objectId,
+            spaceId,
+            queueId,
+          }),
+        );
+        if (!meta) {
+          return null;
+        }
+
+        const snapshotMap = await this._loadQueueSnapshotMap([meta]);
+        return this._loadFromQueue(meta, snapshotMap);
+      }
+      default: {
+        log.warn('unable to resolve DXN', { dxn });
+        return null;
+      }
     }
+  }
 
-    const link = DatabaseDirectory.getLink(dbDirectory, echoDxn.echoId);
-    if (!link) {
-      return null;
+  private async _getTransitiveDeletionState(item: QueryItem, remainingDepth: number): Promise<boolean> {
+    const strongDeps = [
+      QueryItem.getParent(item),
+      QueryItem.getRelationSource(item),
+      QueryItem.getRelationTarget(item),
+    ].filter((x) => x !== undefined);
+
+    if (strongDeps.length === 0) {
+      return false;
     }
 
-    const handle = await this._automergeHost.loadDoc<DatabaseDirectory>(Context.default(), link as AutomergeUrl);
-    const doc = handle.doc();
-    if (!doc) {
-      return null;
+    // TODO(dmaretskyi): This could be optimized to bail early if any of the dependencies are deleted.
+    const strongDepStates = await Promise.all(
+      strongDeps.map(async (dxn) => {
+        const dep = await this._loadFromDXN(DXN.parse(dxn), { sourceSpaceId: item.spaceId });
+        if (!dep) {
+          return false;
+        }
+        if (QueryItem.isDeleted(dep)) {
+          return true;
+        }
+        if (remainingDepth > 0) {
+          return this._getTransitiveDeletionState(dep, remainingDepth - 1);
+        }
+        return false;
+      }),
+    );
+
+    return strongDepStates.some((x) => x);
+  }
+}
+
+const extractQueueIds = (queues: readonly DXN.String[]): ObjectId[] | null => {
+  if (queues.length === 0) {
+    return null;
+  }
+  return queues.map((dxnStr) => DXN.parse(dxnStr).asQueueDXN()?.queueId).filter(Boolean) as ObjectId[];
+};
+
+/**
+ * Extract timestamp parameters from a filter AST node.
+ * Returns null if the filter doesn't contain timestamp nodes.
+ */
+const extractTimestampParams = (
+  filter: QueryAST.Filter,
+): { updatedAfter?: number; updatedBefore?: number; createdAfter?: number; createdBefore?: number } | null => {
+  const collect = (f: QueryAST.Filter): QueryAST.FilterTimestamp[] => {
+    if (f.type === 'timestamp') {
+      return [f];
+    }
+    if (f.type === 'and') {
+      return f.filters.flatMap(collect);
     }
+    return [];
+  };
 
-    const object = DatabaseDirectory.getInlineObject(doc, echoDxn.echoId);
-    if (!object) {
-      return null;
+  const timestamps = collect(filter);
+  if (timestamps.length === 0) {
+    return null;
+  }
+
+  const params: { updatedAfter?: number; updatedBefore?: number; createdAfter?: number; createdBefore?: number } = {};
+  for (const ts of timestamps) {
+    if (ts.field === 'updatedAt' && (ts.operator === 'gt' || ts.operator === 'gte')) {
+      params.updatedAfter = ts.value;
+    } else if (ts.field === 'updatedAt' && (ts.operator === 'lt' || ts.operator === 'lte')) {
+      params.updatedBefore = ts.value;
+    } else if (ts.field === 'createdAt' && (ts.operator === 'gt' || ts.operator === 'gte')) {
+      params.createdAfter = ts.value;
+    } else if (ts.field === 'createdAt' && (ts.operator === 'lt' || ts.operator === 'lte')) {
+      params.createdBefore = ts.value;
     }
+  }
+  return params;
+};
 
-    return {
-      objectId: echoDxn.echoId,
-      documentId: handle.documentId,
-      spaceId,
-      doc: object,
-    };
+function filterContainsTimestamp(filter: QueryAST.Filter): boolean {
+  if (filter.type === 'timestamp') {
+    return true;
+  }
+  if (filter.type === 'and' || filter.type === 'or') {
+    return filter.filters.some(filterContainsTimestamp);
+  }
+  if (filter.type === 'not') {
+    return filterContainsTimestamp(filter.filter);
   }
+  return false;
 }