@dxos/echo 0.8.4-main.422d1c7879 → 0.8.4-main.4f23b4e393

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/echo",
-  "version": "0.8.4-main.422d1c7879",
+  "version": "0.8.4-main.4f23b4e393",
   "description": "ECHO API",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -135,18 +135,18 @@
   ],
   "dependencies": {
     "effect": "3.20.0",
-    "@dxos/async": "0.8.4-main.422d1c7879",
-    "@dxos/context": "0.8.4-main.422d1c7879",
-    "@dxos/debug": "0.8.4-main.422d1c7879",
-    "@dxos/echo-protocol": "0.8.4-main.422d1c7879",
-    "@dxos/effect": "0.8.4-main.422d1c7879",
-    "@dxos/keys": "0.8.4-main.422d1c7879",
-    "@dxos/errors": "0.8.4-main.422d1c7879",
-    "@dxos/log": "0.8.4-main.422d1c7879",
-    "@dxos/invariant": "0.8.4-main.422d1c7879",
-    "@dxos/node-std": "0.8.4-main.422d1c7879",
-    "@dxos/util": "0.8.4-main.422d1c7879",
-    "@dxos/protocols": "0.8.4-main.422d1c7879"
+    "@dxos/context": "0.8.4-main.4f23b4e393",
+    "@dxos/async": "0.8.4-main.4f23b4e393",
+    "@dxos/debug": "0.8.4-main.4f23b4e393",
+    "@dxos/echo-protocol": "0.8.4-main.4f23b4e393",
+    "@dxos/effect": "0.8.4-main.4f23b4e393",
+    "@dxos/errors": "0.8.4-main.4f23b4e393",
+    "@dxos/invariant": "0.8.4-main.4f23b4e393",
+    "@dxos/keys": "0.8.4-main.4f23b4e393",
+    "@dxos/log": "0.8.4-main.4f23b4e393",
+    "@dxos/node-std": "0.8.4-main.4f23b4e393",
+    "@dxos/protocols": "0.8.4-main.4f23b4e393",
+    "@dxos/util": "0.8.4-main.4f23b4e393"
   },
   "publishConfig": {
     "access": "public"

package/src/Annotation.ts

@@ -18,6 +18,7 @@ export {
   setDescriptionWithSchema,
   setLabelWithSchema,
   IconAnnotation,
+  IconFromRefAnnotation,
 } from './internal/Annotation';
 
 import type * as Schema from 'effect/Schema';

package/src/Collection.ts

@@ -25,7 +25,7 @@ export const Collection = Schema.Struct({
   }),
   Annotation.IconAnnotation.set({
     icon: 'ph--folder--regular',
-    hue: 'neutral',
+    hue: 'amber',
   }),
 );
 

package/src/Database.ts

@@ -38,7 +38,7 @@ export interface QueryFn {
 }
 
 /**
- * Common interface for Database and Queue.
+ * Common interface for Database, Feed, and Hypergraph.
  */
 export interface Queryable {
   query: QueryFn;

package/src/Entity.ts

@@ -198,7 +198,7 @@ export const subscribe = (entity: Unknown, callback: () => void): (() => void) =
 //
 
 /**
- * Used to provide a mutable view of an entity within `Entity.change`.
+ * Used to provide a mutable view of an entity within `Entity.update`.
  */
 export type Mutable<T> = internal.Mutable<T>;
 
@@ -206,7 +206,7 @@ export type Mutable<T> = internal.Mutable<T>;
  * Perform mutations on an entity (object or relation) within a change context.
  *
  * Entities are read-only by default. Mutations are batched and notifications fire
- * when the callback completes. Direct mutations outside of `Entity.change` will throw
+ * when the callback completes. Direct mutations outside of `Entity.update` will throw
  * at runtime.
  *
  * @param entity - The echo entity (object or relation) to mutate.
@@ -214,30 +214,30 @@ export type Mutable<T> = internal.Mutable<T>;
  *
  * @example
  * ```typescript
- * // Mutate within Entity.change
- * Entity.change(entity, (obj) => {
+ * // Mutate within Entity.update
+ * Entity.update(entity, (obj) => {
  *   obj.name = 'Updated';
  *   obj.count = 42;
  * });
  *
  * // Direct mutation throws
- * entity.name = 'Bob'; // Error: Cannot modify outside Entity.change()
+ * entity.name = 'Bob'; // Error: Cannot modify outside Entity.update()
  * ```
  *
- * Note: For type-specific operations, prefer `Obj.change` or `Relation.change`.
+ * Note: For type-specific operations, prefer `Obj.update` or `Relation.update`.
  */
-export const change = <T extends Unknown>(entity: T, callback: internal.ChangeCallback<T>): void => {
+export const update = <T extends Unknown>(entity: T, callback: internal.ChangeCallback<T>): void => {
   internal.change(entity, callback);
 };
 
 /**
  * Add a tag to an entity.
- * Must be called within an `Entity.change`, `Obj.change`, or `Relation.change` callback.
+ * Must be called within an `Entity.update`, `Obj.update`, or `Relation.update` callback.
  */
 export const addTag = (entity: Mutable<Unknown>, tag: string): void => internal.addTag(entity, tag);
 
 /**
  * Remove a tag from an entity.
- * Must be called within an `Entity.change`, `Obj.change`, or `Relation.change` callback.
+ * Must be called within an `Entity.update`, `Obj.update`, or `Relation.update` callback.
  */
 export const removeTag = (entity: Mutable<Unknown>, tag: string): void => internal.removeTag(entity, tag);

package/src/Extension.ts

@@ -43,7 +43,7 @@ export interface Extension<T> extends Record<
  *   email: 'john@example.com',
  * });
  *
- * Obj.change(obj, (obj) => {
+ * Obj.update(obj, (obj) => {
  *   Extension.set(obj.extensions, ColorExtension, 'red');
  * });
  *
@@ -103,10 +103,10 @@ export const get: {
 /**
  * Set the value of an extension in a set of values.
  *
- * Can also be used within Obj.change callback:
+ * Can also be used within Obj.update callback:
  *
  * ```ts
- * Obj.change(obj, (obj) => {
+ * Obj.update(obj, (obj) => {
  *   Extension.set(obj.extensions, ColorExtension, 'red');
  * });
  * ```

package/src/Feed.ts

@@ -10,7 +10,7 @@ import * as Layer from 'effect/Layer';
 import type * as Option from 'effect/Option';
 import * as Schema from 'effect/Schema';
 
-import { DXN, type ObjectId } from '@dxos/keys';
+import { DXN } from '@dxos/keys';
 
 import * as Annotation from './Annotation';
 import type * as Entity from './Entity';
@@ -80,6 +80,16 @@ export interface RetentionOptions {
   cursor?: string;
 }
 
+/**
+ * Sync options for a feed.
+ */
+export interface SyncOptions {
+  /** Push local changes to the server. Defaults to true. */
+  shouldPush?: boolean;
+  /** Pull remote changes from the server. Defaults to true. */
+  shouldPull?: boolean;
+}
+
 //
 // Factory
 //
@@ -109,27 +119,6 @@ export const getQueueDxn = (feed: Feed): DXN | undefined => {
   return new DXN(DXN.kind.QUEUE, [feed.namespace ?? 'data', self.spaceId, self.echoId]);
 };
 
-/**
- * Creates a Feed object from a queue DXN, inferring the feed's id and namespace from the DXN parts.
- *
- * The resulting Feed, when added to the same space as the queue, will have a queue DXN
- * equal to the input (see `Feed.getQueueDxn`). Useful when migrating `Ref(Queue)` fields to
- * `Ref(Feed.Feed)`.
- *
- * @remarks Unsafe because the caller must ensure the queue DXN's space matches the database
- * the feed is added to; the feed id is set from the queue id, bypassing id generation.
- */
-export const unsafeFromQueueDXN = (queueDxn: DXN): Feed => {
-  const parts = queueDxn.asQueueDXN();
-  if (!parts) {
-    throw new Error(`Expected a queue DXN, got: ${queueDxn.toString()}`);
-  }
-  return Obj.make(Feed, {
-    id: parts.queueId as ObjectId,
-    namespace: parts.subspaceTag === 'trace' ? 'trace' : undefined,
-  });
-};
-
 //
 // Service
 //
@@ -160,6 +149,11 @@ export class FeedService extends Context.Tag('@dxos/echo/Feed/FeedService')<
       <Q extends Query.Any>(feed: Feed, query: Q): QueryResult.QueryResult<Query.Type<Q>>;
       <F extends Filter.Any>(feed: Feed, filter: F): QueryResult.QueryResult<Filter.Type<F>>;
     };
+
+    /**
+     * Syncs the feed with the server.
+     */
+    sync(feed: Feed, options?: SyncOptions): Promise<void>;
   }
 >() {}
 
@@ -187,8 +181,30 @@ export const notAvailable: Layer.Layer<FeedService> = Layer.succeed(FeedService,
   query: () => {
     throw new Error('Feed.FeedService not available');
   },
+  sync: () => {
+    throw new Error('Feed.FeedService not available');
+  },
 } as Context.Tag.Service<FeedService>);
 
+//
+// Context (per-call) service
+//
+
+/**
+ * Effect service exposing a single `Feed.Feed` as the "current" feed for a call site.
+ *
+ * @deprecated Prefer threading a `Feed.Feed` explicitly through function signatures
+ * over hiding it behind a context service.
+ */
+export class ContextFeedService extends Context.Tag('@dxos/echo/Feed/ContextFeedService')<
+  ContextFeedService,
+  {
+    readonly feed: Feed;
+  }
+>() {
+  static layer = (feed: Feed): Layer.Layer<ContextFeedService> => Layer.succeed(ContextFeedService, { feed });
+}
+
 //
 // Operations
 //
@@ -262,6 +278,21 @@ export const runQuery: {
 } = (feed: Feed, queryOrFilter: Query.Any | Filter.Any) =>
   query(feed, queryOrFilter as any).pipe(Effect.flatMap((queryResult) => Effect.promise(() => queryResult.run())));
 
+/**
+ * Syncs the feed with the server.
+ *
+ * @example
+ * ```ts
+ * yield* Feed.sync(feed);
+ * yield* Feed.sync(feed, { shouldPush: false });
+ * ```
+ */
+export const sync = (feed: Feed, options?: SyncOptions): Effect.Effect<void, never, FeedService> =>
+  Effect.gen(function* () {
+    const service = yield* FeedService;
+    yield* Effect.promise(() => service.sync(feed, options));
+  });
+
 /**
  * Creates a cursor for iterating over feed items.
  * Currently stubbed — cursor operations are not yet implemented.
@@ -292,13 +323,13 @@ export const nextOption = <T = Obj.Snapshot>(_cursor: Cursor<T>): Effect.Effect<
 
 /**
  * Sets the local retention policy for a feed.
- * Currently stubbed — queues do not yet support retention.
+ * Currently stubbed — feeds do not yet support retention.
  *
  * @example
  * ```ts
  * yield* Feed.setRetention(feed, { count: 1000 });
  * ```
  */
-// TODO(feed): Implement when queue retention is supported.
+// TODO(dmaretskyi): Implement when feed retention is supported.
 export const setRetention = (_feed: Feed, _options: RetentionOptions): Effect.Effect<void, never, FeedService> =>
   Effect.void;

package/src/Hypergraph.ts

@@ -22,10 +22,10 @@ export interface RefResolutionContext {
   space?: Key.SpaceId;
 
   /**
-   * Queue that the resolution is happening from.
-   * This queue will be searched first, and then the space it belongs to.
+   * Feed that the resolution is happening from (as the underlying queue DXN).
+   * This feed will be searched first, and then the space it belongs to.
    */
-  queue?: DXN;
+  feed?: DXN;
 }
 
 export interface RefResolverOptions {

package/src/Obj.test.ts

@@ -117,7 +117,7 @@ describe('Obj', () => {
 
     test('returns keys from reactive object and snapshot', ({ expect }) => {
       const obj = Obj.make(TestSchema.Person, { name: 'Test' });
-      Obj.change(obj, (obj) => {
+      Obj.update(obj, (obj) => {
         const meta = Obj.getMeta(obj);
         meta.keys.push({ source: SOURCE, id: 'key-1' });
         meta.keys.push({ source: SOURCE, id: 'key-2' });
@@ -166,7 +166,7 @@ describe('Obj', () => {
 
       const cloned = Obj.clone(original);
 
-      Obj.change(original, (original) => {
+      Obj.update(original, (original) => {
         original.name = 'Bob';
       });
 
@@ -206,7 +206,7 @@ describe('Obj', () => {
       expect(cloned.employer?.target).toBe(person.employer?.target);
 
       // Modifying the referenced object affects both
-      Obj.change(employer, (employer) => {
+      Obj.update(employer, (employer) => {
         employer.name = 'Updated DXOS';
       });
 
@@ -234,7 +234,7 @@ describe('Obj', () => {
       expect(cloned.employer?.target?.name).toBe(employer.name);
 
       // Modifying the original referenced object does not affect the clone
-      Obj.change(employer, (employer) => {
+      Obj.update(employer, (employer) => {
         employer.name = 'Updated DXOS';
       });
 
@@ -333,7 +333,7 @@ describe('Obj', () => {
       expect(cloned.address?.coordinates.lng).toBe(-122.4194);
 
       // Modifying nested properties should be independent
-      Obj.change(person, (person) => {
+      Obj.update(person, (person) => {
         person.address!.city = 'New York';
       });
 
@@ -366,7 +366,7 @@ describe('Obj', () => {
       expect(cloned.tasks?.[2]?.target).not.toBe(task3);
 
       // Modifying original tasks should not affect cloned ones
-      Obj.change(task1, (task1) => {
+      Obj.update(task1, (task1) => {
         task1.title = 'Updated Task 1';
       });
 
@@ -449,7 +449,7 @@ describe('Obj', () => {
     test('returns false when values already match', () => {
       const target = Obj.make(TestSchema.Organization, { name: 'Acme', properties: { region: 'EU' } });
       const source = Obj.make(TestSchema.Organization, { name: 'Acme', properties: { region: 'EU' } });
-      Obj.change(target, (target) => {
+      Obj.update(target, (target) => {
         expect(Obj.updateFrom(target, source)).toBe(false);
       });
     });
@@ -463,7 +463,7 @@ describe('Obj', () => {
         name: 'New',
         properties: { a: '2', b: '3' },
       });
-      Obj.change(target, (target) => {
+      Obj.update(target, (target) => {
         expect(Obj.updateFrom(target, source)).toBe(true);
       });
       expect(target.name).toBe('New');
@@ -487,7 +487,7 @@ describe('Obj', () => {
         employer: Ref.make(orgB),
         address: { city: 'Portland', state: 'OR', zip: '97201', coordinates: { lat: 45.5, lng: -122.6 } },
       });
-      Obj.change(target, (target) => {
+      Obj.update(target, (target) => {
         expect(Obj.updateFrom(target, source)).toBe(true);
       });
       expect(target.employer?.dxn.toString()).toBe(Ref.make(orgB).dxn.toString());
@@ -510,7 +510,7 @@ describe('Obj', () => {
         email: 'bob@x.test',
         tasks: [Ref.make(t1), Ref.make(t3)],
       });
-      Obj.change(target, (target) => {
+      Obj.update(target, (target) => {
         expect(Obj.updateFrom(target, source)).toBe(true);
       });
       expect(target.tasks?.map((r) => r.dxn.toString())).toEqual(source.tasks?.map((r) => r.dxn.toString()));
@@ -519,7 +519,7 @@ describe('Obj', () => {
     test('respects include option', () => {
       const target = Obj.make(TestSchema.Organization, { name: 'Keep', properties: { x: '1' } });
       const source = Obj.make(TestSchema.Organization, { name: 'Drop', properties: { x: '2' } });
-      Obj.change(target, (target) => {
+      Obj.update(target, (target) => {
         expect(Obj.updateFrom(target, source, { include: ['properties'] })).toBe(true);
       });
       expect(target.name).toBe('Keep');
@@ -529,7 +529,7 @@ describe('Obj', () => {
     test('respects exclude option', () => {
       const target = Obj.make(TestSchema.Organization, { name: 'Old', properties: { x: '1' } });
       const source = Obj.make(TestSchema.Organization, { name: 'New', properties: { x: '2' } });
-      Obj.change(target, (target) => {
+      Obj.update(target, (target) => {
         expect(Obj.updateFrom(target, source, { exclude: ['name'] })).toBe(true);
       });
       expect(target.name).toBe('Old');

package/src/Obj.ts

@@ -304,7 +304,7 @@ export const clone: <T extends Unknown>(obj: T, opts?: CloneOptions) => T = objI
 
 /**
  * Makes all properties mutable recursively.
- * Used to provide a mutable view of an object within `Obj.change`.
+ * Used to provide a mutable view of an object within `Obj.update`.
  */
 export type Mutable<T> = internal.Mutable<T>;
 
@@ -312,33 +312,33 @@ export type Mutable<T> = internal.Mutable<T>;
  * Perform mutations on an echo object within a controlled context.
  *
  * All mutations within the callback are batched and trigger a single notification
- * when the callback completes. Direct mutations outside of `Obj.change` will throw
+ * when the callback completes. Direct mutations outside of `Obj.update` will throw
  * an error for echo objects.
  *
  * This function also works with nested objects within echo objects (e.g., Template structs)
  * that are reactive at runtime.
  *
- * @param obj - The echo object to mutate. Use `Relation.change` for relations.
+ * @param obj - The echo object to mutate. Use `Relation.update` for relations.
  * @param callback - The callback that performs mutations on the object.
  *
  * @example
  * ```ts
  * const person = Obj.make(Person, { name: 'John', age: 25 });
  *
- * // Mutate within Obj.change
- * Obj.change(person, (obj) => {
+ * // Mutate within Obj.update
+ * Obj.update(person, (obj) => {
  *   obj.name = 'Jane';
  *   obj.age = 30;
  * });
  * // ONE notification fires here
  *
  * // Direct mutation throws
- * person.name = 'Bob'; // Error: Cannot modify outside Obj.change()
+ * person.name = 'Bob'; // Error: Cannot modify outside Obj.update()
  * ```
  *
- * Note: Only accepts objects. Use `Relation.change` for relations.
+ * Note: Only accepts objects. Use `Relation.update` for relations.
  */
-export const change = <T extends Unknown>(obj: T, callback: internal.ChangeCallback<T>): void => {
+export const update = <T extends Unknown>(obj: T, callback: internal.ChangeCallback<T>): void => {
   internal.change(obj, callback);
 };
 
@@ -373,7 +373,7 @@ export const getValue = (obj: Unknown | Snapshot, path: readonly (string | numbe
  * whether to initialize nested data as an empty object or array.
  *
  * Similar to lodash.set and setDeep from @dxos/util, but schema-aware.
- * Must be called within an `Obj.change` callback.
+ * Must be called within an `Obj.update` callback.
  *
  * NOTE: TypeScript's structural typing allows readonly objects to be passed to `Mutable<T>`
  * parameters, so there is no compile-time error. Enforcement is runtime-only.
@@ -387,7 +387,7 @@ export const getValue = (obj: Unknown | Snapshot, path: readonly (string | numbe
  * ```ts
  * const person = Obj.make(Person, { name: 'John' });
  * // Person schema has: addresses: Schema.Array(Address)
- * Obj.change(person, (obj) => {
+ * Obj.update(person, (obj) => {
  *   Obj.setValue(obj, ['addresses', 0, 'street'], '123 Main St');
  * });
  * // Creates: person.addresses = [{ street: '123 Main St' }]
@@ -520,7 +520,7 @@ export const Meta = internal.MetaId;
 export type ReadonlyMeta = internal.ReadonlyMeta;
 
 /**
- * Mutable meta type returned by `Obj.getMeta` inside an `Obj.change` callback.
+ * Mutable meta type returned by `Obj.getMeta` inside an `Obj.update` callback.
  */
 export type Meta = internal.Meta;
 
@@ -528,7 +528,7 @@ export type Meta = internal.Meta;
 // TODO(dmaretskyi): Allow returning undefined.
 /**
  * Get the metadata for an object.
- * Returns mutable meta when passed a mutable object (inside `Obj.change` callback).
+ * Returns mutable meta when passed a mutable object (inside `Obj.update` callback).
  * Returns read-only meta when passed a regular object or snapshot.
  *
  * @example
@@ -537,7 +537,7 @@ export type Meta = internal.Meta;
  * const meta = Obj.getMeta(person);  // ReadonlyMeta
  *
  * // Mutable access inside change callback
- * Obj.change(person, (obj) => {
+ * Obj.update(person, (obj) => {
  *   const meta = Obj.getMeta(obj);     // ObjectMeta (mutable)
  *   meta.tags ??= [];
  *   meta.tags.push('important');
@@ -562,7 +562,7 @@ export const getKeys: {
 
 /**
  * Delete all keys from the object for the specified source.
- * Must be called within an `Obj.change` callback.
+ * Must be called within an `Obj.update` callback.
  *
  * NOTE: TypeScript's structural typing allows readonly objects to be passed to `Mutable<T>`
  * parameters, so there is no compile-time error. Enforcement is runtime-only.
@@ -571,7 +571,7 @@ export const deleteKeys = (entity: Mutable<Unknown>, source: string): void => in
 
 /**
  * Add a tag to the object.
- * Must be called within an `Obj.change` callback.
+ * Must be called within an `Obj.update` callback.
  *
  * NOTE: TypeScript's structural typing allows readonly objects to be passed to `Mutable<T>`
  * parameters, so there is no compile-time error. Enforcement is runtime-only.
@@ -580,7 +580,7 @@ export const addTag = (entity: Mutable<Unknown>, tag: string): void => internal.
 
 /**
  * Remove a tag from the object.
- * Must be called within an `Obj.change` callback.
+ * Must be called within an `Obj.update` callback.
  *
  * NOTE: TypeScript's structural typing allows readonly objects to be passed to `Mutable<T>`
  * parameters, so there is no compile-time error. Enforcement is runtime-only.
@@ -606,7 +606,7 @@ export const getLabel = (entity: Unknown | Snapshot): string | undefined => inte
 
 /**
  * Set the label of the object.
- * Must be called within an `Obj.change` callback.
+ * Must be called within an `Obj.update` callback.
  *
  * NOTE: TypeScript's structural typing allows readonly objects to be passed to `Mutable<T>`
  * parameters, so there is no compile-time error. Enforcement is runtime-only.
@@ -621,7 +621,7 @@ export const getDescription = (entity: Unknown | Snapshot): string | undefined =
 
 /**
  * Set the description of the object.
- * Must be called within an `Obj.change` callback.
+ * Must be called within an `Obj.update` callback.
  *
  * NOTE: TypeScript's structural typing allows readonly objects to be passed to `Mutable<T>`
  * parameters, so there is no compile-time error. Enforcement is runtime-only.
@@ -744,7 +744,7 @@ const prepareAssignValue = (value: unknown): unknown =>
  * References are compared by target DXN; other values use Effect `Equal.equals` inside a structural region,
  * with recursive comparison for arrays and plain object-shaped property bags (excluding `id`).
  *
- * Must be called within an `Obj.change` callback.
+ * Must be called within an `Obj.update` callback.
  *
  * @returns Whether any property was updated.
  */

package/src/Query.test.ts

@@ -523,7 +523,7 @@ describe('query api', () => {
           "from": {
             "_tag": "scope",
             "scope": {
-              "allQueuesFromSpaces": true,
+              "allFeedsFromSpaces": true,
             },
           },
           "query": {
@@ -563,17 +563,17 @@ describe('query api', () => {
     test('Query.type(...).from(feed) sets queue scope', async () => {
       const spaceId = SpaceId.random();
       const feedId = ObjectId.random();
-      const feedDxn = DXN.parse(`dxn:echo:${spaceId}:${feedId}`);
+      const feedDXN = DXN.parse(`dxn:echo:${spaceId}:${feedId}`);
       const feed = (await Obj.fromJSON(
         {
           '@type': 'dxn:type:org.dxos.type.feed:0.1.0',
           id: feedId,
           name: 'test-feed',
         },
-        { dxn: feedDxn },
+        { dxn: feedDXN },
       )) as Feed.Feed;
 
-      const expectedQueueDxn = new DXN(DXN.kind.QUEUE, ['data', spaceId, feedId]);
+      const expectedQueueDXN = new DXN(DXN.kind.QUEUE, ['data', spaceId, feedId]);
 
       const query = Query.type(TestSchema.Person).from(feed);
       Schema.validateSync(QueryAST.Query)(query.ast);
@@ -582,7 +582,7 @@ describe('query api', () => {
         from: {
           _tag: 'scope',
           scope: {
-            queues: [expectedQueueDxn.toString()],
+            feeds: [expectedQueueDXN.toString()],
           },
         },
         query: {
@@ -617,6 +617,22 @@ describe('query api', () => {
       );
     });
 
+    test('Query.pretty surfaces debugLabel from options', () => {
+      const query = Query.select(Filter.type(TestSchema.Person)).debugLabel('my-label');
+      expect(Query.pretty(query)).toContain('debugLabel');
+      expect(Query.pretty(query)).toContain('"my-label"');
+    });
+
+    test('Query.debugLabel merges onto existing options clause', () => {
+      const query = Query.select(Filter.type(TestSchema.Person))
+        .options({ deleted: 'exclude' })
+        .debugLabel('timer-probe');
+      const pretty = Query.pretty(query);
+      expect(pretty).toContain('deleted');
+      expect(pretty).toContain('debugLabel');
+      expect(pretty).toContain('"timer-probe"');
+    });
+
     test('Query.pretty returns human-readable query string', () => {
       const query = Query.select(Filter.type(TestSchema.Person, { name: 'Fred' }));
       const pretty = Query.pretty(query);
@@ -670,13 +686,13 @@ describe('query api', () => {
 
   describe('Filter.childOf', () => {
     test('childOf with Ref', () => {
-      const parentDxn = DXN.fromSpaceAndObjectId(SpaceId.random(), ObjectId.random());
-      const parentRef = Ref.fromDXN(parentDxn);
+      const parentDXN = DXN.fromSpaceAndObjectId(SpaceId.random(), ObjectId.random());
+      const parentRef = Ref.fromDXN(parentDXN);
       const filter = Filter.childOf(parentRef);
 
       expect(filter.ast).toMatchObject({
         type: 'child-of',
-        parents: [parentDxn.toString()],
+        parents: [parentDXN.toString()],
         transitive: true,
       });
       Schema.validateSync(QueryAST.Filter)(filter.ast);
@@ -720,15 +736,15 @@ describe('query api', () => {
     });
 
     test('childOf in select query', () => {
-      const parentDxn = DXN.fromSpaceAndObjectId(SpaceId.random(), ObjectId.random());
-      const parentRef = Ref.fromDXN(parentDxn);
+      const parentDXN = DXN.fromSpaceAndObjectId(SpaceId.random(), ObjectId.random());
+      const parentRef = Ref.fromDXN(parentDXN);
       const query = Query.select(Filter.childOf(parentRef));
 
       expect(query.ast).toMatchObject({
         type: 'select',
         filter: {
           type: 'child-of',
-          parents: [parentDxn.toString()],
+          parents: [parentDXN.toString()],
           transitive: true,
         },
       });
@@ -736,8 +752,8 @@ describe('query api', () => {
     });
 
     test('childOf combined with type filter', () => {
-      const parentDxn = DXN.fromSpaceAndObjectId(SpaceId.random(), ObjectId.random());
-      const parentRef = Ref.fromDXN(parentDxn);
+      const parentDXN = DXN.fromSpaceAndObjectId(SpaceId.random(), ObjectId.random());
+      const parentRef = Ref.fromDXN(parentDXN);
       const query = Query.select(Filter.and(Filter.type(TestSchema.Person), Filter.childOf(parentRef)));
 
       Schema.validateSync(QueryAST.Query)(query.ast);
@@ -747,7 +763,7 @@ describe('query api', () => {
           type: 'and',
           filters: [
             { type: 'object', typename: 'dxn:type:com.example.type.person:0.1.0' },
-            { type: 'child-of', parents: [parentDxn.toString()], transitive: true },
+            { type: 'child-of', parents: [parentDXN.toString()], transitive: true },
           ],
         },
       });
@@ -763,8 +779,8 @@ describe('query api', () => {
 
     test('childOf with mixed objects and Refs', () => {
       const parent = Obj.make(TestSchema.Person, { name: 'Parent' });
-      const refDxn = DXN.fromSpaceAndObjectId(SpaceId.random(), ObjectId.random());
-      const parentRef = Ref.fromDXN(refDxn);
+      const refDXN = DXN.fromSpaceAndObjectId(SpaceId.random(), ObjectId.random());
+      const parentRef = Ref.fromDXN(refDXN);
       const filter = Filter.childOf([parent, parentRef]);
 
       expect(filter.ast).toMatchObject({