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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/echo",
-  "version": "0.8.4-main.d05539e30a",
+  "version": "0.8.4-main.d9fc60f731",
   "description": "ECHO API",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -103,15 +103,20 @@
       "types": "./dist/types/src/Ref.d.ts",
       "default": "./dist/lib/neutral/Ref.mjs"
     },
+    "./Registry": {
+      "source": "./src/Registry.ts",
+      "types": "./dist/types/src/Registry.d.ts",
+      "default": "./dist/lib/neutral/Registry.mjs"
+    },
     "./Relation": {
       "source": "./src/Relation.ts",
       "types": "./dist/types/src/Relation.d.ts",
       "default": "./dist/lib/neutral/Relation.mjs"
     },
-    "./SchemaRegistry": {
-      "source": "./src/SchemaRegistry.ts",
-      "types": "./dist/types/src/SchemaRegistry.d.ts",
-      "default": "./dist/lib/neutral/SchemaRegistry.mjs"
+    "./Scope": {
+      "source": "./src/Scope.ts",
+      "types": "./dist/types/src/Scope.d.ts",
+      "default": "./dist/lib/neutral/Scope.mjs"
     },
     "./Tag": {
       "source": "./src/Tag.ts",
@@ -122,11 +127,6 @@
       "source": "./src/Type.ts",
       "types": "./dist/types/src/Type.d.ts",
       "default": "./dist/lib/neutral/Type.mjs"
-    },
-    "./Extension": {
-      "source": "./src/Extension.ts",
-      "types": "./dist/types/src/Extension.d.ts",
-      "default": "./dist/lib/neutral/Extension.mjs"
     }
   },
   "files": [
@@ -134,19 +134,17 @@
     "src"
   ],
   "dependencies": {
-    "effect": "3.20.0",
-    "@dxos/async": "0.8.4-main.d05539e30a",
-    "@dxos/context": "0.8.4-main.d05539e30a",
-    "@dxos/echo-protocol": "0.8.4-main.d05539e30a",
-    "@dxos/effect": "0.8.4-main.d05539e30a",
-    "@dxos/invariant": "0.8.4-main.d05539e30a",
-    "@dxos/debug": "0.8.4-main.d05539e30a",
-    "@dxos/keys": "0.8.4-main.d05539e30a",
-    "@dxos/log": "0.8.4-main.d05539e30a",
-    "@dxos/node-std": "0.8.4-main.d05539e30a",
-    "@dxos/protocols": "0.8.4-main.d05539e30a",
-    "@dxos/util": "0.8.4-main.d05539e30a",
-    "@dxos/errors": "0.8.4-main.d05539e30a"
+    "effect": "3.21.2",
+    "@dxos/async": "0.8.4-main.d9fc60f731",
+    "@dxos/debug": "0.8.4-main.d9fc60f731",
+    "@dxos/echo-protocol": "0.8.4-main.d9fc60f731",
+    "@dxos/effect": "0.8.4-main.d9fc60f731",
+    "@dxos/errors": "0.8.4-main.d9fc60f731",
+    "@dxos/log": "0.8.4-main.d9fc60f731",
+    "@dxos/keys": "0.8.4-main.d9fc60f731",
+    "@dxos/invariant": "0.8.4-main.d9fc60f731",
+    "@dxos/node-std": "0.8.4-main.d9fc60f731",
+    "@dxos/util": "0.8.4-main.d9fc60f731"
   },
   "publishConfig": {
     "access": "public"

package/src/Annotation.test.ts

@@ -0,0 +1,439 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Option from 'effect/Option';
+import * as Schema from 'effect/Schema';
+import * as SchemaAST from 'effect/SchemaAST';
+import { describe, test } from 'vitest';
+
+import { DXN } from '@dxos/keys';
+
+import * as Annotation from './Annotation';
+import * as Obj from './Obj';
+import * as Type from './Type';
+
+describe('Annotation', () => {
+  describe('make', () => {
+    test('creates an annotation with a string schema', ({ expect }) => {
+      const ColorAnnotation = Annotation.make({
+        id: 'org.dxos.annotation.color',
+        schema: Schema.String,
+      });
+
+      expect(ColorAnnotation.key).toBe('org.dxos.annotation.color');
+      expect(ColorAnnotation.schema).toBe(Schema.String);
+      expect(ColorAnnotation[Annotation.TypeId]).toBeDefined();
+    });
+
+    test('creates an annotation with a number schema', ({ expect }) => {
+      const PriorityAnnotation = Annotation.make({
+        id: 'org.dxos.annotation.priority',
+        schema: Schema.Number,
+      });
+
+      expect(PriorityAnnotation.key).toBe('org.dxos.annotation.priority');
+      expect(PriorityAnnotation.schema).toBe(Schema.Number);
+    });
+
+    test('creates an annotation with a complex schema', ({ expect }) => {
+      const MetadataSchema = Schema.Struct({
+        author: Schema.String,
+        version: Schema.Number,
+        tags: Schema.Array(Schema.String),
+      });
+      const MetadataAnnotation = Annotation.make({
+        id: 'org.dxos.annotation.metadata',
+        schema: MetadataSchema,
+      });
+
+      expect(MetadataAnnotation.key).toBe('org.dxos.annotation.metadata');
+      expect(MetadataAnnotation.schema).toBe(MetadataSchema);
+    });
+  });
+
+  describe('getDictionary and setDictionary', () => {
+    test('set and get a string value', ({ expect }) => {
+      const ColorAnnotation = Annotation.make({
+        id: 'org.dxos.annotation.color',
+        schema: Schema.String,
+      });
+      const values: Annotation.Dictionary = {};
+
+      Annotation.setDictionary(values, ColorAnnotation, 'red');
+      const result = Annotation.getDictionary(values, ColorAnnotation);
+
+      expect(Option.isSome(result)).toBe(true);
+      expect(Option.getOrThrow(result)).toBe('red');
+    });
+
+    test('set and get a number value', ({ expect }) => {
+      const PriorityAnnotation = Annotation.make({
+        id: 'org.dxos.annotation.priority',
+        schema: Schema.Number,
+      });
+      const values: Annotation.Dictionary = {};
+
+      Annotation.setDictionary(values, PriorityAnnotation, 42);
+      const result = Annotation.getDictionary(values, PriorityAnnotation);
+
+      expect(Option.isSome(result)).toBe(true);
+      expect(Option.getOrThrow(result)).toBe(42);
+    });
+
+    test('set and get a boolean value', ({ expect }) => {
+      const EnabledAnnotation = Annotation.make({
+        id: 'org.dxos.annotation.enabled',
+        schema: Schema.Boolean,
+      });
+      const values: Annotation.Dictionary = {};
+
+      Annotation.setDictionary(values, EnabledAnnotation, true);
+      const result = Annotation.getDictionary(values, EnabledAnnotation);
+
+      expect(Option.isSome(result)).toBe(true);
+      expect(Option.getOrThrow(result)).toBe(true);
+    });
+
+    test('set and get a complex object value', ({ expect }) => {
+      const ConfigSchema = Schema.Struct({
+        theme: Schema.String,
+        fontSize: Schema.Number,
+        darkMode: Schema.Boolean,
+      });
+      const ConfigAnnotation = Annotation.make({
+        id: 'org.dxos.annotation.config',
+        schema: ConfigSchema,
+      });
+      const values: Annotation.Dictionary = {};
+
+      const config = { theme: 'modern', fontSize: 14, darkMode: true };
+      Annotation.setDictionary(values, ConfigAnnotation, config);
+      const result = Annotation.getDictionary(values, ConfigAnnotation);
+
+      expect(Option.isSome(result)).toBe(true);
+      expect(Option.getOrThrow(result)).toEqual(config);
+    });
+
+    test('set and get an array value', ({ expect }) => {
+      const TagsAnnotation = Annotation.make({
+        id: 'org.dxos.annotation.tags',
+        schema: Schema.Array(Schema.String),
+      });
+      const values: Annotation.Dictionary = {};
+
+      const tags = ['important', 'urgent', 'review'];
+      Annotation.setDictionary(values, TagsAnnotation, tags);
+      const result = Annotation.getDictionary(values, TagsAnnotation);
+
+      expect(Option.isSome(result)).toBe(true);
+      expect(Option.getOrThrow(result)).toEqual(tags);
+    });
+
+    test('get returns None for missing annotation', ({ expect }) => {
+      const ColorAnnotation = Annotation.make({
+        id: 'org.dxos.annotation.color',
+        schema: Schema.String,
+      });
+      const values: Annotation.Dictionary = {};
+
+      const result = Annotation.getDictionary(values, ColorAnnotation);
+
+      expect(Option.isNone(result)).toBe(true);
+    });
+
+    test('overwriting an annotation value', ({ expect }) => {
+      const ColorAnnotation = Annotation.make({
+        id: 'org.dxos.annotation.color',
+        schema: Schema.String,
+      });
+      const values: Annotation.Dictionary = {};
+
+      Annotation.setDictionary(values, ColorAnnotation, 'red');
+      Annotation.setDictionary(values, ColorAnnotation, 'blue');
+      const result = Annotation.getDictionary(values, ColorAnnotation);
+
+      expect(Option.isSome(result)).toBe(true);
+      expect(Option.getOrThrow(result)).toBe('blue');
+    });
+
+    test('multiple annotations on the same dictionary', ({ expect }) => {
+      const ColorAnnotation = Annotation.make({
+        id: 'org.dxos.annotation.color',
+        schema: Schema.String,
+      });
+      const PriorityAnnotation = Annotation.make({
+        id: 'org.dxos.annotation.priority',
+        schema: Schema.Number,
+      });
+      const EnabledAnnotation = Annotation.make({
+        id: 'org.dxos.annotation.enabled',
+        schema: Schema.Boolean,
+      });
+      const values: Annotation.Dictionary = {};
+
+      Annotation.setDictionary(values, ColorAnnotation, 'green');
+      Annotation.setDictionary(values, PriorityAnnotation, 5);
+      Annotation.setDictionary(values, EnabledAnnotation, false);
+
+      expect(Option.getOrThrow(Annotation.getDictionary(values, ColorAnnotation))).toBe('green');
+      expect(Option.getOrThrow(Annotation.getDictionary(values, PriorityAnnotation))).toBe(5);
+      expect(Option.getOrThrow(Annotation.getDictionary(values, EnabledAnnotation))).toBe(false);
+    });
+  });
+
+  describe('curried forms', () => {
+    test('getDictionary curried form', ({ expect }) => {
+      const ColorAnnotation = Annotation.make({
+        id: 'org.dxos.annotation.color',
+        schema: Schema.String,
+      });
+      const values: Annotation.Dictionary = {};
+      Annotation.setDictionary(values, ColorAnnotation, 'purple');
+
+      const getColor = Annotation.getDictionary(ColorAnnotation);
+      const result = getColor(values);
+
+      expect(Option.isSome(result)).toBe(true);
+      expect(Option.getOrThrow(result)).toBe('purple');
+    });
+
+    test('setDictionary curried form', ({ expect }) => {
+      const ColorAnnotation = Annotation.make({
+        id: 'org.dxos.annotation.color',
+        schema: Schema.String,
+      });
+      const values: Annotation.Dictionary = {};
+
+      const setOrange = Annotation.setDictionary(ColorAnnotation, 'orange');
+      setOrange(values);
+      const result = Annotation.getDictionary(values, ColorAnnotation);
+
+      expect(Option.isSome(result)).toBe(true);
+      expect(Option.getOrThrow(result)).toBe('orange');
+    });
+
+    test('curried forms work in pipelines', ({ expect }) => {
+      const ColorAnnotation = Annotation.make({
+        id: 'org.dxos.annotation.color',
+        schema: Schema.String,
+      });
+      const values: Annotation.Dictionary = {};
+
+      Annotation.setDictionary(ColorAnnotation, 'cyan')(values);
+      const result = Annotation.getDictionary(ColorAnnotation)(values);
+
+      expect(Option.isSome(result)).toBe(true);
+      expect(Option.getOrThrow(result)).toBe('cyan');
+    });
+  });
+
+  describe('Key', () => {
+    test('Key.make creates a branded key', ({ expect }) => {
+      const key = Annotation.Key.make('org.dxos.annotation.my-annotation');
+
+      expect(key).toBe('org.dxos.annotation.my-annotation');
+      expect(typeof key).toBe('string');
+    });
+  });
+
+  describe('Dictionary schema', () => {
+    test('Dictionary can be used as a schema', ({ expect }) => {
+      const PersonWithAnnotations = Schema.Struct({
+        name: Schema.String,
+        extensions: Annotation.Dictionary,
+      });
+
+      const person = Schema.decodeUnknownSync(PersonWithAnnotations)({
+        name: 'Alice',
+        extensions: {},
+      });
+
+      expect(person.name).toBe('Alice');
+      expect(person.extensions).toEqual({});
+    });
+
+    test('Dictionary schema accepts annotation data', ({ expect }) => {
+      const ColorAnnotation = Annotation.make({
+        id: 'org.dxos.annotation.color',
+        schema: Schema.String,
+      });
+      const values: Annotation.Dictionary = {};
+      Annotation.setDictionary(values, ColorAnnotation, 'red');
+
+      const PersonWithAnnotations = Schema.Struct({
+        name: Schema.String,
+        extensions: Annotation.Dictionary,
+      });
+
+      const person = Schema.decodeUnknownSync(PersonWithAnnotations)({
+        name: 'Bob',
+        extensions: values,
+      });
+
+      expect(person.name).toBe('Bob');
+      const color = Annotation.getDictionary(person.extensions, ColorAnnotation);
+      expect(Option.getOrThrow(color)).toBe('red');
+    });
+  });
+
+  describe('TypeId', () => {
+    test('TypeId is a unique symbol-like string', ({ expect }) => {
+      expect(Annotation.TypeId).toBe('~@dxos/echo/Annotation');
+    });
+
+    test('annotations have TypeId property', ({ expect }) => {
+      const ColorAnnotation = Annotation.make({
+        id: 'org.dxos.annotation.color',
+        schema: Schema.String,
+      });
+
+      expect(Annotation.TypeId in ColorAnnotation).toBe(true);
+    });
+  });
+
+  describe('schema', () => {
+    test('set and get on a struct schema', ({ expect }) => {
+      const ColorAnnotation = Annotation.make({
+        id: 'org.dxos.annotation.color',
+        schema: Schema.String,
+      });
+
+      const PersonSchema = Schema.Struct({
+        name: Schema.String,
+      }).pipe(ColorAnnotation.set('crimson'));
+
+      const result = ColorAnnotation.get(PersonSchema);
+
+      expect(Option.isSome(result)).toBe(true);
+      expect(Option.getOrThrow(result)).toBe('crimson');
+    });
+
+    test('get returns None when annotation is not on schema', ({ expect }) => {
+      const ColorAnnotation = Annotation.make({
+        id: 'org.dxos.annotation.color',
+        schema: Schema.String,
+      });
+
+      const PersonSchema = Schema.Struct({
+        name: Schema.String,
+      });
+
+      expect(Option.isNone(ColorAnnotation.get(PersonSchema))).toBe(true);
+    });
+
+    test('set and get on a property schema', ({ expect }) => {
+      const ColorAnnotation = Annotation.make({
+        id: 'org.dxos.annotation.color',
+        schema: Schema.String,
+      });
+
+      const PersonSchema = Schema.Struct({
+        name: Schema.String.pipe(ColorAnnotation.set('navy')),
+      });
+
+      const nameProperty = SchemaAST.getPropertySignatures(PersonSchema.ast).find((prop) => prop.name === 'name');
+      expect(nameProperty).toBeDefined();
+
+      const result = ColorAnnotation.getFromAst(nameProperty!.type);
+
+      expect(Option.isSome(result)).toBe(true);
+      expect(Option.getOrThrow(result)).toBe('navy');
+    });
+
+    test('annotation survives Type.makeObject and is readable from Type.getSchema', ({ expect }) => {
+      const ColorAnnotation = Annotation.make({
+        id: 'org.dxos.annotation.color',
+        schema: Schema.String,
+      });
+
+      const TaggedPerson = Schema.Struct({
+        name: Schema.String,
+      })
+        .pipe(ColorAnnotation.set('teal'))
+        .pipe(Type.makeObject(DXN.make('com.example.type.taggedperson', '0.1.0')));
+
+      const schema = Type.getSchema(TaggedPerson);
+      const result = ColorAnnotation.get(schema);
+
+      expect(Option.isSome(result)).toBe(true);
+      expect(Option.getOrThrow(result)).toBe('teal');
+    });
+  });
+
+  describe('object', () => {
+    const ColorAnnotation = Annotation.make({
+      id: 'org.dxos.annotation.color',
+      schema: Schema.String,
+    });
+    const Person = Schema.Struct({
+      name: Schema.String,
+    })
+      .pipe(ColorAnnotation.set('schema-teal'))
+      .pipe(Type.makeObject(DXN.make('com.example.type.taggedperson', '0.1.0')));
+
+    test('set and get on Obj.make instance', ({ expect }) => {
+      const person = Obj.make(Person, { name: 'Alice' });
+
+      Obj.update(person, (person) => {
+        Annotation.set(person, ColorAnnotation, 'instance-red');
+      });
+      const result = Annotation.get(person, ColorAnnotation);
+
+      expect(Option.isSome(result)).toBe(true);
+      expect(Option.getOrThrow(result)).toBe('instance-red');
+    });
+
+    test('get returns None when instance has no annotation value', ({ expect }) => {
+      const person = Obj.make(Person, { name: 'Bob' });
+
+      expect(Option.isNone(Annotation.get(person, ColorAnnotation))).toBe(true);
+    });
+
+    test('instance annotation is independent of schema default', ({ expect }) => {
+      const person = Obj.make(Person, { name: 'Carol' });
+
+      expect(Option.getOrThrow(ColorAnnotation.get(Type.getSchema(Person)))).toBe('schema-teal');
+      expect(Option.isNone(Annotation.get(person, ColorAnnotation))).toBe(true);
+
+      Obj.update(person, (person) => {
+        Annotation.set(person, ColorAnnotation, 'instance-blue');
+      });
+
+      expect(Option.getOrThrow(Annotation.get(person, ColorAnnotation))).toBe('instance-blue');
+      expect(Option.getOrThrow(ColorAnnotation.get(Type.getSchema(Person)))).toBe('schema-teal');
+    });
+
+    test('set and get inside Obj.update', ({ expect }) => {
+      const person = Obj.make(Person, { name: 'Dana' });
+
+      Obj.update(person, (person) => {
+        Annotation.set(person, ColorAnnotation, 'updated');
+      });
+
+      expect(Option.getOrThrow(Annotation.get(person, ColorAnnotation))).toBe('updated');
+    });
+
+    test('curried get and set on instances', ({ expect }) => {
+      const person = Obj.make(Person, { name: 'Eve' });
+
+      Obj.update(person, (person) => {
+        Annotation.set(ColorAnnotation, 'curried')(person);
+      });
+      const result = Annotation.get(ColorAnnotation)(person);
+
+      expect(Option.isSome(result)).toBe(true);
+      expect(Option.getOrThrow(result)).toBe('curried');
+    });
+
+    test('get reads annotation from a snapshot', ({ expect }) => {
+      const person = Obj.make(Person, { name: 'Frank' });
+      Obj.update(person, (person) => {
+        Annotation.set(person, ColorAnnotation, 'snapshot-color');
+      });
+
+      const snapshot = Obj.getSnapshot(person);
+      expect(Option.getOrThrow(Annotation.get(snapshot, ColorAnnotation))).toBe('snapshot-color');
+    });
+  });
+});

package/src/Annotation.ts

@@ -7,10 +7,11 @@
 export {
   DescriptionAnnotation,
   FormInputAnnotation,
+  FormInlineAnnotation,
   GeneratorAnnotation,
   LabelAnnotation,
   ReferenceAnnotation,
-  SystemTypeAnnotation,
+  HiddenAnnotation,
   TypeAnnotation,
   getDescriptionWithSchema,
   getLabelWithSchema,
@@ -21,10 +22,68 @@ export {
   IconFromRefAnnotation,
 } from './internal/Annotation';
 
-import type * as Schema from 'effect/Schema';
+import * as Function from 'effect/Function';
+import * as Option from 'effect/Option';
+import * as Schema from 'effect/Schema';
+import * as SchemaAST from 'effect/SchemaAST';
+import * as Types from 'effect/Types';
 
+import * as Entity from './Entity';
 import * as internalAnnotations from './internal/Annotation';
 
+export const TypeId = '~@dxos/echo/Annotation' as const;
+export type TypeId = typeof TypeId;
+
+// TODO(dmaretskyi): Reconcile different get/set styles: mutate in-place, return.
+// TODO(dmaretskyi): Reconcile Annotation methods vs static functions.
+// TODO(dmaretskyi): Reconcile Annotation.Key vs DXN -- work-out approach to versioning.
+
+/**
+ * Annotation is a typed property that can be assigned to a schema or an entity instance.
+ */
+export interface Annotation<T> {
+  [TypeId]: {
+    _Type: T;
+  };
+
+  // TODO(dmaretskyi): Make this a DXN?
+  /**
+   * Unique fully-qualified identifier for the annotation.
+   * @example "org.dxos.annotation.color"
+   */
+  readonly key: Key;
+
+  /**
+   * Schema of the annotation value.
+   */
+  readonly schema: Schema.Schema<T, unknown, never>;
+
+  /**
+   * Get the annotation value from an Effect schema.
+   *
+   * Only accepts `Schema.Schema.Any` — to read an annotation off a `Type.Type`
+   * entity, unwrap it first with `Type.getSchema(entity)`. This keeps the
+   * annotation pipeline single-shaped and forces annotations to live on the
+   * source schema, not on the post-construction Type entity.
+   */
+  get: (schema: Schema.Schema.Any) => Option.Option<T>;
+  /**
+   * Get the annotation value from the AST.
+   */
+  getFromAst: (ast: SchemaAST.AST) => Option.Option<T>;
+  /**
+   * Set the annotation on an Effect schema.
+   *
+   * Only accepts `Schema.Schema.Any` — annotations must be applied to the
+   * source schema BEFORE wrapping it with `Type.makeObject` / `Type.makeRelation`.
+   * In a pipe, place every `Annotation.X.set(...)` before the `Type.make...` step.
+   */
+  set: (value: T) => <S extends Schema.Schema.Any>(schema: S) => S;
+}
+
+export const Key = internalAnnotations.Key;
+export type Key = Schema.Schema.Type<typeof Key>;
+
 interface MakeProps<T> {
   id: string;
   schema: Schema.Schema<T, any, never>;
@@ -45,5 +104,93 @@ interface MakeProps<T> {
  * const schema = Schema.String.annotations(ColorAnnotation.set('red'));
  * ```
  */
-export const make: <T>(props: MakeProps<T>) => internalAnnotations.AnnotationHelper<T> =
-  internalAnnotations.makeUserAnnotation;
+export const make: <T>(props: MakeProps<T>) => Annotation<T> = internalAnnotations.makeUserAnnotation;
+
+/**
+ * Get the value of an annotation from an entity instance or snapshot.
+ * For schema-level reads use the annotation instance method (e.g. `ColorAnnotation.get(schema)`).
+ * For getting an annotation value from a dictionary, use `getDictionary`.
+ */
+export const get: {
+  <T>(annotation: Annotation<T>): (target: Entity.Unknown | Entity.Snapshot) => Option.Option<T>;
+  <T>(target: Entity.Unknown | Entity.Snapshot, annotation: Annotation<T>): Option.Option<T>;
+} = Function.dual<
+  <T>(annotation: Annotation<T>) => (target: Entity.Unknown | Entity.Snapshot) => Option.Option<T>,
+  <T>(target: Entity.Unknown | Entity.Snapshot, annotation: Annotation<T>) => Option.Option<T>
+>(2, (target, annotation) => {
+  return internalAnnotations.get(target, annotation);
+});
+
+/**
+ * Set the value of an annotation on an entity instance.
+ * For schema-level writes use the annotation instance method (e.g. `ColorAnnotation.set('red')`).
+ * For setting an annotation value on a dictionary, use `setDictionary`.
+ */
+export const set: {
+  <T>(annotation: Annotation<T>, value: T): (target: Entity.Mutable<Entity.Unknown>) => void;
+  <T>(target: Entity.Mutable<Entity.Unknown>, annotation: Annotation<T>, value: T): void;
+} = Function.dual<
+  <T>(annotation: Annotation<T>, value: T) => (target: Entity.Mutable<Entity.Unknown>) => void,
+  <T>(target: Entity.Mutable<Entity.Unknown>, annotation: Annotation<T>, value: T) => void
+>(3, (target, annotation, value) => {
+  return internalAnnotations.set(target, annotation, value);
+});
+
+export const getFromAst: {
+  <T>(annotation: Annotation<T>): (ast: SchemaAST.AST) => Option.Option<T>;
+  <T>(ast: SchemaAST.AST, annotation: Annotation<T>): Option.Option<T>;
+} = Function.dual<
+  <T>(annotation: Annotation<T>) => (ast: SchemaAST.AST) => Option.Option<T>,
+  <T>(ast: SchemaAST.AST, annotation: Annotation<T>) => Option.Option<T>
+>(2, (ast, annotation) => {
+  return internalAnnotations.getFromAst(ast, annotation);
+});
+
+/**
+ * Set of annotation values.
+ *
+ * Can be used inside an object/relation schema:
+ *
+ * ```ts
+ * const Person = Schema.Struct({
+ *   name: Schema.String,
+ *   extensions: Annotation.Dictionary,
+ * });
+ * ```
+ */
+export const Dictionary = internalAnnotations.Dictionary;
+export interface Dictionary extends Schema.Schema.Type<typeof Dictionary> {}
+
+/**
+ * Get the value of an annotation from a Dictionary.
+ */
+export const getDictionary: {
+  <T>(annotation: Annotation<T>): (values: Dictionary) => Option.Option<T>;
+  <T>(values: Dictionary, annotation: Annotation<T>): Option.Option<T>;
+} = Function.dual<
+  <T>(annotation: Annotation<T>) => (values: Dictionary) => Option.Option<T>,
+  <T>(values: Dictionary, annotation: Annotation<T>) => Option.Option<T>
+>(2, (values, annotation) => {
+  return internalAnnotations.getDictionary(values, annotation);
+});
+
+/**
+ * Set the value of an annotation in a Dictionary.
+ *
+ * Can also be used within Obj.update callback:
+ *
+ * ```ts
+ * Obj.update(obj, (obj) => {
+ *   Annotation.setDictionary(obj.annotations, ColorAnnotation, 'red');
+ * });
+ * ```
+ */
+export const setDictionary: {
+  <T>(annotation: Annotation<T>, value: T): (values: Dictionary) => void;
+  <T>(values: Types.Mutable<Dictionary>, annotation: Annotation<T>, value: T): void;
+} = Function.dual<
+  <T>(annotation: Annotation<T>, value: T) => (values: Dictionary) => void,
+  <T>(values: Types.Mutable<Dictionary>, annotation: Annotation<T>, value: T) => void
+>(3, (values, annotation, value) => {
+  return internalAnnotations.setDictionary(values, annotation, value);
+});