@dxos/echo 0.9.0 → 0.9.1-staging.ee54ba693a

package/src/internal/Ref/ref.ts

@@ -81,7 +81,8 @@ export const getReferenceAst = (ast: SchemaAST.AST): RefereneAST | undefined =>
   };
 };
 
-export const RefTypeId: unique symbol = Symbol('@dxos/echo/internal/Ref');
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const RefTypeId: unique symbol = Symbol.for('@dxos/echo/internal/Ref') as any;
 
 /**
  * Reference Schema.
@@ -188,7 +189,14 @@ export interface Ref<T> extends Pipeable.Pipeable {
   /**
    * @returns Promise that will resolves with the target object.
    * Will load the object from disk if it is not present in the working set.
+   * Short-circuits immediately when the target is already loaded.
    * @throws If the object is not available locally.
+   *
+   * @idiom org.dxos.echo.refLoad
+   *   applies: Resolving a ref inside an async function or Effect handler — guarantees the object is available before proceeding
+   *   instead-of: `ref.target` — not guaranteed to be defined in async contexts; use `await ref.load()` (or `yield* Database.load(ref)` in Effect) to ensure the target is present
+   *   uses: {@link load}
+   *   related: org.dxos.echo-react.useObjectReactive
    */
   load(): Promise<T>;
 
@@ -253,7 +261,7 @@ export declare namespace Ref {
 }
 
 Ref.isRef = (obj: any): obj is Ref<any> => {
-  return obj && typeof obj === 'object' && RefTypeId in obj;
+  return obj != null && typeof obj === 'object' && RefTypeId in obj;
 };
 
 Ref.hasEntityId = (id: EntityId) => (ref: Ref<any>) => {
@@ -278,7 +286,8 @@ Ref.make = <T extends AnyProperties>(obj: T): Ref<T> => {
   const id = obj.id;
   invariant(EntityId.isValid(id), 'Invalid object ID');
   const uri = EID.make({ entityId: id });
-  return new RefImpl(uri, obj);
+  const ref = new RefImpl(uri, obj);
+  return ref;
 };
 
 Ref.fromURI = (uri: URI.URI): Ref<any> => {
@@ -380,22 +389,79 @@ const getSchemaExpectedName = (ast: SchemaAST.Annotated): string | undefined =>
   );
 };
 
+/**
+ * Load-source ceiling for a resolution request. Cheaper tiers are always probed first; the
+ * ceiling caps how far a request is allowed to reach:
+ * - `working-set`: synchronous, in-memory only. A miss settles `unavailable` immediately.
+ * - `disk`: probe the working set, then local storage; never the network.
+ * - `network`: probe the working set, disk, then fetch from peers.
+ *
+ * `unavailable` is always relative to the requested ceiling (disk-unavailable ≠ network-unavailable).
+ */
+export type RefSource = 'working-set' | 'disk' | 'network';
+
+/**
+ * A stateful, closure-aware handle to an in-flight (or settled) reference resolution.
+ *
+ * `ready` means the entity is FULLY USABLE: its own body and its strong-dependency closure are all
+ * materialized. The body-vs-closure split is internal; `requesting` transparently covers "a
+ * dependency is still loading".
+ */
+export interface RefResolverRequest {
+  /**
+   * `pending` is a one-way entry state (never re-entered). `requesting` means the body and/or
+   * closure is still loading. `ready` means fully usable. `unavailable` means unreachable at the
+   * requested ceiling.
+   */
+  readonly state: 'pending' | 'requesting' | 'ready' | 'unavailable';
+
+  /**
+   * Fires (deferred to a microtask) whenever {@link state} changes.
+   */
+  readonly stateChanged: Event<void>;
+
+  /**
+   * Synchronous snapshot of the resolved entity; defined iff `state === 'ready'`.
+   */
+  getResult(): AnyProperties | undefined;
+
+  /**
+   * Settles when `state ∈ {ready, unavailable}`.
+   */
+  wait(): Promise<AnyProperties | undefined>;
+
+  /**
+   * Decrements the refcount on the shared load op(s); cancels the underlying IO at zero.
+   */
+  abort(): void;
+}
+
 export interface RefResolver {
+  /**
+   * Resolve a reference, returning a stateful handle. `source` is a required ceiling; cheaper
+   * tiers are always probed first.
+   */
+  resolve(uri: URI.URI, options: { source: RefSource }): RefResolverRequest;
+
   /**
    * Resolve ref synchronously from the objects in the working set.
    *
    * @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.
+   * @deprecated Use {@link resolve} with `{ source: 'working-set' }`. Removed in Task 11.
    */
   resolveSync(uri: URI.URI, load: boolean, onLoad?: () => void): AnyProperties | undefined;
 
   /**
    * Resolver ref asynchronously.
+   * @deprecated Use {@link resolve} with `{ source: 'network' }`. Removed in Task 11.
    */
-  resolve(uri: URI.URI): Promise<AnyProperties | undefined>;
+  resolveLegacy(uri: URI.URI): Promise<AnyProperties | undefined>;
 
-  // TODO(dmaretskyi): Combine with `resolve`.
+  /**
+   * @deprecated Use {@link resolve} + `Type.getSchema`. Removed in Task 11.
+   */
   resolveSchema(uri: URI.URI): Promise<Schema.Schema.AnyNoContext | undefined>;
 
   /**
@@ -404,14 +470,30 @@ export interface RefResolver {
    * 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.
+   * @deprecated Use {@link resolve}. Removed in Task 11.
    */
   resolveType?(uri: URI.URI): Promise<unknown | undefined>;
 }
 
+/**
+ * A settled {@link RefResolverRequest} with a fixed `state` and `result`, used by resolvers
+ * whose backends are fully synchronous (e.g. {@link StaticRefResolver}).
+ */
+export const makeSettledRequest = (
+  state: RefResolverRequest['state'],
+  result: AnyProperties | undefined,
+): RefResolverRequest => ({
+  state,
+  stateChanged: new Event<void>(),
+  getResult: () => (state === 'ready' ? result : undefined),
+  wait: async () => (state === 'ready' ? result : undefined),
+  abort: () => {},
+});
+
 export class RefImpl<T> implements Ref<T> {
+  [RefTypeId] = refVariance;
+
   #uri: URI.URI;
-  #resolver?: RefResolver = undefined;
-  #resolved = new Event<void>();
 
   /**
    * Target is set when the reference is created from a specific object.
@@ -419,6 +501,9 @@ export class RefImpl<T> implements Ref<T> {
    */
   #target: T | undefined = undefined;
 
+  #resolver?: RefResolver = undefined;
+  #resolved = new Event<void>();
+
   /**
    * Callback to issue a reactive notification when object is resolved.
    */
@@ -438,13 +523,6 @@ export class RefImpl<T> implements Ref<T> {
     return this.#uri;
   }
 
-  /**
-   * @inheritdoc
-   */
-  get isAvailable(): boolean {
-    return this.#target !== undefined || this.#resolver !== undefined;
-  }
-
   /**
    * @inheritdoc
    */
@@ -457,6 +535,17 @@ export class RefImpl<T> implements Ref<T> {
     return this.#resolver.resolveSync(this.#uri, true, this.#resolverCallback) as T | undefined;
   }
 
+  /**
+   * @inheritdoc
+   */
+  get isAvailable(): boolean {
+    return this.#target !== undefined || this.#resolver !== undefined;
+  }
+
+  get atom(): Atom.Atom<T | undefined> {
+    return RefAtoms.refSimpleFamily(this);
+  }
+
   /**
    * @inheritdoc
    */
@@ -465,7 +554,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.#uri);
+    const obj = await this.#resolver.resolveLegacy(this.#uri);
     if (obj == null) {
       throw new Error('Object not found');
     }
@@ -480,7 +569,7 @@ export class RefImpl<T> implements Ref<T> {
       return this.#target;
     }
     invariant(this.#resolver, 'Resolver is not set');
-    return (await this.#resolver.resolve(this.#uri)) as T | undefined;
+    return (await this.#resolver.resolveLegacy(this.#uri)) as T | undefined;
   }
 
   /**
@@ -530,8 +619,6 @@ export class RefImpl<T> implements Ref<T> {
     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.
@@ -547,13 +634,12 @@ export class RefImpl<T> implements Ref<T> {
     return that instanceof RefImpl && this.#uri === that.uri;
   }
 
-  get atom(): Atom.Atom<T | undefined> {
-    return RefAtoms.refSimpleFamily(this);
+  pipe() {
+    // eslint-disable-next-line prefer-rest-params
+    return Pipeable.pipeArguments(this, arguments);
   }
 
   /**
-   * Internal method to set the resolver.
-   *
    * @internal
    */
   _setResolver(resolver: RefResolver): void {
@@ -566,11 +652,6 @@ export class RefImpl<T> implements Ref<T> {
   _getSavedTarget(): T | undefined {
     return this.#target;
   }
-
-  pipe() {
-    // eslint-disable-next-line prefer-rest-params
-    return Pipeable.pipeArguments(this, arguments);
-  }
 }
 
 /**
@@ -624,27 +705,29 @@ export class StaticRefResolver implements RefResolver {
     return this;
   }
 
+  resolve(uri: URI.URI, _options: { source: RefSource }): RefResolverRequest {
+    const obj = this.#lookup(uri);
+    return makeSettledRequest(obj ? 'ready' : 'unavailable', obj);
+  }
+
   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;
-    }
+    return this.#lookup(uri);
+  }
 
-    return this.objects.get(id);
+  async resolveLegacy(uri: URI.URI): Promise<AnyProperties | undefined> {
+    return this.#lookup(uri);
+  }
+
+  async resolveSchema(uri: URI.URI): Promise<Schema.Schema.AnyNoContext | undefined> {
+    return this.schemas.get(uri);
   }
 
-  async resolve(uri: URI.URI): Promise<AnyProperties | undefined> {
+  #lookup(uri: URI.URI): AnyProperties | undefined {
     const echoUri = EID.tryParse(uri);
     const id = echoUri ? EID.getEntityId(echoUri) : undefined;
     if (id == null) {
       return undefined;
     }
-
     return this.objects.get(id);
   }
-
-  async resolveSchema(uri: URI.URI): Promise<Schema.Schema.AnyNoContext | undefined> {
-    return this.schemas.get(uri);
-  }
 }

package/src/internal/Ref/strong-deps.ts

@@ -0,0 +1,107 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { EID, type SpaceId, type URI } from '@dxos/keys';
+
+import { EntityKind } from '../common/types/entity';
+import { RelationSourceDXNId, RelationTargetDXNId } from '../common/types/model-symbols';
+import { ParentId, TypeId } from '../common/types/typename';
+import { getObjectEchoUri } from '../Entity/util';
+
+/**
+ * Normalized view of the references that make up an entity's strong-dependency set, store-agnostic
+ * so it can be filled from an {@link ObjectCore} (db) or a decoded entity (queue item / snapshot).
+ */
+export interface StrongDepRefs {
+  /** Entity kind — relations additionally depend on their source/target. */
+  kind: EntityKind;
+  /** Type reference URI (`echo:` for a persisted stored schema, `dxn:` for a static/registry type). */
+  type?: URI.URI;
+  /** Relation source reference URI. */
+  source?: URI.URI;
+  /** Relation target reference URI. */
+  target?: URI.URI;
+  /** Parent reference URI. */
+  parent?: URI.URI;
+}
+
+/**
+ * Direct strong-dependency URIs of an entity: the schema (only when stored as an object), the
+ * relation source/target, and the parent. Returns URIs (cross-space `echo:` EIDs and queue-item
+ * EIDs included); a persisted schema is an `echo:` URI, a static/registry type is a `dxn:` URI.
+ *
+ * A static/registry type (`dxn:`) is intentionally NOT a strong dep: it is always synchronously
+ * available through the registry, so gating on it would needlessly delay surfacing. Only a
+ * persisted (db-backed) schema, addressed by an `echo:` URI, must load before its instances.
+ */
+export const getStrongDependencyUris = (refs: StrongDepRefs, owningSpaceId?: SpaceId): URI.URI[] => {
+  const res: URI.URI[] = [];
+
+  if (refs.type != null && EID.tryParse(refs.type) != null) {
+    res.push(qualifyToSpace(refs.type, owningSpaceId));
+  }
+
+  if (refs.kind === EntityKind.Relation) {
+    if (refs.source != null) {
+      res.push(qualifyToSpace(refs.source, owningSpaceId));
+    }
+    if (refs.target != null) {
+      res.push(qualifyToSpace(refs.target, owningSpaceId));
+    }
+  }
+
+  if (refs.parent != null) {
+    res.push(qualifyToSpace(refs.parent, owningSpaceId));
+  }
+
+  return res;
+};
+
+/**
+ * Qualifies a space-less (relative) `echo:` dependency URI with the space of the entity that owns it.
+ * Same-space references are persisted relative; resolution needs them absolute to route to a single
+ * space. Already-qualified URIs (cross-space) and non-`echo:` URIs (registry `dxn:`) pass through.
+ */
+const qualifyToSpace = (uri: URI.URI, owningSpaceId: SpaceId | undefined): URI.URI => {
+  if (owningSpaceId == null) {
+    return uri;
+  }
+  const eid = EID.tryParse(uri);
+  if (eid == null || !EID.isLocal(eid)) {
+    return uri;
+  }
+  const entityId = EID.getEntityId(eid);
+  return entityId != null ? EID.make({ spaceId: owningSpaceId, entityId }) : uri;
+};
+
+/**
+ * Direct strong-dependency URIs of a live (decoded) entity — a queue item, cross-space proxy, or
+ * snapshot. Reads the reference URIs off the entity's hidden model symbols. ECHO db cores compute
+ * the same set from their raw encoded references via {@link getStrongDependencyUris}.
+ */
+export const getStrongDependencies = (entity: unknown): URI.URI[] => {
+  if (entity == null || typeof entity !== 'object') {
+    return [];
+  }
+  const props = entity as Record<symbol, unknown>;
+  const kind =
+    props[RelationSourceDXNId] != null || props[RelationTargetDXNId] != null ? EntityKind.Relation : EntityKind.Object;
+  const parent = props[ParentId];
+
+  // The entity's own space qualifies any relative dependency URIs it carries.
+  const selfUri = getObjectEchoUri(entity);
+  const owningSpaceId = selfUri != null ? EID.getSpaceId(selfUri) : undefined;
+
+  return getStrongDependencyUris(
+    {
+      kind,
+      type: typeof props[TypeId] === 'string' ? (props[TypeId] as URI.URI) : undefined,
+      source: props[RelationSourceDXNId] as URI.URI | undefined,
+      target: props[RelationTargetDXNId] as URI.URI | undefined,
+      // A parent is held as the resolved entity; derive its absolute URI for the dependency edge.
+      parent: parent != null ? getObjectEchoUri(parent) : undefined,
+    },
+    owningSpaceId,
+  );
+};

package/src/internal/common/atom-snapshot.ts

@@ -0,0 +1,19 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+/**
+ * Snapshot a value to create a new reference for atom change-detection and React dependency tracking.
+ * Objects and arrays are shallow-copied (a fresh reference each read, so an in-place mutation is
+ * observed); primitives are returned as-is (so they dedupe via `!==`). Shared by the object-property
+ * and annotation atom families.
+ */
+export const snapshotForComparison = <V>(value: V): V => {
+  if (Array.isArray(value)) {
+    return [...value] as V;
+  }
+  if (value !== null && typeof value === 'object') {
+    return { ...value } as V;
+  }
+  return value;
+};

package/src/internal/common/proxy/make-object.ts

@@ -13,7 +13,7 @@ import { MetaId } from '../types/model-symbols';
 import { defineHiddenProperty } from './define-hidden-property';
 import { attachTypedJsonSerializer } from './json-serializer';
 import { createProxy, getProxyTarget, isValidProxyTarget } from './proxy-utils';
-import { TypeSource, TypedReactiveHandler, prepareTypedTarget, setMetaOwner } from './typed-handler';
+import { TypedReactiveHandler, TypeSource, prepareTypedTarget, setMetaOwner } from './typed-handler';
 
 /**
  *

package/src/internal/common/proxy/proxy-types.ts

@@ -15,6 +15,26 @@ export interface ReactiveHandler<T extends object> extends ProxyHandler<T> {
    * Called when a proxy is created for this target.
    */
   init(target: T): void;
+
+  /**
+   * Replace the string CRDT value at `path` with `newText`, applying a minimal diff so cursors and
+   * concurrent edits are preserved. Implemented by handlers that back string fields; `Text.update`
+   * dispatches here. Must run inside a change context (`Obj.update`).
+   */
+  textUpdate?(target: T, path: readonly (string | number)[], newText: string): void;
+
+  /**
+   * Splice the string CRDT value at `path` (character indices, mirroring `Array.splice`): remove
+   * `deleteCount` characters at `start` and insert `insert`. Returns the removed substring. `Text.splice`
+   * dispatches here. Must run inside a change context (`Obj.update`).
+   */
+  textSplice?(
+    target: T,
+    path: readonly (string | number)[],
+    start: number,
+    deleteCount: number,
+    insert: string,
+  ): string;
 }
 
 /**

package/src/internal/common/proxy/proxy-utils.ts

@@ -8,11 +8,30 @@ import { type ReactiveHandler } from './proxy-types';
 
 export const symbolIsProxy = Symbol.for('@dxos/schema/Proxy');
 
+/**
+ * Marker placed on a reactive-object behaviour prototype (e.g. the typed handler's
+ * `TypedObject` prototype). A record target whose prototype chain carries this marker
+ * is a reactive data record — equivalent, for the purposes of the "plain object" gates
+ * below, to one rooted directly at `Object.prototype`. This lets a handler move its
+ * per-object metadata onto an intermediate prototype without those gates mistaking the
+ * record for a foreign class instance.
+ */
+export const symbolReactivePrototype = Symbol.for('@dxos/echo/ReactivePrototype');
+
 /**
  * Internal api.
  */
 export const isProxy = (value: unknown) => !!(value as any)?.[symbolIsProxy];
 
+/**
+ * True if `value` is a plain data record — either rooted at `Object.prototype` or carrying
+ * a reactive behaviour prototype (see {@link symbolReactivePrototype}).
+ */
+export const isReactiveRecord = (value: any): boolean => {
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || (proto != null && !!proto[symbolReactivePrototype]);
+};
+
 export const isValidProxyTarget = (value: any): value is object => {
   if (value == null || value[symbolIsProxy]) {
     return false;
@@ -21,7 +40,7 @@ export const isValidProxyTarget = (value: any): value is object => {
     return true;
   }
 
-  return typeof value === 'object' && Object.getPrototypeOf(value) === Object.prototype;
+  return typeof value === 'object' && isReactiveRecord(value);
 };
 
 /**
@@ -41,6 +60,23 @@ export const getProxyHandler = <T extends object>(proxy: any): ReactiveHandler<T
   return getProxySlot<T>(proxy).handler;
 };
 
+/**
+ * Clamp a splice range to `Array.prototype.splice` semantics for a string of the given `length`:
+ * a negative `start` counts from the end, a `start` past the end appends, and `deleteCount` is bounded
+ * to the remaining characters. Shared by both reactive handlers so the string CRDT API behaves
+ * identically across the in-memory and Automerge backends (Automerge's `splice` otherwise throws on
+ * out-of-range indices).
+ */
+export const normalizeSpliceRange = (
+  length: number,
+  start: number,
+  deleteCount: number,
+): { start: number; deleteCount: number } => {
+  const safeStart = start < 0 ? Math.max(length + start, 0) : Math.min(start, length);
+  const safeDeleteCount = Math.max(0, Math.min(deleteCount, length - safeStart));
+  return { start: safeStart, deleteCount: safeDeleteCount };
+};
+
 /**
  * Unsafe method to override id for debugging/testing and migration purposes.
  * @deprecated

package/src/internal/common/proxy/reactive-array.ts

@@ -7,7 +7,7 @@ import { createArrayMethodError } from './errors';
 import { batchEvents } from './event-batch';
 import { getEchoRoot } from './ownership';
 import { getProxyTarget, isProxy } from './proxy-utils';
-import { ChangeId, EventId } from './symbols';
+import { EventId } from './symbols';
 
 /**
  * Check if array mutation is allowed (inside a change context).
@@ -20,8 +20,8 @@ const checkArrayMutationAllowed = (arr: any, method: string): void => {
   // Find the root ECHO object.
   const echoRoot = getEchoRoot(target);
 
-  // Check if initialized (has ChangeId marker or EventId).
-  const isInitialized = (echoRoot as any)[ChangeId] === true || EventId in echoRoot;
+  // A root object owns an `EventId` once initialized; before that, mutations are allowed.
+  const isInitialized = EventId in echoRoot;
   if (!isInitialized) {
     // Array is still being initialized, allow mutations.
     return;

package/src/internal/common/proxy/reactive.test.ts

@@ -36,7 +36,7 @@ describe('Obj.subscribe', () => {
   test('returns a no-op unsubscribe for non-proxy inputs', () => {
     const queueShaped: any = {
       id: '01KQ5NKXJWSKMRPVTVG2GHV8V3',
-      blueprints: { added: [], removed: [] },
+      skills: { added: [], removed: [] },
       objects: { added: [], removed: [] },
     };
     const unsubscribe = Obj.subscribe(queueShaped, () => {});