@dxos/echo 0.8.4-main.40e3dcdf1b → 0.8.4-main.43cb759274

package/src/internal/Obj/clone.ts

@@ -7,8 +7,9 @@ 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';
-import { getMeta, getSchema } from '../common/types';
 
 /**
  * Clones an object or relation.
@@ -17,8 +18,12 @@ import { getMeta, getSchema } from '../common/types';
  */
 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

@@ -2,19 +2,19 @@
 // Copyright 2025 DXOS.org
 //
 
-import { inspect } from 'util';
-
 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_RELATION_SOURCE, ATTR_RELATION_TARGET } from '../Entity';
-import { ATTR_META, ATTR_TYPE, getSchema } from '../common/types';
-
+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';
 
@@ -42,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);
   });
 
@@ -55,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: [],
       },
@@ -83,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: [],
       },
@@ -98,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,28 +2,44 @@
 // 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,
+  SchemaKindId,
+  StaticTypeSchemaSlot,
+  getStaticTypeSchema,
+  setSchema,
+  setType,
+} from '../common/types';
+import { MetaId, type EntityMeta } from '../common/types/meta';
 import {
   RelationSourceDXNId,
   RelationSourceId,
   RelationTargetDXNId,
   RelationTargetId,
   assertObjectModel,
-  getObjectDXN,
+  getObjectEchoUri,
 } from '../Entity';
-import { defineHiddenProperty } from '../common/proxy';
-import { EntityKind, KindId, MetaId, setSchema } from '../common/types';
-
 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.
@@ -41,10 +57,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",
@@ -53,10 +66,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');
@@ -70,22 +86,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/deleted.ts

@@ -2,8 +2,8 @@
 // Copyright 2025 DXOS.org
 //
 
-import { ObjectDeletedId } from '../Entity';
 import { type AnyProperties } from '../common/types';
+import { ObjectDeletedId } from '../Entity';
 
 /**
  * @returns `true` if the object has been marked as deleted.

package/src/internal/Obj/index.ts

@@ -5,7 +5,6 @@
 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';

package/src/internal/Obj/inspect.ts

@@ -6,8 +6,9 @@ import type { InspectOptionsStylized, inspect as inspectFn } from 'node:util';
 
 import { type CustomInspectFunction, inspectCustom } from '@dxos/debug';
 
-import { getTypeDXN } from '../Annotation';
-import { ATTR_META, ATTR_TYPE, type AnyEntity, MetaId } from '../common/types';
+import { getTypeURI } from '../Annotation';
+import { ATTR_TYPE, type AnyEntity } from '../common/types';
+import { ATTR_META, MetaId } from '../common/types/meta';
 
 /*
  * @internal
@@ -37,7 +38,7 @@ const typedObjectInspectFunction: CustomInspectFunction<AnyEntity> = function (
   return inspect(
     {
       id,
-      [ATTR_TYPE]: getTypeDXN(this),
+      [ATTR_TYPE]: getTypeURI(this),
       ...props,
       [ATTR_META]: (this as any)[MetaId], // TODO(dmaretskyi): Couldn't use getMeta since that throw's if the object has no meta.
     },

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

@@ -2,27 +2,29 @@
 // Copyright 2025 DXOS.org
 //
 
+import * as Schema from 'effect/Schema';
 import { describe, expect, test } from 'vitest';
 
-import { DXN } from '@dxos/keys';
+import { DXN, EID } from '@dxos/keys';
 
 import * as Obj from '../../Obj';
 import { TestSchema } from '../../testing';
-import { getSchemaDXN, getSchemaTypename, getTypeDXN, getTypename } from '../Annotation';
+import * as Type from '../../Type';
+import { getTypeURI, getTypename } from '../Annotation';
 import { getMetaChecked } from '../common/api';
-import { RelationSourceId, RelationTargetId, getObjectDXN } from '../Entity';
-import { makeObject } from '../common/proxy';
+import { ATTR_TYPE, EntityKind, KindId, TypeId, getSchema } from '../common/types';
+import { MetaId } from '../common/types/meta';
+import { RelationSourceId, RelationTargetId, getObjectEchoUri } from '../Entity';
+import * as JsonSchema from '../JsonSchema';
 import { Ref, StaticRefResolver } from '../Ref';
-import { ATTR_TYPE, EntityKind, KindId, MetaId, TypeId, getSchema } from '../common/types';
-
 import { createObject } from './create-object';
 import { objectFromJSON, objectToJSON } from './json-serializer';
 
 describe('Object JSON serializer', () => {
   test('should serialize and deserialize object', async () => {
-    const contact = makeObject(TestSchema.Person, { name: 'Alice' });
-    Obj.change(contact, (c) => {
-      getMetaChecked(c).keys.push({ id: '12345', source: 'example.com' });
+    const contact = Obj.make(TestSchema.Person, { name: 'Alice' });
+    Obj.update(contact, (contact) => {
+      getMetaChecked(contact).keys.push({ id: '12345', source: 'example.com' });
     });
 
     const task = createObject(TestSchema.Task, {
@@ -34,13 +36,13 @@ describe('Object JSON serializer', () => {
     const taskJson = objectToJSON(task);
 
     expect(contactJson.id).toBe(contact.id);
-    expect(contactJson[ATTR_TYPE]).toEqual(getSchemaDXN(TestSchema.Person)!.toString());
+    expect(contactJson[ATTR_TYPE]).toEqual(Type.getURI(TestSchema.Person).toString());
     expect(contactJson.name).toEqual('Alice');
 
     expect(taskJson.id).toBe(task.id);
-    expect(taskJson[ATTR_TYPE]).toEqual(getSchemaDXN(TestSchema.Task)!.toString());
+    expect(taskJson[ATTR_TYPE]).toEqual(Type.getURI(TestSchema.Task).toString());
     expect(taskJson.title).toEqual('Fix the tests');
-    expect(taskJson.assignee).toEqual({ '/': DXN.fromLocalObjectId(contact.id).toString() });
+    expect(taskJson.assignee).toEqual({ '/': EID.make({ entityId: contact.id }) });
 
     const refResolver = new StaticRefResolver()
       .addSchema(TestSchema.Person)
@@ -53,7 +55,7 @@ describe('Object JSON serializer', () => {
 
     expect(contactFromJson.id).toBe(contact.id);
     expect(contactFromJson.name).toBe('Alice');
-    expect((contactFromJson as any)[TypeId]).toEqual(getSchemaDXN(TestSchema.Person));
+    expect((contactFromJson as any)[TypeId]).toEqual(Type.getURI(TestSchema.Person));
     expect((contactFromJson as any)[KindId]).toBe(EntityKind.Object);
     expect((contactFromJson as any)[RelationSourceId]).toBeUndefined();
     expect((contactFromJson as any)[RelationTargetId]).toBeUndefined();
@@ -64,23 +66,25 @@ describe('Object JSON serializer', () => {
           source: 'example.com',
         },
       ],
+      tags: [],
+      annotations: {},
     });
-    expect(getTypeDXN(contactFromJson)?.toString()).toBe(getSchemaDXN(TestSchema.Person)!.toString());
-    expect(getTypename(contactFromJson)).toBe(getSchemaTypename(TestSchema.Person));
-    expect(getObjectDXN(contactFromJson)?.toString()).toEqual(getObjectDXN(contact)?.toString());
-    expect(getSchema(contactFromJson)).toEqual(TestSchema.Person);
+    expect(getTypeURI(contactFromJson)?.toString()).toBe(Type.getURI(TestSchema.Person).toString());
+    expect(getTypename(contactFromJson)).toBe(Type.getTypename(TestSchema.Person));
+    expect(getObjectEchoUri(contactFromJson)?.toString()).toEqual(getObjectEchoUri(contact)?.toString());
+    expect(getSchema(contactFromJson)).toEqual(Type.getSchema(TestSchema.Person));
 
     expect(taskFromJson.id).toBe(task.id);
     expect(taskFromJson.title).toBe('Fix the tests');
-    expect(taskFromJson.assignee!.dxn).toEqual(DXN.fromLocalObjectId(contact.id));
+    expect(taskFromJson.assignee!.uri).toEqual(EID.make({ entityId: contact.id }));
     expect(taskFromJson.assignee!.target).toEqual(contact);
     expect(await taskFromJson.assignee!.load()).toEqual(contact);
-    expect((taskFromJson as any)[TypeId]).toEqual(getSchemaDXN(TestSchema.Task));
+    expect((taskFromJson as any)[TypeId]).toEqual(Type.getURI(TestSchema.Task));
     expect((taskFromJson as any)[KindId]).toBe(EntityKind.Object);
     expect((taskFromJson as any)[RelationSourceId]).toBeUndefined();
     expect((taskFromJson as any)[RelationTargetId]).toBeUndefined();
-    expect((taskFromJson as any)[MetaId]).toEqual({ keys: [] });
-    expect(getSchema(taskFromJson)).toEqual(TestSchema.Task);
+    expect((taskFromJson as any)[MetaId]).toEqual({ keys: [], tags: [], annotations: {} });
+    expect(getSchema(taskFromJson)).toEqual(Type.getSchema(TestSchema.Task));
   });
 
   test('serialize with unresolved schema', async () => {
@@ -91,9 +95,20 @@ describe('Object JSON serializer', () => {
     expect(contactFromJson.id).toBe(contact.id);
     expect(contactFromJson.name).toBe('Alice');
     expect(getSchema(contactFromJson)).toBeUndefined();
-    expect(getTypename(contactFromJson)).toEqual(getSchemaTypename(TestSchema.Person));
-    expect(getObjectDXN(contactFromJson)).toEqual(getObjectDXN(contact));
-    expect(getTypeDXN(contactFromJson)).toEqual(getSchemaDXN(TestSchema.Person));
+    expect(getTypename(contactFromJson)).toEqual(Type.getTypename(TestSchema.Person));
+    expect(getObjectEchoUri(contactFromJson)).toEqual(getObjectEchoUri(contact));
+    expect(getTypeURI(contactFromJson)).toEqual(Type.getURI(TestSchema.Person));
+  });
+
+  test('upgrades legacy string tags to encoded references on deserialize', async () => {
+    const expando = Obj.make(TestSchema.Expando, { message: 'hi' });
+    const json = objectToJSON(expando) as any;
+    // Simulate data serialized before the tags-as-refs migration: bare DXN strings.
+    json['@meta'] = { keys: [], tags: ['dxn:echo:@:TAGLEGACY'] };
+
+    const fromJson = (await objectFromJSON(json)) as any;
+    // Decodes to a materialized `Ref` (the shared ref codec), not a raw encoded reference.
+    expect(fromJson[MetaId].tags.map((ref: any) => ref.uri)).toEqual(['dxn:echo:@:TAGLEGACY']);
   });
 
   test('deserializes expando without leaking internal json keys', async () => {
@@ -118,4 +133,67 @@ describe('Object JSON serializer', () => {
     expect(expandoFromJson.message).toBe('local-only');
     expect((expandoFromJson as any)[ATTR_TYPE]).toBeUndefined();
   });
+
+  // `objectFromJSON` is the deserialization path for queue messages and devtools
+  // round-trips. For persisted `Type.Type` entities it must stamp `KindId = Type`
+  // (not Object), mirroring the kind resolution that `createObject` does for the
+  // in-memory path. Otherwise `Filter.type(Type.Type)` / `Type.isType` skip them.
+  describe('Type.Type round-trip', () => {
+    test('preserves KindId=Type for a persisted Type.Type entity', async ({ expect }) => {
+      const typeEntity = Type.makeObjectFromJsonSchema({
+        typename: 'com.example.type.regression',
+        version: '0.1.0',
+        jsonSchema: JsonSchema.toJsonSchema(Schema.Struct({ field: Schema.Number })),
+        name: 'Regression Type',
+      });
+
+      const typeJson = objectToJSON(typeEntity as any);
+      const refResolver = new StaticRefResolver().addSchema(Type.Type);
+      const reconstructed = (await objectFromJSON(typeJson, { refResolver })) as any;
+
+      expect(reconstructed[KindId]).toBe(EntityKind.Type);
+      expect(Type.isType(reconstructed)).toBe(true);
+      // `typename` lives in `EntityMeta.key` on persisted Type.Type entities
+      // — surfaced via `Type.getTypename`.
+      expect(Type.getTypename(reconstructed)).toBe('com.example.type.regression');
+    });
+  });
+
+  describe('Uint8Array', () => {
+    const Blob = Schema.Struct({
+      name: Schema.String,
+      bytes: Schema.Uint8ArrayFromSelf,
+    }).pipe(Type.makeObject(DXN.make('com.example.type.blob', '0.1.0')));
+    type Blob = Type.InstanceType<typeof Blob>;
+
+    test('round-trips Uint8Array field through JSON with schema', async ({ expect }) => {
+      const bytes = new Uint8Array([0, 1, 2, 3, 250, 251, 252, 253, 254, 255]);
+      const blob = Obj.make(Blob, { name: 'blob', bytes });
+
+      const blobJson = objectToJSON(blob);
+      // JSON must round-trip through stringify/parse without loss.
+      const roundTripped = JSON.parse(JSON.stringify(blobJson));
+
+      const refResolver = new StaticRefResolver().addSchema(Blob);
+      const blobFromJson = (await objectFromJSON(roundTripped, { refResolver })) as Blob;
+
+      expect(blobFromJson.name).toBe('blob');
+      expect(blobFromJson.bytes).toBeInstanceOf(Uint8Array);
+      expect(Array.from(blobFromJson.bytes)).toEqual(Array.from(bytes));
+    });
+
+    test('round-trips Uint8Array field through JSON without schema resolver', async ({ expect }) => {
+      const bytes = new Uint8Array([10, 20, 30, 40, 50]);
+      const blob = Obj.make(Blob, { name: 'blob', bytes });
+
+      const blobJson = objectToJSON(blob);
+      const roundTripped = JSON.parse(JSON.stringify(blobJson));
+
+      const blobFromJson = (await objectFromJSON(roundTripped)) as Blob;
+
+      expect(blobFromJson.name).toBe('blob');
+      expect(blobFromJson.bytes).toBeInstanceOf(Uint8Array);
+      expect(Array.from(blobFromJson.bytes)).toEqual(Array.from(bytes));
+    });
+  });
 });