@dxos/echo 0.8.4-staging.ac66bdf99f → 0.9.1-main.c7dcc2e112

package/src/internal/common/proxy/make-object.ts

@@ -4,41 +4,57 @@
 
 import type * as Schema from 'effect/Schema';
 
-import { ObjectId } from '@dxos/keys';
+import { EntityId } from '@dxos/keys';
 
-import { getTypeAnnotation } from '../../Annotation';
-import { type AnyProperties, KindId, MetaId, type ObjectMeta, ObjectMetaSchema, ParentId } from '../types';
+import { getTypeAnnotation } from '../../Annotation/annotations';
+import { type AnyProperties, KindId, ParentId, SchemaKindId, StaticTypeSchemaSlot } from '../types';
+import { type EntityMeta, EntityMetaSchema } from '../types/meta';
+import { MetaId } from '../types/model-symbols';
 import { defineHiddenProperty } from './define-hidden-property';
 import { attachTypedJsonSerializer } from './json-serializer';
 import { createProxy, getProxyTarget, isValidProxyTarget } from './proxy-utils';
-import { TypedReactiveHandler, prepareTypedTarget, setMetaOwner } from './typed-handler';
+import { TypeSource, TypedReactiveHandler, prepareTypedTarget, setMetaOwner } from './typed-handler';
 
 /**
  *
  */
 // TODO(burdon): Make internal
-export type MakeObjectProps<T extends AnyProperties> = Omit<T, 'id' | KindId>;
+// Omits the brand slots — those get stamped on the instance by the entity
+// handler (KindId via setKind, SchemaKindId derived in the proxy `get` trap
+// from kind + jsonSchema.entityKind, StaticTypeSchemaSlot lazily via the
+// proxy), not supplied by the caller.
+export type MakeObjectProps<T extends AnyProperties> = Omit<T, 'id' | KindId | SchemaKindId | StaticTypeSchemaSlot>;
 
 /**
  * Creates a reactive object from a plain Javascript object.
  * Requires a TS-effect schema.
+ *
+ * Callers that have a `Type.Type` entity (not a raw schema) must unwrap it
+ * themselves — `Obj.make` / `Relation.make` do this via `Type.getSchema(...)`
+ * and pass the entity through as `typeSource` so the instance carries a
+ * back-reference for `Obj.getType` and resolves the live source schema
+ * uniformly via the entity's `[StaticTypeSchemaSlot]`.
  */
 // TODO(burdon): Make internal
 // TODO(dmaretskyi): Deep mutability.
 // TODO(dmaretskyi): Invert generics (generic over schema) to have better error messages.
 // TODO(dmaretskyi): Could mutate original object making it unusable.
-export const makeObject: {
-  <T extends AnyProperties>(
-    schema: Schema.Schema<T, any, never>,
-    obj: NoInfer<MakeObjectProps<T>>,
-    meta?: ObjectMeta,
-  ): T;
-} = <T extends AnyProperties>(schema: Schema.Schema<T, any>, obj: MakeObjectProps<T>, meta?: ObjectMeta): T => {
+export const makeObject = <T extends AnyProperties>(
+  schema: Schema.Schema<T, any, never>,
+  obj: NoInfer<MakeObjectProps<T>>,
+  meta?: Partial<EntityMeta>,
+  typeSource?: TypeSource,
+): T => {
   // Use Object.assign to copy symbol properties (like ParentId) that spread operator doesn't copy.
-  return createReactiveObject<T>(Object.assign({}, obj) as T, meta, schema);
+  return createReactiveObject<T>(Object.assign({}, obj) as T, meta, schema as Schema.Schema<T, any>, typeSource);
 };
 
-const createReactiveObject = <T extends AnyProperties>(obj: T, meta?: ObjectMeta, schema?: Schema.Schema<T>): T => {
+const createReactiveObject = <T extends AnyProperties>(
+  obj: T,
+  meta?: Partial<EntityMeta>,
+  schema?: Schema.Schema<T>,
+  typeSource?: TypeSource,
+): T => {
   if (!isValidProxyTarget(obj)) {
     throw new Error('Value cannot be made into a reactive object.');
   }
@@ -62,7 +78,7 @@ const createReactiveObject = <T extends AnyProperties>(obj: T, meta?: ObjectMeta
   if (parent !== undefined) {
     defineHiddenProperty(obj, ParentId, parent);
   }
-  prepareTypedTarget(obj, schema);
+  prepareTypedTarget(obj, schema, typeSource);
   attachTypedJsonSerializer(obj);
   const proxy = createProxy<T>(obj, TypedReactiveHandler.instance);
 
@@ -87,11 +103,11 @@ const createReactiveObject = <T extends AnyProperties>(obj: T, meta?: ObjectMeta
 const setIdOnTarget = (target: any) => {
   // invariant(!('id' in target), 'Object already has an `id` field, which is reserved.');
   if ('id' in target && target.id !== undefined && target.id !== null) {
-    if (!ObjectId.isValid(target.id)) {
+    if (!EntityId.isValid(target.id)) {
       throw new Error('Invalid object id format.');
     }
   } else {
-    target.id = ObjectId.random();
+    target.id = EntityId.random();
   }
 };
 
@@ -99,7 +115,15 @@ const setIdOnTarget = (target: any) => {
  * Set metadata on object.
  */
 // TODO(dmaretskyi): Move to echo-schema.
-const initMeta = <T>(obj: T, meta: ObjectMeta = { keys: [] }) => {
-  prepareTypedTarget(meta, ObjectMetaSchema);
-  defineHiddenProperty(obj, MetaId, createProxy(meta, TypedReactiveHandler.instance as any));
+const initMeta = <T>(obj: T, meta?: Partial<EntityMeta>) => {
+  // Backfill required fields so callers may pass a partial meta, or one whose `keys`/`tags`/
+  // `annotations` are explicitly `undefined` (coalesce, don't let a spread reintroduce undefined).
+  const fullMeta: EntityMeta = {
+    ...meta,
+    keys: meta?.keys ?? [],
+    tags: meta?.tags ?? [],
+    annotations: meta?.annotations ?? {},
+  };
+  prepareTypedTarget(fullMeta, EntityMetaSchema);
+  defineHiddenProperty(obj, MetaId, createProxy(fullMeta, TypedReactiveHandler.instance as any));
 };

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

@@ -221,12 +221,12 @@ export const getEchoRoot = (target: object, depth = 0): object => {
 
   // Root ECHO objects (those created with Obj.make or Relation.make) have KindId set.
   // They maintain their own change context identity even when nested inside another object.
-  // Nested helper objects like ObjectMeta don't have KindId and should follow their owner.
+  // Nested helper objects like EntityMeta don't have KindId and should follow their owner.
   if (KindId in target) {
     return target;
   }
 
-  // For non-root objects (nested records, ObjectMeta, etc.), follow the owner chain.
+  // For non-root objects (nested records, EntityMeta, etc.), follow the owner chain.
   const owner = getOwner(target);
   if (owner) {
     return getEchoRoot(owner, depth + 1);

package/src/internal/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. AiContext.Binding) 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();
+    }
+  });
+});

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

@@ -3,7 +3,7 @@
 //
 
 import { type RefTypeId } from '../../Ref/ref';
-import { getProxyTarget } from './proxy-utils';
+import { getProxyTarget, isProxy } from './proxy-utils';
 import { ChangeId, EventId } from './symbols';
 
 /**
@@ -14,6 +14,15 @@ import { ChangeId, EventId } from './symbols';
  */
 // TODO(wittjosiah): Consider throwing if obj doesn't have EventId instead of returning no-op.
 export const subscribe = (obj: unknown, callback: () => void): (() => void) => {
+  // Guard against non-reactive inputs (queue-stored typed objects, snapshots, plain shapes
+  // with branded symbols) before `getProxyTarget`'s `ProxyHandlerSlot` invariant kicks in.
+  // `Obj.isObject` (KindId-based) is satisfied by these inputs, so callers like
+  // `Atom.family((obj) => Atom.make((get) => Obj.subscribe(obj, ...)))` legitimately reach
+  // here with a non-proxy. Falling back to a no-op preserves the documented contract that
+  // values without subscription support get a no-op unsubscribe.
+  if (!isProxy(obj)) {
+    return () => {};
+  }
   const target = getProxyTarget(obj as any);
   if (target && EventId in target) {
     return (target as any)[EventId].on(callback);
@@ -23,7 +32,7 @@ export const subscribe = (obj: unknown, callback: () => void): (() => void) => {
 
 /**
  * Deeply removes readonly modifiers from all properties of T.
- * Inside Obj.change, all properties are fully mutable regardless of schema definition.
+ * Inside Obj.update, all properties are fully mutable regardless of schema definition.
  * Ref types are preserved as-is since they are value-like objects that are replaced, not mutated.
  * Primitive types (including branded primitives) are preserved as-is.
  */

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

@@ -6,34 +6,43 @@ import * as Schema from 'effect/Schema';
 import * as SchemaAST from 'effect/SchemaAST';
 import { describe, expect, test } from 'vitest';
 
+import { invariant } from '@dxos/invariant';
+import { DXN } from '@dxos/keys';
+
 import { createEchoSchema } from '../../../testing';
+import * as Type from '../../../Type';
 import { PropertyMeta, getPropertyMetaAnnotation, getTypeAnnotation } from '../../Annotation';
 import { EchoObjectSchema } from '../../Entity';
 
-// TODO(dmaretskyi): Comment.
-const EmptySchemaType = Schema.Struct({}).pipe(
-  EchoObjectSchema({
-    typename: 'com.example.type.empty',
-    version: '0.1.0',
-  }),
-);
+// Test-local: introspect a Type.Type entity's properties via its rebuilt Effect
+// Schema, filter the implicit `id` field, and unwrap `T | undefined` optionality.
+const getProperties = (type: Type.Type): SchemaAST.PropertySignature[] => {
+  const ast = Type.getSchema(type).ast;
+  invariant(SchemaAST.isTypeLiteral(ast));
+  return [...ast.propertySignatures]
+    .filter((p) => p.name !== 'id')
+    .map((p) => {
+      if (!SchemaAST.isUnion(p.type)) {
+        return p;
+      }
+      const nonUndefined = p.type.types.find((t) => !SchemaAST.isUndefinedKeyword(t))!;
+      return { ...p, type: nonUndefined } as SchemaAST.PropertySignature;
+    });
+};
+
+const EmptySchemaType = Schema.Struct({}).pipe(EchoObjectSchema(DXN.make('com.example.type.empty', '0.1.0')));
 
-interface EmptySchemaType extends Schema.Schema.Type<typeof EmptySchemaType> {}
+type EmptySchemaType = Type.InstanceType<typeof EmptySchemaType>;
 
 describe('dynamic schema', () => {
   test('getProperties filters out id and unwraps optionality', async () => {
     const TestSchema = Schema.Struct({
       field1: Schema.String,
       field2: Schema.Boolean,
-    }).pipe(
-      EchoObjectSchema({
-        typename: 'com.example.type.test',
-        version: '0.1.0',
-      }),
-    );
+    }).pipe(EchoObjectSchema(DXN.make('com.example.type.test', '0.1.0')));
 
-    const registered = createEchoSchema(TestSchema);
-    expect(registered.getProperties().map((p) => [p.name, p.type])).to.deep.eq([
+    const registered = createEchoSchema(Type.getSchema(TestSchema));
+    expect(getProperties(registered).map((p) => [p.name, p.type])).to.deep.eq([
       ['field1', SchemaAST.stringKeyword],
       ['field2', SchemaAST.booleanKeyword],
     ]);
@@ -42,28 +51,23 @@ describe('dynamic schema', () => {
   test('addColumns', async () => {
     const TestSchema = Schema.Struct({
       field1: Schema.String,
-    }).pipe(
-      EchoObjectSchema({
-        typename: 'com.example.type.test',
-        version: '0.1.0',
-      }),
-    );
+    }).pipe(EchoObjectSchema(DXN.make('com.example.type.test', '0.1.0')));
 
-    const registered = createEchoSchema(TestSchema);
-    registered.addFields({ field2: Schema.Boolean });
-    expect(registered.getProperties().map((p) => [p.name, p.type])).to.deep.eq([
+    const registered = createEchoSchema(Type.getSchema(TestSchema));
+    Type.addFields(registered, { field2: Schema.Boolean });
+    expect(getProperties(registered).map((p) => [p.name, p.type])).to.deep.eq([
       ['field1', SchemaAST.stringKeyword],
       ['field2', SchemaAST.booleanKeyword],
     ]);
   });
 
   test('updateColumns preserves order of existing and appends new fields', async () => {
-    const registered = createEchoSchema(EmptySchemaType);
-    registered.addFields({ field1: Schema.String });
-    registered.addFields({ field2: Schema.Boolean });
-    registered.addFields({ field3: Schema.Number });
-    registered.updateFields({ field4: Schema.Boolean, field2: Schema.String });
-    expect(registered.getProperties().map((p) => [p.name, p.type])).to.deep.eq([
+    const registered = createEchoSchema(Type.getSchema(EmptySchemaType));
+    Type.addFields(registered, { field1: Schema.String });
+    Type.addFields(registered, { field2: Schema.Boolean });
+    Type.addFields(registered, { field3: Schema.Number });
+    Type.updateFields(registered, { field4: Schema.Boolean, field2: Schema.String });
+    expect(getProperties(registered).map((p) => [p.name, p.type])).to.deep.eq([
       ['field1', SchemaAST.stringKeyword],
       ['field2', SchemaAST.stringKeyword],
       ['field3', SchemaAST.numberKeyword],
@@ -72,12 +76,12 @@ describe('dynamic schema', () => {
   });
 
   test('removeColumns', async () => {
-    const registered = createEchoSchema(EmptySchemaType);
-    registered.addFields({ field1: Schema.String });
-    registered.addFields({ field2: Schema.Boolean });
-    registered.addFields({ field3: Schema.Number });
-    registered.removeFields(['field2']);
-    expect(registered.getProperties().map((p) => [p.name, p.type])).to.deep.eq([
+    const registered = createEchoSchema(Type.getSchema(EmptySchemaType));
+    Type.addFields(registered, { field1: Schema.String });
+    Type.addFields(registered, { field2: Schema.Boolean });
+    Type.addFields(registered, { field3: Schema.Number });
+    Type.removeFields(registered, ['field2']);
+    expect(getProperties(registered).map((p) => [p.name, p.type])).to.deep.eq([
       ['field1', SchemaAST.stringKeyword],
       ['field3', SchemaAST.numberKeyword],
     ]);
@@ -86,60 +90,18 @@ describe('dynamic schema', () => {
   test('schema manipulations preserve annotations', async () => {
     const metaNamespace = 'dxos.test';
     const metaInfo = { maxLength: 10 };
-    const registered = createEchoSchema(EmptySchemaType);
-    registered.addFields({
+    const registered = createEchoSchema(Type.getSchema(EmptySchemaType));
+    Type.addFields(registered, {
       field1: Schema.String.pipe(PropertyMeta(metaNamespace, metaInfo)),
       field2: Schema.String,
     });
-    registered.addFields({ field3: Schema.String });
-    registered.updateFields({ field3: Schema.Boolean });
-    registered.removeFields(['field2']);
-    expect(getTypeAnnotation(registered)).to.deep.contain({
+    Type.addFields(registered, { field3: Schema.String });
+    Type.updateFields(registered, { field3: Schema.Boolean });
+    Type.removeFields(registered, ['field2']);
+    expect(getTypeAnnotation(Type.getSchema(registered))).to.deep.contain({
       typename: 'com.example.type.empty',
       version: '0.1.0',
     });
-    expect(getPropertyMetaAnnotation(registered.getProperties()[0], metaNamespace)).to.deep.eq(metaInfo);
-  });
-
-  test('updates typename', async ({ expect }) => {
-    // Create schema with some fields and annotations.
-    const registered = createEchoSchema(EmptySchemaType);
-    const originalVersion = registered.persistentSchema.version;
-    registered.addFields({
-      name: Schema.String.pipe(PropertyMeta('test', { maxLength: 10 })),
-      age: Schema.Number,
-    });
-
-    // First update.
-    const newTypename1 = 'com.example.type.individual';
-    registered.updateTypename(newTypename1);
-
-    // Basic typename update checks.
-    expect(registered.typename).toBe(newTypename1);
-    expect(registered.jsonSchema.$id).toBe(`dxn:type:${newTypename1}`);
-    expect(registered.jsonSchema.typename).toBe(newTypename1);
-
-    // Version preservation check.
-    expect(registered.persistentSchema.version).toBe(originalVersion);
-
-    // Field preservation check.
-    const properties = registered.getProperties();
-    expect(properties).toHaveLength(2);
-    expect(properties[0].name).toBe('name');
-
-    // Annotation preservation check.
-    const nameMeta = getPropertyMetaAnnotation(properties[0], 'test');
-    expect(nameMeta).toEqual({ maxLength: 10 });
-
-    // Second update to ensure multiple updates work.
-    const newTypename2 = 'com.example.type.person';
-    registered.updateTypename(newTypename2);
-    expect(registered.typename).toBe(newTypename2);
-    expect(registered.jsonSchema.$id).toBe(`dxn:type:${newTypename2}`);
-    expect(registered.jsonSchema.typename).toBe(newTypename2);
-    expect(getTypeAnnotation(registered)).to.deep.contain({
-      typename: 'com.example.type.person',
-      version: '0.1.0',
-    });
+    expect(getPropertyMetaAnnotation(getProperties(registered)[0], metaNamespace)).to.deep.eq(metaInfo);
   });
 });

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

@@ -5,11 +5,14 @@
 import * as Schema from 'effect/Schema';
 import { describe, expect, test } from 'vitest';
 
+import { DXN } from '@dxos/keys';
+
+import * as Obj from '../../../Obj';
 import { TestSchema } from '../../../testing';
 import { EchoObjectSchema } from '../../Entity';
 import { setValue } from '../../Obj';
 import { Ref } from '../../Ref';
-import { foreignKey, getMeta } from '../types';
+import { foreignKey, getMeta } from '../types/meta';
 import { makeObject } from './make-object';
 import { change, subscribe } from './reactive';
 
@@ -39,15 +42,13 @@ describe('complex schema validations', () => {
 
   test('references', () => {
     const Foo = Schema.Struct({ field: Schema.String }).pipe(
-      EchoObjectSchema({ typename: 'com.example.type.foo', version: '0.1.0' }),
-    );
-    const Bar = Schema.Struct({ fooRef: Ref(Foo) }).pipe(
-      EchoObjectSchema({ typename: 'com.example.type.bar', version: '0.1.0' }),
+      EchoObjectSchema(DXN.make('com.example.type.foo', '0.1.0')),
     );
+    const Bar = Schema.Struct({ fooRef: Ref(Foo) }).pipe(EchoObjectSchema(DXN.make('com.example.type.bar', '0.1.0')));
     const field = 'hello';
-    expect(() => makeObject(Bar, { fooRef: { id: '1', field } as any })).to.throw();
-    expect(() => makeObject(Bar, { fooRef: undefined as any })).to.throw(); // Unresolved reference.
-    const bar = makeObject(Bar, { fooRef: Ref.make(makeObject(Foo, { field })) });
+    expect(() => Obj.make(Bar, { fooRef: { id: '1', field } as any })).to.throw();
+    expect(() => Obj.make(Bar, { fooRef: undefined as any })).to.throw(); // Unresolved reference.
+    const bar = Obj.make(Bar, { fooRef: Ref.make(Obj.make(Foo, { field })) });
     expect(bar.fooRef.target?.field).to.eq(field);
   });
 
@@ -79,7 +80,7 @@ describe('complex schema validations', () => {
   // Untyped reactive objects are no longer supported - use Atoms for untyped reactive state.
 
   test('creating an object with data from another object', () => {
-    const contact = makeObject(TestSchema.Person, {
+    const contact = Obj.make(TestSchema.Person, {
       name: 'Robert Smith',
       email: 'robert@example.com',
     });
@@ -94,9 +95,9 @@ describe('complex schema validations', () => {
 
   test('subscribe', () => {
     const TestSchema = Schema.Struct({ field: Schema.String }).pipe(
-      EchoObjectSchema({ typename: 'Test', version: '0.1.0' }),
+      EchoObjectSchema(DXN.make('com.test.type.test', '0.1.0')),
     );
-    const object = makeObject(TestSchema, { field: 'value' });
+    const object = Obj.make(TestSchema, { field: 'value' });
     let called = 0;
     const unsubscribe = subscribe(object as any, () => {
       called++;

package/src/internal/common/proxy/typed-handler.ts

@@ -8,10 +8,11 @@ import { type InspectOptionsStylized } from 'node:util';
 
 import { Event } from '@dxos/async';
 import { inspectCustom } from '@dxos/debug';
-import { invariant } from '@dxos/invariant';
+import { assertArgument, invariant } from '@dxos/invariant';
 
-import { getSchemaDXN } from '../../Annotation';
-import { ObjectDeletedId, ParentId, SchemaId, TypeId } from '../types';
+import { getSchemaURI } from '../../Annotation/annotations';
+import { toEffectSchema } from '../../JsonSchema/json-schema';
+import { ObjectDeletedId, ParentId, SchemaId, StaticTypeSchemaSlot, TypeEntityId, TypeId } from '../types';
 import { executeChange, isInChangeContext, queueNotification } from './change-context';
 import { defineHiddenProperty } from './define-hidden-property';
 import { createPropertyDeleteError } from './errors';
@@ -142,7 +143,7 @@ export class TypedReactiveHandler implements ReactiveHandler<ProxyTarget> {
   private constructor() {}
 
   init(target: ProxyTarget): void {
-    invariant(typeof target === 'object' && target !== null);
+    assertArgument(typeof target === 'object' && target !== null, 'target');
     invariant(SchemaId in target, 'Schema is not defined for the target');
 
     // Only set EventId on root objects (those without an owner).
@@ -208,6 +209,27 @@ export class TypedReactiveHandler implements ReactiveHandler<ProxyTarget> {
         // Uses target as both the context key and event target for non-database objects.
         return (callback: (obj: any) => void) => executeChange(target, target, receiver, callback);
       }
+      case TypeEntityId: {
+        // The back-reference to the type entity is metadata — return the raw
+        // value so we don't re-wrap an already-reactive `Type.Type` entity in
+        // another proxy (which would fail the SchemaId-in-target invariant).
+        return Reflect.get(target, prop, receiver);
+      }
+      case StaticTypeSchemaSlot: {
+        // Lazily rebuild the source Effect Schema from `jsonSchema` and cache it on
+        // the slot; the set-trap invalidates the cache when `jsonSchema` is mutated.
+        const existing = Reflect.get(target, prop, receiver);
+        if (existing !== undefined) {
+          return existing;
+        }
+        const jsonSchema = (target as any).jsonSchema;
+        if (jsonSchema == null) {
+          return undefined;
+        }
+        const rebuilt = toEffectSchema(jsonSchema);
+        defineHiddenProperty(target, StaticTypeSchemaSlot, rebuilt);
+        return rebuilt;
+      }
     }
 
     // Handle getter properties.
@@ -226,7 +248,7 @@ export class TypedReactiveHandler implements ReactiveHandler<ProxyTarget> {
   set(target: ProxyTarget, prop: string | symbol, value: any, receiver: any): boolean {
     const echoRoot = getEchoRoot(target);
 
-    // Check readonly enforcement - mutations only allowed within Obj.change().
+    // Check readonly enforcement - mutations only allowed within Obj.update().
     // Skip check if the object is still being initialized (no ChangeId handler yet).
     // Also skip for non-initialized root objects (those without EventId).
     // Skip for symbol properties (internal infrastructure, not user data).
@@ -234,8 +256,8 @@ export class TypedReactiveHandler implements ReactiveHandler<ProxyTarget> {
     const isSymbolProp = typeof prop === 'symbol';
     if (isInitialized && !isSymbolProp && !isInChangeContext(echoRoot)) {
       throw new Error(
-        `Cannot modify object property "${String(prop)}" outside of Obj.change(). ` +
-          'Use Obj.change(obj, (mutableObj) => { mutableObj.property = value; }) instead.',
+        `Cannot modify object property "${String(prop)}" outside of Obj.update(). ` +
+          'Use Obj.update(obj, (mutableObj) => { mutableObj.property = value; }) instead.',
       );
     }
 
@@ -245,6 +267,11 @@ export class TypedReactiveHandler implements ReactiveHandler<ProxyTarget> {
       batchEvents(() => {
         const { echoRoot: _, preparedValue } = this._prepareValueForAssignment(target, prop, value);
         result = Reflect.set(target, prop, preparedValue, receiver);
+        // Invalidate the cached source Effect Schema when `jsonSchema` changes
+        // (e.g. `Type.addFields`) so `Type.getSchema` rebuilds from the new shape.
+        if (prop === 'jsonSchema') {
+          Reflect.deleteProperty(target, StaticTypeSchemaSlot);
+        }
         // Queue notification instead of emitting immediately (batched).
         if (isInitialized) {
           queueNotification(echoRoot);
@@ -265,7 +292,7 @@ export class TypedReactiveHandler implements ReactiveHandler<ProxyTarget> {
   deleteProperty(target: ProxyTarget, property: string | symbol): boolean {
     const echoRoot = getEchoRoot(target);
 
-    // Check readonly enforcement - mutations only allowed within Obj.change().
+    // Check readonly enforcement - mutations only allowed within Obj.update().
     // Skip for symbol properties (internal infrastructure, not user data).
     const isInitialized = (echoRoot as any)[ChangeId] === true || EventId in echoRoot;
     const isSymbolProp = typeof property === 'symbol';
@@ -283,15 +310,15 @@ export class TypedReactiveHandler implements ReactiveHandler<ProxyTarget> {
   defineProperty(target: ProxyTarget, property: string | symbol, attributes: PropertyDescriptor): boolean {
     const echoRoot = getEchoRoot(target);
 
-    // Check readonly enforcement - mutations only allowed within Obj.change().
+    // Check readonly enforcement - mutations only allowed within Obj.update().
     // Skip check if the object is still being initialized (no ChangeId handler yet).
     // Skip for symbol properties (internal infrastructure, not user data).
     const isInitialized = ChangeId in echoRoot || EventId in echoRoot;
     const isSymbolProp = typeof property === 'symbol';
     if (isInitialized && !isSymbolProp && !isInChangeContext(echoRoot)) {
       throw new Error(
-        `Cannot modify object property "${String(property)}" outside of Obj.change(). ` +
-          'Use Obj.change(obj, (mutableObj) => { mutableObj.property = value; }) instead.',
+        `Cannot modify object property "${String(property)}" outside of Obj.update(). ` +
+          'Use Obj.update(obj, (mutableObj) => { mutableObj.property = value; }) instead.',
       );
     }
 
@@ -400,16 +427,49 @@ const toJSON = (target: ProxyTarget): any => {
   return { '@type': 'TypedReactiveObject', ...target };
 };
 
+/**
+ * Pointer to a `Type.Type` entity, stamped as the back-reference (`TypeEntityId`)
+ * on instances and read by the `SchemaId` getter installed below.
+ *
+ * Structural shape (not `Type.AnyEntity`) because `internal/common/proxy/`
+ * can't import the top-level `Type` module without a cycle. Every kind of
+ * `Type.Type` entity satisfies this shape:
+ *   - Static (`Type.makeObject(dxn)` pipe) — slot set directly on the object.
+ *   - Persisted (echo-handler-wrapped) — slot exposed via that handler's
+ *     `get` trap (rebuilds from `data.jsonSchema`).
+ *   - In-memory pre-persist (`Type.makeObjectFromJsonSchema`) — slot exposed
+ *     via the `case StaticTypeSchemaSlot:` arm in this file's `get` trap.
+ */
+export type TypeSource = { readonly [StaticTypeSchemaSlot]?: Schema.Schema.AnyNoContext };
+
 /**
  * Recursively set AST on all potential proxy targets.
  */
-const setSchemaProperties = (obj: any, schema: Schema.Schema.AnyNoContext) => {
-  const schemaType = getSchemaDXN(schema);
+const setSchemaProperties = (obj: any, schema: Schema.Schema.AnyNoContext, typeSource?: TypeSource) => {
+  const schemaType = getSchemaURI(schema);
   if (schemaType != null) {
     defineHiddenProperty(obj, TypeId, schemaType);
   }
 
-  defineHiddenProperty(obj, SchemaId, schema);
+  if (typeSource != null) {
+    // Keep a back-reference to the type entity so `Obj.getType` /
+    // `Relation.getType` / `Entity.getType` can return it.
+    defineHiddenProperty(obj, TypeEntityId, typeSource);
+
+    // Install `SchemaId` as a getter that reads through the entity's static
+    // schema slot. The three entity shapes (static / persisted / in-memory
+    // pre-persist) each populate the slot via their own get-trap path, so
+    // `Type.update` / `Type.addFields` mutations propagate into validation
+    // for objects created via `Obj.make(typeEntity, ...)` without this file
+    // having to rebuild from `jsonSchema` itself.
+    Object.defineProperty(obj, SchemaId, {
+      get: () => typeSource[StaticTypeSchemaSlot] ?? schema,
+      enumerable: false,
+      configurable: true,
+    });
+  } else {
+    defineHiddenProperty(obj, SchemaId, schema);
+  }
   for (const key in obj) {
     if (isValidProxyTarget(obj[key])) {
       const elementSchema = SchemaValidator.getTargetPropertySchema(obj, key);
@@ -420,7 +480,9 @@ const setSchemaProperties = (obj: any, schema: Schema.Schema.AnyNoContext) => {
   }
 };
 
-export const prepareTypedTarget = <T>(target: T, schema: Schema.Schema<T>) => {
+// Accepts any encoded type: the typed handler operates on the decoded representation, so schemas
+// whose encoded form differs (e.g. refs encode as `{ '/': uri }`) are valid here.
+export const prepareTypedTarget = <T>(target: T, schema: Schema.Schema<T, any>, typeSource?: TypeSource) => {
   // log.info('prepareTypedTarget', { target, schema });
   if (!SchemaAST.isTypeLiteral(schema.ast)) {
     throw new Error('schema has to describe an object type');
@@ -429,7 +491,7 @@ export const prepareTypedTarget = <T>(target: T, schema: Schema.Schema<T>) => {
   SchemaValidator.validateSchema(schema);
   const _ = Schema.asserts(schema)(target);
   makeArraysReactive(target);
-  setSchemaProperties(target, schema);
+  setSchemaProperties(target, schema, typeSource);
 };
 
 const makeArraysReactive = (target: any) => {