@dxos/echo 0.8.4-staging.ac66bdf99f → 0.9.0

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

@@ -6,18 +6,21 @@ import type { ForeignKey } from '@dxos/echo-protocol';
 import { assertArgument, invariant } from '@dxos/invariant';
 import type { DeepReadonly } from '@dxos/util';
 
+import type * as Tag from '../../../Tag';
+import type { Ref } from '../../Ref/ref';
 import { type Mutable } from '../proxy';
-import { type AnyProperties, type ObjectMeta, getMeta as getMeta$ } from '../types';
+import { type AnyProperties } from '../types';
+import { type EntityMeta, getMeta as getMeta$ } from '../types/meta';
 
 /**
- * Deeply read-only version of ObjectMeta.
+ * Deeply read-only version of EntityMeta.
  */
-export type ReadonlyMeta = DeepReadonly<ObjectMeta>;
+export type ReadonlyMeta = DeepReadonly<EntityMeta>;
 
 /**
  * Mutable meta type received in meta mutation callbacks.
  */
-export type Meta = Mutable<ObjectMeta>;
+export type Meta = Mutable<EntityMeta>;
 
 /**
  * Get the metadata for an entity with validation.
@@ -48,7 +51,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);
@@ -61,26 +64,25 @@ 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.
+ * Add a tag (a reference to a {@link Tag} object) to the entity. Idempotent.
+ * Must be called within an Obj.update or Relation.update callback.
  */
-export const addTag = (entity: Mutable<AnyProperties>, tag: string) => {
+export const addTag = (entity: Mutable<AnyProperties>, tag: Ref<Tag.Tag>) => {
   const meta = getMetaChecked(entity);
-  meta.tags ??= [];
-  meta.tags.push(tag);
+  // Two refs to the same target are not `===`; dedupe by URI.
+  if (!meta.tags.some((existing) => existing.uri === tag.uri)) {
+    meta.tags.push(tag);
+  }
 };
 
 /**
- * Remove a tag from the entity.
- * Must be called within an Obj.change or Relation.change callback.
+ * Remove a tag (a reference to a {@link Tag} object) from the entity. No-op when not present.
+ * Must be called within an Obj.update or Relation.update callback.
  */
-export const removeTag = (entity: Mutable<AnyProperties>, tag: string) => {
+export const removeTag = (entity: Mutable<AnyProperties>, tag: Ref<Tag.Tag>) => {
   const meta = getMetaChecked(entity);
-  if (!meta.tags) {
-    return;
-  }
   for (let i = 0; i < meta.tags.length; i++) {
-    if (meta.tags[i] === tag) {
+    if (meta.tags[i].uri === tag.uri) {
       meta.tags.splice(i, 1);
       i--;
     }

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.

package/src/internal/common/proxy/change.test.ts

@@ -4,22 +4,30 @@
 
 import { describe, test } from 'vitest';
 
+import { URI } from '@dxos/keys';
+
 import * as Obj from '../../../Obj';
+import * as Ref from '../../../Ref';
 import * as Relation from '../../../Relation';
 import { TestSchema } from '../../../testing';
 
+// Tags are stored as `Ref<Tag>`; build refs from synthetic URIs and compare by `.uri`.
+const tagRef = (id: string): Ref.Ref<any> => Ref.fromURI(URI.make(`echo://BBBBBBBBBBBBBBBBBBBBBBBBBB/${id}`));
+const tagUris = (entity: Obj.Unknown | Relation.Unknown): string[] =>
+  Obj.getMeta(entity as Obj.Unknown).tags.map((tag) => tag.uri);
+
 /**
- * Tests for Obj.change context enforcement and mutator type safety.
+ * Tests for Obj.update context enforcement and mutator type safety.
  *
  * These tests verify:
  * 1. Mutator functions require Mutable<T> at compile-time.
- * 2. getMeta returns ReadonlyMeta outside change callbacks and ObjectMeta inside.
- * 3. Mutations outside Obj.change throw at runtime.
+ * 2. getMeta returns ReadonlyMeta outside change callbacks and EntityMeta inside.
+ * 3. Mutations outside Obj.update throw at runtime.
  * 4. Nested object/property mutations work correctly.
  * 5. Array mutations (push, pop, splice) require change context.
  * 6. Property delete requires change context.
  */
-describe('Obj.change enforcement', () => {
+describe('Obj.update enforcement', () => {
   describe('compile-time and runtime safety', () => {
     test('direct property mutation outside change throws', ({ expect }) => {
       const obj = Obj.make(TestSchema.Person, { name: 'Test' });
@@ -28,7 +36,7 @@ describe('Obj.change enforcement', () => {
       expect(() => {
         // @ts-expect-error Testing runtime error for readonly property mutation.
         obj.name = 'New Name';
-      }).toThrow(/outside of Obj.change/);
+      }).toThrow(/outside of Obj.update/);
     });
 
     test('Obj.setValue outside change throws', ({ expect }) => {
@@ -36,7 +44,7 @@ describe('Obj.change enforcement', () => {
 
       // No compile-time error: TypeScript's structural typing allows readonly objects
       // to be passed to Mutable<T> parameters. Enforcement is runtime-only.
-      expect(() => Obj.setValue(obj, ['name'], 'value')).toThrow(/outside of Obj.change/);
+      expect(() => Obj.setValue(obj, ['name'], 'value')).toThrow(/outside of Obj.update/);
     });
 
     test('Obj.addTag outside change throws', ({ expect }) => {
@@ -44,7 +52,7 @@ describe('Obj.change enforcement', () => {
 
       // No compile-time error: TypeScript's structural typing allows readonly objects
       // to be passed to Mutable<T> parameters. Enforcement is runtime-only.
-      expect(() => Obj.addTag(obj, 'tag')).toThrow(/outside of Obj.change/);
+      expect(() => Obj.addTag(obj, tagRef('tag'))).toThrow(/outside of Obj.update/);
     });
 
     test('getMeta mutation outside change throws', ({ expect }) => {
@@ -52,23 +60,23 @@ describe('Obj.change enforcement', () => {
       const meta = Obj.getMeta(obj);
 
       // Runtime errors for direct meta mutations.
-      expect(() => ((meta as any).keys = [])).toThrow(/outside of Obj.change/);
-      expect(() => ((meta as any).tags = ['tag'])).toThrow(/outside of Obj.change/);
+      expect(() => ((meta as any).keys = [])).toThrow(/outside of Obj.update/);
+      expect(() => ((meta as any).tags = [tagRef('tag')])).toThrow(/outside of Obj.update/);
     });
 
-    test('getMeta returns mutable ObjectMeta inside change callback', ({ expect }) => {
+    test('getMeta returns mutable EntityMeta inside change callback', ({ expect }) => {
       const obj = Obj.make(TestSchema.Person, { name: 'Test' });
 
-      Obj.change(obj, (obj) => {
+      Obj.update(obj, (obj) => {
         const meta = Obj.getMeta(obj);
 
-        // These should compile without errors because meta is ObjectMeta (mutable).
+        // These should compile without errors because meta is EntityMeta (mutable).
         meta.keys = [];
-        meta.tags = ['tag'];
+        meta.tags = [tagRef('tag')];
         meta.keys.push({ source: 'test', id: '123' });
       });
 
-      expect(Obj.getMeta(obj).tags).toEqual(['tag']);
+      expect(tagUris(obj)).toEqual([tagRef('tag').uri]);
       expect(Obj.getMeta(obj).keys).toHaveLength(1);
     });
 
@@ -76,13 +84,13 @@ describe('Obj.change enforcement', () => {
       const obj = Obj.make(TestSchema.Person, { name: 'Test' });
 
       // These should compile without errors inside change callback.
-      Obj.change(obj, (obj) => {
-        Obj.addTag(obj, 'my-tag');
+      Obj.update(obj, (obj) => {
+        Obj.addTag(obj, tagRef('my-tag'));
         Obj.setValue(obj, ['name'], 'Updated');
       });
 
       expect(obj.name).toBe('Updated');
-      expect(Obj.getMeta(obj).tags).toContain('my-tag');
+      expect(tagUris(obj)).toContain(tagRef('my-tag').uri);
     });
 
     test('Relation property mutation outside change throws', ({ expect }) => {
@@ -97,7 +105,7 @@ describe('Obj.change enforcement', () => {
       expect(() => {
         // @ts-expect-error Testing runtime error for readonly property mutation.
         rel.title = 'Manager';
-      }).toThrow(/outside of Obj.change/);
+      }).toThrow(/outside of Obj.update/);
     });
 
     test('Relation.addTag outside change throws', ({ expect }) => {
@@ -110,7 +118,7 @@ describe('Obj.change enforcement', () => {
 
       // No compile-time error: TypeScript's structural typing allows readonly objects
       // to be passed to Mutable<T> parameters. Enforcement is runtime-only.
-      expect(() => Relation.addTag(rel, 'tag')).toThrow(/outside of Obj.change/);
+      expect(() => Relation.addTag(rel, tagRef('tag'))).toThrow(/outside of Obj.update/);
     });
   });
 
@@ -122,7 +130,7 @@ describe('Obj.change enforcement', () => {
       // Person schema uses 'name' as label field.
       expect(Obj.getLabel(obj)).toBe('John');
 
-      Obj.change(obj, (obj) => {
+      Obj.update(obj, (obj) => {
         Obj.setLabel(obj, 'Jane');
       });
 
@@ -140,7 +148,7 @@ describe('Obj.change enforcement', () => {
 
       // setDescription only works if schema has description annotation.
       // For schemas without it, this is a no-op.
-      Obj.change(obj, (obj) => {
+      Obj.update(obj, (obj) => {
         Obj.setDescription(obj, 'My Description');
       });
 
@@ -151,26 +159,26 @@ describe('Obj.change enforcement', () => {
     test('addTag and removeTag work correctly', ({ expect }) => {
       const obj = Obj.make(TestSchema.Person, { name: 'Test' });
 
-      expect(Obj.getMeta(obj).tags).toBeUndefined();
+      expect(Obj.getMeta(obj).tags).toEqual([]);
 
-      Obj.change(obj, (obj) => {
-        Obj.addTag(obj, 'tag-1');
-        Obj.addTag(obj, 'tag-2');
+      Obj.update(obj, (obj) => {
+        Obj.addTag(obj, tagRef('tag-1'));
+        Obj.addTag(obj, tagRef('tag-2'));
       });
 
-      expect(Obj.getMeta(obj).tags).toEqual(['tag-1', 'tag-2']);
+      expect(tagUris(obj)).toEqual([tagRef('tag-1').uri, tagRef('tag-2').uri]);
 
-      Obj.change(obj, (obj) => {
-        Obj.removeTag(obj, 'tag-1');
+      Obj.update(obj, (obj) => {
+        Obj.removeTag(obj, tagRef('tag-1'));
       });
 
-      expect(Obj.getMeta(obj).tags).toEqual(['tag-2']);
+      expect(tagUris(obj)).toEqual([tagRef('tag-2').uri]);
     });
 
     test('deleteKeys removes foreign keys by source', ({ 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-a', id: '1' });
         meta.keys.push({ source: 'source-a', id: '2' });
@@ -179,7 +187,7 @@ describe('Obj.change enforcement', () => {
 
       expect(Obj.getMeta(obj).keys).toHaveLength(3);
 
-      Obj.change(obj, (obj) => {
+      Obj.update(obj, (obj) => {
         Obj.deleteKeys(obj, 'source-a');
       });
 
@@ -190,7 +198,7 @@ describe('Obj.change enforcement', () => {
     test('setValue sets nested properties', ({ expect }) => {
       const obj = Obj.make(TestSchema.Person, { name: 'Test' });
 
-      Obj.change(obj, (obj) => {
+      Obj.update(obj, (obj) => {
         Obj.setValue(obj, ['name'], 'Updated Name');
       });
 
@@ -200,36 +208,36 @@ describe('Obj.change enforcement', () => {
     test('getMeta is mutable inside change and changes persist', ({ expect }) => {
       const obj = Obj.make(TestSchema.Person, { name: 'Test' });
 
-      Obj.change(obj, (obj) => {
+      Obj.update(obj, (obj) => {
         const meta = Obj.getMeta(obj);
-        meta.tags = ['tag-1', 'tag-2'];
+        meta.tags = [tagRef('tag-1'), tagRef('tag-2')];
         meta.keys.push({ source: 'external', id: '123' });
       });
 
       // Changes should persist after the change callback.
-      expect(Obj.getMeta(obj).tags).toEqual(['tag-1', 'tag-2']);
+      expect(tagUris(obj)).toEqual([tagRef('tag-1').uri, tagRef('tag-2').uri]);
       expect(Obj.getMeta(obj).keys).toEqual([{ source: 'external', id: '123' }]);
     });
 
     test('multiple mutations in single change all persist', ({ expect }) => {
       const obj = Obj.make(TestSchema.Person, { name: 'Test' });
 
-      Obj.change(obj, (obj) => {
+      Obj.update(obj, (obj) => {
         obj.name = 'Name 1';
         obj.name = 'Name 2';
         obj.name = 'Name 3';
-        Obj.addTag(obj, 'tag-1');
-        Obj.addTag(obj, 'tag-2');
+        Obj.addTag(obj, tagRef('tag-1'));
+        Obj.addTag(obj, tagRef('tag-2'));
       });
 
       // All mutations should persist.
       expect(obj.name).toBe('Name 3');
-      expect(Obj.getMeta(obj).tags).toEqual(['tag-1', 'tag-2']);
+      expect(tagUris(obj)).toEqual([tagRef('tag-1').uri, tagRef('tag-2').uri]);
     });
   });
 
   describe('notifications', () => {
-    test('batched notifications - only one per Obj.change', ({ expect }) => {
+    test('batched notifications - only one per Obj.update', ({ expect }) => {
       const obj = Obj.make(TestSchema.Person, { name: 'John' });
 
       let notificationCount = 0;
@@ -237,7 +245,7 @@ describe('Obj.change enforcement', () => {
         notificationCount++;
       });
 
-      Obj.change(obj, (obj) => {
+      Obj.update(obj, (obj) => {
         obj.name = 'Jane';
         obj.age = 30;
       });
@@ -250,13 +258,13 @@ describe('Obj.change enforcement', () => {
   });
 
   describe('nested mutations', () => {
-    test('nested object property mutation within Obj.change', ({ expect }) => {
+    test('nested object property mutation within Obj.update', ({ expect }) => {
       const obj = Obj.make(TestSchema.Person, {
         name: 'John',
         address: { city: 'NYC', coordinates: {} },
       });
 
-      Obj.change(obj, (obj) => {
+      Obj.update(obj, (obj) => {
         obj.address!.state = 'NY';
       });
 
@@ -264,13 +272,13 @@ describe('Obj.change enforcement', () => {
       expect(obj.address?.city).toBe('NYC');
     });
 
-    test('deeply nested property mutation within Obj.change (2 levels)', ({ expect }) => {
+    test('deeply nested property mutation within Obj.update (2 levels)', ({ expect }) => {
       const obj = Obj.make(TestSchema.Person, {
         name: 'John',
         address: { city: 'NYC', coordinates: { lat: 40.7128, lng: -74.006 } },
       });
 
-      Obj.change(obj, (obj) => {
+      Obj.update(obj, (obj) => {
         obj.address!.coordinates!.lat = 51.5074;
         obj.address!.coordinates!.lng = -0.1278;
       });
@@ -279,7 +287,7 @@ describe('Obj.change enforcement', () => {
       expect(obj.address?.coordinates?.lng).toBe(-0.1278);
     });
 
-    test('nested object mutation outside Obj.change throws (1 level deep)', ({ expect }) => {
+    test('nested object mutation outside Obj.update throws (1 level deep)', ({ expect }) => {
       const obj = Obj.make(TestSchema.Person, {
         name: 'John',
         address: { city: 'NYC', coordinates: {} },
@@ -288,10 +296,10 @@ describe('Obj.change enforcement', () => {
       expect(() => {
         // @ts-expect-error - nested property assignment is readonly.
         obj.address!.city = 'LA';
-      }).toThrow(/outside of Obj.change/);
+      }).toThrow(/outside of Obj.update/);
     });
 
-    test('deeply nested mutation outside Obj.change throws (2 levels deep)', ({ expect }) => {
+    test('deeply nested mutation outside Obj.update throws (2 levels deep)', ({ expect }) => {
       const obj = Obj.make(TestSchema.Person, {
         name: 'John',
         address: { city: 'NYC', coordinates: { lat: 40.7128, lng: -74.006 } },
@@ -300,17 +308,17 @@ describe('Obj.change enforcement', () => {
       expect(() => {
         // @ts-expect-error - deeply nested property assignment should be caught.
         obj.address!.coordinates!.lat = 0;
-      }).toThrow(/outside of Obj.change/);
+      }).toThrow(/outside of Obj.update/);
     });
 
-    test('nested Obj.change calls work correctly', ({ expect }) => {
+    test('nested Obj.update calls work correctly', ({ expect }) => {
       const obj = Obj.make(TestSchema.Person, { name: 'John' });
 
-      Obj.change(obj, (obj) => {
+      Obj.update(obj, (obj) => {
         obj.name = 'Jane';
 
         // Nested change should work (already in change context).
-        Obj.change(obj, (obj) => {
+        Obj.update(obj, (obj) => {
           obj.age = 30;
         });
       });
@@ -323,7 +331,7 @@ describe('Obj.change enforcement', () => {
       const obj = Obj.make(TestSchema.Person, { name: 'John' });
 
       expect(() => {
-        Obj.change(obj, (obj) => {
+        Obj.update(obj, (obj) => {
           obj.name = 'Jane';
           throw new Error('Test error');
         });
@@ -333,18 +341,18 @@ describe('Obj.change enforcement', () => {
       expect(() => {
         // @ts-expect-error Testing runtime error for readonly property mutation.
         obj.name = 'Bob';
-      }).toThrow(/outside of Obj.change/);
+      }).toThrow(/outside of Obj.update/);
     });
   });
 
   describe('array mutations', () => {
-    test('array push within Obj.change', ({ expect }) => {
+    test('array push within Obj.update', ({ expect }) => {
       const obj = Obj.make(TestSchema.Person, {
         name: 'John',
         fields: [{ label: 'tag1', value: 'val1' }],
       });
 
-      Obj.change(obj, (obj) => {
+      Obj.update(obj, (obj) => {
         obj.fields!.push({ label: 'tag2', value: 'val2' });
       });
 
@@ -352,7 +360,7 @@ describe('Obj.change enforcement', () => {
       expect(obj.fields![1].label).toBe('tag2');
     });
 
-    test('array pop within Obj.change', ({ expect }) => {
+    test('array pop within Obj.update', ({ expect }) => {
       const obj = Obj.make(TestSchema.Person, {
         name: 'John',
         fields: [
@@ -362,7 +370,7 @@ describe('Obj.change enforcement', () => {
       });
 
       let popped: any;
-      Obj.change(obj, (obj) => {
+      Obj.update(obj, (obj) => {
         popped = obj.fields!.pop();
       });
 
@@ -370,7 +378,7 @@ describe('Obj.change enforcement', () => {
       expect(obj.fields).toHaveLength(1);
     });
 
-    test('array splice within Obj.change', ({ expect }) => {
+    test('array splice within Obj.update', ({ expect }) => {
       const obj = Obj.make(TestSchema.Person, {
         name: 'John',
         fields: [
@@ -380,7 +388,7 @@ describe('Obj.change enforcement', () => {
         ],
       });
 
-      Obj.change(obj, (obj) => {
+      Obj.update(obj, (obj) => {
         obj.fields!.splice(1, 1, { label: 'x', value: 'x' });
       });
 
@@ -388,7 +396,7 @@ describe('Obj.change enforcement', () => {
       expect(obj.fields![1].label).toBe('x');
     });
 
-    test('array push outside Obj.change throws', ({ expect }) => {
+    test('array push outside Obj.update throws', ({ expect }) => {
       const obj = Obj.make(TestSchema.Person, {
         name: 'John',
         fields: [{ label: 'tag1', value: 'val1' }],
@@ -397,10 +405,10 @@ describe('Obj.change enforcement', () => {
       expect(() => {
         // @ts-expect-error Testing runtime error for readonly array mutation.
         obj.fields!.push({ label: 'tag2', value: 'val2' });
-      }).toThrow(/array\.push\(\).*outside of Obj\.change/);
+      }).toThrow(/array\.push\(\).*outside of Obj\.update/);
     });
 
-    test('array pop outside Obj.change throws', ({ expect }) => {
+    test('array pop outside Obj.update throws', ({ expect }) => {
       const obj = Obj.make(TestSchema.Person, {
         name: 'John',
         fields: [{ label: 'tag1', value: 'val1' }],
@@ -409,10 +417,10 @@ describe('Obj.change enforcement', () => {
       expect(() => {
         // @ts-expect-error Testing runtime error for readonly array mutation.
         obj.fields!.pop();
-      }).toThrow(/array\.pop\(\).*outside of Obj\.change/);
+      }).toThrow(/array\.pop\(\).*outside of Obj\.update/);
     });
 
-    test('array splice outside Obj.change throws', ({ expect }) => {
+    test('array splice outside Obj.update throws', ({ expect }) => {
       const obj = Obj.make(TestSchema.Person, {
         name: 'John',
         fields: [{ label: 'tag1', value: 'val1' }],
@@ -421,33 +429,33 @@ describe('Obj.change enforcement', () => {
       expect(() => {
         // @ts-expect-error Testing runtime error for readonly array mutation.
         obj.fields!.splice(0, 1);
-      }).toThrow(/array\.splice\(\).*outside of Obj\.change/);
+      }).toThrow(/array\.splice\(\).*outside of Obj\.update/);
     });
   });
 
   describe('property delete', () => {
-    test('delete property within Obj.change', ({ expect }) => {
+    test('delete property within Obj.update', ({ expect }) => {
       const obj = Obj.make(TestSchema.Person, { name: 'John', age: 25 });
 
-      Obj.change(obj, (obj) => {
+      Obj.update(obj, (obj) => {
         delete obj.age;
       });
 
       expect(obj.age).toBeUndefined();
     });
 
-    test('delete property outside Obj.change throws', ({ expect }) => {
+    test('delete property outside Obj.update throws', ({ expect }) => {
       const obj = Obj.make(TestSchema.Person, { name: 'John', age: 25 });
 
       expect(() => {
         // @ts-expect-error Testing runtime error for readonly property delete.
         delete obj.age;
-      }).toThrow(/delete object property.*outside of Obj\.change/);
+      }).toThrow(/delete object property.*outside of Obj\.update/);
     });
   });
 
   describe('Relation mutators', () => {
-    test('Relation.getMeta is mutable inside Relation.change', ({ expect }) => {
+    test('Relation.getMeta is mutable inside Relation.update', ({ expect }) => {
       const source = Obj.make(TestSchema.Person, { name: 'Alice' });
       const target = Obj.make(TestSchema.Person, { name: 'Bob' });
       const rel = Relation.make(TestSchema.HasManager, {
@@ -455,13 +463,13 @@ describe('Obj.change enforcement', () => {
         [Relation.Target]: target,
       });
 
-      Relation.change(rel, (rel) => {
+      Relation.update(rel, (rel) => {
         const meta = Relation.getMeta(rel);
-        meta.tags = ['rel-tag'];
+        meta.tags = [tagRef('rel-tag')];
         meta.keys.push({ source: 'rel-source', id: 'rel-key' });
       });
 
-      expect(Relation.getMeta(rel).tags).toEqual(['rel-tag']);
+      expect(tagUris(rel)).toEqual([tagRef('rel-tag').uri]);
       expect(Relation.getMeta(rel).keys).toHaveLength(1);
     });
 
@@ -473,17 +481,17 @@ describe('Obj.change enforcement', () => {
         [Relation.Target]: target,
       });
 
-      Relation.change(rel, (rel) => {
-        Relation.addTag(rel, 'important');
+      Relation.update(rel, (rel) => {
+        Relation.addTag(rel, tagRef('important'));
       });
 
-      expect(Relation.getMeta(rel).tags).toContain('important');
+      expect(tagUris(rel)).toContain(tagRef('important').uri);
 
-      Relation.change(rel, (rel) => {
-        Relation.removeTag(rel, 'important');
+      Relation.update(rel, (rel) => {
+        Relation.removeTag(rel, tagRef('important'));
       });
 
-      expect(Relation.getMeta(rel).tags).not.toContain('important');
+      expect(tagUris(rel)).not.toContain(tagRef('important').uri);
     });
   });
 
@@ -494,7 +502,7 @@ describe('Obj.change enforcement', () => {
 
       // Direct assignment of root ECHO objects (created with Obj.make) is not allowed.
       expect(() => {
-        Obj.change(obj, (obj) => {
+        Obj.update(obj, (obj) => {
           obj.other = other;
         });
       }).toThrow(/Object references must be wrapped with `Ref\.make`/);
@@ -504,13 +512,13 @@ describe('Obj.change enforcement', () => {
       const obj = Obj.make(TestSchema.Expando, {});
 
       // Assign a plain object (not created with Obj.make).
-      Obj.change(obj, (obj) => {
+      Obj.update(obj, (obj) => {
         obj.nested = { value: 'initial' };
       });
       expect(obj.nested.value).toBe('initial');
 
       // Modify plain nested object through parent's change context.
-      Obj.change(obj, (obj) => {
+      Obj.update(obj, (obj) => {
         obj.nested.value = 'modified';
       });
       expect(obj.nested.value).toBe('modified');

package/src/internal/common/proxy/errors.ts

@@ -3,12 +3,12 @@
 //
 
 /**
- * Error thrown when attempting to mutate an object outside of an Obj.change() context.
+ * Error thrown when attempting to mutate an object outside of an Obj.update() context.
  */
 export class MutationOutsideChangeContextError extends Error {
   constructor(operation: string, suggestion: string) {
     super(
-      `Cannot ${operation} outside of Obj.change(). Use Obj.change(obj, (mutableObj) => { ${suggestion} }) instead.`,
+      `Cannot ${operation} outside of Obj.update(). Use Obj.update(obj, (mutableObj) => { ${suggestion} }) instead.`,
     );
     this.name = 'MutationOutsideChangeContextError';
   }

package/src/internal/common/proxy/handler.test.ts

@@ -9,7 +9,7 @@ import { isNode } from '@dxos/util';
 
 import { TestSchema, updateCounter } from '../../../testing';
 import { createObject } from '../../Obj';
-import { ATTR_META } from '../types';
+import { ATTR_META } from '../types/meta';
 import { makeObject } from './make-object';
 import { objectData } from './proxy-types';
 import { change } from './reactive';