@byline/client 6.7.0 → 6.7.1

package/dist/client.d.ts

@@ -49,8 +49,10 @@ export declare class BylineClient<TCollections extends CollectionRegistry = Regi
      * actor cannot `read` are excluded; `beforeRead` row scoping applies per
      * collection; `hydrate: true` attaches a shaped `ClientDocument` per hit.
      * A public search (the default `status: 'published'`) also re-checks each
-     * hit's locale against the advertised-locale policy, and reports a
-     * page-local `total` with no facets, as `CollectionHandle.search()` does.
+     * hit's locale against the advertised-locale policy. The provider `total`
+     * and facets pass through unless an actor-specific restriction applies
+     * (unreadable members or `beforeRead` scoping), as `CollectionHandle.search()`
+     * does.
      * For homogeneous, single-collection search use
      * `client.collection(path).search()`.
      */

package/dist/client.js

@@ -123,8 +123,10 @@ export class BylineClient {
      * actor cannot `read` are excluded; `beforeRead` row scoping applies per
      * collection; `hydrate: true` attaches a shaped `ClientDocument` per hit.
      * A public search (the default `status: 'published'`) also re-checks each
-     * hit's locale against the advertised-locale policy, and reports a
-     * page-local `total` with no facets, as `CollectionHandle.search()` does.
+     * hit's locale against the advertised-locale policy. The provider `total`
+     * and facets pass through unless an actor-specific restriction applies
+     * (unreadable members or `beforeRead` scoping), as `CollectionHandle.search()`
+     * does.
      * For homogeneous, single-collection search use
      * `client.collection(path).search()`.
      */

package/dist/collection-handle.d.ts

@@ -59,11 +59,13 @@ export declare class CollectionHandle<TFields extends Record<string, any> = Reco
      * hits into shaped `ClientDocument`s in their own locale (no source
      * substitution) and attaches them as `hit.document`. Consequences:
      *
-     *   - for every public search, and under row scoping, `total` is the
-     *     surviving hit count for this page and facets are omitted rather than
-     *     leaking provider-wide aggregates;
-     *   - only an editorial search (`status: 'any'`) with no `beforeRead` hook
-     *     passes the provider `total` and facets through unchanged;
+     *   - under `beforeRead` row scoping, `total` is the surviving hit count
+     *     for this page and facets are omitted rather than leaking
+     *     provider-wide aggregates of rows this actor can't see;
+     *   - otherwise — including every unscoped public search — the provider
+     *     `total` and facets pass through unchanged (public locale eligibility
+     *     is actor-independent and applied at indexing, so a hit the re-check
+     *     drops is a stale index entry, logged at warn level);
      *   - a page of hits can come back shorter than `limit` when candidates
      *     are dropped; paginate on `offset`, not on received length.
      *

package/dist/collection-handle.js

@@ -180,11 +180,13 @@ export class CollectionHandle {
      * hits into shaped `ClientDocument`s in their own locale (no source
      * substitution) and attaches them as `hit.document`. Consequences:
      *
-     *   - for every public search, and under row scoping, `total` is the
-     *     surviving hit count for this page and facets are omitted rather than
-     *     leaking provider-wide aggregates;
-     *   - only an editorial search (`status: 'any'`) with no `beforeRead` hook
-     *     passes the provider `total` and facets through unchanged;
+     *   - under `beforeRead` row scoping, `total` is the surviving hit count
+     *     for this page and facets are omitted rather than leaking
+     *     provider-wide aggregates of rows this actor can't see;
+     *   - otherwise — including every unscoped public search — the provider
+     *     `total` and facets pass through unchanged (public locale eligibility
+     *     is actor-independent and applied at indexing, so a hit the re-check
+     *     drops is a stale index entry, logged at warn level);
      *   - a page of hits can come back shorter than `limit` when candidates
      *     are dropped; paginate on `offset`, not on received length.
      *
@@ -222,10 +224,12 @@ export class CollectionHandle {
         });
         // Row-level authorization, exact-locale eligibility (+ optional
         // hydration) — the shared finishing pipeline the zone entry point uses
-        // too. Public searches always re-check every hit and always follow the
-        // restricted-result convention; only an editorial search without a
-        // beforeRead predicate or hydration passes hits through untouched.
-        const { hits, eligibilityRestricted } = await finalizeSearchHits({
+        // too. Public searches re-check every hit; an editorial search without a
+        // beforeRead predicate or hydration passes hits through untouched. Only
+        // actor-specific restriction (beforeRead) replaces the provider
+        // aggregate — public locale eligibility is actor-independent and already
+        // applied at indexing, so provider total and facets pass through.
+        const hits = await finalizeSearchHits({
             client: this.client,
             requestContext,
             hits: results.hits,
@@ -236,7 +240,7 @@ export class CollectionHandle {
             localeVisibility: resolveLocaleVisibility(readMode),
             readContext: readCtx,
         });
-        return aggregateRestricted || eligibilityRestricted
+        return aggregateRestricted
             ? { hits, total: hits.length }
             : { hits, total: results.total, facets: results.facets };
     }

package/dist/search.d.ts

@@ -17,6 +17,15 @@
  * into shaped `ClientDocument`s in the same query. Under `'public'` locale
  * visibility every hit is also re-checked for exact-locale eligibility, so a
  * stale index entry for a withheld translation is dropped whole.
+ *
+ * Aggregates: the provider's `total` and facets pass through unless an
+ * *actor-specific* restriction applies (a `beforeRead` predicate, or zone
+ * members the actor cannot read) — then the restricted-result convention
+ * (retained-hit `total`, no facets) prevents leaking counts of rows this
+ * reader can't see. Public locale eligibility is actor-independent and is
+ * the same rule indexing applies, so the provider aggregate already is the
+ * public aggregate; a stale entry the re-check drops is an index-maintenance
+ * lag, logged at warn level, not a reason to degrade the response.
  */
 import type { RequestContext } from '@byline/auth';
 import type { LocaleVisibility, ReadContext, ReadMode, SearchHit, SearchProvider } from '@byline/core';
@@ -40,21 +49,6 @@ export interface FinalizeSearchHitsParams {
     /** Shared per-request read context (beforeRead cache). Created when omitted. */
     readContext?: ReadContext;
 }
-/** Finished hits, plus whether a post-ranking eligibility policy applied. */
-export interface FinalizedSearchHits {
-    hits: HydratedSearchHit[];
-    /**
-     * `true` whenever the public exact-locale eligibility policy applies — that
-     * is, for every `'public'` search, including an empty page. The provider's
-     * `total` and facets count its whole index, which can hold slices the
-     * policy would reject on other pages, so a page-only check cannot certify
-     * them. The caller follows the restricted-result convention (retained-hit
-     * `total`, no provider facets), exactly as for `beforeRead` row scoping,
-     * which also restricts on the presence of the policy, not on an observed
-     * removal.
-     */
-    eligibilityRestricted: boolean;
-}
 /**
  * Authorise (and optionally hydrate) provider hits, per collection:
  *
@@ -82,7 +76,7 @@ export interface FinalizedSearchHits {
  * dropped with a debug log (an index can outlive a collection). Original
  * ranking order is preserved.
  */
-export declare function finalizeSearchHits(params: FinalizeSearchHitsParams): Promise<FinalizedSearchHits>;
+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

package/dist/search.js

@@ -50,9 +50,8 @@ export function assertSearchFieldScope(provider, fieldScope) {
  */
 export async function finalizeSearchHits(params) {
     const { client, requestContext, hits, locale, status, hydrate, bypassBeforeRead, localeVisibility, } = params;
-    const eligibilityRestricted = localeVisibility === 'public';
     if (hits.length === 0)
-        return { hits, eligibilityRestricted };
+        return hits;
     const readCtx = params.readContext ?? createReadContext();
     // Group hit ids by collection, preserving overall ranking order for the
     // final reassembly.
@@ -97,6 +96,7 @@ export async function finalizeSearchHits(params) {
                 ...(bypassBeforeRead ? { _bypassBeforeRead: true } : {}),
             });
             documentsByCollection.set(collectionPath, new Map(result.docs.map((d) => [d.id, d])));
+            await warnOnStaleHits(params, readCtx, collectionPath, group, new Set(result.docs.map((d) => d.id)));
             continue;
         }
         if (localeVisibility === 'public') {
@@ -114,7 +114,9 @@ export async function finalizeSearchHits(params) {
                 _readContext: readCtx,
                 ...(bypassBeforeRead ? { _bypassBeforeRead: true } : {}),
             });
-            allowedByCollection.set(collectionPath, new Set(result.docs.map((d) => d.id)));
+            const allowed = new Set(result.docs.map((d) => d.id));
+            allowedByCollection.set(collectionPath, allowed);
+            await warnOnStaleHits(params, readCtx, collectionPath, group, allowed);
             continue;
         }
         if (bypassBeforeRead) {
@@ -158,7 +160,31 @@ export async function finalizeSearchHits(params) {
             finished.push(hit);
         }
     }
-    return { hits: finished, eligibilityRestricted };
+    return finished;
+}
+/**
+ * Warn about hits the re-check dropped for a reason other than `beforeRead`
+ * scoping — a stale index entry (deleted document, withdrawn translation,
+ * unpublished version) that index maintenance hasn't caught up with yet.
+ * Drops under an active `beforeRead` predicate are expected and not logged.
+ */
+async function warnOnStaleHits(params, readCtx, collectionPath, group, resolved) {
+    const dropped = group.filter((h) => !resolved.has(h.documentId));
+    if (dropped.length === 0)
+        return;
+    const { client, requestContext, bypassBeforeRead } = params;
+    if (!bypassBeforeRead) {
+        const definition = client.collections.find((c) => c.path === collectionPath);
+        const filters = definition == null
+            ? null
+            : await resolveReadSecurityFilters(client, definition, requestContext, readCtx);
+        if (filters != null)
+            return;
+    }
+    client.logger.warn({
+        collectionPath,
+        dropped: dropped.map((h) => ({ documentId: h.documentId, locale: h.locale })),
+    }, 'search: dropped index entries that no longer resolve for this read; reindex the affected documents');
 }
 // ---------------------------------------------------------------------------
 // Zone (cross-collection) entry point
@@ -234,7 +260,7 @@ export async function zoneSearch(client, options) {
     });
     // Constrain to readable member collections, then authorise / hydrate.
     const scoped = results.hits.filter((h) => readable.has(h.collectionPath));
-    const { hits, eligibilityRestricted } = await finalizeSearchHits({
+    const hits = await finalizeSearchHits({
         client,
         requestContext,
         hits: scoped,
@@ -245,7 +271,7 @@ export async function zoneSearch(client, options) {
         localeVisibility: resolveLocaleVisibility(readMode),
         readContext: readCtx,
     });
-    return aggregateRestricted || eligibilityRestricted
+    return aggregateRestricted
         ? { hits, total: hits.length }
         : { hits, total: results.total, facets: results.facets };
 }

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/client",
   "private": false,
   "license": "MPL-2.0",
-  "version": "6.7.0",
+  "version": "6.7.1",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -44,8 +44,8 @@
   ],
   "dependencies": {
     "uuid": "^14.0.2",
-    "@byline/auth": "6.7.0",
-    "@byline/core": "6.7.0"
+    "@byline/auth": "6.7.1",
+    "@byline/core": "6.7.1"
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.14",
@@ -57,8 +57,8 @@
     "tsc-alias": "^1.9.5",
     "typescript": "^7.0.2",
     "vitest": "^5.0.1",
-    "@byline/search-postgres": "6.7.0",
-    "@byline/db-postgres": "6.7.0"
+    "@byline/db-postgres": "6.7.1",
+    "@byline/search-postgres": "6.7.1"
   },
   "publishConfig": {
     "access": "public",