@dxos/echo 0.8.4-main.d05539e30a → 0.8.4-main.d9fc60f731

package/src/Json.ts

@@ -2,7 +2,7 @@
 // Copyright 2026 DXOS.org
 //
 
-import { DXN } from '@dxos/keys';
+import { EID } from '@dxos/keys';
 
 import * as Database from './Database';
 import * as Obj from './Obj';
@@ -64,21 +64,22 @@ export const createRefReplacer = ({ db, depth = 1 }: CreateRefReplacerOptions):
       // an unparseable string would otherwise crash the whole `JSON.stringify`.
       // Treat any parse miss as "leave as-is" rather than propagating.
       const dxnString = value['/'];
-      if (!dxnString.startsWith('dxn:')) {
+      if (!dxnString.startsWith('dxn:') && !dxnString.startsWith('echo:')) {
         return value;
       }
 
-      let echoId: string | undefined;
+      let echoUri: string | undefined;
       try {
-        echoId = DXN.parse(dxnString).asEchoDXN()?.echoId;
+        const parsed = EID.tryParse(dxnString);
+        echoUri = parsed ? EID.getEntityId(parsed) : undefined;
       } catch {
         return value;
       }
 
-      if (!echoId) {
+      if (!echoUri) {
         return value;
       }
-      const target = db.getObjectById(echoId);
+      const target = db.getObjectById(echoUri);
       if (!target) {
         return value;
       }

package/src/Key.ts

@@ -5,4 +5,4 @@
 // TODO(wittjosiah): Should this be a subset of Type?
 
 export { ForeignKey } from '@dxos/echo-protocol';
-export { SpaceId, ObjectId } from '@dxos/keys';
+export { EID, EntityId, SpaceId, URI } from '@dxos/keys';

package/src/Migration.ts

@@ -6,25 +6,31 @@
 
 import type * as Schema from 'effect/Schema';
 
-import { type DXN } from '@dxos/keys';
+import { type URI } from '@dxos/keys';
 
 import type * as Database from './Database';
 import type * as Entity from './Entity';
-import { MetaId, type ObjectMeta, getSchemaDXN } from './internal';
+import { MetaId, type EntityMeta, getSchemaURI } from './internal';
+import * as Type from './Type';
 
 /**
  * Result returned by a migration's `transform` callback.
  * The data shape matches the target schema; the optional `[Obj.Meta]` symbol key lets the
  * transform update the object's meta (e.g. `key` / `version`) atomically with the data swap.
  */
-export type TransformResult<To extends Schema.Schema.AnyNoContext> = Omit<
-  Schema.Schema.Type<To>,
-  'id' | Entity.KindId
-> & {
-  [MetaId]?: Partial<ObjectMeta>;
+type MigrationSchemaInput = Type.AnyEntity;
+
+type MigrationInstanceType<S> = S extends Type.AnyEntity
+  ? Type.InstanceType<S>
+  : S extends Schema.Schema.AnyNoContext
+    ? Schema.Schema.Type<S>
+    : never;
+
+export type TransformResult<To> = Omit<MigrationInstanceType<To>, 'id' | Entity.KindId> & {
+  [MetaId]?: Partial<EntityMeta>;
 };
 
-type DefineObjectMigrationOptions<From extends Schema.Schema.AnyNoContext, To extends Schema.Schema.AnyNoContext> = {
+type DefineObjectMigrationOptions<From extends MigrationSchemaInput, To extends MigrationSchemaInput> = {
   from: From;
   to: To;
   /**
@@ -34,7 +40,7 @@ type DefineObjectMigrationOptions<From extends Schema.Schema.AnyNoContext, To ex
    * (e.g. registry `key` / `version`) atomically with the data swap.
    */
   // TODO(dmaretskyi): `id` should not be a part of the schema.
-  transform: (from: Schema.Schema.Type<From>, context: ObjectMigrationContext) => Promise<TransformResult<To>>;
+  transform: (from: MigrationInstanceType<From>, context: ObjectMigrationContext) => Promise<TransformResult<To>>;
 
   /**
    * Callback that is called after the object is migrated. Called for every object that is migrated.
@@ -52,9 +58,9 @@ export type ObjectMigrationContext = {
   db: Database.Database;
 };
 
-type OnMigrateProps<From extends Schema.Schema.AnyNoContext, To extends Schema.Schema.AnyNoContext> = {
-  before: Schema.Schema.Type<From>;
-  object: Schema.Schema.Type<To>;
+type OnMigrateProps<From, To> = {
+  before: MigrationInstanceType<From>;
+  object: MigrationInstanceType<To>;
   db: Database.Database;
 };
 
@@ -62,8 +68,8 @@ type OnMigrateProps<From extends Schema.Schema.AnyNoContext, To extends Schema.S
  * Definition of a migration from one object schema version to another.
  */
 export type ObjectMigration = {
-  fromType: DXN;
-  toType: DXN;
+  fromType: URI.URI;
+  toType: URI.URI;
   fromSchema: Schema.Schema.AnyNoContext;
   toSchema: Schema.Schema.AnyNoContext;
   transform: (from: unknown, context: ObjectMigrationContext) => Promise<unknown>;
@@ -83,14 +89,16 @@ export type ObjectMigration = {
  * });
  * ```
  */
-export const define = <From extends Schema.Schema.AnyNoContext, To extends Schema.Schema.AnyNoContext>(
+export const define = <From extends MigrationSchemaInput, To extends MigrationSchemaInput>(
   options: DefineObjectMigrationOptions<From, To>,
 ): ObjectMigration => {
-  const fromType = getSchemaDXN(options.from);
+  const fromSchema = Type.getSchema(options.from);
+  const toSchema = Type.getSchema(options.to);
+  const fromType = getSchemaURI(fromSchema);
   if (!fromType) {
     throw new Error('Invalid from schema');
   }
-  const toType = getSchemaDXN(options.to);
+  const toType = getSchemaURI(toSchema);
   if (!toType) {
     throw new Error('Invalid to schema');
   }
@@ -98,8 +106,8 @@ export const define = <From extends Schema.Schema.AnyNoContext, To extends Schem
   return {
     fromType,
     toType,
-    fromSchema: options.from,
-    toSchema: options.to,
+    fromSchema,
+    toSchema,
     transform: options.transform as any,
     onMigration: options.onMigration as any,
   };

package/src/Obj.test.ts

@@ -42,8 +42,8 @@ describe('Obj', () => {
       const snapshot = Obj.getSnapshot(obj);
 
       // getDXN - works with both.
-      expect(Obj.getDXN(obj)).toBeDefined();
-      expect(Obj.getDXN(snapshot)).toBeDefined();
+      expect(Obj.getURI(obj)).toBeDefined();
+      expect(Obj.getURI(snapshot)).toBeDefined();
 
       // getTypename - works with both.
       expect(Obj.getTypename(obj)).toBe('com.example.type.person');
@@ -80,6 +80,17 @@ describe('Obj', () => {
       expect(SnapshotKindId in snapshot).toBe(true);
       expect(Entity.KindId in snapshot).toBe(false);
     });
+
+    test('getSnapshot preserves parent', ({ expect }) => {
+      const parent = Obj.make(TestSchema.Organization, { name: 'parent' });
+      const child = Obj.make(TestSchema.Person, { name: 'child' });
+      Obj.setParent(child, parent);
+
+      const snapshot = Obj.getSnapshot(child);
+
+      expect(Obj.getParent(child)).toBe(parent);
+      expect(Obj.getParent(snapshot)).toBe(parent);
+    });
   });
 
   describe('snapshotOf', () => {
@@ -134,7 +145,7 @@ describe('Obj', () => {
 
     test('throws for plain object without metadata', ({ expect }) => {
       const plain = { id: 'plain-1', name: 'Plain' };
-      expect(() => Obj.getKeys(plain as any, SOURCE)).toThrow(/ObjectMeta not found/);
+      expect(() => Obj.getKeys(plain as any, SOURCE)).toThrow(/EntityMeta not found/);
     });
   });
 
@@ -329,8 +340,8 @@ describe('Obj', () => {
       expect(cloned.address?.city).toBe('San Francisco');
       expect(cloned.address?.state).toBe('CA');
       expect(cloned.address?.zip).toBe('94102');
-      expect(cloned.address?.coordinates.lat).toBe(37.7749);
-      expect(cloned.address?.coordinates.lng).toBe(-122.4194);
+      expect(cloned.address?.coordinates?.lat).toBe(37.7749);
+      expect(cloned.address?.coordinates?.lng).toBe(-122.4194);
 
       // Modifying nested properties should be independent
       Obj.update(person, (person) => {
@@ -405,7 +416,7 @@ describe('Obj', () => {
       const cloned = Obj.clone(person);
 
       expect(Obj.instanceOf(TestSchema.Person, cloned)).toBe(true);
-      expect(Obj.getSchema(cloned)).toBe(Obj.getSchema(person));
+      expect(Obj.getType(cloned)).toBe(Obj.getType(person));
     });
   });
 
@@ -490,7 +501,7 @@ describe('Obj', () => {
       Obj.update(target, (target) => {
         expect(Obj.updateFrom(target, source)).toBe(true);
       });
-      expect(target.employer?.dxn.toString()).toBe(Ref.make(orgB).dxn.toString());
+      expect(target.employer?.uri.toString()).toBe(Ref.make(orgB).uri.toString());
       expect(target.address?.city).toBe('Portland');
     });
 
@@ -513,7 +524,7 @@ describe('Obj', () => {
       Obj.update(target, (target) => {
         expect(Obj.updateFrom(target, source)).toBe(true);
       });
-      expect(target.tasks?.map((r) => r.dxn.toString())).toEqual(source.tasks?.map((r) => r.dxn.toString()));
+      expect(target.tasks?.map((r) => r.uri)).toEqual(source.tasks?.map((r) => r.uri));
     });
 
     test('respects include option', () => {

package/src/Obj.ts

@@ -14,7 +14,7 @@ import * as Utils from 'effect/Utils';
 import type { ForeignKey } from '@dxos/echo-protocol';
 import { createJsonPath } from '@dxos/effect';
 import { assertArgument, invariant } from '@dxos/invariant';
-import { type DXN, ObjectId } from '@dxos/keys';
+import { DXN, EntityId, type URI } from '@dxos/keys';
 import { assumeType, deepMapValues } from '@dxos/util';
 
 import type * as Database from './Database';
@@ -24,7 +24,8 @@ import * as internal from './internal';
 import { getProxyTarget, isProxy } from './internal/common/proxy/proxy-utils';
 import * as objInternal from './internal/Obj';
 import * as Ref from './Ref';
-import type * as Type from './Type';
+import type * as Tag from './Tag';
+import * as Type from './Type';
 
 /**
  * Base type for all ECHO objects.
@@ -64,25 +65,24 @@ export interface Unknown extends BaseObj {}
  * // Reference to any object type
  * const Collection = Schema.Struct({
  *   objects: Schema.Array(Ref.Ref(Obj.Unknown)),
- * }).pipe(Type.object({ typename: 'Collection', version: '0.1.0' }));
+ * }).pipe(Type.makeObject(DXN.make('com.example.type.collection', '0.1.0')));
  * ```
  */
 // TODO(wittjosiah): Investigate if Schema.filter can validate KindId on ECHO instances.
 //   Effect Schema normalizes proxy objects to plain objects before calling filter predicates.
 //   Possible approaches: custom Schema.declare, AST manipulation, or upstream contribution.
-export const Unknown: Type.Obj<Unknown> = Schema.Struct({
+export const Unknown: internal.UnknownTypeSchema<Unknown, typeof Entity.Kind.Object> = Schema.Struct({
   id: Schema.String,
 }).pipe(
   Schema.extend(Schema.Record({ key: Schema.String, value: Schema.Unknown })),
-  // TODO(dmaretskyi): Clean this up.
-  // NOTE: The EchoObjectSchema annotation is required for Ref.Ref(Obj.Unknown) to work.
-  //   The typename/version only satisfy ECHO schema machinery for reference targets.
-  internal.EchoObjectSchema({ typename: internal.ANY_OBJECT_TYPENAME, version: internal.ANY_OBJECT_VERSION }),
-  (schema) =>
-    Object.assign(schema, {
-      [internal.SchemaKindId]: (schema as any)[internal.SchemaKindId],
-    }) as unknown as Type.Obj<Unknown>,
-);
+  Schema.annotations({
+    [internal.TypeAnnotationId]: {
+      kind: Entity.Kind.Object,
+      typename: internal.ANY_OBJECT_TYPENAME,
+      version: internal.ANY_OBJECT_VERSION,
+    },
+  }),
+) as unknown as internal.UnknownTypeSchema<Unknown, typeof Entity.Kind.Object>;
 
 /**
  * Object with arbitrary properties.
@@ -99,7 +99,7 @@ export interface Any extends BaseObj, internal.AnyProperties {}
  */
 interface BaseSnapshot extends internal.AnyEntity {
   readonly [Entity.SnapshotKindId]: typeof Entity.Kind.Object;
-  readonly id: ObjectId;
+  readonly id: EntityId;
 }
 
 /**
@@ -120,30 +120,44 @@ export interface BaseObjJson {
   id: string;
 }
 
-const defaultMeta: internal.ObjectMeta = {
+// Factory (not a shared const): each object must get its own `keys`/`tags`/`annotations` containers,
+// otherwise mutating one object's meta would leak into every other object via the shared references.
+const defaultMeta = (): internal.EntityMeta => ({
   keys: [],
-};
-
-type MakePropsInternal<T extends Unknown> = {
-  id?: ObjectId;
-  [Meta]?: Partial<internal.ObjectMeta>;
-} & Entity.Properties<T>;
+  tags: [],
+  annotations: {},
+});
 
 // TODO(burdon): Should we allow the caller to set the id?
 /**
- * Props type for object creation with a given schema.
+ * Props type for object creation with a given type. Accepts a `Type.AnyObj`
+ * entity and derives the instance shape via `Type.InstanceType`. Relation-kind
+ * entities are rejected at the type level — use `Relation.MakeProps` for those.
+ *
+ * When the schema is the unconstrained `Type.AnyObj` (`Obj<unknown>` — e.g. a
+ * dynamic type from `schemaRegistry.register`), the instance shape is not
+ * statically known, so data props widen to `Record<string, unknown>` and the
+ * caller can pass arbitrary fields without a cast.
  */
-export type MakeProps<S extends Schema.Schema.AnyNoContext> = {
-  id?: ObjectId;
-  [Meta]?: Partial<internal.ObjectMeta>;
+export type MakeProps<S extends Type.AnyObj> = {
+  id?: EntityId;
+  [Meta]?: Partial<internal.EntityMeta>;
   [Parent]?: Unknown;
-} & MakePropsInternal<Schema.Schema.Type<S>>;
+  // When the resolved instance has no known data keys, widen to a permissive
+  // record (the `Obj<unknown>` case); otherwise use the precise property shape.
+  // `[keyof …] extends [never]` is wrapped in tuples so the check is
+  // non-distributive — a `never` instance type (e.g. when narrowing collapses
+  // the schema) stays a single branch instead of distributing to `never`.
+} & ([keyof Entity.Properties<Type.InstanceType<S>>] extends [never]
+  ? Record<string, unknown>
+  : Entity.Properties<Type.InstanceType<S>>);
 
 /**
- * Creates a new echo object of the given schema.
- * @param schema - Object schema.
+ * Creates a new echo object of the given schema or `Type.Type`.
+ *
+ * @param typeOrSchema - A static object schema (`Type.makeObject(...)`) or a
+ *   `Type.Type` entity (e.g. one returned by `db.addType(schemaEntity)`).
  * @param props - Object properties.
- * @param meta - Object metadata (deprecated) -- pass with Obj.Meta.
  *
  * Meta can be passed as a symbol in `props`.
  *
@@ -152,23 +166,26 @@ export type MakeProps<S extends Schema.Schema.AnyNoContext> = {
  * const obj = Obj.make(Person, { [Obj.Meta]: { keys: [...] }, name: 'John' });
  * ```
  *
- * Note: Only accepts object schemas, not relation schemas. Use `Relation.make` for relations.
+ * Note: Only accepts object schemas / object-kind types, not relation schemas.
+ * Use `Relation.make` for relations.
  */
-export const make = <S extends Type.AnyObj>(
-  schema: S,
-  props: NoInfer<MakeProps<S>>,
-): OfShape<Schema.Schema.Type<S>> => {
+export function make<T extends Type.AnyObj>(type: T, props: NoInfer<MakeProps<T>>): OfShape<Type.InstanceType<T>>;
+export function make(input: Type.AnyObj, props: any): OfShape<any> {
+  // `Type.Type` entities aren't `Schema.Schema` themselves; derive the Effect
+  // Schema via `Type.getSchema(...)`. Pass the entity through to `makeObject`
+  // so subsequent schema mutations (`Type.addFields`, etc.) propagate.
+  const schema = Type.getSchema(input);
   assertArgument(
     internal.getTypeAnnotation(schema)?.kind === Entity.Kind.Object,
     'schema',
     'Expected an object schema',
   );
 
-  let meta: internal.ObjectMeta | undefined = undefined;
+  let meta: internal.EntityMeta | undefined = undefined;
 
   // Set default fields on meta on creation.
   if (props[internal.MetaId] != null) {
-    meta = { ...structuredClone(defaultMeta), ...props[internal.MetaId] };
+    meta = { ...defaultMeta(), ...props[internal.MetaId] };
     delete props[internal.MetaId];
   }
 
@@ -183,11 +200,16 @@ export const make = <S extends Type.AnyObj>(
     }
   }
 
-  return internal.makeObject<Schema.Schema.Type<S>>(schema, filterUndefined as any, {
-    ...defaultMeta,
-    ...meta,
-  });
-};
+  return internal.makeObject(
+    schema,
+    filterUndefined,
+    {
+      ...defaultMeta(),
+      ...meta,
+    },
+    input,
+  );
+}
 
 /**
  * Determine if object is an ECHO object.
@@ -401,12 +423,12 @@ export const setValue: (obj: Mutable<Unknown>, path: readonly (string | number)[
 // Type
 //
 
-// TODO(burdon): To discuss: prefer over ObjectId or Key.ObjectId or Type.ID?
-export const ID = ObjectId;
-export type ID = ObjectId;
+export const ID = EntityId;
+export type ID = EntityId;
 
 /**
- * Test if object or relation is an instance of a schema.
+ * Test if an object is an instance of a given object type.
+ *
  * @example
  * ```ts
  * const john = Obj.make(Person, { name: 'John' });
@@ -415,11 +437,29 @@ export type ID = ObjectId;
  *   // john is Person
  * }
  * ```
+ *
+ * Only accepts `Type.AnyObj` — use `Relation.instanceOf` for relations and
+ * `Type.isType(value)` to test for `Type.Type` meta-schema entities.
  */
 export const instanceOf: {
-  <S extends Type.AnyEntity>(schema: S): (value: unknown) => value is Schema.Schema.Type<S>;
-  <S extends Type.AnyEntity>(schema: S, value: unknown): value is Schema.Schema.Type<S>;
-} = ((...args: [schema: Type.AnyEntity, value: unknown] | [schema: Type.AnyEntity]) => {
+  // Reject `Type.Type` at the type level — those are meta-schema entities, not
+  // object instances. Use `Type.isType(value)` instead.
+  <T extends Type.Type>(
+    type: T,
+    _hint?: never,
+    // eslint-disable-next-line @typescript-eslint/unified-signatures
+    ..._error: ['ERROR: Obj.instanceOf does not accept Type.Type; use Type.isType(value) instead']
+  ): never;
+  // Reject relation types — use `Relation.instanceOf` instead.
+  <R extends Type.AnyRelation>(
+    type: R,
+    _hint?: never,
+    // eslint-disable-next-line @typescript-eslint/unified-signatures
+    ..._error: ['ERROR: Obj.instanceOf does not accept relation types; use Relation.instanceOf instead']
+  ): never;
+  <S extends Type.AnyObj>(schema: S): (value: unknown) => value is Type.InstanceType<S>;
+  <S extends Type.AnyObj>(schema: S, value: unknown): value is Type.InstanceType<S>;
+} = ((...args: [schema: Type.AnyEntity, value?: unknown]) => {
   if (args.length === 1) {
     return (entity: unknown) => internal.isInstanceOf(args[0], entity);
   }
@@ -441,9 +481,9 @@ export const instanceOf: {
  * ```
  */
 export const snapshotOf: {
-  <S extends Type.AnyEntity>(schema: S): (value: unknown) => value is Snapshot<Schema.Schema.Type<S>>;
-  <S extends Type.AnyEntity>(schema: S, value: unknown): value is Snapshot<Schema.Schema.Type<S>>;
-} = ((...args: [schema: Type.AnyEntity, value: unknown] | [schema: Type.AnyEntity]) => {
+  <S extends Type.AnyObj>(schema: S): (value: unknown) => value is Snapshot<Type.InstanceType<S>>;
+  <S extends Type.AnyObj>(schema: S, value: unknown): value is Snapshot<Type.InstanceType<S>>;
+} = ((...args: [schema: Type.AnyObj, value: unknown] | [schema: Type.AnyObj]) => {
   const check = (entity: unknown) =>
     entity != null &&
     typeof entity === 'object' &&
@@ -459,12 +499,14 @@ export const snapshotOf: {
 
 // TODO(dmaretskyi): Allow returning undefined.
 /**
- * Get the DXN of the object.
+ * Get the canonical URI of the object. Returns `URI.URI` (today always an EID,
+ * but future entity kinds may surface other URI schemes — narrow with
+ * `EID.parse(uri)` or `DXN.tryMake(uri)` at the point of use).
  * Accepts both reactive objects and snapshots.
  */
-export const getDXN = (entity: Unknown | Snapshot): DXN => {
+export const getURI = (entity: Unknown | Snapshot): URI.URI => {
   assertArgument(!Schema.isSchema(entity), 'obj', 'Object should not be a schema.');
-  return internal.getDXN(entity);
+  return internal.getUri(entity);
 };
 
 /**
@@ -472,17 +514,22 @@ export const getDXN = (entity: Unknown | Snapshot): DXN => {
  * @example dxn:com.example.type.person:1.0.0
  * @throws If the object is missing its type (corrupted object).
  */
-export const getTypeDXN = (obj: Unknown | Snapshot): DXN => {
-  const type = internal.getTypeDXN(obj);
+export const getTypeURI = (obj: Unknown | Snapshot): URI.URI => {
+  const type = internal.getTypeURI(obj);
   invariant(type != null, 'Corrupted object: missing type.');
   return type;
 };
 
 /**
- * Get the schema of the object.
- * Returns the branded ECHO schema used to create the object.
+ * Get the type entity (`Type.AnyObj`) the object was created from.
+ *
+ * Returns `undefined` when the object's type isn't registered in this runtime
+ * (e.g. a freshly deserialized snapshot whose type entity hasn't been wired
+ * up yet, or an object loaded from storage before its schema is known). To
+ * get the Effect Schema from the returned entity, use `Type.getSchema(...)`.
  */
-export const getSchema: (obj: Unknown | Snapshot) => Type.AnyEntity | undefined = internal.getSchema as any;
+export const getType = (obj: Unknown | Snapshot): Type.AnyObj | undefined =>
+  internal.getType(obj) as Type.AnyObj | undefined;
 
 /**
  * @returns The typename of the object's type.
@@ -514,7 +561,7 @@ export const getDatabase = (entity: Entity.Unknown | Entity.Snapshot): Database.
 export const Meta = internal.MetaId;
 
 /**
- * Deeply read-only version of ObjectMeta.
+ * Deeply read-only version of EntityMeta.
  * Prevents mutation at all nesting levels (e.g., `meta.keys.push()` is a TypeScript error).
  */
 export type ReadonlyMeta = internal.ReadonlyMeta;
@@ -538,9 +585,8 @@ export type Meta = internal.Meta;
  *
  * // Mutable access inside change callback
  * Obj.update(person, (obj) => {
- *   const meta = Obj.getMeta(obj);     // ObjectMeta (mutable)
- *   meta.tags ??= [];
- *   meta.tags.push('important');
+ *   const meta = Obj.getMeta(obj);     // EntityMeta (mutable)
+ *   meta.tags.push(Ref.make(tag));     // tags are refs to Tag objects
  * });
  * ```
  */
@@ -576,7 +622,7 @@ export const deleteKeys = (entity: Mutable<Unknown>, source: string): void => in
  * NOTE: TypeScript's structural typing allows readonly objects to be passed to `Mutable<T>`
  * parameters, so there is no compile-time error. Enforcement is runtime-only.
  */
-export const addTag = (entity: Mutable<Unknown>, tag: string): void => internal.addTag(entity, tag);
+export const addTag = (entity: Mutable<Unknown>, tag: Ref.Ref<Tag.Tag>): void => internal.addTag(entity, tag);
 
 /**
  * Remove a tag from the object.
@@ -585,7 +631,7 @@ export const addTag = (entity: Mutable<Unknown>, tag: string): void => internal.
  * NOTE: TypeScript's structural typing allows readonly objects to be passed to `Mutable<T>`
  * parameters, so there is no compile-time error. Enforcement is runtime-only.
  */
-export const removeTag = (entity: Mutable<Unknown>, tag: string): void => internal.removeTag(entity, tag);
+export const removeTag = (entity: Mutable<Unknown>, tag: Ref.Ref<Tag.Tag>): void => internal.removeTag(entity, tag);
 
 /**
  * Check if the object is deleted.
@@ -601,8 +647,12 @@ export const isDeleted = (entity: Unknown | Snapshot): boolean => objInternal.is
 /**
  * Get the label of the object.
  * Accepts both reactive objects and snapshots.
+ *
+ * @param options.fallback `'typename'` returns the object's typename when no
+ *   label is set (e.g. `org.dxos.type.table`).
  */
-export const getLabel = (entity: Unknown | Snapshot): string | undefined => internal.getLabel(entity);
+export const getLabel = (entity: Unknown | Snapshot, options?: internal.GetLabelOptions): string | undefined =>
+  internal.getLabel(entity, options);
 
 /**
  * Set the label of the object.
@@ -619,6 +669,17 @@ export const setLabel = (entity: Mutable<Unknown>, label: string): void => inter
  */
 export const getDescription = (entity: Unknown | Snapshot): string | undefined => internal.getDescription(entity);
 
+/**
+ * Get the icon annotation for the object (or any entity), resolved via its type-level
+ * `IconAnnotation`. Accepts both reactive entities and snapshots, and either Objects or
+ * Relations — the underlying schema-based lookup works for both.
+ *
+ * Returns the full `{ icon, hue }` annotation; callers wanting just the icon name typically
+ * write `Obj.getIcon(obj)?.icon ?? 'ph--cube--regular'`.
+ */
+export const getIcon = (entity: Entity.Unknown | Entity.Snapshot): internal.IconAnnotation | undefined =>
+  internal.getIcon(entity);
+
 /**
  * Set the description of the object.
  * Must be called within an `Obj.update` callback.
@@ -648,7 +709,7 @@ export const Parent: unique symbol = internal.ParentId as any;
  * @returns The parent object, or undefined if the object has no parent.
  */
 export const getParent = (entity: Unknown | Snapshot): Unknown | undefined => {
-  assertArgument(isObject(entity), 'Expected an object');
+  assertArgument(isObject(entity) || isSnapshot(entity), 'Expected an object');
   assumeType<internal.InternalObjectProps>(entity);
   return entity[internal.ParentId] as Unknown | undefined;
 };
@@ -683,7 +744,7 @@ const valuesEqual = (left: unknown, right: unknown): boolean => {
     return Utils.structuralRegion(() => Equal.equals(left, right));
   }
   if (Ref.isRef(left) && Ref.isRef(right)) {
-    return left.dxn.toString() === right.dxn.toString();
+    return left.uri === right.uri;
   }
   if (Ref.isRef(left) || Ref.isRef(right)) {
     return false;
@@ -807,12 +868,12 @@ export const toJSON = (entity: Unknown | Snapshot): JSON => objInternal.objectTo
  * The function must be async to support resolving the schema as well as the relation endpoints.
  *
  * @param options.refResolver - Resolver for references. Produces hydrated references that can be resolved.
- * @param options.dxn - Override object DXN. Changes the result of `Obj.getDXN`.
+ * @param options.uri - Override object URI. Changes the result of `Obj.getURI`.
  * @param options.database - Database to associate with the object.
  */
 export const fromJSON: (
   json: unknown,
-  options?: { refResolver?: Ref.Resolver; dxn?: DXN; database?: Database.Database; parent?: Unknown },
+  options?: { refResolver?: Ref.Resolver; uri?: URI.URI; database?: Database.Database; parent?: Unknown },
 ) => Promise<Unknown> = objInternal.objectFromJSON as any;
 
 /**