@dxos/echo 0.8.4-main.40e3dcdf1b → 0.8.4-main.43cb759274

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

@@ -11,14 +11,17 @@ import type * as Types from 'effect/Types';
 
 import { type ForeignKey, type QueryAST } from '@dxos/echo-protocol';
 import { assertArgument } from '@dxos/invariant';
-import { DXN, ObjectId } from '@dxos/keys';
+import { DXN, EID, EntityId, type URI } from '@dxos/keys';
 
 import * as internal from './internal';
+import type * as Obj from './Obj';
 import * as Ref from './Ref';
+// eslint-disable-next-line @dxos/rules/import-as-namespace
+import type * as Type$ from './Type';
 
 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;
 }
@@ -76,11 +79,11 @@ export const nothing = (): FilterClass => {
 };
 
 /*
- * Filter by ObjectId.
+ * Filter by EntityId.
  */
-export const id = (...ids: ObjectId[]): Any => {
+export const id = (...ids: EntityId[]): Any => {
   assertArgument(
-    ids.every((id) => ObjectId.isValid(id)),
+    ids.every((id) => EntityId.isValid(id)),
     'ids',
     'ids must be valid',
   );
@@ -99,27 +102,46 @@ export const id = (...ids: ObjectId[]): Any => {
 
 /**
  * Filter by type.
+ *
+ * Accepts a `Type.Type` entity (the value produced by `Type.makeObject` /
+ * `Type.makeRelation`), a `Schema.Union` of such entities (for filtering across a
+ * union of ECHO types), or a non-qualified typename string.
  */
-export const type = <S extends Schema.Schema.All>(
-  schema: S | string,
-  props?: Props<Schema.Schema.Type<S>>,
-): Filter<Schema.Schema.Type<S>> => {
-  if (Schema.isSchema(schema) && SchemaAST.isUnion(schema.ast)) {
-    const typenames = schema.ast.types.map((type) => internal.getTypeDXNFromSpecifier(Schema.make(type)));
+export const type: {
+  <T extends Type$.AnyEntity>(type: T, props?: Props<Type$.InstanceType<T>>): Filter<Type$.InstanceType<T>>;
+  // Schema-side overload restricted to the well-known unknown schemas and to
+  // `Schema.Union(...)` of `Type.Type` entities (for filtering across a union
+  // of ECHO types). Other raw schemas are rejected.
+  <S extends internal.UnknownTypeSchema<any, any>>(
+    schema: S,
+    props?: Props<Schema.Schema.Type<S>>,
+  ): Filter<Schema.Schema.Type<S>>;
+  <S extends Schema.Union<readonly Schema.Schema.AnyNoContext[]>>(
+    union: S,
+    props?: Props<Schema.Schema.Type<S>>,
+  ): Filter<Schema.Schema.Type<S>>;
+  (schema: string, props?: Props<unknown>): Filter<any>;
+  // Passthrough overload for callers that hold a `Type.AnyEntity | string` union
+  // (e.g. Query.type / Query.sourceOf / Query.targetOf impls). Listed last so the
+  // typed overloads above still win for monomorphic inputs.
+  (input: Type$.AnyEntity | string, props?: Props<unknown>): Filter<unknown>;
+} = (input: Type$.AnyEntity | Schema.Schema.AnyNoContext | string, props?: Props<unknown>): any => {
+  if (Schema.isSchema(input) && SchemaAST.isUnion(input.ast)) {
+    const typenames = input.ast.types.map((t) => internal.getTypeURIFromSpecifier(Schema.make(t)));
     return new FilterClass({
       type: 'or',
       filters: typenames.map((typename) => ({
         type: 'object',
-        typename: typename.toString(),
+        typename,
         props: {},
       })),
     });
   }
 
-  const dxn = internal.getTypeDXNFromSpecifier(schema);
+  const uri = internal.getTypeURIFromSpecifier(input);
   return new FilterClass({
     type: 'object',
-    typename: dxn.toString(),
+    typename: uri,
     ...propsFilterToAst(props ?? {}),
   });
 };
@@ -131,18 +153,19 @@ export const typename = (typename: string): Any => {
   assertArgument(!typename.startsWith('dxn:'), 'typename', 'Typename must no be qualified');
   return new FilterClass({
     type: 'object',
-    typename: DXN.fromTypename(typename).toString(),
+    typename: DXN.make(typename),
     props: {},
   });
 };
 
 /**
- * Filter by fully qualified type DXN.
+ * Filter by fully qualified type URI — either a typename DXN (for static schemas) or
+ * a schema-as-object EID (for stored dynamic schemas). See `getSchemaURI`.
  */
-export const typeDXN = (dxn: DXN): Any => {
+export const typeURI = (uri: URI.URI): Any => {
   return new FilterClass({
     type: 'object',
-    typename: dxn.toString(),
+    typename: uri,
     props: {},
   });
 };
@@ -157,6 +180,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.
  */
@@ -191,14 +245,14 @@ export const text = (
 /**
  * Filter by foreign keys.
  */
-export const foreignKeys = <S extends Schema.Schema.All>(
-  schema: S | string,
+export const foreignKeys = <S extends Type$.AnyEntity | string>(
+  schema: S,
   keys: ForeignKey[],
-): Filter<Schema.Schema.Type<S>> => {
-  const dxn = internal.getTypeDXNFromSpecifier(schema);
+): Filter<S extends Type$.AnyEntity ? Type$.InstanceType<S> : unknown> => {
+  const uri = internal.getTypeURIFromSpecifier(schema);
   return new FilterClass({
     type: 'object',
-    typename: dxn.toString(),
+    typename: uri,
     props: {},
     foreignKeys: keys,
   });
@@ -278,7 +332,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 +356,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 +364,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.getURI}.
+ * 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 EID.parse(item.uri);
+    }
+    return internal.getUri(item);
+  });
+  return new FilterClass({
+    type: 'child-of',
+    parents: dxns,
+    transitive: options?.transitive ?? true,
+  });
+};
+
 /**
  * Negate the filter.
  */
@@ -343,7 +454,7 @@ export const or = <Filters extends readonly Any[]>(...filters: Filters): Filter<
 // TODO(dmaretskyi): Add `Filter.match` to support pattern matching on string props.
 
 const propsFilterToAst = (predicates: Props<any>): Pick<QueryAST.FilterObject, 'id' | 'props'> => {
-  let idFilter: readonly ObjectId[] | undefined;
+  let idFilter: readonly EntityId[] | undefined;
   if ('id' in predicates) {
     assertArgument(
       typeof predicates.id === 'string' || Array.isArray(predicates.id),
@@ -351,7 +462,7 @@ const propsFilterToAst = (predicates: Props<any>): Pick<QueryAST.FilterObject, '
       'invalid id filter',
     );
     idFilter = typeof predicates.id === 'string' ? [predicates.id] : predicates.id;
-    Schema.Array(ObjectId).pipe(Schema.validateSync)(idFilter);
+    Schema.Array(EntityId).pipe(Schema.validateSync)(idFilter);
   }
 
   return {
@@ -389,3 +500,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/Hypergraph.ts

@@ -2,14 +2,14 @@
 // Copyright 2025 DXOS.org
 //
 
-import { type DXN } from '@dxos/keys';
+import { type URI } from '@dxos/keys';
 
 import type * as Database from './Database';
 import type * as Entity from './Entity';
 import type * as internal from './internal';
 import type * as Key from './Key';
 import type * as Ref from './Ref';
-import type * as SchemaRegistry from './SchemaRegistry';
+import type * as Registry from './Registry';
 
 /**
  * Resolution context.
@@ -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.
+   * This feed will be searched first, and then the space it belongs to.
    */
-  queue?: DXN;
+  feed?: URI.URI;
 }
 
 export interface RefResolverOptions {
@@ -46,7 +46,12 @@ export interface RefResolverOptions {
  * Manages cross-space database interactions.
  */
 export interface Hypergraph extends Database.Queryable {
-  get schemaRegistry(): SchemaRegistry.SchemaRegistry;
+  /**
+   * In-process registry of keyed objects and static schema types.
+   * Populated at startup via `registry.add(objects)` / `registry.add(schemas)`.
+   * Queries that include no explicit from() clause will fan out to this registry automatically.
+   */
+  get registry(): Registry.Registry;
 
   /**
    * Query objects.
@@ -57,11 +62,11 @@ export interface Hypergraph extends Database.Queryable {
    * Creates a reference to an existing object in the database.
    *
    * NOTE: The reference may be dangling if the object is not present in the database.
-   * NOTE: Difference from `Ref.fromDXN`
-   * `Ref.fromDXN(dxn)` returns an unhydrated reference. The `.load` and `.target` APIs will not work.
+   * NOTE: Difference from `Ref.fromURI`
+   * `Ref.fromURI(dxn)` returns an unhydrated reference. The `.load` and `.target` APIs will not work.
    * `db.makeRef(dxn)` is preferable in cases with access to the database.
    */
-  makeRef<T extends Entity.Unknown = Entity.Unknown>(dxn: DXN): Ref.Ref<T>;
+  makeRef<T extends Entity.Unknown = Entity.Unknown>(uri: URI.URI): Ref.Ref<T>;
 
   /**
    * @param hostDb Host database for reference resolution.

package/src/Json.test.ts

@@ -0,0 +1,175 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, expect, test } from 'vitest';
+
+import { DXN, EID, EntityId } 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 => EntityId.random();
+
+/** Build a fake encoded ref for a local-space object id. */
+const encodeRef = (id: string): { '/': string } => ({ '/': EID.make({ entityId: id }) });
+
+/** 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.make('com.example.Thing') };
+    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' } });
+  });
+});