@dxos/echo 0.8.4-staging.ac66bdf99f → 0.9.0

package/src/View.ts

@@ -7,8 +7,8 @@
 import * as Schema from 'effect/Schema';
 
 import { QueryAST } from '@dxos/echo-protocol';
-import { JsonPath } from '@dxos/effect';
-import { PublicKey } from '@dxos/keys';
+import { SchemaEx } from '@dxos/effect';
+import { DXN, PublicKey } from '@dxos/keys';
 
 import * as Annotation from './Annotation';
 import * as Filter from './Filter';
@@ -22,11 +22,11 @@ import * as Type from './Type';
  */
 export const FieldSchema = Schema.Struct({
   id: Schema.String,
-  path: JsonPath,
+  path: SchemaEx.JsonPath,
   visible: Schema.optional(Schema.Boolean),
 
   // TODO(wittjosiah): Presentation-specific?
-  referencePath: Schema.optional(JsonPath),
+  referencePath: Schema.optional(SchemaEx.JsonPath),
 });
 
 export type FieldType = Schema.Schema.Type<typeof FieldSchema>;
@@ -44,7 +44,7 @@ export const Projection = Schema.Struct({
   /**
    * UX metadata associated with displayed fields (in table, form, etc.)
    */
-  // TODO(wittjosiah): Should this just be an array of JsonPath?
+  // TODO(wittjosiah): Should this just be an array of SchemaEx.JsonPath?
   fields: Schema.Array(FieldSchema),
 
   /**
@@ -75,27 +75,18 @@ const ViewSchema = Schema.Struct({
    */
   projection: Projection,
 }).pipe(
-  Type.object({
-    typename: 'org.dxos.type.view',
-    version: '0.1.0',
-  }),
-  internal.SystemTypeAnnotation.set(true),
-  Annotation.IconAnnotation.set({
-    icon: 'ph--funnel--regular',
-    hue: 'green',
-  }),
+  internal.HiddenAnnotation.set(true),
+  Annotation.IconAnnotation.set({ icon: 'ph--funnel--regular', hue: 'green' }),
+  Type.makeObject(DXN.make('org.dxos.type.view', '0.1.0')),
 );
 
-export interface View extends Schema.Schema.Type<typeof ViewSchema> {}
-
-/**
- * View instance type.
- */
-// NOTE: This interface is explicitly defined rather than derived from the schema to avoid
-//   TypeScript "cannot be named" portability errors. The schema contains QueryAST.Query which
-//   references internal @dxos/echo-protocol module paths. Without this explicit interface,
-//   any schema using Ref.Ref(View) would inherit the non-portable type and fail to compile.
+// NOTE: Declared as a named interface and the `View` const is annotated `Type.Obj<View>` so
+//   downstream consumers see a named `View` type instead of the inlined `QueryAST.Query` union.
+//   Without the named interface, embedding `Type.getSchema(View.View)` in a downstream
+//   `Schema.Struct` triggers TS2742 portability errors (e.g. plugin-kanban, plugin-table).
 // TODO(wittjosiah): Find a better solution that doesn't require manually keeping the interface in sync.
+export interface View extends Type.InstanceType<typeof ViewSchema> {}
+
 export const View: Type.Obj<View> = ViewSchema as any;
 
 export const make = (props: Partial<Obj.MakeProps<typeof View>>): View => {

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

@@ -3,8 +3,7 @@
 //
 
 export { QueryAST } from '@dxos/echo-protocol';
-// TODO(wittjosiah): Refactor DXN to not use statics similar to Query.
-export { DXN } from '@dxos/keys';
+export { DXN, EID, URI } from '@dxos/keys';
 
 export * as Annotation from './Annotation';
 export * as Database from './Database';
@@ -15,6 +14,7 @@ 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';
@@ -23,11 +23,11 @@ export * as Order from './Order';
 export * as Query from './Query';
 export * as QueryResult from './QueryResult';
 export * as Ref from './Ref';
+export * as Registry from './Registry';
 export * as Relation from './Relation';
-export * as SchemaRegistry from './SchemaRegistry';
+export * as Scope from './Scope';
 export * as Tag from './Tag';
 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/Annotation/annotations.test.ts

@@ -5,8 +5,13 @@
 import * as Schema from 'effect/Schema';
 import { describe, test } from 'vitest';
 
+import { DXN } from '@dxos/keys';
+
+import { createEchoSchema } from '../../testing';
+import * as Type from '../../Type';
+import { EntityKind } from '../common/types';
 import { EchoObjectSchema } from '../Entity';
-import { LabelAnnotation, TypenameSchema, VersionSchema, getLabelWithSchema } from './annotations';
+import { LabelAnnotation, TypenameSchema, VersionSchema, getLabelWithSchema, getTypeAnnotation } from './annotations';
 
 // TODO(dmaretskyi): Use one of the testing schemas.
 const TestObject = Schema.Struct({
@@ -17,14 +22,9 @@ const TestObject = Schema.Struct({
 
 type TestObject = Schema.Schema.Type<typeof TestObject>;
 
-const TestEchoSchema = TestObject.pipe(
-  EchoObjectSchema({
-    typename: 'org.dxos.type.test',
-    version: '0.1.0',
-  }),
-);
+const TestEchoSchema = TestObject.pipe(EchoObjectSchema(DXN.make('org.dxos.type.test', '0.1.0')));
 
-type TestEchoSchema = Schema.Schema.Type<typeof TestEchoSchema>;
+type TestEchoSchema = Type.InstanceType<typeof TestEchoSchema>;
 
 describe('annotations', () => {
   describe('Typename', () => {
@@ -132,14 +132,34 @@ describe('annotations', () => {
     });
 
     test('should return label from echo object', ({ expect }) => {
-      const obj: TestEchoSchema = {
+      const obj = {
         id: 'test',
         name: 'Primary Name',
         fallbackName: 'Fallback Name',
         other: 'Other',
-      };
+      } as unknown as TestEchoSchema;
+
+      expect(getLabelWithSchema(Type.getSchema(TestEchoSchema), obj)).toEqual('Primary Name');
+    });
+  });
+
+  // `getTypeAnnotation` reads annotations from an Effect Schema. To read off a
+  // `Type.Type` entity (static or persisted), unwrap with `Type.getSchema(entity)`
+  // first — that handles both the static `StaticTypeSchemaSlot` case and the
+  // persisted `jsonSchema` rebuild case.
+  describe('getTypeAnnotation via Type.getSchema(entity)', () => {
+    test('returns TypeAnnotation for a static Type.Obj entity', ({ expect }) => {
+      const annotation = getTypeAnnotation(Type.getSchema(TestEchoSchema));
+      expect(annotation).toBeDefined();
+      expect(annotation?.kind).toBe(EntityKind.Object);
+      expect(annotation?.typename).toBe('org.dxos.type.test');
+    });
 
-      expect(getLabelWithSchema(TestEchoSchema, obj)).toEqual('Primary Name');
+    test('returns TypeAnnotation for a persisted Type.Type entity', ({ expect }) => {
+      const persisted = createEchoSchema(Type.getSchema(TestEchoSchema));
+      const annotation = getTypeAnnotation(Type.getSchema(persisted));
+      expect(annotation).toBeDefined();
+      expect(annotation?.typename).toBe('org.dxos.type.test');
     });
   });
 });

package/src/internal/Annotation/annotations.ts

@@ -7,15 +7,17 @@ import * as Option from 'effect/Option';
 import * as Schema from 'effect/Schema';
 import * as SchemaAST from 'effect/SchemaAST';
 
-import { raise } from '@dxos/debug';
-import { type JsonPath, getField } from '@dxos/effect';
+import { SchemaEx } from '@dxos/effect';
 import { assertArgument, invariant } from '@dxos/invariant';
-import { DXN } from '@dxos/keys';
+import { DXN, URI } from '@dxos/keys';
 import { type Primitive } from '@dxos/util';
 
+import type * as Annotation from '../../Annotation';
 import { type Mutable } from '../common/proxy';
 import { type AnyProperties, EntityKind, TypeId, getSchema } from '../common/types';
-import { type AnnotationHelper, createAnnotationHelper } from './util';
+import { createAnnotationHelper } from './util';
+
+const ANNOTATION_TYPE_ID: Annotation.TypeId = '~@dxos/echo/Annotation' as const;
 
 /**
  * @internal
@@ -35,7 +37,7 @@ export const FieldPath = (path: string) => PropertyMeta(FIELD_PATH_ANNOTATION, p
 
 /**
  * ECHO identifier (for a stored schema).
- * Must be a `dxn:echo:` URI.
+ * Must be an `echo:` URI.
  */
 export const TypeIdentifierAnnotationId = Symbol.for('@dxos/schema/annotation/TypeIdentifier');
 
@@ -46,39 +48,27 @@ export const getTypeIdentifierAnnotation = (schema: Schema.Schema.All) =>
   )(schema.ast);
 
 /**
- * @returns DXN of the schema.
+ * @returns The schema's type identifier URI — whichever URI fits.
+ *
+ * - Stored (dynamic) schemas: the schema-as-object's EID, so loaded objects ride
+ *   along with their schema as a strong dependency.
+ * - Non-stored (static) schemas: the typename DXN built from `TypeAnnotation`.
  *
- * For non-stored schema returns `dxn:type:`.
- * For stored schema returns `dxn:echo:`.
+ * This URI is what gets written to an object's `system.type`; queries that filter by
+ * type also use it (see `Filter.type` / `getTypeURIFromSpecifier`), so both sides
+ * stay symmetric without per-schema branching.
  */
-export const getSchemaDXN = (schema: Schema.Schema.All): DXN | undefined => {
+export const getSchemaURI = (schema: Schema.Schema.All): URI.URI | undefined => {
   assertArgument(Schema.isSchema(schema), 'schema', 'invalid schema');
   const id = getTypeIdentifierAnnotation(schema);
   if (id) {
-    return DXN.parse(id);
+    return URI.make(id);
   }
-
-  // TODO(dmaretskyi): Add support for dynamic schema.
   const objectAnnotation = getTypeAnnotation(schema);
-  if (!objectAnnotation) {
-    return undefined;
-  }
-
-  return DXN.fromTypenameAndVersion(objectAnnotation.typename, objectAnnotation.version);
-};
-
-/**
- * @param input schema or a typename string.
- * @return type DXN.
- */
-export const getTypeDXNFromSpecifier = (input: Schema.Schema.All | string): DXN => {
-  if (Schema.isSchema(input)) {
-    return getSchemaDXN(input) ?? raise(new TypeError('Schema has no DXN'));
-  } else {
-    assertArgument(typeof input === 'string', 'input');
-    assertArgument(!input.startsWith('dxn:'), 'input');
-    return DXN.fromTypename(input);
+  if (objectAnnotation) {
+    return DXN.make(objectAnnotation.typename, objectAnnotation.version);
   }
+  return undefined;
 };
 
 //
@@ -186,8 +176,15 @@ export const getTypename = (obj: AnyProperties): string | undefined => {
     // Try to extract typename from DXN.
     return getSchemaTypename(schema);
   } else {
-    const type = getTypeDXN(obj);
-    return type?.asTypeDXN()?.type;
+    // `obj` may be an arbitrary value (e.g. from `isInstanceOf`); read TypeId
+    // directly so we return undefined for non-entities instead of throwing.
+    const type = (obj as any)?.[TypeId];
+    // Parse the URI string to extract typename.
+    if (DXN.isDXN(type)) {
+      const parsed = DXN.tryMake(type);
+      return parsed && DXN.getName(parsed);
+    }
+    return undefined;
   }
 };
 
@@ -195,8 +192,8 @@ export const getTypename = (obj: AnyProperties): string | undefined => {
  * @internal (use Type.setTypename)
  */
 // TODO(dmaretskyi): Rename setTypeDXN.
-export const setTypename = (obj: any, typename: DXN): void => {
-  invariant(typename instanceof DXN, 'Invalid type.');
+export const setTypename = (obj: any, typename: URI.URI): void => {
+  assertArgument(typeof typename === 'string', 'typename', 'Invalid type.');
   Object.defineProperty(obj, TypeId, {
     value: typename,
     writable: false,
@@ -206,68 +203,25 @@ export const setTypename = (obj: any, typename: DXN): void => {
 };
 
 /**
- * @returns Object type as {@link DXN}.
- * @returns undefined if the object doesn't have a type.
+ * @returns Object type URI — either a typename {@link DXN} or an `echo:` reference to a stored Schema object.
+ * @returns undefined if the object has no registered type URI (e.g. unresolved query result).
  * @example `dxn:com.example.type.person:1.0.0`
+ * @example `echo:/01KKKG2FHWCMTR0BY00GJSVT1X` (stored schema)
  *
- * @internal (use Obj.getTypeDXN)
+ * @internal (use Obj.getTypeURI)
  */
-// TODO(burdon): Narrow type.
-export const getTypeDXN = (obj: AnyProperties): DXN | undefined => {
-  if (!obj) {
+export const getTypeURI = (obj: AnyProperties): URI.URI | undefined => {
+  if (obj == null) {
     return undefined;
   }
-
   const type = (obj as any)[TypeId];
-  if (!type) {
+  if (type == null) {
     return undefined;
   }
-
-  invariant(type instanceof DXN, 'Invalid object.');
+  invariant(URI.isURI(type), 'Invalid object.');
   return type;
 };
 
-/**
- * Checks if the object is an instance of the schema.
- * Only typename is compared, the schema version is ignored.
- *
- * The following cases are considered to mean that the object is an instance of the schema:
- *  - Object was created with this exact schema.
- *  - Object was created with a different version of this schema.
- *  - Object was created with a different schema (maybe dynamic) that has the same typename.
- */
-// TODO(burdon): Can we use `Schema.is`?
-export const isInstanceOf = <Schema extends Schema.Schema.AnyNoContext>(
-  schema: Schema,
-  object: any,
-): object is Schema.Schema.Type<Schema> => {
-  if (object == null) {
-    return false;
-  }
-
-  const schemaDXN = getSchemaDXN(schema);
-  if (!schemaDXN) {
-    throw new Error('Schema must have an object annotation.');
-  }
-
-  const type = getTypeDXN(object);
-  if (type && DXN.equals(type, schemaDXN)) {
-    return true;
-  }
-
-  const typename = getTypename(object);
-  if (!typename) {
-    return false;
-  }
-
-  const typeDXN = schemaDXN.asTypeDXN();
-  if (!typeDXN) {
-    return false;
-  }
-
-  return typeDXN.type === typename;
-};
-
 //
 // PropertyMeta
 //
@@ -286,6 +240,12 @@ export type PropertyMetaAnnotation = {
 
 // TODO(wittjosiah): Align with other annotations.
 // TODO(wittjosiah): Why is this separate from FormatAnnotation?
+/**
+ * Apply property-level metadata to an Effect schema. Only accepts
+ * `Schema.Schema.Any` — apply BEFORE wrapping the schema with
+ * `Type.makeObject` / `Type.makeRelation`. To read property meta off a
+ * `Type.Type` entity, unwrap it first with `Type.getSchema(entity)`.
+ */
 export const PropertyMeta = (name: string, value: PropertyMetaValue) => {
   return <A, I, R>(self: Schema.Schema<A, I, R>): Schema.Schema<A, I, R> => {
     const existingMeta = self.ast.annotations[PropertyMetaAnnotationId] as PropertyMetaAnnotation;
@@ -323,10 +283,10 @@ export const SchemaMetaSymbol = Symbol.for('@dxos/schema/SchemaMeta');
 export type SchemaMeta = TypeMeta & { id: string };
 
 /**
- * Identifies a schema as a schema for a hidden system type.
+ * Identifies a schema as hidden from user-facing surfaces (like dotfiles — visible only via an advanced setting).
  */
-export const SystemTypeAnnotationId = Symbol.for('@dxos/schema/annotation/SystemType');
-export const SystemTypeAnnotation = createAnnotationHelper<boolean>(SystemTypeAnnotationId);
+export const HiddenAnnotationId = Symbol.for('@dxos/schema/annotation/Hidden');
+export const HiddenAnnotation = createAnnotationHelper<boolean>(HiddenAnnotationId);
 
 /**
  * Identifies label property or JSON path expression.
@@ -340,7 +300,7 @@ export const LabelAnnotation = createAnnotationHelper<string[]>(LabelAnnotationI
  * 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?
+// TODO(burdon): Convert to SchemaEx.JsonPath?
 export const getLabelWithSchema = <S extends Schema.Schema.Any>(
   schema: S,
   object: Schema.Schema.Type<S>,
@@ -352,7 +312,7 @@ export const getLabelWithSchema = <S extends Schema.Schema.Any>(
       'accessor',
       'Label annotation must be a string or an array of strings',
     );
-    const value = getField(object, accessor as JsonPath);
+    const value = SchemaEx.getField(object, accessor as SchemaEx.JsonPath);
     switch (typeof value) {
       case 'string': {
         const trimmed = value.trim();
@@ -403,14 +363,14 @@ export const DescriptionAnnotation = createAnnotationHelper<string>(DescriptionA
  * Returns the description for a given object based on {@link DescriptionAnnotationId}.
  * Lower-level version that requires explicit schema parameter.
  */
-// TODO(burdon): Convert to JsonPath?
+// TODO(burdon): Convert to SchemaEx.JsonPath?
 export const getDescriptionWithSchema = <S extends Schema.Schema.Any>(
   schema: S,
   object: Schema.Schema.Type<S>,
 ): string | undefined => {
   const accessor = DescriptionAnnotation.get(schema).pipe(Option.getOrElse(() => 'description'));
   assertArgument(typeof accessor === 'string', 'accessor', 'Description annotation must be a string');
-  const value = getField(object, accessor as JsonPath);
+  const value = SchemaEx.getField(object, accessor as SchemaEx.JsonPath);
   switch (typeof value) {
     case 'string':
     case 'number':
@@ -446,6 +406,13 @@ export const setDescriptionWithSchema = <S extends Schema.Schema.Any>(
 export const FormInputAnnotationId = Symbol.for('@dxos/schema/annotation/FormInput');
 export const FormInputAnnotation = createAnnotationHelper<boolean>(FormInputAnnotationId);
 
+/**
+ * When set on a `Ref` property, the form renders the referenced object's own
+ * fields inline (a nested form bound to the target) instead of a picker.
+ */
+export const FormInlineAnnotationId = Symbol.for('@dxos/schema/annotation/FormInline');
+export const FormInlineAnnotation = createAnnotationHelper<boolean>(FormInlineAnnotationId);
+
 /**
  * Default field to be used on referenced schema to lookup the value.
  */
@@ -471,26 +438,29 @@ interface MakeAnnoationsProps<T> {
   schema: Schema.Schema<T, any, never>;
 }
 
-// TODO(wittjosiah): Comment.
-export const makeUserAnnotation = <T>(props: MakeAnnoationsProps<T>): AnnotationHelper<T> => {
+// Annotation ids use the same NSID / reverse-DNS format as TypenameSchema —
+// dot-separated segments, middle segments may be hyphenated, final segment may be camelCase.
+// At least 3 segments are required (e.g. org.dxos.annotation.example).
+export const makeUserAnnotation = <T>(props: MakeAnnoationsProps<T>): Annotation.Annotation<T> => {
   assertArgument(
-    /^[a-z][a-z0-9]*(\.[a-z][a-z0-9-]*){2,}$/.test(props.id),
+    /^[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])?){2,}(\.[a-zA-Z]([a-zA-Z0-9]{0,62})?)?$/.test(
+      props.id,
+    ),
     'id',
-    'Annotation id must be in the FQN format (org.dxos.annotation.example).',
+    'Annotation id must be in the FQN format (org.dxos.annotation.example or org.dxos.space.rootCollection).',
   );
 
-  const getFromAst = (ast: SchemaAST.AST) =>
-    SchemaAST.getAnnotation<PropertyMetaAnnotation>(PropertyMetaAnnotationId)(ast).pipe(
-      Option.map((meta) => meta[props.id] as unknown),
-      Option.map(Schema.decodeUnknownSync(props.schema)),
-    );
-
-  return {
-    get: (schema) => getFromAst(schema.ast),
-    getFromAst: (ast) => getFromAst(ast),
+  const annotation: Annotation.Annotation<T> = {
+    [ANNOTATION_TYPE_ID]: { _Type: {} as T },
+    key: props.id as Annotation.Key,
+    schema: props.schema,
+    get: (schema) => getFromAst(schema.ast, annotation),
+    getFromAst: (ast) => getFromAst(ast, annotation),
     set: (value) =>
       PropertyMeta(props.id, Schema.encodeSync(props.schema)(value)) as <S extends Schema.Schema.Any>(schema: S) => S,
   };
+
+  return annotation;
 };
 
 const IconAnnotationSchema = Schema.Struct({
@@ -518,7 +488,6 @@ const IconAnnotationSchema = Schema.Struct({
    *  - 'pink'
    *  - 'rose'
    */
-
   hue: Schema.optional(Schema.String),
 });
 
@@ -532,20 +501,54 @@ export const IconAnnotation = makeUserAnnotation<IconAnnotation>({
   schema: IconAnnotationSchema,
 });
 
+/**
+ * Indicates that this entity's icon should be resolved from a property whose value is a `Ref`
+ * to another entity. Consumers (e.g. graph node builders) resolve the ref target and use that
+ * target's schema `IconAnnotation` in place of the static one declared on this schema.
+ *
+ * Useful for wrapper schemas that delegate their visual identity to a referenced sub-entity
+ * (e.g. a generic `Game` whose icon should come from its `variant` ref's typed state).
+ */
+export const IconFromRefAnnotation = makeUserAnnotation<string>({
+  id: 'org.dxos.annotation.icon.from-ref',
+  schema: Schema.String,
+});
+
+/**
+ * Options for {@link getLabel}.
+ */
+export type GetLabelOptions = {
+  /**
+   * Strategy for deriving a label when the entity has no `LabelAnnotation` value.
+   * - `'typename'`: use the entity's typename (e.g. `org.dxos.type.table`).
+   *   Useful for Card.Title chrome that must always display something, even
+   *   for unlabeled objects.
+   */
+  fallback?: 'typename';
+};
+
 /**
  * Get the label of an entity.
  * Accepts both reactive entities and snapshots.
+ *
+ * If `options.fallback === 'typename'` and no label is set, returns the
+ * entity's typename instead.
  */
-export const getLabel = (entity: AnyProperties): string | undefined => {
+export const getLabel = (entity: AnyProperties, options?: GetLabelOptions): string | undefined => {
   const schema = getSchema(entity);
-  if (schema != null) {
-    return getLabelWithSchema(schema, entity);
+  const label = schema != null ? getLabelWithSchema(schema, entity) : undefined;
+  if (label != null) {
+    return label;
+  }
+  if (options?.fallback === 'typename') {
+    return getTypename(entity);
   }
+  return undefined;
 };
 
 /**
  * Set the label of an entity.
- * Must be called within an Obj.change or Relation.change callback.
+ * Must be called within an Obj.update or Relation.update callback.
  */
 export const setLabel = (entity: Mutable<AnyProperties>, label: string) => {
   const schema = getSchema(entity);
@@ -565,9 +568,29 @@ export const getDescription = (entity: AnyProperties): string | undefined => {
   }
 };
 
+/**
+ * Get the icon annotation for an entity, resolved via its type-level `IconAnnotation`.
+ * Accepts both reactive entities and snapshots.
+ *
+ * Returns the full `{ icon, hue }` annotation so callers can use both the phosphor icon
+ * name and the suggested colour. Callers wanting just the icon name typically write
+ * `Obj.getIcon(obj)?.icon ?? 'ph--cube--regular'`.
+ *
+ * Note: this is the "static" icon from the object's own schema. It does not follow
+ * `IconFromRefAnnotation` delegation — call sites needing that (e.g. app-graph node
+ * builders) should resolve the ref themselves.
+ */
+export const getIcon = (entity: AnyProperties): IconAnnotation | undefined => {
+  const schema = getSchema(entity);
+  if (schema == null) {
+    return undefined;
+  }
+  return Option.getOrUndefined(IconAnnotation.get(schema));
+};
+
 /**
  * Set the description of an entity.
- * Must be called within an Obj.change or Relation.change callback.
+ * Must be called within an Obj.update or Relation.update callback.
  */
 export const setDescription = (entity: Mutable<AnyProperties>, description: string) => {
   const schema = getSchema(entity);
@@ -575,3 +598,12 @@ export const setDescription = (entity: Mutable<AnyProperties>, description: stri
     setDescriptionWithSchema(schema, entity, description);
   }
 };
+
+export { Dictionary, Key, getDictionary, setDictionary } from './dictionary';
+
+export const getFromAst = <T>(ast: SchemaAST.AST, annotation: Annotation.Annotation<T>): Option.Option<T> => {
+  return SchemaAST.getAnnotation<PropertyMetaAnnotation>(PropertyMetaAnnotationId)(ast).pipe(
+    Option.flatMap((meta) => Option.fromNullable(meta[annotation.key])),
+    Option.map(Schema.decodeUnknownSync(annotation.schema)),
+  );
+};

package/src/internal/Annotation/dictionary.ts

@@ -0,0 +1,47 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Function from 'effect/Function';
+import * as Option from 'effect/Option';
+import * as Schema from 'effect/Schema';
+import * as Types from 'effect/Types';
+
+import type * as Annotation from '../../Annotation';
+
+/**
+ * Unique identifier for an annotation.
+ */
+export const Key = Schema.String.pipe(Schema.brand('~@dxos/echo/AnnotationKey'));
+export type Key = Schema.Schema.Type<typeof Key>;
+
+/**
+ * Set of annotation values stored on entity meta or nested in schemas.
+ */
+export const Dictionary = Schema.Record({ key: Key, value: Schema.Unknown });
+export interface Dictionary extends Schema.Schema.Type<typeof Dictionary> {}
+
+/**
+ * Get the value of an annotation from a dictionary.
+ */
+export const getDictionary = <T>(
+  values: Annotation.Dictionary,
+  annotation: Annotation.Annotation<T>,
+): Option.Option<T> => {
+  if (!(annotation.key in values)) {
+    return Option.none();
+  }
+
+  return Function.pipe(values[annotation.key], Schema.decodeUnknownSync(annotation.schema), Option.some);
+};
+
+/**
+ * Set the value of an annotation in a dictionary.
+ */
+export const setDictionary = <T>(
+  values: Types.Mutable<Annotation.Dictionary>,
+  annotation: Annotation.Annotation<T>,
+  value: T,
+): void => {
+  values[annotation.key] = Schema.encodeSync(annotation.schema)(value);
+};