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

package/src/View.ts

@@ -8,7 +8,7 @@ import * as Schema from 'effect/Schema';
 
 import { QueryAST } from '@dxos/echo-protocol';
 import { JsonPath } from '@dxos/effect';
-import { PublicKey } from '@dxos/keys';
+import { DXN, PublicKey } from '@dxos/keys';
 
 import * as Annotation from './Annotation';
 import * as Filter from './Filter';
@@ -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/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';
@@ -24,11 +23,14 @@ 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 StateMap from './StateMap';
 export * as Tag from './Tag';
+export * as TagIndex from './TagIndex';
+export * as Tagging from './Tagging';
 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 { 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
@@ -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.
@@ -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.flatMap((meta) => Option.fromNullable(meta[props.id])),
-      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),
 });
 
@@ -545,15 +514,36 @@ export const IconFromRefAnnotation = makeUserAnnotation<string>({
   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;
 };
 
 /**
@@ -578,6 +568,26 @@ 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.update or Relation.update callback.
@@ -588,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);
+};

package/src/internal/Annotation/entity-dictionary.ts

@@ -0,0 +1,40 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Option from 'effect/Option';
+
+import type * as Annotation from '../../Annotation';
+import type * as Entity from '../../Entity';
+import { getMetaChecked } from '../common/api/meta';
+import { type Mutable } from '../common/proxy/reactive';
+import { isEntity, isSnapshot } from '../Entity/guard';
+import { getDictionary, setDictionary } from './dictionary';
+
+/**
+ * Get the value of an annotation from an entity instance or snapshot.
+ */
+export const get = <T>(
+  target: Entity.Unknown | Entity.Snapshot,
+  annotation: Annotation.Annotation<T>,
+): Option.Option<T> => {
+  if (isEntity(target) || isSnapshot(target)) {
+    const meta = getMetaChecked(target);
+    return getDictionary(meta.annotations, annotation);
+  } else {
+    throw new TypeError('Target is not an annotation target.');
+  }
+};
+
+/**
+ * Set the value of an annotation on an entity instance.
+ * Must be called with a mutable entity — i.e. inside an `Obj.update` callback.
+ */
+export const set = <T>(target: Mutable<Entity.Unknown>, annotation: Annotation.Annotation<T>, value: T): void => {
+  if (isEntity(target)) {
+    const meta = getMetaChecked(target);
+    setDictionary(meta.annotations, annotation, value);
+  } else {
+    throw new TypeError('Target is not an annotation target.');
+  }
+};

package/src/internal/Annotation/index.ts

@@ -2,6 +2,8 @@
 // Copyright 2024 DXOS.org
 //
 
-export * from './annotations';
-export * from './sorting';
+export * from './dictionary';
 export * from './util';
+export * from './sorting';
+export * from './annotations';
+export * from './entity-dictionary';

package/src/internal/Annotation/util.ts

@@ -2,7 +2,7 @@
 // Copyright 2025 DXOS.org
 //
 
-import type * as Option from 'effect/Option';
+import * as Option from 'effect/Option';
 import type * as Schema from 'effect/Schema';
 import * as SchemaAST from 'effect/SchemaAST';
 
@@ -13,7 +13,12 @@ import { EntityKind } from '../common/types';
 
 export interface AnnotationHelper<T> {
   /**
-   * Get the annotation value from the schema.
+   * 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>;
   /**
@@ -21,7 +26,11 @@ export interface AnnotationHelper<T> {
    */
   getFromAst: (ast: SchemaAST.AST) => Option.Option<T>;
   /**
-   * Set the annotation value on the schema.
+   * 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;
 }
@@ -30,13 +39,14 @@ export interface AnnotationHelper<T> {
  * Note: only for system annotations.
  */
 // TODO(dmaretskyi): Rename to createSystemAnnotationHelper.
+// TODO(dmaretskyi): REconcile with Annotation.make.
 export const createAnnotationHelper = <T>(id: symbol): AnnotationHelper<T> => {
   return {
     get: (schema) => SchemaAST.getAnnotation(schema.ast, id),
     getFromAst: (ast) => SchemaAST.getAnnotation(ast, id),
     set:
       (value) =>
-      <S extends Schema.Schema.Any>(schema: S) =>
+      <S extends Schema.Schema.Any>(schema: S): S =>
         schema.annotations({ [id]: value }) as S,
   };
 };
@@ -69,13 +79,12 @@ export const makeTypeJsonSchemaAnnotation = (options: {
   assertArgument(!!options.relationSource === (options.kind === EntityKind.Relation), 'relationSource');
   assertArgument(!!options.relationTarget === (options.kind === EntityKind.Relation), 'relationTarget');
 
-  const obj = {
-    // TODO(dmaretskyi): Should this include the version?
-    $id: options.identifier ?? DXN.fromTypename(options.typename).toString(),
+  const obj: Record<string, unknown> = {
+    $id: options.identifier ?? DXN.make(options.typename, options.version),
     entityKind: options.kind,
     version: options.version,
     typename: options.typename,
-  } as any;
+  };
   if (options.kind === EntityKind.Relation) {
     obj.relationSource = { $ref: options.relationSource };
     obj.relationTarget = { $ref: options.relationTarget };