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

package/src/internal/Query.ts

@@ -0,0 +1,156 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type QueryAST } from '@dxos/echo-protocol';
+
+/**
+ * Returns a human-readable string representation of a Filter AST.
+ */
+export const prettyFilter = (filter: QueryAST.Filter): string => {
+  switch (filter.type) {
+    case 'object': {
+      // A type-less object filter with only a meta-key constraint is `Filter.key(...)`.
+      if (
+        filter.typename === null &&
+        (filter.id === undefined || filter.id.length === 0) &&
+        Object.keys(filter.props).length === 0 &&
+        (filter.foreignKeys === undefined || filter.foreignKeys.length === 0) &&
+        filter.metaKey !== undefined
+      ) {
+        return filter.metaVersion !== undefined
+          ? `Filter.key(${JSON.stringify(filter.metaKey)}, { version: ${JSON.stringify(filter.metaVersion)} })`
+          : `Filter.key(${JSON.stringify(filter.metaKey)})`;
+      }
+      const parts: string[] = [];
+      if (filter.typename !== null) {
+        parts.push(String(filter.typename));
+      }
+      if (filter.id !== undefined && filter.id.length > 0) {
+        parts.push(`id: [${filter.id.join(', ')}]`);
+      }
+      const propEntries = Object.entries(filter.props);
+      if (propEntries.length > 0) {
+        const propsStr = propEntries.map(([k, v]) => `${k}: ${prettyFilter(v)}`).join(', ');
+        parts.push(`{ ${propsStr} }`);
+      }
+      if (filter.foreignKeys !== undefined && filter.foreignKeys.length > 0) {
+        parts.push(`foreignKeys: [${filter.foreignKeys.map((fk) => JSON.stringify(fk)).join(', ')}]`);
+      }
+      if (filter.metaKey !== undefined) {
+        parts.push(
+          filter.metaVersion !== undefined
+            ? `metaKey: ${JSON.stringify(filter.metaKey)} (${filter.metaVersion})`
+            : `metaKey: ${JSON.stringify(filter.metaKey)}`,
+        );
+      }
+      return parts.length > 0 ? `Filter.type(${parts.join(', ')})` : 'Filter.everything()';
+    }
+    case 'compare':
+      return `Filter.${filter.operator}(${JSON.stringify(filter.value)})`;
+    case 'in':
+      return `Filter.in([${filter.values.map((v) => JSON.stringify(v)).join(', ')}])`;
+    case 'contains':
+      return `Filter.contains(${JSON.stringify(filter.value)})`;
+    case 'tag':
+      return `Filter.tag(${JSON.stringify(filter.tag)})`;
+    case 'range':
+      return `Filter.range(${JSON.stringify(filter.from)}, ${JSON.stringify(filter.to)})`;
+    case 'text-search':
+      return filter.searchKind
+        ? `Filter.textSearch(${JSON.stringify(filter.text)}, ${JSON.stringify(filter.searchKind)})`
+        : `Filter.textSearch(${JSON.stringify(filter.text)})`;
+    case 'timestamp':
+      return `Filter.${filter.field}.${filter.operator}(${filter.value})`;
+    case 'child-of':
+      return `Filter.childOf([${filter.parents.map((p) => JSON.stringify(p)).join(', ')}], { transitive: ${filter.transitive} })`;
+    case 'not':
+      return `Filter.not(${prettyFilter(filter.filter)})`;
+    case 'and':
+      return `Filter.and(${filter.filters.map(prettyFilter).join(', ')})`;
+    case 'or':
+      return `Filter.or(${filter.filters.map(prettyFilter).join(', ')})`;
+  }
+};
+
+/**
+ * Returns a human-readable string representation of a Query AST.
+ */
+export const prettyQuery = (query: QueryAST.Query): string => {
+  switch (query.type) {
+    case 'select':
+      return `Query.select(${prettyFilter(query.filter)})`;
+    case 'filter':
+      return `${prettyQuery(query.selection)}.select(${prettyFilter(query.filter)})`;
+    case 'reference-traversal':
+      return `${prettyQuery(query.anchor)}.reference(${JSON.stringify(query.property)})`;
+    case 'incoming-references': {
+      const args: string[] = [];
+      if (query.typename !== null) {
+        args.push(String(query.typename));
+      }
+      if (query.property !== null) {
+        args.push(JSON.stringify(query.property));
+      }
+      return `${prettyQuery(query.anchor)}.referencedBy(${args.join(', ')})`;
+    }
+    case 'relation': {
+      const method =
+        query.direction === 'outgoing' ? 'sourceOf' : query.direction === 'incoming' ? 'targetOf' : 'relationOf';
+      const filterStr = query.filter !== undefined ? prettyFilter(query.filter) : '';
+      return `${prettyQuery(query.anchor)}.${method}(${filterStr})`;
+    }
+    case 'relation-traversal':
+      return `${prettyQuery(query.anchor)}.${query.direction}()`;
+    case 'hierarchy-traversal':
+      return query.direction === 'to-parent'
+        ? `${prettyQuery(query.anchor)}.parent()`
+        : `${prettyQuery(query.anchor)}.children()`;
+    case 'union':
+      return `Query.all(${query.queries.map(prettyQuery).join(', ')})`;
+    case 'set-difference':
+      return `Query.without(${prettyQuery(query.source)}, ${prettyQuery(query.exclude)})`;
+    case 'order': {
+      const orders = query.order.map((o) => {
+        if (o.kind === 'natural') {
+          return 'Order.natural()';
+        } else if (o.kind === 'rank') {
+          return `Order.rank(${JSON.stringify(o.direction)})`;
+        } else {
+          return `Order.property(${JSON.stringify(o.property)}, ${JSON.stringify(o.direction)})`;
+        }
+      });
+      return `${prettyQuery(query.query)}.orderBy(${orders.join(', ')})`;
+    }
+    case 'options': {
+      const opts = query.options;
+      const parts: string[] = [];
+      if (opts.deleted !== undefined) {
+        parts.push(`deleted: ${JSON.stringify(opts.deleted)}`);
+      }
+      if (opts.debugLabel !== undefined) {
+        parts.push(`debugLabel: ${JSON.stringify(opts.debugLabel)}`);
+      }
+      return `${prettyQuery(query.query)}.options({ ${parts.join(', ')} })`;
+    }
+    case 'from': {
+      if (query.from._tag === 'scope') {
+        const scope = query.from.scope;
+        const parts: string[] = [];
+        if (scope.spaceIds !== undefined) {
+          parts.push(`spaceIds: [${scope.spaceIds.map((s) => JSON.stringify(s)).join(', ')}]`);
+        }
+        if (scope.feeds !== undefined) {
+          parts.push(`feeds: [${scope.feeds.map(String).join(', ')}]`);
+        }
+        if (scope.allFeedsFromSpaces !== undefined) {
+          parts.push(`allFeedsFromSpaces: ${scope.allFeedsFromSpaces}`);
+        }
+        return `${prettyQuery(query.query)}.from({ ${parts.join(', ')} })`;
+      }
+      return `${prettyQuery(query.query)}.from(${prettyQuery(query.from.query)})`;
+    }
+    case 'limit':
+      return `${prettyQuery(query.query)}.limit(${query.limit})`;
+  }
+};

package/src/internal/{ref → Ref}/ref-array.ts

@@ -5,8 +5,7 @@
 import { type ObjectId } from '@dxos/keys';
 import { isNonNullable } from '@dxos/util';
 
-import { type AnyEntity } from '../types';
-
+import { type AnyEntity } from '../common/types';
 import { Ref } from './ref';
 
 /**

package/src/internal/{ref → Ref}/ref.test.ts

@@ -5,47 +5,37 @@
 import * as Schema from 'effect/Schema';
 import { describe, expect, test } from 'vitest';
 
-import { DXN, ObjectId } from '@dxos/keys';
-
-import { EchoObjectSchema, getObjectDXN } from '../entities';
-import { createObject } from '../object';
+import { EchoURI, ObjectId, DXN } from '@dxos/keys';
 
+import * as Type from '../../Type';
+import { EchoObjectSchema, getObjectEchoUri } from '../Entity';
+import { createObject } from '../Obj';
 import { Ref, getReferenceAst } from './ref';
 
 const Task = Schema.Struct({
   title: Schema.optional(Schema.String),
-}).pipe(
-  EchoObjectSchema({
-    typename: 'example.com/type/Task',
-    version: '0.1.0',
-  }),
-);
+}).pipe(EchoObjectSchema(DXN.make('com.example.type.task', '0.1.0')));
 
-type Task = Schema.Schema.Type<typeof Task>;
+type Task = Type.InstanceType<typeof Task>;
 
 const Contact = Schema.Struct({
   name: Schema.String,
   email: Schema.optional(Schema.String),
   tasks: Schema.Array(Ref(Task)),
-}).pipe(
-  EchoObjectSchema({
-    typename: 'example.com/type/Person',
-    version: '0.1.0',
-  }),
-);
+}).pipe(EchoObjectSchema(DXN.make('com.example.type.person', '0.1.0')));
 
-type Contact = Schema.Schema.Type<typeof Contact>;
+type Contact = Type.InstanceType<typeof Contact>;
 
 describe('Ref', () => {
   test('Schema is', () => {
-    Ref(Contact).pipe(Schema.is)(Ref.fromDXN(DXN.parse(`dxn:echo:@:${ObjectId.random()}`)));
+    Ref(Contact).pipe(Schema.is)(Ref.fromURI(EchoURI.make({ objectId: ObjectId.random() })));
   });
 
   test('ref ast', () => {
     const ref = Ref(Task);
     expect(ref.ast._tag).toEqual('Declaration');
     const refAst = getReferenceAst(ref.ast);
-    expect(refAst).toEqual({ typename: Task.typename, version: Task.version });
+    expect(refAst).toEqual({ typename: Type.getTypename(Task), version: Type.getVersion(Task) });
   });
 
   // TODO(dmaretskyi): Figure out how to expose this in the API.
@@ -56,14 +46,14 @@ describe('Ref', () => {
     const json = JSON.parse(JSON.stringify(contact));
     expect(json).toEqual({
       id: contact.id,
-      '@type': `dxn:type:${Contact.typename}:${Contact.version}`,
+      '@type': `dxn:${Type.getTypename(Contact)}:${Type.getVersion(Contact)}`,
       '@meta': {
         keys: [],
       },
       name: 'John Doe',
       tasks: [
         {
-          '/': getObjectDXN(task as any)!.toString(),
+          '/': getObjectEchoUri(task)!.toString(),
           target: JSON.parse(JSON.stringify(task)),
         },
       ],
@@ -77,12 +67,12 @@ describe('Ref', () => {
     const json = JSON.parse(JSON.stringify(contact));
     expect(json).toEqual({
       id: contact.id,
-      '@type': `dxn:type:${Contact.typename}:${Contact.version}`,
+      '@type': `dxn:${Type.getTypename(Contact)}:${Type.getVersion(Contact)}`,
       '@meta': {
         keys: [],
       },
       name: 'John Doe',
-      tasks: [{ '/': getObjectDXN(task)!.toString() }],
+      tasks: [{ '/': getObjectEchoUri(task)!.toString() }],
     });
   });
 
@@ -94,8 +84,8 @@ describe('Ref', () => {
       tasks: [{ '/': `dxn:echo:@:${id}` }],
     };
 
-    const contact = Contact.pipe(Schema.decodeUnknownSync)(contactData);
+    const contact = Type.getSchema(Contact).pipe(Schema.decodeUnknownSync)(contactData);
     expect(Ref.isRef(contact.tasks[0])).toEqual(true);
-    expect(contact.tasks[0].dxn.toString()).toEqual(`dxn:echo:@:${id}`);
+    expect(contact.tasks[0].uri.toString()).toEqual(`dxn:echo:@:${id}`);
   });
 });

package/src/internal/{ref → Ref}/ref.ts

@@ -16,12 +16,13 @@ import { Event } from '@dxos/async';
 import { type CustomInspectFunction, inspectCustom } from '@dxos/debug';
 import { EncodedReference } from '@dxos/echo-protocol';
 import { assertArgument, invariant } from '@dxos/invariant';
-import { DXN, ObjectId } from '@dxos/keys';
+import { DXN, EchoURI, ObjectId, type URI } from '@dxos/keys';
 
 import * as Database from '../../Database';
-import { ReferenceAnnotationId, getSchemaDXN, getTypeAnnotation, getTypeIdentifierAnnotation } from '../annotations';
-import { type JsonSchemaType } from '../json-schema';
-import type { AnyEntity, AnyProperties } from '../types';
+import type * as Type from '../../Type';
+import { ReferenceAnnotationId, getSchemaURI, getTypeAnnotation, getTypeIdentifierAnnotation } from '../Annotation';
+import { type AnyEntity, type AnyProperties, type UnknownTypeSchema, getStaticTypeSchema } from '../common/types';
+import { type JsonSchemaType } from '../JsonSchema';
 
 /**
  * The `$id` and `$ref` fields for an ECHO reference schema.
@@ -31,7 +32,9 @@ export const JSON_SCHEMA_ECHO_REF_ID = '/schemas/echo/ref';
 export const getSchemaReference = (property: JsonSchemaType): { typename: string } | undefined => {
   const { $id, reference: { schema: { $ref } = {} } = {} } = property;
   if ($id === JSON_SCHEMA_ECHO_REF_ID && $ref) {
-    return { typename: DXN.parse($ref).typename };
+    const parsed = DXN.tryMake($ref);
+    const typename = parsed ? DXN.getName(parsed) : undefined;
+    return typename ? { typename } : undefined;
   }
 };
 
@@ -40,7 +43,7 @@ export const createSchemaReference = (typename: string): Types.DeepMutable<JsonS
     $id: JSON_SCHEMA_ECHO_REF_ID,
     reference: {
       schema: {
-        $ref: DXN.fromTypename(typename).toString(),
+        $ref: DXN.make(typename),
       },
     },
   };
@@ -82,7 +85,27 @@ export interface RefSchema<T extends AnyEntity> extends Schema.SchemaClass<Ref<T
  * Type of the `Ref` function and extra methods attached to it.
  */
 export interface RefFn {
-  <S extends Schema.Schema.Any>(schema: S): RefSchema<Schema.Schema.Type<S>>;
+  // A reference target is a `Type.AnyEntity` entity (the canonical Option B
+  // input) or one of the well-known "any object" / "any relation" branded
+  // schemas (`Obj.Unknown` / `Relation.Unknown`). Arbitrary raw schemas are
+  // rejected.
+  //
+  // Referencing a type-kind entity (a meta-schema, e.g. `Type.Type`) yields a
+  // reference to a stored schema record; its loaded target is any registered
+  // entity (`Type.AnyEntity`), since a stored object/relation schema is itself a
+  // `Type.Type` record. Referencing an object/relation type yields a reference
+  // to an instance of that type.
+  <S extends Type.AnyEntity | UnknownTypeSchema<any, any> = Type.AnyEntity>(
+    schema: S,
+  ): RefSchema<
+    S extends Type.AnyType
+      ? Type.AnyEntity
+      : S extends Type.AnyObj | Type.AnyRelation
+        ? Type.InstanceType<S>
+        : S extends UnknownTypeSchema<infer A, any>
+          ? A
+          : never
+  >;
 
   /**
    * @returns True if the object is a reference.
@@ -111,15 +134,19 @@ export interface RefFn {
   make: <T extends AnyEntity>(object: T) => Ref<T>;
 
   /**
-   * Constructs a reference that points to the object specified by the provided DXN.
+   * Constructs a reference that points to the object specified by the provided URI
+   * (either an `echo:` EchoURI for an object reference or a `dxn:` DXN for a type reference).
    */
-  fromDXN: (dxn: DXN) => Ref<any>;
+  fromURI: (uri: URI.URI) => Ref<any>;
 }
 
 /**
  * Schema builder for references.
  */
-export const Ref: RefFn = <S extends Schema.Schema.Any>(schema: S): RefSchema<Schema.Schema.Type<S>> => {
+export const Ref: RefFn = (input: any): RefSchema<any> => {
+  // `Type.Type` entities carry their source schema on the hidden slot; the
+  // branded `Obj.Unknown` / `Relation.Unknown` schemas are used directly.
+  const schema = getStaticTypeSchema(input) ?? input;
   assertArgument(Schema.isSchema(schema), 'schema', 'Must call with an instance of effect-schema');
   const annotation = getTypeAnnotation(schema);
   if (annotation == null) {
@@ -135,9 +162,9 @@ export const Ref: RefFn = <S extends Schema.Schema.Any>(schema: S): RefSchema<Sc
  */
 export interface Ref<T> extends Pipeable.Pipeable {
   /**
-   * Target object DXN.
+   * Target URI (either an `echo:` EchoURI for an object reference or a `dxn:` DXN for a type reference).
    */
-  get dxn(): DXN;
+  get uri(): URI.URI;
 
   /**
    * Returns true if the reference has a target available (inlined or resolver set).
@@ -164,6 +191,16 @@ export interface Ref<T> extends Pipeable.Pipeable {
 
   tryLoad(): Promise<T | undefined>;
 
+  /**
+   * Subscribe to the ref's resolution event.
+   * The callback fires when the target object becomes available in the working set
+   * (e.g. when its document is loaded after sibling-client mutation).
+   * Note: the resolver only schedules a notification when the target is requested
+   * via {@link target} while it is not yet loaded.
+   * @returns Function that unsubscribes the callback.
+   */
+  onResolved(callback: () => void): () => void;
+
   /**
    * Do not inline the target object in the reference.
    * Makes .target unavailable unless the reference is connected to a database context.
@@ -205,7 +242,10 @@ Ref.isRef = (obj: any): obj is Ref<any> => {
   return obj && typeof obj === 'object' && RefTypeId in obj;
 };
 
-Ref.hasObjectId = (id: ObjectId) => (ref: Ref<any>) => ref.dxn.isLocalObjectId() && ref.dxn.parts[1] === id;
+Ref.hasObjectId = (id: ObjectId) => (ref: Ref<any>) => {
+  const uri = EchoURI.tryParse(ref.uri);
+  return uri !== undefined && EchoURI.isLocal(uri) && EchoURI.getObjectId(uri) === id;
+};
 
 Ref.isRefSchema = (schema: Schema.Schema<any, any>): schema is RefSchema<any> => {
   return Ref.isRefSchemaAST(schema.ast);
@@ -220,16 +260,16 @@ Ref.make = <T extends AnyProperties>(obj: T): Ref<T> => {
     throw new TypeError('Expected: ECHO object.');
   }
 
-  // TODO(dmaretskyi): Extract to `getObjectDXN` function.
+  // TODO(dmaretskyi): Extract to `getObjectEchoUri` function.
   const id = obj.id;
   invariant(ObjectId.isValid(id), 'Invalid object ID');
-  const dxn = DXN.fromLocalObjectId(id);
-  return new RefImpl(dxn, obj);
+  const uri = EchoURI.make({ objectId: id });
+  return new RefImpl(uri, obj);
 };
 
-Ref.fromDXN = (dxn: DXN): Ref<any> => {
-  assertArgument(dxn instanceof DXN, 'dxn', 'Expected DXN');
-  return new RefImpl(dxn);
+Ref.fromURI = (uri: URI.URI): Ref<any> => {
+  assertArgument(typeof uri === 'string', 'uri', 'Expected URI string');
+  return new RefImpl(uri);
 };
 
 /**
@@ -245,18 +285,18 @@ export type JsonSchemaReferenceInfo = {
  */
 // TODO(burdon): Move to json schema and make private?
 export const createEchoReferenceSchema = (
-  echoId: string | undefined,
+  echoUri: string | undefined,
   typename: string | undefined,
   version: string | undefined,
 ): Schema.SchemaClass<Ref<any>, EncodedReference> => {
-  if (!echoId && !typename) {
-    throw new TypeError('Either echoId or typename must be provided.');
+  if (!echoUri && !typename) {
+    throw new TypeError('Either echoUri or typename must be provided.');
   }
 
   const referenceInfo: JsonSchemaReferenceInfo = {
     schema: {
       // TODO(dmaretskyi): Include version?
-      $ref: echoId ?? DXN.fromTypename(typename!).toString(),
+      $ref: echoUri ?? DXN.make(typename!),
     },
     schemaVersion: version,
   };
@@ -269,7 +309,7 @@ export const createEchoReferenceSchema = (
         return (value) =>
           Effect.gen(function* () {
             if (Ref.isRef(value)) {
-              return EncodedReference.fromDXN((value as Ref<any>).dxn);
+              return EncodedReference.fromURI((value as Ref<any>).uri);
             } else if (EncodedReference.isEncodedReference(value)) {
               return value;
             }
@@ -284,7 +324,7 @@ export const createEchoReferenceSchema = (
             // TODO(dmaretskyi): This branch seems to be taken by Schema.is
             if (Ref.isRef(value)) {
               if (Option.isSome(dbService)) {
-                return dbService.value.db.makeRef(value.dxn);
+                return dbService.value.db.makeRef(value.uri);
               } else {
                 return value;
               }
@@ -294,9 +334,9 @@ export const createEchoReferenceSchema = (
               return yield* Effect.fail(new ParseResult.Unexpected(value, 'reference'));
             }
             if (Option.isSome(dbService)) {
-              return dbService.value.db.makeRef(EncodedReference.toDXN(value));
+              return dbService.value.db.makeRef(EncodedReference.toURI(value));
             } else {
-              return Ref.fromDXN(EncodedReference.toDXN(value));
+              return Ref.fromURI(EncodedReference.toURI(value));
             }
           });
       },
@@ -330,23 +370,32 @@ export interface RefResolver {
   /**
    * Resolve ref synchronously from the objects in the working set.
    *
-   * @param dxn
+   * @param uri
    * @param load If true the resolver should attempt to load the object from disk.
    * @param onLoad Callback to call when the object is loaded.
    */
-  resolveSync(dxn: DXN, load: boolean, onLoad?: () => void): AnyProperties | undefined;
+  resolveSync(uri: URI.URI, load: boolean, onLoad?: () => void): AnyProperties | undefined;
 
   /**
    * Resolver ref asynchronously.
    */
-  resolve(dxn: DXN): Promise<AnyProperties | undefined>;
+  resolve(uri: URI.URI): Promise<AnyProperties | undefined>;
 
   // TODO(dmaretskyi): Combine with `resolve`.
-  resolveSchema(dxn: DXN): Promise<Schema.Schema.AnyNoContext | undefined>;
+  resolveSchema(uri: URI.URI): Promise<Schema.Schema.AnyNoContext | undefined>;
+
+  /**
+   * Resolve the source `Type.AnyEntity` entity for a type URI. Used by
+   * deserialization paths (`Obj.fromJSON`) to set the back-reference accessed
+   * via `Obj.getType` / `Entity.getType`. Optional — resolvers that only
+   * carry raw schemas may leave this unimplemented; the deserializer falls
+   * back to leaving the type entity unset.
+   */
+  resolveType?(uri: URI.URI): Promise<unknown | undefined>;
 }
 
 export class RefImpl<T> implements Ref<T> {
-  #dxn: DXN;
+  #uri: URI.URI;
   #resolver?: RefResolver = undefined;
   #resolved = new Event<void>();
 
@@ -363,16 +412,16 @@ export class RefImpl<T> implements Ref<T> {
     this.#resolved.emit();
   };
 
-  constructor(dxn: DXN, target?: T) {
-    this.#dxn = dxn;
+  constructor(uri: URI.URI, target?: T) {
+    this.#uri = uri;
     this.#target = target;
   }
 
   /**
    * @inheritdoc
    */
-  get dxn(): DXN {
-    return this.#dxn;
+  get uri(): URI.URI {
+    return this.#uri;
   }
 
   /**
@@ -391,7 +440,7 @@ export class RefImpl<T> implements Ref<T> {
     }
 
     invariant(this.#resolver, 'Resolver is not set');
-    return this.#resolver.resolveSync(this.#dxn, true, this.#resolverCallback) as T | undefined;
+    return this.#resolver.resolveSync(this.#uri, true, this.#resolverCallback) as T | undefined;
   }
 
   /**
@@ -402,7 +451,7 @@ export class RefImpl<T> implements Ref<T> {
       return this.#target;
     }
     invariant(this.#resolver, 'Resolver is not set');
-    const obj = await this.#resolver.resolve(this.#dxn);
+    const obj = await this.#resolver.resolve(this.#uri);
     if (obj == null) {
       throw new Error('Object not found');
     }
@@ -417,7 +466,14 @@ export class RefImpl<T> implements Ref<T> {
       return this.#target;
     }
     invariant(this.#resolver, 'Resolver is not set');
-    return (await this.#resolver.resolve(this.#dxn)) as T | undefined;
+    return (await this.#resolver.resolve(this.#uri)) as T | undefined;
+  }
+
+  /**
+   * @inheritdoc
+   */
+  onResolved(callback: () => void): () => void {
+    return this.#resolved.on(callback);
   }
 
   /**
@@ -426,14 +482,14 @@ export class RefImpl<T> implements Ref<T> {
    * Clones the reference object.
    */
   noInline(): RefImpl<T> {
-    const ref = new RefImpl<T>(this.#dxn, undefined);
+    const ref = new RefImpl<T>(this.#uri, undefined);
     ref.#resolver = this.#resolver;
     return ref;
   }
 
   encode(): EncodedReference {
     return {
-      '/': this.#dxn.toString(),
+      '/': this.#uri,
       ...(this.#target ? { target: this.#target } : {}),
     };
   }
@@ -453,7 +509,7 @@ export class RefImpl<T> implements Ref<T> {
       return `Ref(${this.#target.toString()})`;
     }
 
-    return `Ref(${this.#dxn.toString()})`;
+    return `Ref(${this.#uri.toString()})`;
   }
 
   [inspectCustom]: CustomInspectFunction = (depth, options, inspect) => {
@@ -469,12 +525,12 @@ export class RefImpl<T> implements Ref<T> {
    * so without this, each access would create a separate cache entry.
    */
   [Hash.symbol](): number {
-    return Hash.hash(this.#dxn.toString());
+    return Hash.hash(this.#uri.toString());
   }
 
   /** Effect Equal trait. See {@link Hash.symbol} for rationale. */
   [Equal.symbol](that: Equal.Equal): boolean {
-    return that instanceof RefImpl && this.#dxn.toString() === that.dxn.toString();
+    return that instanceof RefImpl && this.#uri === that.uri;
   }
 
   /**
@@ -521,8 +577,8 @@ const refVariance: Ref<any>[typeof RefTypeId] = {
 };
 
 export const refFromEncodedReference = (encodedReference: EncodedReference, resolver?: RefResolver): Ref<any> => {
-  const dxn = DXN.parse(encodedReference['/']);
-  const ref = new RefImpl(dxn);
+  const uri = EncodedReference.toURI(encodedReference);
+  const ref = new RefImpl(uri);
 
   // TODO(dmaretskyi): Handle inline target in the encoded reference.
 
@@ -534,22 +590,25 @@ export const refFromEncodedReference = (encodedReference: EncodedReference, reso
 
 export class StaticRefResolver implements RefResolver {
   public objects = new Map<ObjectId, AnyProperties>();
-  public schemas = new Map<DXN.String, Schema.Schema.AnyNoContext>();
+  public schemas = new Map<URI.URI, Schema.Schema.AnyNoContext>();
 
   addObject(obj: AnyProperties): this {
     this.objects.set(obj.id, obj);
     return this;
   }
 
-  addSchema(schema: Schema.Schema.AnyNoContext): this {
-    const dxn = getSchemaDXN(schema);
-    invariant(dxn, 'Schema has no DXN');
-    this.schemas.set(dxn.toString(), schema);
+  addSchema(input: Type.AnyEntity): this {
+    const schema = getStaticTypeSchema(input);
+    invariant(schema, 'Type entity is missing its source schema');
+    const uri = getSchemaURI(schema);
+    invariant(uri, 'Schema has no URI');
+    this.schemas.set(uri, schema);
     return this;
   }
 
-  resolveSync(dxn: DXN, _load: boolean, _onLoad?: () => void): AnyProperties | undefined {
-    const id = dxn?.asEchoDXN()?.echoId;
+  resolveSync(uri: URI.URI, _load: boolean, _onLoad?: () => void): AnyProperties | undefined {
+    const echoUri = EchoURI.tryParse(uri);
+    const id = echoUri ? EchoURI.getObjectId(echoUri) : undefined;
     if (id == null) {
       return undefined;
     }
@@ -557,8 +616,9 @@ export class StaticRefResolver implements RefResolver {
     return this.objects.get(id);
   }
 
-  async resolve(dxn: DXN): Promise<AnyProperties | undefined> {
-    const id = dxn?.asEchoDXN()?.echoId;
+  async resolve(uri: URI.URI): Promise<AnyProperties | undefined> {
+    const echoUri = EchoURI.tryParse(uri);
+    const id = echoUri ? EchoURI.getObjectId(echoUri) : undefined;
     if (id == null) {
       return undefined;
     }
@@ -566,7 +626,7 @@ export class StaticRefResolver implements RefResolver {
     return this.objects.get(id);
   }
 
-  async resolveSchema(dxn: DXN): Promise<Schema.Schema.AnyNoContext | undefined> {
-    return this.schemas.get(dxn.toString());
+  async resolveSchema(uri: URI.URI): Promise<Schema.Schema.AnyNoContext | undefined> {
+    return this.schemas.get(uri);
   }
 }