@byline/client 6.6.0 → 6.7.1

package/dist/client.d.ts

@@ -48,6 +48,11 @@ export declare class BylineClient<TCollections extends CollectionRegistry = Regi
      * 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.
+     * A public search (the default `status: 'published'`) also re-checks each
+     * 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

@@ -122,6 +122,11 @@ export class BylineClient {
      * 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.
+     * A public search (the default `status: 'published'`) also re-checks each
+     * 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

@@ -45,25 +45,32 @@ export declare class CollectionHandle<TFields extends Record<string, any> = Reco
      * Asserts the collection `read` ability first (same gate as the other
      * reads), and defaults `status` to `'published'`, so a public viewer only
      * sees published content — which is also all the index holds, since
-     * indexing is published-only.
+     * indexing writes only publicly deliverable locales of the published
+     * version.
      *
-     * **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:
+     * **Authorization after ranking** — "rank in the provider, authorise in
+     * core": the provider's candidate hits are re-resolved through the normal
+     * read path (the same predicate merge + SQL compile every other read uses)
+     * whenever the search is public (`status: 'published'`, the default) or
+     * the collection configures a `beforeRead` hook. A public search re-checks
+     * every hit's locale against the advertised-locale policy even without a
+     * hook, so a stale index slice for an unchecked translation is dropped;
+     * one batched read per page performs the check. `hydrate: true` reads the
+     * hits into shaped `ClientDocument`s in their own locale (no source
+     * substitution) and attaches them as `hit.document`. Consequences:
      *
-     *   - under row scoping, `total` is the authorized hit count for this page
-     *     and facets are omitted rather than leaking provider-wide aggregates.
+     *   - 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.
      *
      * `_bypassBeforeRead: true` is the same system-operation escape hatch the
-     * read methods take.
+     * read methods take; it skips `beforeRead` scoping, never the locale check.
      *
      * Throws `ERR_VALIDATION` when no provider is registered.
      */
@@ -309,6 +316,17 @@ export declare class CollectionHandle<TFields extends Record<string, any> = Reco
      * Returns the resolved context so callers can thread `readMode` and
      * other per-request state into the adapter without re-resolving.
      */
+    /**
+     * Resolve the request context for a read and authorize it: the collection
+     * read ability (`assertActorCanPerform`) and the read's locale visibility
+     * (`assertLocaleVisibility`). Visibility defaults from `readMode`, so the
+     * editing, history and version reads (`readMode: 'any'`) are editorial.
+     *
+     * The visibility check validates the *effective* locale, the value every
+     * read method sends to storage (`locale ?? client.defaultLocale`), so a
+     * client configured with `defaultLocale: 'all'` cannot turn an omitted
+     * locale into a public all-locale read.
+     */
     private resolveAndAssertRead;
     /**
      * Guard that this collection opts into the document-tree primitive. The

package/dist/collection-handle.js

@@ -5,7 +5,7 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
-import { applyAfterRead, assertActorCanPerform, buildSearchDocument, cancelDocumentScheduledPublish, changeDocumentStatus, confirmDocumentScheduledPublish, createDocument, createReadContext, createRichTextDocumentReader, deleteDocument, documentAbilityKey, documentRevisionFromDatabase, ERR_VALIDATION, getDocumentScheduledPublish, parseSort, parseWhere, placeTreeNode as placeTreeNodeLifecycle, populateDocuments, populateRichTextFields, removeFromTree as removeFromTreeLifecycle, resolveIdentityField, restoreDocumentVersion, scheduleDocumentPublish, unpublishDocument, updateDocument, } from '@byline/core';
+import { applyAfterRead, assertActorCanPerform, assertLocaleVisibility, buildSearchDocument, cancelDocumentScheduledPublish, changeDocumentStatus, confirmDocumentScheduledPublish, createDocument, createReadContext, createRichTextDocumentReader, deleteDocument, documentAbilityKey, documentRevisionFromDatabase, ERR_VALIDATION, getDocumentScheduledPublish, parseSort, parseWhere, placeTreeNode as placeTreeNodeLifecycle, populateDocuments, populateRichTextFields, removeFromTree as removeFromTreeLifecycle, resolveIdentityField, resolveLocaleVisibility, restoreDocumentVersion, scheduleDocumentPublish, unpublishDocument, updateDocument, } from '@byline/core';
 import { getReadSecurityDomain, resolveReadRequestContext, resolveReadSecurityFilters, } from './read-context.js';
 import { expectedDocumentId, readSingletonForEdit, } from './read-internals.js';
 import { shapeDocument, shapePopulatedInPlace } from './response.js';
@@ -39,7 +39,8 @@ export class CollectionHandle {
     async find(options = {}) {
         const readMode = resolveReadMode(options.status);
         const readCtx = options._readContext ?? createReadContext();
-        const requestContext = await this.resolveAndAssertRead(readMode, readCtx);
+        const localeVisibility = resolveLocaleVisibility(options.status, options.localeVisibility);
+        const requestContext = await this.resolveAndAssertRead(readMode, readCtx, localeVisibility, options.locale);
         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, {
@@ -66,12 +67,13 @@ export class CollectionHandle {
             fields: select,
             readMode,
             onMissingLocale: options.onMissingLocale ?? 'fallback',
+            localeVisibility,
         });
         await this.populateIfRequested(collectionId, result.documents, locale, readMode, requestContext, {
             ...options,
             _readContext: readCtx,
         });
-        await this.finishReadDocuments(result.documents, readCtx, requestContext, locale, readMode, options._bypassBeforeRead, select, readMaterialization(options.populate, options.depth));
+        await this.finishReadDocuments(result.documents, readCtx, requestContext, locale, readMode, options._bypassBeforeRead, select, readMaterialization(options.populate, options.depth), localeVisibility);
         return {
             docs: result.documents.map((d) => this.shapeWithPopulated(d)),
             meta: {
@@ -147,6 +149,7 @@ export class CollectionHandle {
             populate: options.populate,
             depth: options.depth,
             status: options.status,
+            localeVisibility: options.localeVisibility,
             onMissingLocale: options.onMissingLocale,
             _readContext: options._readContext,
             _bypassBeforeRead: options._bypassBeforeRead,
@@ -163,25 +166,32 @@ export class CollectionHandle {
      * Asserts the collection `read` ability first (same gate as the other
      * reads), and defaults `status` to `'published'`, so a public viewer only
      * sees published content — which is also all the index holds, since
-     * indexing is published-only.
+     * indexing writes only publicly deliverable locales of the published
+     * version.
      *
-     * **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:
+     * **Authorization after ranking** — "rank in the provider, authorise in
+     * core": the provider's candidate hits are re-resolved through the normal
+     * read path (the same predicate merge + SQL compile every other read uses)
+     * whenever the search is public (`status: 'published'`, the default) or
+     * the collection configures a `beforeRead` hook. A public search re-checks
+     * every hit's locale against the advertised-locale policy even without a
+     * hook, so a stale index slice for an unchecked translation is dropped;
+     * one batched read per page performs the check. `hydrate: true` reads the
+     * hits into shaped `ClientDocument`s in their own locale (no source
+     * substitution) and attaches them as `hit.document`. Consequences:
      *
-     *   - under row scoping, `total` is the authorized hit count for this page
-     *     and facets are omitted rather than leaking provider-wide aggregates.
+     *   - 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.
      *
      * `_bypassBeforeRead: true` is the same system-operation escape hatch the
-     * read methods take.
+     * read methods take; it skips `beforeRead` scoping, never the locale check.
      *
      * Throws `ERR_VALIDATION` when no provider is registered.
      */
@@ -212,9 +222,13 @@ 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.
+        // Row-level authorization, exact-locale eligibility (+ optional
+        // hydration) — the shared finishing pipeline the zone entry point uses
+        // 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,
@@ -223,6 +237,7 @@ export class CollectionHandle {
             status: options.status,
             hydrate: options.hydrate,
             bypassBeforeRead: options._bypassBeforeRead,
+            localeVisibility: resolveLocaleVisibility(readMode),
             readContext: readCtx,
         });
         return aggregateRestricted
@@ -251,9 +266,13 @@ export class CollectionHandle {
             return;
         const populate = this.buildSearchFacetPopulateMap();
         for (const locale of this.client.contentLocales) {
+            // Public delivery, pinned explicitly: the system client indexing here
+            // is authenticated, but only publicly eligible locale slices (source,
+            // or checked and complete) may enter the index.
             const view = await this.findById(documentId, {
                 locale,
                 status: 'published',
+                localeVisibility: 'public',
                 onMissingLocale: 'omit',
                 populate,
                 _bypassBeforeRead: true,
@@ -360,7 +379,8 @@ export class CollectionHandle {
     async findById(documentId, options = {}) {
         const readMode = resolveReadMode(options.status);
         const readCtx = options._readContext ?? createReadContext();
-        const requestContext = await this.resolveAndAssertRead(readMode, readCtx);
+        const localeVisibility = resolveLocaleVisibility(options.status, options.localeVisibility);
+        const requestContext = await this.resolveAndAssertRead(readMode, readCtx, localeVisibility, options.locale);
         const { locale = this.client.defaultLocale } = options;
         const filters = await this.resolveBeforeReadFilters(requestContext, readCtx, options._bypassBeforeRead);
         const collectionId = await this.client.resolveCollectionId(this.definition.path);
@@ -373,6 +393,7 @@ export class CollectionHandle {
             filters,
             lenient: options.lenient,
             onMissingLocale: options.onMissingLocale ?? 'fallback',
+            localeVisibility,
         });
         if (raw == null)
             return null;
@@ -385,7 +406,7 @@ export class CollectionHandle {
             ...options,
             _readContext: readCtx,
         });
-        await this.finishReadDocuments([raw], readCtx, requestContext, locale, readMode, options._bypassBeforeRead, options.select, readMaterialization(options.populate, options.depth));
+        await this.finishReadDocuments([raw], readCtx, requestContext, locale, readMode, options._bypassBeforeRead, options.select, readMaterialization(options.populate, options.depth), localeVisibility);
         return this.shapeWithPopulated(raw);
     }
     async findByIdForEdit(documentId, options = {}) {
@@ -453,7 +474,8 @@ export class CollectionHandle {
     async findByPath(path, options = {}) {
         const readMode = resolveReadMode(options.status);
         const readCtx = options._readContext ?? createReadContext();
-        const requestContext = await this.resolveAndAssertRead(readMode, readCtx);
+        const localeVisibility = resolveLocaleVisibility(options.status, options.localeVisibility);
+        const requestContext = await this.resolveAndAssertRead(readMode, readCtx, localeVisibility, options.locale);
         const { locale = this.client.defaultLocale } = options;
         const filters = await this.resolveBeforeReadFilters(requestContext, readCtx, options._bypassBeforeRead);
         const collectionId = await this.client.resolveCollectionId(this.definition.path);
@@ -465,6 +487,7 @@ export class CollectionHandle {
             readMode,
             filters,
             onMissingLocale: options.onMissingLocale ?? 'fallback',
+            localeVisibility,
         });
         if (raw == null)
             return null;
@@ -475,7 +498,7 @@ export class CollectionHandle {
             ...options,
             _readContext: readCtx,
         });
-        await this.finishReadDocuments([raw], readCtx, requestContext, locale, readMode, options._bypassBeforeRead, options.select, readMaterialization(options.populate, options.depth));
+        await this.finishReadDocuments([raw], readCtx, requestContext, locale, readMode, options._bypassBeforeRead, options.select, readMaterialization(options.populate, options.depth), localeVisibility);
         return this.shapeWithPopulated(raw);
     }
     // -------------------------------------------------------------------------
@@ -817,7 +840,8 @@ export class CollectionHandle {
         this.assertTreeCollection();
         const readMode = resolveReadMode(options.status);
         const readCtx = options._readContext ?? createReadContext();
-        const requestContext = await this.resolveAndAssertRead(readMode, readCtx);
+        const localeVisibility = resolveLocaleVisibility(options.status, options.localeVisibility);
+        const requestContext = await this.resolveAndAssertRead(readMode, readCtx, localeVisibility, options.locale);
         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);
@@ -828,10 +852,11 @@ export class CollectionHandle {
             readMode,
             locale,
             filters,
+            localeVisibility,
         });
         if (structure.length === 0)
             return [];
-        const shapedById = await this.hydrateTreeNodes(collectionId, structure.map((n) => n.document_id), locale, readMode, options.select, filters, readCtx, requestContext, options._bypassBeforeRead);
+        const shapedById = await this.hydrateTreeNodes(collectionId, structure.map((n) => n.document_id), locale, readMode, options.select, filters, readCtx, requestContext, options._bypassBeforeRead, localeVisibility);
         // 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.
@@ -960,7 +985,8 @@ export class CollectionHandle {
         this.assertTreeCollection();
         const readMode = resolveReadMode(options.status);
         const readCtx = options._readContext ?? createReadContext();
-        const requestContext = await this.resolveAndAssertRead(readMode, readCtx);
+        const localeVisibility = resolveLocaleVisibility(options.status, options.localeVisibility);
+        const requestContext = await this.resolveAndAssertRead(readMode, readCtx, localeVisibility, options.locale);
         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);
@@ -969,11 +995,12 @@ export class CollectionHandle {
             readMode,
             locale,
             filters,
+            localeVisibility,
         });
         if (ancestors.length === 0)
             return [];
         const ids = ancestors.map((a) => a.document_id);
-        const shapedById = await this.hydrateTreeNodes(collectionId, ids, locale, readMode, options.select, filters, readCtx, requestContext, options._bypassBeforeRead);
+        const shapedById = await this.hydrateTreeNodes(collectionId, ids, locale, readMode, options.select, filters, readCtx, requestContext, options._bypassBeforeRead, localeVisibility);
         // A hydration-time miss truncates the edge rather than compacting past a
         // newly-hidden ancestor.
         const visible = [];
@@ -1001,13 +1028,15 @@ export class CollectionHandle {
         this.assertTreeCollection();
         const readMode = resolveReadMode(options.status);
         const readCtx = options._readContext ?? createReadContext();
-        const requestContext = await this.resolveAndAssertRead(readMode, readCtx);
+        const localeVisibility = resolveLocaleVisibility(options.status, options.localeVisibility);
+        const requestContext = await this.resolveAndAssertRead(readMode, readCtx, localeVisibility, options.locale);
         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,
+            localeVisibility,
         });
         return {
             placed: result.placed,
@@ -1085,9 +1114,21 @@ 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(readMode, readContext) {
+    /**
+     * Resolve the request context for a read and authorize it: the collection
+     * read ability (`assertActorCanPerform`) and the read's locale visibility
+     * (`assertLocaleVisibility`). Visibility defaults from `readMode`, so the
+     * editing, history and version reads (`readMode: 'any'`) are editorial.
+     *
+     * The visibility check validates the *effective* locale, the value every
+     * read method sends to storage (`locale ?? client.defaultLocale`), so a
+     * client configured with `defaultLocale: 'all'` cannot turn an omitted
+     * locale into a public all-locale read.
+     */
+    async resolveAndAssertRead(readMode, readContext, localeVisibility = resolveLocaleVisibility(readMode), locale) {
         const requestContext = await resolveReadRequestContext(this.client, readContext, readMode);
         assertActorCanPerform(requestContext, this.definition, 'read');
+        assertLocaleVisibility(requestContext, this.definition.path, localeVisibility, locale ?? this.client.defaultLocale);
         return requestContext;
     }
     /**
@@ -1113,7 +1154,7 @@ export class CollectionHandle {
      * `afterRead` per node (deduped within one shared `ReadContext`) to stay
      * consistent with the other client read paths.
      */
-    async hydrateTreeNodes(collectionId, documentIds, locale, readMode, select, filters, readContext, requestContext, bypassBeforeRead) {
+    async hydrateTreeNodes(collectionId, documentIds, locale, readMode, select, filters, readContext, requestContext, bypassBeforeRead, localeVisibility = resolveLocaleVisibility(readMode)) {
         const shapedById = new Map();
         if (documentIds.length === 0)
             return shapedById;
@@ -1124,8 +1165,9 @@ export class CollectionHandle {
             readMode,
             fields: select,
             filters,
+            localeVisibility,
         });
-        await this.finishReadDocuments(rawDocs, readContext, requestContext, locale, readMode, bypassBeforeRead, select, 'tree');
+        await this.finishReadDocuments(rawDocs, readContext, requestContext, locale, readMode, bypassBeforeRead, select, 'tree', localeVisibility);
         for (const raw of rawDocs) {
             const doc = raw;
             shapedById.set(doc.document_id, this.shapeWithPopulated(doc));
@@ -1153,6 +1195,9 @@ export class CollectionHandle {
             depth: options.depth,
             locale,
             readMode,
+            // Equals the entry point's resolved visibility: an explicit option wins,
+            // otherwise the default follows the same status that selected `readMode`.
+            localeVisibility: options.localeVisibility ?? resolveLocaleVisibility(readMode),
             readContext: options._readContext,
             requestContext,
             securityDomain: getReadSecurityDomain(this.client),
@@ -1169,7 +1214,7 @@ export class CollectionHandle {
      * `populateRelationsOnRead` inside the service. No-ops when no adapter
      * is registered.
      */
-    async richTextPopulateSources(rawDocs, readContext, requestContext, locale, readMode, bypassBeforeRead) {
+    async richTextPopulateSources(rawDocs, readContext, requestContext, locale, readMode, bypassBeforeRead, localeVisibility) {
         const populate = this.client.richTextPopulate;
         if (!populate || rawDocs.length === 0)
             return;
@@ -1187,6 +1232,7 @@ export class CollectionHandle {
                 requestContext,
                 readContext,
                 readMode,
+                localeVisibility,
                 locale,
                 bypassBeforeRead,
                 richTextPopulate: populate,
@@ -1195,10 +1241,10 @@ export class CollectionHandle {
         });
     }
     /** Complete the common post-reconstruction pipeline in security order. */
-    async finishReadDocuments(rawDocs, readContext, requestContext, locale, readMode, bypassBeforeRead, projection, materialization) {
+    async finishReadDocuments(rawDocs, readContext, requestContext, locale, readMode, bypassBeforeRead, projection, materialization, localeVisibility = resolveLocaleVisibility(readMode)) {
         // 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);
+        await this.richTextPopulateSources(rawDocs, readContext, requestContext, locale, readMode, bypassBeforeRead, localeVisibility);
         for (const doc of rawDocs) {
             await applyAfterRead({
                 doc,

package/dist/response.js

@@ -39,6 +39,13 @@ export function shapeDocument(raw) {
     if (typeof raw.source_locale === 'string') {
         shaped.sourceLocale = raw.source_locale;
     }
+    // The read's language decision for this document and selected version
+    // (storage key `resolved_locale`). `null` is a real value (withheld exact
+    // read, multi-locale read, locale-agnostic version); only a result the
+    // adapter did not reconstruct lacks the key.
+    if ('resolved_locale' in raw) {
+        shaped.resolvedLocale = raw.resolved_locale ?? null;
+    }
     // Version audit metadata — acting user + action (storage keys
     // `created_by` / `event_type`).
     // `created_by` is NULL on rows written before audit wiring or by

package/dist/search.d.ts

@@ -14,10 +14,21 @@
  * `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.
+ * 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 { ReadContext, ReadMode, SearchHit, SearchProvider } from '@byline/core';
+import type { LocaleVisibility, ReadContext, ReadMode, SearchHit, SearchProvider } from '@byline/core';
 import type { BylineClient } from './client.js';
 import type { ClientSearchResults, HydratedSearchHit, ZoneSearchOptions } from './types.js';
 /** Validate the optional logical body-field scope before calling a provider. */
@@ -30,6 +41,11 @@ export interface FinalizeSearchHitsParams {
     status?: ReadMode;
     hydrate?: boolean;
     bypassBeforeRead?: true;
+    /**
+     * The search's locale visibility (derived from `status`). Under `'public'`
+     * each hit's document must be publicly eligible in the hit's locale.
+     */
+    localeVisibility: LocaleVisibility;
     /** Shared per-request read context (beforeRead cache). Created when omitted. */
     readContext?: ReadContext;
 }
@@ -42,9 +58,19 @@ export interface FinalizeSearchHitsParams {
  *     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).
+ *   - `hydrate` off, public visibility — every collection's hit ids are
+ *     re-resolved through the normal read path with `onMissingLocale:
+ *     'omit'` (identity-field projection), which applies both exact-locale
+ *     eligibility and any `beforeRead` scoping. An index entry can outlive
+ *     the checkbox that allowed it (until reindexing catches up), so this
+ *     check runs even without a hook.
+ *   - `hydrate` off, editorial visibility — collections with a `beforeRead`
+ *     predicate get the trimmed id re-resolution; collections without one
+ *     pass through untouched (no second query).
+ *
+ * Hydration also reads with `'omit'`: a hit is for one locale slice, and a
+ * source-language document substituted by fallback would not make that hit
+ * safe.
  *
  * Hits whose `collectionPath` isn't registered in the runtime config are
  * dropped with a debug log (an index can outlive a collection). Original

package/dist/search.js

@@ -5,7 +5,7 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
-import { assertActorCanPerform, createReadContext, ERR_VALIDATION, getCollectionAdminConfig, MAX_SEARCH_QUERY_LENGTH, resolveSearchZones, } from '@byline/core';
+import { assertActorCanPerform, createReadContext, ERR_VALIDATION, getCollectionAdminConfig, MAX_SEARCH_QUERY_LENGTH, resolveLocaleVisibility, resolveSearchZones, } from '@byline/core';
 import { resolveReadRequestContext, resolveReadSecurityFilters } from './read-context.js';
 /** Validate the optional logical body-field scope before calling a provider. */
 export function assertSearchFieldScope(provider, fieldScope) {
@@ -30,16 +30,26 @@ export function assertSearchFieldScope(provider, fieldScope) {
  *     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).
+ *   - `hydrate` off, public visibility — every collection's hit ids are
+ *     re-resolved through the normal read path with `onMissingLocale:
+ *     'omit'` (identity-field projection), which applies both exact-locale
+ *     eligibility and any `beforeRead` scoping. An index entry can outlive
+ *     the checkbox that allowed it (until reindexing catches up), so this
+ *     check runs even without a hook.
+ *   - `hydrate` off, editorial visibility — collections with a `beforeRead`
+ *     predicate get the trimmed id re-resolution; collections without one
+ *     pass through untouched (no second query).
+ *
+ * Hydration also reads with `'omit'`: a hit is for one locale slice, and a
+ * source-language document substituted by fallback would not make that hit
+ * safe.
  *
  * 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;
+    const { client, requestContext, hits, locale, status, hydrate, bypassBeforeRead, localeVisibility, } = params;
     if (hits.length === 0)
         return hits;
     const readCtx = params.readContext ?? createReadContext();
@@ -78,12 +88,35 @@ export async function finalizeSearchHits(params) {
                 select,
                 locale,
                 status,
+                onMissingLocale: 'omit',
+                localeVisibility,
                 page: 1,
                 pageSize: ids.length,
                 _readContext: readCtx,
                 ...(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') {
+            // Exact-locale eligibility (and beforeRead scoping, unless bypassed)
+            // for every public hit, hook or no hook.
+            const result = await handle.find({
+                where: { id: { $in: ids } },
+                select: definition.useAsTitle != null ? [definition.useAsTitle] : undefined,
+                locale,
+                status,
+                onMissingLocale: 'omit',
+                localeVisibility,
+                page: 1,
+                pageSize: ids.length,
+                _readContext: readCtx,
+                ...(bypassBeforeRead ? { _bypassBeforeRead: true } : {}),
+            });
+            const allowed = new Set(result.docs.map((d) => d.id));
+            allowedByCollection.set(collectionPath, allowed);
+            await warnOnStaleHits(params, readCtx, collectionPath, group, allowed);
             continue;
         }
         if (bypassBeforeRead) {
@@ -129,6 +162,30 @@ export async function finalizeSearchHits(params) {
     }
     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
 // ---------------------------------------------------------------------------
@@ -211,6 +268,7 @@ export async function zoneSearch(client, options) {
         status: options.status,
         hydrate: options.hydrate,
         bypassBeforeRead: options._bypassBeforeRead,
+        localeVisibility: resolveLocaleVisibility(readMode),
         readContext: readCtx,
     });
     return aggregateRestricted

package/dist/singleton-handle.js

@@ -5,7 +5,7 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
-import { assertActorCanPerform, cancelDocumentScheduledPublish, changeDocumentStatus, confirmDocumentScheduledPublish, copySingletonToLocale, createReadContext, ERR_NOT_FOUND, getDocumentScheduledPublish, resolveSingletonDocumentId, restoreSingletonVersion, scheduleDocumentPublish, unpublishDocument, updateSingleton, } from '@byline/core';
+import { assertActorCanPerform, assertLocaleVisibility, cancelDocumentScheduledPublish, changeDocumentStatus, confirmDocumentScheduledPublish, copySingletonToLocale, createReadContext, ERR_NOT_FOUND, getDocumentScheduledPublish, resolveLocaleVisibility, resolveSingletonDocumentId, restoreSingletonVersion, scheduleDocumentPublish, unpublishDocument, updateSingleton, } from '@byline/core';
 import { CollectionHandle } from './collection-handle.js';
 import { resolveReadRequestContext } from './read-context.js';
 import { expectedDocumentId, readSingletonForEdit, } from './read-internals.js';
@@ -32,7 +32,11 @@ export class SingletonHandle {
     }
     async get(options = {}) {
         const readContext = options._readContext ?? createReadContext();
-        await this.authorizeRead(options.status ?? 'published', readContext);
+        const requestContext = await this.authorizeRead(options.status ?? 'published', readContext);
+        // Validate locale visibility before the slot lookup, so an invalid request
+        // is rejected whether or not the slot is materialized, and before any
+        // adapter work. The delegated `findById` repeats the same check.
+        assertLocaleVisibility(requestContext, this.definition.path, resolveLocaleVisibility(options.status, options.localeVisibility), options.locale ?? this.client.defaultLocale);
         const documentId = await this.resolveMappedDocumentId();
         if (documentId == null)
             return null;

package/dist/types.d.ts

@@ -6,7 +6,7 @@
  * Copyright (c) Infonomic Company Limited
  */
 import type { RequestContext } from '@byline/auth';
-import type { BylineLogger, CollectionDefinition, DocumentPublishSchedule, IDbAdapter, IStorageProvider, MissingLocalePolicy, PopulateSpec, PredicateValue, QueryPredicate, ReadContext, ReadMode, RichTextPopulateFn, RichTextToTextFn, SearchFacetBucket, SearchHit, SearchMatching, SearchProvider, ServerConfig, SingletonSavePrecondition, SlugifierFn, SortSpec } from '@byline/core';
+import type { BylineLogger, CollectionDefinition, DocumentPublishSchedule, IDbAdapter, IStorageProvider, LocaleVisibility, MissingLocalePolicy, PopulateSpec, PredicateValue, QueryPredicate, ReadContext, ReadMode, RichTextPopulateFn, RichTextToTextFn, SearchFacetBucket, SearchHit, SearchMatching, SearchProvider, ServerConfig, SingletonSavePrecondition, SlugifierFn, SortSpec } from '@byline/core';
 export type { FilterOperators, PredicateValue, QueryPredicate, SearchFacetBucket, SearchHit, SearchProvider, SearchResults, SortDirection, SortSpec, } from '@byline/core';
 export interface BylineClientConfig {
     /**
@@ -165,9 +165,18 @@ interface PopulateControls extends ReadContextControls {
  * Distinct from `where.status`, which is an *exact-match filter* on the
  * selected version's status column ("show me all drafts"). `status` is
  * the *source view* selector.
+ *
+ * `localeVisibility` chooses which of the selected version's languages may be
+ * delivered. `'public'` honours the editor's advertised-locale checkboxes (an
+ * unchecked translation behaves like a missing one); `'editorial'` ignores them
+ * so an authorized reviewer can see a withheld translation. It defaults from
+ * `status`: omitted or `'published'` → `'public'`, `'any'` → `'editorial'`.
+ * `'editorial'` requires an authenticated actor, and a `'public'` read cannot
+ * request `locale: 'all'`. See `LocaleVisibility` in `@byline/core`.
  */
 interface StatusControls {
     status?: ReadMode;
+    localeVisibility?: LocaleVisibility;
 }
 /**
  * Options for `CollectionHandle.search(...)` — a ranked full-text query
@@ -596,6 +605,21 @@ export interface ClientDocument<F = Record<string, any>> {
      * `docs/08-internationalization/index.md`.
      */
     sourceLocale?: string;
+    /**
+     * The content locale this read selected for this document's fields, decided
+     * from the whole selected version before any field projection.
+     *
+     *   - `'fallback'`: the first eligible locale in the chain, which may be the
+     *     source rather than the requested locale.
+     *   - `'omit'`, or an eligible exact read: the requested locale.
+     *   - `null`: a public exact read that withheld an unavailable translation,
+     *     a multi-locale (`locale: 'all'`) read, or a locale-agnostic version.
+     *
+     * It describes which locale was selected, not whether every field is
+     * linguistically in that language, and not whether the translation is
+     * publicly released. Each populated target and tree node carries its own.
+     */
+    resolvedLocale?: string | null;
     /** When this version was created. */
     createdAt: Date;
     /** When this version was last updated. */
@@ -730,6 +754,6 @@ export interface EditableTreeNode<F = Record<string, any>> {
     depth: number;
     children: EditableTreeNode<F>[];
 }
-export type FindByIdForEditOptions<F = Record<string, any>> = Omit<FindByIdOptions<F>, 'status'>;
-export type FindForEditOptions<F = Record<string, any>> = Omit<FindOptions<F>, 'status'>;
-export type GetSubtreeForEditOptions<F = Record<string, any>> = Omit<GetSubtreeOptions<F>, 'status'>;
+export type FindByIdForEditOptions<F = Record<string, any>> = Omit<FindByIdOptions<F>, 'status' | 'localeVisibility'>;
+export type FindForEditOptions<F = Record<string, any>> = Omit<FindOptions<F>, 'status' | 'localeVisibility'>;
+export type GetSubtreeForEditOptions<F = Record<string, any>> = Omit<GetSubtreeOptions<F>, 'status' | 'localeVisibility'>;

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/client",
   "private": false,
   "license": "MPL-2.0",
-  "version": "6.6.0",
+  "version": "6.7.1",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -44,8 +44,8 @@
   ],
   "dependencies": {
     "uuid": "^14.0.2",
-    "@byline/auth": "6.6.0",
-    "@byline/core": "6.6.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/db-postgres": "6.6.0",
-    "@byline/search-postgres": "6.6.0"
+    "@byline/db-postgres": "6.7.1",
+    "@byline/search-postgres": "6.7.1"
   },
   "publishConfig": {
     "access": "public",