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

package/src/internal/{proxy → common/proxy}/change.test.ts

@@ -4,22 +4,22 @@
 
 import { describe, test } from 'vitest';
 
-import * as Obj from '../../Obj';
-import * as Relation from '../../Relation';
-import { TestSchema } from '../../testing';
+import * as Obj from '../../../Obj';
+import * as Relation from '../../../Relation';
+import { TestSchema } from '../../../testing';
 
 /**
- * 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.
+ * 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 +28,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 +36,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 +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.addTag(obj, 'tag')).toThrow(/outside of Obj.change/);
+      expect(() => Obj.addTag(obj, 'tag')).toThrow(/outside of Obj.update/);
     });
 
     test('getMeta mutation outside change throws', ({ expect }) => {
@@ -52,15 +52,15 @@ 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 = ['tag'])).toThrow(/outside of Obj.update/);
     });
 
     test('getMeta returns mutable ObjectMeta inside change callback', ({ expect }) => {
       const obj = Obj.make(TestSchema.Person, { name: 'Test' });
 
-      Obj.change(obj, (mutableObj) => {
-        const meta = Obj.getMeta(mutableObj);
+      Obj.update(obj, (obj) => {
+        const meta = Obj.getMeta(obj);
 
         // These should compile without errors because meta is ObjectMeta (mutable).
         meta.keys = [];
@@ -76,9 +76,9 @@ describe('Obj.change enforcement', () => {
       const obj = Obj.make(TestSchema.Person, { name: 'Test' });
 
       // These should compile without errors inside change callback.
-      Obj.change(obj, (mutableObj) => {
-        Obj.addTag(mutableObj, 'my-tag');
-        Obj.setValue(mutableObj, ['name'], 'Updated');
+      Obj.update(obj, (obj) => {
+        Obj.addTag(obj, 'my-tag');
+        Obj.setValue(obj, ['name'], 'Updated');
       });
 
       expect(obj.name).toBe('Updated');
@@ -97,7 +97,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 +110,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, 'tag')).toThrow(/outside of Obj.update/);
     });
   });
 
@@ -122,8 +122,8 @@ describe('Obj.change enforcement', () => {
       // Person schema uses 'name' as label field.
       expect(Obj.getLabel(obj)).toBe('John');
 
-      Obj.change(obj, (o) => {
-        Obj.setLabel(o, 'Jane');
+      Obj.update(obj, (obj) => {
+        Obj.setLabel(obj, 'Jane');
       });
 
       // setLabel updates the name field.
@@ -140,8 +140,8 @@ describe('Obj.change enforcement', () => {
 
       // setDescription only works if schema has description annotation.
       // For schemas without it, this is a no-op.
-      Obj.change(obj, (o) => {
-        Obj.setDescription(o, 'My Description');
+      Obj.update(obj, (obj) => {
+        Obj.setDescription(obj, 'My Description');
       });
 
       // Verify setDescription doesn't throw.
@@ -153,15 +153,15 @@ describe('Obj.change enforcement', () => {
 
       expect(Obj.getMeta(obj).tags).toBeUndefined();
 
-      Obj.change(obj, (o) => {
-        Obj.addTag(o, 'tag-1');
-        Obj.addTag(o, 'tag-2');
+      Obj.update(obj, (obj) => {
+        Obj.addTag(obj, 'tag-1');
+        Obj.addTag(obj, 'tag-2');
       });
 
       expect(Obj.getMeta(obj).tags).toEqual(['tag-1', 'tag-2']);
 
-      Obj.change(obj, (o) => {
-        Obj.removeTag(o, 'tag-1');
+      Obj.update(obj, (obj) => {
+        Obj.removeTag(obj, 'tag-1');
       });
 
       expect(Obj.getMeta(obj).tags).toEqual(['tag-2']);
@@ -170,8 +170,8 @@ describe('Obj.change enforcement', () => {
     test('deleteKeys removes foreign keys by source', ({ expect }) => {
       const obj = Obj.make(TestSchema.Person, { name: 'Test' });
 
-      Obj.change(obj, (o) => {
-        const meta = Obj.getMeta(o);
+      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' });
         meta.keys.push({ source: 'source-b', id: '3' });
@@ -179,8 +179,8 @@ describe('Obj.change enforcement', () => {
 
       expect(Obj.getMeta(obj).keys).toHaveLength(3);
 
-      Obj.change(obj, (o) => {
-        Obj.deleteKeys(o, 'source-a');
+      Obj.update(obj, (obj) => {
+        Obj.deleteKeys(obj, 'source-a');
       });
 
       expect(Obj.getMeta(obj).keys).toHaveLength(1);
@@ -190,8 +190,8 @@ describe('Obj.change enforcement', () => {
     test('setValue sets nested properties', ({ expect }) => {
       const obj = Obj.make(TestSchema.Person, { name: 'Test' });
 
-      Obj.change(obj, (o) => {
-        Obj.setValue(o, ['name'], 'Updated Name');
+      Obj.update(obj, (obj) => {
+        Obj.setValue(obj, ['name'], 'Updated Name');
       });
 
       expect(obj.name).toBe('Updated Name');
@@ -200,8 +200,8 @@ 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, (o) => {
-        const meta = Obj.getMeta(o);
+      Obj.update(obj, (obj) => {
+        const meta = Obj.getMeta(obj);
         meta.tags = ['tag-1', 'tag-2'];
         meta.keys.push({ source: 'external', id: '123' });
       });
@@ -214,12 +214,12 @@ describe('Obj.change enforcement', () => {
     test('multiple mutations in single change all persist', ({ expect }) => {
       const obj = Obj.make(TestSchema.Person, { name: 'Test' });
 
-      Obj.change(obj, (o) => {
-        o.name = 'Name 1';
-        o.name = 'Name 2';
-        o.name = 'Name 3';
-        Obj.addTag(o, 'tag-1');
-        Obj.addTag(o, 'tag-2');
+      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');
       });
 
       // All mutations should persist.
@@ -229,7 +229,7 @@ describe('Obj.change enforcement', () => {
   });
 
   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,9 +237,9 @@ describe('Obj.change enforcement', () => {
         notificationCount++;
       });
 
-      Obj.change(obj, (p) => {
-        p.name = 'Jane';
-        p.age = 30;
+      Obj.update(obj, (obj) => {
+        obj.name = 'Jane';
+        obj.age = 30;
       });
 
       // Should only fire one notification for all changes.
@@ -250,36 +250,36 @@ 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, (p) => {
-        p.address!.state = 'NY';
+      Obj.update(obj, (obj) => {
+        obj.address!.state = 'NY';
       });
 
       expect(obj.address?.state).toBe('NY');
       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, (p) => {
-        p.address!.coordinates!.lat = 51.5074;
-        p.address!.coordinates!.lng = -0.1278;
+      Obj.update(obj, (obj) => {
+        obj.address!.coordinates!.lat = 51.5074;
+        obj.address!.coordinates!.lng = -0.1278;
       });
 
       expect(obj.address?.coordinates?.lat).toBe(51.5074);
       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 +288,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,18 +300,18 @@ 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, (p) => {
-        p.name = 'Jane';
+      Obj.update(obj, (obj) => {
+        obj.name = 'Jane';
 
         // Nested change should work (already in change context).
-        Obj.change(obj, (p2) => {
-          p2.age = 30;
+        Obj.update(obj, (obj) => {
+          obj.age = 30;
         });
       });
 
@@ -323,8 +323,8 @@ describe('Obj.change enforcement', () => {
       const obj = Obj.make(TestSchema.Person, { name: 'John' });
 
       expect(() => {
-        Obj.change(obj, (p) => {
-          p.name = 'Jane';
+        Obj.update(obj, (obj) => {
+          obj.name = 'Jane';
           throw new Error('Test error');
         });
       }).toThrow('Test error');
@@ -333,26 +333,26 @@ 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, (p) => {
-        p.fields!.push({ label: 'tag2', value: 'val2' });
+      Obj.update(obj, (obj) => {
+        obj.fields!.push({ label: 'tag2', value: 'val2' });
       });
 
       expect(obj.fields).toHaveLength(2);
       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,15 +362,15 @@ describe('Obj.change enforcement', () => {
       });
 
       let popped: any;
-      Obj.change(obj, (p) => {
-        popped = p.fields!.pop();
+      Obj.update(obj, (obj) => {
+        popped = obj.fields!.pop();
       });
 
       expect(popped.label).toBe('b');
       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,15 +380,15 @@ describe('Obj.change enforcement', () => {
         ],
       });
 
-      Obj.change(obj, (p) => {
-        p.fields!.splice(1, 1, { label: 'x', value: 'x' });
+      Obj.update(obj, (obj) => {
+        obj.fields!.splice(1, 1, { label: 'x', value: 'x' });
       });
 
       expect(obj.fields).toHaveLength(3);
       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 +397,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 +409,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 +421,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, (p) => {
-        delete p.age;
+      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,8 +455,8 @@ describe('Obj.change enforcement', () => {
         [Relation.Target]: target,
       });
 
-      Relation.change(rel, (r) => {
-        const meta = Relation.getMeta(r);
+      Relation.update(rel, (rel) => {
+        const meta = Relation.getMeta(rel);
         meta.tags = ['rel-tag'];
         meta.keys.push({ source: 'rel-source', id: 'rel-key' });
       });
@@ -473,14 +473,14 @@ describe('Obj.change enforcement', () => {
         [Relation.Target]: target,
       });
 
-      Relation.change(rel, (r) => {
-        Relation.addTag(r, 'important');
+      Relation.update(rel, (rel) => {
+        Relation.addTag(rel, 'important');
       });
 
       expect(Relation.getMeta(rel).tags).toContain('important');
 
-      Relation.change(rel, (r) => {
-        Relation.removeTag(r, 'important');
+      Relation.update(rel, (rel) => {
+        Relation.removeTag(rel, 'important');
       });
 
       expect(Relation.getMeta(rel).tags).not.toContain('important');
@@ -494,8 +494,8 @@ describe('Obj.change enforcement', () => {
 
       // Direct assignment of root ECHO objects (created with Obj.make) is not allowed.
       expect(() => {
-        Obj.change(obj, (o) => {
-          o.other = other;
+        Obj.update(obj, (obj) => {
+          obj.other = other;
         });
       }).toThrow(/Object references must be wrapped with `Ref\.make`/);
     });
@@ -504,14 +504,14 @@ describe('Obj.change enforcement', () => {
       const obj = Obj.make(TestSchema.Expando, {});
 
       // Assign a plain object (not created with Obj.make).
-      Obj.change(obj, (o) => {
-        o.nested = { value: 'initial' };
+      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, (o) => {
-        o.nested.value = 'modified';
+      Obj.update(obj, (obj) => {
+        obj.nested.value = 'modified';
       });
       expect(obj.nested.value).toBe('modified');
     });

package/src/internal/{proxy → 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/{proxy → common/proxy}/handler.test.ts

@@ -3,15 +3,13 @@
 //
 
 import { inspect } from 'node:util';
-
 import { describe, expect, test } from 'vitest';
 
 import { isNode } from '@dxos/util';
 
-import { TestSchema, updateCounter } from '../../testing';
-import { createObject } from '../object';
+import { TestSchema, updateCounter } from '../../../testing';
+import { createObject } from '../../Obj';
 import { ATTR_META } from '../types';
-
 import { makeObject } from './make-object';
 import { objectData } from './proxy-types';
 import { change } from './reactive';

package/src/internal/{proxy → common/proxy}/json-serializer.ts

@@ -7,16 +7,19 @@ import { invariant } from '@dxos/invariant';
 import { DXN } from '@dxos/keys';
 import { deepMapValues } from '@dxos/util';
 
+import { Ref } from '../../Ref';
 import {
+  ATTR_META,
   ATTR_RELATION_SOURCE,
   ATTR_RELATION_TARGET,
   ATTR_SELF_DXN,
+  ATTR_TYPE,
+  MetaId,
   RelationSourceDXNId,
   RelationTargetDXNId,
   SelfDXNId,
-} from '../entities';
-import { Ref } from '../ref';
-import { ATTR_META, ATTR_TYPE, MetaId, TypeId } from '../types';
+  TypeId,
+} from '../types';
 
 /**
  * Attaches a toJSON method to the object for typed serialization.

package/src/internal/{proxy → common/proxy}/make-object.ts

@@ -6,9 +6,8 @@ import type * as Schema from 'effect/Schema';
 
 import { ObjectId } from '@dxos/keys';
 
-import { getTypeAnnotation } from '../annotations';
+import { getTypeAnnotation } from '../../Annotation';
 import { type AnyProperties, KindId, MetaId, type ObjectMeta, ObjectMetaSchema, ParentId } from '../types';
-
 import { defineHiddenProperty } from './define-hidden-property';
 import { attachTypedJsonSerializer } from './json-serializer';
 import { createProxy, getProxyTarget, isValidProxyTarget } from './proxy-utils';

package/src/internal/{proxy → common/proxy}/ownership.ts

@@ -5,7 +5,6 @@
 import { invariant } from '@dxos/invariant';
 
 import { KindId } from '../types';
-
 import { queueOwnerNotification } from './change-context';
 import { defineHiddenProperty } from './define-hidden-property';
 import { getProxyTarget, isProxy, isValidProxyTarget } from './proxy-utils';

package/src/internal/{proxy → common/proxy}/reactive-array.ts

@@ -34,7 +34,7 @@ const checkArrayMutationAllowed = (arr: any, method: string): void => {
 
 /**
  * Extends the native array to make sure that arrays methods are correctly reactive.
- * Enforces that mutations only happen within Obj.change() context.
+ * Enforces that mutations only happen within Obj.update() context.
  */
 export class ReactiveArray<T> extends Array<T> {
   static override get [Symbol.species]() {

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

@@ -0,0 +1,54 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, expect, test } from 'vitest';
+
+import * as Obj from '../../../Obj';
+import { TestSchema } from '../../../testing';
+
+describe('Obj.subscribe', () => {
+  test('subscribes and fires for reactive proxies', () => {
+    const obj = Obj.make(TestSchema.Person, { name: 'Test' });
+    let calls = 0;
+    const unsubscribe = Obj.subscribe(obj, () => {
+      calls++;
+    });
+
+    Obj.update(obj, (obj) => {
+      obj.name = 'Updated';
+    });
+    expect(calls).toBeGreaterThan(0);
+
+    unsubscribe();
+    const seen = calls;
+    Obj.update(obj, (obj) => {
+      obj.name = 'After unsubscribe';
+    });
+    expect(calls).toBe(seen);
+  });
+
+  // Regression: queue-stored typed objects (e.g. ContextBinding) and other Obj-shaped values
+  // satisfy `Obj.isObject` (KindId is set) but are not wrapped in a reactive Proxy. Earlier
+  // versions invariant'd inside `getProxyTarget` when an atom body did `Obj.subscribe(obj)` on
+  // such an input. The contract is "no-op for non-reactive inputs"; verify the function
+  // returns gracefully instead of throwing.
+  test('returns a no-op unsubscribe for non-proxy inputs', () => {
+    const queueShaped: any = {
+      id: '01KQ5NKXJWSKMRPVTVG2GHV8V3',
+      blueprints: { added: [], removed: [] },
+      objects: { added: [], removed: [] },
+    };
+    const unsubscribe = Obj.subscribe(queueShaped, () => {});
+    expect(typeof unsubscribe).toBe('function');
+    expect(() => unsubscribe()).not.toThrow();
+  });
+
+  test('returns a no-op unsubscribe for primitives, null, and undefined', () => {
+    for (const value of [null, undefined, 42, 'string', true]) {
+      const unsubscribe = Obj.subscribe(value as any, () => {});
+      expect(typeof unsubscribe).toBe('function');
+      expect(() => unsubscribe()).not.toThrow();
+    }
+  });
+});