@byline/client 3.15.2 → 3.16.1

package/dist/client.d.ts

@@ -8,7 +8,7 @@
 import { type RequestContext } from '@byline/auth';
 import type { BylineLogger, CollectionDefinition, IDbAdapter, IStorageProvider, RichTextPopulateFn, RichTextToTextFn, SearchProvider, SlugifierFn } from '@byline/core';
 import { CollectionHandle } from './collection-handle.js';
-import type { BylineClientConfig } from './types.js';
+import type { BylineClientConfig, ClientSearchResults, ZoneSearchOptions } from './types.js';
 /**
  * The main Byline client instance. Holds the database adapter, collection
  * definitions, and optional storage provider. Use `collection(path)` to get
@@ -22,7 +22,12 @@ export declare class BylineClient {
     readonly defaultLocale: string;
     readonly slugifier: SlugifierFn | undefined;
     readonly richTextPopulate: RichTextPopulateFn | undefined;
-    readonly search: SearchProvider | undefined;
+    /**
+     * The registered `SearchProvider` (`ServerConfig.search`), if any.
+     * Renamed from `search` when the cross-collection `search()` *method*
+     * landed — the method is the query surface, this is the driver.
+     */
+    readonly searchProvider: SearchProvider | undefined;
     readonly richTextToText: RichTextToTextFn | undefined;
     readonly contentLocales: string[];
     /** Cache: collection path → database row id + schema version. */
@@ -36,6 +41,15 @@ export declare class BylineClient {
      * configured — every read and write on the client requires one.
      */
     resolveRequestContext(): Promise<RequestContext>;
+    /**
+     * Cross-collection (zone) search — heterogeneous hits ranked together
+     * across every collection indexed into the named zone. Collections the
+     * actor cannot `read` are excluded; `beforeRead` row scoping applies per
+     * collection; `hydrate: true` attaches a shaped `ClientDocument` per hit.
+     * For homogeneous, single-collection search use
+     * `client.collection(path).search()`.
+     */
+    search(options: ZoneSearchOptions): Promise<ClientSearchResults>;
     /**
      * Get a handle scoped to a single collection. All subsequent read/write
      * operations on the handle are performed against this collection.

package/dist/client.js

@@ -8,6 +8,7 @@
 import { ERR_UNAUTHENTICATED } from '@byline/auth';
 import { ERR_NOT_FOUND, getLogger } from '@byline/core';
 import { CollectionHandle } from './collection-handle.js';
+import { zoneSearch } from './search.js';
 /**
  * Resolve a logger for the client in priority order:
  *   1. explicit `config.logger`
@@ -56,7 +57,12 @@ export class BylineClient {
     defaultLocale;
     slugifier;
     richTextPopulate;
-    search;
+    /**
+     * The registered `SearchProvider` (`ServerConfig.search`), if any.
+     * Renamed from `search` when the cross-collection `search()` *method*
+     * landed — the method is the query surface, this is the driver.
+     */
+    searchProvider;
     richTextToText;
     contentLocales;
     /** Cache: collection path → database row id + schema version. */
@@ -85,7 +91,7 @@ export class BylineClient {
         this.slugifier = config.slugifier ?? fromConfig?.slugifier;
         this.richTextPopulate =
             config.richTextPopulate ?? fromConfig?.fields?.richText?.populate ?? undefined;
-        this.search = config.search ?? fromConfig?.search ?? undefined;
+        this.searchProvider = config.search ?? fromConfig?.search ?? undefined;
         this.richTextToText = config.richTextToText ?? fromConfig?.fields?.richText?.toText ?? undefined;
         this.contentLocales = config.contentLocales ??
             fromConfig?.i18n?.content?.locales ?? [this.defaultLocale];
@@ -110,6 +116,17 @@ export class BylineClient {
         }
         return source;
     }
+    /**
+     * Cross-collection (zone) search — heterogeneous hits ranked together
+     * across every collection indexed into the named zone. Collections the
+     * actor cannot `read` are excluded; `beforeRead` row scoping applies per
+     * collection; `hydrate: true` attaches a shaped `ClientDocument` per hit.
+     * For homogeneous, single-collection search use
+     * `client.collection(path).search()`.
+     */
+    async search(options) {
+        return zoneSearch(this, options);
+    }
     /**
      * Get a handle scoped to a single collection. All subsequent read/write
      * operations on the handle are performed against this collection.

package/dist/collection-handle.d.ts

@@ -5,9 +5,9 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
-import type { AuditLogPage, ChangeStatusResult, CollectionDefinition, CreateDocumentResult, DeleteDocumentResult, RestoreVersionResult, SearchResults, UnpublishResult, UpdateDocumentResult } from '@byline/core';
+import type { AuditLogPage, ChangeStatusResult, CollectionDefinition, CreateDocumentResult, DeleteDocumentResult, RestoreVersionResult, UnpublishResult, UpdateDocumentResult } from '@byline/core';
 import type { BylineClient } from './client.js';
-import type { AuditLogOptions, ClientDocument, 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, HistoryOptions, PlaceTreeNodeOptions, ReindexResult, TreeNode, UpdateOptions } from './types.js';
 /**
  * A handle scoped to a single collection. Provides read (and eventually write)
  * operations against that collection's documents.
@@ -45,9 +45,27 @@ export declare class CollectionHandle {
      * sees published content — which is also all the index holds, since
      * indexing is published-only.
      *
+     * **Row-level authorization** — "rank in the provider, authorise in core":
+     * when the collection configures a `beforeRead` hook, the provider's
+     * candidate hits are re-resolved through the normal read path (the same
+     * predicate merge + SQL compile every other read uses) and hits whose
+     * document doesn't survive the scoping are dropped. Collections without a
+     * hook skip the second query entirely. `hydrate: true` batch-reads the
+     * hits into shaped `ClientDocument`s in the same query (authorisation
+     * 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.
+     *   - a page of hits can come back shorter than `limit` when candidates
+     *     are dropped; paginate on `offset`, not on received length.
+     *
+     * `_bypassBeforeRead: true` is the same system-operation escape hatch the
+     * read methods take.
+     *
      * Throws `ERR_VALIDATION` when no provider is registered.
      */
-    search(options: CollectionSearchOptions): Promise<SearchResults>;
+    search(options: CollectionSearchOptions): Promise<ClientSearchResults>;
     /**
      * Re-sync one document into the search index across every content locale.
      * Reads the document's *published* view per locale (`onMissingLocale: 'omit'`)
@@ -166,7 +184,7 @@ export declare class CollectionHandle {
      */
     history<F = Record<string, any>>(documentId: string, options?: HistoryOptions): Promise<FindResult<F>>;
     /**
-     * Fetch the document-grain audit log for a single document (docs/AUDIT.md —
+     * Fetch the document-grain audit log for a single document (docs/06-auth-and-security/02-auditability.md —
      * Workstream 3): the non-versioned system-field writes (path,
      * available-locales), in-place status transitions, and the deletion event
      * the immutable version stream deliberately does not record an actor for.

package/dist/collection-handle.js

@@ -7,6 +7,7 @@
  */
 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 { shapeDocument, shapePopulatedInPlace } from './response.js';
+import { finalizeSearchHits } from './search.js';
 /**
  * A handle scoped to a single collection. Provides read (and eventually write)
  * operations against that collection's documents.
@@ -115,18 +116,36 @@ export class CollectionHandle {
      * sees published content — which is also all the index holds, since
      * indexing is published-only.
      *
+     * **Row-level authorization** — "rank in the provider, authorise in core":
+     * when the collection configures a `beforeRead` hook, the provider's
+     * candidate hits are re-resolved through the normal read path (the same
+     * predicate merge + SQL compile every other read uses) and hits whose
+     * document doesn't survive the scoping are dropped. Collections without a
+     * hook skip the second query entirely. `hydrate: true` batch-reads the
+     * hits into shaped `ClientDocument`s in the same query (authorisation
+     * 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.
+     *   - a page of hits can come back shorter than `limit` when candidates
+     *     are dropped; paginate on `offset`, not on received length.
+     *
+     * `_bypassBeforeRead: true` is the same system-operation escape hatch the
+     * read methods take.
+     *
      * Throws `ERR_VALIDATION` when no provider is registered.
      */
     async search(options) {
-        await this.resolveAndAssertRead();
-        const provider = this.client.search;
+        const requestContext = await this.resolveAndAssertRead();
+        const provider = this.client.searchProvider;
         if (provider == null) {
             throw ERR_VALIDATION({
                 message: 'No search provider is registered. Register one on ServerConfig.search — ' +
                     'see `@byline/search-postgres` → `postgresSearch()` for the built-in driver.',
             });
         }
-        return provider.search({
+        const results = await provider.search({
             query: options.query,
             collectionPath: this.definition.path,
             locale: options.locale ?? this.client.defaultLocale,
@@ -136,6 +155,19 @@ export class CollectionHandle {
             limit: options.limit,
             offset: options.offset,
         });
+        // Row-level authorization (+ optional hydration) — the shared finishing
+        // pipeline the zone entry point uses too. Collections without a
+        // beforeRead predicate and no hydrate request pass through untouched.
+        const hits = await finalizeSearchHits({
+            client: this.client,
+            requestContext,
+            hits: results.hits,
+            locale: options.locale,
+            status: options.status,
+            hydrate: options.hydrate,
+            bypassBeforeRead: options._bypassBeforeRead,
+        });
+        return { hits, total: results.total, facets: results.facets };
     }
     // -------------------------------------------------------------------------
     // Search index maintenance
@@ -154,7 +186,7 @@ export class CollectionHandle {
      * path. The index always mirrors what a public reader can see.
      */
     async indexDocument(documentId) {
-        const provider = this.client.search;
+        const provider = this.client.searchProvider;
         if (provider == null || this.definition.search == null)
             return;
         const populate = this.buildSearchFacetPopulateMap();
@@ -186,7 +218,7 @@ export class CollectionHandle {
     }
     /** Remove one document from the search index entirely (all locales). */
     async removeFromIndex(documentId) {
-        const provider = this.client.search;
+        const provider = this.client.searchProvider;
         if (provider == null)
             return;
         await provider.remove({ collectionPath: this.definition.path, documentId });
@@ -203,7 +235,7 @@ export class CollectionHandle {
     async reindex() {
         const requestContext = await this.client.resolveRequestContext();
         assertActorCanPerform(requestContext, this.definition.path, 'reindex');
-        const provider = this.client.search;
+        const provider = this.client.searchProvider;
         const result = { collectionPath: this.definition.path, documents: 0, indexed: 0 };
         if (provider == null || this.definition.search == null)
             return result;
@@ -518,7 +550,7 @@ export class CollectionHandle {
         };
     }
     /**
-     * Fetch the document-grain audit log for a single document (docs/AUDIT.md —
+     * Fetch the document-grain audit log for a single document (docs/06-auth-and-security/02-auditability.md —
      * Workstream 3): the non-versioned system-field writes (path,
      * available-locales), in-place status transitions, and the deletion event
      * the immutable version stream deliberately does not record an actor for.
@@ -583,7 +615,7 @@ export class CollectionHandle {
         return this.shapeWithPopulated(raw);
     }
     // -------------------------------------------------------------------------
-    // Document tree (the `tree: true` primitive — docs/DOCUMENT-TREE.md)
+    // Document tree (the `tree: true` primitive — docs/04-collections/03-document-trees.md)
     //
     // A document-grain, unversioned single-parent ordered hierarchy. Reads/writes
     // here go through the storage adapter's dedicated tree commands, NOT the

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, CollectionSearchOptions, CreateOptions, FilterOperators, FindByIdOptions, FindByPathOptions, FindOneOptions, FindOptions, FindResult, GetAncestorsOptions, GetSubtreeOptions, PlaceTreeNodeOptions, PopulatedRelation, ReindexResult, SearchFacetBucket, SearchHit, SearchResults, SortDirection, SortSpec, TreeNode, UpdateOptions, WhereClause, WhereValue, WithPopulated, WithPopulatedMany, } from './types.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';

package/dist/response.js

@@ -43,7 +43,7 @@ export function shapeDocument(raw) {
     // `created_by` / `event_type`).
     // `created_by` is NULL on rows written before audit wiring or by
     // internal tooling without a request context — omitted here, rendered as
-    // "unknown" by consumers. See docs/AUDIT.md — Workstream 1.
+    // "unknown" by consumers. See docs/06-auth-and-security/02-auditability.md — Workstream 1.
     if (typeof raw.created_by === 'string') {
         shaped.createdBy = raw.created_by;
     }
@@ -55,7 +55,7 @@ export function shapeDocument(raw) {
     // Storage raw keys already match the surface names (passthrough) —
     // `availableLocales` is the editorial advertised set (document-grain,
     // stored), `_availableVersionLocales` is the structural ledger fact
-    // (version-grain, computed). See docs/I18N.md.
+    // (version-grain, computed). See docs/07-internationalization/index.md.
     if (Array.isArray(raw.availableLocales)) {
         shaped.availableLocales = raw.availableLocales;
     }

package/dist/search.d.ts

@@ -0,0 +1,60 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+/**
+ * Client-side search finishing pipeline + the cross-collection (zone)
+ * entry point.
+ *
+ * The provider ranks; core authorises and hydrates. Both `client.search({
+ * zone })` and `CollectionHandle.search()` hand their provider hits to
+ * `finalizeSearchHits`, which — per collection represented in the hits —
+ * applies `beforeRead` row scoping (re-resolving candidate ids through the
+ * normal read path) and, when `hydrate` is requested, batch-reads the hits
+ * into shaped `ClientDocument`s in the same query.
+ */
+import type { RequestContext } from '@byline/auth';
+import type { ReadContext, ReadMode, SearchHit } from '@byline/core';
+import type { BylineClient } from './client.js';
+import type { ClientSearchResults, HydratedSearchHit, ZoneSearchOptions } from './types.js';
+export interface FinalizeSearchHitsParams {
+    client: BylineClient;
+    requestContext: RequestContext;
+    hits: SearchHit[];
+    locale?: string;
+    status?: ReadMode;
+    hydrate?: boolean;
+    bypassBeforeRead?: true;
+    /** Shared per-request read context (beforeRead cache). Created when omitted. */
+    readContext?: ReadContext;
+}
+/**
+ * Authorise (and optionally hydrate) provider hits, per collection:
+ *
+ *   - `hydrate: true` — batch-read each collection's hit ids through the
+ *     normal read path (`find` with `id: { $in }`). The read applies
+ *     `beforeRead` row scoping as a side effect, so authorisation and
+ *     hydration cost one query per collection. Hits whose document doesn't
+ *     come back — dropped by scoping, or a stale index entry whose document
+ *     no longer resolves — are removed; the rest carry `hit.document`.
+ *   - `hydrate` off — collections with a `beforeRead` predicate get the
+ *     trimmed id re-resolution (identity-field projection); collections
+ *     without one pass through untouched (no second query).
+ *
+ * Hits whose `collectionPath` isn't registered in the runtime config are
+ * dropped with a debug log (an index can outlive a collection). Original
+ * ranking order is preserved.
+ */
+export declare function finalizeSearchHits(params: FinalizeSearchHitsParams): Promise<HydratedSearchHit[]>;
+/**
+ * Cross-collection search over a named zone. Membership is resolved from
+ * the runtime collection definitions (`search.zones`, defaulting to the
+ * collection's own path — the same rule the indexing assembler applies);
+ * collections the actor cannot `read` are excluded from the scope. Throws
+ * `ERR_VALIDATION` for a zone no collection indexes into; rethrows the
+ * ability error only when the actor can read none of the members.
+ */
+export declare function zoneSearch(client: BylineClient, options: ZoneSearchOptions): Promise<ClientSearchResults>;

package/dist/search.js

@@ -0,0 +1,184 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import { applyBeforeRead, assertActorCanPerform, createReadContext, ERR_VALIDATION, getCollectionAdminConfig, resolveItemViewColumns, resolveSearchZones, } from '@byline/core';
+/**
+ * Authorise (and optionally hydrate) provider hits, per collection:
+ *
+ *   - `hydrate: true` — batch-read each collection's hit ids through the
+ *     normal read path (`find` with `id: { $in }`). The read applies
+ *     `beforeRead` row scoping as a side effect, so authorisation and
+ *     hydration cost one query per collection. Hits whose document doesn't
+ *     come back — dropped by scoping, or a stale index entry whose document
+ *     no longer resolves — are removed; the rest carry `hit.document`.
+ *   - `hydrate` off — collections with a `beforeRead` predicate get the
+ *     trimmed id re-resolution (identity-field projection); collections
+ *     without one pass through untouched (no second query).
+ *
+ * Hits whose `collectionPath` isn't registered in the runtime config are
+ * dropped with a debug log (an index can outlive a collection). Original
+ * ranking order is preserved.
+ */
+export async function finalizeSearchHits(params) {
+    const { client, requestContext, hits, locale, status, hydrate, bypassBeforeRead } = params;
+    if (hits.length === 0)
+        return hits;
+    const readCtx = params.readContext ?? createReadContext();
+    // Group hit ids by collection, preserving overall ranking order for the
+    // final reassembly.
+    const byCollection = new Map();
+    for (const hit of hits) {
+        const group = byCollection.get(hit.collectionPath);
+        if (group)
+            group.push(hit);
+        else
+            byCollection.set(hit.collectionPath, [hit]);
+    }
+    // Per collection: resolve either a hydrated document map or an allowed-id
+    // set. `null` means "no filtering — pass the group through".
+    const documentsByCollection = new Map();
+    const allowedByCollection = new Map();
+    for (const [collectionPath, group] of byCollection) {
+        const definition = client.collections.find((c) => c.path === collectionPath);
+        if (definition == null) {
+            client.logger.debug({ collectionPath }, 'search: dropping hits for a collection not registered in the runtime config');
+            allowedByCollection.set(collectionPath, new Set());
+            continue;
+        }
+        const ids = group.map((h) => h.documentId);
+        const handle = client.collection(collectionPath);
+        if (hydrate) {
+            // itemView columns are the projection when the admin config is
+            // registered in this runtime; otherwise read the full field set.
+            const itemView = resolveItemViewColumns(getCollectionAdminConfig(collectionPath));
+            const select = itemView != null && itemView.length > 0
+                ? Array.from(new Set([...itemView.map((c) => String(c.fieldName)), definition.useAsTitle].filter((f) => typeof f === 'string' && f.length > 0)))
+                : undefined;
+            const result = await handle.find({
+                where: { id: { $in: ids } },
+                select,
+                locale,
+                status,
+                page: 1,
+                pageSize: ids.length,
+                _readContext: readCtx,
+                ...(bypassBeforeRead ? { _bypassBeforeRead: true } : {}),
+            });
+            documentsByCollection.set(collectionPath, new Map(result.docs.map((d) => [d.id, d])));
+            continue;
+        }
+        if (bypassBeforeRead) {
+            allowedByCollection.set(collectionPath, null);
+            continue;
+        }
+        const predicate = await applyBeforeRead({ definition, requestContext, readContext: readCtx });
+        if (predicate == null) {
+            allowedByCollection.set(collectionPath, null);
+            continue;
+        }
+        // Row scoping applies — re-resolve the candidate ids through the normal
+        // read path (find re-applies the cached predicate AND-merged with the id
+        // set), projected to the identity field.
+        const result = await handle.find({
+            where: { id: { $in: ids } },
+            select: definition.useAsTitle != null ? [definition.useAsTitle] : undefined,
+            locale,
+            status,
+            page: 1,
+            pageSize: ids.length,
+            _readContext: readCtx,
+        });
+        allowedByCollection.set(collectionPath, new Set(result.docs.map((d) => d.id)));
+    }
+    // Reassemble in the provider's ranking order.
+    const finished = [];
+    for (const hit of hits) {
+        if (hydrate) {
+            const doc = documentsByCollection.get(hit.collectionPath)?.get(hit.documentId);
+            if (doc == null)
+                continue;
+            finished.push({ ...hit, document: doc });
+            continue;
+        }
+        const allowed = allowedByCollection.get(hit.collectionPath);
+        if (allowed === null) {
+            finished.push(hit);
+        }
+        else if (allowed?.has(hit.documentId)) {
+            finished.push(hit);
+        }
+    }
+    return finished;
+}
+// ---------------------------------------------------------------------------
+// Zone (cross-collection) entry point
+// ---------------------------------------------------------------------------
+/**
+ * Cross-collection search over a named zone. Membership is resolved from
+ * the runtime collection definitions (`search.zones`, defaulting to the
+ * collection's own path — the same rule the indexing assembler applies);
+ * collections the actor cannot `read` are excluded from the scope. Throws
+ * `ERR_VALIDATION` for a zone no collection indexes into; rethrows the
+ * ability error only when the actor can read none of the members.
+ */
+export async function zoneSearch(client, options) {
+    const provider = client.searchProvider;
+    if (provider == null) {
+        throw ERR_VALIDATION({
+            message: 'No search provider is registered. Register one on ServerConfig.search — ' +
+                'see `@byline/search-postgres` → `postgresSearch()` for the built-in driver.',
+        });
+    }
+    const members = client.collections.filter((c) => (resolveSearchZones(c) ?? []).includes(options.zone));
+    if (members.length === 0) {
+        throw ERR_VALIDATION({
+            message: `No collection indexes into search zone '${options.zone}'. Declare zone ` +
+                'membership via the collection `search.zones` config (a collection without ' +
+                'explicit zones belongs to the implicit zone named after its own path).',
+        });
+    }
+    // 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 readable = new Set();
+    let firstAbilityError;
+    for (const member of members) {
+        try {
+            assertActorCanPerform(requestContext, member.path, 'read');
+            readable.add(member.path);
+        }
+        catch (err) {
+            firstAbilityError ??= err;
+            client.logger.debug({ collectionPath: member.path, zone: options.zone }, 'zone search: excluding collection the actor cannot read');
+        }
+    }
+    if (readable.size === 0) {
+        throw firstAbilityError;
+    }
+    const results = await provider.search({
+        query: options.query,
+        zone: options.zone,
+        locale: options.locale ?? client.defaultLocale,
+        status: options.status === 'any' ? 'any' : 'published',
+        where: options.where,
+        facets: options.facets,
+        limit: options.limit,
+        offset: options.offset,
+    });
+    // Constrain to readable member collections, then authorise / hydrate.
+    const scoped = results.hits.filter((h) => readable.has(h.collectionPath));
+    const hits = await finalizeSearchHits({
+        client,
+        requestContext,
+        hits: scoped,
+        locale: options.locale,
+        status: options.status,
+        hydrate: options.hydrate,
+        bypassBeforeRead: options._bypassBeforeRead,
+    });
+    return { hits, total: results.total, facets: results.facets };
+}

package/dist/types.d.ts

@@ -6,7 +6,7 @@
  * Copyright (c) Infonomic Company Limited
  */
 import type { RequestContext } from '@byline/auth';
-import type { BylineLogger, CollectionDefinition, IDbAdapter, IStorageProvider, MissingLocalePolicy, PopulateSpec, PredicateValue, QueryPredicate, ReadContext, ReadMode, RichTextPopulateFn, RichTextToTextFn, SearchProvider, ServerConfig, SlugifierFn, SortSpec } from '@byline/core';
+import type { BylineLogger, CollectionDefinition, IDbAdapter, IStorageProvider, MissingLocalePolicy, PopulateSpec, PredicateValue, QueryPredicate, ReadContext, ReadMode, RichTextPopulateFn, RichTextToTextFn, SearchFacetBucket, SearchHit, SearchProvider, ServerConfig, SlugifierFn, SortSpec } from '@byline/core';
 export type { FilterOperators, PredicateValue, QueryPredicate, SearchFacetBucket, SearchHit, SearchProvider, SearchResults, SortDirection, SortSpec, } from '@byline/core';
 export interface BylineClientConfig {
     /**
@@ -164,10 +164,48 @@ interface StatusControls {
  * `collectionPath` is implied by the handle, so callers supply only the
  * query and optional scoping. `status` defaults to `'published'` (public
  * readers); pass `'any'` for admin contexts.
+ *
+ * When the collection configures a `beforeRead` hook, hits are re-resolved
+ * through the row-scoping pipeline before being returned; `_bypassBeforeRead`
+ * is the same system-operation escape hatch the read methods take.
+ */
+export interface CollectionSearchOptions extends BeforeReadControls {
+    /** Free-text query string. */
+    query: string;
+    /** Restrict to a single content locale (defaults to the client default). */
+    locale?: string;
+    /** Read mode — `'published'` (default) or `'any'`. */
+    status?: ReadMode;
+    /** Structured filters AND-merged with the text query (driver-dependent). */
+    where?: QueryPredicate;
+    /** Field names to compute facet buckets for (driver-capability gated). */
+    facets?: string[];
+    /** Max hits to return. */
+    limit?: number;
+    /** Offset for pagination. */
+    offset?: number;
+    /**
+     * Attach a shaped `ClientDocument` to each hit (`hit.document`), batch-read
+     * through the normal read path — the two-tier results model's rich tier.
+     * Projection is the collection's `admin.itemView` columns when that config
+     * is registered in the runtime, otherwise the full field set. Hits whose
+     * document no longer resolves (stale index entry, or dropped by `beforeRead`
+     * row scoping) are removed.
+     */
+    hydrate?: boolean;
+}
+/**
+ * Options for `client.search(...)` — the cross-collection (zone) entry
+ * point. Every collection indexed into `zone` participates; hits come back
+ * heterogeneous, ranked together, each carrying its `collectionPath`.
+ * Collections the actor cannot `read` are excluded from the results (the
+ * call only throws when the actor can read none of the zone's members).
  */
-export interface CollectionSearchOptions {
+export interface ZoneSearchOptions extends BeforeReadControls {
     /** Free-text query string. */
     query: string;
+    /** The zone (named cross-collection scope) to search. */
+    zone: string;
     /** Restrict to a single content locale (defaults to the client default). */
     locale?: string;
     /** Read mode — `'published'` (default) or `'any'`. */
@@ -180,6 +218,23 @@ export interface CollectionSearchOptions {
     limit?: number;
     /** Offset for pagination. */
     offset?: number;
+    /** Attach a shaped `ClientDocument` per hit — see `CollectionSearchOptions.hydrate`. */
+    hydrate?: boolean;
+}
+/** A search hit, optionally carrying its hydrated document (`hydrate: true`). */
+export interface HydratedSearchHit extends SearchHit {
+    document?: ClientDocument<Record<string, any>>;
+}
+/**
+ * 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.
+ */
+export interface ClientSearchResults {
+    hits: HydratedSearchHit[];
+    total: number;
+    facets?: Record<string, SearchFacetBucket[]>;
 }
 /** Outcome of a collection `reindex()` — counts for reporting. */
 export interface ReindexResult {
@@ -209,7 +264,7 @@ export interface ReindexResult {
  *     in every locale.
  *
  * Availability is the version-grain ledger described in
- * `docs/I18N.md`. Relationship population always behaves
+ * `docs/07-internationalization/index.md`. Relationship population always behaves
  * as `'fallback'` so a populated tree never has holes.
  */
 interface MissingLocaleControls {
@@ -283,7 +338,7 @@ export interface HistoryOptions extends BeforeReadControls {
 }
 /**
  * Options for `CollectionHandle.auditLog(documentId, options)`. The
- * document-grain audit log (docs/AUDIT.md — Workstream 3) records the
+ * document-grain audit log (docs/06-auth-and-security/02-auditability.md — Workstream 3) records the
  * non-versioned changes the immutable version stream does not capture an
  * actor for: system-field writes (path, available-locales), in-place status
  * transitions, and the deletion event. Entries are newest-first and paged;
@@ -325,7 +380,7 @@ export interface CreateOptions {
      * The editorial advertised-locale set, stored document-grain in
      * `byline_document_available_locales`. When omitted, a new document starts
      * with an empty set; an explicit array (empty included) is stored verbatim.
-     * Surfaced on reads as `availableLocales`. See `docs/I18N.md`.
+     * Surfaced on reads as `availableLocales`. See `docs/07-internationalization/index.md`.
      */
     availableLocales?: string[];
 }
@@ -341,7 +396,7 @@ export interface UpdateOptions {
      * The editorial advertised-locale set. When omitted, the existing set
      * carries forward unchanged (sticky — document-grain, like `path`); an
      * explicit array (empty included) replaces it wholesale. Surfaced on reads
-     * as `availableLocales`. See `docs/I18N.md`.
+     * as `availableLocales`. See `docs/07-internationalization/index.md`.
      */
     availableLocales?: string[];
 }
@@ -462,7 +517,7 @@ export interface ClientDocument<F = Record<string, any>> {
      * yardstick). Stable, document-grain. Surfaced so consumers / the admin can
      * indicate a document whose primary language differs from the system default.
      * Present on `find` / `findById` / `findByPath`. See
-     * `docs/I18N.md`.
+     * `docs/07-internationalization/index.md`.
      */
     sourceLocale?: string;
     /** When this version was created. */
@@ -475,7 +530,7 @@ export interface ClientDocument<F = Record<string, any>> {
      * the creator of the current version is also "who last updated the
      * document". Absent on rows written before audit wiring or by
      * internal tooling without a request context. Raw id only — display-name
-     * resolution is an admin-realm concern (see docs/AUDIT.md — Workstream 1).
+     * resolution is an admin-realm concern (see docs/06-auth-and-security/02-auditability.md — Workstream 1).
      */
     createdBy?: string;
     /**
@@ -503,7 +558,7 @@ export interface ClientDocument<F = Record<string, any>> {
      * `_availableVersionLocales` fact below; the public advertised set is their
      * intersection (`availableLocales ∩ _availableVersionLocales`), which the
      * host composes for hreflang / sitemap / "Also available in…" menus.
-     * Present on `find` / `findById` / `findByPath`. See `docs/I18N.md`.
+     * Present on `find` / `findById` / `findByPath`. See `docs/07-internationalization/index.md`.
      */
     availableLocales?: string[];
     /**
@@ -513,7 +568,7 @@ export interface ClientDocument<F = Record<string, any>> {
      * Present on `find` / `findById` / `findByPath` (absent on version/history
      * reads); the published-available set on a normal (published) read. The
      * structural fact reconciled against the editorial `availableLocales` above.
-     * See `docs/I18N.md`.
+     * See `docs/07-internationalization/index.md`.
      */
     _availableVersionLocales?: string[];
     /**

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/client",
   "private": false,
   "license": "MPL-2.0",
-  "version": "3.15.2",
+  "version": "3.16.1",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -37,9 +37,8 @@
     "dist"
   ],
   "dependencies": {
-    "npm-run-all": "^4.1.5",
-    "@byline/auth": "3.15.2",
-    "@byline/core": "3.15.2"
+    "@byline/auth": "3.16.1",
+    "@byline/core": "3.16.1"
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.15",
@@ -47,11 +46,13 @@
     "chokidar": "^5.0.0",
     "chokidar-cli": "^3.0.0",
     "dotenv": "^17.4.2",
+    "npm-run-all": "^4.1.5",
     "tsc-alias": "^1.8.17",
     "tsx": "^4.22.3",
     "typescript": "6.0.3",
     "vitest": "^4.1.7",
-    "@byline/db-postgres": "3.15.2"
+    "@byline/db-postgres": "3.16.1",
+    "@byline/search-postgres": "3.16.1"
   },
   "publishConfig": {
     "access": "public",