@dxos/echo 0.8.4-main.c85a9c8dae → 0.8.4-main.d05539e30a

package/src/internal/{object → Obj}/create-object.test.ts

@@ -2,19 +2,17 @@
 // Copyright 2025 DXOS.org
 //
 
-import { inspect } from 'util';
-
 import * as Schema from 'effect/Schema';
+import { inspect } from 'util';
 import { describe, expect, test } from 'vitest';
 
 import { DXN } from '@dxos/keys';
 
 import { Relation } from '../../index';
 import { TestSchema } from '../../testing';
-import { getSchemaDXN, getTypeDXN, isInstanceOf } from '../annotations';
-import { ATTR_RELATION_SOURCE, ATTR_RELATION_TARGET } from '../entities';
-import { ATTR_META, ATTR_TYPE, getSchema } from '../types';
-
+import { getSchemaDXN, getTypeDXN, isInstanceOf } from '../Annotation';
+import { ATTR_META, ATTR_TYPE, getSchema } from '../common/types';
+import { ATTR_RELATION_SOURCE, ATTR_RELATION_TARGET } from '../Entity';
 import { createObject } from './create-object';
 import { objectToJSON } from './json-serializer';
 
@@ -110,7 +108,7 @@ describe('create (static version)', () => {
     const text = inspect(contact);
     expect(text).toContain('Bot');
     expect(text).toContain('bot@example.com');
-    expect(text).toContain('example.com/type/Person');
+    expect(text).toContain('com.example.type.person');
     expect(text).toContain('0.1.0');
   });
 });

package/src/internal/{object → Obj}/create-object.ts

@@ -8,7 +8,9 @@ import { raise } from '@dxos/debug';
 import { assertArgument, failedInvariant } from '@dxos/invariant';
 import { ObjectId } from '@dxos/keys';
 
-import { getSchemaDXN, getTypeAnnotation, setTypename } from '../annotations';
+import { getSchemaDXN, getTypeAnnotation, setTypename } from '../Annotation';
+import { defineHiddenProperty } from '../common/proxy';
+import { EntityKind, KindId, MetaId, setSchema } from '../common/types';
 import {
   RelationSourceDXNId,
   RelationSourceId,
@@ -16,10 +18,7 @@ import {
   RelationTargetId,
   assertObjectModel,
   getObjectDXN,
-} from '../entities';
-import { defineHiddenProperty } from '../proxy';
-import { EntityKind, KindId, MetaId, setSchema } from '../types';
-
+} from '../Entity';
 import { attachedTypedObjectInspector } from './inspect';
 import { attachTypedJsonSerializer } from './json-serializer';
 
@@ -42,7 +41,7 @@ export type CreateObjectProps<T> = T extends { id: string } ? Omit<T, 'id' | Kin
  *   name: Schema.String,
  *   email: Schema.String,
  * }).pipe(Type.object({
- *   typename: 'example.com/type/Person',
+ *   typename: 'com.example.type.person',
  *   version: '0.1.0',
  * }))
  *

package/src/internal/{object → Obj}/deleted.ts

@@ -2,8 +2,8 @@
 // Copyright 2025 DXOS.org
 //
 
-import { ObjectDeletedId } from '../entities';
-import { type AnyProperties } from '../types';
+import { type AnyProperties } from '../common/types';
+import { ObjectDeletedId } from '../Entity';
 
 /**
  * @returns `true` if the object has been marked as deleted.

package/src/internal/{object → Obj}/ids.ts

@@ -5,7 +5,7 @@
 import { DXN, ObjectId, QueueSubspaceTags, SpaceId } from '@dxos/keys';
 
 /**
- * @deprecated Use `db.queues.create()`
+ * @deprecated Use `Feed.make(...)` + `db.add(feed)` then `Feed.getQueueDxn(feed)`.
  */
 // TODO(burdon): Move to @dxos/keys.
 export const createQueueDXN = (spaceId = SpaceId.random(), queueId = ObjectId.random()) =>

package/src/internal/{object → Obj}/inspect.ts

@@ -6,8 +6,8 @@ import type { InspectOptionsStylized, inspect as inspectFn } from 'node:util';
 
 import { type CustomInspectFunction, inspectCustom } from '@dxos/debug';
 
-import { getTypeDXN } from '../annotations';
-import { ATTR_META, ATTR_TYPE, type AnyEntity, MetaId } from '../types';
+import { getTypeDXN } from '../Annotation';
+import { ATTR_META, ATTR_TYPE, type AnyEntity, MetaId } from '../common/types';
 
 /*
  * @internal

package/src/internal/{object → Obj}/json-serializer.test.ts

@@ -8,21 +8,20 @@ import { DXN } from '@dxos/keys';
 
 import * as Obj from '../../Obj';
 import { TestSchema } from '../../testing';
-import { getSchemaDXN, getSchemaTypename, getTypeDXN, getTypename } from '../annotations';
-import { getMetaChecked } from '../api';
-import { RelationSourceId, RelationTargetId, getObjectDXN } from '../entities';
-import { makeObject } from '../proxy';
-import { Ref, StaticRefResolver } from '../ref';
-import { ATTR_TYPE, EntityKind, KindId, MetaId, TypeId, getSchema } from '../types';
-
+import { getSchemaDXN, getSchemaTypename, getTypeDXN, getTypename } from '../Annotation';
+import { getMetaChecked } from '../common/api';
+import { makeObject } from '../common/proxy';
+import { ATTR_TYPE, EntityKind, KindId, MetaId, TypeId, getSchema } from '../common/types';
+import { RelationSourceId, RelationTargetId, getObjectDXN } from '../Entity';
+import { Ref, StaticRefResolver } from '../Ref';
 import { createObject } from './create-object';
 import { objectFromJSON, objectToJSON } from './json-serializer';
 
 describe('Object JSON serializer', () => {
   test('should serialize and deserialize object', async () => {
     const contact = makeObject(TestSchema.Person, { name: 'Alice' });
-    Obj.change(contact, (c) => {
-      getMetaChecked(c).keys.push({ id: '12345', source: 'example.com' });
+    Obj.update(contact, (contact) => {
+      getMetaChecked(contact).keys.push({ id: '12345', source: 'example.com' });
     });
 
     const task = createObject(TestSchema.Task, {

package/src/internal/{object → Obj}/json-serializer.ts

@@ -10,13 +10,28 @@ import { assertArgument, invariant } from '@dxos/invariant';
 import { DXN, ObjectId } from '@dxos/keys';
 import { assumeType, deepMapValues, visitValues } from '@dxos/util';
 
+import type * as Database from '../../Database';
 import type * as Obj from '../../Obj';
-import { getTypeDXN, setTypename } from '../annotations';
+import { getTypeDXN, setTypename } from '../Annotation';
+import { attachTypedJsonSerializer, defineHiddenProperty, typedJsonSerializer } from '../common/proxy';
+import {
+  ATTR_META,
+  ATTR_PARENT,
+  ATTR_TYPE,
+  type AnyEntity,
+  EntityKind,
+  KindId,
+  MetaId,
+  ObjectMetaSchema,
+  ParentId,
+  setSchema,
+} from '../common/types';
 import {
   ATTR_DELETED,
   ATTR_RELATION_SOURCE,
   ATTR_RELATION_TARGET,
   ATTR_SELF_DXN,
+  ObjectDatabaseId,
   type ObjectJSON,
   RelationSourceDXNId,
   RelationSourceId,
@@ -24,21 +39,8 @@ import {
   RelationTargetId,
   SelfDXNId,
   assertObjectModel,
-} from '../entities';
-import { attachTypedJsonSerializer, defineHiddenProperty, typedJsonSerializer } from '../proxy';
-import { Ref, type RefResolver, refFromEncodedReference, setRefResolver } from '../ref';
-import {
-  ATTR_META,
-  ATTR_PARENT,
-  ATTR_TYPE,
-  type AnyEntity,
-  EntityKind,
-  KindId,
-  MetaId,
-  ObjectMetaSchema,
-  ParentId,
-  setSchema,
-} from '../types';
+} from '../Entity';
+import { Ref, type RefResolver, refFromEncodedReference, setRefResolver } from '../Ref';
 
 // Re-export for backward compatibility.
 export { attachTypedJsonSerializer };
@@ -70,10 +72,20 @@ export const objectToJSON = <T extends AnyEntity>(obj: T): SerializedObject<T> =
  * Performs schema validation.
  * References and schema will be resolvable if the `refResolver` is provided.
  * The function need to be async to support resolving the schema as well as the relation endpoints.
+ *
+ * @param jsonData - JSON representation of the object.
+ * @param options.refResolver - Resolver for references.
+ * @param options.dxn - Override object DXN.
+ * @param options.database - Database to associate with the object.
  */
 export const objectFromJSON = async (
   jsonData: unknown,
-  { refResolver, dxn }: { refResolver?: RefResolver; dxn?: DXN } = {},
+  {
+    refResolver,
+    dxn,
+    database,
+    parent,
+  }: { refResolver?: RefResolver; dxn?: DXN; database?: Database.Database; parent?: Obj.Unknown } = {},
 ): Promise<AnyEntity> => {
   assumeType<ObjectJSON>(jsonData);
   assertArgument(typeof jsonData === 'object' && jsonData !== null, 'jsonData', 'expect object');
@@ -104,15 +116,15 @@ export const objectFromJSON = async (
   const isRelation =
     typeof jsonData[ATTR_RELATION_SOURCE] === 'string' || typeof jsonData[ATTR_RELATION_TARGET] === 'string';
   if (isRelation) {
-    const sourceDxn: DXN = DXN.parse(jsonData[ATTR_RELATION_SOURCE] ?? raise(new TypeError('Missing relation source')));
-    const targetDxn: DXN = DXN.parse(jsonData[ATTR_RELATION_TARGET] ?? raise(new TypeError('Missing relation target')));
+    const sourceDXN: DXN = DXN.parse(jsonData[ATTR_RELATION_SOURCE] ?? raise(new TypeError('Missing relation source')));
+    const targetDXN: DXN = DXN.parse(jsonData[ATTR_RELATION_TARGET] ?? raise(new TypeError('Missing relation target')));
 
-    const source = (await refResolver?.resolve(sourceDxn)) as AnyEntity | undefined;
-    const target = (await refResolver?.resolve(targetDxn)) as AnyEntity | undefined;
+    const source = (await refResolver?.resolve(sourceDXN)) as AnyEntity | undefined;
+    const target = (await refResolver?.resolve(targetDXN)) as AnyEntity | undefined;
 
     defineHiddenProperty(obj, KindId, EntityKind.Relation);
-    defineHiddenProperty(obj, RelationSourceDXNId, sourceDxn);
-    defineHiddenProperty(obj, RelationTargetDXNId, targetDxn);
+    defineHiddenProperty(obj, RelationSourceDXNId, sourceDXN);
+    defineHiddenProperty(obj, RelationTargetDXNId, targetDXN);
     defineHiddenProperty(obj, RelationSourceId, source);
     defineHiddenProperty(obj, RelationTargetId, target);
   } else {
@@ -130,8 +142,10 @@ export const objectFromJSON = async (
   }
 
   if (jsonData[ATTR_PARENT]) {
-    const parentDxn = DXN.parse(jsonData[ATTR_PARENT]);
-    const parent = (await refResolver?.resolve(parentDxn)) as Obj.Unknown | undefined;
+    const parentDXN = DXN.parse(jsonData[ATTR_PARENT]);
+    const resolvedParent = (await refResolver?.resolve(parentDXN)) as Obj.Unknown | undefined;
+    defineHiddenProperty(obj, ParentId, resolvedParent);
+  } else if (parent) {
     defineHiddenProperty(obj, ParentId, parent);
   }
 
@@ -139,6 +153,10 @@ export const objectFromJSON = async (
     defineHiddenProperty(obj, SelfDXNId, dxn);
   }
 
+  if (database) {
+    defineHiddenProperty(obj, ObjectDatabaseId, database);
+  }
+
   assertObjectModel(obj);
   invariant((obj as any)[ATTR_TYPE] === undefined, 'Invalid object model');
   invariant((obj as any)[ATTR_META] === undefined, 'Invalid object model');
@@ -166,7 +184,7 @@ const stripInternalJsonKeys = (jsonData: unknown) => {
     [ATTR_TYPE]: _type,
     [ATTR_META]: _meta,
     [ATTR_DELETED]: _deleted,
-    [ATTR_SELF_DXN]: _selfDxn,
+    [ATTR_SELF_DXN]: _selfDXN,
     [ATTR_RELATION_SOURCE]: _relationSource,
     [ATTR_RELATION_TARGET]: _relationTarget,
     ...props

package/src/internal/{object → Obj}/schema-validator.ts

@@ -3,4 +3,4 @@
 //
 
 // Re-export from proxy for backward compatibility.
-export { SchemaValidator, checkIdNotPresentOnSchema } from '../proxy';
+export { SchemaValidator, checkIdNotPresentOnSchema } from '../common/proxy';

package/src/internal/{object → Obj}/set-value.test.ts

@@ -17,7 +17,7 @@ describe('Obj.setValue', () => {
       email: 'john@example.com',
     });
 
-    Obj.change(person, (p) => Obj.setValue(p, ['address', 'city'], 'NYC'));
+    Obj.update(person, (person) => Obj.setValue(person, ['address', 'city'], 'NYC'));
 
     expect(person.address).toBeDefined();
     expect(person.address?.city).toBe('NYC');
@@ -30,7 +30,7 @@ describe('Obj.setValue', () => {
       email: 'john@example.com',
     });
 
-    Obj.change(person, (p) => Obj.setValue(p, ['fields', 0, 'label'], 'Phone'));
+    Obj.update(person, (person) => Obj.setValue(person, ['fields', 0, 'label'], 'Phone'));
 
     expect(Array.isArray(person.fields)).toBe(true);
     expect(person.fields?.[0].label).toBe('Phone');
@@ -45,7 +45,7 @@ describe('Obj.setValue', () => {
       email: 'john@example.com',
     });
 
-    Obj.change(person, (p) => Obj.setValue(p, ['address', 'coordinates', 'lat'], 40.7128));
+    Obj.update(person, (person) => Obj.setValue(person, ['address', 'coordinates', 'lat'], 40.7128));
 
     expect(person.address).toBeDefined();
     expect(person.address?.coordinates).toBeDefined();
@@ -69,10 +69,10 @@ describe('Obj.setValue', () => {
 
     const container = Obj.make(Container, { name: 'box' });
 
-    Obj.change(container, (c) => {
-      Obj.setValue(c, ['items', 0, 'value'], 10);
-      Obj.setValue(c, ['items', 1, 'value'], 20);
-      Obj.setValue(c, ['items', 2, 'value'], 30);
+    Obj.update(container, (container) => {
+      Obj.setValue(container, ['items', 0, 'value'], 10);
+      Obj.setValue(container, ['items', 1, 'value'], 20);
+      Obj.setValue(container, ['items', 2, 'value'], 30);
     });
 
     expect(container.items).toHaveLength(3);
@@ -88,7 +88,7 @@ describe('Obj.setValue', () => {
       email: 'john@example.com',
     });
 
-    Obj.change(person, (p) => Obj.setValue(p, ['age'], 25));
+    Obj.update(person, (person) => Obj.setValue(person, ['age'], 25));
 
     expect(person.age).toBe(25);
   });
@@ -100,7 +100,7 @@ describe('Obj.setValue', () => {
       email: 'john@example.com',
     });
 
-    Obj.change(person, (p) => Obj.setValue(p, ['address', 'city'], 'NYC'));
+    Obj.update(person, (person) => Obj.setValue(person, ['address', 'city'], 'NYC'));
 
     expect(person.address).toBeDefined();
     expect(person.address?.city).toBe('NYC');
@@ -114,8 +114,8 @@ describe('Obj.setValue', () => {
     });
 
     let result: any;
-    Obj.change(person, (p) => {
-      result = Obj.setValue(p, ['age'], 30);
+    Obj.update(person, (person) => {
+      result = Obj.setValue(person, ['age'], 30);
     });
 
     expect(result).toBe(30);
@@ -129,7 +129,7 @@ describe('Obj.setValue', () => {
       age: 25,
     });
 
-    Obj.change(person, (p) => Obj.setValue(p, ['age'], 30));
+    Obj.update(person, (person) => Obj.setValue(person, ['age'], 30));
 
     expect(person.age).toBe(30);
   });
@@ -142,7 +142,7 @@ describe('Obj.setValue', () => {
       address: { city: 'Boston', state: 'MA', coordinates: {} },
     });
 
-    Obj.change(person, (p) => Obj.setValue(p, ['address', 'city'], 'NYC'));
+    Obj.update(person, (person) => Obj.setValue(person, ['address', 'city'], 'NYC'));
 
     expect(person.address?.city).toBe('NYC');
     expect(person.address?.state).toBe('MA');
@@ -160,11 +160,11 @@ describe('Obj.setValue', () => {
 
     const matrix = Obj.make(Matrix, {});
 
-    Obj.change(matrix, (m) => {
-      Obj.setValue(m, ['values', 0, 0], 1);
-      Obj.setValue(m, ['values', 0, 1], 2);
-      Obj.setValue(m, ['values', 1, 0], 3);
-      Obj.setValue(m, ['values', 1, 1], 4);
+    Obj.update(matrix, (matrix) => {
+      Obj.setValue(matrix, ['values', 0, 0], 1);
+      Obj.setValue(matrix, ['values', 0, 1], 2);
+      Obj.setValue(matrix, ['values', 1, 0], 3);
+      Obj.setValue(matrix, ['values', 1, 1], 4);
     });
 
     expect(matrix.values?.[0][0]).toBe(1);
@@ -180,8 +180,8 @@ describe('Obj.setValue', () => {
       email: 'john@example.com',
     });
 
-    Obj.change(person, (p) => {
-      expect(() => Obj.setValue(p, [], 'value')).toThrow('Path must not be empty');
+    Obj.update(person, (person) => {
+      expect(() => Obj.setValue(person, [], 'value')).toThrow('Path must not be empty');
     });
   });
 
@@ -192,7 +192,7 @@ describe('Obj.setValue', () => {
       email: 'john@example.com',
     });
 
-    Obj.change(person, (p) => Obj.setValue(p, ['age'], 30));
+    Obj.update(person, (person) => Obj.setValue(person, ['age'], 30));
 
     expect(person.age).toBe(30);
   });
@@ -215,7 +215,7 @@ describe('Obj.setValue', () => {
     const container = Obj.make(Container, { name: 'box' });
 
     // Using string '0' for array index.
-    Obj.change(container, (c) => Obj.setValue(c, ['items', '0', 'value'], 42));
+    Obj.update(container, (container) => Obj.setValue(container, ['items', '0', 'value'], 42));
 
     expect(container.items?.[0].value).toBe(42);
   });
@@ -243,7 +243,7 @@ describe('Obj.setValue', () => {
 
     // This should work: setting a nested property on an array element.
     // The required 'id' field should be initialized with a default value.
-    Obj.change(todoList, (t) => Obj.setValue(t, ['tasks', 0, 'title'], 'Buy groceries'));
+    Obj.update(todoList, (todoList) => Obj.setValue(todoList, ['tasks', 0, 'title'], 'Buy groceries'));
 
     expect(todoList.tasks?.[0].id).toBe(''); // Default value for required String
     expect(todoList.tasks?.[0].title).toBe('Buy groceries');
@@ -270,7 +270,7 @@ describe('Obj.setValue', () => {
 
     const container = Obj.make(Container, { name: 'box' });
 
-    Obj.change(container, (c) => Obj.setValue(c, ['items', 0, 'label'], 'First Item'));
+    Obj.update(container, (container) => Obj.setValue(container, ['items', 0, 'label'], 'First Item'));
 
     // All required primitive fields should have default values.
     expect(container.items?.[0].id).toBe('');

package/src/internal/{object → Obj}/set-value.ts

@@ -16,12 +16,12 @@ import {
 } from '@dxos/effect';
 import { invariant } from '@dxos/invariant';
 
-import { type Mutable } from '../proxy';
-import { getSchema } from '../types';
+import { type Mutable } from '../common/proxy';
+import { getSchema } from '../common/types';
 
 /**
  * Set a deeply nested property on an object.
- * Must be called within an Obj.change or Relation.change callback.
+ * Must be called within an Obj.update or Relation.update callback.
  */
 export const setValue = (obj: Mutable<any>, path: readonly (string | number)[], value: any): void => {
   invariant(path.length > 0, 'Path must not be empty');

package/src/internal/{object → Obj}/snapshot.ts

@@ -5,11 +5,20 @@
 import { assertArgument } from '@dxos/invariant';
 import { deepMapValues } from '@dxos/util';
 
-import { ObjectDatabaseId, ObjectDeletedId, SelfDXNId } from '../entities/model';
-import { RelationSourceDXNId, RelationSourceId, RelationTargetDXNId, RelationTargetId } from '../entities/relation';
-import { KindId, SnapshotKindId } from '../types/entity';
-import { MetaId } from '../types/meta';
-import { SchemaId, TypeId } from '../types/typename';
+import {
+  KindId,
+  MetaId,
+  ObjectDatabaseId,
+  ObjectDeletedId,
+  RelationSourceDXNId,
+  RelationSourceId,
+  RelationTargetDXNId,
+  RelationTargetId,
+  SchemaId,
+  SelfDXNId,
+  SnapshotKindId,
+  TypeId,
+} from '../common/types';
 
 /**
  * Copy a Symbol-keyed property from source to target if it has a defined value.

package/src/internal/{object → Obj}/typed-object.test.ts

@@ -6,13 +6,13 @@ import * as Schema from 'effect/Schema';
 import * as SchemaAST from 'effect/SchemaAST';
 import { describe, expect, test } from 'vitest';
 
-import { EchoObjectSchema } from '../entities';
+import { EchoObjectSchema } from '../Entity';
 
 const Organization = Schema.Struct({
   name: Schema.String,
 }).pipe(
   EchoObjectSchema({
-    typename: 'example.com/type/Organization',
+    typename: 'com.example.type.organization',
     version: '0.1.0',
   }),
 );
@@ -25,7 +25,7 @@ describe('EchoObjectSchema DSL', () => {
   });
 
   test('static typename accessor', async () => {
-    expect(Organization.typename).to.eq('example.com/type/Organization');
+    expect(Organization.typename).to.eq('com.example.type.organization');
   });
 
   test('expect schema', async () => {

package/src/internal/{object → Obj}/typed-object.ts

@@ -4,8 +4,8 @@
 
 import type * as Schema from 'effect/Schema';
 
-import { type TypeMeta } from '../annotations';
-import { type AnyEntity } from '../types';
+import { type TypeMeta } from '../Annotation';
+import { type AnyEntity } from '../common/types';
 
 /**
  * Definition for an object type that can be stored in an ECHO database.

package/src/internal/Query.ts

@@ -0,0 +1,156 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type QueryAST } from '@dxos/echo-protocol';
+
+/**
+ * Returns a human-readable string representation of a Filter AST.
+ */
+export const prettyFilter = (filter: QueryAST.Filter): string => {
+  switch (filter.type) {
+    case 'object': {
+      // A type-less object filter with only a meta-key constraint is `Filter.key(...)`.
+      if (
+        filter.typename === null &&
+        (filter.id === undefined || filter.id.length === 0) &&
+        Object.keys(filter.props).length === 0 &&
+        (filter.foreignKeys === undefined || filter.foreignKeys.length === 0) &&
+        filter.metaKey !== undefined
+      ) {
+        return filter.metaVersion !== undefined
+          ? `Filter.key(${JSON.stringify(filter.metaKey)}, { version: ${JSON.stringify(filter.metaVersion)} })`
+          : `Filter.key(${JSON.stringify(filter.metaKey)})`;
+      }
+      const parts: string[] = [];
+      if (filter.typename !== null) {
+        parts.push(String(filter.typename));
+      }
+      if (filter.id !== undefined && filter.id.length > 0) {
+        parts.push(`id: [${filter.id.join(', ')}]`);
+      }
+      const propEntries = Object.entries(filter.props);
+      if (propEntries.length > 0) {
+        const propsStr = propEntries.map(([k, v]) => `${k}: ${prettyFilter(v)}`).join(', ');
+        parts.push(`{ ${propsStr} }`);
+      }
+      if (filter.foreignKeys !== undefined && filter.foreignKeys.length > 0) {
+        parts.push(`foreignKeys: [${filter.foreignKeys.map((fk) => JSON.stringify(fk)).join(', ')}]`);
+      }
+      if (filter.metaKey !== undefined) {
+        parts.push(
+          filter.metaVersion !== undefined
+            ? `metaKey: ${JSON.stringify(filter.metaKey)} (${filter.metaVersion})`
+            : `metaKey: ${JSON.stringify(filter.metaKey)}`,
+        );
+      }
+      return parts.length > 0 ? `Filter.type(${parts.join(', ')})` : 'Filter.everything()';
+    }
+    case 'compare':
+      return `Filter.${filter.operator}(${JSON.stringify(filter.value)})`;
+    case 'in':
+      return `Filter.in([${filter.values.map((v) => JSON.stringify(v)).join(', ')}])`;
+    case 'contains':
+      return `Filter.contains(${JSON.stringify(filter.value)})`;
+    case 'tag':
+      return `Filter.tag(${JSON.stringify(filter.tag)})`;
+    case 'range':
+      return `Filter.range(${JSON.stringify(filter.from)}, ${JSON.stringify(filter.to)})`;
+    case 'text-search':
+      return filter.searchKind
+        ? `Filter.textSearch(${JSON.stringify(filter.text)}, ${JSON.stringify(filter.searchKind)})`
+        : `Filter.textSearch(${JSON.stringify(filter.text)})`;
+    case 'timestamp':
+      return `Filter.${filter.field}.${filter.operator}(${filter.value})`;
+    case 'child-of':
+      return `Filter.childOf([${filter.parents.map((p) => JSON.stringify(p)).join(', ')}], { transitive: ${filter.transitive} })`;
+    case 'not':
+      return `Filter.not(${prettyFilter(filter.filter)})`;
+    case 'and':
+      return `Filter.and(${filter.filters.map(prettyFilter).join(', ')})`;
+    case 'or':
+      return `Filter.or(${filter.filters.map(prettyFilter).join(', ')})`;
+  }
+};
+
+/**
+ * Returns a human-readable string representation of a Query AST.
+ */
+export const prettyQuery = (query: QueryAST.Query): string => {
+  switch (query.type) {
+    case 'select':
+      return `Query.select(${prettyFilter(query.filter)})`;
+    case 'filter':
+      return `${prettyQuery(query.selection)}.select(${prettyFilter(query.filter)})`;
+    case 'reference-traversal':
+      return `${prettyQuery(query.anchor)}.reference(${JSON.stringify(query.property)})`;
+    case 'incoming-references': {
+      const args: string[] = [];
+      if (query.typename !== null) {
+        args.push(String(query.typename));
+      }
+      if (query.property !== null) {
+        args.push(JSON.stringify(query.property));
+      }
+      return `${prettyQuery(query.anchor)}.referencedBy(${args.join(', ')})`;
+    }
+    case 'relation': {
+      const method =
+        query.direction === 'outgoing' ? 'sourceOf' : query.direction === 'incoming' ? 'targetOf' : 'relationOf';
+      const filterStr = query.filter !== undefined ? prettyFilter(query.filter) : '';
+      return `${prettyQuery(query.anchor)}.${method}(${filterStr})`;
+    }
+    case 'relation-traversal':
+      return `${prettyQuery(query.anchor)}.${query.direction}()`;
+    case 'hierarchy-traversal':
+      return query.direction === 'to-parent'
+        ? `${prettyQuery(query.anchor)}.parent()`
+        : `${prettyQuery(query.anchor)}.children()`;
+    case 'union':
+      return `Query.all(${query.queries.map(prettyQuery).join(', ')})`;
+    case 'set-difference':
+      return `Query.without(${prettyQuery(query.source)}, ${prettyQuery(query.exclude)})`;
+    case 'order': {
+      const orders = query.order.map((o) => {
+        if (o.kind === 'natural') {
+          return 'Order.natural()';
+        } else if (o.kind === 'rank') {
+          return `Order.rank(${JSON.stringify(o.direction)})`;
+        } else {
+          return `Order.property(${JSON.stringify(o.property)}, ${JSON.stringify(o.direction)})`;
+        }
+      });
+      return `${prettyQuery(query.query)}.orderBy(${orders.join(', ')})`;
+    }
+    case 'options': {
+      const opts = query.options;
+      const parts: string[] = [];
+      if (opts.deleted !== undefined) {
+        parts.push(`deleted: ${JSON.stringify(opts.deleted)}`);
+      }
+      if (opts.debugLabel !== undefined) {
+        parts.push(`debugLabel: ${JSON.stringify(opts.debugLabel)}`);
+      }
+      return `${prettyQuery(query.query)}.options({ ${parts.join(', ')} })`;
+    }
+    case 'from': {
+      if (query.from._tag === 'scope') {
+        const scope = query.from.scope;
+        const parts: string[] = [];
+        if (scope.spaceIds !== undefined) {
+          parts.push(`spaceIds: [${scope.spaceIds.map((s) => JSON.stringify(s)).join(', ')}]`);
+        }
+        if (scope.feeds !== undefined) {
+          parts.push(`feeds: [${scope.feeds.map(String).join(', ')}]`);
+        }
+        if (scope.allFeedsFromSpaces !== undefined) {
+          parts.push(`allFeedsFromSpaces: ${scope.allFeedsFromSpaces}`);
+        }
+        return `${prettyQuery(query.query)}.from({ ${parts.join(', ')} })`;
+      }
+      return `${prettyQuery(query.query)}.from(${prettyQuery(query.from.query)})`;
+    }
+    case 'limit':
+      return `${prettyQuery(query.query)}.limit(${query.limit})`;
+  }
+};

package/src/internal/{ref → Ref}/ref-array.ts

@@ -5,8 +5,7 @@
 import { type ObjectId } from '@dxos/keys';
 import { isNonNullable } from '@dxos/util';
 
-import { type AnyEntity } from '../types';
-
+import { type AnyEntity } from '../common/types';
 import { Ref } from './ref';
 
 /**