@dxos/echo-protocol 0.8.4-main.fffef41 → 0.8.4-staging.60fe92afc8

package/src/query/ast.ts

@@ -5,13 +5,14 @@
 import * as Match from 'effect/Match';
 import * as Schema from 'effect/Schema';
 
-import { DXN, ObjectId } from '@dxos/keys';
+import { EID, EntityId, URI } from '@dxos/keys';
 
 import { ForeignKey } from '../foreign-key';
 
-const TypenameSpecifier = Schema.Union(DXN.Schema, Schema.Null).annotations({
-  description: 'DXN or null. Null means any type will match',
-});
+// Type identifier URI — either a DXN (typename) or an EID (stored-schema-as-object).
+// Matches the URI written into an object's `system.type` (see `getSchemaURI`). Null
+// matches any type.
+const TypenameSpecifier = Schema.Union(URI.Schema, Schema.Null);
 
 // NOTE: This pattern with 3 definitions per schema is need to make the types opaque, and circular references in AST to not cause compiler errors.
 
@@ -26,7 +27,7 @@ const FilterObject_ = Schema.Struct({
 
   typename: TypenameSpecifier,
 
-  id: Schema.optional(Schema.Array(ObjectId)),
+  id: Schema.optional(Schema.Array(EntityId)),
 
   /**
    * Filter by property.
@@ -42,6 +43,17 @@ const FilterObject_ = Schema.Struct({
    */
   foreignKeys: Schema.optional(Schema.Array(ForeignKey)),
 
+  /**
+   * Match objects whose meta `key` equals this fully-qualified registry key (FQN format).
+   */
+  metaKey: Schema.optional(Schema.String),
+
+  /**
+   * Semver range matched against the object's meta `version`.
+   * Only consulted when {@link metaKey} is set. Objects with no `version` do not satisfy a version-constrained filter.
+   */
+  metaVersion: Schema.optional(Schema.String),
+
   // NOTE: Make sure to update `FilterStep.isNoop` if you change this.
 });
 export interface FilterObject extends Schema.Schema.Type<typeof FilterObject_> {}
@@ -75,7 +87,9 @@ const FilterContains_ = Schema.Struct({
   type: Schema.Literal('contains'),
   value: Schema.Any,
 });
+
 export interface FilterContains extends Schema.Schema.Type<typeof FilterContains_> {}
+
 /**
  * Predicate for an array property to contain the provided value.
  * Nested objects are matched using strict structural matching.
@@ -89,6 +103,7 @@ const FilterTag_ = Schema.Struct({
   type: Schema.Literal('tag'),
   tag: Schema.String, // TODO(burdon): Make OR-collection?
 });
+
 export interface FilterTag extends Schema.Schema.Type<typeof FilterTag_> {}
 export const FilterTag: Schema.Schema<FilterTag> = FilterTag_;
 
@@ -100,9 +115,24 @@ const FilterRange_ = Schema.Struct({
   from: Schema.Any,
   to: Schema.Any,
 });
+
 export interface FilterRange extends Schema.Schema.Type<typeof FilterRange_> {}
 export const FilterRange: Schema.Schema<FilterRange> = FilterRange_;
 
+/**
+ * Filter by system timestamp (createdAt / updatedAt).
+ * Timestamps are unix milliseconds stored in the object meta index.
+ */
+const FilterTimestamp_ = Schema.Struct({
+  type: Schema.Literal('timestamp'),
+  field: Schema.Literal('createdAt', 'updatedAt'),
+  operator: Schema.Literal('gt', 'gte', 'lt', 'lte'),
+  value: Schema.Number,
+});
+
+export interface FilterTimestamp extends Schema.Schema.Type<typeof FilterTimestamp_> {}
+export const FilterTimestamp: Schema.Schema<FilterTimestamp> = FilterTimestamp_;
+
 /**
  * Text search.
  */
@@ -111,6 +141,7 @@ const FilterTextSearch_ = Schema.Struct({
   text: Schema.String,
   searchKind: Schema.optional(Schema.Literal('full-text', 'vector')),
 });
+
 export interface FilterTextSearch extends Schema.Schema.Type<typeof FilterTextSearch_> {}
 export const FilterTextSearch: Schema.Schema<FilterTextSearch> = FilterTextSearch_;
 
@@ -121,6 +152,7 @@ const FilterNot_ = Schema.Struct({
   type: Schema.Literal('not'),
   filter: Schema.suspend(() => Filter),
 });
+
 export interface FilterNot extends Schema.Schema.Type<typeof FilterNot_> {}
 export const FilterNot: Schema.Schema<FilterNot> = FilterNot_;
 
@@ -131,6 +163,7 @@ const FilterAnd_ = Schema.Struct({
   type: Schema.Literal('and'),
   filters: Schema.Array(Schema.suspend(() => Filter)),
 });
+
 export interface FilterAnd extends Schema.Schema.Type<typeof FilterAnd_> {}
 export const FilterAnd: Schema.Schema<FilterAnd> = FilterAnd_;
 
@@ -141,9 +174,25 @@ const FilterOr_ = Schema.Struct({
   type: Schema.Literal('or'),
   filters: Schema.Array(Schema.suspend(() => Filter)),
 });
+
 export interface FilterOr extends Schema.Schema.Type<typeof FilterOr_> {}
 export const FilterOr: Schema.Schema<FilterOr> = FilterOr_;
 
+/**
+ * Filter objects that are children of the specified parents.
+ * With transitive=true (default), matches grandchildren and beyond.
+ */
+const FilterChildOf_ = Schema.Struct({
+  type: Schema.Literal('child-of'),
+  /** Parent DXNs to match children of. */
+  parents: Schema.Array(EID.Schema),
+  /** Whether to match transitively (grandchildren, etc.). Defaults to true. */
+  transitive: Schema.Boolean,
+});
+
+export interface FilterChildOf extends Schema.Schema.Type<typeof FilterChildOf_> {}
+export const FilterChildOf: Schema.Schema<FilterChildOf> = FilterChildOf_;
+
 /**
  * Union of filters.
  */
@@ -154,11 +203,14 @@ export const Filter = Schema.Union(
   FilterContains,
   FilterTag,
   FilterRange,
+  FilterTimestamp,
   FilterTextSearch,
+  FilterChildOf,
   FilterNot,
   FilterAnd,
   FilterOr,
-).annotations({ identifier: 'dxos.org/schema/Filter' });
+).annotations({ identifier: 'org.dxos.schema.filter' });
+
 export type Filter = Schema.Schema.Type<typeof Filter>;
 
 /**
@@ -168,6 +220,7 @@ const QuerySelectClause_ = Schema.Struct({
   type: Schema.Literal('select'),
   filter: Schema.suspend(() => Filter),
 });
+
 export interface QuerySelectClause extends Schema.Schema.Type<typeof QuerySelectClause_> {}
 export const QuerySelectClause: Schema.Schema<QuerySelectClause> = QuerySelectClause_;
 
@@ -179,6 +232,7 @@ const QueryFilterClause_ = Schema.Struct({
   selection: Schema.suspend(() => Query),
   filter: Schema.suspend(() => Filter),
 });
+
 export interface QueryFilterClause extends Schema.Schema.Type<typeof QueryFilterClause_> {}
 export const QueryFilterClause: Schema.Schema<QueryFilterClause> = QueryFilterClause_;
 
@@ -190,6 +244,7 @@ const QueryReferenceTraversalClause_ = Schema.Struct({
   anchor: Schema.suspend(() => Query),
   property: Schema.String, // TODO(dmaretskyi): Change to EscapedPropPath.
 });
+
 export interface QueryReferenceTraversalClause extends Schema.Schema.Type<typeof QueryReferenceTraversalClause_> {}
 export const QueryReferenceTraversalClause: Schema.Schema<QueryReferenceTraversalClause> =
   QueryReferenceTraversalClause_;
@@ -200,9 +255,14 @@ export const QueryReferenceTraversalClause: Schema.Schema<QueryReferenceTraversa
 const QueryIncomingReferencesClause_ = Schema.Struct({
   type: Schema.Literal('incoming-references'),
   anchor: Schema.suspend(() => Query),
-  property: Schema.String,
+  /**
+   * Property path where the reference is located.
+   * If null, matches references from any property.
+   */
+  property: Schema.NullOr(Schema.String),
   typename: TypenameSpecifier,
 });
+
 export interface QueryIncomingReferencesClause extends Schema.Schema.Type<typeof QueryIncomingReferencesClause_> {}
 export const QueryIncomingReferencesClause: Schema.Schema<QueryIncomingReferencesClause> =
   QueryIncomingReferencesClause_;
@@ -221,6 +281,7 @@ const QueryRelationClause_ = Schema.Struct({
   direction: Schema.Literal('outgoing', 'incoming', 'both'),
   filter: Schema.optional(Schema.suspend(() => Filter)),
 });
+
 export interface QueryRelationClause extends Schema.Schema.Type<typeof QueryRelationClause_> {}
 export const QueryRelationClause: Schema.Schema<QueryRelationClause> = QueryRelationClause_;
 
@@ -232,9 +293,27 @@ const QueryRelationTraversalClause_ = Schema.Struct({
   anchor: Schema.suspend(() => Query),
   direction: Schema.Literal('source', 'target', 'both'),
 });
+
 export interface QueryRelationTraversalClause extends Schema.Schema.Type<typeof QueryRelationTraversalClause_> {}
 export const QueryRelationTraversalClause: Schema.Schema<QueryRelationTraversalClause> = QueryRelationTraversalClause_;
 
+/**
+ * Traverse parent-child hierarchy.
+ */
+const QueryHierarchyTraversalClause_ = Schema.Struct({
+  type: Schema.Literal('hierarchy-traversal'),
+  anchor: Schema.suspend(() => Query),
+  /**
+   * to-parent: traverse from child to parent.
+   * to-children: traverse from parent to children.
+   */
+  direction: Schema.Literal('to-parent', 'to-children'),
+});
+
+export interface QueryHierarchyTraversalClause extends Schema.Schema.Type<typeof QueryHierarchyTraversalClause_> {}
+export const QueryHierarchyTraversalClause: Schema.Schema<QueryHierarchyTraversalClause> =
+  QueryHierarchyTraversalClause_;
+
 /**
  * Union of multiple queries.
  */
@@ -242,6 +321,7 @@ const QueryUnionClause_ = Schema.Struct({
   type: Schema.Literal('union'),
   queries: Schema.Array(Schema.suspend(() => Query)),
 });
+
 export interface QueryUnionClause extends Schema.Schema.Type<typeof QueryUnionClause_> {}
 export const QueryUnionClause: Schema.Schema<QueryUnionClause> = QueryUnionClause_;
 
@@ -253,6 +333,7 @@ const QuerySetDifferenceClause_ = Schema.Struct({
   source: Schema.suspend(() => Query),
   exclude: Schema.suspend(() => Query),
 });
+
 export interface QuerySetDifferenceClause extends Schema.Schema.Type<typeof QuerySetDifferenceClause_> {}
 export const QuerySetDifferenceClause: Schema.Schema<QuerySetDifferenceClause> = QuerySetDifferenceClause_;
 
@@ -269,7 +350,20 @@ const Order_ = Schema.Union(
     property: Schema.String,
     direction: OrderDirection,
   }),
+  Schema.Struct({
+    // Order by relevance rank (for FTS/vector search results).
+    // Default direction is 'desc' (higher rank = better match first).
+    kind: Schema.Literal('rank'),
+    direction: OrderDirection,
+  }),
+  Schema.Struct({
+    // Order by system timestamp (createdAt / updatedAt) from the object meta index.
+    kind: Schema.Literal('timestamp'),
+    field: Schema.Literal('createdAt', 'updatedAt'),
+    direction: OrderDirection,
+  }),
 );
+
 export type Order = Schema.Schema.Type<typeof Order_>;
 export const Order: Schema.Schema<Order> = Order_;
 
@@ -282,6 +376,7 @@ const QueryOrderClause_ = Schema.Struct({
   query: Schema.suspend(() => Query),
   order: Schema.Array(Order),
 });
+
 export interface QueryOrderClause extends Schema.Schema.Type<typeof QueryOrderClause_> {}
 export const QueryOrderClause: Schema.Schema<QueryOrderClause> = QueryOrderClause_;
 
@@ -293,9 +388,37 @@ const QueryOptionsClause_ = Schema.Struct({
   query: Schema.suspend(() => Query),
   options: Schema.suspend(() => QueryOptions),
 });
+
 export interface QueryOptionsClause extends Schema.Schema.Type<typeof QueryOptionsClause_> {}
 export const QueryOptionsClause: Schema.Schema<QueryOptionsClause> = QueryOptionsClause_;
 
+/**
+ * Limit the number of results.
+ */
+const QueryLimitClause_ = Schema.Struct({
+  type: Schema.Literal('limit'),
+  query: Schema.suspend(() => Query),
+  limit: Schema.Number,
+});
+
+export interface QueryLimitClause extends Schema.Schema.Type<typeof QueryLimitClause_> {}
+export const QueryLimitClause: Schema.Schema<QueryLimitClause> = QueryLimitClause_;
+
+export const QueryFromClause_ = Schema.Struct({
+  type: Schema.Literal('from'),
+  query: Schema.suspend(() => Query),
+  from: Schema.Union(
+    Schema.TaggedStruct('scope', {
+      scopes: Schema.Array(Schema.suspend(() => Scope)),
+    }),
+    Schema.TaggedStruct('query', {
+      query: Schema.suspend(() => Query),
+    }),
+  ),
+});
+export interface QueryFromClause extends Schema.Schema.Type<typeof QueryFromClause_> {}
+export const QueryFromClause: Schema.Schema<QueryFromClause> = QueryFromClause_;
+
 const Query_ = Schema.Union(
   QuerySelectClause,
   QueryFilterClause,
@@ -303,37 +426,73 @@ const Query_ = Schema.Union(
   QueryIncomingReferencesClause,
   QueryRelationClause,
   QueryRelationTraversalClause,
+  QueryHierarchyTraversalClause,
   QueryUnionClause,
   QuerySetDifferenceClause,
   QueryOrderClause,
   QueryOptionsClause,
-).annotations({ identifier: 'dxos.org/schema/Query' });
+  QueryLimitClause,
+  QueryFromClause,
+).annotations({ identifier: 'org.dxos.schema.query' });
 
 export type Query = Schema.Schema.Type<typeof Query_>;
 export const Query: Schema.Schema<Query> = Query_;
 
 export const QueryOptions = Schema.Struct({
   /**
-   * The nested select statemets will select from the given spaces.
-   *
-   * NOTE: Spaces and queues are unioned together if both are specified.
-   */
-  spaceIds: Schema.optional(Schema.Array(Schema.String)),
-
-  /**
-   * The nested select statemets will select from the given queues.
-   *
-   * NOTE: Spaces and queues are unioned together if both are specified.
+   * Nested select statements will use this option to filter deleted objects.
    */
-  queues: Schema.optional(Schema.Array(DXN.Schema)),
+  deleted: Schema.optional(Schema.Literal('include', 'exclude', 'only')),
 
   /**
-   * Nested select statements will use this option to filter deleted objects.
+   * Diagnostics-only label for logs / tooling (not used by execution semantics).
    */
-  deleted: Schema.optional(Schema.Literal('include', 'exclude', 'only')),
+  debugLabel: Schema.optional(Schema.String),
 });
+
 export interface QueryOptions extends Schema.Schema.Type<typeof QueryOptions> {}
 
+/**
+ * Selects from a space (automerge documents).
+ * When `spaceId` is omitted, targets the owning space — i.e. the space of whichever
+ * database executes the query. This lets callers reference "this space" without
+ * having to look up its id.
+ * When `includeAllFeeds` is true, also selects from all feeds belonging to that space.
+ */
+export const SpaceScope = Schema.TaggedStruct('space', {
+  spaceId: Schema.optional(Schema.String),
+  includeAllFeeds: Schema.optional(Schema.Boolean),
+});
+export interface SpaceScope extends Schema.Schema.Type<typeof SpaceScope> {}
+
+/**
+ * Selects from a specific feed (by its underlying queue DXN).
+ */
+export const FeedScope = Schema.TaggedStruct('feed', {
+  feedUri: Schema.String,
+});
+export interface FeedScope extends Schema.Schema.Type<typeof FeedScope> {}
+
+/**
+ * Selects from a code-shipped object registry.
+ *
+ * - `'local'`  — the in-process registry attached to the hypergraph.
+ * - `'remote'` — a future remote registry service (not yet implemented).
+ *
+ * To include both, add two separate `RegistryScope` entries to the `scopes` array.
+ */
+export const RegistryScope = Schema.TaggedStruct('registry', {
+  location: Schema.Literal('local', 'remote'),
+});
+export interface RegistryScope extends Schema.Schema.Type<typeof RegistryScope> {}
+
+/**
+ * Specifies the scope of the data to query from.
+ * A `from` clause may carry multiple scopes; results are unioned across them.
+ */
+export const Scope = Schema.Union(SpaceScope, FeedScope, RegistryScope);
+export type Scope = Schema.Schema.Type<typeof Scope>;
+
 export const visit = (query: Query, visitor: (node: Query) => void) => {
   visitor(query);
 
@@ -344,17 +503,57 @@ export const visit = (query: Query, visitor: (node: Query) => void) => {
     Match.when({ type: 'relation' }, ({ anchor }) => visit(anchor, visitor)),
     Match.when({ type: 'options' }, ({ query }) => visit(query, visitor)),
     Match.when({ type: 'relation-traversal' }, ({ anchor }) => visit(anchor, visitor)),
+    Match.when({ type: 'hierarchy-traversal' }, ({ anchor }) => visit(anchor, visitor)),
     Match.when({ type: 'union' }, ({ queries }) => queries.forEach((q) => visit(q, visitor))),
     Match.when({ type: 'set-difference' }, ({ source, exclude }) => {
       visit(source, visitor);
       visit(exclude, visitor);
     }),
     Match.when({ type: 'order' }, ({ query }) => visit(query, visitor)),
+    Match.when({ type: 'limit' }, ({ query }) => visit(query, visitor)),
+    Match.when({ type: 'from' }, (node) => {
+      visit(node.query, visitor);
+      if (node.from._tag === 'query') {
+        visit(node.from.query, visitor);
+      }
+    }),
     Match.when({ type: 'select' }, () => {}),
     Match.exhaustive,
   );
 };
 
+/**
+ * Recursively transforms a query tree bottom-up.
+ * The mapper receives each node with its children already transformed.
+ */
+export const map = (query: Query, mapper: (node: Query) => Query): Query => {
+  const mapped: Query = Match.value(query).pipe(
+    Match.when({ type: 'filter' }, (node) => ({ ...node, selection: map(node.selection, mapper) })),
+    Match.when({ type: 'reference-traversal' }, (node) => ({ ...node, anchor: map(node.anchor, mapper) })),
+    Match.when({ type: 'incoming-references' }, (node) => ({ ...node, anchor: map(node.anchor, mapper) })),
+    Match.when({ type: 'relation' }, (node) => ({ ...node, anchor: map(node.anchor, mapper) })),
+    Match.when({ type: 'relation-traversal' }, (node) => ({ ...node, anchor: map(node.anchor, mapper) })),
+    Match.when({ type: 'hierarchy-traversal' }, (node) => ({ ...node, anchor: map(node.anchor, mapper) })),
+    Match.when({ type: 'options' }, (node) => ({ ...node, query: map(node.query, mapper) })),
+    Match.when({ type: 'order' }, (node) => ({ ...node, query: map(node.query, mapper) })),
+    Match.when({ type: 'limit' }, (node) => ({ ...node, query: map(node.query, mapper) })),
+    Match.when({ type: 'from' }, (node) => ({
+      ...node,
+      query: map(node.query, mapper),
+      ...(node.from._tag === 'query' ? { from: { _tag: 'query' as const, query: map(node.from.query, mapper) } } : {}),
+    })),
+    Match.when({ type: 'union' }, (node) => ({ ...node, queries: node.queries.map((q) => map(q, mapper)) })),
+    Match.when({ type: 'set-difference' }, (node) => ({
+      ...node,
+      source: map(node.source, mapper),
+      exclude: map(node.exclude, mapper),
+    })),
+    Match.when({ type: 'select' }, (node) => node),
+    Match.exhaustive,
+  );
+  return mapper(mapped);
+};
+
 export const fold = <T>(query: Query, reducer: (node: Query) => T): T[] => {
   return Match.value(query).pipe(
     Match.withReturnType<T[]>(),
@@ -364,11 +563,20 @@ export const fold = <T>(query: Query, reducer: (node: Query) => T): T[] => {
     Match.when({ type: 'relation' }, ({ anchor }) => fold(anchor, reducer)),
     Match.when({ type: 'options' }, ({ query }) => fold(query, reducer)),
     Match.when({ type: 'relation-traversal' }, ({ anchor }) => fold(anchor, reducer)),
+    Match.when({ type: 'hierarchy-traversal' }, ({ anchor }) => fold(anchor, reducer)),
     Match.when({ type: 'union' }, ({ queries }) => queries.flatMap((q) => fold(q, reducer))),
     Match.when({ type: 'set-difference' }, ({ source, exclude }) =>
       fold(source, reducer).concat(fold(exclude, reducer)),
     ),
     Match.when({ type: 'order' }, ({ query }) => fold(query, reducer)),
+    Match.when({ type: 'limit' }, ({ query }) => fold(query, reducer)),
+    Match.when({ type: 'from' }, (node) => {
+      const results = fold(node.query, reducer);
+      if (node.from._tag === 'query') {
+        return results.concat(fold(node.from.query, reducer));
+      }
+      return results;
+    }),
     Match.when({ type: 'select' }, () => []),
     Match.exhaustive,
   );

package/src/reference.ts

@@ -3,126 +3,7 @@
 //
 
 import { assertArgument } from '@dxos/invariant';
-import { DXN, LOCAL_SPACE_TAG, type PublicKey } from '@dxos/keys';
-import { type ObjectId } from '@dxos/protocols';
-import { type Reference as ReferenceProto } from '@dxos/protocols/proto/dxos/echo/model/document';
-
-/**
- * Runtime representation of an reference in ECHO.
- * Implemented as a DXN, but we might extend it to other URIs in the future.
- * @deprecated Use `EncodedReference` instead.
- */
-export class Reference {
-  /**
-   * Protocol references to runtime registered types.
-   * @deprecated
-   */
-  static TYPE_PROTOCOL = 'protobuf';
-
-  static fromDXN(dxn: DXN): Reference {
-    switch (dxn.kind) {
-      case DXN.kind.TYPE:
-        return new Reference(dxn.parts[0], Reference.TYPE_PROTOCOL, 'dxos.org', dxn);
-      case DXN.kind.ECHO:
-        if (dxn.parts[0] === LOCAL_SPACE_TAG) {
-          return new Reference(dxn.parts[1], undefined, undefined, dxn);
-        } else {
-          return new Reference(dxn.parts[1], undefined, dxn.parts[0], dxn);
-        }
-      default:
-        return new Reference(dxn.parts[0], undefined, dxn.parts[0], dxn);
-    }
-  }
-
-  static fromValue(value: ReferenceProto): Reference {
-    return new Reference(value.objectId, value.protocol, value.host);
-  }
-
-  /**
-   * Reference an object in the local space.
-   */
-  static localObjectReference(objectId: ObjectId): Reference {
-    return new Reference(objectId);
-  }
-
-  /**
-   * @deprecated
-   */
-  // TODO(dmaretskyi): Remove.
-  static fromLegacyTypename(type: string): Reference {
-    return new Reference(type, Reference.TYPE_PROTOCOL, 'dxos.org');
-  }
-
-  /**
-   * @deprecated
-   */
-  // TODO(dmaretskyi): Remove
-  static fromObjectIdAndSpaceKey(objectId: ObjectId, spaceKey: PublicKey): Reference {
-    // TODO(dmaretskyi): FIX ME! This should be a space ID not a space key.
-    return new Reference(objectId, undefined, spaceKey.toHex());
-  }
-
-  // prettier-ignore
-  private constructor(
-    // TODO(dmaretskyi): Remove and just leave DXN.
-    private readonly _objectId: ObjectId,
-    private readonly _protocol?: string,
-    private readonly _host?: string,
-    private readonly _dxn?: DXN,
-  ) {}
-
-  get dxn(): DXN | undefined {
-    return this._dxn;
-  }
-
-  /**
-   * @deprecated
-   */
-  // TODO(dmaretskyi): Remove.
-  get objectId(): ObjectId {
-    return this._objectId;
-  }
-
-  /**
-   * @deprecated
-   */
-  // TODO(dmaretskyi): Remove.
-  get protocol(): string | undefined {
-    return this._protocol;
-  }
-
-  /**
-   * @deprecated
-   */
-  // TODO(dmaretskyi): Remove.
-  get host(): string | undefined {
-    return this._host;
-  }
-
-  encode(): ReferenceProto {
-    return { objectId: this.objectId, host: this.host, protocol: this.protocol };
-  }
-
-  // TODO(dmaretskyi): Remove in favor of `reference.dxn`.
-  toDXN(): DXN {
-    if (this._dxn) {
-      return this._dxn;
-    }
-
-    if (this.protocol === Reference.TYPE_PROTOCOL) {
-      return new DXN(DXN.kind.TYPE, [this.objectId]);
-    } else {
-      if (this.host) {
-        // Host is assumed to be the space key.
-        // The DXN should actually have the space ID.
-        // TODO(dmaretskyi): Migrate to space id.
-        return new DXN(DXN.kind.ECHO, [this.host, this.objectId]);
-      } else {
-        return new DXN(DXN.kind.ECHO, [LOCAL_SPACE_TAG, this.objectId]);
-      }
-    }
-  }
-}
+import { URI } from '@dxos/keys';
 
 // TODO(dmaretskyi): Is this used anywhere?
 export const REFERENCE_TYPE_TAG = 'dxos.echo.model.document.Reference';
@@ -131,52 +12,26 @@ export const REFERENCE_TYPE_TAG = 'dxos.echo.model.document.Reference';
  * Reference as it is stored in Automerge document.
  */
 export type EncodedReference = {
-  '/': string;
+  '/': URI.URI;
 };
 
-/**
- * @deprecated Use `EncodedReference.fromDXN` instead.
- */
-export const encodeReference = (reference: Reference): EncodedReference => ({
-  '/': reference.toDXN().toString(),
-});
-
-/**
- * @deprecated Use `EncodedReference.toDXN` instead.
- */
-export const decodeReference = (value: any) => {
-  if (typeof value !== 'object' || value === null || typeof value['/'] !== 'string') {
-    throw new Error('Invalid reference');
-  }
-  const dxnString = value['/'];
-
-  if (
-    dxnString.length % 2 === 0 &&
-    dxnString.slice(0, dxnString.length / 2) === dxnString.slice(dxnString.length / 2) &&
-    dxnString.includes('dxn:echo')
-  ) {
-    throw new Error('Automerge bug detected!');
-  }
-
-  return Reference.fromDXN(DXN.parse(dxnString));
-};
-
-/**
- * @deprecated Use `EncodedReference.isEncodedReference` instead.
- */
 export const isEncodedReference = (value: any): value is EncodedReference =>
   typeof value === 'object' && value !== null && Object.keys(value).length === 1 && typeof value['/'] === 'string';
 
 export const EncodedReference = Object.freeze({
   isEncodedReference,
-  getReferenceString: (value: EncodedReference): string => {
+  /**
+   * Returns the opaque URI stored in the encoded reference (any scheme: `echo:` or `dxn:`).
+   * Consumers can narrow with `EID.isEID(uri)` / `DXN.isDXN(uri)`.
+   */
+  toURI: (value: EncodedReference): URI.URI => {
     assertArgument(isEncodedReference(value), 'value', 'invalid reference');
     return value['/'];
   },
-  toDXN: (value: EncodedReference): DXN => {
-    return DXN.parse(EncodedReference.getReferenceString(value));
-  },
-  fromDXN: (dxn: DXN): EncodedReference => {
-    return encodeReference(Reference.fromDXN(dxn));
+  /**
+   * Creates an encoded reference from an opaque URI.
+   */
+  fromURI: (uri: URI.URI): EncodedReference => {
+    return { '/': uri };
   },
 });