@byline/client 3.21.0 → 4.1.0

package/dist/collection-handle.js

@@ -5,7 +5,8 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
-import { applyAfterRead, applyBeforeRead, assertActorCanPerform, buildSearchDocument, changeDocumentStatus, createDocument, createReadContext, deleteDocument, ERR_VALIDATION, mergePredicates, parseSort, parseWhere, placeTreeNode as placeTreeNodeLifecycle, populateDocuments, populateRichTextFields, removeFromTree as removeFromTreeLifecycle, resolveIdentityField, restoreDocumentVersion, unpublishDocument, updateDocument, } from '@byline/core';
+import { applyAfterRead, assertActorCanPerform, buildSearchDocument, changeDocumentStatus, createDocument, createReadContext, createRichTextDocumentReader, deleteDocument, ERR_VALIDATION, parseSort, parseWhere, placeTreeNode as placeTreeNodeLifecycle, populateDocuments, populateRichTextFields, removeFromTree as removeFromTreeLifecycle, resolveIdentityField, restoreDocumentVersion, unpublishDocument, updateDocument, } from '@byline/core';
+import { getReadSecurityDomain, resolveReadRequestContext, resolveReadSecurityFilters, } from './read-context.js';
 import { shapeDocument, shapePopulatedInPlace } from './response.js';
 import { finalizeSearchHits } from './search.js';
 /**
@@ -31,18 +32,19 @@ export class CollectionHandle {
      * (LATERAL JOINs).
      */
     async find(options = {}) {
-        const requestContext = await this.resolveAndAssertRead();
-        const collectionId = await this.client.resolveCollectionId(this.definition.path);
-        const { where, select, sort, locale = this.client.defaultLocale, page = 1, pageSize = 20, } = options;
         const readMode = resolveReadMode(options.status);
         const readCtx = options._readContext ?? createReadContext();
-        const hookPredicate = await this.resolveBeforeReadPredicate(requestContext, readCtx, options._bypassBeforeRead);
-        const merged = mergePredicates(hookPredicate, where);
-        const parsedWhere = await parseWhere(merged, this.definition, {
+        const requestContext = await this.resolveAndAssertRead(readMode, readCtx);
+        const { where, select, sort, locale = this.client.defaultLocale, page = 1, pageSize = 20, } = options;
+        const securityFilters = await this.resolveBeforeReadFilters(requestContext, readCtx, options._bypassBeforeRead);
+        const parsedWhere = await parseWhere(where, this.definition, {
             collections: this.client.collections,
             resolveCollectionId: (path) => this.client.resolveCollectionId(path),
             logger: this.client.logger,
         });
+        if (securityFilters)
+            parsedWhere.filters.push(...securityFilters);
+        const collectionId = await this.client.resolveCollectionId(this.definition.path);
         const parsedSort = parseSort(sort, this.definition);
         const result = await this.client.db.queries.documents.findDocuments({
             collection_id: collectionId,
@@ -64,16 +66,7 @@ export class CollectionHandle {
             ...options,
             _readContext: readCtx,
         });
-        // Richtext populate runs *after* relation populate (so populated relation
-        // targets are already attached) and *before* afterRead (so user-land
-        // hooks observe the refreshed rich-text content).
-        await this.richTextPopulateSources(result.documents, readCtx);
-        // Fire afterRead for each source document AFTER populate so the hook
-        // sees the fully populated tree. Targets were already fired inside
-        // populate. applyAfterRead deduplicates via readCtx.afterReadFired.
-        for (const d of result.documents) {
-            await applyAfterRead({ doc: d, definition: this.definition, readContext: readCtx });
-        }
+        await this.finishReadDocuments(result.documents, readCtx, requestContext, locale, readMode, options._bypassBeforeRead, select, readMaterialization(options.populate, options.depth));
         return {
             docs: result.documents.map((d) => this.shapeWithPopulated(d)),
             meta: {
@@ -126,8 +119,8 @@ export class CollectionHandle {
      * comes free) and attaches them as `hit.document`. Two consequences to be
      * aware of:
      *
-     *   - `total` (and facet counts) remain the provider's pre-authorization
-     *     numbers — approximate under row scoping, exact without it.
+     *   - under row scoping, `total` is the authorized hit count for this page
+     *     and facets are omitted rather than leaking provider-wide aggregates.
      *   - a page of hits can come back shorter than `limit` when candidates
      *     are dropped; paginate on `offset`, not on received length.
      *
@@ -137,7 +130,11 @@ export class CollectionHandle {
      * Throws `ERR_VALIDATION` when no provider is registered.
      */
     async search(options) {
-        const requestContext = await this.resolveAndAssertRead();
+        const readMode = resolveReadMode(options.status);
+        const readCtx = createReadContext();
+        const requestContext = await this.resolveAndAssertRead(readMode, readCtx);
+        const aggregateRestricted = (await this.resolveBeforeReadFilters(requestContext, readCtx, options._bypassBeforeRead)) !=
+            null;
         const provider = this.client.searchProvider;
         if (provider == null) {
             throw ERR_VALIDATION({
@@ -149,7 +146,7 @@ export class CollectionHandle {
             query: options.query,
             collectionPath: this.definition.path,
             locale: options.locale ?? this.client.defaultLocale,
-            status: resolveReadMode(options.status),
+            status: readMode,
             where: options.where,
             facets: options.facets,
             limit: options.limit,
@@ -166,8 +163,11 @@ export class CollectionHandle {
             status: options.status,
             hydrate: options.hydrate,
             bypassBeforeRead: options._bypassBeforeRead,
+            readContext: readCtx,
         });
-        return { hits, total: results.total, facets: results.facets };
+        return aggregateRestricted
+            ? { hits, total: hits.length }
+            : { hits, total: results.total, facets: results.facets };
     }
     // -------------------------------------------------------------------------
     // Search index maintenance
@@ -298,12 +298,12 @@ export class CollectionHandle {
      * Find a document by its logical document ID.
      */
     async findById(documentId, options = {}) {
-        const requestContext = await this.resolveAndAssertRead();
-        const collectionId = await this.client.resolveCollectionId(this.definition.path);
-        const { locale = this.client.defaultLocale } = options;
         const readMode = resolveReadMode(options.status);
         const readCtx = options._readContext ?? createReadContext();
+        const requestContext = await this.resolveAndAssertRead(readMode, readCtx);
+        const { locale = this.client.defaultLocale } = options;
         const filters = await this.resolveBeforeReadFilters(requestContext, readCtx, options._bypassBeforeRead);
+        const collectionId = await this.client.resolveCollectionId(this.definition.path);
         const raw = await this.client.db.queries.documents.getDocumentById({
             collection_id: collectionId,
             document_id: documentId,
@@ -325,12 +325,7 @@ export class CollectionHandle {
             ...options,
             _readContext: readCtx,
         });
-        await this.richTextPopulateSources([raw], readCtx);
-        await applyAfterRead({
-            doc: raw,
-            definition: this.definition,
-            readContext: readCtx,
-        });
+        await this.finishReadDocuments([raw], readCtx, requestContext, locale, readMode, options._bypassBeforeRead, options.select, readMaterialization(options.populate, options.depth));
         return this.shapeWithPopulated(raw);
     }
     /**
@@ -339,12 +334,12 @@ export class CollectionHandle {
      * to `null` rather than throwing).
      */
     async findByPath(path, options = {}) {
-        const requestContext = await this.resolveAndAssertRead();
-        const collectionId = await this.client.resolveCollectionId(this.definition.path);
-        const { locale = this.client.defaultLocale } = options;
         const readMode = resolveReadMode(options.status);
         const readCtx = options._readContext ?? createReadContext();
+        const requestContext = await this.resolveAndAssertRead(readMode, readCtx);
+        const { locale = this.client.defaultLocale } = options;
         const filters = await this.resolveBeforeReadFilters(requestContext, readCtx, options._bypassBeforeRead);
+        const collectionId = await this.client.resolveCollectionId(this.definition.path);
         const raw = await this.client.db.queries.documents.getDocumentByPath({
             collection_id: collectionId,
             path,
@@ -363,12 +358,7 @@ export class CollectionHandle {
             ...options,
             _readContext: readCtx,
         });
-        await this.richTextPopulateSources([raw], readCtx);
-        await applyAfterRead({
-            doc: raw,
-            definition: this.definition,
-            readContext: readCtx,
-        });
+        await this.finishReadDocuments([raw], readCtx, requestContext, locale, readMode, options._bypassBeforeRead, options.select, readMaterialization(options.populate, options.depth));
         return this.shapeWithPopulated(raw);
     }
     // -------------------------------------------------------------------------
@@ -460,8 +450,10 @@ export class CollectionHandle {
         return deleteDocument(ctx, { documentId });
     }
     /**
-     * Count documents visible to the current actor, optionally filtered by
-     * status.
+     * Sum the current-version workflow status buckets visible to the actor,
+     * optionally selecting one exact status. This is an editorial status-count
+     * API, not an ordinary published-view document count; it therefore
+     * authorizes as `readMode: 'any'` and rejects anonymous callers.
      *
      * Applies the collection's `beforeRead` predicate so the count reflects
      * only the rows the actor can see (multi-tenant scoping, owner-only
@@ -479,13 +471,15 @@ export class CollectionHandle {
     }
     /**
      * Per-status document counts for this collection. Used by admin status
-     * bars / dashboards. Applies `beforeRead` so per-status counts reflect
+     * bars / dashboards. This always reads current versions across statuses,
+     * authorizes as `readMode: 'any'`, and applies `beforeRead` so counts reflect
      * only the actor's visible rows.
      */
     async countByStatus(options = {}) {
-        const requestContext = await this.resolveAndAssertRead();
+        const readCtx = createReadContext();
+        const requestContext = await this.resolveAndAssertRead('any', readCtx);
+        const filters = await this.resolveBeforeReadFilters(requestContext, readCtx, options._bypassBeforeRead);
         const collectionId = await this.client.resolveCollectionId(this.definition.path);
-        const filters = await this.resolveBeforeReadFilters(requestContext, createReadContext(), options._bypassBeforeRead);
         return this.client.db.queries.documents.getDocumentCountsByStatus({
             collection_id: collectionId,
             filters,
@@ -493,43 +487,21 @@ export class CollectionHandle {
     }
     /**
      * Fetch the version history for a single document. Applies `beforeRead`
-     * as an access gate via `findById` — if the actor can't see the
-     * document at all, history returns an empty result rather than
-     * leaking version metadata.
+     * independently to every immutable version before pagination and counting,
+     * so ownership changes cannot expose hidden version content or metadata.
      *
      * Each version in the response is a shaped `ClientDocument`. Pagination
      * mirrors the storage adapter's `{ documents, meta }` shape, then is
      * mapped to the same `{ docs, meta }` envelope `find()` returns.
      */
     async history(documentId, options = {}) {
-        const _requestContext = await this.resolveAndAssertRead();
-        const collectionId = await this.client.resolveCollectionId(this.definition.path);
         const readCtx = options._readContext ?? createReadContext();
+        const requestContext = await this.resolveAndAssertRead('any', readCtx);
         const locale = options.locale ?? this.client.defaultLocale;
         const page = options.page ?? 1;
         const pageSize = options.pageSize ?? 20;
-        // Access gate. `findById` runs `beforeRead`; a `null` here means either
-        // the document does not exist or the actor's predicate excludes it. In
-        // both cases an empty history is the correct response.
-        //
-        // `status: 'any'` so the gate asks "can the actor see *any* version of
-        // this document?" rather than the client's default "is there a
-        // published version they can see?". A draft-only document with the
-        // owning actor should still surface history; using the published-only
-        // default would gate them out incorrectly.
-        if (!options._bypassBeforeRead) {
-            const accessible = await this.findById(documentId, {
-                locale,
-                status: 'any',
-                _readContext: readCtx,
-            });
-            if (accessible == null) {
-                return {
-                    docs: [],
-                    meta: { total: 0, page, pageSize, totalPages: 0 },
-                };
-            }
-        }
+        const filters = await this.resolveBeforeReadFilters(requestContext, readCtx, options._bypassBeforeRead);
+        const collectionId = await this.client.resolveCollectionId(this.definition.path);
         const result = await this.client.db.queries.documents.getDocumentHistory({
             collection_id: collectionId,
             document_id: documentId,
@@ -538,7 +510,9 @@ export class CollectionHandle {
             page_size: pageSize,
             order: options.order,
             desc: options.desc,
+            filters,
         });
+        await this.finishReadDocuments(result.documents, readCtx, requestContext, locale, 'any', options._bypassBeforeRead, undefined, 'historical-version');
         return {
             docs: result.documents.map((d) => this.shapeWithPopulated(d)),
             meta: {
@@ -555,9 +529,9 @@ export class CollectionHandle {
      * available-locales), in-place status transitions, and the deletion event
      * the immutable version stream deliberately does not record an actor for.
      *
-     * Applies `beforeRead` as an access gate via `findById` — exactly as
-     * `history()` does — so an actor who cannot see the document at all gets an
-     * empty log rather than leaking change metadata. Entries are newest-first.
+     * Applies `beforeRead` as a current-document access gate via `findById`, so
+     * an actor who cannot see the document at all gets an empty log rather than
+     * leaking change metadata. Entries are newest-first.
      * Actor *ids* are returned raw; resolving them to display labels is an
      * admin-realm concern handled above the SDK.
      *
@@ -565,8 +539,8 @@ export class CollectionHandle {
      * (`queries.audit` absent) — the same graceful shape as a gated-out read.
      */
     async auditLog(documentId, options = {}) {
-        await this.resolveAndAssertRead();
         const readCtx = options._readContext ?? createReadContext();
+        await this.resolveAndAssertRead('any', readCtx);
         const locale = options.locale ?? this.client.defaultLocale;
         const page = options.page ?? 1;
         const pageSize = options.pageSize ?? 20;
@@ -596,22 +570,29 @@ export class CollectionHandle {
      * Fetch a specific version of a document by its `documentVersionId`.
      * Used by admin diff views.
      *
-     * Pass-through to `getDocumentByVersion`; access enforcement falls back
-     * to the collection-level `read` ability (asserted at the top of every
-     * read entry point). Row-level `beforeRead` does **not** apply here —
-     * version-by-id is a history-viewing primitive and the caller is
-     * expected to have already passed an access check on the parent
-     * document. Use `history()` instead if you want the access gate.
+     * The adapter query is constrained to this handle's collection and applies
+     * the collection's strict `beforeRead` predicate directly to the historical
+     * version. Unknown, cross-collection, and row-scoped version ids all return
+     * `null` without revealing ownership.
      */
     async findByVersion(versionId, options = {}) {
-        await this.resolveAndAssertRead();
+        const readCtx = options._readContext ?? createReadContext();
+        const requestContext = await this.resolveAndAssertRead('any', readCtx);
+        const filters = await this.resolveBeforeReadFilters(requestContext, readCtx, options._bypassBeforeRead);
+        const collectionId = await this.client.resolveCollectionId(this.definition.path);
         const locale = options.locale ?? this.client.defaultLocale;
         const raw = await this.client.db.queries.documents.getDocumentByVersion({
             document_version_id: versionId,
             locale,
+            collection_id: collectionId,
+            filters,
         });
         if (raw == null)
             return null;
+        if (options.select?.length) {
+            trimFields(raw, options.select);
+        }
+        await this.finishReadDocuments([raw], readCtx, requestContext, locale, 'any', options._bypassBeforeRead, options.select, 'historical-version');
         return this.shapeWithPopulated(raw);
     }
     // -------------------------------------------------------------------------
@@ -639,6 +620,7 @@ export class CollectionHandle {
             parentDocumentId: options.parentDocumentId,
             beforeDocumentId: options.beforeDocumentId ?? null,
             afterDocumentId: options.afterDocumentId ?? null,
+            reconcile: options.reconcile,
         });
     }
     /**
@@ -646,10 +628,10 @@ export class CollectionHandle {
      * in the collection, but not in any table of contents). Distinct from
      * deleting the document. No-op when already unplaced.
      */
-    async removeFromTree(documentId) {
+    async removeFromTree(documentId, options = {}) {
         this.assertTreeCollection();
         const ctx = await this.buildLifecycleContext();
-        await removeFromTreeLifecycle(ctx, { documentId });
+        await removeFromTreeLifecycle(ctx, { documentId, reconcile: options.reconcile });
     }
     /**
      * Read a node's subtree as a nested {@link TreeNode} forest, hydrated to
@@ -657,26 +639,32 @@ export class CollectionHandle {
      * from the collection roots; a value returns the subtree rooted at (and
      * including) that node. Children are ordered per-parent. `status` defaults to
      * `'published'` (the client default) — an unpublished node hides its whole
-     * subtree in that mode.
+     * subtree in that mode. `beforeRead` visibility follows the same edge rule:
+     * a hidden node and its descendants are omitted, never promoted.
      */
     async getSubtree(options = {}) {
         this.assertTreeCollection();
-        await this.resolveAndAssertRead();
-        const collectionId = await this.client.resolveCollectionId(this.definition.path);
-        const locale = options.locale ?? this.client.defaultLocale;
         const readMode = resolveReadMode(options.status);
+        const readCtx = options._readContext ?? createReadContext();
+        const requestContext = await this.resolveAndAssertRead(readMode, readCtx);
+        const locale = options.locale ?? this.client.defaultLocale;
+        const filters = await this.resolveBeforeReadFilters(requestContext, readCtx, options._bypassBeforeRead);
+        const collectionId = await this.client.resolveCollectionId(this.definition.path);
         const structure = await this.client.db.queries.documents.getTreeSubtree({
             collectionId,
             rootDocumentId: options.rootDocumentId ?? null,
             maxDepth: options.depth,
             readMode,
+            locale,
+            filters,
         });
         if (structure.length === 0)
             return [];
-        const shapedById = await this.hydrateTreeNodes(collectionId, structure.map((n) => n.document_id), locale, readMode, options.select);
+        const shapedById = await this.hydrateTreeNodes(collectionId, structure.map((n) => n.document_id), locale, readMode, options.select, filters, readCtx, requestContext, options._bypassBeforeRead);
         // Assemble the nested forest. Rows arrive pre-order, so a parent is always
         // materialised before its children; a row whose parent is not in the result
         // set (null parent, or the requested root's own parent) is a top-level node.
+        const structuralIds = new Set(structure.map((row) => row.document_id));
         const nodeById = new Map();
         const roots = [];
         for (const row of structure) {
@@ -686,10 +674,12 @@ export class CollectionHandle {
             const node = { document, depth: row.depth, children: [] };
             nodeById.set(row.document_id, node);
             const parent = row.parent_document_id != null ? nodeById.get(row.parent_document_id) : undefined;
-            if (parent)
+            if (parent) {
                 parent.children.push(node);
-            else
+            }
+            else if (row.parent_document_id == null || !structuralIds.has(row.parent_document_id)) {
                 roots.push(node);
+            }
         }
         return roots;
     }
@@ -699,36 +689,71 @@ export class CollectionHandle {
      * to `ClientDocument`s. In `'published'` mode (the client default) the walk
      * applies status-at-edge: it stops at the first unpublished ancestor (a
      * truncated chain), so a broken spine surfaces as a short chain the caller can
-     * detect rather than a silently-compacted one.
+     * detect rather than a silently-compacted one. A `beforeRead`-hidden ancestor
+     * breaks the edge identically.
      */
     async getAncestors(documentId, options = {}) {
         this.assertTreeCollection();
-        await this.resolveAndAssertRead();
-        const collectionId = await this.client.resolveCollectionId(this.definition.path);
-        const locale = options.locale ?? this.client.defaultLocale;
         const readMode = resolveReadMode(options.status);
+        const readCtx = options._readContext ?? createReadContext();
+        const requestContext = await this.resolveAndAssertRead(readMode, readCtx);
+        const locale = options.locale ?? this.client.defaultLocale;
+        const filters = await this.resolveBeforeReadFilters(requestContext, readCtx, options._bypassBeforeRead);
+        const collectionId = await this.client.resolveCollectionId(this.definition.path);
         const ancestors = await this.client.db.queries.documents.getTreeAncestors({
             document_id: documentId,
             readMode,
+            locale,
+            filters,
         });
         if (ancestors.length === 0)
             return [];
         const ids = ancestors.map((a) => a.document_id);
-        const shapedById = await this.hydrateTreeNodes(collectionId, ids, locale, readMode, options.select);
-        // Preserve root-first order; drop ancestors not visible in this read mode.
-        return ids.map((id) => shapedById.get(id)).filter((d) => d != null);
+        const shapedById = await this.hydrateTreeNodes(collectionId, ids, locale, readMode, options.select, filters, readCtx, requestContext, options._bypassBeforeRead);
+        // A hydration-time miss truncates the edge rather than compacting past a
+        // newly-hidden ancestor.
+        const visible = [];
+        for (let i = ids.length - 1; i >= 0; i--) {
+            const id = ids[i];
+            if (id == null)
+                break;
+            const document = shapedById.get(id);
+            if (document == null)
+                break;
+            visible.unshift(document);
+        }
+        return visible;
     }
     /**
      * Resolve a document's placement state in the tree — the tri-state that
      * `getAncestors` cannot express (it returns `[]` for both a root and an
      * unplaced node). Returns `{ placed, parentDocumentId }`: `placed: false` is
      * *unplaced* (no edge row), `placed: true` with a null parent is a *root*, and
-     * a non-null parent is a *child*. Structure-only — no document hydration.
+     * a non-null parent is a *child*. A hidden queried node reports unplaced; a
+     * visible child of a hidden parent remains placed but the parent id is
+     * redacted to null. Structure-only — no document hydration.
      */
-    async getTreeParent(documentId) {
+    async getTreeParent(documentId, options = {}) {
         this.assertTreeCollection();
-        await this.resolveAndAssertRead();
-        return this.client.db.queries.documents.getTreeParent({ document_id: documentId });
+        const readMode = resolveReadMode(options.status);
+        const readCtx = options._readContext ?? createReadContext();
+        const requestContext = await this.resolveAndAssertRead(readMode, readCtx);
+        const filters = await this.resolveBeforeReadFilters(requestContext, readCtx, options._bypassBeforeRead);
+        const result = await this.client.db.queries.documents.getTreeParent({
+            document_id: documentId,
+            readMode,
+            locale: options.locale ?? this.client.defaultLocale,
+            filters,
+        });
+        return {
+            placed: result.placed,
+            parentDocumentId: result.parentDocumentId,
+            parentVisibility: result.parentRedacted
+                ? 'redacted'
+                : result.parentDocumentId != null
+                    ? 'visible'
+                    : 'none',
+        };
     }
     // -------------------------------------------------------------------------
     // Internals
@@ -761,8 +786,8 @@ export class CollectionHandle {
      * Returns the resolved context so callers can thread `readMode` and
      * other per-request state into the adapter without re-resolving.
      */
-    async resolveAndAssertRead() {
-        const requestContext = await this.client.resolveRequestContext();
+    async resolveAndAssertRead(readMode, readContext) {
+        const requestContext = await resolveReadRequestContext(this.client, readContext, readMode);
         assertActorCanPerform(requestContext, this.definition.path, 'read');
         return requestContext;
     }
@@ -784,12 +809,12 @@ export class CollectionHandle {
      * Batch-hydrate a set of tree node document ids into shaped
      * `ClientDocument`s, keyed by document id. Reuses the populate batch read
      * (`getDocumentsByDocumentIds`) under the requested `readMode` — the tree's
-     * own status-at-edge filtering already happened structurally, so a node
-     * absent here in `'published'` mode simply has no published version. Fires
+     * own status/beforeRead edge filtering already happened structurally, and the
+     * same filters are applied again to close the structure/hydration race. Fires
      * `afterRead` per node (deduped within one shared `ReadContext`) to stay
      * consistent with the other client read paths.
      */
-    async hydrateTreeNodes(collectionId, documentIds, locale, readMode, select) {
+    async hydrateTreeNodes(collectionId, documentIds, locale, readMode, select, filters, readContext, requestContext, bypassBeforeRead) {
         const shapedById = new Map();
         if (documentIds.length === 0)
             return shapedById;
@@ -799,11 +824,11 @@ export class CollectionHandle {
             locale,
             readMode,
             fields: select,
+            filters,
         });
-        const readContext = createReadContext();
+        await this.finishReadDocuments(rawDocs, readContext, requestContext, locale, readMode, bypassBeforeRead, select, 'tree');
         for (const raw of rawDocs) {
             const doc = raw;
-            await applyAfterRead({ doc, definition: this.definition, readContext });
             shapedById.set(doc.document_id, this.shapeWithPopulated(doc));
         }
         return shapedById;
@@ -831,6 +856,7 @@ export class CollectionHandle {
             readMode,
             readContext: options._readContext,
             requestContext,
+            securityDomain: getReadSecurityDomain(this.client),
             bypassBeforeRead: options._bypassBeforeRead,
             richTextPopulate: this.client.richTextPopulate,
         });
@@ -844,7 +870,7 @@ export class CollectionHandle {
      * `populateRelationsOnRead` inside the service. No-ops when no adapter
      * is registered.
      */
-    async richTextPopulateSources(rawDocs, readContext) {
+    async richTextPopulateSources(rawDocs, readContext, requestContext, locale, readMode, bypassBeforeRead) {
         const populate = this.client.richTextPopulate;
         if (!populate || rawDocs.length === 0)
             return;
@@ -854,38 +880,45 @@ export class CollectionHandle {
             documents: rawDocs,
             populate,
             readContext,
-        });
-    }
-    /**
-     * Resolve and cache the `beforeRead` hook predicate for this collection
-     * inside the current `ReadContext`. Honours `_bypassBeforeRead` (admin
-     * tooling, seeds, migrations).
-     */
-    async resolveBeforeReadPredicate(requestContext, readContext, bypass) {
-        if (bypass)
-            return null;
-        return applyBeforeRead({
-            definition: this.definition,
             requestContext,
-            readContext,
+            readMode,
+            readDocuments: createRichTextDocumentReader({
+                db: this.client.db,
+                collections: this.client.collections,
+                requestContext,
+                readContext,
+                readMode,
+                locale,
+                bypassBeforeRead,
+                richTextPopulate: populate,
+                securityDomain: getReadSecurityDomain(this.client),
+            }),
         });
     }
+    /** Complete the common post-reconstruction pipeline in security order. */
+    async finishReadDocuments(rawDocs, readContext, requestContext, locale, readMode, bypassBeforeRead, projection, materialization) {
+        // Rich-text targets must be authorised and refreshed before user hooks see
+        // the document, regardless of which read entry point materialised it.
+        await this.richTextPopulateSources(rawDocs, readContext, requestContext, locale, readMode, bypassBeforeRead);
+        for (const doc of rawDocs) {
+            await applyAfterRead({
+                doc,
+                definition: this.definition,
+                readContext,
+                requestContext,
+                locale,
+                readMode,
+                projection,
+                materialization,
+            });
+        }
+    }
     /**
-     * Like `resolveBeforeReadPredicate`, but parses the predicate to the
-     * adapter-facing `DocumentFilter[]` shape used by `getDocumentById` /
-     * `getDocumentByPath`. Returns `undefined` (not `[]`) when there is no
-     * scoping, so the adapter can skip the loop entirely.
+     * Resolve the cached strict security filters used by every read shape.
+     * Returns `undefined` when no scoping applies.
      */
     async resolveBeforeReadFilters(requestContext, readContext, bypass) {
-        const predicate = await this.resolveBeforeReadPredicate(requestContext, readContext, bypass);
-        if (predicate == null)
-            return undefined;
-        const parsed = await parseWhere(predicate, this.definition, {
-            collections: this.client.collections,
-            resolveCollectionId: (path) => this.client.resolveCollectionId(path),
-            logger: this.client.logger,
-        });
-        return parsed.filters.length > 0 ? parsed.filters : undefined;
+        return resolveReadSecurityFilters(this.client, this.definition, requestContext, readContext, bypass);
     }
     /**
      * Shape a raw doc to `ClientDocument<F>`, then recursively shape any
@@ -911,6 +944,11 @@ export class CollectionHandle {
 function resolveReadMode(status) {
     return status ?? 'published';
 }
+function readMaterialization(populate, depth) {
+    if (populate === undefined)
+        return 'document';
+    return `populate:${depth ?? 1}:${typeof populate === 'object' ? JSON.stringify(populate) : populate}`;
+}
 /** Mutate `raw.fields` to retain only the entries matching `select`. */
 function trimFields(raw, select) {
     const fields = raw.fields;

package/dist/index.d.ts

@@ -8,4 +8,5 @@
 export { type AuditLogEntry, type AuditLogPage, type ChangeStatusResult, type CreateDocumentResult, type CycleRelationValue, createReadContext, type DeleteDocumentResult, ERR_CONFLICT, ERR_INVALID_TRANSITION, ERR_NOT_FOUND, ERR_READ_BUDGET_EXCEEDED, ERR_VALIDATION, type PopulatedRelationValue, type PopulateFieldOptions, type PopulateFieldSpec, type PopulateMap, type PopulateSpec, type ReadContext, type ReadMode, type RestoreVersionResult, type UnpublishResult, type UnresolvedRelationValue, type UpdateDocumentResult, } from '@byline/core';
 export { BylineClient, createBylineClient } from './client.js';
 export { CollectionHandle } from './collection-handle.js';
-export type { AuditLogOptions, BylineClientConfig, ClientDocument, ClientSearchResults, CollectionSearchOptions, CreateOptions, FilterOperators, FindByIdOptions, FindByPathOptions, FindOneOptions, FindOptions, FindResult, GetAncestorsOptions, GetSubtreeOptions, HydratedSearchHit, PlaceTreeNodeOptions, PopulatedRelation, ReindexResult, SearchFacetBucket, SearchHit, SearchResults, SortDirection, SortSpec, TreeNode, UpdateOptions, WhereClause, WhereValue, WithPopulated, WithPopulatedMany, ZoneSearchOptions, } from './types.js';
+export type { Register, RegisteredCollections } from './register.js';
+export type { AuditLogOptions, BylineClientConfig, ClientDocument, ClientSearchResults, CollectionSearchOptions, CreateOptions, FilterOperators, FindByIdOptions, FindByPathOptions, FindOneOptions, FindOptions, FindResult, GetAncestorsOptions, GetSubtreeOptions, GetTreeParentOptions, HydratedSearchHit, PlaceTreeNodeOptions, PopulatedRelation, ReindexResult, RemoveFromTreeOptions, SearchFacetBucket, SearchHit, SearchResults, SortDirection, SortSpec, TreeNode, TreeParentResult, UpdateOptions, WhereClause, WhereValue, WithPopulated, WithPopulatedMany, ZoneSearchOptions, } from './types.js';

package/dist/read-context.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Bind one authenticated request identity to a logical ReadContext without
+ * putting forgeable auth state on the public ReadContext shape. Each operation
+ * gets an immutable clone carrying its effective read mode.
+ */
+import type { RequestContext } from '@byline/auth';
+import type { CollectionDefinition, DocumentFilter, ReadContext, ReadMode } from '@byline/core';
+import type { BylineClient } from './client.js';
+export declare function getReadSecurityDomain(client: BylineClient<any>): object;
+export declare function resolveReadRequestContext(client: BylineClient<any>, readContext: ReadContext, readMode: ReadMode, supplied?: RequestContext): Promise<RequestContext>;
+export declare function resolveReadSecurityFilters(client: BylineClient<any>, definition: CollectionDefinition, requestContext: RequestContext, readContext: ReadContext, bypass?: true): Promise<DocumentFilter[] | undefined>;