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

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/Obj/common.ts

@@ -0,0 +1,75 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+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 = {
+  // TODO(burdon): Document.
+  partial?: true;
+  // TODO(burdon): Document.
+  record?: true;
+};
+
+/**
+ *
+ */
+// TODO(burdon): Comment required.
+// TODO(dmaretskyi): Rename to represent commonality between objects and relations (e.g. `entity`).
+type SimplifiedSchemaFields<
+  SchemaFields extends Schema.Struct.Fields,
+  Options extends TypedObjectOptions,
+> = Options['partial'] extends boolean
+  ? Schema.SimplifyMutable<Partial<Schema.Struct.Type<SchemaFields>>>
+  : Schema.SimplifyMutable<Schema.Struct.Type<SchemaFields>>;
+
+/**
+ *
+ */
+// TODO(burdon): Comment required.
+// TODO(dmaretskyi): Rename to represent commonality between objects and relations (e.g. `entity`).
+export type TypedObjectFields<
+  SchemaFields extends Schema.Struct.Fields,
+  Options extends TypedObjectOptions,
+> = SimplifiedSchemaFields<SchemaFields, Options> & { id: string } & (Options['record'] extends boolean
+    ? Schema.SimplifyMutable<Schema.IndexSignature.Type<Schema.IndexSignature.Records>>
+    : {});
+
+export const makeTypedEntityClass = (
+  typename: string,
+  version: string,
+  baseSchema: Schema.Schema.AnyNoContext,
+): Schema.SchemaClass<any> => {
+  return class {
+    // Implement TypedObject properties.
+    static readonly typename = typename;
+    static readonly version = version;
+
+    // Implement Schema.Schema properties.
+    // TODO(burdon): Comment required.
+    static readonly [Schema.TypeId] = schemaVariance;
+    static readonly ast = baseSchema.ast;
+    static readonly annotations = baseSchema.annotations.bind(baseSchema);
+    static readonly pipe = baseSchema.pipe.bind(baseSchema);
+
+    // TODO(burdon): Comment required.
+    static [Symbol.hasInstance](obj: AnyProperties) {
+      return obj != null && getTypename(obj) === typename;
+    }
+
+    // TODO(burdon): Throw APIError.
+    private constructor() {
+      throw new Error('Use live(Typename, { ...fields }) to instantiate an object.');
+    }
+  } as any;
+};
+
+const schemaVariance = {
+  _A: (_: any) => _,
+  _I: (_: any) => _,
+  _R: (_: never) => _,
+};

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');
+  });
+});

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

@@ -0,0 +1,140 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { raise } from '@dxos/debug';
+import { assertArgument, failedInvariant } from '@dxos/invariant';
+import { EntityId } from '@dxos/keys';
+
+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 { type EntityMeta } from '../common/types/meta';
+import { MetaId } from '../common/types/model-symbols';
+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<EntityMeta>;
+};
+
+/**
+ * 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 ?? EntityId.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, {
+    ...metaOverride,
+    keys: metaOverride?.keys ?? [],
+    tags: metaOverride?.tags ?? [],
+    annotations: metaOverride?.annotations ?? {},
+  });
+  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,14 @@
+//
+// 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 './atoms';
+export * from './clone';