@dxos/echo 0.8.4-main.fffef41 → 0.8.4-staging.60fe92afc8

package/src/internal/{json → JsonSchema}/json-schema.ts

@@ -11,25 +11,31 @@ import * as SchemaAST from 'effect/SchemaAST';
 import type * as Types from 'effect/Types';
 
 import { raise } from '@dxos/debug';
-import { mapAst } from '@dxos/effect';
+import { SchemaEx } from '@dxos/effect';
 import { assertArgument, invariant } from '@dxos/invariant';
-import { DXN, ObjectId } from '@dxos/keys';
+import { DXN, EID, EntityId } from '@dxos/keys';
 import { log } from '@dxos/log';
 import { clearUndefined, orderKeys, removeProperties } from '@dxos/util';
 
-import { type TypeAnnotation, TypeAnnotationId, TypeIdentifierAnnotationId } from '../ast';
-import { EntityKind, EntityKindSchema } from '../ast';
+import type * as Type from '../../Type';
+import { type TypeAnnotation, TypeAnnotationId, TypeIdentifierAnnotationId } from '../Annotation/annotations';
+import { makeTypeJsonSchemaAnnotation } from '../Annotation/util';
+import {
+  ANY_OBJECT_TYPENAME,
+  ANY_OBJECT_VERSION,
+  EntityKind,
+  EntityKindSchema,
+  getStaticTypeSchema,
+} from '../common/types';
+import { type JsonSchemaReferenceInfo, createEchoReferenceSchema } from '../Ref';
+import { CustomAnnotations, DecodedAnnotations, EchoAnnotations } from './annotations';
 import {
   ECHO_ANNOTATIONS_NS_DEPRECATED_KEY,
   ECHO_ANNOTATIONS_NS_KEY,
   type JsonSchemaEchoAnnotations,
   type JsonSchemaType,
   getNormalizedEchoAnnotations,
-} from '../json-schema';
-import { Expando, makeTypeJsonSchemaAnnotation } from '../object';
-import { type JsonSchemaReferenceInfo, Ref, createEchoReferenceSchema } from '../ref';
-
-import { CustomAnnotations, DecodedAnnotations, EchoAnnotations } from './annotations';
+} from './json-schema-type';
 
 // TODO(burdon): Are these values stored (can they be changed?)
 export enum PropType {
@@ -71,11 +77,29 @@ export type JsonSchemaOptions = {
 
 /**
  * Convert effect schema to JSON Schema.
+ * NOTE: This handles custom annotations.
  * @param schema
  */
-export const toJsonSchema = (schema: Schema.Schema.All, options: JsonSchemaOptions = {}): JsonSchemaType => {
+// TODO(burdon): Reconcile with possibly extending @effect/Schema/JSONSchema
+//  We add additional propertyOrder (but the object properties ARE ordered); and type "string" for literals.
+// 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 | Type.AnyEntity,
+  options: JsonSchemaOptions = {},
+): Types.DeepMutable<JsonSchemaType> => {
+  // Allow passing a `Type.Type` entity — use its hidden source schema (or its
+  // already-built jsonSchema as a fallback).
+  const slot = getStaticTypeSchema(schema);
+  if (slot != null) {
+    schema = slot;
+  } else if (!Schema.isSchema(schema)) {
+    const entityJsonSchema = (schema as { jsonSchema?: JsonSchemaType }).jsonSchema;
+    if (entityJsonSchema != null) {
+      return entityJsonSchema as Types.DeepMutable<JsonSchemaType>;
+    }
+  }
   assertArgument(Schema.isSchema(schema), 'schema');
-  let jsonSchema = _toJsonSchemaAST(schema.ast);
+  let jsonSchema = _toJsonSchemaAST((schema as Schema.Schema.All).ast);
   if (options.strict) {
     // TOOD(burdon): Workaround to ensure JSON schema is valid (for agv parsing).
     jsonSchema = removeProperties(jsonSchema, (key, value) => {
@@ -96,11 +120,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);
 };
@@ -133,7 +157,7 @@ const withEchoRefinements = (
     }
   } else if (SchemaAST.isTypeLiteral(ast)) {
     // Add property order annotations
-    recursiveResult = mapAst(ast, (ast, key) =>
+    recursiveResult = SchemaEx.mapAst(ast, (ast, key) =>
       withEchoRefinements(ast, path && typeof key === 'string' ? `${path}/${key}` : undefined, suspendCache),
     );
     recursiveResult = addJsonSchemaFields(recursiveResult, {
@@ -143,7 +167,7 @@ const withEchoRefinements = (
     // Ignore undefined keyword that appears in the optional fields.
     return ast;
   } else {
-    recursiveResult = mapAst(ast, (ast, key) =>
+    recursiveResult = SchemaEx.mapAst(ast, (ast, key) =>
       withEchoRefinements(
         ast,
         path && (typeof key === 'string' || typeof key === 'number') ? `${path}/${key}` : undefined,
@@ -180,7 +204,7 @@ export const toEffectSchema = (root: JsonSchemaType, _defs?: JsonSchemaType['$de
       }
     }
   } else if ('$id' in root) {
-    switch (root.$id as string) {
+    switch (decodeURIComponent(root.$id as string)) {
       case '/schemas/any': {
         result = anyToEffectSchema(root as JSONSchema.JsonSchema7Any);
         break;
@@ -191,7 +215,7 @@ export const toEffectSchema = (root: JsonSchemaType, _defs?: JsonSchemaType['$de
       }
       case '/schemas/{}':
       case '/schemas/object': {
-        result = Schema.Object;
+        result = Schema.Struct({});
         break;
       }
       // Custom ECHO object reference.
@@ -319,7 +343,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);
@@ -330,9 +354,9 @@ const anyToEffectSchema = (root: JSONSchema.JsonSchema7Any): Schema.Schema.AnyNo
   const echoRefinement: JsonSchemaEchoAnnotations = (root as any)[ECHO_ANNOTATIONS_NS_DEPRECATED_KEY];
   // TODO(dmaretskyi): Is this branch still taken?
   if ((echoRefinement as any)?.reference != null) {
-    const echoId = root.$id.startsWith('dxn:echo:') ? root.$id : undefined;
+    const echoUri = root.$id.startsWith('echo:') ? root.$id : undefined;
     return createEchoReferenceSchema(
-      echoId,
+      echoUri,
       (echoRefinement as any).reference.typename,
       (echoRefinement as any).reference.version,
     );
@@ -344,21 +368,20 @@ const anyToEffectSchema = (root: JSONSchema.JsonSchema7Any): Schema.Schema.AnyNo
 // TODO(dmaretskyi): Types.
 const refToEffectSchema = (root: any): Schema.Schema.AnyNoContext => {
   if (!('reference' in root)) {
-    return Ref(Expando);
+    // Fallback to generic object ref when no reference info is provided.
+    return createEchoReferenceSchema(undefined, ANY_OBJECT_TYPENAME, ANY_OBJECT_VERSION);
   }
+
   const reference: JsonSchemaReferenceInfo = root.reference;
   if (typeof reference !== 'object') {
     throw new Error('Invalid reference field in ref schema');
   }
 
-  const targetSchemaDXN = DXN.parse(reference.schema.$ref);
-  invariant(targetSchemaDXN.kind === DXN.kind.TYPE);
+  const ref = reference.schema.$ref;
+  const targetSchemaDXN = DXN.tryMake(ref);
+  invariant(targetSchemaDXN, `Expected a type DXN, got: ${ref}`);
 
-  return createEchoReferenceSchema(
-    targetSchemaDXN.toString(),
-    targetSchemaDXN.kind === DXN.kind.TYPE ? targetSchemaDXN.parts[0] : undefined,
-    reference.schemaVersion,
-  );
+  return createEchoReferenceSchema(ref, DXN.getName(targetSchemaDXN), reference.schemaVersion);
 };
 
 //
@@ -368,7 +391,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;
@@ -379,10 +402,11 @@ const annotations_toJsonSchemaFields = (annotations: SchemaAST.Annotations): Rec
     schemaFields[ECHO_ANNOTATIONS_NS_KEY] = echoAnnotations;
   }
 
+  // For stored schemas the storage URI is the definitive identifier — it overrides
+  // the typename `$id` written above.
   const echoIdentifier = annotations[TypeIdentifierAnnotationId];
   if (echoIdentifier) {
-    schemaFields[ECHO_ANNOTATIONS_NS_KEY] ??= {};
-    schemaFields[ECHO_ANNOTATIONS_NS_KEY].schemaId = echoIdentifier;
+    schemaFields.$id = echoIdentifier;
   }
 
   // Custom (at end).
@@ -397,14 +421,14 @@ const annotations_toJsonSchemaFields = (annotations: SchemaAST.Annotations): Rec
 };
 
 const decodeTypeIdentifierAnnotation = (schema: JsonSchemaType): string | undefined => {
-  // Limit to dxn:echo: URIs.
-  if (schema.$id && schema.$id.startsWith('dxn:echo:')) {
+  // For stored schemas `$id` IS the storage URI (echo:/<id>).
+  if (schema.$id && schema.$id.startsWith('echo:')) {
     return schema.$id;
-  } else if (schema.$id && schema.$id.startsWith('dxn:type:') && schema?.echo?.type?.schemaId) {
-    const id = schema?.echo?.type?.schemaId;
-    if (ObjectId.isValid(id)) {
-      return DXN.fromLocalObjectId(id).toString();
-    }
+  }
+  // Older serializations stored the EID on echo.type.schemaId.
+  const legacySchemaId = schema.echo?.type?.schemaId;
+  if (legacySchemaId) {
+    return EntityId.isValid(legacySchemaId) ? EID.make({ entityId: legacySchemaId }) : legacySchemaId;
   }
   return undefined;
 };
@@ -421,8 +445,8 @@ const decodeTypeAnnotation = (schema: JsonSchemaType): TypeAnnotation | undefine
     if (annotation.kind === EntityKind.Relation) {
       const source = schema.relationSource?.$ref ?? raise(new Error('Relation source not set'));
       const target = schema.relationTarget?.$ref ?? raise(new Error('Relation target not set'));
-      annotation.sourceSchema = DXN.parse(source).toString();
-      annotation.targetSchema = DXN.parse(target).toString();
+      annotation.sourceSchema = DXN.tryMake(source) ?? raise(new Error(`Invalid relation source: ${source}`));
+      annotation.targetSchema = DXN.tryMake(target) ?? raise(new Error(`Invalid relation target: ${target}`));
     }
 
     return annotation;
@@ -452,11 +476,15 @@ const jsonSchemaFieldsToAnnotations = (schema: JsonSchemaType): SchemaAST.Annota
     }
   }
 
-  annotations[TypeIdentifierAnnotationId] = decodeTypeIdentifierAnnotation(schema);
+  const typeIdentifier = decodeTypeIdentifierAnnotation(schema);
+  annotations[TypeIdentifierAnnotationId] = typeIdentifier;
   const typeAnnotation = decodeTypeAnnotation(schema);
   if (typeAnnotation) {
     annotations[TypeAnnotationId] = typeAnnotation;
     annotations[SchemaAST.JSONSchemaAnnotationId] = makeTypeJsonSchemaAnnotation({
+      // $id is the typename DXN — the schema's type identity. The storage EID (if any)
+      // is preserved separately on TypeIdentifierAnnotation / echo.schemaId.
+      identifier: DXN.make(typeAnnotation.typename, typeAnnotation.version),
       kind: typeAnnotation.kind,
       typename: typeAnnotation.typename,
       version: typeAnnotation.version,
@@ -486,7 +514,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/Obj/atoms.ts

@@ -0,0 +1,244 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Atom from '@effect-atom/atom/Atom';
+import * as Result from '@effect-atom/atom/Result';
+import * as Effect from 'effect/Effect';
+import * as Function from 'effect/Function';
+import * as Option from 'effect/Option';
+
+import { assertArgument } from '@dxos/invariant';
+
+import type * as Entity from '../../Entity';
+import type * as Obj from '../../Obj';
+import type * as Ref from '../../Ref';
+import type * as Relation from '../../Relation';
+import { subscribe } from '../common/proxy/reactive';
+import { isEntity, getDatabase } from '../Entity';
+import { RefTypeId } from '../Ref/ref';
+import { loadRefTarget } from '../Ref/utils';
+import { getSnapshot } from './snapshot';
+
+const isRef = (obj: unknown): obj is Ref.Ref<any> =>
+  obj != null && typeof obj === 'object' && RefTypeId in (obj as object);
+
+const getReactiveOption = <T extends Obj.Unknown>(snapshot: Obj.Snapshot<T>): Effect.Effect<Option.Option<T>, never> =>
+  Effect.gen(function* () {
+    const db = getDatabase(snapshot as any);
+    if (!db) {
+      return Option.none();
+    }
+    const obj = db.getObjectById((snapshot as any).id);
+    return obj ? Option.some(obj as T) : Option.none();
+  });
+
+/**
+ * Atom family for ECHO objects.
+ * Uses object reference as key — same object returns same atom.
+ */
+const objectFamily = Atom.family(<T extends Obj.Unknown>(obj: T): Atom.Atom<Obj.Snapshot<T>> => {
+  return Atom.make<Obj.Snapshot<T>>((get) => {
+    const unsubscribe = subscribe(obj, () => {
+      // getSnapshot adds SnapshotKindId brand at runtime; cast bridges static types.
+      get.setSelf(getSnapshot(obj) as unknown as Obj.Snapshot<T>);
+    });
+
+    get.addFinalizer(() => unsubscribe());
+
+    return getSnapshot(obj) as unknown as Obj.Snapshot<T>;
+  }).pipe(Atom.keepAlive);
+});
+
+/**
+ * Atom family for ECHO refs (snapshot version).
+ * Uses ref as key — same ref returns same atom.
+ * Subscribes to target object changes after loading.
+ */
+const refFamily = Atom.family(<T extends Obj.Unknown>(ref: Ref.Ref<T>): Atom.Atom<Obj.Snapshot<T> | undefined> => {
+  return Atom.make<Obj.Snapshot<T> | undefined>((get) => {
+    let unsubscribeTarget: (() => void) | undefined;
+
+    const setupTargetSubscription = (target: T): Obj.Snapshot<T> => {
+      unsubscribeTarget?.();
+      unsubscribeTarget = subscribe(target, () => {
+        // getSnapshot adds SnapshotKindId brand at runtime; cast bridges static types.
+        get.setSelf(getSnapshot(target) as unknown as Obj.Snapshot<T>);
+      });
+      return getSnapshot(target) as unknown as Obj.Snapshot<T>;
+    };
+
+    get.addFinalizer(() => {
+      unsubscribeTarget?.();
+    });
+
+    return loadRefTarget(ref, get, setupTargetSubscription);
+  }).pipe(Atom.keepAlive);
+});
+
+/**
+ * Snapshot a value to create a new reference for comparison and React dependency tracking.
+ */
+const snapshotForComparison = <V>(value: V): V => {
+  if (Array.isArray(value)) {
+    return [...value] as V;
+  }
+  if (value !== null && typeof value === 'object') {
+    return { ...value } as V;
+  }
+  return value;
+};
+
+/**
+ * Atom family for ECHO object properties.
+ * Uses nested families: outer keyed by object, inner keyed by property key.
+ */
+const propertyFamily = Atom.family(<T extends Obj.Unknown>(obj: T) =>
+  Atom.family(<K extends keyof T>(key: K): Atom.Atom<T[K]> => {
+    return Atom.make<T[K]>((get) => {
+      let previousSnapshot = snapshotForComparison(obj[key]);
+
+      const unsubscribe2 = subscribe(obj, () => {
+        const newValue = obj[key];
+        const newSnapshot = snapshotForComparison(newValue);
+        if (newSnapshot !== previousSnapshot) {
+          previousSnapshot = newSnapshot;
+          get.setSelf(newSnapshot);
+        }
+      });
+
+      get.addFinalizer(() => unsubscribe2());
+
+      return snapshotForComparison(obj[key]);
+    }).pipe(Atom.keepAlive);
+  }),
+);
+
+/**
+ * Atom family for ECHO objects — returns the live object, not a snapshot.
+ */
+const objectWithReactiveFamily = Atom.family(<T extends Obj.Unknown>(obj: T): Atom.Atom<T> => {
+  return Atom.make<T>((get) => {
+    const unsubscribe = subscribe(obj, () => {
+      get.setSelf(obj);
+    });
+
+    get.addFinalizer(() => unsubscribe());
+
+    return obj;
+  }).pipe(Atom.keepAlive);
+});
+
+/**
+ * Atom family for ECHO refs — returns the live reactive object, not a snapshot.
+ */
+const refWithReactiveFamily = Atom.family(<T extends Obj.Unknown>(ref: Ref.Ref<T>): Atom.Atom<T | undefined> => {
+  const effect = (get: Atom.Context) =>
+    Effect.gen(function* () {
+      const snapshot = get(makeAtom(ref));
+      if (snapshot == null) {
+        return undefined;
+      }
+      const option = yield* getReactiveOption(snapshot);
+      return Option.getOrElse(option, () => undefined);
+    });
+
+  return Function.pipe(
+    Atom.make(effect),
+    Atom.map((result) => Result.getOrElse(result, () => undefined)),
+  );
+});
+
+/**
+ * Atom family for any ECHO entity (obj or relation) — returns a snapshot.
+ */
+const entityFamily = Atom.family(<T extends Entity.Unknown>(entity: T): Atom.Atom<Entity.Snapshot> => {
+  return Atom.make<Entity.Snapshot>((get) => {
+    const unsubscribe = subscribe(entity, () => {
+      // getSnapshot adds SnapshotKindId brand at runtime; cast bridges static types.
+      get.setSelf(getSnapshot(entity) as unknown as Entity.Snapshot);
+    });
+
+    get.addFinalizer(() => unsubscribe());
+
+    return getSnapshot(entity) as unknown as Entity.Snapshot;
+  }).pipe(Atom.keepAlive);
+});
+
+/**
+ * Atom family for ECHO relations — returns a typed relation snapshot.
+ */
+const relationFamily = Atom.family(<T extends Relation.Unknown>(relation: T): Atom.Atom<Relation.Snapshot<T>> => {
+  return Atom.make<Relation.Snapshot<T>>((get) => {
+    const unsubscribe = subscribe(relation, () => {
+      // getSnapshot adds SnapshotKindId brand at runtime; cast bridges static types.
+      get.setSelf(getSnapshot(relation) as unknown as Relation.Snapshot<T>);
+    });
+
+    get.addFinalizer(() => unsubscribe());
+
+    return getSnapshot(relation) as unknown as Relation.Snapshot<T>;
+  }).pipe(Atom.keepAlive);
+});
+
+/**
+ * Create a read-only snapshot atom for a reactive object or ref.
+ * Updates automatically when the object is mutated.
+ * For refs, subscribes to target object changes after loading.
+ */
+export const makeAtom: {
+  <T extends Obj.Unknown>(obj: T): Atom.Atom<Obj.Snapshot<T>>;
+  <T extends Obj.Unknown>(ref: Ref.Ref<T>): Atom.Atom<Obj.Snapshot<T> | undefined>;
+} = (objOrRef: Obj.Unknown | Ref.Ref<any>): Atom.Atom<any> => {
+  if (isRef(objOrRef)) {
+    return refFamily(objOrRef as any);
+  }
+
+  const obj = objOrRef as Obj.Unknown;
+  assertArgument(isEntity(obj), 'obj', 'Object must be a reactive object');
+  return objectFamily(obj as any);
+};
+
+/**
+ * Create a read-only atom for a specific property of a reactive object.
+ * Only fires updates when the property value actually changes.
+ */
+export const makeProperty = <T extends Obj.Unknown, K extends keyof T>(obj: T, key: K): Atom.Atom<T[K]> => {
+  assertArgument(isEntity(obj), 'obj', 'Object must be a reactive object');
+  return propertyFamily(obj)(key);
+};
+
+/**
+ * Like `makeAtom` but returns the live reactive object instead of a snapshot.
+ * Prefer `makeAtom` (snapshot) unless you need the live Obj for generic mutations.
+ */
+export const makeWithReactive: {
+  <T extends Obj.Unknown>(obj: T): Atom.Atom<T>;
+  <T extends Obj.Unknown>(ref: Ref.Ref<T>): Atom.Atom<T | undefined>;
+} = (objOrRef: Obj.Unknown | Ref.Ref<any>): Atom.Atom<any> => {
+  if (isRef(objOrRef)) {
+    return refWithReactiveFamily(objOrRef as Ref.Ref<any>);
+  }
+
+  const obj = objOrRef as Obj.Unknown;
+  assertArgument(isEntity(obj), 'obj', 'Object must be a reactive object');
+  return objectWithReactiveFamily(obj);
+};
+
+/**
+ * Create a read-only snapshot atom for any ECHO entity (obj or relation).
+ * Updates automatically when the entity is mutated.
+ */
+export const makeEntity = <T extends Entity.Unknown>(entity: T): Atom.Atom<Entity.Snapshot> => {
+  assertArgument(isEntity(entity), 'entity', 'Must be a reactive ECHO entity');
+  return entityFamily(entity);
+};
+
+/**
+ * Create a read-only snapshot atom for a reactive relation.
+ * Updates automatically when the relation is mutated.
+ */
+export const makeRelation = <T extends Relation.Unknown>(relation: T): Atom.Atom<Relation.Snapshot<T>> => {
+  assertArgument(isEntity(relation), 'relation', 'Must be a reactive ECHO relation');
+  return relationFamily(relation);
+};

package/src/internal/Obj/clone.ts

@@ -0,0 +1,53 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { invariant } from '@dxos/invariant';
+import { deepMapValues } from '@dxos/util';
+
+import type * as Obj from '../../Obj';
+import { makeObject } from '../common/proxy';
+import { getSchema, getStaticTypeSchema, getType } from '../common/types';
+import { getMeta } from '../common/types/meta';
+import { Ref } from '../Ref';
+
+/**
+ * Clones an object or relation.
+ * This does not clone referenced objects, only the properties in the object.
+ * @returns A new object with the same schema and properties.
+ */
+export const clone = <T extends Obj.Any>(obj: T, opts?: Obj.CloneOptions): T => {
+  const { id, ...data } = obj;
+  // Prefer cloning through the type entity so the cloned instance preserves
+  // `Obj.getType` identity. Falls back to the raw schema for older instances
+  // that don't have a type-entity back-reference set (e.g. deserialized).
+  const typeEntity = getType(obj);
+  const schema = typeEntity != null ? getStaticTypeSchema(typeEntity) : getSchema(obj);
+  invariant(schema != null, 'Object should have a type or schema');
+  const props: any = deepMapValues(data, (value, recurse) => {
+    if (Ref.isRef(value)) {
+      if (opts?.deep) {
+        // TODO(dmaretskyi): Will break on circular references.
+        return Ref.make(clone(value.target!, opts));
+      }
+      return value;
+    }
+    return recurse(value);
+  });
+
+  if (opts?.retainId) {
+    props.id = id;
+  }
+  const meta = deepMapValues(getMeta(obj), (value, recurse) => {
+    if (Ref.isRef(value)) {
+      if (opts?.deep) {
+        // TODO(dmaretskyi): Will break on circular references.
+        return Ref.make(clone(value.target!, opts));
+      }
+      return value;
+    }
+    return recurse(value);
+  });
+
+  return makeObject(schema, props, meta, typeEntity as object | undefined);
+};

package/src/internal/{object → Obj}/common.ts

@@ -4,9 +4,8 @@
 
 import * as Schema from 'effect/Schema';
 
-import { type BaseObject } from '../types';
-
-import { getTypename } from './typename';
+import { getTypename } from '../Annotation';
+import { type AnyProperties } from '../common/types';
 
 // TODO(dmaretskyi): Rename to represent commonality between objects and relations (e.g. `entity`).
 export type TypedObjectOptions = {
@@ -58,7 +57,7 @@ export const makeTypedEntityClass = (
     static readonly pipe = baseSchema.pipe.bind(baseSchema);
 
     // TODO(burdon): Comment required.
-    static [Symbol.hasInstance](obj: BaseObject) {
+    static [Symbol.hasInstance](obj: AnyProperties) {
       return obj != null && getTypename(obj) === typename;
     }
 

package/src/internal/Obj/create-object.test.ts

@@ -0,0 +1,116 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+import { inspect } from 'util';
+import { describe, expect, test } from 'vitest';
+
+import { DXN, EID } from '@dxos/keys';
+
+import { Relation } from '../../index';
+import { TestSchema } from '../../testing';
+import * as Type from '../../Type';
+import { getTypeURI } from '../Annotation';
+import { ATTR_TYPE, getSchema } from '../common/types';
+import { ATTR_META } from '../common/types/meta';
+import { ATTR_RELATION_SOURCE, ATTR_RELATION_TARGET, isInstanceOf } from '../Entity';
+import { createObject } from './create-object';
+import { objectToJSON } from './json-serializer';
+
+describe('create (static version)', () => {
+  test('defaults', ({ expect }) => {
+    const Contact = Schema.Struct({
+      name: Schema.String.pipe(
+        Schema.optional,
+        Schema.withConstructorDefault(() => 'Anonymous'),
+      ),
+      email: Schema.String.pipe(Schema.optional),
+    });
+
+    const obj = Contact.make({});
+    expect(obj.name).toBe('Anonymous');
+  });
+
+  test('create static object', () => {
+    const contact = createObject(TestSchema.Person, {
+      name: 'Bot',
+      email: 'bot@example.com',
+    });
+
+    expect(contact.id).toBeDefined();
+    expect(contact.name).toBe('Bot');
+    expect(contact.email).toBe('bot@example.com');
+    expect((contact as any)['@type']).toBeUndefined();
+    expect(getTypeURI(contact)?.toString()).toBe(Type.getURI(TestSchema.Person).toString());
+    expect(isInstanceOf(TestSchema.Person, contact)).toBe(true);
+  });
+
+  test('JSON encoding', () => {
+    const contact = createObject(TestSchema.Person, {
+      name: 'Bot',
+      email: 'bot@example.com',
+    });
+
+    const json = JSON.parse(JSON.stringify(contact));
+    expect(json).toEqual({
+      id: contact.id,
+      '@type': DXN.make(Type.getTypename(TestSchema.Person), Type.getVersion(TestSchema.Person)),
+      '@meta': {
+        keys: [],
+      },
+      name: 'Bot',
+      email: 'bot@example.com',
+    });
+    expect(objectToJSON(contact)).toStrictEqual(json);
+  });
+
+  test('JSON encoding with relation', () => {
+    const person1 = createObject(TestSchema.Person, {
+      name: 'Alice',
+      email: 'alice@example.com',
+    });
+    const person2 = createObject(TestSchema.Person, {
+      name: 'Bob',
+      email: 'bob@example.com',
+    });
+
+    const manager = createObject(TestSchema.HasManager, {
+      [Relation.Source]: person1 as any,
+      [Relation.Target]: person2 as any,
+    });
+
+    const json = JSON.parse(JSON.stringify(manager));
+    expect(json).toEqual({
+      id: manager.id,
+      [ATTR_TYPE]: DXN.make(Type.getTypename(TestSchema.HasManager), Type.getVersion(TestSchema.HasManager)),
+      [ATTR_RELATION_SOURCE]: EID.make({ entityId: person1.id }),
+      [ATTR_RELATION_TARGET]: EID.make({ entityId: person2.id }),
+      [ATTR_META]: {
+        keys: [],
+      },
+    });
+  });
+
+  test('getSchema', () => {
+    const contact = createObject(TestSchema.Person, {
+      name: 'Bot',
+      email: 'bot@example.com',
+    });
+
+    expect(getSchema(contact)).toBe(Type.getSchema(TestSchema.Person));
+  });
+
+  test('inspect', () => {
+    const contact = createObject(TestSchema.Person, {
+      name: 'Bot',
+      email: 'bot@example.com',
+    });
+
+    const text = inspect(contact);
+    expect(text).toContain('Bot');
+    expect(text).toContain('bot@example.com');
+    expect(text).toContain('com.example.type.person');
+    expect(text).toContain('0.1.0');
+  });
+});