@byline/core 3.20.4 → 4.0.0

package/dist/services/populate.js

@@ -5,11 +5,135 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
-import { applyBeforeRead } from '../auth/apply-before-read.js';
+/**
+ * Relationship population service.
+ *
+ * `populateDocuments` walks a set of reconstructed documents, finds every
+ * relation leaf that matches a caller-supplied populate spec, batches
+ * fetches against each target collection (one DB round-trip per depth
+ * level per target collection), and replaces each leaf in place with the
+ * populated document. Missing targets become a `{ _resolved: false }`
+ * stub; already-visited targets become a `{ _cycle: true }` stub.
+ *
+ * Consumed by both `@byline/client` (external read API with `populate`
+ * and `depth` options) and the admin webapp's API-preview server fn.
+ *
+ * A request-scoped `ReadContext` is threaded through the walk. Its
+ * `visited` set and `readCount` budget guard against recursive reads —
+ * particularly the A→B→A failure mode that appears when future
+ * `afterRead` hooks invoke their own reads from within populated
+ * documents. The guard is in place from day one so that the hook work
+ * in Phase 4+ cannot reintroduce the problem.
+ *
+ * See docs/04-collections/02-relationships.md for the full design rationale.
+ *
+ * ---------------------------------------------------------------------
+ * DSL summary
+ * ---------------------------------------------------------------------
+ *
+ * The populate DSL has two independent axes:
+ *
+ *   1. **Scope** — which relations in the *source* document to walk.
+ *   2. **Projection** — which fields of each *target* document to load.
+ *
+ * The top-level `populate` value selects scope + (optionally) a uniform
+ * projection across the whole tree:
+ *
+ *   - `populate: true`                  → walk every relation leaf,
+ *                                         default projection at every
+ *                                         depth. See below for exactly
+ *                                         what the default projection
+ *                                         returns.
+ *   - `populate: '*'`                   → walk every relation leaf, full
+ *                                         document projection at every
+ *                                         depth. Symmetric with the
+ *                                         sub-spec shorthand and intended
+ *                                         for tools like the admin API
+ *                                         preview where the whole tree
+ *                                         should be visible.
+ *   - `populate: { name: … }`           → walk only the named relations.
+ *   - `populate: undefined`             → skip populate entirely (no-op).
+ *
+ * Default projection — exactly what comes back for `true` (and for any
+ * sub-spec whose `select` is omitted):
+ *
+ *   - **Document row metadata, always present** (lives on the
+ *     `document_versions` row, not in the `store_*` tables, so it is
+ *     returned regardless of the `fields` projection):
+ *       `document_version_id`, `document_id`, `collection_id`, `path`,
+ *       `status`, `created_at`, `updated_at`.
+ *   - **The `useAsTitle` field** (schema-declared identity field;
+ *     falls back to the first declared text field when `useAsTitle`
+ *     is not set on the `CollectionDefinition`). This is the one
+ *     entry added to the `fields` object.
+ *
+ * In effect "default projection" is "enough to identify and label the
+ * target" — document metadata for wiring, plus one user-defined field
+ * (typically `title`) for a human-readable label. Callers wanting more
+ * use `'*'` (full doc) or `{ select: [...] }` (explicit fields).
+ *
+ * Each matched leaf carries a `PopulateFieldSpec` that selects projection:
+ *
+ *   - `true`                            → default projection: the target's
+ *                                         identity field (`useAsTitle`,
+ *                                         falling back to the first text
+ *                                         field). Document metadata
+ *                                         (`document_id`, `collection_id`,
+ *                                         `path`, `status`, timestamps) is
+ *                                         always included for free — it
+ *                                         lives on the row, not in the
+ *                                         store_* tables.
+ *   - `'*'`                             → full document: every field of
+ *                                         the target is loaded.
+ *   - `{ select: [...] }`               → explicit field list, merged with
+ *                                         the identity field so downstream
+ *                                         UI always has a label to render.
+ *   - `{ populate: {...} }`             → nested populate for the next
+ *                                         depth level. Combinable with
+ *                                         `select`.
+ *
+ * Examples:
+ *
+ *   populate: true
+ *     → every relation, default projection at every depth level.
+ *
+ *   populate: '*'
+ *     → every relation, full projection at every depth level
+ *       (use for API previews / debug views that want the whole tree).
+ *
+ *   populate: { heroImage: true }
+ *     → only heroImage, default projection. If heroImage's own
+ *       relations exist, they populate at the next depth with `true`.
+ *
+ *   populate: { heroImage: '*' }
+ *     → only heroImage, full document. If heroImage's own relations
+ *       exist, they populate at the next depth with `'*'` (consistent
+ *       with how `true` propagates).
+ *
+ *   populate: { author: { select: ['name'] } }
+ *     → only author; fetch `name` + identity field.
+ *
+ *   populate: { author: { select: ['name'], populate: { employer: '*' } } }
+ *     → author with `name` at depth 1; employer fully populated at depth 2.
+ *
+ * Notes:
+ *
+ *   - `'*'` belongs on the sub-spec (or as the whole top-level spec),
+ *     not inside `select`. `select` is always an explicit field list.
+ *   - Projection defaults are transitive at every depth: `true` propagates
+ *     `true` into nested levels; `'*'` propagates `'*'`. Explicit
+ *     `{ populate: {...} }` maps take precedence when declared.
+ *   - Multiple leaves pointing at the same target document are batched
+ *     into a single fetch; their projection specs are merged (any `'*'`
+ *     wins; otherwise selects union together, identity field is always
+ *     added).
+ */
+import { createRequestContext } from '@byline/auth';
+import { compileBeforeReadFilters } from '../auth/apply-before-read.js';
+import { assertActorCanPerform } from '../auth/assert-actor-can-perform.js';
 import { ERR_READ_BUDGET_EXCEEDED } from '../lib/errors.js';
-import { parseWhere } from '../query/parse-where.js';
 import { applyAfterRead } from './document-read.js';
-import { populateRichTextFields } from './richtext-populate.js';
+import { createRichTextDocumentReader, populateRichTextFields } from './richtext-populate.js';
 import { walkFieldTree } from './walk-field-tree.js';
 // ---------------------------------------------------------------------------
 // ReadContext — recursion guard
@@ -20,8 +144,6 @@ const DEFAULT_MAX_DEPTH = 8;
 export function createReadContext(overrides) {
     return {
         visited: overrides?.visited ?? new Set(),
-        afterReadFired: overrides?.afterReadFired ?? new Set(),
-        beforeReadCache: overrides?.beforeReadCache ?? new Map(),
         readCount: overrides?.readCount ?? 0,
         maxReads: overrides?.maxReads ?? DEFAULT_MAX_READS,
         maxDepth: overrides?.maxDepth ?? DEFAULT_MAX_DEPTH,
@@ -36,6 +158,9 @@ export function createReadContext(overrides) {
  */
 export async function populateDocuments(opts) {
     const ctx = opts.readContext ?? createReadContext();
+    const securityDomain = opts.securityDomain ?? {};
+    const operationRequestContext = opts.requestContext ??
+        createRequestContext({ readMode: opts.readMode ?? 'any', locale: opts.locale });
     const populate = opts.populate;
     const requestedDepth = opts.depth ?? (populate !== undefined ? 1 : 0);
     const maxDepth = Math.max(0, Math.min(requestedDepth, ctx.maxDepth));
@@ -90,13 +215,19 @@ export async function populateDocuments(opts) {
         for (const [targetCollectionId, leaves] of byTarget) {
             const targetDef = await resolveCollectionDef(opts.db, opts.collections, targetCollectionId, defCache);
             const selectList = buildBatchSelect(leaves, targetDef);
+            // Production reads always carry an operation-scoped context. Assert the
+            // target collection before any adapter access; unresolved target schemas
+            // remain unresolved rather than bypassing the collection gate.
+            if (opts.requestContext && targetDef) {
+                assertActorCanPerform(opts.requestContext, targetDef.path, 'read');
+            }
             // Only fetch IDs we haven't materialised earlier in this request.
             const idsToFetch = Array.from(new Set(leaves
                 .filter((l) => !ctx.visited.has(visitedKey(targetCollectionId, l.value.targetDocumentId)))
                 .map((l) => l.value.targetDocumentId)));
             // Resolve the target collection's `beforeRead` predicate, if any.
-            // The cache on `ctx.beforeReadCache` ensures each (collectionPath,
-            // actor) tuple only runs through the hook once per request, even
+            // Private authority-bound state ensures each collection/mode tuple only
+            // runs through the hook once per request, even
             // across populate fanout where the same target collection may be
             // visited from multiple sources.
             const targetFilters = await resolveBeforeReadFiltersForTarget({
@@ -106,9 +237,10 @@ export async function populateDocuments(opts) {
                 readContext: ctx,
                 bypassBeforeRead: opts.bypassBeforeRead,
                 db: opts.db,
+                securityDomain,
             });
             let fetched = [];
-            if (idsToFetch.length > 0) {
+            if (idsToFetch.length > 0 && targetDef) {
                 fetched = await opts.db.queries.documents.getDocumentsByDocumentIds({
                     collection_id: targetCollectionId,
                     document_ids: idsToFetch,
@@ -186,16 +318,38 @@ export async function populateDocuments(opts) {
                     // so hook authors observe fully-populated rich-text content. The
                     // gate (per-field `populateRelationsOnRead`) lives inside the
                     // service; passing the function unconditionally is correct.
-                    if (opts.richTextPopulate) {
+                    if (opts.richTextPopulate && opts.requestContext) {
                         await populateRichTextFields({
                             fields: targetDef.fields,
                             collectionPath: targetDef.path,
                             documents: [d],
                             populate: opts.richTextPopulate,
                             readContext: ctx,
+                            requestContext: opts.requestContext,
+                            readMode: opts.readMode ?? 'any',
+                            readDocuments: createRichTextDocumentReader({
+                                db: opts.db,
+                                collections: opts.collections,
+                                requestContext: opts.requestContext,
+                                readContext: ctx,
+                                readMode: opts.readMode ?? 'any',
+                                locale: opts.locale,
+                                bypassBeforeRead: opts.bypassBeforeRead,
+                                richTextPopulate: opts.richTextPopulate,
+                                securityDomain,
+                            }),
                         });
                     }
-                    await applyAfterRead({ doc: d, definition: targetDef, readContext: ctx });
+                    await applyAfterRead({
+                        doc: d,
+                        definition: targetDef,
+                        readContext: ctx,
+                        requestContext: operationRequestContext,
+                        locale: opts.locale,
+                        readMode: opts.readMode,
+                        projection: selectList,
+                        materialization: 'relation-target',
+                    });
                 }
                 if (!targetDef || queuedForNext.has(key))
                     continue;
@@ -274,31 +428,29 @@ async function resolveCollectionDef(db, collections, id, cache) {
  * the EXISTS-loop entirely.
  */
 async function resolveBeforeReadFiltersForTarget(params) {
-    const { targetDef, collections, requestContext, readContext, bypassBeforeRead, db } = params;
+    const { targetDef, collections, requestContext, readContext, bypassBeforeRead, db, securityDomain, } = params;
     if (!targetDef || !requestContext || bypassBeforeRead)
         return undefined;
-    const predicate = await applyBeforeRead({
+    return compileBeforeReadFilters({
         definition: targetDef,
         requestContext,
         readContext,
-    });
-    if (predicate == null)
-        return undefined;
-    const parsed = await parseWhere(predicate, targetDef, {
-        collections,
-        resolveCollectionId: async (path) => {
-            // Match the target collection by path against the loaded collection
-            // list first (cheap, in-memory); fall back to a DB lookup for cases
-            // where a hook references a collection not loaded into the same
-            // populate context. This mirrors `CollectionHandle`'s parser ctx.
-            const local = collections.find((c) => c.path === path);
-            if (local?.id)
-                return local.id;
-            const row = await db.queries.collections.getCollectionByPath(path);
-            return row?.id ?? '';
+        securityDomain,
+        parseContext: {
+            collections,
+            resolveCollectionId: async (path) => {
+                // Match the target collection by path against the loaded collection
+                // list first (cheap, in-memory); fall back to a DB lookup for cases
+                // where a hook references a collection not loaded into the same
+                // populate context. This mirrors `CollectionHandle`'s parser ctx.
+                const local = collections.find((c) => c.path === path);
+                if (local?.id)
+                    return local.id;
+                const row = await db.queries.collections.getCollectionByPath(path);
+                return row?.id ?? '';
+            },
         },
     });
-    return parsed.filters.length > 0 ? parsed.filters : undefined;
 }
 /**
  * Collect every relation leaf whose name matches `populate`. Structure

package/dist/services/populate.test.node.js

@@ -5,6 +5,7 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
+import { AdminAuth, createRequestContext } from '@byline/auth';
 import { describe, expect, it, vi } from 'vitest';
 import { BylineError, ErrorCodes } from '../lib/errors.js';
 import { __internal, createReadContext, populateDocuments } from './populate.js';
@@ -150,12 +151,23 @@ function makeMockAdapter(store = {}, pathByCollectionId = {}) {
                 setOrderKey: vi.fn(),
                 placeTreeNode: vi.fn(),
                 removeFromTree: vi.fn(),
+                promoteChildrenAndRemoveFromTree: vi.fn(async () => ({
+                    removed: {
+                        changed: false,
+                        before: { placed: false, parentDocumentId: null, orderKey: null, index: null },
+                        after: { placed: false, parentDocumentId: null, orderKey: null, index: null },
+                        beforeSiblingDocumentIds: [],
+                        beforeSubtreeDocumentIds: [],
+                    },
+                    promoted: [],
+                })),
             },
             counters: {
                 ensureCounterGroup: vi.fn(),
                 nextCounterValue: vi.fn(),
                 nextScopedCounterValue: vi.fn(),
             },
+            audit: { append: vi.fn(async () => ({ id: 'audit-1' })) },
         },
         queries: {
             collections: {
@@ -164,6 +176,7 @@ function makeMockAdapter(store = {}, pathByCollectionId = {}) {
                 getCollectionById,
             },
             documents: {
+                getDocumentSystemFieldsForUpdate: vi.fn(async () => null),
                 getDocumentById: vi.fn(),
                 getCurrentVersionMetadata: vi.fn(),
                 getCurrentPath: vi.fn(),
@@ -184,7 +197,18 @@ function makeMockAdapter(store = {}, pathByCollectionId = {}) {
                 getTreeParent: vi.fn(),
                 getTreeSubtree: vi.fn(),
             },
+            audit: {
+                getDocumentAuditLog: vi.fn(async () => ({
+                    entries: [],
+                    meta: { total: 0, page: 1, pageSize: 20, totalPages: 0 },
+                })),
+                findAuditLog: vi.fn(async () => ({
+                    entries: [],
+                    meta: { total: 0, page: 1, pageSize: 20, totalPages: 0 },
+                })),
+            },
         },
+        withTransaction: async (fn) => fn(),
     };
     return { db, getDocumentsByDocumentIds, getCollectionById };
 }
@@ -353,6 +377,41 @@ describe('buildBatchSelect', () => {
 // populateDocuments — behaviour
 // ---------------------------------------------------------------------------
 describe('populateDocuments', () => {
+    it('isolates direct callers by default and shares compiled filters only with an explicit domain', async () => {
+        const beforeRead = vi.fn(() => ({ name: 'allowed' }));
+        const scopedAuthors = {
+            ...authorsCollection,
+            hooks: { beforeRead },
+        };
+        const { db, getDocumentsByDocumentIds } = makeMockAdapter();
+        const readContext = createReadContext();
+        const requestContext = createRequestContext({
+            actor: new AdminAuth({ id: 'reader', abilities: ['collections.authors.read'] }),
+        });
+        const populate = (suffix, securityDomain) => populateDocuments({
+            db,
+            collections: [postsCollection, scopedAuthors],
+            collectionId: 'posts',
+            documents: [
+                shapedDoc('posts', `p-${suffix}`, {
+                    author: relationRef('authors', `a-${suffix}`),
+                }),
+            ],
+            populate: true,
+            readContext,
+            requestContext,
+            securityDomain,
+        });
+        await populate('implicit-a');
+        await populate('implicit-b');
+        const sharedDomain = {};
+        await populate('explicit-a', sharedDomain);
+        await populate('explicit-b', sharedDomain);
+        const calls = getDocumentsByDocumentIds.mock.calls;
+        expect(calls[1]?.[0].filters).not.toBe(calls[0]?.[0].filters);
+        expect(calls[3]?.[0].filters).toBe(calls[2]?.[0].filters);
+        expect(beforeRead).toHaveBeenCalledTimes(3);
+    });
     it('is a no-op when populate is omitted', async () => {
         const { db, getDocumentsByDocumentIds } = makeMockAdapter();
         const doc = shapedDoc('posts', 'p1', { author: relationRef('authors', 'a1') });

package/dist/services/richtext-embed.d.ts

@@ -5,8 +5,42 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
-import type { FieldSet, RichTextEmbedFn, RichTextField } from '../@types/field-types.js';
-import type { ReadContext } from '../@types/index.js';
+/**
+ * Richtext embed service — walks an outgoing document, finds every
+ * rich-text leaf (including those nested inside `group` / `array` /
+ * `blocks` structures), gates each leaf by its `embedRelationsOnSave`
+ * flag, and dispatches to the registered richtext embed adapter so
+ * link envelopes (and any future write-time embeds) can be refreshed
+ * before the value is flattened and persisted.
+ *
+ * Mirror of `richtext-populate.ts`. Slots into the document-lifecycle
+ * write path:
+ *
+ *   beforeCreate / beforeUpdate
+ *     → assignCounterValues
+ *     → embedRichTextFields       (this module)
+ *     → createDocumentVersion
+ *     → afterCreate / afterUpdate
+ *
+ * Per-leaf errors are logged and swallowed — leaving the persisted state
+ * for that leaf as the editor submitted it. Aligns with the strategy's
+ * "branch C — hard error" non-destructive fail mode (see
+ * docs/RICHTEXT-LINK-REFACTOR-STRATEGY.md § 3.3).
+ *
+ * Multi-locale (`locale: 'all'`) writes: when a richText leaf's value is
+ * a `{ <locale>: lexicalJson }` map (the shape used by
+ * `restoreDocumentVersion` and `duplicateDocument`), the adapter's
+ * `getLexicalRoot` parses the object as a single tree, finds no `root`
+ * key and no `children` array, and yields nothing. So embed is a no-op
+ * on multi-locale writes — the persisted state carries forward exactly
+ * what the source had. Per-locale walking is a deliberate future
+ * refinement; today's behaviour matches the populate side (which only
+ * fires on locale-scoped reads) and the renderer's fallback chain
+ * handles stale embedded paths.
+ */
+import type { RequestContext } from '@byline/auth';
+import type { FieldSet, RichTextEmbedFn, RichTextField, RichTextReadDocumentsFn } from '../@types/field-types.js';
+import type { ReadContext, ReadMode } from '../@types/index.js';
 import type { BylineLogger } from '../lib/logger.js';
 /**
  * Resolve the effective `embedRelationsOnSave` for a richText field.
@@ -32,6 +66,9 @@ export interface EmbedRichTextFieldsOptions {
      * visited-set / read-budget machinery as the rest of the framework.
      */
     readContext: ReadContext;
+    requestContext: RequestContext;
+    readMode: ReadMode;
+    readDocuments: RichTextReadDocumentsFn;
     /** Structured logger — used for branch-C per-leaf error reporting. */
     logger: BylineLogger;
 }

package/dist/services/richtext-embed.js

@@ -5,39 +5,6 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
-/**
- * Richtext embed service — walks an outgoing document, finds every
- * rich-text leaf (including those nested inside `group` / `array` /
- * `blocks` structures), gates each leaf by its `embedRelationsOnSave`
- * flag, and dispatches to the registered richtext embed adapter so
- * link envelopes (and any future write-time embeds) can be refreshed
- * before the value is flattened and persisted.
- *
- * Mirror of `richtext-populate.ts`. Slots into the document-lifecycle
- * write path:
- *
- *   beforeCreate / beforeUpdate
- *     → assignCounterValues
- *     → embedRichTextFields       (this module)
- *     → createDocumentVersion
- *     → afterCreate / afterUpdate
- *
- * Per-leaf errors are logged and swallowed — leaving the persisted state
- * for that leaf as the editor submitted it. Aligns with the strategy's
- * "branch C — hard error" non-destructive fail mode (see
- * docs/RICHTEXT-LINK-REFACTOR-STRATEGY.md § 3.3).
- *
- * Multi-locale (`locale: 'all'`) writes: when a richText leaf's value is
- * a `{ <locale>: lexicalJson }` map (the shape used by
- * `restoreDocumentVersion` and `duplicateDocument`), the adapter's
- * `getLexicalRoot` parses the object as a single tree, finds no `root`
- * key and no `children` array, and yields nothing. So embed is a no-op
- * on multi-locale writes — the persisted state carries forward exactly
- * what the source had. Per-locale walking is a deliberate future
- * refinement; today's behaviour matches the populate side (which only
- * fires on locale-scoped reads) and the renderer's fallback chain
- * handles stale embedded paths.
- */
 import { collectRichTextLeaves } from './richtext-populate.js';
 /**
  * Resolve the effective `embedRelationsOnSave` for a richText field.
@@ -58,7 +25,7 @@ export function resolveEmbedOnSave(field) {
  * downstream proceeds. Document-level errors propagate.
  */
 export async function embedRichTextFields(options) {
-    const { fields, collectionPath, data, embed, readContext, logger } = options;
+    const { fields, collectionPath, data, embed, readContext, requestContext, readMode, readDocuments, logger, } = options;
     for (const leaf of collectRichTextLeaves(fields, data)) {
         if (!resolveEmbedOnSave(leaf.field))
             continue;
@@ -68,6 +35,9 @@ export async function embedRichTextFields(options) {
                 fieldPath: leaf.fieldPath,
                 collectionPath,
                 readContext,
+                requestContext,
+                readMode,
+                readDocuments,
             });
         }
         catch (err) {

package/dist/services/richtext-embed.test.node.js

@@ -11,6 +11,7 @@
  * branch C (per-leaf error swallow). The visitor-side branches (A / B /
  * found) live in `@byline/richtext-lexical` and have their own suite.
  */
+import { createSuperAdminContext } from '@byline/auth';
 import { describe, expect, it, vi } from 'vitest';
 import { embedRichTextFields } from './richtext-embed.js';
 const noopLogger = {
@@ -24,6 +25,11 @@ const noopLogger = {
     silent: vi.fn(),
 };
 const fakeReadContext = {};
+const authOptions = {
+    requestContext: createSuperAdminContext(),
+    readMode: 'published',
+    readDocuments: vi.fn(),
+};
 const richTextValue = (label) => ({
     root: { type: 'root', children: [], _label: label },
 });
@@ -56,9 +62,15 @@ describe('embedRichTextFields', () => {
             data,
             embed,
             readContext: fakeReadContext,
+            ...authOptions,
             logger: noopLogger,
         });
         expect(embed).toHaveBeenCalledTimes(3);
+        expect(embed).toHaveBeenCalledWith(expect.objectContaining({
+            requestContext: authOptions.requestContext,
+            readMode: 'published',
+            readDocuments: authOptions.readDocuments,
+        }));
         const paths = embed.mock.calls.map((call) => call[0].fieldPath);
         expect(paths.sort()).toEqual(['body', 'faq.0.answer', 'meta.summary']);
     });
@@ -83,6 +95,7 @@ describe('embedRichTextFields', () => {
             data,
             embed,
             readContext: fakeReadContext,
+            ...authOptions,
             logger: noopLogger,
         });
         expect(embed).toHaveBeenCalledTimes(1);
@@ -116,6 +129,7 @@ describe('embedRichTextFields', () => {
             data,
             embed,
             readContext: fakeReadContext,
+            ...authOptions,
             logger,
         })).resolves.toBeUndefined();
         // All three leaves were attempted — the failure in 'second' did not
@@ -142,6 +156,7 @@ describe('embedRichTextFields', () => {
             data,
             embed,
             readContext: fakeReadContext,
+            ...authOptions,
             logger: noopLogger,
         });
         expect(embed).not.toHaveBeenCalled();

package/dist/services/richtext-populate.d.ts

@@ -23,9 +23,10 @@
  * each call has a precise `fieldPath` for error messages and so future
  * adapters can implement per-leaf caching if needed.
  */
-import { type FieldSet, type RichTextField, type RichTextPopulateFn } from '../@types/field-types.js';
+import type { RequestContext } from '@byline/auth';
+import { type FieldSet, type RichTextField, type RichTextPopulateFn, type RichTextReadDocumentsFn } from '../@types/field-types.js';
 import type { CollectionDefinition } from '../@types/collection-types.js';
-import type { ReadContext } from '../@types/index.js';
+import type { IDbAdapter, ReadContext, ReadMode } from '../@types/index.js';
 /**
  * One rich-text leaf yielded by `collectRichTextLeaves`. The walker hands
  * back a reference to the *parent container* (`parent[key]`) rather than
@@ -61,6 +62,9 @@ export interface PopulateRichTextFieldsOptions {
     /** Registered server-side populate function from `ServerConfig`. */
     populate: RichTextPopulateFn;
     readContext: ReadContext;
+    requestContext: RequestContext;
+    readMode: ReadMode;
+    readDocuments: RichTextReadDocumentsFn;
 }
 /**
  * Resolve the effective `populateRelationsOnRead` for a richText field.
@@ -76,6 +80,20 @@ export declare function resolvePopulateOnRead(field: RichTextField): boolean;
  * is `true`. Mutates document `fields` in place.
  */
 export declare function populateRichTextFields(options: PopulateRichTextFieldsOptions): Promise<void>;
+/** Build the secure batch reader exposed to editor-agnostic adapters. */
+export declare function createRichTextDocumentReader(options: {
+    db: IDbAdapter;
+    collections: readonly CollectionDefinition[];
+    requestContext: RequestContext;
+    readContext: ReadContext;
+    readMode: ReadMode;
+    locale?: string;
+    bypassBeforeRead?: true;
+    /** Private cache domain explicitly shared with the originating client read. */
+    securityDomain?: object;
+    /** Adapter reused recursively for rich-text fields on target documents. */
+    richTextPopulate?: RichTextPopulateFn;
+}): RichTextReadDocumentsFn;
 /**
  * Which richtext server adapters the host has registered. Pass both
  * flags so the validator can fail-fast on each missing-adapter case
@@ -102,4 +120,4 @@ export interface RichTextAdapterPresence {
  * Called once at `initBylineCore()` time. Fail-fast at boot is the right
  * posture; the alternative is a silent broken renderer at request time.
  */
-export declare function validateRichTextFieldFlags(collections: CollectionDefinition[], adapters: RichTextAdapterPresence): void;
+export declare function validateRichTextFieldFlags(collections: readonly CollectionDefinition[], adapters: RichTextAdapterPresence): void;