@dxos/echo 0.8.4-main.ef1bc66f44 → 0.8.4-main.effb148878

package/src/internal/Entity/entity.ts

@@ -0,0 +1,246 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+import * as SchemaAST from 'effect/SchemaAST';
+import type * as Types from 'effect/Types';
+
+import { DXN, ObjectId } from '@dxos/keys';
+import { type ToMutable } from '@dxos/util';
+
+import { type TypeAnnotation, TypeAnnotationId, makeTypeJsonSchemaAnnotation } from '../Annotation';
+import { defineHiddenProperty } from '../common/proxy/define-hidden-property';
+import { makeObject } from '../common/proxy/make-object';
+import { getProxyTarget } from '../common/proxy/proxy-utils';
+import {
+  type AnyEntity,
+  EntityKind,
+  InstancePhantomId,
+  KindId,
+  type ObjectMeta,
+  SchemaKindId,
+  StaticTypeSchemaSlot,
+} from '../common/types';
+import { JsonSchemaType } from '../JsonSchema';
+
+// TODO(burdon): Define Schema type for `typename` and use consistently for all DXN-like properties.
+
+// type RequiredKeys<T> = { [K in keyof T]-?: {} extends Pick<T, K> ? never : K }[keyof T];
+export type EchoTypeSchemaProps<T, ExtraFields = {}> = Types.Simplify<AnyEntity & ToMutable<T> & ExtraFields>;
+
+/**
+ * In-memory `Type.Type` entity shape produced by `Type.makeObject(dxn)` /
+ * `Type.makeRelation({...})`. A live reactive `TypeSchema` instance —
+ * identical to a persisted `Type.Type` except for database attachment.
+ *
+ * NOT a `Schema.Schema`. The underlying Effect Schema is cached on the hidden
+ * `StaticTypeSchemaSlot` slot — retrieve it via `Type.getSchema(...)`.
+ */
+// TODO(burdon): Rename EchoEntitySchema.
+export interface EchoTypeSchema<
+  Self extends Schema.Schema.Any,
+  ExtraFields = {},
+  K extends EntityKind = EntityKind,
+  Fields extends Schema.Struct.Fields = Schema.Struct.Fields,
+> {
+  /**
+   * Entity-kind brand. Type entities are their own kind (`Type`) regardless of
+   * the kind of instance they describe — `[SchemaKindId]` carries the latter.
+   * This lets predicates like `Obj.isObject` / `Relation.isRelation` cleanly
+   * reject type entities without also having to inspect `[SchemaKindId]`.
+   */
+  readonly [KindId]: EntityKind.Type;
+
+  /** Schema-kind brand indicating what kind of instance this type describes. */
+  readonly [SchemaKindId]: K;
+
+  /**
+   * Entity id. Always present — stamped at construction — but NOT the type's
+   * identity while in-memory: an unattached type resolves its URI to the typename
+   * DXN, switching to `echo:/<id>` only once attached to a database (see
+   * `getTypeURIFromSpecifier`, which discriminates by database attachment).
+   */
+  readonly id: ObjectId;
+
+  /** Source Effect Schema (kept on a hidden slot for `Type.getSchema`). */
+  readonly [StaticTypeSchemaSlot]: Schema.Schema.AnyNoContext;
+
+  // NOTE: `typename` / `version` are intentionally NOT fields. They live in
+  // `ObjectMeta` (`key` / `version`); read via `Type.getTypename(self)` /
+  // `Type.getVersion(self)`.
+  readonly jsonSchema: JsonSchemaType;
+
+  /** Struct fields for introspection. */
+  readonly fields: Fields;
+
+  /** Phantom — instance type produced by `Obj.make(self, ...)`. */
+  readonly _instance?: EchoTypeSchemaProps<Schema.Schema.Type<Self>, ExtraFields>;
+
+  /**
+   * Phantom slot mirroring `Type<A>` so internal helpers (`makeObject`,
+   * `createObject`, `Ref.make`) infer the instance type uniformly whether
+   * the caller passes an `EchoTypeSchema` or a top-level `Type.Type` entity.
+   *
+   * Includes the instance-kind brand (`[KindId]`) so the phantom is assignable
+   * to the matching public-side interface in `Type.ts` (`Type.Obj` /
+   * `Type.Relation` / `Type.Type`). Each kind projects identity: instances of
+   * an object-kind schema are object-kind entities, type-kind schemas produce
+   * type-kind (persisted Type.Type) entities — the latter additionally carry
+   * the `[SchemaKindId]` / `[StaticTypeSchemaSlot]` brands the echo-handler
+   * proxy exposes on persisted Type entities.
+   */
+  readonly [InstancePhantomId]?: EchoTypeSchemaProps<Schema.Schema.Type<Self>, ExtraFields> & {
+    readonly [KindId]: K;
+  } & (K extends EntityKind.Type
+      ? {
+          readonly [SchemaKindId]: EntityKind.Type;
+          readonly [StaticTypeSchemaSlot]: Schema.Schema.AnyNoContext;
+        }
+      : {});
+}
+
+// type MakeProps =
+//   | boolean
+//   | {
+//       readonly disableValidation?: boolean;
+//     };
+
+// NOTE: Utils copied from Effect `Schema.ts`.
+// const _ownKeys = (o: object): Array<PropertyKey> =>
+//   (Object.keys(o) as Array<PropertyKey>).concat(Object.getOwnPropertySymbols(o));
+
+// const _lazilyMergeDefaults = (
+//   fields: Schema.Struct.Fields,
+//   out: Record<PropertyKey, unknown>,
+// ): { [x: string | symbol]: unknown } => {
+//   const ownKeys = _ownKeys(fields);
+//   for (const key of ownKeys) {
+//     const field = fields[key];
+//     if (out[key] === undefined && Schema.isPropertySignature(field)) {
+//       const ast = field.ast;
+//       const defaultValue = ast._tag === 'PropertySignatureDeclaration' ? ast.defaultValue : ast.to.defaultValue;
+//       if (defaultValue !== undefined) {
+//         out[key] = defaultValue();
+//       }
+//     }
+//   }
+//   return out;
+// };
+
+// const _getDisableValidationMakeOption = (options: MakeProps | undefined): boolean =>
+//   Predicate.isBoolean(options) ? options : options?.disableValidation ?? false;
+
+/**
+ * Identity (typename + version) of the type meta-schema — the `Type.Type` that
+ * every ECHO type entity is itself an instance of. Shared by the materialisation
+ * vehicle ({@link persistentEntitySchema}) and `TypeSchema` so the two cannot
+ * drift on identity.
+ */
+export const TypeMetaSchemaDXN = DXN.make('org.dxos.type.schema', '0.1.0');
+
+/**
+ * Effect Schema that every `Type.Type` entity is an instance of: the meta-schema
+ * struct `{ name?, jsonSchema, id }` branded as a type-kind ECHO entity. This is
+ * the materialisation vehicle for `makeObject` below — the canonical user-facing
+ * entity is `Type/type-schema.ts`'s `TypeSchema`, which carries the same shape
+ * plus UI annotations.
+ *
+ * Kept self-contained (no import of `TypeSchema`) to avoid a bootstrap cycle:
+ * `TypeSchema` is itself produced via `makeEchoTypeSchema`, so this builder must
+ * not depend on it. `jsonSchema` is declared optional here (only on the
+ * materialisation vehicle — the canonical `TypeSchema` keeps it required) so the
+ * construction-time `Schema.asserts` does not force the field before it is
+ * attached; it is populated immediately after via a lazy accessor (see
+ * `makeEchoTypeSchema`).
+ */
+// TODO(wittjosiah): Reconcile with `TypeSchema` (`Type/type-schema.ts`).
+//   Both describe the same `org.dxos.type.schema` shape.
+const persistentEntitySchema: Schema.Schema.AnyNoContext = (() => {
+  const typename = DXN.getName(TypeMetaSchemaDXN);
+  const version = DXN.getVersion(TypeMetaSchemaDXN)!;
+  const struct = Schema.Struct({
+    name: Schema.optional(Schema.String),
+    jsonSchema: JsonSchemaType.pipe(Schema.optional),
+    id: ObjectId,
+  });
+  const ast = SchemaAST.annotations(struct.ast, {
+    [TypeAnnotationId]: { kind: EntityKind.Type, typename, version } satisfies TypeAnnotation,
+    [SchemaAST.JSONSchemaAnnotationId]: makeTypeJsonSchemaAnnotation({ kind: EntityKind.Type, typename, version }),
+  });
+  return Schema.make(ast);
+})();
+
+/**
+ * @internal
+ *
+ * Build an in-memory `Type.Type` entity (the value returned by `Type.makeObject`
+ * / `Type.makeRelation`). The result is a LIVE reactive `TypeSchema`
+ * instance — identical in every respect to a persisted `Type.Type` except that
+ * it is not yet attached to a database. It is mutable via `Type.update`, can be
+ * passed to `db.add(...)` (which keeps the same proxy and swaps the handler),
+ * and round-trips through `jsonSchema`.
+ *
+ * The source Effect Schema describing the user's type is cached on
+ * `[StaticTypeSchemaSlot]` so `Type.getSchema(...)` returns it without a
+ * jsonSchema round-trip; the cache is invalidated by the proxy set-trap when
+ * `jsonSchema` is mutated (see `typed-handler.ts`).
+ */
+export const makeEchoTypeSchema = <
+  Self extends Schema.Schema.Any,
+  K extends EntityKind = EntityKind,
+  // TODO(wittjosiah): Can this be inferred from the schema?
+  Fields extends Schema.Struct.Fields = Schema.Struct.Fields,
+>(
+  fields: Fields,
+  ast: SchemaAST.AST,
+  typename: string,
+  version: string,
+  kind: K,
+  computeJsonSchema: () => JsonSchemaType,
+): EchoTypeSchema<Self, {}, K, Fields> => {
+  // Source Effect Schema describing the user's type — cached for `Type.getSchema`.
+  const sourceSchema = Schema.make<
+    EchoTypeSchemaProps<Schema.Schema.Type<Self>>,
+    EchoTypeSchemaProps<Schema.Schema.Encoded<Self>>,
+    Schema.Schema.Context<Self>
+  >(ast);
+
+  // `typename` / `version` route through `ObjectMeta` (`key` / `version`) — the
+  // canonical registry-provenance pair — not data fields. `keys` is empty for
+  // in-memory declarations until persisted.
+  const meta: ObjectMeta = { keys: [], key: typename, version };
+
+  // Materialise as a live reactive meta-schema instance. `jsonSchema` is attached
+  // below as a getter (not passed here as data) for two reasons; see that accessor.
+  const entity = makeObject(persistentEntitySchema, {} as any, meta);
+
+  const target = getProxyTarget(entity)!;
+  // `jsonSchema` is always available, but computed once on first read rather than at
+  // construction: serializing the AST walks `Schema.suspend(...)` thunks, and for a
+  // self-referential type (`Schema.suspend(() => Self)`) that thunk hits `Self`'s TDZ
+  // while we're still inside its `const` initializer. A getter also lets reads return
+  // the raw object instead of a child reactive proxy.
+  let memoizedJsonSchema: JsonSchemaType | undefined;
+  Object.defineProperty(target, 'jsonSchema', {
+    configurable: true,
+    enumerable: true,
+    get() {
+      return (memoizedJsonSchema ??= computeJsonSchema());
+    },
+    set(value: JsonSchemaType) {
+      memoizedJsonSchema = value;
+    },
+  });
+  // Cache the source Effect Schema (read by `Type.getSchema` via the proxy's
+  // `[StaticTypeSchemaSlot]` get-trap; invalidated on `jsonSchema` mutation).
+  defineHiddenProperty(target, StaticTypeSchemaSlot, sourceSchema);
+  // Schema-kind brand: what kind of instance this type describes. There is no
+  // database handler to derive it for in-memory entities, so stamp it directly.
+  defineHiddenProperty(target, SchemaKindId, kind);
+  // Struct fields for introspection. A getter (not a data property) so reads return
+  // the raw fields object rather than a child reactive proxy.
+  Object.defineProperty(target, 'fields', { configurable: true, enumerable: false, get: () => fields });
+
+  return entity as unknown as EchoTypeSchema<Self, {}, K, Fields>;
+};

package/src/internal/{entities → Entity}/index.ts

@@ -2,8 +2,12 @@
 // Copyright 2024 DXOS.org
 //
 
+export * from './api';
 export * from './entity';
 export * from './model'; // TODO(burdon): Rename.
 export * from './object';
 export * from './relation';
+export * from './type-kind';
+export * from './type-uri';
 export * from './util';
+export * from './version';

package/src/internal/{entities → Entity}/model.ts

@@ -6,7 +6,7 @@ import type * as Schema from 'effect/Schema';
 
 import { type ForeignKey } from '@dxos/echo-protocol';
 import { invariant } from '@dxos/invariant';
-import { DXN, ObjectId } from '@dxos/keys';
+import { EchoURI, ObjectId, type URI } from '@dxos/keys';
 import { assumeType } from '@dxos/util';
 
 import type * as Database from '../../Database';
@@ -14,58 +14,38 @@ import {
   type ATTR_META,
   type ATTR_PARENT,
   type ATTR_TYPE,
+  ATTR_DELETED,
+  ATTR_RELATION_SOURCE,
+  ATTR_RELATION_TARGET,
+  ATTR_SELF_URI,
+  ATTR_SELF_URI_LEGACY,
   EntityKind,
   KindId,
   type MetaId,
+  ObjectDatabaseId,
+  ObjectDeletedId,
   type ObjectMeta,
+  ObjectVersionId,
   type ParentId,
-  type SchemaId,
-  TypeId,
-  type Version,
-} from '../types';
-
-import {
-  type ATTR_RELATION_SOURCE,
-  type ATTR_RELATION_TARGET,
   RelationSourceDXNId,
   RelationSourceId,
   RelationTargetDXNId,
   RelationTargetId,
-} from './relation';
-
-//
-// Defines the internal model of the echo object.
-//
-
-/**
- * Property name for self DXN when object is serialized to JSON.
- */
-export const ATTR_SELF_DXN = '@dxn';
-
-/**
- * DXN to the object itself.
- */
-export const SelfDXNId = Symbol.for('@dxos/echo/DXN');
-
-/**
- * Property name for deleted when object is serialized to JSON.
- */
-export const ATTR_DELETED = '@deleted';
-
-/**
- * Deletion marker.
- */
-export const ObjectDeletedId = Symbol.for('@dxos/echo/Deleted');
-
-/**
- * Object version accessor symbol.
- */
-export const ObjectVersionId: unique symbol = Symbol.for('@dxos/echo/Version');
-
-/**
- * Object database accessor symbol.
- */
-export const ObjectDatabaseId = Symbol.for('@dxos/echo/Database');
+  type SchemaId,
+  SelfURIId,
+  TypeId,
+  type Version,
+} from '../common/types';
+
+export {
+  ATTR_DELETED,
+  ATTR_SELF_URI,
+  ATTR_SELF_URI_LEGACY,
+  ObjectDatabaseId,
+  ObjectDeletedId,
+  ObjectVersionId,
+  SelfURIId,
+};
 
 /**
  * Internal runtime representation of an object.
@@ -74,17 +54,17 @@ export const ObjectDatabaseId = Symbol.for('@dxos/echo/Database');
 // NOTE: Each symbol has a jsdoc describing its purpose.
 export interface InternalObjectProps {
   readonly id: ObjectId;
-  readonly [SelfDXNId]: DXN;
+  readonly [SelfURIId]: EchoURI.EchoURI;
   readonly [KindId]: EntityKind;
   readonly [SchemaId]: Schema.Schema.AnyNoContext;
-  readonly [TypeId]: DXN;
+  readonly [TypeId]: URI.URI;
   readonly [MetaId]?: ObjectMeta;
   [ParentId]?: InternalObjectProps;
   readonly [ObjectDatabaseId]?: Database.Database;
   readonly [ObjectDeletedId]?: boolean;
   readonly [ObjectVersionId]?: Version;
-  readonly [RelationSourceDXNId]?: DXN;
-  readonly [RelationTargetDXNId]?: DXN;
+  readonly [RelationSourceDXNId]?: EchoURI.EchoURI;
+  readonly [RelationTargetDXNId]?: EchoURI.EchoURI;
   readonly [RelationSourceId]?: InternalObjectProps;
   readonly [RelationTargetId]?: InternalObjectProps;
 }
@@ -95,20 +75,22 @@ export interface InternalObjectProps {
 export interface ObjectMetaJSON {
   keys: ForeignKey[];
   tags?: string[];
+  key?: string;
+  version?: string;
 }
 
 /**
  * JSON representation of an object or relation metadata.
  */
 export interface ObjectJSON {
-  id: string;
-  [ATTR_TYPE]: DXN.String;
-  [ATTR_SELF_DXN]?: DXN.String;
-  [ATTR_PARENT]?: string; // Encoded reference
+  id: ObjectId;
+  [ATTR_TYPE]?: URI.URI;
+  [ATTR_SELF_URI]?: EchoURI.EchoURI;
+  [ATTR_PARENT]?: EchoURI.EchoURI; // Encoded reference
   [ATTR_DELETED]?: boolean;
   [ATTR_META]?: ObjectMetaJSON;
-  [ATTR_RELATION_SOURCE]?: DXN.String;
-  [ATTR_RELATION_TARGET]?: DXN.String;
+  [ATTR_RELATION_SOURCE]?: EchoURI.EchoURI;
+  [ATTR_RELATION_TARGET]?: EchoURI.EchoURI;
 
   /**
    * Application-specific properties.
@@ -123,16 +105,16 @@ export function assertObjectModel(obj: unknown): asserts obj is InternalObjectPr
   invariant(typeof obj === 'object' && obj !== null, 'Invalid object model: not an object');
   assumeType<InternalObjectProps>(obj);
   invariant(ObjectId.isValid(obj.id), 'Invalid object model: invalid id');
-  invariant(obj[TypeId] === undefined || obj[TypeId] instanceof DXN, 'Invalid object model: invalid type');
+  invariant(obj[TypeId] === undefined || typeof obj[TypeId] === 'string', 'Invalid object model: invalid type');
   invariant(
-    obj[KindId] === EntityKind.Object || obj[KindId] === EntityKind.Relation,
+    obj[KindId] === EntityKind.Object || obj[KindId] === EntityKind.Relation || obj[KindId] === EntityKind.Type,
     'Invalid object model: invalid entity kind',
   );
 
   if (obj[KindId] === EntityKind.Relation) {
-    invariant(obj[RelationSourceDXNId] instanceof DXN, 'Invalid object model: invalid relation source');
-    invariant(obj[RelationTargetDXNId] instanceof DXN, 'Invalid object model: invalid relation target');
-    invariant(!(obj[RelationSourceId] instanceof DXN), 'Invalid object model: source pointer is a DXN');
-    invariant(!(obj[RelationTargetId] instanceof DXN), 'Invalid object model: target pointer is a DXN');
+    invariant(EchoURI.isEchoURI(obj[RelationSourceDXNId]), 'Invalid object model: invalid relation source');
+    invariant(EchoURI.isEchoURI(obj[RelationTargetDXNId]), 'Invalid object model: invalid relation target');
+    invariant(!EchoURI.isEchoURI(obj[RelationSourceId]), 'Invalid object model: source pointer is a DXN');
+    invariant(!EchoURI.isEchoURI(obj[RelationTargetId]), 'Invalid object model: target pointer is a DXN');
   }
 }

package/src/internal/{entities → Entity}/object.ts

@@ -6,10 +6,11 @@ import * as Schema from 'effect/Schema';
 import * as SchemaAST from 'effect/SchemaAST';
 
 import { invariant } from '@dxos/invariant';
+import { DXN } from '@dxos/keys';
 
-import { type TypeAnnotation, TypeAnnotationId, type TypeMeta, makeTypeJsonSchemaAnnotation } from '../annotations';
-import { EntityKind } from '../types';
-
+import { type TypeAnnotation, TypeAnnotationId, makeTypeJsonSchemaAnnotation } from '../Annotation';
+import { EntityKind } from '../common/types';
+import { toJsonSchema } from '../JsonSchema';
 import { type EchoTypeSchema, makeEchoTypeSchema } from './entity';
 
 /**
@@ -26,11 +27,15 @@ export type EchoObjectSchema<
  */
 export const EchoObjectSchema: {
   (
-    meta: TypeMeta,
+    dxn: DXN.DXN,
   ): <Self extends Schema.Schema.Any, Fields extends Schema.Struct.Fields = Schema.Struct.Fields>(
     self: Self & { fields?: Fields },
   ) => EchoObjectSchema<Self, Fields>;
-} = ({ typename, version }) => {
+} = (dxn) => {
+  const typename = DXN.getName(dxn);
+  const version = DXN.getVersion(dxn);
+  invariant(version, `Type.makeObject requires a versioned DXN: ${dxn}`);
+
   return <Self extends Schema.Schema.Any, Fields extends Schema.Struct.Fields = Schema.Struct.Fields>(
     self: Self & { fields?: Fields },
   ): EchoObjectSchema<Self, Fields> => {
@@ -53,6 +58,8 @@ export const EchoObjectSchema: {
       }),
     });
 
-    return makeEchoTypeSchema<Self, EntityKind.Object, Fields>(fields, ast, typename, version, EntityKind.Object);
+    return makeEchoTypeSchema<Self, EntityKind.Object, Fields>(fields, ast, typename, version, EntityKind.Object, () =>
+      toJsonSchema(Schema.make(ast)),
+    );
   };
 };

package/src/internal/Entity/relation.ts

@@ -0,0 +1,179 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+import * as SchemaAST from 'effect/SchemaAST';
+
+import { raise } from '@dxos/debug';
+import { assertArgument, invariant } from '@dxos/invariant';
+import { DXN } from '@dxos/keys';
+
+// Type-only imports (erased at runtime — no import cycle); `internal` may depend
+// on the top-level `Obj` / `Type` API at the type level only.
+import type * as Obj from '../../Obj';
+import type * as Type from '../../Type';
+import {
+  type TypeAnnotation,
+  TypeAnnotationId,
+  getEntityKind,
+  getSchemaTypename,
+  getTypeIdentifierAnnotation,
+  makeTypeJsonSchemaAnnotation,
+} from '../Annotation';
+import {
+  ATTR_RELATION_SOURCE,
+  ATTR_RELATION_TARGET,
+  EntityKind,
+  RelationSourceDXNId,
+  RelationSourceId,
+  RelationTargetDXNId,
+  RelationTargetId,
+  type UnknownTypeSchema,
+  getStaticTypeSchema,
+} from '../common/types';
+
+export {
+  ATTR_RELATION_SOURCE,
+  ATTR_RELATION_TARGET,
+  RelationSourceDXNId,
+  RelationSourceId,
+  RelationTargetDXNId,
+  RelationTargetId,
+};
+
+import { toJsonSchema } from '../JsonSchema';
+import { type EchoTypeSchema, makeEchoTypeSchema } from './entity';
+
+/**
+ * Source and target props on relations.
+ */
+// TODO(burdon): any?
+export type RelationSourceTargetRefs<Source = any, Target = any> = {
+  /**
+   * Source ECHO live object.
+   */
+  [RelationSourceId]: Source;
+
+  /**
+   * Target ECHO live object.
+   */
+  [RelationTargetId]: Target;
+};
+
+export type RelationSource<R> = R extends RelationSourceTargetRefs<infer Source, infer _Target> ? Source : never;
+export type RelationTarget<R> = R extends RelationSourceTargetRefs<infer _Source, infer Target> ? Target : never;
+
+/**
+ * Accepted relation endpoint: an object-kind `Type.Type` entity (slot-backed)
+ * or the branded `Obj.Unknown` schema. Source/target are constrained to these
+ * — relations only connect object-kind entities.
+ */
+export type RelationEndpoint = Type.AnyObj | UnknownTypeSchema<any, EntityKind.Object>;
+
+/**
+ * Resolves a relation endpoint to the instance type it describes — the source /
+ * target instance recorded on the relation's `RelationSourceTargetRefs`.
+ */
+export type RelationEndpointInstance<S> =
+  S extends UnknownTypeSchema<infer A, any> ? A : S extends Type.AnyObj ? Type.InstanceType<S> : unknown;
+
+export type EchoRelationSchemaOptions<TSource extends RelationEndpoint, TTarget extends RelationEndpoint> = {
+  dxn: DXN.DXN;
+  source: TSource;
+  target: TTarget;
+};
+
+/**
+ * Relation schema type with kind marker. `SourceInstance` / `TargetInstance`
+ * are the resolved endpoint instance types (see {@link RelationEndpointInstance}).
+ */
+export type EchoRelationSchema<
+  Self extends Schema.Schema.Any,
+  SourceInstance extends Obj.Unknown,
+  TargetInstance extends Obj.Unknown,
+  Fields extends Schema.Struct.Fields = Schema.Struct.Fields,
+> = EchoTypeSchema<Self, RelationSourceTargetRefs<SourceInstance, TargetInstance>, EntityKind.Relation, Fields>;
+
+/**
+ * Schema for Relation entity types.
+ */
+export const EchoRelationSchema = <Source extends RelationEndpoint, Target extends RelationEndpoint>({
+  dxn,
+  source,
+  target,
+}: EchoRelationSchemaOptions<Source, Target>) => {
+  // `source` / `target` are `Type.Type` entities (slot-backed) or the branded
+  // `Obj.Unknown` schema (used directly); resolve each to its Effect Schema for
+  // the schema-side machinery (DXN ref + entity-kind checks).
+  const sourceSchema = source != null ? (getStaticTypeSchema(source) ?? source) : source;
+  const targetSchema = target != null ? (getStaticTypeSchema(target) ?? target) : target;
+  assertArgument(Schema.isSchema(sourceSchema), 'source');
+  assertArgument(Schema.isSchema(targetSchema), 'target');
+  const typename = DXN.getName(dxn);
+  const version = DXN.getVersion(dxn);
+  invariant(version, `Type.makeRelation requires a versioned DXN: ${dxn}`);
+  const sourceDXN = getDXNForRelationSchemaRef(sourceSchema);
+  const targetDXN = getDXNForRelationSchemaRef(targetSchema);
+  if (getEntityKind(sourceSchema) !== EntityKind.Object) {
+    raise(new Error('Source schema must be an echo object schema.'));
+  }
+  if (getEntityKind(targetSchema) !== EntityKind.Object) {
+    raise(new Error('Target schema must be an echo object schema.'));
+  }
+
+  return <Self extends Schema.Schema.Any, Fields extends Schema.Struct.Fields = Schema.Struct.Fields>(
+    self: Self & { fields?: Fields },
+  ): EchoRelationSchema<Self, RelationEndpointInstance<Source>, RelationEndpointInstance<Target>, Fields> => {
+    invariant(SchemaAST.isTypeLiteral(self.ast), 'Schema must be a TypeLiteral.');
+
+    // Extract fields from the schema if available (Struct schemas have .fields).
+    const fields = ((self as any).fields ?? {}) as Fields;
+
+    const schemaWithId = Schema.extend(self, Schema.Struct({ id: Schema.String }));
+    const ast = SchemaAST.annotations(schemaWithId.ast, {
+      // TODO(dmaretskyi): `extend` kills the annotations.
+      ...self.ast.annotations,
+      [TypeAnnotationId]: {
+        kind: EntityKind.Relation,
+        typename,
+        version,
+        sourceSchema: sourceDXN,
+        targetSchema: targetDXN,
+      } satisfies TypeAnnotation,
+      // TODO(dmaretskyi): TypeIdentifierAnnotationId?
+
+      [SchemaAST.JSONSchemaAnnotationId]: makeTypeJsonSchemaAnnotation({
+        kind: EntityKind.Relation,
+        typename,
+        version,
+        relationSource: sourceDXN,
+        relationTarget: targetDXN,
+      }),
+    });
+
+    return makeEchoTypeSchema<Self, EntityKind.Relation, Fields>(
+      fields,
+      ast,
+      typename,
+      version,
+      EntityKind.Relation,
+      () => toJsonSchema(Schema.make(ast)),
+    );
+  };
+};
+
+export const getDXNForRelationSchemaRef = (schema: Schema.Schema.Any): DXN.DXN => {
+  assertArgument(Schema.isSchema(schema), 'schema');
+  const identifier = getTypeIdentifierAnnotation(schema);
+  if (identifier) {
+    return DXN.tryMake(identifier) ?? raise(new Error(`Invalid schema identifier: ${identifier}`));
+  }
+
+  const typename = getSchemaTypename(schema);
+  if (!typename) {
+    throw new Error('Schema must have a typename');
+  }
+
+  return DXN.make(typename);
+};