@dxos/echo 0.8.4-staging.ac66bdf99f → 0.9.0

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

@@ -11,19 +11,22 @@ 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 * as Type from '../../Type';
+import { type TypeAnnotation, TypeAnnotationId, TypeIdentifierAnnotationId } from '../Annotation/annotations';
+import { makeTypeJsonSchemaAnnotation } from '../Annotation/util';
 import {
-  type TypeAnnotation,
-  TypeAnnotationId,
-  TypeIdentifierAnnotationId,
-  makeTypeJsonSchemaAnnotation,
-} from '../Annotation';
-import { ANY_OBJECT_TYPENAME, ANY_OBJECT_VERSION, EntityKind, EntityKindSchema } from '../common/types';
+  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 {
@@ -81,11 +84,22 @@ export type JsonSchemaOptions = {
 //  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,
+  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) => {
@@ -143,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, {
@@ -153,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,
@@ -190,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;
@@ -201,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.
@@ -340,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,
     );
@@ -363,14 +377,11 @@ const refToEffectSchema = (root: any): Schema.Schema.AnyNoContext => {
     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);
 };
 
 //
@@ -391,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).
@@ -409,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;
 };
@@ -433,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;
@@ -470,7 +482,9 @@ const jsonSchemaFieldsToAnnotations = (schema: JsonSchemaType): SchemaAST.Annota
   if (typeAnnotation) {
     annotations[TypeAnnotationId] = typeAnnotation;
     annotations[SchemaAST.JSONSchemaAnnotationId] = makeTypeJsonSchemaAnnotation({
-      identifier: typeIdentifier,
+      // $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,

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

@@ -7,7 +7,8 @@ import { deepMapValues } from '@dxos/util';
 
 import type * as Obj from '../../Obj';
 import { makeObject } from '../common/proxy';
-import { getMeta, getSchema } from '../common/types';
+import { getSchema, getStaticTypeSchema, getType } from '../common/types';
+import { getMeta } from '../common/types/meta';
 import { Ref } from '../Ref';
 
 /**
@@ -17,8 +18,12 @@ import { Ref } from '../Ref';
  */
 export const clone = <T extends Obj.Any>(obj: T, opts?: Obj.CloneOptions): T => {
   const { id, ...data } = obj;
-  const schema = getSchema(obj);
-  invariant(schema != null, 'Object should have a schema');
+  // 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) {
@@ -44,5 +49,5 @@ export const clone = <T extends Obj.Any>(obj: T, opts?: Obj.CloneOptions): T =>
     return recurse(value);
   });
 
-  return makeObject(schema, props, meta);
+  return makeObject(schema, props, meta, typeEntity as object | undefined);
 };

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

@@ -6,13 +6,15 @@ import * as Schema from 'effect/Schema';
 import { inspect } from 'util';
 import { describe, expect, test } from 'vitest';
 
-import { DXN } from '@dxos/keys';
+import { DXN, EID } from '@dxos/keys';
 
 import { Relation } from '../../index';
 import { TestSchema } from '../../testing';
-import { getSchemaDXN, getTypeDXN, isInstanceOf } from '../Annotation';
-import { ATTR_META, ATTR_TYPE, getSchema } from '../common/types';
-import { ATTR_RELATION_SOURCE, ATTR_RELATION_TARGET } from '../Entity';
+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';
 
@@ -40,7 +42,7 @@ describe('create (static version)', () => {
     expect(contact.name).toBe('Bot');
     expect(contact.email).toBe('bot@example.com');
     expect((contact as any)['@type']).toBeUndefined();
-    expect(getTypeDXN(contact)?.toString()).toBe(getSchemaDXN(TestSchema.Person)!.toString());
+    expect(getTypeURI(contact)?.toString()).toBe(Type.getURI(TestSchema.Person).toString());
     expect(isInstanceOf(TestSchema.Person, contact)).toBe(true);
   });
 
@@ -53,7 +55,7 @@ describe('create (static version)', () => {
     const json = JSON.parse(JSON.stringify(contact));
     expect(json).toEqual({
       id: contact.id,
-      '@type': DXN.fromTypenameAndVersion(TestSchema.Person.typename, TestSchema.Person.version).toString(),
+      '@type': DXN.make(Type.getTypename(TestSchema.Person), Type.getVersion(TestSchema.Person)),
       '@meta': {
         keys: [],
       },
@@ -81,9 +83,9 @@ describe('create (static version)', () => {
     const json = JSON.parse(JSON.stringify(manager));
     expect(json).toEqual({
       id: manager.id,
-      [ATTR_TYPE]: DXN.fromTypenameAndVersion(TestSchema.HasManager.typename, TestSchema.HasManager.version).toString(),
-      [ATTR_RELATION_SOURCE]: DXN.fromLocalObjectId(person1.id).toString(),
-      [ATTR_RELATION_TARGET]: DXN.fromLocalObjectId(person2.id).toString(),
+      [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: [],
       },
@@ -96,7 +98,7 @@ describe('create (static version)', () => {
       email: 'bot@example.com',
     });
 
-    expect(getSchema(contact)).toBe(TestSchema.Person);
+    expect(getSchema(contact)).toBe(Type.getSchema(TestSchema.Person));
   });
 
   test('inspect', () => {

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

@@ -2,27 +2,45 @@
 // Copyright 2025 DXOS.org
 //
 
-import type * as Schema from 'effect/Schema';
-
 import { raise } from '@dxos/debug';
 import { assertArgument, failedInvariant } from '@dxos/invariant';
-import { ObjectId } from '@dxos/keys';
+import { EntityId } from '@dxos/keys';
 
-import { getSchemaDXN, getTypeAnnotation, setTypename } from '../Annotation';
+import type * as Type from '../../Type';
+import { getSchemaURI, getTypeAnnotation, setTypename } from '../Annotation';
 import { defineHiddenProperty } from '../common/proxy';
-import { EntityKind, KindId, MetaId, setSchema } from '../common/types';
+import {
+  EntityKind,
+  KindId,
+  SchemaKindId,
+  StaticTypeSchemaSlot,
+  getStaticTypeSchema,
+  setSchema,
+  setType,
+} from '../common/types';
+import { type EntityMeta } from '../common/types/meta';
+import { MetaId } from '../common/types/model-symbols';
 import {
   RelationSourceDXNId,
   RelationSourceId,
   RelationTargetDXNId,
   RelationTargetId,
   assertObjectModel,
-  getObjectDXN,
+  getObjectEchoUri,
 } from '../Entity';
 import { attachedTypedObjectInspector } from './inspect';
 import { attachTypedJsonSerializer } from './json-serializer';
 
-export type CreateObjectProps<T> = T extends { id: string } ? Omit<T, 'id' | KindId> & { id?: string } : T;
+// 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. Allows `[Obj.Meta]` (MetaId symbol) for
+// seeding registry-provenance meta at construction (mirrors `Obj.make`).
+export type CreateObjectProps<T> = (T extends { id: string }
+  ? Omit<T, 'id' | KindId | SchemaKindId | StaticTypeSchemaSlot> & { id?: string }
+  : Omit<T, KindId | SchemaKindId | StaticTypeSchemaSlot>) & {
+  readonly [MetaId]?: Partial<EntityMeta>;
+};
 
 /**
  * Creates a new object instance from a schema and data, without signal reactivity.
@@ -40,10 +58,7 @@ export type CreateObjectProps<T> = T extends { id: string } ? Omit<T, 'id' | Kin
  * const Contact = Schema.Struct({
  *   name: Schema.String,
  *   email: Schema.String,
- * }).pipe(Type.object({
- *   typename: 'com.example.type.person',
- *   version: '0.1.0',
- * }))
+ * }).pipe(Type.makeObject(DXN.make('com.example.type.person', '0.1.0')))
  *
  * const contact = createObject(Contact, {
  *   name: "John",
@@ -52,10 +67,13 @@ export type CreateObjectProps<T> = T extends { id: string } ? Omit<T, 'id' | Kin
  * ```
  */
 // TODO(burdon): Make internal.
-export const createObject = <S extends Schema.Schema.AnyNoContext>(
-  schema: S,
-  props: CreateObjectProps<Schema.Schema.Type<S>>,
-): CreateObjectProps<Schema.Schema.Type<S>> & { id: string; [KindId]: EntityKind } => {
+export const createObject: {
+  <T extends Type.AnyEntity>(input: T, props: NoInfer<CreateObjectProps<Type.InstanceType<T>>>): Type.InstanceType<T>;
+} = (input: any, props: any): any => {
+  // `Type.Type` entities aren't `Schema.Schema` themselves; read the source
+  // schema off the hidden slot (persisted entities synthesize it lazily via
+  // the proxy `get` trap).
+  const schema = getStaticTypeSchema(input) ?? failedInvariant('Type entity is missing its source schema');
   const annotation = getTypeAnnotation(schema);
   if (!annotation) {
     throw new Error('Schema is not an ECHO schema');
@@ -69,22 +87,50 @@ export const createObject = <S extends Schema.Schema.AnyNoContext>(
     'Relation source and target must be provided together',
   );
 
+  // Pull `[Obj.Meta]` (MetaId-symbol) off props before spreading so it doesn't
+  // leak into data. Callers use this to seed registry-provenance meta fields
+  // (`key`, `version`) and foreign keys / tags at construction time, mirroring
+  // `Obj.make`'s symbol-keyed meta convention.
+  const metaOverride = props[MetaId];
+  if (metaOverride !== undefined) {
+    delete props[MetaId];
+  }
+
   // Raw object.
-  const obj = { ...props, id: props.id ?? ObjectId.random() };
+  const obj = { ...props, id: props.id ?? EntityId.random() };
 
-  // Metadata.
-  const kind = RelationSourceId in props ? EntityKind.Relation : EntityKind.Object;
+  // Metadata. Instance-kind is read from the schema's TypeAnnotation (set by
+  // EchoObjectSchema / EchoRelationSchema / EchoTypeKindSchema): instances of
+  // a type-kind meta-schema are themselves type-kind entities, etc. The
+  // RelationSourceId-in-props check covers the legacy path where the schema
+  // annotation isn't authoritative.
+  const kind =
+    annotation.kind === EntityKind.Type
+      ? EntityKind.Type
+      : annotation.kind === EntityKind.Relation || RelationSourceId in props
+        ? EntityKind.Relation
+        : EntityKind.Object;
   defineHiddenProperty(obj, KindId, kind);
-  defineHiddenProperty(obj, MetaId, { keys: [] });
+  defineHiddenProperty(obj, MetaId, {
+    ...metaOverride,
+    keys: metaOverride?.keys ?? [],
+    tags: metaOverride?.tags ?? [],
+    annotations: metaOverride?.annotations ?? {},
+  });
   setSchema(obj, schema);
-  setTypename(obj, getSchemaDXN(schema) ?? failedInvariant('Missing schema DXN'));
+  // If the caller passed a type entity (recognised via the schema slot), keep
+  // a reference to it on the instance for `Obj.getType` / `Relation.getType`.
+  if (input !== schema) {
+    setType(obj, input);
+  }
+  setTypename(obj, getSchemaURI(schema) ?? failedInvariant('Missing schema URI'));
   attachTypedJsonSerializer(obj);
   attachedTypedObjectInspector(obj);
 
   // Relation.
   if (kind === EntityKind.Relation) {
-    const sourceDXN = getObjectDXN(props[RelationSourceId]) ?? raise(new Error('Unresolved relation source'));
-    const targetDXN = getObjectDXN(props[RelationTargetId]) ?? raise(new Error('Unresolved relation target'));
+    const sourceDXN = getObjectEchoUri(props[RelationSourceId]) ?? raise(new Error('Unresolved relation source'));
+    const targetDXN = getObjectEchoUri(props[RelationTargetId]) ?? raise(new Error('Unresolved relation target'));
     defineHiddenProperty(obj, RelationSourceDXNId, sourceDXN);
     defineHiddenProperty(obj, RelationTargetDXNId, targetDXN);
   }

package/src/internal/Obj/index.ts

@@ -5,10 +5,10 @@
 export * from './common';
 export * from './create-object';
 export * from './deleted';
-export * from './ids';
 export * from './json-serializer';
 export * from './schema-validator';
 export * from './set-value';
 export * from './snapshot';
 export * from './typed-object';
+export * from './atoms';
 export * from './clone';