@byline/client 3.21.0 → 4.0.0

package/dist/collection-handle.d.ts

@@ -7,7 +7,7 @@
  */
 import type { AuditLogPage, ChangeStatusResult, CollectionDefinition, CreateDocumentResult, DeleteDocumentResult, RestoreVersionResult, UnpublishResult, UpdateDocumentResult } from '@byline/core';
 import type { BylineClient } from './client.js';
-import type { AuditLogOptions, ClientDocument, ClientSearchResults, CollectionSearchOptions, CreateOptions, FindByIdOptions, FindByPathOptions, FindByVersionOptions, FindOneOptions, FindOptions, FindResult, GetAncestorsOptions, GetSubtreeOptions, HistoryOptions, PlaceTreeNodeOptions, ReindexResult, TreeNode, UpdateOptions } from './types.js';
+import type { AuditLogOptions, ClientDocument, ClientSearchResults, CollectionSearchOptions, CreateOptions, FindByIdOptions, FindByPathOptions, FindByVersionOptions, FindOneOptions, FindOptions, FindResult, GetAncestorsOptions, GetSubtreeOptions, GetTreeParentOptions, HistoryOptions, PlaceTreeNodeOptions, ReindexResult, RemoveFromTreeOptions, TreeNode, TreeParentResult, UpdateOptions } from './types.js';
 /**
  * A handle scoped to a single collection. Provides read (and eventually write)
  * operations against that collection's documents.
@@ -55,8 +55,8 @@ export declare class CollectionHandle<TFields extends Record<string, any> = Reco
      * 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.
      *
@@ -150,8 +150,10 @@ export declare class CollectionHandle<TFields extends Record<string, any> = Reco
      */
     delete(documentId: string): Promise<DeleteDocumentResult>;
     /**
-     * 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
@@ -163,7 +165,8 @@ export declare class CollectionHandle<TFields extends Record<string, any> = Reco
     }): Promise<number>;
     /**
      * 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.
      */
     countByStatus(options?: {
@@ -174,9 +177,8 @@ export declare class CollectionHandle<TFields extends Record<string, any> = Reco
     }>>;
     /**
      * 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
@@ -189,9 +191,9 @@ export declare class CollectionHandle<TFields extends Record<string, any> = Reco
      * 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.
      *
@@ -203,12 +205,10 @@ export declare class CollectionHandle<TFields extends Record<string, any> = Reco
      * 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.
      */
     findByVersion<F = TFields>(versionId: string, options?: FindByVersionOptions<F>): Promise<ClientDocument<F> | null>;
     /**
@@ -227,14 +227,15 @@ export declare class CollectionHandle<TFields extends Record<string, any> = Reco
      * in the collection, but not in any table of contents). Distinct from
      * deleting the document. No-op when already unplaced.
      */
-    removeFromTree(documentId: string): Promise<void>;
+    removeFromTree(documentId: string, options?: RemoveFromTreeOptions): Promise<void>;
     /**
      * Read a node's subtree as a nested {@link TreeNode} forest, hydrated to
      * `ClientDocument`s. `rootDocumentId: null` (default) returns the whole tree
      * 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.
      */
     getSubtree<F = TFields>(options?: GetSubtreeOptions<F>): Promise<TreeNode<F>[]>;
     /**
@@ -243,7 +244,8 @@ export declare class CollectionHandle<TFields extends Record<string, any> = Reco
      * 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.
      */
     getAncestors<F = TFields>(documentId: string, options?: GetAncestorsOptions<F>): Promise<ClientDocument<F>[]>;
     /**
@@ -251,12 +253,11 @@ export declare class CollectionHandle<TFields extends Record<string, any> = Reco
      * `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.
      */
-    getTreeParent(documentId: string): Promise<{
-        placed: boolean;
-        parentDocumentId: string | null;
-    }>;
+    getTreeParent(documentId: string, options?: GetTreeParentOptions): Promise<TreeParentResult>;
     /**
      * Build a fresh `DocumentLifecycleContext` for a write call. Pulls the
      * resolved collection id, inherits the client-wide logger and storage
@@ -283,8 +284,8 @@ export declare class CollectionHandle<TFields extends Record<string, any> = Reco
      * 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.
      */
@@ -309,17 +310,11 @@ export declare class CollectionHandle<TFields extends Record<string, any> = Reco
      * is registered.
      */
     private richTextPopulateSources;
+    /** Complete the common post-reconstruction pipeline in security order. */
+    private finishReadDocuments;
     /**
-     * Resolve and cache the `beforeRead` hook predicate for this collection
-     * inside the current `ReadContext`. Honours `_bypassBeforeRead` (admin
-     * tooling, seeds, migrations).
-     */
-    private resolveBeforeReadPredicate;
-    /**
-     * 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.
      */
     private resolveBeforeReadFilters;
     /**

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,4 @@
 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 { 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>;

package/dist/read-context.js

@@ -0,0 +1,36 @@
+/**
+ * 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 { bindReadContextAuthority, compileBeforeReadFilters } from '@byline/core';
+const readSecurityDomains = new WeakMap();
+export function getReadSecurityDomain(client) {
+    let domain = readSecurityDomains.get(client);
+    if (!domain) {
+        domain = {};
+        readSecurityDomains.set(client, domain);
+    }
+    return domain;
+}
+export async function resolveReadRequestContext(client, readContext, readMode, supplied) {
+    const candidate = supplied ?? (await client.resolveRequestContext());
+    const base = Object.freeze({ ...candidate });
+    bindReadContextAuthority(readContext, base);
+    return { ...base, readMode };
+}
+export function resolveReadSecurityFilters(client, definition, requestContext, readContext, bypass) {
+    if (bypass)
+        return Promise.resolve(undefined);
+    return compileBeforeReadFilters({
+        definition,
+        requestContext,
+        readContext,
+        securityDomain: getReadSecurityDomain(client),
+        parseContext: {
+            collections: client.collections,
+            resolveCollectionId: (path) => client.resolveCollectionId(path),
+            logger: client.logger,
+        },
+    });
+}

package/dist/search.js

@@ -5,7 +5,8 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
-import { applyBeforeRead, assertActorCanPerform, createReadContext, ERR_VALIDATION, getCollectionAdminConfig, resolveItemViewColumns, resolveSearchZones, } from '@byline/core';
+import { assertActorCanPerform, createReadContext, ERR_VALIDATION, getCollectionAdminConfig, resolveItemViewColumns, resolveSearchZones, } from '@byline/core';
+import { resolveReadRequestContext, resolveReadSecurityFilters } from './read-context.js';
 /**
  * Authorise (and optionally hydrate) provider hits, per collection:
  *
@@ -75,8 +76,8 @@ export async function finalizeSearchHits(params) {
             allowedByCollection.set(collectionPath, null);
             continue;
         }
-        const predicate = await applyBeforeRead({ definition, requestContext, readContext: readCtx });
-        if (predicate == null) {
+        const securityFilters = await resolveReadSecurityFilters(client, definition, requestContext, readCtx);
+        if (securityFilters == null) {
             allowedByCollection.set(collectionPath, null);
             continue;
         }
@@ -143,7 +144,9 @@ export async function zoneSearch(client, options) {
     }
     // Per-member read gate: exclude collections the actor can't read; only
     // when *none* are readable does the ability error surface.
-    const requestContext = await client.resolveRequestContext();
+    const readMode = options.status ?? 'published';
+    const readCtx = createReadContext();
+    const requestContext = await resolveReadRequestContext(client, readCtx, readMode);
     const readable = new Set();
     let firstAbilityError;
     for (const member of members) {
@@ -159,11 +162,22 @@ export async function zoneSearch(client, options) {
     if (readable.size === 0) {
         throw firstAbilityError;
     }
+    let aggregateRestricted = readable.size !== members.length;
+    if (!options._bypassBeforeRead) {
+        for (const member of members) {
+            if (!readable.has(member.path))
+                continue;
+            const securityFilters = await resolveReadSecurityFilters(client, member, requestContext, readCtx);
+            if (securityFilters == null)
+                continue;
+            aggregateRestricted = true;
+        }
+    }
     const results = await provider.search({
         query: options.query,
         zone: options.zone,
         locale: options.locale ?? client.defaultLocale,
-        status: options.status === 'any' ? 'any' : 'published',
+        status: readMode,
         where: options.where,
         facets: options.facets,
         limit: options.limit,
@@ -179,6 +193,9 @@ export async function zoneSearch(client, options) {
         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 };
 }

package/dist/types.d.ts

@@ -97,9 +97,18 @@ export interface BylineClientConfig {
      *   - a static `RequestContext` — convenient for long-lived processes
      *     that authenticate once (seeds, migrations, CLI tooling); or
      *   - a factory `() => RequestContext | Promise<RequestContext>` —
-     *     resolved per-call so each operation picks up the current
-     *     authenticated request (the pattern Phase 5's admin webapp will
-     *     use to thread middleware-derived actors).
+     *     invoked per operation so each one picks up the current
+     *     authenticated request (the pattern the admin webapp uses to
+     *     thread middleware-derived actors).
+     *
+     * **Factory contract — request-stable resolution.** Within one logical
+     * request the factory must return the same context instance (same
+     * `requestId`) on every call. Reads that share a `ReadContext` bind an
+     * immutable request authority whose token includes `requestId`, so a
+     * factory that mints a fresh context per call makes the second such
+     * read throw `ERR_VALIDATION` ('ReadContext cannot be reused across
+     * request authorities'). Host adapters should memoize resolution per
+     * request — see `oncePerRequest` in `@byline/host-tanstack-start`.
      *
      * When omitted, calls fail closed with `ERR_UNAUTHENTICATED`. Scripts
      * and tests pass `createSuperAdminContext()` from `@byline/auth`.
@@ -112,12 +121,10 @@ export interface BylineClientConfig {
  * documents; `depth` caps the traversal (default 1 when populate is set,
  * 0 otherwise). Clamped to the request's internal `ReadContext.maxDepth`.
  */
-interface PopulateControls {
-    populate?: PopulateSpec;
-    depth?: number;
+interface ReadContextControls {
     /**
      * Escape hatch for read-side hook re-entry. Carries the visited set,
-     * depth clamp, and `afterReadFired` set across nested reads so the
+     * depth clamp, and `afterRead` recursion/object state across nested reads so the
      * A→B→A recursion guard stays intact.
      *
      * Threading rules:
@@ -138,6 +145,10 @@ interface PopulateControls {
      */
     _readContext?: ReadContext;
 }
+interface PopulateControls extends ReadContextControls {
+    populate?: PopulateSpec;
+    depth?: number;
+}
 /**
  * Read-mode selector shared by every read method.
  *
@@ -227,9 +238,9 @@ export interface HydratedSearchHit extends SearchHit {
 }
 /**
  * The client-side search result envelope — `SearchResults` with the hits
- * widened to carry an optional hydrated document. `total` (and facet
- * counts) are the provider's pre-authorization numbers: approximate when
- * row scoping or hydration drops hits, exact otherwise.
+ * widened to carry an optional hydrated document. When authorization removes
+ * collections or applies row predicates, `total` is conservatively reduced to
+ * the authorized hits in this page and facets are omitted.
  */
 export interface ClientSearchResults {
     hits: HydratedSearchHit[];
@@ -324,8 +335,8 @@ export interface FindByPathOptions<F = Record<string, any>> extends PopulateCont
 /**
  * Options for `CollectionHandle.history(documentId, options)`. The history
  * endpoint is paginated; `order` / `desc` mirror the storage adapter's
- * version-row sort axes. `_bypassBeforeRead` skips the `findById` access
- * gate for admin tooling.
+ * version-row sort axes. `_bypassBeforeRead` skips per-version row scoping
+ * for admin tooling.
  */
 export interface HistoryOptions extends BeforeReadControls {
     locale?: string;
@@ -353,12 +364,11 @@ export interface AuditLogOptions extends BeforeReadControls {
     _readContext?: ReadContext;
 }
 /**
- * Options for `CollectionHandle.findByVersion(versionId, options)`. No
- * `BeforeReadControls` — `findByVersion` is a low-level pass-through
- * intended for admin diff views; row-level scoping is the caller's
- * responsibility (typically by gating with a prior `findById` call).
+ * Options for `CollectionHandle.findByVersion(versionId, options)`. Historical
+ * reads are collection-bound and apply the same `beforeRead` predicate as
+ * current reads.
  */
-export interface FindByVersionOptions<F = Record<string, any>> {
+export interface FindByVersionOptions<F = Record<string, any>> extends BeforeReadControls, ReadContextControls {
     select?: (keyof F & string)[] | string[];
     locale?: string;
 }
@@ -418,6 +428,13 @@ export interface PlaceTreeNodeOptions {
     beforeDocumentId?: string | null;
     /** Right neighbour — the node lands immediately before it. */
     afterDocumentId?: string | null;
+    /** Re-run `afterTreeChange` when this exact placement is already current. */
+    reconcile?: boolean;
+}
+/** Options for an idempotent tree removal or post-commit hook retry. */
+export interface RemoveFromTreeOptions {
+    /** Re-run `afterTreeChange` when the document is already unplaced. */
+    reconcile?: boolean;
 }
 /**
  * Options for `CollectionHandle.getSubtree(options)`. Reads a node's subtree as
@@ -426,8 +443,10 @@ export interface PlaceTreeNodeOptions {
  * at (and including) that node. `depth` bounds the descent (0-based; the root is
  * depth 0). `status` follows the usual published/any selector — in `'published'`
  * mode an unpublished node hides its entire subtree (the spine breaks).
+ * `beforeRead`-hidden nodes use the same edge semantics. `_bypassBeforeRead`
+ * is reserved for internal tooling.
  */
-export interface GetSubtreeOptions<F = Record<string, any>> extends StatusControls {
+export interface GetSubtreeOptions<F = Record<string, any>> extends StatusControls, BeforeReadControls, ReadContextControls {
     rootDocumentId?: string | null;
     depth?: number;
     /** Locale for field value resolution. Defaults to the client's `defaultLocale`. */
@@ -439,14 +458,30 @@ export interface GetSubtreeOptions<F = Record<string, any>> extends StatusContro
  * Options for `CollectionHandle.getAncestors(documentId, options)`. Walks the
  * node's ancestor chain upward, returning the ancestors **root-first** (the
  * breadcrumb trail, excluding the node itself). In `'published'` mode only
- * ancestors with a published version are returned.
+ * ancestors with a published version are returned. The walk also stops at the
+ * first ancestor excluded by `beforeRead`.
  */
-export interface GetAncestorsOptions<F = Record<string, any>> extends StatusControls {
+export interface GetAncestorsOptions<F = Record<string, any>> extends StatusControls, BeforeReadControls, ReadContextControls {
     /** Locale for field value resolution. Defaults to the client's `defaultLocale`. */
     locale?: string;
     /** Return only these fields on each ancestor. Omit for all fields. */
     select?: (keyof F & string)[] | string[];
 }
+/**
+ * Options for `CollectionHandle.getTreeParent(documentId, options)`. A hidden
+ * queried node is indistinguishable from an unplaced node. When only the parent
+ * is hidden, placement remains true but its id is redacted to `null`.
+ */
+export interface GetTreeParentOptions extends StatusControls, BeforeReadControls, ReadContextControls {
+    /** Locale used to evaluate localized `beforeRead` field predicates. */
+    locale?: string;
+}
+export interface TreeParentResult {
+    placed: boolean;
+    parentDocumentId: string | null;
+    /** Distinguishes a true root/unplaced node from a hidden parent id. */
+    parentVisibility: 'none' | 'visible' | 'redacted';
+}
 /**
  * A node in a hydrated document tree. `document` is the fully-shaped
  * `ClientDocument`; `depth` is 0-based from the subtree root; `children` are the
@@ -598,16 +633,18 @@ export interface PopulatedRelation<T> {
     document?: ClientDocument<T>;
 }
 /**
- * Re-type one key of a schema-inferred fields type as a populated relation.
+ * Re-type one key of a generated fields type as a populated relation.
  * Use to overlay populate's per-call enrichment on top of the unpopulated
- * shape that `CollectionFieldData<typeof X>` derives from the schema.
+ * shape emitted for the configured collection.
  *
  * Homomorphic mapped form preserves the optionality of the underlying key —
  * an optional relation field stays optional after populate is layered on.
  *
  * ```ts
+ * import type { MediaFields, NewsCategoriesFields, NewsFields } from './byline/generated/collection-types.js'
+ *
  * type NewsPopulated = WithPopulated<
- *   WithPopulated<NewsFields, 'category', NewsCategoryFields>,
+ *   WithPopulated<NewsFields, 'category', NewsCategoriesFields>,
  *   'featureImage', MediaFields
  * >
  * client.collection('news').find<NewsPopulated>({ populate: { category: '*', featureImage: '*' } })

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/client",
   "private": false,
   "license": "MPL-2.0",
-  "version": "3.21.0",
+  "version": "4.0.0",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -37,8 +37,8 @@
     "dist"
   ],
   "dependencies": {
-    "@byline/auth": "3.21.0",
-    "@byline/core": "3.21.0"
+    "@byline/core": "4.0.0",
+    "@byline/auth": "4.0.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.2",
@@ -51,8 +51,8 @@
     "tsx": "^4.23.0",
     "typescript": "^7.0.2",
     "vitest": "^4.1.10",
-    "@byline/db-postgres": "3.21.0",
-    "@byline/search-postgres": "3.21.0"
+    "@byline/db-postgres": "4.0.0",
+    "@byline/search-postgres": "4.0.0"
   },
   "publishConfig": {
     "access": "public",