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

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

@@ -13,23 +13,33 @@ import type * as Types from 'effect/Types';
 import { raise } from '@dxos/debug';
 import { mapAst } from '@dxos/effect';
 import { assertArgument, invariant } from '@dxos/invariant';
-import { DXN, ObjectId } from '@dxos/keys';
+import { DXN, EchoURI, ObjectId } 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,
+  makeTypeJsonSchemaAnnotation,
+} from '../Annotation';
+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 +81,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 +124,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);
 };
@@ -319,7 +347,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 +358,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.startsWith('dxn:echo:') ? root.$id : undefined;
     return createEchoReferenceSchema(
-      echoId,
+      echoUri,
       (echoRefinement as any).reference.typename,
       (echoRefinement as any).reference.version,
     );
@@ -344,21 +372,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 +395,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 +406,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 +425,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:/… or legacy dxn:echo:…).
+  if (schema.$id && (schema.$id.startsWith('echo:') || schema.$id.startsWith('dxn: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();
-    }
+  }
+  // Legacy: older serializations stored the EchoURI on echo.type.schemaId.
+  const legacySchemaId = schema.echo?.type?.schemaId;
+  if (legacySchemaId) {
+    return ObjectId.isValid(legacySchemaId) ? EchoURI.make({ objectId: legacySchemaId }) : legacySchemaId;
   }
   return undefined;
 };
@@ -421,8 +449,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 +480,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 EchoURI (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 +518,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/clone.ts

@@ -0,0 +1,52 @@
+//
+// 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 { getMeta, getSchema, getStaticTypeSchema, getType } from '../common/types';
+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/{object/create.test.ts → Obj/create-object.test.ts}

@@ -2,22 +2,20 @@
 // 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, EchoURI } from '@dxos/keys';
 
-import { getSchemaDXN } from '../ast';
-import { Testing } from '../testing';
-import { isInstanceOf } from '../types';
-
-import { getSchema } from './accessors';
-import { create } from './create';
+import { Relation } from '../../index';
+import { TestSchema } from '../../testing';
+import * as Type from '../../Type';
+import { getTypeURI } from '../Annotation';
+import { ATTR_META, ATTR_TYPE, getSchema } from '../common/types';
+import { ATTR_RELATION_SOURCE, ATTR_RELATION_TARGET, isInstanceOf } from '../Entity';
+import { createObject } from './create-object';
 import { objectToJSON } from './json-serializer';
-import { RelationSourceId, RelationTargetId } from './model';
-import { getType } from './typename';
 
 describe('create (static version)', () => {
   test('defaults', ({ expect }) => {
@@ -34,7 +32,7 @@ describe('create (static version)', () => {
   });
 
   test('create static object', () => {
-    const contact = create(Testing.Contact, {
+    const contact = createObject(TestSchema.Person, {
       name: 'Bot',
       email: 'bot@example.com',
     });
@@ -43,12 +41,12 @@ describe('create (static version)', () => {
     expect(contact.name).toBe('Bot');
     expect(contact.email).toBe('bot@example.com');
     expect((contact as any)['@type']).toBeUndefined();
-    expect(getType(contact)?.toString()).toBe(getSchemaDXN(Testing.Contact)!.toString());
-    expect(isInstanceOf(Testing.Contact, contact)).toBe(true);
+    expect(getTypeURI(contact)?.toString()).toBe(Type.getURI(TestSchema.Person).toString());
+    expect(isInstanceOf(TestSchema.Person, contact)).toBe(true);
   });
 
   test('JSON encoding', () => {
-    const contact = create(Testing.Contact, {
+    const contact = createObject(TestSchema.Person, {
       name: 'Bot',
       email: 'bot@example.com',
     });
@@ -56,7 +54,7 @@ describe('create (static version)', () => {
     const json = JSON.parse(JSON.stringify(contact));
     expect(json).toEqual({
       id: contact.id,
-      '@type': DXN.fromTypenameAndVersion(Testing.Contact.typename, Testing.Contact.version).toString(),
+      '@type': DXN.make(Type.getTypename(TestSchema.Person), Type.getVersion(TestSchema.Person)),
       '@meta': {
         keys: [],
       },
@@ -67,52 +65,51 @@ describe('create (static version)', () => {
   });
 
   test('JSON encoding with relation', () => {
-    const contactA = create(Testing.Contact, {
-      name: 'Bot',
-      email: 'bot@example.com',
+    const person1 = createObject(TestSchema.Person, {
+      name: 'Alice',
+      email: 'alice@example.com',
     });
-    const contactB = create(Testing.Contact, {
-      name: 'Bot',
-      email: 'bot@example.com',
+    const person2 = createObject(TestSchema.Person, {
+      name: 'Bob',
+      email: 'bob@example.com',
     });
-    const hasManager = create(Testing.HasManager, {
-      [RelationSourceId]: contactA,
-      [RelationTargetId]: contactB,
+
+    const manager = createObject(TestSchema.HasManager, {
+      [Relation.Source]: person1 as any,
+      [Relation.Target]: person2 as any,
     });
 
-    const json = JSON.parse(JSON.stringify(hasManager));
+    const json = JSON.parse(JSON.stringify(manager));
     expect(json).toEqual({
-      id: hasManager.id,
-      '@type': DXN.fromTypenameAndVersion(Testing.HasManager.typename, Testing.HasManager.version).toString(),
-      '@relationSource': DXN.fromLocalObjectId(contactA.id).toString(),
-      '@relationTarget': DXN.fromLocalObjectId(contactB.id).toString(),
-      '@meta': {
+      id: manager.id,
+      [ATTR_TYPE]: DXN.make(Type.getTypename(TestSchema.HasManager), Type.getVersion(TestSchema.HasManager)),
+      [ATTR_RELATION_SOURCE]: EchoURI.make({ objectId: person1.id }),
+      [ATTR_RELATION_TARGET]: EchoURI.make({ objectId: person2.id }),
+      [ATTR_META]: {
         keys: [],
       },
     });
   });
 
   test('getSchema', () => {
-    const contact = create(Testing.Contact, {
+    const contact = createObject(TestSchema.Person, {
       name: 'Bot',
       email: 'bot@example.com',
     });
 
-    expect(getSchema(contact)).toBe(Testing.Contact);
+    expect(getSchema(contact)).toBe(Type.getSchema(TestSchema.Person));
   });
 
   test('inspect', () => {
-    const contact = create(Testing.Contact, {
+    const contact = createObject(TestSchema.Person, {
       name: 'Bot',
       email: 'bot@example.com',
     });
 
-    // console.log(contact);
-
     const text = inspect(contact);
     expect(text).toContain('Bot');
     expect(text).toContain('bot@example.com');
-    expect(text).toContain('example.com/type/Contact');
+    expect(text).toContain('com.example.type.person');
     expect(text).toContain('0.1.0');
   });
 });

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

@@ -0,0 +1,135 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { raise } from '@dxos/debug';
+import { assertArgument, failedInvariant } from '@dxos/invariant';
+import { ObjectId } from '@dxos/keys';
+
+import type * as Type from '../../Type';
+import { getSchemaURI, getTypeAnnotation, setTypename } from '../Annotation';
+import { defineHiddenProperty } from '../common/proxy';
+import {
+  EntityKind,
+  KindId,
+  MetaId,
+  type ObjectMeta,
+  SchemaKindId,
+  StaticTypeSchemaSlot,
+  getStaticTypeSchema,
+  setSchema,
+  setType,
+} from '../common/types';
+import {
+  RelationSourceDXNId,
+  RelationSourceId,
+  RelationTargetDXNId,
+  RelationTargetId,
+  assertObjectModel,
+  getObjectEchoUri,
+} from '../Entity';
+import { attachedTypedObjectInspector } from './inspect';
+import { attachTypedJsonSerializer } from './json-serializer';
+
+// 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<ObjectMeta>;
+};
+
+/**
+ * Creates a new object instance from a schema and data, without signal reactivity.
+ * This static version creates plain JavaScript objects that are not reactive/observable.
+ * For reactive objects that automatically update UI when changed, use the regular live() function.
+ *
+ * @param schema - The Effect schema that defines the object's structure and type, piped into EchoObjectSchema
+ * @param data - The data to initialize the object with. The id and @type fields are handled automatically.
+ * @returns A new non-reactive object instance conforming to the schema
+ * @throws {Error} If the schema is not an object schema
+ * @throws {TypeError} If data contains an @type field
+ *
+ * @example
+ * ```ts
+ * const Contact = Schema.Struct({
+ *   name: Schema.String,
+ *   email: Schema.String,
+ * }).pipe(Type.makeObject(DXN.make('com.example.type.person', '0.1.0')))
+ *
+ * const contact = createObject(Contact, {
+ *   name: "John",
+ *   email: "john@example.com",
+ * })
+ * ```
+ */
+// TODO(burdon): Make internal.
+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');
+  }
+  assertArgument(!('@type' in props), 'data', '@type is not allowed');
+  assertArgument(!(RelationSourceDXNId in props), 'data', 'Relation source DXN is not allowed in the constructor');
+  assertArgument(!(RelationTargetDXNId in props), 'data', 'Relation target DXN is not allowed in the constructor');
+  assertArgument(
+    RelationSourceId in props === RelationTargetId in props,
+    'data',
+    '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() };
+
+  // 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: [], ...metaOverride });
+  setSchema(obj, schema);
+  // 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 = 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);
+  }
+
+  assertObjectModel(obj);
+  return obj;
+};

package/src/internal/Obj/deleted.ts

@@ -0,0 +1,19 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type AnyProperties } from '../common/types';
+import { ObjectDeletedId } from '../Entity';
+
+/**
+ * @returns `true` if the object has been marked as deleted.
+ */
+export const isDeleted = (obj: AnyProperties): boolean => {
+  if ((obj as any)[ObjectDeletedId] === undefined) {
+    // TODO(dmaretskyi): Return to prior behavior of throwing.
+    // throw new Error('Object does not support deletion marker');
+    return false;
+  }
+
+  return (obj as any)[ObjectDeletedId] ?? false;
+};

package/src/internal/Obj/index.ts

@@ -0,0 +1,13 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+export * from './common';
+export * from './create-object';
+export * from './deleted';
+export * from './json-serializer';
+export * from './schema-validator';
+export * from './set-value';
+export * from './snapshot';
+export * from './typed-object';
+export * from './clone';

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

@@ -6,10 +6,8 @@ import type { InspectOptionsStylized, inspect as inspectFn } from 'node:util';
 
 import { type CustomInspectFunction, inspectCustom } from '@dxos/debug';
 
-import { type AnyEchoObject } from '../types';
-
-import { ATTR_META, ATTR_TYPE, MetaId } from './model';
-import { getType } from './typename';
+import { getTypeURI } from '../Annotation';
+import { ATTR_META, ATTR_TYPE, type AnyEntity, MetaId } from '../common/types';
 
 /*
  * @internal
@@ -29,8 +27,8 @@ export const attachedTypedObjectInspector = (obj: any) => {
 };
 
 // NOTE: KEEP as function.
-const typedObjectInspectFunction: CustomInspectFunction<AnyEchoObject> = function (
-  this: AnyEchoObject,
+const typedObjectInspectFunction: CustomInspectFunction<AnyEntity> = function (
+  this: AnyEntity,
   depth: number,
   options: InspectOptionsStylized,
   inspect: typeof inspectFn,
@@ -39,7 +37,7 @@ const typedObjectInspectFunction: CustomInspectFunction<AnyEchoObject> = functio
   return inspect(
     {
       id,
-      [ATTR_TYPE]: getType(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.
     },