@dxos/echo 0.8.4-main.c85a9c8dae → 0.8.4-main.cb12b3f963

package/src/Relation.ts

@@ -2,6 +2,8 @@
 // Copyright 2025 DXOS.org
 //
 
+// @import-as-namespace
+
 import * as Schema from 'effect/Schema';
 
 import { raise } from '@dxos/debug';
@@ -14,6 +16,7 @@ import { assumeType } from '@dxos/util';
 import type * as Database from './Database';
 import * as Entity from './Entity';
 import * as internal from './internal';
+import * as entityInternal from './internal/Entity';
 import * as Obj from './Obj';
 import type * as Type from './Type';
 
@@ -64,7 +67,7 @@ export const Unknown: Type.Relation<Unknown, Obj.Any, Obj.Any> = Schema.Struct({
   // NOTE: The EchoRelationSchema annotation is required for Ref.Ref(Relation.Unknown) to work.
   //   The typename/version/source/target only satisfy ECHO schema machinery for reference targets.
   internal.EchoRelationSchema({
-    typename: 'dxos.org/schema/AnyRelation',
+    typename: 'org.dxos.schema.anyRelation',
     version: '0.0.0',
     source: Obj.Unknown,
     target: Obj.Unknown,
@@ -107,10 +110,10 @@ export interface BaseRelationJson {
 export type Snapshot<T extends Unknown = Unknown> = Omit<T, Entity.KindId> &
   BaseRelationSnapshot<Obj.Unknown, Obj.Unknown>;
 
-export const Source: unique symbol = internal.RelationSourceId as any;
+export const Source: unique symbol = entityInternal.RelationSourceId as any;
 export type Source = typeof Source;
 
-export const Target: unique symbol = internal.RelationTargetId as any;
+export const Target: unique symbol = entityInternal.RelationTargetId as any;
 export type Target = typeof Target;
 
 /**
@@ -234,7 +237,9 @@ export const getSource = <T extends Unknown | Snapshot>(relation: T): SourceOf<T
   assertArgument(isRelation(relation), 'Expected a relation');
   assumeType<internal.InternalObjectProps>(relation);
   const obj = (relation as internal.InternalObjectProps)[internal.RelationSourceId];
-  invariant(obj !== undefined, `Invalid source: ${relation.id}`);
+  if (obj === undefined) {
+    throw new Error(`Relation source could not be resolved.`);
+  }
   return obj as SourceOf<T>;
 };
 
@@ -247,7 +252,9 @@ export const getTarget = <T extends Unknown | Snapshot>(relation: T): TargetOf<T
   assertArgument(isRelation(relation), 'Expected a relation');
   assumeType<internal.InternalObjectProps>(relation);
   const obj = (relation as internal.InternalObjectProps)[internal.RelationTargetId];
-  invariant(obj !== undefined, `Invalid target: ${relation.id}`);
+  if (obj === undefined) {
+    throw new Error(`Relation target could not be resolved.`);
+  }
   return obj as TargetOf<T>;
 };
 
@@ -257,7 +264,7 @@ export const getTarget = <T extends Unknown | Snapshot>(relation: T): TargetOf<T
 
 /**
  * Makes all properties mutable recursively.
- * Used to provide a mutable view of a relation within `Relation.change`.
+ * Used to provide a mutable view of a relation within `Relation.update`.
  */
 export type Mutable<T> = internal.Mutable<T>;
 
@@ -265,10 +272,10 @@ export type Mutable<T> = internal.Mutable<T>;
  * Perform mutations on an echo relation within a controlled context.
  *
  * All mutations within the callback are batched and trigger a single notification
- * when the callback completes. Direct mutations outside of `Relation.change` will throw
+ * when the callback completes. Direct mutations outside of `Relation.update` will throw
  * an error for echo relations.
  *
- * @param relation - The echo relation to mutate. Use `Obj.change` for objects.
+ * @param relation - The echo relation to mutate. Use `Obj.update` for objects.
  * @param callback - The callback that performs mutations on the relation.
  *
  * @example
@@ -279,15 +286,15 @@ export type Mutable<T> = internal.Mutable<T>;
  *   role: 'Engineer',
  * });
  *
- * // Mutate within Relation.change
- * Relation.change(worksFor, (r) => {
- *   r.role = 'Senior Engineer';
+ * // Mutate within Relation.update
+ * Relation.update(worksFor, (obj) => {
+ *   obj.role = 'Senior Engineer';
  * });
  * ```
  *
- * Note: Only accepts relations. Use `Obj.change` for objects.
+ * Note: Only accepts relations. Use `Obj.update` for objects.
  */
-export const change = <T extends Unknown>(relation: T, callback: internal.ChangeCallback<T>): void => {
+export const update = <T extends Unknown>(relation: T, callback: internal.ChangeCallback<T>): void => {
   internal.change(relation, callback);
 };
 
@@ -330,7 +337,7 @@ export const getValue = (rel: Unknown | Snapshot, path: readonly (string | numbe
 
 /**
  * Set a deeply nested property on a relation.
- * Must be called within a `Relation.change` callback.
+ * Must be called within a `Relation.update` callback.
  *
  * 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.
@@ -392,13 +399,13 @@ export const Meta = internal.MetaId;
 export type ReadonlyMeta = internal.ReadonlyMeta;
 
 /**
- * Mutable meta type returned by `Relation.getMeta` inside a `Relation.change` callback.
+ * Mutable meta type returned by `Relation.getMeta` inside a `Relation.update` callback.
  */
 export type Meta = internal.Meta;
 
 /**
  * Get the metadata for a relation.
- * Returns mutable meta when passed a mutable relation (inside `Relation.change` callback).
+ * Returns mutable meta when passed a mutable relation (inside `Relation.update` callback).
  * Returns read-only meta when passed a regular relation or snapshot.
  */
 // TODO(wittjosiah): When passed a Snapshot, should return a snapshot of meta, not the live meta proxy.
@@ -416,7 +423,7 @@ export const getKeys = (entity: Unknown | Snapshot, source: string): ForeignKey[
 
 /**
  * Delete all keys from the relation for the specified source.
- * Must be called within a `Relation.change` callback.
+ * Must be called within a `Relation.update` callback.
  *
  * 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.
@@ -425,7 +432,7 @@ export const deleteKeys = (entity: Mutable<Unknown>, source: string): void => in
 
 /**
  * Add a tag to the relation.
- * Must be called within a `Relation.change` callback.
+ * Must be called within a `Relation.update` callback.
  *
  * 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.
@@ -434,7 +441,7 @@ export const addTag = (entity: Mutable<Unknown>, tag: string): void => internal.
 
 /**
  * Remove a tag from the relation.
- * Must be called within a `Relation.change` callback.
+ * Must be called within a `Relation.update` callback.
  *
  * 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.
@@ -459,7 +466,7 @@ export const getLabel = (entity: Unknown | Snapshot): string | undefined => inte
 
 /**
  * Set the label of the relation.
- * Must be called within a `Relation.change` callback.
+ * Must be called within a `Relation.update` callback.
  *
  * 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.
@@ -474,7 +481,7 @@ export const getDescription = (entity: Unknown | Snapshot): string | undefined =
 
 /**
  * Set the description of the relation.
- * Must be called within a `Relation.change` callback.
+ * Must be called within a `Relation.update` callback.
  *
  * 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.

package/src/SchemaRegistry.ts

@@ -47,7 +47,7 @@ export type Query = {
    * @default false
    *
    * The system schema include but are not limited to:
-   *  - dxos.org/type/Schema
+   *  - org.dxos.type.schema
    */
   includeSystem?: boolean;
 };

package/src/Tag.ts

@@ -2,6 +2,8 @@
 // Copyright 2025 DXOS.org
 //
 
+// @import-as-namespace
+
 import * as Schema from 'effect/Schema';
 
 import * as internal from './internal';
@@ -13,7 +15,7 @@ export const Tag = Schema.Struct({
   hue: Schema.optional(Schema.String), // TODO(burdon): Color name?
 }).pipe(
   Type.object({
-    typename: 'dxos.org/type/Tag',
+    typename: 'org.dxos.type.tag',
     version: '0.1.0',
   }),
   internal.LabelAnnotation.set(['label']),

package/src/Type.ts

@@ -2,6 +2,8 @@
 // Copyright 2025 DXOS.org
 //
 
+// @import-as-namespace
+
 import type * as Schema from 'effect/Schema';
 
 import { type EncodedReference } from '@dxos/echo-protocol';
@@ -9,20 +11,21 @@ import { invariant } from '@dxos/invariant';
 import { type DXN } from '@dxos/keys';
 import { type ToMutable } from '@dxos/util';
 
-import type * as EntityModule from './Entity';
+import type * as Entity from './Entity';
 import * as internal from './internal';
+import * as typeInternal from './internal/Type';
 import type * as ObjModule from './Obj';
 import type * as RelationModule from './Relation';
 
 /**
  * Dynamic type that can be constructed, mutated, and persisted in the ECHO database.
  */
-export const RuntimeType = internal.EchoSchema;
+export const RuntimeType = typeInternal.EchoSchema;
 
 /**
  * Dynamic type that can be constructed, mutated, and persisted in the ECHO database.
  */
-export type RuntimeType = internal.EchoSchema;
+export type RuntimeType = typeInternal.EchoSchema;
 
 //
 // Internal types (not exported)
@@ -61,7 +64,7 @@ export interface Obj<T, Fields extends Schema.Struct.Fields = Schema.Struct.Fiel
     EchoSchemaKind<internal.EntityKind.Object>,
     Schema.AnnotableClass<
       Obj<T, Fields>,
-      EntityModule.OfKind<typeof EntityModule.Kind.Object> & T,
+      Entity.OfKind<typeof Entity.Kind.Object> & T,
       Schema.Simplify<ObjModule.BaseObjJson & ToMutable<T>>,
       never
     > {
@@ -97,7 +100,7 @@ export type AnyObj = ObjectSchemaBase;
  * ```ts
  * const Person = Schema.Struct({
  *   name: Schema.String,
- * }).pipe(Type.object({ typename: 'example.com/type/Person', version: '0.1.0' }));
+ * }).pipe(Type.object({ typename: 'com.example.type.person', version: '0.1.0' }));
  * ```
  */
 export const object: {
@@ -108,7 +111,7 @@ export const object: {
 // PersistentType (Schema stored in database)
 //
 
-export const PersistentType: Obj<internal.PersistentSchema> = internal.PersistentSchema as any;
+export const PersistentType: Obj<typeInternal.PersistentSchema> = typeInternal.PersistentSchema as any;
 
 export interface PersistentType extends Schema.Schema.Type<typeof PersistentType> {}
 
@@ -124,7 +127,7 @@ export interface Relation<T, Source, Target, Fields extends Schema.Struct.Fields
     EchoSchemaKind<internal.EntityKind.Relation>,
     Schema.AnnotableClass<
       Relation<T, Source, Target, Fields>,
-      EntityModule.OfKind<typeof EntityModule.Kind.Relation> & RelationModule.Endpoints<Source, Target> & T,
+      Entity.OfKind<typeof Entity.Kind.Relation> & RelationModule.Endpoints<Source, Target> & T,
       Schema.Simplify<RelationModule.BaseRelationJson & ToMutable<T>>,
       never
     > {
@@ -161,7 +164,7 @@ export type AnyRelation = RelationSchemaBase;
  * const WorksFor = Schema.Struct({
  *   role: Schema.String,
  * }).pipe(Type.relation({
- *   typename: 'example.com/type/WorksFor',
+ *   typename: 'com.example.type.works-for',
  *   version: '0.1.0',
  *   source: Person,
  *   target: Company,
@@ -211,7 +214,7 @@ export type AnyRef = Schema.Schema<internal.Ref<any>, EncodedReference>;
 /**
  * Gets the full DXN of the schema.
  * Will include the version if it's a `type` DXN.
- * @example "dxn:example.com/type/Person:0.1.0"
+ * @example "dxn:com.example.type.person:0.1.0"
  * @example "dxn:echo:SSSSSSSSSS:XXXXXXXXXXXXX"
  */
 export const getDXN = (schema: AnyEntity): DXN | undefined => {
@@ -220,7 +223,7 @@ export const getDXN = (schema: AnyEntity): DXN | undefined => {
 
 /**
  * @param schema - Schema to get the typename from.
- * @returns The typename of the schema. Example: `example.com/type/Person`.
+ * @returns The typename of the schema. Example: `com.example.type.person`.
  */
 export const getTypename = (schema: AnyEntity): string => {
   const typename = internal.getSchemaTypename(schema);
@@ -241,7 +244,7 @@ export const getVersion = (schema: AnyEntity): string => {
 /**
  * @returns True if the schema is mutable.
  */
-export const isMutable = internal.isMutable;
+export const isMutable = typeInternal.isMutable;
 
 /**
  * ECHO type metadata.

package/src/View.ts

@@ -2,12 +2,15 @@
 // Copyright 2025 DXOS.org
 //
 
+// @import-as-namespace
+
 import * as Schema from 'effect/Schema';
 
 import { QueryAST } from '@dxos/echo-protocol';
 import { JsonPath } from '@dxos/effect';
 import { PublicKey } from '@dxos/keys';
 
+import * as Annotation from './Annotation';
 import * as Filter from './Filter';
 import * as internal from './internal';
 import * as Obj from './Obj';
@@ -73,10 +76,14 @@ const ViewSchema = Schema.Struct({
   projection: Projection,
 }).pipe(
   Type.object({
-    typename: 'dxos.org/type/View',
-    version: '0.5.0',
+    typename: 'org.dxos.type.view',
+    version: '0.1.0',
   }),
   internal.SystemTypeAnnotation.set(true),
+  Annotation.IconAnnotation.set({
+    icon: 'ph--funnel--regular',
+    hue: 'green',
+  }),
 );
 
 export interface View extends Schema.Schema.Type<typeof ViewSchema> {}

package/src/exemplars.test.ts

@@ -0,0 +1,21 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import * as Obj from './Obj';
+import { TestSchema } from './testing';
+import type * as Type from './Type';
+
+describe('Exemplars', () => {
+  test('factory', ({ expect }) => {
+    const factory = <S extends Type.AnyObj>(schema: S) => {
+      return (props: Obj.MakeProps<S>) => Obj.make(schema, props);
+    };
+
+    const makePerson = factory(TestSchema.Person);
+    const person = makePerson({ name: 'John Doe' });
+    expect(person.name).toBe('John Doe');
+  });
+});

package/src/index.ts

@@ -9,13 +9,16 @@ export { DXN } from '@dxos/keys';
 export * as Annotation from './Annotation';
 export * as Database from './Database';
 export * as Entity from './Entity';
+// TODO(burdon): Rename to Error (less problematic than Obj/Object).
 export * as Err from './Err';
 export * as Feed from './Feed';
 export * as Filter from './Filter';
 export * as Format from './Format';
 export * as Hypergraph from './Hypergraph';
+export * as Json from './Json';
 export * as JsonSchema from './JsonSchema';
 export * as Key from './Key';
+export * as Migration from './Migration';
 export * as Obj from './Obj';
 export * as Order from './Order';
 export * as Query from './Query';
@@ -28,3 +31,4 @@ export * as Type from './Type';
 export * as Collection from './Collection';
 export * as View from './View';
 export * as Dataset from './Dataset';
+export * as Extension from './Extension';

package/src/internal/{annotations → Annotation}/annotations.test.ts

@@ -5,8 +5,7 @@
 import * as Schema from 'effect/Schema';
 import { describe, test } from 'vitest';
 
-import { EchoObjectSchema } from '../entities';
-
+import { EchoObjectSchema } from '../Entity';
 import { LabelAnnotation, TypenameSchema, VersionSchema, getLabelWithSchema } from './annotations';
 
 // TODO(dmaretskyi): Use one of the testing schemas.
@@ -20,7 +19,7 @@ type TestObject = Schema.Schema.Type<typeof TestObject>;
 
 const TestEchoSchema = TestObject.pipe(
   EchoObjectSchema({
-    typename: 'dxos.org/type/Test',
+    typename: 'org.dxos.type.test',
     version: '0.1.0',
   }),
 );
@@ -30,10 +29,10 @@ type TestEchoSchema = Schema.Schema.Type<typeof TestEchoSchema>;
 describe('annotations', () => {
   describe('Typename', () => {
     test('should validate typename', ({ expect }) => {
-      // Valid.
-      expect(TypenameSchema.make('dxos.org/type/foo')).to.exist;
-      expect(TypenameSchema.make('dxos.org/type/foo-bar')).to.exist;
-      expect(TypenameSchema.make('dxos.org/type/foo_bar')).to.exist;
+      // Valid (reverse-DNS format).
+      expect(TypenameSchema.make('org.dxos.type.foo')).to.exist;
+      expect(TypenameSchema.make('org.dxos.type.fooBar')).to.exist;
+      expect(TypenameSchema.make('org.dxos.type.foobar')).to.exist;
 
       // Invalid.
       expect(() => TypenameSchema.make('dxn:dxos.org')).to.throw();
@@ -82,6 +81,56 @@ describe('annotations', () => {
       expect(getLabelWithSchema(TestObject, obj)).toBeUndefined();
     });
 
+    test('should skip empty string and fallback to next path', ({ expect }) => {
+      const obj: TestObject = {
+        name: '',
+        fallbackName: 'Fallback Name',
+        other: 'Other',
+      };
+
+      expect(getLabelWithSchema(TestObject, obj)).toEqual('Fallback Name');
+    });
+
+    test('should skip whitespace-only string and fallback to next path', ({ expect }) => {
+      const obj: TestObject = {
+        name: '   ',
+        fallbackName: 'Fallback Name',
+        other: 'Other',
+      };
+
+      expect(getLabelWithSchema(TestObject, obj)).toEqual('Fallback Name');
+    });
+
+    test('should return undefined if all paths are empty strings', ({ expect }) => {
+      const obj: TestObject = {
+        name: '',
+        fallbackName: '',
+        other: 'Other',
+      };
+
+      expect(getLabelWithSchema(TestObject, obj)).toBeUndefined();
+    });
+
+    test('should return undefined if all paths are whitespace-only', ({ expect }) => {
+      const obj: TestObject = {
+        name: '  ',
+        fallbackName: '\t\n',
+        other: 'Other',
+      };
+
+      expect(getLabelWithSchema(TestObject, obj)).toBeUndefined();
+    });
+
+    test('should preserve original string with leading/trailing whitespace when valid', ({ expect }) => {
+      const obj: TestObject = {
+        name: '  Valid Name  ',
+        fallbackName: 'Fallback Name',
+        other: 'Other',
+      };
+
+      expect(getLabelWithSchema(TestObject, obj)).toEqual('  Valid Name  ');
+    });
+
     test('should return label from echo object', ({ expect }) => {
       const obj: TestEchoSchema = {
         id: 'test',

package/src/internal/{annotations → Annotation}/annotations.ts

@@ -13,8 +13,8 @@ import { assertArgument, invariant } from '@dxos/invariant';
 import { DXN } from '@dxos/keys';
 import { type Primitive } from '@dxos/util';
 
-import { type AnyProperties, EntityKind, TypeId, getSchema } from '../types';
-
+import { type Mutable } from '../common/proxy';
+import { type AnyProperties, EntityKind, TypeId, getSchema } from '../common/types';
 import { type AnnotationHelper, createAnnotationHelper } from './util';
 
 /**
@@ -87,16 +87,17 @@ export const getTypeDXNFromSpecifier = (input: Schema.Schema.All | string): DXN
 
 /**
  * Fully qualified globally unique typename.
- * Example: `dxos.org/type/Message`
- */
-// TODO(burdon): Reconcile with short DXN format.
-// TODO(burdon): Change "/type" => "/schema" throughout.
-export const TypenameSchema = Schema.String.pipe(Schema.pattern(/^[a-zA-Z]\w+\.[a-zA-Z]\w{1,}\/[\w/_-]+$/)).annotations(
-  {
-    description: 'Fully qualified globally unique typename',
-    example: 'dxos.org/type/Message',
-  },
-);
+ * Example: `org.dxos.type.message`
+ */
+// TODO(wittjosiah): Factor out to DXN spec.
+export const TypenameSchema = Schema.String.pipe(
+  Schema.pattern(
+    /^[a-zA-Z]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(\.[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)+(\.[a-zA-Z]([a-zA-Z0-9]{0,62})?)$/,
+  ),
+).annotations({
+  description: 'Fully qualified globally unique typename in reverse-DNS form.',
+  example: 'org.dxos.type.message',
+});
 
 /**
  * Semantic version format: `major.minor.patch`
@@ -175,7 +176,7 @@ export const getSchemaVersion = (schema: Schema.Schema.All): string | undefined
 /**
  * Gets the typename of the object without the version.
  * Returns only the name portion, not the DXN.
- * @example "example.org/type/Contact"
+ * @example "org.example.type.contact"
  *
  * @internal (use Obj.getTypename)
  */
@@ -207,7 +208,7 @@ export const setTypename = (obj: any, typename: DXN): void => {
 /**
  * @returns Object type as {@link DXN}.
  * @returns undefined if the object doesn't have a type.
- * @example `dxn:example.com/type/Person:1.0.0`
+ * @example `dxn:com.example.type.person:1.0.0`
  *
  * @internal (use Obj.getTypeDXN)
  */
@@ -337,6 +338,7 @@ export const LabelAnnotation = createAnnotationHelper<string[]>(LabelAnnotationI
 /**
  * Returns the label for a given object based on {@link LabelAnnotationId}.
  * Lower-level version that requires explicit schema parameter.
+ * Skips empty strings and whitespace-only strings, continuing to the next field.
  */
 // TODO(burdon): Convert to JsonPath?
 export const getLabelWithSchema = <S extends Schema.Schema.Any>(
@@ -352,7 +354,13 @@ export const getLabelWithSchema = <S extends Schema.Schema.Any>(
     );
     const value = getField(object, accessor as JsonPath);
     switch (typeof value) {
-      case 'string':
+      case 'string': {
+        const trimmed = value.trim();
+        if (trimmed.length > 0) {
+          return value;
+        }
+        continue;
+      }
       case 'number':
       case 'boolean':
       case 'bigint':
@@ -435,7 +443,6 @@ export const setDescriptionWithSchema = <S extends Schema.Schema.Any>(
  * Identifies if a property should be included in a form or not.
  * By default, all properties are included in forms, so this is opt-out.
  */
-// TODO(burdon): UI concern.
 export const FormInputAnnotationId = Symbol.for('@dxos/schema/annotation/FormInput');
 export const FormInputAnnotation = createAnnotationHelper<boolean>(FormInputAnnotationId);
 
@@ -467,14 +474,14 @@ interface MakeAnnoationsProps<T> {
 // TODO(wittjosiah): Comment.
 export const makeUserAnnotation = <T>(props: MakeAnnoationsProps<T>): AnnotationHelper<T> => {
   assertArgument(
-    /[a-zA-Z0-9]+\.[a-zA-Z.]+\/[a-zA-Z/]+/.test(props.id),
+    /^[a-z][a-z0-9]*(\.[a-z][a-z0-9-]*){2,}$/.test(props.id),
     'id',
-    'Annotation id must be in the FQN format (dxos.org/annotation/Example).',
+    'Annotation id must be in the FQN format (org.dxos.annotation.example).',
   );
 
   const getFromAst = (ast: SchemaAST.AST) =>
     SchemaAST.getAnnotation<PropertyMetaAnnotation>(PropertyMetaAnnotationId)(ast).pipe(
-      Option.map((meta) => meta[props.id] as unknown),
+      Option.flatMap((meta) => Option.fromNullable(meta[props.id])),
       Option.map(Schema.decodeUnknownSync(props.schema)),
     );
 
@@ -521,6 +528,50 @@ export interface IconAnnotation extends Schema.Schema.Type<typeof IconAnnotation
  * Icon to render in the UI.
  */
 export const IconAnnotation = makeUserAnnotation<IconAnnotation>({
-  id: 'dxos.org/annotation/Icon',
+  id: 'org.dxos.annotation.icon',
   schema: IconAnnotationSchema,
 });
+
+/**
+ * Get the label of an entity.
+ * Accepts both reactive entities and snapshots.
+ */
+export const getLabel = (entity: AnyProperties): string | undefined => {
+  const schema = getSchema(entity);
+  if (schema != null) {
+    return getLabelWithSchema(schema, entity);
+  }
+};
+
+/**
+ * Set the label of an entity.
+ * Must be called within an Obj.update or Relation.update callback.
+ */
+export const setLabel = (entity: Mutable<AnyProperties>, label: string) => {
+  const schema = getSchema(entity);
+  if (schema != null) {
+    setLabelWithSchema(schema, entity, label);
+  }
+};
+
+/**
+ * Get the description of an entity.
+ * Accepts both reactive entities and snapshots.
+ */
+export const getDescription = (entity: AnyProperties): string | undefined => {
+  const schema = getSchema(entity);
+  if (schema != null) {
+    return getDescriptionWithSchema(schema, entity);
+  }
+};
+
+/**
+ * Set the description of an entity.
+ * Must be called within an Obj.update or Relation.update callback.
+ */
+export const setDescription = (entity: Mutable<AnyProperties>, description: string) => {
+  const schema = getSchema(entity);
+  if (schema != null) {
+    setDescriptionWithSchema(schema, entity, description);
+  }
+};

package/src/internal/{annotations → Annotation}/index.ts

@@ -3,4 +3,5 @@
 //
 
 export * from './annotations';
+export * from './sorting';
 export * from './util';

package/src/internal/{api → Annotation}/sorting.ts

@@ -2,10 +2,8 @@
 // Copyright 2025 DXOS.org
 //
 
-import { getTypename } from '../annotations';
-import type { AnyEntity } from '../types';
-
-import { getLabel } from './annotations';
+import type { AnyEntity } from '../common/types';
+import { getLabel, getTypename } from './annotations';
 
 /**
  * String comparison helper for sorting.

package/src/internal/{annotations → Annotation}/util.ts

@@ -9,7 +9,7 @@ import * as SchemaAST from 'effect/SchemaAST';
 import { assertArgument } from '@dxos/invariant';
 import { DXN } from '@dxos/keys';
 
-import { EntityKind } from '../types';
+import { EntityKind } from '../common/types';
 
 export interface AnnotationHelper<T> {
   /**

package/src/internal/{api/entity.ts → Entity/api.ts}

@@ -6,8 +6,9 @@ import { invariant } from '@dxos/invariant';
 import { type DXN } from '@dxos/keys';
 import { assumeType } from '@dxos/util';
 
-import { type InternalObjectProps, ObjectDatabaseId, getObjectDXN } from '../entities';
-import type { AnyEntity } from '../types';
+import type { AnyEntity } from '../common/types';
+import { type InternalObjectProps, ObjectDatabaseId } from './model';
+import { getObjectDXN } from './util';
 
 /**
  * Get the DXN of an entity.