@dxos/echo 0.8.4-main.74a063c4e0 → 0.8.4-main.765dc60934

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/echo",
-  "version": "0.8.4-main.74a063c4e0",
+  "version": "0.8.4-main.765dc60934",
   "description": "ECHO API",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -8,7 +8,7 @@
     "type": "git",
     "url": "https://github.com/dxos/dxos"
   },
-  "license": "MIT",
+  "license": "FSL-1.1-Apache-2.0",
   "author": "info@dxos.org",
   "sideEffects": false,
   "type": "module",
@@ -73,6 +73,11 @@
       "types": "./dist/types/src/Key.d.ts",
       "default": "./dist/lib/neutral/Key.mjs"
     },
+    "./Migration": {
+      "source": "./src/Migration.ts",
+      "types": "./dist/types/src/Migration.d.ts",
+      "default": "./dist/lib/neutral/Migration.mjs"
+    },
     "./Obj": {
       "source": "./src/Obj.ts",
       "types": "./dist/types/src/Obj.d.ts",
@@ -130,18 +135,18 @@
   ],
   "dependencies": {
     "effect": "3.20.0",
-    "@dxos/async": "0.8.4-main.74a063c4e0",
-    "@dxos/debug": "0.8.4-main.74a063c4e0",
-    "@dxos/echo-protocol": "0.8.4-main.74a063c4e0",
-    "@dxos/effect": "0.8.4-main.74a063c4e0",
-    "@dxos/errors": "0.8.4-main.74a063c4e0",
-    "@dxos/invariant": "0.8.4-main.74a063c4e0",
-    "@dxos/keys": "0.8.4-main.74a063c4e0",
-    "@dxos/node-std": "0.8.4-main.74a063c4e0",
-    "@dxos/log": "0.8.4-main.74a063c4e0",
-    "@dxos/protocols": "0.8.4-main.74a063c4e0",
-    "@dxos/util": "0.8.4-main.74a063c4e0",
-    "@dxos/context": "0.8.4-main.74a063c4e0"
+    "@dxos/async": "0.8.4-main.765dc60934",
+    "@dxos/context": "0.8.4-main.765dc60934",
+    "@dxos/debug": "0.8.4-main.765dc60934",
+    "@dxos/effect": "0.8.4-main.765dc60934",
+    "@dxos/invariant": "0.8.4-main.765dc60934",
+    "@dxos/echo-protocol": "0.8.4-main.765dc60934",
+    "@dxos/keys": "0.8.4-main.765dc60934",
+    "@dxos/errors": "0.8.4-main.765dc60934",
+    "@dxos/log": "0.8.4-main.765dc60934",
+    "@dxos/protocols": "0.8.4-main.765dc60934",
+    "@dxos/node-std": "0.8.4-main.765dc60934",
+    "@dxos/util": "0.8.4-main.765dc60934"
   },
   "publishConfig": {
     "access": "public"

package/src/Annotation.ts

@@ -18,6 +18,7 @@ export {
   setDescriptionWithSchema,
   setLabelWithSchema,
   IconAnnotation,
+  IconFromRefAnnotation,
 } from './internal/Annotation';
 
 import type * as Schema from 'effect/Schema';

package/src/Collection.ts

@@ -25,7 +25,7 @@ export const Collection = Schema.Struct({
   }),
   Annotation.IconAnnotation.set({
     icon: 'ph--folder--regular',
-    hue: 'neutral',
+    hue: 'amber',
   }),
 );
 

package/src/Database.ts

@@ -38,7 +38,7 @@ export interface QueryFn {
 }
 
 /**
- * Common interface for Database and Queue.
+ * Common interface for Database, Feed, and Hypergraph.
  */
 export interface Queryable {
   query: QueryFn;
@@ -229,24 +229,28 @@ export const resolve: {
     }
     invariant(!schema || isInstanceOf(schema, object), 'Object type mismatch.');
     return object as any;
-  })) as any;
+  }).pipe(Effect.withSpan('Database.resolve'))) as any;
 
 /**
  * Loads an object reference.
  */
-export const load: <T>(ref: Ref<T>) => Effect.Effect<T, Err.ObjectNotFoundError, never> = Effect.fn(function* (ref) {
-  const object = yield* promiseWithCauseCapture(() => ref.tryLoad());
-  if (!object) {
-    return yield* Effect.fail(new Err.ObjectNotFoundError(ref.dxn));
-  }
-  return object;
-});
+export const load: <T>(ref: Ref<T>) => Effect.Effect<T, Err.ObjectNotFoundError, never> = Effect.fn('Database.load')(
+  function* (ref) {
+    const object = yield* promiseWithCauseCapture(() => ref.tryLoad());
+    if (!object) {
+      return yield* Effect.fail(new Err.ObjectNotFoundError(ref.dxn));
+    }
+    return object;
+  },
+);
 
 /**
  * Loads an object reference option.
  */
 // TODO(dmaretskyi): Do we need this -- you can just use `Effect.catchTag` in calling code instead.
-export const loadOption: <T>(ref: Ref<T>) => Effect.Effect<Option.Option<T>, never, never> = Effect.fn(function* (ref) {
+export const loadOption: <T>(ref: Ref<T>) => Effect.Effect<Option.Option<T>, never, never> = Effect.fn(
+  'Database.loadOption',
+)(function* (ref) {
   const object = yield* load(ref).pipe(Effect.catchTag('ObjectNotFoundError', () => Effect.succeed(undefined)));
 
   return Option.fromNullable(object);
@@ -257,21 +261,23 @@ export const loadOption: <T>(ref: Ref<T>) => Effect.Effect<Option.Option<T>, nev
  * @see {@link Database.add}
  */
 export const add = <T extends Entity.Unknown>(obj: T): Effect.Effect<T, never, Service> =>
-  Service.pipe(Effect.map(({ db }) => db.add(obj)));
+  Service.pipe(Effect.map(({ db }) => db.add(obj))).pipe(Effect.withSpan('Database.add'));
 
 /**
  * Removes an object from the database.
  * @see {@link Database.remove}
  */
 export const remove = <T extends Entity.Unknown>(obj: T): Effect.Effect<void, never, Service> =>
-  Service.pipe(Effect.map(({ db }) => db.remove(obj)));
+  Service.pipe(Effect.map(({ db }) => db.remove(obj))).pipe(Effect.withSpan('Database.remove'));
 
 /**
  * Flushes pending changes to disk.
  * @see {@link Database.flush}
  */
 export const flush = (opts?: FlushOptions) =>
-  Service.pipe(Effect.flatMap(({ db }) => promiseWithCauseCapture(() => db.flush(opts))));
+  Service.pipe(Effect.flatMap(({ db }) => promiseWithCauseCapture(() => db.flush(opts)))).pipe(
+    Effect.withSpan('Database.flush'),
+  );
 
 /**
  * Creates a `QueryResult` object that can be subscribed to.
@@ -292,7 +298,10 @@ export const runQuery: {
   <Q extends Query.Any>(query: Q): Effect.Effect<Query.Type<Q>[], never, Service>;
   <F extends Filter.Any>(filter: F): Effect.Effect<Filter.Type<F>[], never, Service>;
 } = (queryOrFilter: Query.Any | Filter.Any) =>
-  query(queryOrFilter as any).pipe(Effect.flatMap((queryResult) => promiseWithCauseCapture(() => queryResult.run())));
+  query(queryOrFilter as any).pipe(
+    Effect.flatMap((queryResult) => promiseWithCauseCapture(() => queryResult.run())),
+    Effect.withSpan('Database.runQuery'),
+  );
 
 /**
  * Executes the query once and returns the first result as or None.
@@ -305,6 +314,19 @@ export const runQueryFirst: {
     Effect.flatMap((queryResult) =>
       promiseWithCauseCapture(async () => Option.fromNullable(await queryResult.firstOrUndefined())),
     ),
+    Effect.withSpan('Database.runQueryFirst'),
+  );
+
+/**
+ * Persists schemas in the database so they replicate to other clients.
+ * @see {@link SchemaRegistry.SchemaRegistry.register}
+ */
+export const registerSchema = (
+  input: SchemaRegistry.RegisterSchemaInput[],
+): Effect.Effect<Type.RuntimeType[], never, Service> =>
+  Service.pipe(
+    Effect.flatMap(({ db }) => promiseWithCauseCapture(() => db.schemaRegistry.register(input))),
+    Effect.withSpan('Database.registerSchema'),
   );
 
 /**

package/src/Entity.ts

@@ -9,6 +9,7 @@ import type { DXN, ObjectId } from '@dxos/keys';
 
 import * as internal from './internal';
 import type * as Relation from './Relation';
+import type * as Type from './Type';
 
 // Re-export KindId and SnapshotKindId from internal.
 export const KindId = internal.KindId;
@@ -131,6 +132,12 @@ export const getDXN = (entity: Unknown | Snapshot): DXN => internal.getDXN(entit
  */
 export const getTypeDXN = internal.getTypeDXN;
 
+/**
+ * Get the schema of an entity.
+ * Returns the branded ECHO schema used to create the entity.
+ */
+export const getSchema: (entity: Unknown | Snapshot) => Type.AnyEntity | undefined = internal.getSchema as any;
+
 /**
  * Get the typename of an entity's type.
  */
@@ -191,7 +198,7 @@ export const subscribe = (entity: Unknown, callback: () => void): (() => void) =
 //
 
 /**
- * Used to provide a mutable view of an entity within `Entity.change`.
+ * Used to provide a mutable view of an entity within `Entity.update`.
  */
 export type Mutable<T> = internal.Mutable<T>;
 
@@ -199,7 +206,7 @@ export type Mutable<T> = internal.Mutable<T>;
  * Perform mutations on an entity (object or relation) within a change context.
  *
  * Entities are read-only by default. Mutations are batched and notifications fire
- * when the callback completes. Direct mutations outside of `Entity.change` will throw
+ * when the callback completes. Direct mutations outside of `Entity.update` will throw
  * at runtime.
  *
  * @param entity - The echo entity (object or relation) to mutate.
@@ -207,30 +214,30 @@ export type Mutable<T> = internal.Mutable<T>;
  *
  * @example
  * ```typescript
- * // Mutate within Entity.change
- * Entity.change(entity, (obj) => {
+ * // Mutate within Entity.update
+ * Entity.update(entity, (obj) => {
  *   obj.name = 'Updated';
  *   obj.count = 42;
  * });
  *
  * // Direct mutation throws
- * entity.name = 'Bob'; // Error: Cannot modify outside Entity.change()
+ * entity.name = 'Bob'; // Error: Cannot modify outside Entity.update()
  * ```
  *
- * Note: For type-specific operations, prefer `Obj.change` or `Relation.change`.
+ * Note: For type-specific operations, prefer `Obj.update` or `Relation.update`.
  */
-export const change = <T extends Unknown>(entity: T, callback: internal.ChangeCallback<T>): void => {
+export const update = <T extends Unknown>(entity: T, callback: internal.ChangeCallback<T>): void => {
   internal.change(entity, callback);
 };
 
 /**
  * Add a tag to an entity.
- * Must be called within an `Entity.change`, `Obj.change`, or `Relation.change` callback.
+ * Must be called within an `Entity.update`, `Obj.update`, or `Relation.update` callback.
  */
 export const addTag = (entity: Mutable<Unknown>, tag: string): void => internal.addTag(entity, tag);
 
 /**
  * Remove a tag from an entity.
- * Must be called within an `Entity.change`, `Obj.change`, or `Relation.change` callback.
+ * Must be called within an `Entity.update`, `Obj.update`, or `Relation.update` callback.
  */
 export const removeTag = (entity: Mutable<Unknown>, tag: string): void => internal.removeTag(entity, tag);

package/src/Extension.ts

@@ -43,7 +43,7 @@ export interface Extension<T> extends Record<
  *   email: 'john@example.com',
  * });
  *
- * Obj.change(obj, (obj) => {
+ * Obj.update(obj, (obj) => {
  *   Extension.set(obj.extensions, ColorExtension, 'red');
  * });
  *
@@ -103,10 +103,10 @@ export const get: {
 /**
  * Set the value of an extension in a set of values.
  *
- * Can also be used within Obj.change callback:
+ * Can also be used within Obj.update callback:
  *
  * ```ts
- * Obj.change(obj, (obj) => {
+ * Obj.update(obj, (obj) => {
  *   Extension.set(obj.extensions, ColorExtension, 'red');
  * });
  * ```

package/src/Feed.ts

@@ -80,6 +80,16 @@ export interface RetentionOptions {
   cursor?: string;
 }
 
+/**
+ * Sync options for a feed.
+ */
+export interface SyncOptions {
+  /** Push local changes to the server. Defaults to true. */
+  shouldPush?: boolean;
+  /** Pull remote changes from the server. Defaults to true. */
+  shouldPull?: boolean;
+}
+
 //
 // Factory
 //
@@ -139,6 +149,11 @@ export class FeedService extends Context.Tag('@dxos/echo/Feed/FeedService')<
       <Q extends Query.Any>(feed: Feed, query: Q): QueryResult.QueryResult<Query.Type<Q>>;
       <F extends Filter.Any>(feed: Feed, filter: F): QueryResult.QueryResult<Filter.Type<F>>;
     };
+
+    /**
+     * Syncs the feed with the server.
+     */
+    sync(feed: Feed, options?: SyncOptions): Promise<void>;
   }
 >() {}
 
@@ -166,8 +181,30 @@ export const notAvailable: Layer.Layer<FeedService> = Layer.succeed(FeedService,
   query: () => {
     throw new Error('Feed.FeedService not available');
   },
+  sync: () => {
+    throw new Error('Feed.FeedService not available');
+  },
 } as Context.Tag.Service<FeedService>);
 
+//
+// Context (per-call) service
+//
+
+/**
+ * Effect service exposing a single `Feed.Feed` as the "current" feed for a call site.
+ *
+ * @deprecated Prefer threading a `Feed.Feed` explicitly through function signatures
+ * over hiding it behind a context service.
+ */
+export class ContextFeedService extends Context.Tag('@dxos/echo/Feed/ContextFeedService')<
+  ContextFeedService,
+  {
+    readonly feed: Feed;
+  }
+>() {
+  static layer = (feed: Feed): Layer.Layer<ContextFeedService> => Layer.succeed(ContextFeedService, { feed });
+}
+
 //
 // Operations
 //
@@ -241,6 +278,21 @@ export const runQuery: {
 } = (feed: Feed, queryOrFilter: Query.Any | Filter.Any) =>
   query(feed, queryOrFilter as any).pipe(Effect.flatMap((queryResult) => Effect.promise(() => queryResult.run())));
 
+/**
+ * Syncs the feed with the server.
+ *
+ * @example
+ * ```ts
+ * yield* Feed.sync(feed);
+ * yield* Feed.sync(feed, { shouldPush: false });
+ * ```
+ */
+export const sync = (feed: Feed, options?: SyncOptions): Effect.Effect<void, never, FeedService> =>
+  Effect.gen(function* () {
+    const service = yield* FeedService;
+    yield* Effect.promise(() => service.sync(feed, options));
+  });
+
 /**
  * Creates a cursor for iterating over feed items.
  * Currently stubbed — cursor operations are not yet implemented.
@@ -271,13 +323,13 @@ export const nextOption = <T = Obj.Snapshot>(_cursor: Cursor<T>): Effect.Effect<
 
 /**
  * Sets the local retention policy for a feed.
- * Currently stubbed — queues do not yet support retention.
+ * Currently stubbed — feeds do not yet support retention.
  *
  * @example
  * ```ts
  * yield* Feed.setRetention(feed, { count: 1000 });
  * ```
  */
-// TODO(feed): Implement when queue retention is supported.
+// TODO(dmaretskyi): Implement when feed retention is supported.
 export const setRetention = (_feed: Feed, _options: RetentionOptions): Effect.Effect<void, never, FeedService> =>
   Effect.void;

package/src/Filter.ts

@@ -14,6 +14,7 @@ import { assertArgument } from '@dxos/invariant';
 import { DXN, ObjectId } from '@dxos/keys';
 
 import * as internal from './internal';
+import type * as Obj from './Obj';
 import * as Ref from './Ref';
 
 export interface Filter<T> {
@@ -157,6 +158,37 @@ export const tag = (tag: string): Any => {
   });
 };
 
+/**
+ * Options for {@link key} filter.
+ */
+export type KeyFilterOptions = {
+  /**
+   * Optional semver range expression (e.g. `^1.2.3`, `~2.0.0`, `>=1.0.0 <2.0.0`).
+   * Matches the object's meta `version` field against the range.
+   * If omitted, matches any version (including objects with no version).
+   */
+  version?: string;
+};
+
+/**
+ * Filter by registry key stored in object meta.
+ *
+ * @example
+ * ```ts
+ * Filter.key('org.example.type.foo');
+ * Filter.key('org.example.type.foo', { version: '^1.2.3' });
+ * ```
+ */
+export const key = (key: string, options?: KeyFilterOptions): Any => {
+  return new FilterClass({
+    type: 'object',
+    typename: null,
+    props: {},
+    metaKey: key,
+    metaVersion: options?.version,
+  });
+};
+
 /**
  * Filter by properties.
  */
@@ -338,6 +370,35 @@ export const updated = (range: TimeRange): Any => _timeRangeFilter('updatedAt',
  */
 export const created = (range: TimeRange): Any => _timeRangeFilter('createdAt', range);
 
+export type ChildOfOptions = {
+  /** Whether to match transitively (grandchildren, etc.). Defaults to true. */
+  transitive?: boolean;
+};
+
+/**
+ * Filter objects that are children of the specified parent(s).
+ * Accepts ECHO objects, Refs, or arrays of either.
+ * Refs are resolved to DXNs without loading; objects use {@link Obj.getDXN}.
+ * With transitive=true (default), also matches grandchildren and beyond.
+ */
+export const childOf = (
+  parents: Obj.Unknown | Ref.Unknown | readonly (Obj.Unknown | Ref.Unknown)[],
+  options?: ChildOfOptions,
+): Any => {
+  const items = Array.isArray(parents) ? parents : [parents];
+  const dxns = items.map((item) => {
+    if (Ref.isRef(item)) {
+      return item.dxn.toString();
+    }
+    return internal.getDXN(item).toString();
+  });
+  return new FilterClass({
+    type: 'child-of',
+    parents: dxns,
+    transitive: options?.transitive ?? true,
+  });
+};
+
 /**
  * Negate the filter.
  */

package/src/Hypergraph.ts

@@ -22,10 +22,10 @@ export interface RefResolutionContext {
   space?: Key.SpaceId;
 
   /**
-   * Queue that the resolution is happening from.
-   * This queue will be searched first, and then the space it belongs to.
+   * Feed that the resolution is happening from (as the underlying queue DXN).
+   * This feed will be searched first, and then the space it belongs to.
    */
-  queue?: DXN;
+  feed?: DXN;
 }
 
 export interface RefResolverOptions {

package/src/Json.test.ts

@@ -0,0 +1,175 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, expect, test } from 'vitest';
+
+import { DXN, ObjectId } from '@dxos/keys';
+import { safeStringify } from '@dxos/util';
+
+import * as Database from './Database';
+import * as Json from './Json';
+
+/** Mint a random ECHO object id usable as both a stub-db key and a DXN payload. */
+const newId = (): string => ObjectId.random();
+
+/** Build a fake encoded ref for a local-space object id. */
+const encodeRef = (id: string): { '/': string } => ({ '/': DXN.fromLocalObjectId(id).toString() });
+
+/** Minimal stub: `createRefReplacer` only touches `db.getObjectById`. */
+const makeStubDb = (objects: Record<string, unknown>): Database.Database => {
+  return {
+    getObjectById: (id: string) => objects[id],
+  } as unknown as Database.Database;
+};
+
+/**
+ * Run a value through the replacer's public contract — `JSON.stringify(value, replacer)` —
+ * then re-parse the result so tests can assert on plain JS shapes. This mirrors the way
+ * the JSON highlighter invokes the replacer in production.
+ */
+const stringifyWith = (replacer: Json.JsonReplacer, value: unknown): unknown =>
+  JSON.parse(JSON.stringify(value, replacer));
+
+describe('createRefReplacer', () => {
+  test('passes plain values through unchanged', () => {
+    const replacer = Json.createRefReplacer({ db: makeStubDb({}) });
+    const subject = { a: 1, b: 'two', c: [3, { d: 4 }] };
+    expect(stringifyWith(replacer, subject)).toEqual(subject);
+  });
+
+  test('inlines refs at default depth (1)', () => {
+    const id = newId();
+    const target = { name: 'inlined' };
+    const replacer = Json.createRefReplacer({ db: makeStubDb({ [id]: target }) });
+    const subject = { ref: encodeRef(id) };
+    expect(stringifyWith(replacer, subject)).toEqual({ ref: target });
+  });
+
+  test('does not follow refs when depth is 0', () => {
+    const id = newId();
+    const target = { name: 'inlined' };
+    const ref = encodeRef(id);
+    const replacer = Json.createRefReplacer({ db: makeStubDb({ [id]: target }), depth: 0 });
+    expect(stringifyWith(replacer, { ref })).toEqual({ ref });
+  });
+
+  test('inlines refs across multiple levels up to depth', () => {
+    const innerId = newId();
+    const middleId = newId();
+    const inner = { name: 'inner' };
+    const middle = { ref: encodeRef(innerId) };
+    const outer = { ref: encodeRef(middleId) };
+    const db = makeStubDb({ [innerId]: inner, [middleId]: middle });
+
+    expect(stringifyWith(Json.createRefReplacer({ db, depth: 1 }), outer)).toEqual({
+      ref: { ref: encodeRef(innerId) },
+    });
+
+    expect(stringifyWith(Json.createRefReplacer({ db, depth: 2 }), outer)).toEqual({
+      ref: { ref: inner },
+    });
+  });
+
+  test('leaves refs encoded when the target is missing in the db', () => {
+    const ref = encodeRef(newId());
+    const replacer = Json.createRefReplacer({ db: makeStubDb({}) });
+    expect(stringifyWith(replacer, { ref })).toEqual({ ref });
+  });
+
+  test('leaves non-DXN single-key { "/": string } objects untouched', () => {
+    // Same `{ '/': string }` shape is used by other IPLD-style refs (e.g. CIDs); those should
+    // not crash the replacer and should pass through verbatim.
+    const cidLike = { '/': 'bafybeibwzifw7izxykxz' };
+    const replacer = Json.createRefReplacer({ db: makeStubDb({}) });
+    expect(stringifyWith(replacer, { ref: cidLike })).toEqual({ ref: cidLike });
+  });
+
+  test('leaves malformed dxn strings untouched', () => {
+    const malformed = { '/': 'dxn:not-a-real-dxn' };
+    const replacer = Json.createRefReplacer({ db: makeStubDb({}) });
+    expect(stringifyWith(replacer, { ref: malformed })).toEqual({ ref: malformed });
+  });
+
+  test('leaves non-echo dxns untouched (e.g. type DXN)', () => {
+    // Type DXNs share the `dxn:` prefix but `asEchoDXN()` returns undefined.
+    const typeRef = { '/': DXN.fromTypename('com.example.Thing').toString() };
+    const replacer = Json.createRefReplacer({ db: makeStubDb({}) });
+    expect(stringifyWith(replacer, { ref: typeRef })).toEqual({ ref: typeRef });
+  });
+
+  test('inlines refs inside arrays', () => {
+    const idA = newId();
+    const idB = newId();
+    const a = { name: 'a' };
+    const b = { name: 'b' };
+    const replacer = Json.createRefReplacer({ db: makeStubDb({ [idA]: a, [idB]: b }) });
+    expect(stringifyWith(replacer, { items: [encodeRef(idA), encodeRef(idB), { plain: true }] })).toEqual({
+      items: [a, b, { plain: true }],
+    });
+  });
+
+  test('walks nested objects recursively', () => {
+    const innerId = newId();
+    const inner = { name: 'inner' };
+    const replacer = Json.createRefReplacer({ db: makeStubDb({ [innerId]: inner }) });
+    const subject = { outer: { mid: { ref: encodeRef(innerId) } } };
+    expect(stringifyWith(replacer, subject)).toEqual({ outer: { mid: { ref: inner } } });
+  });
+
+  test('a single replacer invocation does not recurse on its own', () => {
+    // The replacer is per-call; JSON.stringify drives the tree walk. Calling the replacer
+    // directly on a cyclic input must therefore return without touching the cycle.
+    const replacer = Json.createRefReplacer({ db: makeStubDb({}) });
+    const node: any = { name: 'self' };
+    node.self = node;
+
+    expect(() => replacer('', node)).not.toThrow();
+    expect(replacer('', node)).toBe(node);
+  });
+
+  test('invokes `toJSON` on resolved targets so refs in the target are re-walked', () => {
+    // Simulates the ECHO-object branch: `db.getObjectById` returns a live proxy, the replacer
+    // calls `.toJSON()` to get the encoded form, then continues walking that form. A ref nested
+    // inside the target should be inlined when there's depth budget remaining.
+    const outerId = newId();
+    const innerId = newId();
+    const inner = { name: 'inner' };
+    const target = {
+      toJSON: () => ({ nestedRef: encodeRef(innerId) }),
+    };
+    const replacer = Json.createRefReplacer({ db: makeStubDb({ [outerId]: target, [innerId]: inner }), depth: 2 });
+    expect(stringifyWith(replacer, { ref: encodeRef(outerId) })).toEqual({
+      ref: { nestedRef: inner },
+    });
+  });
+
+  test('depth budget counts ref hops, not tree depth — a ref deep in a plain tree still resolves', () => {
+    // A ref nested under arbitrarily many plain objects is one ref hop from the root, so
+    // `depth: 1` resolves it. `depth: 0` leaves it encoded.
+    const innerId = newId();
+    const inner = { name: 'inner' };
+    const subject = { a: { b: { c: { d: { ref: encodeRef(innerId) } } } } };
+
+    const inlining = Json.createRefReplacer({ db: makeStubDb({ [innerId]: inner }), depth: 1 });
+    expect(stringifyWith(inlining, subject)).toEqual({ a: { b: { c: { d: { ref: inner } } } } });
+
+    const passthrough = Json.createRefReplacer({ db: makeStubDb({ [innerId]: inner }), depth: 0 });
+    expect(stringifyWith(passthrough, subject)).toEqual(subject);
+  });
+
+  test('inlines refs when invoked through safeStringify (production path)', () => {
+    // `JsonHighlighter` runs the replacer through `@dxos/util/safeStringify`, whose inner
+    // wrapper short-circuits the root call without forwarding it to the user's filter. The
+    // replacer must therefore work on a per-call basis — not as a one-shot root tree walk.
+    // This regression-tests that integration: the `content` ref must inline.
+    const targetId = newId();
+    const target = { toJSON: () => ({ name: 'README content' }) };
+    const document = { id: '01ABC', name: 'README', content: encodeRef(targetId) };
+
+    const replacer = Json.createRefReplacer({ db: makeStubDb({ [targetId]: target }) });
+    const out = JSON.parse(safeStringify(document, replacer, 0)!);
+
+    expect(out).toEqual({ id: '01ABC', name: 'README', content: { name: 'README content' } });
+  });
+});