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

package/src/Query.ts

@@ -207,6 +207,11 @@ export interface Query<T> {
    * Add options to a query.
    */
   'options'(options: QueryAST.QueryOptions): Query<T>;
+
+  /**
+   * Attach a diagnostic label for logs and tooling (execution semantics unchanged).
+   */
+  'debugLabel'(label: string): Query<T>;
 }
 
 export type Any = Query<any>;
@@ -354,7 +359,7 @@ class QueryClass implements Any {
         from: {
           _tag: 'scope',
           scope: {
-            ...(options?.includeFeeds ? { allQueuesFromSpaces: true } : {}),
+            ...(options?.includeFeeds ? { allFeedsFromSpaces: true } : {}),
           },
         },
       });
@@ -379,7 +384,7 @@ class QueryClass implements Any {
           _tag: 'scope',
           scope: {
             spaceIds: databases.map((db) => db.spaceId),
-            ...(options?.includeFeeds ? { allQueuesFromSpaces: true } : {}),
+            ...(options?.includeFeeds ? { allFeedsFromSpaces: true } : {}),
           },
         },
       });
@@ -405,10 +410,15 @@ class QueryClass implements Any {
       }
     }
 
-    const feeds = items as Feed.Feed[];
-    const queueDxns = feeds.flatMap((feed) => {
+    const feedItems = items as Feed.Feed[];
+    const feedDXNs = feedItems.map((feed) => {
       const dxn = Feed.getQueueDxn(feed);
-      return dxn ? [dxn.toString()] : [];
+      if (!dxn) {
+        throw new TypeError(
+          `Query.from() expects persisted Feed objects with a queue DXN; got feed without a space (id=${Obj.getDXN(feed).toString()}).`,
+        );
+      }
+      return dxn.toString();
     });
     return new QueryClass({
       type: 'from',
@@ -416,7 +426,7 @@ class QueryClass implements Any {
       from: {
         _tag: 'scope',
         scope: {
-          queues: queueDxns,
+          feeds: feedDXNs,
         },
       },
     });
@@ -429,6 +439,21 @@ class QueryClass implements Any {
       options,
     });
   }
+
+  debugLabel(label: string): Any {
+    if (this.ast.type === 'options') {
+      return new QueryClass({
+        type: 'options',
+        query: this.ast.query,
+        options: { ...this.ast.options, debugLabel: label },
+      });
+    }
+    return new QueryClass({
+      type: 'options',
+      query: this.ast,
+      options: { debugLabel: label },
+    });
+  }
 }
 
 export const is = (value: unknown): value is Any => {
@@ -531,7 +556,7 @@ export const from = (
   return wrapper.from(source as any, options);
 };
 
-const SCOPE_KEYS = new Set(['spaceIds', 'queues', 'allQueuesFromSpaces']);
+const SCOPE_KEYS = new Set(['spaceIds', 'feeds', 'allFeedsFromSpaces']);
 
 /** Detect a raw Scope object (plain object with only Scope-valid keys). */
 const _isScope = (value: unknown): value is QueryAST.Scope => {

package/src/Ref.ts

@@ -85,6 +85,8 @@ export const make = refInternal.Ref.make;
 // TODO(dmaretskyi): Consider just allowing `make` to accept DXN.
 export const fromDXN = refInternal.Ref.fromDXN;
 
+export const hasObjectId = refInternal.Ref.hasObjectId;
+
 // TODO(wittjosiah): Factor out?
 export const isRefType = (ast: SchemaAST.AST): boolean => {
   return SchemaAST.getAnnotation<JsonSchema.JsonSchema>(ast, SchemaAST.JSONSchemaAnnotationId).pipe(

package/src/Relation.ts

@@ -264,7 +264,7 @@ export const getTarget = <T extends Unknown | Snapshot>(relation: T): TargetOf<T
 
 /**
  * Makes all properties mutable recursively.
- * Used to provide a mutable view of a relation within `Relation.change`.
+ * Used to provide a mutable view of a relation within `Relation.update`.
  */
 export type Mutable<T> = internal.Mutable<T>;
 
@@ -272,10 +272,10 @@ export type Mutable<T> = internal.Mutable<T>;
  * Perform mutations on an echo relation within a controlled context.
  *
  * All mutations within the callback are batched and trigger a single notification
- * when the callback completes. Direct mutations outside of `Relation.change` will throw
+ * when the callback completes. Direct mutations outside of `Relation.update` will throw
  * an error for echo relations.
  *
- * @param relation - The echo relation to mutate. Use `Obj.change` for objects.
+ * @param relation - The echo relation to mutate. Use `Obj.update` for objects.
  * @param callback - The callback that performs mutations on the relation.
  *
  * @example
@@ -286,15 +286,15 @@ export type Mutable<T> = internal.Mutable<T>;
  *   role: 'Engineer',
  * });
  *
- * // Mutate within Relation.change
- * Relation.change(worksFor, (obj) => {
+ * // Mutate within Relation.update
+ * Relation.update(worksFor, (obj) => {
  *   obj.role = 'Senior Engineer';
  * });
  * ```
  *
- * Note: Only accepts relations. Use `Obj.change` for objects.
+ * Note: Only accepts relations. Use `Obj.update` for objects.
  */
-export const change = <T extends Unknown>(relation: T, callback: internal.ChangeCallback<T>): void => {
+export const update = <T extends Unknown>(relation: T, callback: internal.ChangeCallback<T>): void => {
   internal.change(relation, callback);
 };
 
@@ -337,7 +337,7 @@ export const getValue = (rel: Unknown | Snapshot, path: readonly (string | numbe
 
 /**
  * Set a deeply nested property on a relation.
- * Must be called within a `Relation.change` callback.
+ * Must be called within a `Relation.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.
@@ -399,13 +399,13 @@ export const Meta = internal.MetaId;
 export type ReadonlyMeta = internal.ReadonlyMeta;
 
 /**
- * Mutable meta type returned by `Relation.getMeta` inside a `Relation.change` callback.
+ * Mutable meta type returned by `Relation.getMeta` inside a `Relation.update` callback.
  */
 export type Meta = internal.Meta;
 
 /**
  * Get the metadata for a relation.
- * Returns mutable meta when passed a mutable relation (inside `Relation.change` callback).
+ * Returns mutable meta when passed a mutable relation (inside `Relation.update` callback).
  * Returns read-only meta when passed a regular relation or snapshot.
  */
 // TODO(wittjosiah): When passed a Snapshot, should return a snapshot of meta, not the live meta proxy.
@@ -423,7 +423,7 @@ export const getKeys = (entity: Unknown | Snapshot, source: string): ForeignKey[
 
 /**
  * Delete all keys from the relation for the specified source.
- * Must be called within a `Relation.change` callback.
+ * Must be called within a `Relation.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.
@@ -432,7 +432,7 @@ export const deleteKeys = (entity: Mutable<Unknown>, source: string): void => in
 
 /**
  * Add a tag to the relation.
- * Must be called within a `Relation.change` callback.
+ * Must be called within a `Relation.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.
@@ -441,7 +441,7 @@ export const addTag = (entity: Mutable<Unknown>, tag: string): void => internal.
 
 /**
  * Remove a tag from the relation.
- * Must be called within a `Relation.change` callback.
+ * Must be called within a `Relation.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.
@@ -466,7 +466,7 @@ export const getLabel = (entity: Unknown | Snapshot): string | undefined => inte
 
 /**
  * Set the label of the relation.
- * Must be called within a `Relation.change` callback.
+ * Must be called within a `Relation.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.
@@ -481,7 +481,7 @@ export const getDescription = (entity: Unknown | Snapshot): string | undefined =
 
 /**
  * Set the description of the relation.
- * Must be called within a `Relation.change` callback.
+ * Must be called within a `Relation.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.

package/src/exemplars.test.ts

@@ -0,0 +1,21 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import * as Obj from './Obj';
+import { TestSchema } from './testing';
+import type * as Type from './Type';
+
+describe('Exemplars', () => {
+  test('factory', ({ expect }) => {
+    const factory = <S extends Type.AnyObj>(schema: S) => {
+      return (props: Obj.MakeProps<S>) => Obj.make(schema, props);
+    };
+
+    const makePerson = factory(TestSchema.Person);
+    const person = makePerson({ name: 'John Doe' });
+    expect(person.name).toBe('John Doe');
+  });
+});

package/src/internal/Annotation/annotations.ts

@@ -481,7 +481,7 @@ export const makeUserAnnotation = <T>(props: MakeAnnoationsProps<T>): Annotation
 
   const getFromAst = (ast: SchemaAST.AST) =>
     SchemaAST.getAnnotation<PropertyMetaAnnotation>(PropertyMetaAnnotationId)(ast).pipe(
-      Option.map((meta) => meta[props.id] as unknown),
+      Option.flatMap((meta) => Option.fromNullable(meta[props.id])),
       Option.map(Schema.decodeUnknownSync(props.schema)),
     );
 
@@ -532,6 +532,19 @@ export const IconAnnotation = makeUserAnnotation<IconAnnotation>({
   schema: IconAnnotationSchema,
 });
 
+/**
+ * Indicates that this entity's icon should be resolved from a property whose value is a `Ref`
+ * to another entity. Consumers (e.g. graph node builders) resolve the ref target and use that
+ * target's schema `IconAnnotation` in place of the static one declared on this schema.
+ *
+ * Useful for wrapper schemas that delegate their visual identity to a referenced sub-entity
+ * (e.g. a generic `Game` whose icon should come from its `variant` ref's typed state).
+ */
+export const IconFromRefAnnotation = makeUserAnnotation<string>({
+  id: 'org.dxos.annotation.icon.from-ref',
+  schema: Schema.String,
+});
+
 /**
  * Get the label of an entity.
  * Accepts both reactive entities and snapshots.
@@ -545,7 +558,7 @@ export const getLabel = (entity: AnyProperties): string | undefined => {
 
 /**
  * Set the label of an entity.
- * Must be called within an Obj.change or Relation.change callback.
+ * Must be called within an Obj.update or Relation.update callback.
  */
 export const setLabel = (entity: Mutable<AnyProperties>, label: string) => {
   const schema = getSchema(entity);
@@ -567,7 +580,7 @@ export const getDescription = (entity: AnyProperties): string | undefined => {
 
 /**
  * Set the description of an entity.
- * Must be called within an Obj.change or Relation.change callback.
+ * Must be called within an Obj.update or Relation.update callback.
  */
 export const setDescription = (entity: Mutable<AnyProperties>, description: string) => {
   const schema = getSchema(entity);

package/src/internal/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/Obj/json-serializer.test.ts

@@ -20,7 +20,7 @@ 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, (contact) => {
+    Obj.update(contact, (contact) => {
       getMetaChecked(contact).keys.push({ id: '12345', source: 'example.com' });
     });
 

package/src/internal/Obj/json-serializer.ts

@@ -116,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 {
@@ -142,8 +142,8 @@ export const objectFromJSON = async (
   }
 
   if (jsonData[ATTR_PARENT]) {
-    const parentDxn = DXN.parse(jsonData[ATTR_PARENT]);
-    const resolvedParent = (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);
@@ -184,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/Obj/set-value.test.ts

@@ -17,7 +17,7 @@ describe('Obj.setValue', () => {
       email: 'john@example.com',
     });
 
-    Obj.change(person, (person) => Obj.setValue(person, ['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, (person) => Obj.setValue(person, ['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, (person) => Obj.setValue(person, ['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,7 +69,7 @@ describe('Obj.setValue', () => {
 
     const container = Obj.make(Container, { name: 'box' });
 
-    Obj.change(container, (container) => {
+    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);
@@ -88,7 +88,7 @@ describe('Obj.setValue', () => {
       email: 'john@example.com',
     });
 
-    Obj.change(person, (person) => Obj.setValue(person, ['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, (person) => Obj.setValue(person, ['address', 'city'], 'NYC'));
+    Obj.update(person, (person) => Obj.setValue(person, ['address', 'city'], 'NYC'));
 
     expect(person.address).toBeDefined();
     expect(person.address?.city).toBe('NYC');
@@ -114,7 +114,7 @@ describe('Obj.setValue', () => {
     });
 
     let result: any;
-    Obj.change(person, (person) => {
+    Obj.update(person, (person) => {
       result = Obj.setValue(person, ['age'], 30);
     });
 
@@ -129,7 +129,7 @@ describe('Obj.setValue', () => {
       age: 25,
     });
 
-    Obj.change(person, (person) => Obj.setValue(person, ['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, (person) => Obj.setValue(person, ['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,7 +160,7 @@ describe('Obj.setValue', () => {
 
     const matrix = Obj.make(Matrix, {});
 
-    Obj.change(matrix, (matrix) => {
+    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);
@@ -180,7 +180,7 @@ describe('Obj.setValue', () => {
       email: 'john@example.com',
     });
 
-    Obj.change(person, (person) => {
+    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, (person) => Obj.setValue(person, ['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, (container) => Obj.setValue(container, ['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, (todoList) => Obj.setValue(todoList, ['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, (container) => Obj.setValue(container, ['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/Obj/set-value.ts

@@ -21,7 +21,7 @@ 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/Query.ts

@@ -109,6 +109,9 @@ export const prettyQuery = (query: QueryAST.Query): 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': {
@@ -118,11 +121,11 @@ export const prettyQuery = (query: QueryAST.Query): string => {
         if (scope.spaceIds !== undefined) {
           parts.push(`spaceIds: [${scope.spaceIds.map((s) => JSON.stringify(s)).join(', ')}]`);
         }
-        if (scope.queues !== undefined) {
-          parts.push(`queues: [${scope.queues.map(String).join(', ')}]`);
+        if (scope.feeds !== undefined) {
+          parts.push(`feeds: [${scope.feeds.map(String).join(', ')}]`);
         }
-        if (scope.allQueuesFromSpaces !== undefined) {
-          parts.push(`allQueuesFromSpaces: ${scope.allQueuesFromSpaces}`);
+        if (scope.allFeedsFromSpaces !== undefined) {
+          parts.push(`allFeedsFromSpaces: ${scope.allFeedsFromSpaces}`);
         }
         return `${prettyQuery(query.query)}.from({ ${parts.join(', ')} })`;
       }

package/src/internal/Type/echo-schema.ts

@@ -372,7 +372,7 @@ export class EchoSchema<A = any, I = any> extends EchoSchemaConstructor() implem
   }
 
   /**
-   * Wrapper for Obj.change that handles the change context for the persistent schema.
+   * Wrapper for Obj.update that handles the change context for the persistent schema.
    */
   private _change(callback: (schema: PersistentSchema) => void): void {
     const changeFn = (this._persistentSchema as any)[ChangeId];

package/src/internal/common/README.md

@@ -99,4 +99,4 @@
 - [ ] ReactiveObject should specify id property? Reconcile AnyProperties, ReactiveObject, HasId, WithId, etc.
 - [ ] Can we us S.is(MyType) to detect objects with our types system? (Branding?)
 - [ ] Type.Expando doesn't work with AtomQuery result type (have to use Obj.Any instead).
-- [ ] Obj.Any doesn't work with Obj.change callback types (have to use `any` for the mutable parameter).
+- [ ] Obj.Any doesn't work with Obj.update callback types (have to use `any` for the mutable parameter).

package/src/internal/common/api/meta.ts

@@ -48,7 +48,7 @@ export const getKeys = (entity: AnyProperties, source: string): ForeignKey[] =>
 
 /**
  * Delete all keys from the entity for the specified source.
- * Must be called within an Obj.change or Relation.change callback.
+ * Must be called within an Obj.update or Relation.update callback.
  */
 export const deleteKeys = (entity: Mutable<AnyProperties>, source: string) => {
   const meta = getMetaChecked(entity);
@@ -62,7 +62,7 @@ export const deleteKeys = (entity: Mutable<AnyProperties>, source: string) => {
 
 /**
  * Add a tag to the entity.
- * Must be called within an Obj.change or Relation.change callback.
+ * Must be called within an Obj.update or Relation.update callback.
  */
 export const addTag = (entity: Mutable<AnyProperties>, tag: string) => {
   const meta = getMetaChecked(entity);
@@ -72,7 +72,7 @@ export const addTag = (entity: Mutable<AnyProperties>, tag: string) => {
 
 /**
  * Remove a tag from the entity.
- * Must be called within an Obj.change or Relation.change callback.
+ * Must be called within an Obj.update or Relation.update callback.
  */
 export const removeTag = (entity: Mutable<AnyProperties>, tag: string) => {
   const meta = getMetaChecked(entity);

package/src/internal/common/proxy/change-context.ts

@@ -35,7 +35,7 @@ const pendingOwnerNotifications = new Set<object>();
 /**
  * Enter a change context for the given key.
  * While in a change context, mutations are allowed on the associated object.
- * Nested Obj.change calls are not supported.
+ * Nested Obj.update calls are not supported.
  *
  * @param key - The key to enter the change context for (target object or ObjectCore).
  * @returns A cleanup function that exits the change context.