@dxos/echo 0.8.4-main.d05673bc65 → 0.8.4-main.dfabb4ec29

package/src/Feed.ts

@@ -10,8 +10,9 @@ import * as Layer from 'effect/Layer';
 import type * as Option from 'effect/Option';
 import * as Schema from 'effect/Schema';
 
-import { DXN } from '@dxos/keys';
+import { DXN, type ObjectId } from '@dxos/keys';
 
+import * as Annotation from './Annotation';
 import type * as Entity from './Entity';
 import type * as Filter from './Filter';
 import * as internal from './internal';
@@ -33,12 +34,24 @@ export const Feed = Schema.Struct({
   name: Schema.String.pipe(Schema.optional),
   /** Identifier for the feed's kind (e.g., plugin id). */
   kind: Schema.String.pipe(internal.FormInputAnnotation.set(false), Schema.optional),
+
+  /**
+   * Feed namespace.
+   * Controls how feed data is stored and replicated.
+   * - `data`: Data feed (default).
+   * - `trace`: Trace feed.
+   */
+  namespace: Schema.optional(Schema.Literal('data', 'trace')),
 }).pipe(
   Type.object({
     typename: 'org.dxos.type.feed',
     version: '0.1.0',
   }),
   internal.SystemTypeAnnotation.set(true),
+  Annotation.IconAnnotation.set({
+    icon: 'ph--rows--regular',
+    hue: 'yellow',
+  }),
 );
 
 /**
@@ -50,12 +63,6 @@ export interface Feed extends Schema.Schema.Type<typeof Feed> {}
 // Types
 //
 
-/**
- * Meta key source for storing the backing DXN bound to a feed object.
- */
-// TODO(dmaretskyi): Enforce that Feed ObjectId = feed storage ID. And remove this key.
-export const DXN_KEY = 'org.dxos.key.feed';
-
 /**
  * Opaque cursor for iterating over feed items.
  */
@@ -89,14 +96,38 @@ export interface RetentionOptions {
 export const make = (props: Obj.MakeProps<typeof Feed> = {}): Feed => Obj.make(Feed, props);
 
 /**
- * Reads the queue DXN from feed metadata.
+ * Derives the queue DXN from the feed object's DXN.
+ * Returns `undefined` when the feed is not stored in a space yet.
  *
- * @deprecated
+ * Used internally by the feed service layer.
  */
-// TODO(wittjosiah): Align backing feed dxn's with object DXN.
 export const getQueueDxn = (feed: Feed): DXN | undefined => {
-  const keys = Obj.getKeys(feed, DXN_KEY);
-  return keys.length === 0 ? undefined : DXN.parse(keys[0].id);
+  const self = Obj.getDXN(feed).asEchoDXN();
+  if (!self || !self.spaceId) {
+    return undefined;
+  }
+  return new DXN(DXN.kind.QUEUE, [feed.namespace ?? 'data', self.spaceId, self.echoId]);
+};
+
+/**
+ * Creates a Feed object from a queue DXN, inferring the feed's id and namespace from the DXN parts.
+ *
+ * The resulting Feed, when added to the same space as the queue, will have a queue DXN
+ * equal to the input (see `Feed.getQueueDxn`). Useful when migrating `Ref(Queue)` fields to
+ * `Ref(Feed.Feed)`.
+ *
+ * @remarks Unsafe because the caller must ensure the queue DXN's space matches the database
+ * the feed is added to; the feed id is set from the queue id, bypassing id generation.
+ */
+export const unsafeFromQueueDXN = (queueDxn: DXN): Feed => {
+  const parts = queueDxn.asQueueDXN();
+  if (!parts) {
+    throw new Error(`Expected a queue DXN, got: ${queueDxn.toString()}`);
+  }
+  return Obj.make(Feed, {
+    id: parts.queueId as ObjectId,
+    namespace: parts.subspaceTag === 'trace' ? 'trace' : undefined,
+  });
 };
 
 //
@@ -108,8 +139,8 @@ export const getQueueDxn = (feed: Feed): DXN | undefined => {
  * Provides the bridge to the underlying storage implementation.
  * Must be provided by the application layer (e.g., echo-db).
  */
-export class Service extends Context.Tag('@dxos/echo/Feed/Service')<
-  Service,
+export class FeedService extends Context.Tag('@dxos/echo/Feed/FeedService')<
+  FeedService,
   {
     /**
      * Appends items to a feed.
@@ -132,21 +163,31 @@ export class Service extends Context.Tag('@dxos/echo/Feed/Service')<
   }
 >() {}
 
+/**
+ * @deprecated Use `FeedService` instead.
+ */
+export type Service = FeedService;
+
+/**
+ * @deprecated Use `FeedService` instead.
+ */
+export const Service = FeedService;
+
 /**
  * Layer that provides a Feed service that throws when accessed.
  * Useful as a default layer when no feed service is available.
  */
-export const notAvailable: Layer.Layer<Service> = Layer.succeed(Service, {
+export const notAvailable: Layer.Layer<FeedService> = Layer.succeed(FeedService, {
   append: () => {
-    throw new Error('Feed.Service not available');
+    throw new Error('Feed.FeedService not available');
   },
   remove: () => {
-    throw new Error('Feed.Service not available');
+    throw new Error('Feed.FeedService not available');
   },
   query: () => {
-    throw new Error('Feed.Service not available');
+    throw new Error('Feed.FeedService not available');
   },
-} as Context.Tag.Service<Service>);
+} as Context.Tag.Service<FeedService>);
 
 //
 // Operations
@@ -160,9 +201,9 @@ export const notAvailable: Layer.Layer<Service> = Layer.succeed(Service, {
  * yield* Feed.append(feed, [Obj.make(Notification, { title: 'Hello' })]);
  * ```
  */
-export const append = (feed: Feed, items: Entity.Unknown[]): Effect.Effect<void, never, Service> =>
+export const append = (feed: Feed, items: Entity.Unknown[]): Effect.Effect<void, never, FeedService> =>
   Effect.gen(function* () {
-    const service = yield* Service;
+    const service = yield* FeedService;
     yield* Effect.promise(() => service.append(feed, items));
   });
 
@@ -175,9 +216,9 @@ export const append = (feed: Feed, items: Entity.Unknown[]): Effect.Effect<void,
  * ```
  */
 // TODO(dmaretskyi): Should we allow snapshots here? - what does it mean to remove a snapshot?
-export const remove = (feed: Feed, items: (Entity.Unknown | Obj.Snapshot)[]): Effect.Effect<void, never, Service> =>
+export const remove = (feed: Feed, items: (Entity.Unknown | Obj.Snapshot)[]): Effect.Effect<void, never, FeedService> =>
   Effect.gen(function* () {
-    const service = yield* Service;
+    const service = yield* FeedService;
     const ids = items.map((item) => item.id);
     yield* Effect.promise(() => service.remove(feed, ids));
   });
@@ -196,10 +237,16 @@ export const remove = (feed: Feed, items: (Entity.Unknown | Obj.Snapshot)[]): Ef
 //                   const object = yield* feed.pipe(Feed.query(Filter.type(Person))).first;
 // ... unify for Database and schema queries.
 export const query: {
-  <Q extends Query.Any>(feed: Feed, query: Q): Effect.Effect<QueryResult.QueryResult<Query.Type<Q>>, never, Service>;
-  <F extends Filter.Any>(feed: Feed, filter: F): Effect.Effect<QueryResult.QueryResult<Filter.Type<F>>, never, Service>;
+  <Q extends Query.Any>(
+    feed: Feed,
+    query: Q,
+  ): Effect.Effect<QueryResult.QueryResult<Query.Type<Q>>, never, FeedService>;
+  <F extends Filter.Any>(
+    feed: Feed,
+    filter: F,
+  ): Effect.Effect<QueryResult.QueryResult<Filter.Type<F>>, never, FeedService>;
 } = (feed: Feed, queryOrFilter: Query.Any | Filter.Any) =>
-  Service.pipe(Effect.map((service) => service.query(feed, queryOrFilter as any) as QueryResult.QueryResult<any>));
+  FeedService.pipe(Effect.map((service) => service.query(feed, queryOrFilter as any) as QueryResult.QueryResult<any>));
 
 /**
  * Executes a feed query once and returns the results.
@@ -210,8 +257,8 @@ export const query: {
  * ```
  */
 export const runQuery: {
-  <Q extends Query.Any>(feed: Feed, query: Q): Effect.Effect<Query.Type<Q>[], never, Service>;
-  <F extends Filter.Any>(feed: Feed, filter: F): Effect.Effect<Filter.Type<F>[], never, Service>;
+  <Q extends Query.Any>(feed: Feed, query: Q): Effect.Effect<Query.Type<Q>[], never, FeedService>;
+  <F extends Filter.Any>(feed: Feed, filter: F): Effect.Effect<Filter.Type<F>[], never, FeedService>;
 } = (feed: Feed, queryOrFilter: Query.Any | Filter.Any) =>
   query(feed, queryOrFilter as any).pipe(Effect.flatMap((queryResult) => Effect.promise(() => queryResult.run())));
 
@@ -226,21 +273,21 @@ export const runQuery: {
  * ```
  */
 // TODO(wittjosiah): Implement cursor operations. Use Effect streams?
-export const cursor = <T = Obj.Snapshot>(_feed: Feed): Effect.Effect<Cursor<T>, never, Service> =>
+export const cursor = <T = Obj.Snapshot>(_feed: Feed): Effect.Effect<Cursor<T>, never, FeedService> =>
   Effect.succeed({ _tag: 'Cursor' } as Cursor<T>);
 
 /**
  * Returns the next item from a feed cursor.
  * Currently stubbed — cursor operations are not yet implemented.
  */
-export const next = <T = Obj.Snapshot>(_cursor: Cursor<T>): Effect.Effect<T, never, Service> =>
+export const next = <T = Obj.Snapshot>(_cursor: Cursor<T>): Effect.Effect<T, never, FeedService> =>
   Effect.die('Feed.next is not yet implemented');
 
 /**
  * Returns the next item from a feed cursor as an Option.
  * Currently stubbed — cursor operations are not yet implemented.
  */
-export const nextOption = <T = Obj.Snapshot>(_cursor: Cursor<T>): Effect.Effect<Option.Option<T>, never, Service> =>
+export const nextOption = <T = Obj.Snapshot>(_cursor: Cursor<T>): Effect.Effect<Option.Option<T>, never, FeedService> =>
   Effect.die('Feed.nextOption is not yet implemented');
 
 /**
@@ -253,5 +300,5 @@ export const nextOption = <T = Obj.Snapshot>(_cursor: Cursor<T>): Effect.Effect<
  * ```
  */
 // TODO(feed): Implement when queue retention is supported.
-export const setRetention = (_feed: Feed, _options: RetentionOptions): Effect.Effect<void, never, Service> =>
+export const setRetention = (_feed: Feed, _options: RetentionOptions): Effect.Effect<void, never, FeedService> =>
   Effect.void;

package/src/Filter.test.ts

@@ -0,0 +1,90 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, expect, test } from 'vitest';
+
+import * as Filter from './Filter';
+
+describe('Filter timestamp builders', () => {
+  test('updated({ after }) produces correct AST', () => {
+    const ts = 1700000000000;
+    const f = Filter.updated({ after: ts });
+    expect(f.ast).toEqual({ type: 'timestamp', field: 'updatedAt', operator: 'gte', value: ts });
+  });
+
+  test('updated({ before }) produces correct AST', () => {
+    const ts = 1700000000000;
+    const f = Filter.updated({ before: ts });
+    expect(f.ast).toEqual({ type: 'timestamp', field: 'updatedAt', operator: 'lte', value: ts });
+  });
+
+  test('created({ after }) produces correct AST', () => {
+    const ts = 1700000000000;
+    const f = Filter.created({ after: ts });
+    expect(f.ast).toEqual({ type: 'timestamp', field: 'createdAt', operator: 'gte', value: ts });
+  });
+
+  test('created({ before }) produces correct AST', () => {
+    const ts = 1700000000000;
+    const f = Filter.created({ before: ts });
+    expect(f.ast).toEqual({ type: 'timestamp', field: 'createdAt', operator: 'lte', value: ts });
+  });
+
+  test('updated() accepts Date objects', () => {
+    const date = new Date('2026-03-20T21:00:00Z');
+    const f = Filter.updated({ after: date });
+    expect(f.ast).toEqual({ type: 'timestamp', field: 'updatedAt', operator: 'gte', value: date.getTime() });
+  });
+
+  test('created() accepts Date objects', () => {
+    const date = new Date('2026-03-20T09:00:00Z');
+    const f = Filter.created({ before: date });
+    expect(f.ast).toEqual({ type: 'timestamp', field: 'createdAt', operator: 'lte', value: date.getTime() });
+  });
+
+  test('updated({ after, before }) produces AND of two timestamp nodes', () => {
+    const from = 1700000000000;
+    const to = 1700086400000;
+    const f = Filter.updated({ after: from, before: to });
+    expect(f.ast).toEqual({
+      type: 'and',
+      filters: [
+        { type: 'timestamp', field: 'updatedAt', operator: 'gte', value: from },
+        { type: 'timestamp', field: 'updatedAt', operator: 'lte', value: to },
+      ],
+    });
+  });
+
+  test('updated({ after, before }) accepts Date objects', () => {
+    const from = new Date('2026-03-19T00:00:00Z');
+    const to = new Date('2026-03-20T00:00:00Z');
+    const f = Filter.updated({ after: from, before: to });
+    expect(f.ast).toEqual({
+      type: 'and',
+      filters: [
+        { type: 'timestamp', field: 'updatedAt', operator: 'gte', value: from.getTime() },
+        { type: 'timestamp', field: 'updatedAt', operator: 'lte', value: to.getTime() },
+      ],
+    });
+  });
+
+  test('timestamp filters compose with and()', () => {
+    const typeFilter = Filter.everything();
+    const timeFilter = Filter.updated({ after: 1700000000000 });
+    const combined = Filter.and(typeFilter, timeFilter);
+    expect(combined.ast.type).toBe('and');
+    expect((combined.ast as any).filters).toHaveLength(2);
+    expect((combined.ast as any).filters[1]).toEqual({
+      type: 'timestamp',
+      field: 'updatedAt',
+      operator: 'gte',
+      value: 1700000000000,
+    });
+  });
+
+  test('timestamp filters pass the is() check', () => {
+    const f = Filter.updated({ after: Date.now() });
+    expect(Filter.is(f)).toBe(true);
+  });
+});

package/src/Filter.ts

@@ -14,11 +14,12 @@ 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> {
   // TODO(dmaretskyi): See new effect-schema approach to variance.
-  '~Filter': { value: Types.Contravariant<T> };
+  '~Filter': { value: Types.Covariant<T> };
 
   ast: QueryAST.Filter;
 }
@@ -278,7 +279,7 @@ export const lte = <T>(value: T): Filter<T | undefined> => {
  * Predicate for property to be in the provided array.
  * @param values - Values to check against.
  */
-const in$ = <T>(...values: T[]): Filter<T | undefined> => {
+const in$ = <T>(...values: T[]): Filter<T> => {
   return new FilterClass({
     type: 'in',
     values,
@@ -302,7 +303,7 @@ export const contains = <T>(value: T): Filter<readonly T[] | undefined> => {
  * @param from - Start of the range (inclusive).
  * @param to - End of the range (exclusive).
  */
-export const between = <T>(from: T, to: T): Filter<unknown> => {
+export const between = <T>(from: T, to: T): Filter<T> => {
   return new FilterClass({
     type: 'range',
     from,
@@ -310,6 +311,63 @@ export const between = <T>(from: T, to: T): Filter<unknown> => {
   });
 };
 
+type TimeRange = { after?: Date | number; before?: Date | number };
+
+const _toUnixMs = (date: Date | number): number => (typeof date === 'number' ? date : date.getTime());
+
+const _timeRangeFilter = (field: 'updatedAt' | 'createdAt', range: TimeRange): Any => {
+  const filters: Any[] = [];
+  if (range.after != null) {
+    filters.push(new FilterClass({ type: 'timestamp', field, operator: 'gte', value: _toUnixMs(range.after) }));
+  }
+  if (range.before != null) {
+    filters.push(new FilterClass({ type: 'timestamp', field, operator: 'lte', value: _toUnixMs(range.before) }));
+  }
+  if (filters.length === 0) {
+    return everything();
+  }
+  return filters.length === 1 ? filters[0] : and(...filters);
+};
+
+/**
+ * Filter objects by updatedAt timestamp.
+ */
+export const updated = (range: TimeRange): Any => _timeRangeFilter('updatedAt', range);
+
+/**
+ * Filter objects by createdAt timestamp.
+ */
+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.
  */
@@ -389,3 +447,8 @@ const processPredicate = (predicate: any): QueryAST.Filter => {
     Match.orElse((value) => eq(value).ast),
   );
 };
+
+/**
+ * Returns a human-readable string representation of a Filter AST.
+ */
+export const pretty = (filter: Any): string => internal.prettyFilter(filter.ast);

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' } });
+  });
+});