@dxos/echo 0.9.1-main.c7dcc2e112 → 0.9.1-staging.ee54ba693a

package/src/internal/Obj/set-value.test.ts

@@ -59,10 +59,12 @@ describe('Obj.setValue', () => {
       value: Schema.optional(Schema.Number),
     });
 
-    const Container = Schema.Struct({
-      name: Schema.String,
-      items: Schema.optional(Schema.Array(Item)),
-    }).pipe(Type.makeObject(DXN.make('com.test.type.container', '0.1.0')));
+    const Container = Type.makeObject(DXN.make('com.test.type.container', '0.1.0'))(
+      Schema.Struct({
+        name: Schema.String,
+        items: Schema.optional(Schema.Array(Item)),
+      }),
+    );
 
     const container = Obj.make(Container, { name: 'box' });
 
@@ -146,9 +148,11 @@ describe('Obj.setValue', () => {
   });
 
   test('handles two-dimensional arrays', ({ expect }) => {
-    const Matrix = Schema.Struct({
-      values: Schema.optional(Schema.Array(Schema.Array(Schema.Number))),
-    }).pipe(Type.makeObject(DXN.make('com.test.type.matrix', '0.1.0')));
+    const Matrix = Type.makeObject(DXN.make('com.test.type.matrix', '0.1.0'))(
+      Schema.Struct({
+        values: Schema.optional(Schema.Array(Schema.Array(Schema.Number))),
+      }),
+    );
 
     const matrix = Obj.make(Matrix, {});
 
@@ -194,10 +198,12 @@ describe('Obj.setValue', () => {
       value: Schema.optional(Schema.Number),
     });
 
-    const Container = Schema.Struct({
-      name: Schema.String,
-      items: Schema.optional(Schema.Array(Item)),
-    }).pipe(Type.makeObject(DXN.make('com.test.type.container', '0.1.0')));
+    const Container = Type.makeObject(DXN.make('com.test.type.container', '0.1.0'))(
+      Schema.Struct({
+        name: Schema.String,
+        items: Schema.optional(Schema.Array(Item)),
+      }),
+    );
 
     const container = Obj.make(Container, { name: 'box' });
 
@@ -216,10 +222,12 @@ describe('Obj.setValue', () => {
       completed: Schema.optional(Schema.Boolean),
     });
 
-    const TodoList = Schema.Struct({
-      name: Schema.String,
-      tasks: Schema.optional(Schema.Array(Task)),
-    }).pipe(Type.makeObject(DXN.make('com.test.type.todoList', '0.1.0')));
+    const TodoList = Type.makeObject(DXN.make('com.test.type.todoList', '0.1.0'))(
+      Schema.Struct({
+        name: Schema.String,
+        tasks: Schema.optional(Schema.Array(Task)),
+      }),
+    );
 
     const todoList = Obj.make(TodoList, { name: 'My Tasks' });
 
@@ -240,10 +248,12 @@ describe('Obj.setValue', () => {
       label: Schema.optional(Schema.String), // Optional - should not be initialized
     });
 
-    const Container = Schema.Struct({
-      name: Schema.String,
-      items: Schema.optional(Schema.Array(Item)),
-    }).pipe(Type.makeObject(DXN.make('com.test.type.container', '0.1.0')));
+    const Container = Type.makeObject(DXN.make('com.test.type.container', '0.1.0'))(
+      Schema.Struct({
+        name: Schema.String,
+        items: Schema.optional(Schema.Array(Item)),
+      }),
+    );
 
     const container = Obj.make(Container, { name: 'box' });
 

package/src/internal/Query/index.ts

@@ -3,3 +3,4 @@
 //
 
 export * from './pretty';
+export * from './query-result-effect';

package/src/internal/Query/query-result-effect.ts

@@ -0,0 +1,35 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import * as Effectable from 'effect/Effectable';
+import * as Option from 'effect/Option';
+
+import { EffectEx } from '@dxos/effect';
+
+import type * as QueryResult from '../../QueryResult';
+
+/**
+ * Wraps an effect that produces a {@link QueryResult.QueryResult} into a
+ * {@link QueryResult.QueryResultEffect}, exposing `.run` and `.first` shorthands that execute the
+ * query once. Shared by `Database.query` and `Feed.query` so both surfaces chain identically.
+ */
+export const makeQueryResultEffect = <T, E, R>(
+  eff: Effect.Effect<QueryResult.QueryResult<T>, E, R>,
+): QueryResult.QueryResultEffect<T, E, R> => {
+  return {
+    run: Effect.flatMap(eff, (result) => EffectEx.promiseWithCauseCapture(() => result.run())),
+    first: Effect.flatMap(eff, (result) =>
+      EffectEx.promiseWithCauseCapture(async () => Option.fromNullable(await result.firstOrUndefined())),
+    ),
+
+    // Effect internals: the result is itself an Effect, so it carries the commit prototype.
+    ...Effectable.CommitPrototype,
+    commit() {
+      return eff;
+    },
+    // Cast required: Effect's commit protocol is supplied at runtime via `CommitPrototype` and
+    // cannot be expressed by the object literal's static type.
+  } as any;
+};

package/src/internal/Ref/atoms.ts

@@ -4,17 +4,37 @@
 
 import * as Atom from '@effect-atom/atom/Atom';
 
+import { subscribe } from '../common/proxy/reactive';
+import { ObjectDeletedId } from '../common/types/model-symbols';
 import type { Ref } from './ref';
 import { loadRefTarget } from './utils';
 
 /**
  * Atom family for ECHO refs.
  * Uses ref reference as key — same ref returns same atom.
- * This atom only updates once when the ref loads — it does not subscribe to target object changes.
- * Use `Obj.atom(ref)` if you need reactive snapshots of ECHO objects via a ref.
+ * Subscribes to target object changes and resolves to undefined when the target is deleted.
  */
 export const refSimpleFamily = Atom.family(<T>(ref: Ref<T>): Atom.Atom<T | undefined> => {
   return Atom.make<T | undefined>((get) => {
-    return loadRefTarget(ref, get, (target) => target);
+    let unsubscribeTarget: (() => void) | undefined;
+
+    const setupSubscription = (target: T): T | undefined => {
+      // Release any previous subscription before re-subscribing (loadRefTarget may call this more than once).
+      // T has no ECHO-proxy constraint at this generic level; `subscribe` and ObjectDeletedId
+      // both require the internal proxy shape that cannot be expressed statically here.
+      unsubscribeTarget?.();
+      unsubscribeTarget = subscribe(target as any, () => {
+        const deleted = !!(target as any)[ObjectDeletedId];
+        get.setSelf(deleted ? undefined : target);
+      });
+      const deleted = !!(target as any)[ObjectDeletedId];
+      return deleted ? undefined : target;
+    };
+
+    get.addFinalizer(() => {
+      unsubscribeTarget?.();
+    });
+
+    return loadRefTarget(ref, get, setupSubscription);
   });
 });

package/src/internal/Ref/ref.test.ts

@@ -5,7 +5,7 @@
 import * as Schema from 'effect/Schema';
 import { describe, expect, test } from 'vitest';
 
-import { EID, EntityId, DXN } from '@dxos/keys';
+import { DXN, EID, EntityId } from '@dxos/keys';
 
 import * as Type from '../../Type';
 import { EchoObjectSchema, getObjectEchoUri } from '../Entity';
@@ -45,16 +45,16 @@ describe('Ref', () => {
 
     const json = JSON.parse(JSON.stringify(contact));
     expect(json).toEqual({
-      id: contact.id,
+      'id': contact.id,
       '@type': `dxn:${Type.getTypename(Contact)}:${Type.getVersion(Contact)}`,
       '@meta': {
         keys: [],
       },
-      name: 'John Doe',
-      tasks: [
+      'name': 'John Doe',
+      'tasks': [
         {
           '/': getObjectEchoUri(task)!.toString(),
-          target: JSON.parse(JSON.stringify(task)),
+          'target': JSON.parse(JSON.stringify(task)),
         },
       ],
     });
@@ -66,13 +66,13 @@ describe('Ref', () => {
 
     const json = JSON.parse(JSON.stringify(contact));
     expect(json).toEqual({
-      id: contact.id,
+      'id': contact.id,
       '@type': `dxn:${Type.getTypename(Contact)}:${Type.getVersion(Contact)}`,
       '@meta': {
         keys: [],
       },
-      name: 'John Doe',
-      tasks: [{ '/': getObjectEchoUri(task)!.toString() }],
+      'name': 'John Doe',
+      'tasks': [{ '/': getObjectEchoUri(task)!.toString() }],
     });
   });
 

package/src/internal/Ref/ref.ts

@@ -189,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>;
 
@@ -484,9 +491,9 @@ export const makeSettledRequest = (
 });
 
 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.
@@ -494,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.
    */
@@ -513,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
    */
@@ -532,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
    */
@@ -605,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.
@@ -622,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 {
@@ -641,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);
-  }
 }
 
 /**

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, () => {});