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

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

@@ -2,40 +2,55 @@
 // Copyright 2024 DXOS.org
 //
 
+import type * as Atom from '@effect-atom/atom/Atom';
 import * as Effect from 'effect/Effect';
+import * as Equal from 'effect/Equal';
+import * as Hash from 'effect/Hash';
 import * as Option from 'effect/Option';
 import * as ParseResult from 'effect/ParseResult';
+import * as Pipeable from 'effect/Pipeable';
 import * as Schema from 'effect/Schema';
 import * as SchemaAST from 'effect/SchemaAST';
+import type * as Types from 'effect/Types';
 
-import { type EncodedReference, Reference } from '@dxos/echo-protocol';
-import { compositeRuntime } from '@dxos/echo-signals/runtime';
+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 { ReferenceAnnotationId, getSchemaDXN, getTypeAnnotation, getTypeIdentifierAnnotation } from '../ast';
-import { type JsonSchemaType } from '../json-schema';
-import type { BaseObject, WithId } from '../types';
+import { DXN, EID, EntityId, type URI } from '@dxos/keys';
+
+import * as Database from '../../Database';
+import type * as Type from '../../Type';
+import {
+  ReferenceAnnotationId,
+  getSchemaURI,
+  getTypeAnnotation,
+  getTypeIdentifierAnnotation,
+} from '../Annotation/annotations';
+import { type AnyEntity, type AnyProperties, type UnknownTypeSchema, getStaticTypeSchema } from '../common/types';
+import { type JsonSchemaType } from '../JsonSchema';
+import * as RefAtoms from './atoms';
 
 /**
  * The `$id` and `$ref` fields for an ECHO reference schema.
  */
 export const JSON_SCHEMA_ECHO_REF_ID = '/schemas/echo/ref';
 
-// TODO(burdon): Define return type.
 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;
   }
 };
 
-export const createSchemaReference = (typename: string): JsonSchemaType => {
+export const createSchemaReference = (typename: string): Types.DeepMutable<JsonSchemaType> => {
   return {
     $id: JSON_SCHEMA_ECHO_REF_ID,
     reference: {
       schema: {
-        $ref: DXN.fromTypename(typename).toString(),
+        $ref: DXN.make(typename),
       },
     },
   };
@@ -71,26 +86,48 @@ export const RefTypeId: unique symbol = Symbol('@dxos/echo/internal/Ref');
 /**
  * Reference Schema.
  */
-export interface Ref$<T extends WithId> extends Schema.SchemaClass<Ref<T>, EncodedReference> {}
+export interface RefSchema<T extends AnyEntity> extends Schema.SchemaClass<Ref<T>, EncodedReference> {}
 
-// Type of the `Ref` function and extra methods attached to it.
+/**
+ * Type of the `Ref` function and extra methods attached to it.
+ */
 export interface RefFn {
-  <S extends Schema.Schema.Any>(schema: S): Ref$<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.
    */
-  isRef: (obj: any) => obj is Ref<any>;
+  isRef: (obj: unknown) => obj is Ref<any>;
 
   /**
    * @returns True if the reference points to the given object id.
    */
-  hasObjectId: (id: ObjectId) => (ref: Ref<any>) => boolean;
+  hasEntityId: (id: EntityId) => (ref: Ref<any>) => boolean;
 
   /**
    * @returns True if the schema is a reference schema.
    */
-  isRefSchema: (schema: Schema.Schema<any, any>) => schema is Ref$<any>;
+  isRefSchema: (schema: Schema.Schema<any, any>) => schema is RefSchema<any>;
 
   /**
    * @returns True if the schema AST is a reference schema.
@@ -100,49 +137,51 @@ export interface RefFn {
   /**
    * Constructs a reference that points to the given object.
    */
-  // TODO(burdon): Tighten type of T?
-  make: <T extends WithId>(object: T) => Ref<T>;
+  // TODO(burdon): Narrow to Obj.Unknown?
+  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:` EID 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): Ref$<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) {
     throw new Error('Reference target must be an ECHO schema.');
   }
 
-  return createEchoReferenceSchema(
-    getTypeIdentifierAnnotation(schema),
-    annotation.typename,
-    annotation.version,
-    getSchemaExpectedName(schema.ast),
-  );
+  return createEchoReferenceSchema(getTypeIdentifierAnnotation(schema), annotation.typename, annotation.version);
 };
 
 /**
  * Represents materialized reference to a target.
  * This is the data type for the fields marked as ref.
  */
-export interface Ref<T> {
+export interface Ref<T> extends Pipeable.Pipeable {
   /**
-   * Target object DXN.
+   * Target URI (either an `echo:` EID 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).
+   */
+  get isAvailable(): boolean;
 
   /**
    * @returns The reference target.
    * May return `undefined` if the object is not loaded in the working set.
    * Accessing this property, even if it returns `undefined` will trigger the object to be loaded to the working set.
-   *
-   * @reactive Supports signal subscriptions.
    */
   get target(): T | undefined;
 
@@ -156,8 +195,19 @@ export interface Ref<T> {
   /**
    * @returns Promise that will resolves with the target object or undefined if the object is not loaded locally.
    */
+
   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.
@@ -171,6 +221,13 @@ export interface Ref<T> {
    */
   noInline(): Ref<T>;
 
+  /**
+   * Read-only atom for the ref target.
+   * Resolves once when the target loads; does NOT subscribe to target object mutations.
+   * Use `Obj.atom(ref)` if you need reactive snapshots that update on every object mutation.
+   */
+  get atom(): Atom.Atom<T | undefined>;
+
   /**
    * Serializes the reference to a JSON object.
    * The serialization format is compatible with the IPLD-style encoded references.
@@ -199,9 +256,12 @@ 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.hasEntityId = (id: EntityId) => (ref: Ref<any>) => {
+  const uri = EID.tryParse(ref.uri);
+  return uri !== undefined && EID.isLocal(uri) && EID.getEntityId(uri) === id;
+};
 
-Ref.isRefSchema = (schema: Schema.Schema<any, any>): schema is Ref$<any> => {
+Ref.isRefSchema = (schema: Schema.Schema<any, any>): schema is RefSchema<any> => {
   return Ref.isRefSchemaAST(schema.ast);
 };
 
@@ -209,21 +269,21 @@ Ref.isRefSchemaAST = (ast: SchemaAST.AST): boolean => {
   return SchemaAST.getAnnotation(ast, ReferenceAnnotationId).pipe(Option.isSome);
 };
 
-Ref.make = <T extends BaseObject>(obj: T): Ref<T> => {
+Ref.make = <T extends AnyProperties>(obj: T): Ref<T> => {
   if (typeof obj !== 'object' || obj === null) {
     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 = Reference.localObjectReference(id).toDXN();
-  return new RefImpl(dxn, obj);
+  invariant(EntityId.isValid(id), 'Invalid object ID');
+  const uri = EID.make({ entityId: 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);
 };
 
 /**
@@ -239,19 +299,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,
-  schemaName?: string,
 ): 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,
   };
@@ -261,25 +320,39 @@ export const createEchoReferenceSchema = (
     [],
     {
       encode: () => {
-        return (value) => {
-          return Effect.succeed({
-            '/': (value as Ref<any>).dxn.toString(),
+        return (value) =>
+          Effect.gen(function* () {
+            if (Ref.isRef(value)) {
+              return EncodedReference.fromURI((value as Ref<any>).uri);
+            } else if (EncodedReference.isEncodedReference(value)) {
+              return value;
+            }
+            throw new Error('Invalid reference');
           });
-        };
       },
       decode: () => {
-        return (value) => {
-          // TODO(dmaretskyi): This branch seems to be taken by Schema.is
-          if (Ref.isRef(value)) {
-            return Effect.succeed(value);
-          }
-
-          if (typeof value !== 'object' || value == null || typeof (value as any)['/'] !== 'string') {
-            return Effect.fail(new ParseResult.Unexpected(value, 'reference'));
-          }
-
-          return Effect.succeed(Ref.fromDXN(DXN.parse((value as any)['/'])));
-        };
+        return (value) =>
+          Effect.gen(function* () {
+            const dbService = yield* Effect.serviceOption(Database.Service);
+
+            // 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.uri);
+              } else {
+                return value;
+              }
+            }
+
+            if (!EncodedReference.isEncodedReference(value)) {
+              return yield* Effect.fail(new ParseResult.Unexpected(value, 'reference'));
+            }
+            if (Option.isSome(dbService)) {
+              return dbService.value.db.makeRef(EncodedReference.toURI(value));
+            } else {
+              return Ref.fromURI(EncodedReference.toURI(value));
+            }
+          });
       },
     },
     {
@@ -311,25 +384,34 @@ 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): BaseObject | undefined;
+  resolveSync(uri: URI.URI, load: boolean, onLoad?: () => void): AnyProperties | undefined;
 
   /**
    * Resolver ref asynchronously.
    */
-  resolve(dxn: DXN): Promise<BaseObject | 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;
-  #signal = compositeRuntime.createSignal();
+  #resolved = new Event<void>();
 
   /**
    * Target is set when the reference is created from a specific object.
@@ -341,32 +423,38 @@ export class RefImpl<T> implements Ref<T> {
    * Callback to issue a reactive notification when object is resolved.
    */
   #resolverCallback = () => {
-    this.#signal.notifyWrite();
+    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;
+  }
+
+  /**
+   * @inheritdoc
+   */
+  get isAvailable(): boolean {
+    return this.#target !== undefined || this.#resolver !== undefined;
   }
 
   /**
    * @inheritdoc
    */
   get target(): T | undefined {
-    this.#signal.notifyRead();
     if (this.#target) {
       return this.#target;
     }
 
     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;
   }
 
   /**
@@ -377,7 +465,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');
     }
@@ -388,8 +476,18 @@ export class RefImpl<T> implements Ref<T> {
    * @inheritdoc
    */
   async tryLoad(): Promise<T | undefined> {
+    if (this.#target) {
+      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);
   }
 
   /**
@@ -398,14 +496,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 } : {}),
     };
   }
@@ -425,13 +523,37 @@ 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) => {
+    return this.toString();
+  };
+
   [RefTypeId] = refVariance;
 
+  /**
+   * Effect Hash trait. Required for MutableHashMap-based caches (e.g., Atom.family)
+   * to deduplicate Ref instances that point to the same object.
+   * ECHO proxies return new RefImpl instances on every property access,
+   * so without this, each access would create a separate cache entry.
+   */
+  [Hash.symbol](): number {
+    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.#uri === that.uri;
+  }
+
+  get atom(): Atom.Atom<T | undefined> {
+    return RefAtoms.refSimpleFamily(this);
+  }
+
   /**
    * Internal method to set the resolver.
+   *
    * @internal
    */
   _setResolver(resolver: RefResolver): void {
@@ -439,13 +561,16 @@ export class RefImpl<T> implements Ref<T> {
   }
 
   /**
-   * Internal method to get the saved target.
-   * Not the same as `target` which is resolved from the resolver.
    * @internal
    */
   _getSavedTarget(): T | undefined {
     return this.#target;
   }
+
+  pipe() {
+    // eslint-disable-next-line prefer-rest-params
+    return Pipeable.pipeArguments(this, arguments);
+  }
 }
 
 /**
@@ -459,7 +584,7 @@ export const setRefResolver = (ref: Ref<any>, resolver: RefResolver) => {
 /**
  * Internal API for getting the saved target on a reference.
  */
-export const getRefSavedTarget = (ref: Ref<any>): BaseObject | undefined => {
+export const getRefSavedTarget = (ref: Ref<any>): AnyProperties | undefined => {
   invariant(ref instanceof RefImpl, 'Ref is not an instance of RefImpl');
   return ref._getSavedTarget();
 };
@@ -470,8 +595,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.
 
@@ -482,23 +607,26 @@ export const refFromEncodedReference = (encodedReference: EncodedReference, reso
 };
 
 export class StaticRefResolver implements RefResolver {
-  public objects = new Map<ObjectId, BaseObject>();
-  public schemas = new Map<DXN.String, Schema.Schema.AnyNoContext>();
+  public objects = new Map<EntityId, AnyProperties>();
+  public schemas = new Map<URI.URI, Schema.Schema.AnyNoContext>();
 
-  addObject(obj: BaseObject): this {
+  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): BaseObject | undefined {
-    const id = dxn?.asEchoDXN()?.echoId;
+  resolveSync(uri: URI.URI, _load: boolean, _onLoad?: () => void): AnyProperties | undefined {
+    const echoUri = EID.tryParse(uri);
+    const id = echoUri ? EID.getEntityId(echoUri) : undefined;
     if (id == null) {
       return undefined;
     }
@@ -506,8 +634,9 @@ export class StaticRefResolver implements RefResolver {
     return this.objects.get(id);
   }
 
-  async resolve(dxn: DXN): Promise<BaseObject | undefined> {
-    const id = dxn?.asEchoDXN()?.echoId;
+  async resolve(uri: URI.URI): Promise<AnyProperties | undefined> {
+    const echoUri = EID.tryParse(uri);
+    const id = echoUri ? EID.getEntityId(echoUri) : undefined;
     if (id == null) {
       return undefined;
     }
@@ -515,7 +644,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);
   }
 }

package/src/internal/Ref/utils.ts

@@ -0,0 +1,45 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import type * as Atom from '@effect-atom/atom/Atom';
+
+import type { Ref } from './ref';
+
+/**
+ * Internal helper for loading ref targets in atoms.
+ * Handles the common pattern of checking for loaded target and triggering async load.
+ */
+export const loadRefTarget = <T, R>(
+  ref: Ref<T>,
+  get: Atom.Context,
+  onTargetAvailable: (target: T) => R,
+): R | undefined => {
+  // Accessing `ref.target` registers a resolution callback when the target is
+  // not yet loaded, so resolution can be observed via `ref.onResolved` below.
+  const currentTarget = ref.target;
+  if (currentTarget) {
+    return onTargetAvailable(currentTarget);
+  }
+
+  // Subscribe to the ref's resolution event in case the target loads later.
+  const unsubscribe = ref.onResolved(() => {
+    const target = ref.target;
+    if (target) {
+      get.setSelf(onTargetAvailable(target));
+    }
+  });
+  get.addFinalizer(unsubscribe);
+
+  // Also try async load (e.g. for objects that need disk loading).
+  void ref
+    .load()
+    .then((loadedTarget) => {
+      get.setSelf(onTargetAvailable(loadedTarget));
+    })
+    .catch(() => {
+      // Loading failed; the resolution subscription above will pick up cross-client updates.
+    });
+
+  return undefined;
+};