@dxos/echo 0.8.4-main.21d9917 → 0.8.4-main.2244d791bb

package/src/internal/json-schema/json-schema-type.ts

@@ -7,6 +7,7 @@ import * as Schema from 'effect/Schema';
 import { JsonPath, type JsonProp } from '@dxos/effect';
 
 import { FormatAnnotation, TypeFormat } from '../formats';
+import { type Mutable } from '../proxy';
 import { EntityKindSchema } from '../types';
 
 //
@@ -18,7 +19,7 @@ const SimpleTypes = Schema.Literal('array', 'boolean', 'integer', 'null', 'numbe
 
 const NonNegativeInteger = Schema.Number.pipe(Schema.greaterThanOrEqualTo(0));
 
-const StringArray = Schema.Array(Schema.String).pipe(Schema.mutable);
+const StringArray = Schema.Array(Schema.String);
 
 const JsonSchemaOrBoolean = Schema.Union(
   Schema.suspend(() => JsonSchemaType),
@@ -48,7 +49,7 @@ export const JsonSchemaEchoAnnotations = Schema.Struct({
     Schema.Record({
       key: Schema.String,
       value: Schema.Any,
-    }).pipe(Schema.mutable),
+    }),
   ),
 
   /**
@@ -62,7 +63,7 @@ export const JsonSchemaEchoAnnotations = Schema.Struct({
 
       // Not used.
       schemaId: Schema.optional(Schema.String),
-    }).pipe(Schema.mutable),
+    }),
   ),
 
   /**
@@ -72,9 +73,9 @@ export const JsonSchemaEchoAnnotations = Schema.Struct({
     Schema.Record({
       key: Schema.String,
       value: Schema.Any,
-    }).pipe(Schema.mutable),
+    }),
   ),
-}).pipe(Schema.mutable);
+});
 export type JsonSchemaEchoAnnotations = Schema.Schema.Type<typeof JsonSchemaEchoAnnotations>;
 
 /**
@@ -257,23 +258,21 @@ const _JsonSchemaType = Schema.Struct({
     Schema.Record({
       key: Schema.String,
       value: Schema.suspend(() => JsonSchemaType),
-    }).pipe(Schema.mutable),
+    }),
   ),
   patternProperties: Schema.optional(
     Schema.Record({
       key: Schema.String,
       value: Schema.suspend(() => JsonSchemaType),
-    }).pipe(Schema.mutable),
+    }),
   ),
   propertyNames: Schema.optional(Schema.suspend(() => JsonSchemaType)),
 
   definitions: Schema.optional(
-    Schema.mutable(
-      Schema.Record({
-        key: Schema.String,
-        value: Schema.suspend(() => JsonSchemaType),
-      }),
-    ),
+    Schema.Record({
+      key: Schema.String,
+      value: Schema.suspend(() => JsonSchemaType),
+    }),
   ),
   dependencies: Schema.optional(
     Schema.Record({
@@ -296,12 +295,10 @@ const _JsonSchemaType = Schema.Struct({
   oneOf: Schema.optional(Schema.Array(Schema.suspend(() => JsonSchemaType))),
   not: Schema.optional(Schema.suspend(() => JsonSchemaType)),
   $defs: Schema.optional(
-    Schema.mutable(
-      Schema.Record({
-        key: Schema.String,
-        value: Schema.suspend(() => JsonSchemaType),
-      }),
-    ),
+    Schema.Record({
+      key: Schema.String,
+      value: Schema.suspend(() => JsonSchemaType),
+    }),
   ),
 
   //
@@ -311,25 +308,23 @@ const _JsonSchemaType = Schema.Struct({
   currency: Schema.optional(Schema.String),
 
   reference: Schema.optional(
-    Schema.mutable(
-      Schema.Struct({
-        schema: Schema.suspend(() => JsonSchemaType),
-        schemaVersion: Schema.optional(Schema.String),
-        schemaObject: Schema.optional(Schema.String),
-      }),
-    ),
+    Schema.Struct({
+      schema: Schema.suspend(() => JsonSchemaType),
+      schemaVersion: Schema.optional(Schema.String),
+      schemaObject: Schema.optional(Schema.String),
+    }),
   ),
 
   /**
    * ECHO-specific annotations.
    */
   // TODO(dmaretskyi): Since we are adding a lot of new extensions to the JSON Schema, it is safer to namespace them here.
-  annotations: Schema.optional(Schema.mutable(JsonSchemaEchoAnnotations)),
+  annotations: Schema.optional(JsonSchemaEchoAnnotations),
 
   /**
    * @deprecated Use `annotations` instead.
    */
-  echo: Schema.optional(Schema.mutable(JsonSchemaEchoAnnotations)),
+  echo: Schema.optional(JsonSchemaEchoAnnotations),
 }).annotations({ identifier: 'jsonSchema', description: 'JSON Schema' });
 
 export const JsonSchemaFields = Object.keys(_JsonSchemaType.fields);
@@ -338,9 +333,9 @@ export const JsonSchemaFields = Object.keys(_JsonSchemaType.fields);
  * https://json-schema.org/draft-07/schema
  */
 // TODO(burdon): Reconcile with @effect/Schema/JSONSchema
-export interface JsonSchemaType extends Schema.Schema.Type<Schema.mutable<typeof _JsonSchemaType>> {}
+export interface JsonSchemaType extends Schema.Schema.Type<typeof _JsonSchemaType> {}
 
-export const JsonSchemaType: Schema.Schema<JsonSchemaType> = _JsonSchemaType.pipe(Schema.mutable);
+export const JsonSchemaType: Schema.Schema<JsonSchemaType> = _JsonSchemaType;
 
 // TODO(burdon): Factor out JSON schema utils.
 
@@ -349,7 +344,11 @@ export const getSchemaProperty = (schema: JsonSchemaType, property: JsonProp): J
 };
 
 // TODO(burdon): Properties should be ordered.
-export const setSchemaProperty = (schema: JsonSchemaType, property: JsonProp, value: JsonSchemaType) => {
+export const setSchemaProperty = (
+  schema: Mutable<JsonSchemaType>,
+  property: JsonProp,
+  value: Mutable<JsonSchemaType>,
+) => {
   schema.properties ??= {};
   schema.properties[property] = value;
   return schema;

package/src/internal/json-schema/json-schema.ts

@@ -80,7 +80,11 @@ export type JsonSchemaOptions = {
  */
 // TODO(burdon): Reconcile with possibly extending @effect/Schema/JSONSchema
 //  We add additional propertyOrder (but the object properties ARE ordered); and type "string" for literals.
-export const toJsonSchema = (schema: Schema.Schema.All, options: JsonSchemaOptions = {}): JsonSchemaType => {
+// TODO(wittjosiah): This is mutable because its a pojo, perhaps should be left as readonly at type level though?
+export const toJsonSchema = (
+  schema: Schema.Schema.All,
+  options: JsonSchemaOptions = {},
+): Types.DeepMutable<JsonSchemaType> => {
   assertArgument(Schema.isSchema(schema), 'schema');
   let jsonSchema = _toJsonSchemaAST(schema.ast);
   if (options.strict) {
@@ -103,11 +107,11 @@ export const toJsonSchema = (schema: Schema.Schema.All, options: JsonSchemaOptio
   return jsonSchema;
 };
 
-const _toJsonSchemaAST = (ast: SchemaAST.AST): JsonSchemaType => {
+const _toJsonSchemaAST = (ast: SchemaAST.AST): Types.DeepMutable<JsonSchemaType> => {
   const withRefinements = withEchoRefinements(ast, '#');
   const jsonSchema = JSONSchema.fromAST(withRefinements, {
     definitions: {},
-  }) as JsonSchemaType;
+  }) as Types.DeepMutable<JsonSchemaType>;
 
   return normalizeJsonSchema(jsonSchema);
 };
@@ -326,7 +330,7 @@ const objectToEffectSchema = (root: JsonSchemaType, defs: JsonSchemaType['$defs'
   }
 
   if (immutableIdField) {
-    schema = Schema.extend(Schema.mutable(schema), Schema.Struct({ id: immutableIdField }));
+    schema = Schema.extend(schema, Schema.Struct({ id: immutableIdField }));
   }
 
   const annotations = jsonSchemaFieldsToAnnotations(root);
@@ -377,7 +381,7 @@ const refToEffectSchema = (root: any): Schema.Schema.AnyNoContext => {
 const annotations_toJsonSchemaFields = (annotations: SchemaAST.Annotations): Record<symbol, any> => {
   const schemaFields: Record<string, any> = {};
 
-  const echoAnnotations: JsonSchemaEchoAnnotations = {};
+  const echoAnnotations: Types.Mutable<JsonSchemaEchoAnnotations> = {};
   for (const [key, annotationId] of Object.entries(EchoAnnotations)) {
     if (annotations[annotationId] != null) {
       echoAnnotations[key as keyof JsonSchemaEchoAnnotations] = annotations[annotationId] as any;
@@ -495,7 +499,7 @@ const addJsonSchemaFields = (ast: SchemaAST.AST, schema: JsonSchemaType): Schema
  * Fixes field order.
  * Sets `$schema` prop.
  */
-const normalizeJsonSchema = (jsonSchema: JsonSchemaType): JsonSchemaType => {
+const normalizeJsonSchema = (jsonSchema: Types.DeepMutable<JsonSchemaType>): Types.DeepMutable<JsonSchemaType> => {
   if (jsonSchema.properties && 'id' in jsonSchema.properties) {
     jsonSchema.properties = orderKeys(jsonSchema.properties, ['id']); // Put id first.
   }

package/src/internal/object/json-serializer.test.ts

@@ -9,10 +9,11 @@ import { DXN } from '@dxos/keys';
 import * as Obj from '../../Obj';
 import { TestSchema } from '../../testing';
 import { getSchemaDXN, getSchemaTypename, getTypeDXN, getTypename } from '../annotations';
+import { getMetaChecked } from '../api';
 import { RelationSourceId, RelationTargetId, getObjectDXN } from '../entities';
 import { makeObject } from '../proxy';
 import { Ref, StaticRefResolver } from '../ref';
-import { ATTR_TYPE, EntityKind, KindId, MetaId, TypeId, getMeta, getSchema } from '../types';
+import { ATTR_TYPE, EntityKind, KindId, MetaId, TypeId, getSchema } from '../types';
 
 import { createObject } from './create-object';
 import { objectFromJSON, objectToJSON } from './json-serializer';
@@ -21,7 +22,7 @@ describe('Object JSON serializer', () => {
   test('should serialize and deserialize object', async () => {
     const contact = makeObject(TestSchema.Person, { name: 'Alice' });
     Obj.change(contact, (c) => {
-      getMeta(c).keys.push({ id: '12345', source: 'example.com' });
+      getMetaChecked(c).keys.push({ id: '12345', source: 'example.com' });
     });
 
     const task = createObject(TestSchema.Task, {
@@ -94,4 +95,27 @@ describe('Object JSON serializer', () => {
     expect(getObjectDXN(contactFromJson)).toEqual(getObjectDXN(contact));
     expect(getTypeDXN(contactFromJson)).toEqual(getSchemaDXN(TestSchema.Person));
   });
+
+  test('deserializes expando without leaking internal json keys', async () => {
+    const expando = Obj.make(TestSchema.Expando, { message: 'local-only' });
+    const expandoJson = objectToJSON(expando);
+
+    const refResolver = new StaticRefResolver().addSchema(TestSchema.Expando);
+    const expandoFromJson = (await objectFromJSON(expandoJson, { refResolver })) as TestSchema.Expando;
+
+    expect(expandoFromJson.id).toBe(expando.id);
+    expect(expandoFromJson.message).toBe('local-only');
+    expect((expandoFromJson as any)[ATTR_TYPE]).toBeUndefined();
+  });
+
+  test('deserializes expando without schema resolver and without leaking internal json keys', async () => {
+    const expando = Obj.make(TestSchema.Expando, { message: 'local-only' });
+    const expandoJson = objectToJSON(expando);
+
+    const expandoFromJson = (await objectFromJSON(expandoJson)) as TestSchema.Expando;
+
+    expect(expandoFromJson.id).toBe(expando.id);
+    expect(expandoFromJson.message).toBe('local-only');
+    expect((expandoFromJson as any)[ATTR_TYPE]).toBeUndefined();
+  });
 });

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

@@ -29,12 +29,14 @@ import { attachTypedJsonSerializer, defineHiddenProperty, typedJsonSerializer }
 import { Ref, type RefResolver, refFromEncodedReference, setRefResolver } from '../ref';
 import {
   ATTR_META,
+  ATTR_PARENT,
   ATTR_TYPE,
   type AnyEntity,
   EntityKind,
   KindId,
   MetaId,
   ObjectMetaSchema,
+  ParentId,
   setSchema,
 } from '../types';
 
@@ -81,15 +83,16 @@ export const objectFromJSON = async (
   const type = DXN.parse(jsonData[ATTR_TYPE]);
   const schema = await refResolver?.resolveSchema(type);
   invariant(schema === undefined || Schema.isSchema(schema));
+  const decodedInput = stripInternalJsonKeys(jsonData);
 
   let obj: any;
   if (schema != null) {
-    obj = await schema.pipe(Schema.decodeUnknownPromise)(jsonData);
+    obj = await schema.pipe(Schema.decodeUnknownPromise)(decodedInput);
     if (refResolver) {
       setRefResolverOnData(obj, refResolver);
     }
   } else {
-    obj = decodeGeneric(jsonData, { refResolver });
+    obj = decodeGeneric(decodedInput, { refResolver });
   }
 
   invariant(ObjectId.isValid(obj.id), 'Invalid object id');
@@ -126,6 +129,12 @@ export const objectFromJSON = async (
     });
   }
 
+  if (jsonData[ATTR_PARENT]) {
+    const parentDxn = DXN.parse(jsonData[ATTR_PARENT]);
+    const parent = (await refResolver?.resolve(parentDxn)) as Obj.Unknown | undefined;
+    defineHiddenProperty(obj, ParentId, parent);
+  }
+
   if (dxn) {
     defineHiddenProperty(obj, SelfDXNId, dxn);
   }
@@ -141,6 +150,18 @@ export const objectFromJSON = async (
 };
 
 const decodeGeneric = (jsonData: unknown, options: { refResolver?: RefResolver }) => {
+  const props = stripInternalJsonKeys(jsonData);
+
+  return deepMapValues(props, (value, visitor) => {
+    if (isEncodedReference(value)) {
+      return refFromEncodedReference(value, options.refResolver);
+    }
+
+    return visitor(value);
+  });
+};
+
+const stripInternalJsonKeys = (jsonData: unknown) => {
   const {
     [ATTR_TYPE]: _type,
     [ATTR_META]: _meta,
@@ -151,13 +172,7 @@ const decodeGeneric = (jsonData: unknown, options: { refResolver?: RefResolver }
     ...props
   } = jsonData as any;
 
-  return deepMapValues(props, (value, visitor) => {
-    if (isEncodedReference(value)) {
-      return refFromEncodedReference(value, options.refResolver);
-    }
-
-    return visitor(value);
-  });
+  return props;
 };
 
 export const setRefResolverOnData = (obj: AnyEntity, refResolver: RefResolver) => {
@@ -182,6 +197,7 @@ export const objectStructureToJson = (objectId: string, structure: ObjectStructu
     id: objectId,
     [ATTR_TYPE]: (ObjectStructure.getTypeReference(structure)?.['/'] ?? '') as DXN.String,
     [ATTR_DELETED]: ObjectStructure.isDeleted(structure),
+    [ATTR_PARENT]: ObjectStructure.getParent(structure)?.['/'] as DXN.String | undefined,
     [ATTR_RELATION_SOURCE]: ObjectStructure.getRelationSource(structure)?.['/'] as DXN.String | undefined,
     [ATTR_RELATION_TARGET]: ObjectStructure.getRelationTarget(structure)?.['/'] as DXN.String | undefined,
   };

package/src/internal/object/schema-validator.test.ts

@@ -27,9 +27,7 @@ describe('schema-validator', () => {
       const TestSchema: Schema.Schema.AnyNoContext = Schema.Struct({
         name: Schema.String.annotations({ [annotationId]: annotationValue }),
         parent: Schema.optional(Schema.suspend(() => TestSchema.annotations({ [annotationId]: annotationValue }))),
-        friends: Schema.suspend(() =>
-          Schema.mutable(Schema.Array(TestSchema.annotations({ [annotationId]: annotationValue }))),
-        ),
+        friends: Schema.suspend(() => Schema.Array(TestSchema.annotations({ [annotationId]: annotationValue }))),
       });
       expect(SchemaValidator.hasTypeAnnotation(TestSchema, 'name', annotationId)).to.be.true;
       expect(SchemaValidator.hasTypeAnnotation(TestSchema, 'parent', annotationId)).to.be.true;
@@ -41,7 +39,7 @@ describe('schema-validator', () => {
       const Person: Schema.Schema.AnyNoContext = Schema.Struct({
         name: Schema.String,
         parent: Schema.optional(Schema.suspend(() => Person)),
-        friends: Schema.suspend(() => Schema.mutable(Schema.Array(Person))),
+        friends: Schema.suspend(() => Schema.Array(Person)),
       });
       expect(SchemaValidator.hasTypeAnnotation(Person, 'name', annotationId)).to.be.false;
       expect(SchemaValidator.hasTypeAnnotation(Person, 'parent', annotationId)).to.be.false;
@@ -87,9 +85,7 @@ describe('schema-validator', () => {
       const annotationValue = 'bar';
       const Person: Schema.Schema.AnyNoContext = Schema.Struct({
         parent: Schema.optional(Schema.suspend(() => Person.annotations({ [annotationId]: annotationValue }))),
-        friends: Schema.suspend(() =>
-          Schema.mutable(Schema.Array(Person.annotations({ [annotationId]: annotationValue }))),
-        ),
+        friends: Schema.suspend(() => Schema.Array(Person.annotations({ [annotationId]: annotationValue }))),
       });
       expect(SchemaValidator.getPropertySchema(Person, ['parent']).ast.annotations[annotationId]).to.eq(
         annotationValue,

package/src/internal/object/set-value.test.ts

@@ -55,11 +55,11 @@ describe('Obj.setValue', () => {
   test('sets multiple nested array elements', ({ expect }) => {
     const Item = Schema.Struct({
       value: Schema.optional(Schema.Number),
-    }).pipe(Schema.mutable);
+    });
 
     const Container = Schema.Struct({
       name: Schema.String,
-      items: Schema.optional(Schema.mutable(Schema.Array(Item))),
+      items: Schema.optional(Schema.Array(Item)),
     }).pipe(
       Type.object({
         typename: 'test.com/Container',
@@ -150,7 +150,7 @@ describe('Obj.setValue', () => {
 
   test('handles two-dimensional arrays', ({ expect }) => {
     const Matrix = Schema.Struct({
-      values: Schema.optional(Schema.mutable(Schema.Array(Schema.mutable(Schema.Array(Schema.Number))))),
+      values: Schema.optional(Schema.Array(Schema.Array(Schema.Number))),
     }).pipe(
       Type.object({
         typename: 'test.com/Matrix',
@@ -200,11 +200,11 @@ describe('Obj.setValue', () => {
   test('handles numeric keys as strings', ({ expect }) => {
     const Item = Schema.Struct({
       value: Schema.optional(Schema.Number),
-    }).pipe(Schema.mutable);
+    });
 
     const Container = Schema.Struct({
       name: Schema.String,
-      items: Schema.optional(Schema.mutable(Schema.Array(Item))),
+      items: Schema.optional(Schema.Array(Item)),
     }).pipe(
       Type.object({
         typename: 'test.com/Container',
@@ -227,11 +227,11 @@ describe('Obj.setValue', () => {
       id: Schema.String, // Required field.
       title: Schema.optional(Schema.String),
       completed: Schema.optional(Schema.Boolean),
-    }).pipe(Schema.mutable);
+    });
 
     const TodoList = Schema.Struct({
       name: Schema.String,
-      tasks: Schema.optional(Schema.mutable(Schema.Array(Task))),
+      tasks: Schema.optional(Schema.Array(Task)),
     }).pipe(
       Type.object({
         typename: 'test.com/TodoList',
@@ -256,11 +256,11 @@ describe('Obj.setValue', () => {
       count: Schema.Number, // Required - should default to 0
       active: Schema.Boolean, // Required - should default to false
       label: Schema.optional(Schema.String), // Optional - should not be initialized
-    }).pipe(Schema.mutable);
+    });
 
     const Container = Schema.Struct({
       name: Schema.String,
-      items: Schema.optional(Schema.mutable(Schema.Array(Item))),
+      items: Schema.optional(Schema.Array(Item)),
     }).pipe(
       Type.object({
         typename: 'test.com/Container',

package/src/internal/object/snapshot.ts

@@ -4,18 +4,35 @@
 
 import { deepMapValues } from '@dxos/util';
 
+import { ObjectDatabaseId } from '../entities/model';
 import { RelationSourceDXNId, RelationSourceId, RelationTargetDXNId, RelationTargetId } from '../entities/relation';
 import { KindId, SnapshotKindId } from '../types/entity';
 import { MetaId } from '../types/meta';
 import { SchemaId, TypeId } from '../types/typename';
 
 /**
- * Copy a Symbol-keyed property from source to target if it exists.
+ * Copy a Symbol-keyed property from source to target if it has a defined value.
+ * Handles both plain objects (symbol in source) and proxies where get returns a value
+ * but has/in returns false (e.g. ObjectDatabaseId on echo-db proxies).
+ * Optional transform clones or mutates the value before assignment (e.g. for MetaId).
  */
-const copySymbolProperty = (source: any, target: any, symbol: symbol): void => {
-  if (symbol in source) {
+const copySymbolProperty = (
+  source: any,
+  target: any,
+  symbol: symbol,
+  transform?: (value: unknown) => unknown,
+): void => {
+  let value: unknown;
+  // Echo-db proxy getters (e.g. RelationSourceId, RelationTargetId) can throw in certain states.
+  try {
+    value = source[symbol];
+  } catch {
+    return;
+  }
+  if (value !== undefined) {
+    const finalValue = transform ? transform(value) : value;
     Object.defineProperty(target, symbol, {
-      value: source[symbol],
+      value: finalValue,
       writable: false,
       enumerable: false,
       configurable: false,
@@ -56,8 +73,14 @@ export const getSnapshot = <T extends object>(obj: T): T => {
     copySymbolProperty(source, snapshot, TypeId);
     copySymbolProperty(source, snapshot, SchemaId);
 
-    // Metadata symbol.
-    copySymbolProperty(source, snapshot, MetaId);
+    // Database reference (required for Obj.getDatabase to work on snapshots).
+    copySymbolProperty(source, snapshot, ObjectDatabaseId);
+
+    // Metadata symbol. Copy arrays so the snapshot is not affected by mutations to the live meta's keys/tags.
+    copySymbolProperty(source, snapshot, MetaId, (meta: any) => ({
+      keys: [...(meta?.keys ?? [])],
+      tags: [...(meta?.tags ?? [])],
+    }));
 
     // Relation endpoint symbols.
     copySymbolProperty(source, snapshot, RelationSourceDXNId);

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

@@ -7,7 +7,7 @@ import type * as Schema from 'effect/Schema';
 import { ObjectId } from '@dxos/keys';
 
 import { getTypeAnnotation } from '../annotations';
-import { type AnyProperties, KindId, MetaId, type ObjectMeta, ObjectMetaSchema } from '../types';
+import { type AnyProperties, KindId, MetaId, type ObjectMeta, ObjectMetaSchema, ParentId } from '../types';
 
 import { defineHiddenProperty } from './define-hidden-property';
 import { attachTypedJsonSerializer } from './json-serializer';
@@ -35,7 +35,8 @@ export const makeObject: {
     meta?: ObjectMeta,
   ): T;
 } = <T extends AnyProperties>(schema: Schema.Schema<T, any>, obj: MakeObjectProps<T>, meta?: ObjectMeta): T => {
-  return createReactiveObject<T>({ ...obj } as T, meta, schema);
+  // 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);
 };
 
 const createReactiveObject = <T extends AnyProperties>(obj: T, meta?: ObjectMeta, schema?: Schema.Schema<T>): T => {
@@ -47,12 +48,21 @@ const createReactiveObject = <T extends AnyProperties>(obj: T, meta?: ObjectMeta
     throw new Error('Schema is required for reactive objects. Use Atom for untyped reactive state.');
   }
 
+  // Extract parent from props (can be set via [Obj.Parent]).
+  const parent = (obj as any)[ParentId];
+  if (parent !== undefined) {
+    delete (obj as any)[ParentId];
+  }
+
   const annotation = getTypeAnnotation(schema);
   if (annotation) {
     setIdOnTarget(obj);
     defineHiddenProperty(obj, KindId, annotation.kind);
   }
   initMeta(obj, meta);
+  if (parent !== undefined) {
+    defineHiddenProperty(obj, ParentId, parent);
+  }
   prepareTypedTarget(obj, schema);
   attachTypedJsonSerializer(obj);
   const proxy = createProxy<T>(obj, TypedReactiveHandler.instance);

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

@@ -94,7 +94,7 @@ describe('complex schema validations', () => {
   });
 
   test('subscribe', () => {
-    const TestSchema = Schema.mutable(Schema.Struct({ field: Schema.String })).pipe(
+    const TestSchema = Schema.Struct({ field: Schema.String }).pipe(
       EchoObjectSchema({ typename: 'Test', version: '0.1.0' }),
     );
     const object = makeObject(TestSchema, { field: 'value' });
@@ -117,12 +117,10 @@ describe('complex schema validations', () => {
 });
 
 describe('object structure restrictions', () => {
-  const NestedSchema = Schema.mutable(
-    Schema.Struct({
-      data: Schema.optional(Schema.Any),
-      nested: Schema.optional(Schema.Any),
-    }),
-  );
+  const NestedSchema = Schema.Struct({
+    data: Schema.optional(Schema.Any),
+    nested: Schema.optional(Schema.Any),
+  });
 
   test('prevents direct cycles', () => {
     const obj = makeObject(NestedSchema, { data: null });
@@ -226,11 +224,9 @@ describe('object structure restrictions', () => {
   });
 
   test('array elements are owned by root ECHO object', () => {
-    const ArraySchema = Schema.mutable(
-      Schema.Struct({
-        items: Schema.mutable(Schema.Array(Schema.Any)),
-      }),
-    );
+    const ArraySchema = Schema.Struct({
+      items: Schema.Array(Schema.Any),
+    });
 
     const obj1 = makeObject(ArraySchema, {
       items: [{ id: 1 }, { id: 2 }, { id: 3 }],

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

@@ -13,7 +13,7 @@ import { invariant } from '@dxos/invariant';
 
 import { getSchemaDXN } from '../annotations';
 import { ObjectDeletedId } from '../entities';
-import { SchemaId, TypeId } from '../types';
+import { ParentId, SchemaId, TypeId } from '../types';
 
 import { executeChange, isInChangeContext, queueNotification } from './change-context';
 import { defineHiddenProperty } from './define-hidden-property';
@@ -47,6 +47,7 @@ type ProxyTarget = {
    * Schema for the root.
    */
   [SchemaId]: Schema.Schema.AnyNoContext;
+  [ParentId]?: any;
 
   /**
    * For modifications.
@@ -320,6 +321,10 @@ export class TypedReactiveHandler implements ReactiveHandler<ProxyTarget> {
   ): { echoRoot: object; preparedValue: any } {
     const echoRoot = getEchoRoot(target);
 
+    if (prop === ParentId) {
+      return { echoRoot, preparedValue: value }; // Short-circuit for parent assignment.
+    }
+
     // Check for cycles before assignment.
     if (isValidProxyTarget(value) || isProxy(value)) {
       if (wouldCreateCycle(echoRoot, value)) {
@@ -363,6 +368,9 @@ export class TypedReactiveHandler implements ReactiveHandler<ProxyTarget> {
   }
 
   private _validateValue(target: any, prop: string | symbol, value: any) {
+    if (prop === ParentId) {
+      return value;
+    }
     const schema = SchemaValidator.getTargetPropertySchema(target, prop);
     const _ = Schema.asserts(schema)(value);
     if (isValidProxyTarget(value)) {

package/src/internal/proxy/typed-object.test.ts

@@ -3,6 +3,7 @@
 //
 
 import * as Schema from 'effect/Schema';
+import type * as Types from 'effect/Types';
 import { describe, expect, test } from 'vitest';
 
 import { EchoObjectSchema } from '../entities';
@@ -61,15 +62,13 @@ describe('EchoObjectSchema class DSL', () => {
   });
 
   test('record', () => {
-    const schema = Schema.mutable(
-      Schema.Struct({
-        meta: Schema.optional(Schema.mutable(Schema.Any)),
-        // NOTE: Schema.Record only supports shallow values.
-        // https://www.npmjs.com/package/@effect/schema#mutable-records
-        // meta: Schema.optional(Schema.mutable(Schema.Record({ key: Schema.String, value: Schema.Any }))),
-        // meta: Schema.optional(Schema.mutable(Schema.object)),
-      }),
-    );
+    const schema = Schema.Struct({
+      meta: Schema.optional(Schema.Any),
+      // NOTE: Schema.Record only supports shallow values.
+      // https://www.npmjs.com/package/@effect/schema#mutable-records
+      // meta: Schema.optional(Schema.Record({ key: Schema.String, value: Schema.Any })),
+      // meta: Schema.optional(Schema.object),
+    });
 
     {
       const object = makeObject(schema, {});
@@ -89,7 +88,8 @@ describe('EchoObjectSchema class DSL', () => {
 
     {
       // Plain object (not a reactive proxy) - doesn't need Obj.change.
-      type Test1 = Schema.Schema.Type<typeof schema>;
+      // Note: Schema.Schema.Type generates readonly types, so we cast to mutable for plain objects.
+      type Test1 = Types.Mutable<Schema.Schema.Type<typeof schema>>;
 
       const object: Test1 = {};
       (object.meta ??= {}).test = 100;
@@ -98,7 +98,7 @@ describe('EchoObjectSchema class DSL', () => {
 
     {
       const Test2 = Schema.Struct({
-        meta: Schema.optional(Schema.mutable(Schema.Record({ key: Schema.String, value: Schema.Any }))),
+        meta: Schema.optional(Schema.Record({ key: Schema.String, value: Schema.Any })),
       }).pipe(
         EchoObjectSchema({
           typename: 'dxos.org/type/FunctionTrigger',