@dxos/echo 0.8.4-main.ef1bc66f44 → 0.8.4-main.effb148878

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

@@ -6,40 +6,62 @@ import type * as Schema from 'effect/Schema';
 
 import { ObjectId } from '@dxos/keys';
 
-import { getTypeAnnotation } from '../annotations';
-import { type AnyProperties, KindId, MetaId, type ObjectMeta, ObjectMetaSchema, ParentId } from '../types';
-
+import { getTypeAnnotation } from '../../Annotation';
+import {
+  type AnyProperties,
+  KindId,
+  MetaId,
+  type ObjectMeta,
+  ObjectMetaSchema,
+  ParentId,
+  SchemaKindId,
+  StaticTypeSchemaSlot,
+} from '../types';
 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?: ObjectMeta,
+  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?: ObjectMeta,
+  schema?: Schema.Schema<T>,
+  typeSource?: TypeSource,
+): T => {
   if (!isValidProxyTarget(obj)) {
     throw new Error('Value cannot be made into a reactive object.');
   }
@@ -63,7 +85,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);
 

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. 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/{proxy → common/proxy}/reactive.ts

@@ -2,9 +2,8 @@
 // Copyright 2025 DXOS.org
 //
 
-import { type RefTypeId } from '../ref/ref';
-
-import { getProxyTarget } from './proxy-utils';
+import { type RefTypeId } from '../../Ref/ref';
+import { getProxyTarget, isProxy } from './proxy-utils';
 import { ChangeId, EventId } from './symbols';
 
 /**
@@ -15,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);
@@ -24,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

@@ -0,0 +1,107 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+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';
+
+// 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')));
+
+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(DXN.make('com.example.type.test', '0.1.0')));
+
+    const registered = createEchoSchema(Type.getSchema(TestSchema));
+    expect(getProperties(registered).map((p) => [p.name, p.type])).to.deep.eq([
+      ['field1', SchemaAST.stringKeyword],
+      ['field2', SchemaAST.booleanKeyword],
+    ]);
+  });
+
+  test('addColumns', async () => {
+    const TestSchema = Schema.Struct({
+      field1: Schema.String,
+    }).pipe(EchoObjectSchema(DXN.make('com.example.type.test', '0.1.0')));
+
+    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(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],
+      ['field4', SchemaAST.booleanKeyword],
+    ]);
+  });
+
+  test('removeColumns', async () => {
+    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],
+    ]);
+  });
+
+  test('schema manipulations preserve annotations', async () => {
+    const metaNamespace = 'dxos.test';
+    const metaInfo = { maxLength: 10 };
+    const registered = createEchoSchema(Type.getSchema(EmptySchemaType));
+    Type.addFields(registered, {
+      field1: Schema.String.pipe(PropertyMeta(metaNamespace, metaInfo)),
+      field2: Schema.String,
+    });
+    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(getProperties(registered)[0], metaNamespace)).to.deep.eq(metaInfo);
+  });
+});

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

@@ -5,12 +5,14 @@
 import * as Schema from 'effect/Schema';
 import { describe, expect, test } from 'vitest';
 
-import { TestSchema } from '../../testing';
-import { EchoObjectSchema } from '../entities';
-import { setValue } from '../object';
-import { Ref } from '../ref';
-import { foreignKey, getMeta } from '../types';
+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 { makeObject } from './make-object';
 import { change, subscribe } from './reactive';
 
@@ -40,15 +42,13 @@ describe('complex schema validations', () => {
 
   test('references', () => {
     const Foo = Schema.Struct({ field: Schema.String }).pipe(
-      EchoObjectSchema({ typename: 'example.com/type/Foo', version: '0.1.0' }),
-    );
-    const Bar = Schema.Struct({ fooRef: Ref(Foo) }).pipe(
-      EchoObjectSchema({ typename: 'example.com/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);
   });
 
@@ -80,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',
     });
@@ -95,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/{proxy → common/proxy}/typed-handler.ts

@@ -2,19 +2,17 @@
 // Copyright 2024 DXOS.org
 //
 
-import { type InspectOptionsStylized } from 'node:util';
-
 import * as Schema from 'effect/Schema';
 import * as SchemaAST from 'effect/SchemaAST';
+import { type InspectOptionsStylized } from 'node:util';
 
 import { Event } from '@dxos/async';
 import { inspectCustom } from '@dxos/debug';
 import { invariant } from '@dxos/invariant';
 
-import { getSchemaDXN } from '../annotations';
-import { ObjectDeletedId } from '../entities';
-import { ParentId, SchemaId, TypeId } from '../types';
-
+import { getSchemaURI } from '../../Annotation';
+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';
@@ -211,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.
@@ -229,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).
@@ -237,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.',
       );
     }
 
@@ -248,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);
@@ -268,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';
@@ -286,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.',
       );
     }
 
@@ -403,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);
@@ -423,7 +480,7 @@ const setSchemaProperties = (obj: any, schema: Schema.Schema.AnyNoContext) => {
   }
 };
 
-export const prepareTypedTarget = <T>(target: T, schema: Schema.Schema<T>) => {
+export const prepareTypedTarget = <T>(target: T, schema: Schema.Schema<T>, typeSource?: TypeSource) => {
   // log.info('prepareTypedTarget', { target, schema });
   if (!SchemaAST.isTypeLiteral(schema.ast)) {
     throw new Error('schema has to describe an object type');
@@ -432,7 +489,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) => {

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

@@ -6,22 +6,20 @@ import * as Schema from 'effect/Schema';
 import type * as Types from 'effect/Types';
 import { describe, expect, test } from 'vitest';
 
-import { EchoObjectSchema } from '../entities';
-import { getSchema } from '../types';
+import { DXN } from '@dxos/keys';
 
+import * as Obj from '../../../Obj';
+import * as Type from '../../../Type';
+import { EchoObjectSchema } from '../../Entity';
+import { getSchema } from '../types';
 import { makeObject } from './make-object';
 import { change } from './reactive';
 
 const Organization = Schema.Struct({
   name: Schema.String,
-}).pipe(
-  EchoObjectSchema({
-    typename: 'example.com/type/Organization',
-    version: '0.1.0',
-  }),
-);
+}).pipe(EchoObjectSchema(DXN.make('com.example.type.organization', '0.1.0')));
 
-interface Organization extends Schema.Schema.Type<typeof Organization> {}
+type Organization = Type.InstanceType<typeof Organization>;
 
 const Contact = Schema.Struct(
   {
@@ -31,27 +29,21 @@ const Contact = Schema.Struct(
     key: Schema.String,
     value: Schema.Any,
   },
-).pipe(
-  Schema.partial,
-  EchoObjectSchema({
-    typename: 'example.com/type/Person',
-    version: '0.1.0',
-  }),
-);
+).pipe(Schema.partial, EchoObjectSchema(DXN.make('com.example.type.person', '0.1.0')));
 
-interface Contact extends Schema.Schema.Type<typeof Contact> {}
+type Contact = Type.InstanceType<typeof Contact>;
 
-const TEST_ORG: Omit<Organization, 'id'> = { name: 'Test' };
+const TEST_ORG = { name: 'Test' } satisfies Pick<Organization, 'name'>;
 
 describe('EchoObjectSchema class DSL', () => {
   test('can get object schema', async () => {
-    const obj = makeObject(Organization, TEST_ORG);
-    expect(getSchema(obj)).to.deep.eq(Organization);
+    const obj = Obj.make(Organization, TEST_ORG);
+    expect(getSchema(obj)).to.deep.eq(Type.getSchema(Organization));
   });
 
   describe('class options', () => {
     test('can assign undefined to partial fields', async () => {
-      const person = makeObject(Contact, { name: 'John' });
+      const person = Obj.make(Contact, { name: 'John' });
       change(person, (p) => {
         p.name = undefined;
         p.recordField = 'hello';
@@ -87,7 +79,7 @@ describe('EchoObjectSchema class DSL', () => {
     }
 
     {
-      // Plain object (not a reactive proxy) - doesn't need Obj.change.
+      // Plain object (not a reactive proxy) - doesn't need Obj.update.
       // Note: Schema.Schema.Type generates readonly types, so we cast to mutable for plain objects.
       type Test1 = Types.Mutable<Schema.Schema.Type<typeof schema>>;
 
@@ -99,14 +91,9 @@ describe('EchoObjectSchema class DSL', () => {
     {
       const Test2 = Schema.Struct({
         meta: Schema.optional(Schema.Record({ key: Schema.String, value: Schema.Any })),
-      }).pipe(
-        EchoObjectSchema({
-          typename: 'dxos.org/type/FunctionTrigger',
-          version: '0.1.0',
-        }),
-      );
-
-      const object = makeObject(Test2, {});
+      }).pipe(EchoObjectSchema(DXN.make('org.dxos.type.functionTrigger', '0.1.0')));
+
+      const object = Obj.make(Test2, {});
       change(object, (o) => {
         (o.meta ??= {}).test = 100;
       });

package/src/internal/{types → common/types}/base.ts

@@ -14,12 +14,12 @@ import { type ATTR_META, type ObjectMeta } from './meta';
  * NOTE: This describes the base type for all database objects.
  * It is stricter than `T extends {}` or `T extends object`.
  */
-// TODO(burdon): Make internal.
 // TODO(burdon): Prefer Record<string, unknown>.
 export type AnyProperties = Record<string, any>;
 
 /**
  * Canonical type for all ECHO entities (objects and relations).
+ * @depreacted Remove, use Entity.Unknown instead.
  */
 // TODO(wittjosiah): Remove. Prefer higher level types (e.g. Entity.Unknown).
 export interface AnyEntity {