@byline/core 6.5.0 → 6.7.0

package/dist/@types/db-types.d.ts

@@ -44,6 +44,28 @@ export type ReadMode = 'any' | 'published';
  * in every locale. See `docs/08-internationalization/index.md`.
  */
 export type MissingLocalePolicy = 'empty' | 'fallback' | 'omit';
+/**
+ * Whether a read's language selection honours the editor's advertised-locale
+ * checkboxes (the value of the `localeVisibility` read option).
+ *
+ *   - `'public'`    — in a collection with `advertiseLocales: true`, an
+ *                     additional translation is eligible only when it is both
+ *                     complete on the selected version and checked in the
+ *                     document's `availableLocales`. An unchecked translation
+ *                     behaves exactly like a missing one under every
+ *                     `onMissingLocale` policy. The source locale is always
+ *                     eligible. Collections without `advertiseLocales` are
+ *                     gated by completeness alone.
+ *   - `'editorial'` — completeness alone decides; checkboxes are ignored, so an
+ *                     authorized reviewer can see a withheld translation. Also
+ *                     the visibility of exact editing reads.
+ *
+ * Independent of `ReadMode`: version selection chooses *which version*, locale
+ * visibility chooses *which of its languages* may be delivered. `@byline/client`
+ * defaults it from `status` — `'published'` (or omitted) → `'public'`,
+ * `'any'` → `'editorial'` — and requires an actor for `'editorial'`.
+ */
+export type LocaleVisibility = 'public' | 'editorial';
 /**
  * Request-scoped context shared across every read and populate walk in one
  * logical request. Threaded through populate, `afterRead` hooks, and any
@@ -1058,6 +1080,15 @@ export interface IDocumentQueries {
         /** See `MissingLocalePolicy`. `'omit'` returns `null` when the document
          *  is not available in the requested locale. Omitted ⇒ `'empty'`. */
         onMissingLocale?: MissingLocalePolicy;
+        /**
+         * See `LocaleVisibility`. Omitted ⇒ `'editorial'`: direct adapter reads are
+         * trusted primitives and keep their exact editing behaviour. `@byline/client`
+         * always passes the resolved value. Under `'public'`, `'fallback'` skips
+         * ineligible locales, `'omit'` excludes documents whose requested locale is
+         * ineligible, and an exact read of an ineligible locale withholds localized
+         * values. A reconstructed result reports its decision as `resolved_locale`.
+         */
+        localeVisibility?: LocaleVisibility;
     }): Promise<any | null>;
     /**
      * Fetch only the current version's metadata row (no field reconstruction).
@@ -1119,6 +1150,8 @@ export interface IDocumentQueries {
         /** See `MissingLocalePolicy`. `'omit'` returns `null` when the document
          *  is not available in the requested locale. Omitted ⇒ `'empty'`. */
         onMissingLocale?: MissingLocalePolicy;
+        /** See `getDocumentById.localeVisibility`. */
+        localeVisibility?: LocaleVisibility;
     }): Promise<any | null>;
     getDocumentByVersion(params: {
         document_version_id: string;
@@ -1157,6 +1190,9 @@ export interface IDocumentQueries {
         filters?: DocumentFilter[];
         /** See `getDocumentById.requestContext`. */
         requestContext?: RequestContext;
+        /** See `getDocumentById.localeVisibility`. Each document resolves under
+         *  its own source locale, completeness ledger and checkbox set. */
+        localeVisibility?: LocaleVisibility;
     }): Promise<any[]>;
     getDocumentHistory(params: {
         collection_id: string;
@@ -1269,6 +1305,9 @@ export interface IDocumentQueries {
          *  in the requested locale (filtered at the SQL layer so pagination stays
          *  correct). Omitted ⇒ `'empty'`. */
         onMissingLocale?: MissingLocalePolicy;
+        /** See `getDocumentById.localeVisibility`. Under `'public'` with `'omit'`,
+         *  the checkbox gate is compiled into SQL before count and pagination. */
+        localeVisibility?: LocaleVisibility;
     }): Promise<{
         documents: any[];
         total: number;
@@ -1351,6 +1390,13 @@ export interface IDocumentQueries {
         readMode?: ReadMode;
         locale?: string;
         filters?: DocumentFilter[];
+        /**
+         * The read's resolved locale visibility. When supplied, localized
+         * `filters` evaluate each node in the locale hydration shows (fallback
+         * under this visibility). Omitted ⇒ exact requested-locale matching, as
+         * editing reads expect.
+         */
+        localeVisibility?: LocaleVisibility;
     }): Promise<Array<{
         document_id: string;
         depth: number;
@@ -1388,6 +1434,13 @@ export interface IDocumentQueries {
         readMode?: ReadMode;
         locale?: string;
         filters?: DocumentFilter[];
+        /**
+         * The read's resolved locale visibility. When supplied, localized
+         * `filters` evaluate each node in the locale hydration shows (fallback
+         * under this visibility). Omitted ⇒ exact requested-locale matching, as
+         * editing reads expect.
+         */
+        localeVisibility?: LocaleVisibility;
     }): Promise<{
         placed: boolean;
         parentDocumentId: string | null;
@@ -1422,6 +1475,13 @@ export interface IDocumentQueries {
         readMode?: ReadMode;
         locale?: string;
         filters?: DocumentFilter[];
+        /**
+         * The read's resolved locale visibility. When supplied, localized
+         * `filters` evaluate each node in the locale hydration shows (fallback
+         * under this visibility). Omitted ⇒ exact requested-locale matching, as
+         * editing reads expect.
+         */
+        localeVisibility?: LocaleVisibility;
     }): Promise<Array<{
         document_id: string;
         parent_document_id: string | null;

package/dist/auth/assert-locale-visibility.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 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 { type RequestContext } from '@byline/auth';
+import type { LocaleVisibility } from '../@types/index.js';
+/**
+ * Authorize a read's locale visibility, alongside `assertActorCanPerform`.
+ * Called by `@byline/client` read methods after the collection read check and
+ * before any DB work.
+ *
+ *   1. **`'editorial'` requires an actor.** Editorial visibility can deliver a
+ *      complete but unchecked translation, so an anonymous caller is rejected
+ *      with `ERR_UNAUTHENTICATED` even when `readMode === 'published'`. The
+ *      actor's collection read ability is asserted by `assertActorCanPerform`.
+ *   2. **`'public'` rejects `locale: 'all'`.** The multi-locale map would expose
+ *      every stored translation, withheld or partial, so a public read must
+ *      name one locale. This applies to every collection, including those
+ *      without `advertiseLocales`.
+ *
+ * Locale visibility is read intent, not authority: nothing here elevates a
+ * context, and `_bypassBeforeRead` has no bearing on it.
+ */
+export declare function assertLocaleVisibility(context: RequestContext | undefined, collectionPath: string, visibility: LocaleVisibility, locale: string | undefined): void;

package/dist/auth/assert-locale-visibility.js

@@ -0,0 +1,43 @@
+/**
+ * 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 { ERR_UNAUTHENTICATED } from '@byline/auth';
+import { ERR_VALIDATION } from '../lib/errors.js';
+/**
+ * Authorize a read's locale visibility, alongside `assertActorCanPerform`.
+ * Called by `@byline/client` read methods after the collection read check and
+ * before any DB work.
+ *
+ *   1. **`'editorial'` requires an actor.** Editorial visibility can deliver a
+ *      complete but unchecked translation, so an anonymous caller is rejected
+ *      with `ERR_UNAUTHENTICATED` even when `readMode === 'published'`. The
+ *      actor's collection read ability is asserted by `assertActorCanPerform`.
+ *   2. **`'public'` rejects `locale: 'all'`.** The multi-locale map would expose
+ *      every stored translation, withheld or partial, so a public read must
+ *      name one locale. This applies to every collection, including those
+ *      without `advertiseLocales`.
+ *
+ * Locale visibility is read intent, not authority: nothing here elevates a
+ * context, and `_bypassBeforeRead` has no bearing on it.
+ */
+export function assertLocaleVisibility(context, collectionPath, visibility, locale) {
+    if (visibility === 'editorial') {
+        if (context?.actor == null) {
+            throw ERR_UNAUTHENTICATED({
+                message: `anonymous read of '${collectionPath}' cannot use localeVisibility: 'editorial'`,
+            });
+        }
+        return;
+    }
+    if (locale === 'all') {
+        throw ERR_VALIDATION({
+            message: `locale: 'all' is an editorial read on '${collectionPath}'; ` +
+                `a public read must request a single locale`,
+            details: { collectionPath },
+        });
+    }
+}

package/dist/auth/assert-locale-visibility.test.node.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 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
+ */
+export {};

package/dist/auth/assert-locale-visibility.test.node.js

@@ -0,0 +1,46 @@
+/**
+ * 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 { AuthError, AuthErrorCodes, createRequestContext, createSuperAdminContext, } from '@byline/auth';
+import { describe, expect, it } from 'vitest';
+import { ErrorCodes } from '../lib/errors.js';
+import { assertLocaleVisibility } from './assert-locale-visibility.js';
+const anonymous = createRequestContext({ actor: null, readMode: 'published' });
+const admin = createSuperAdminContext({ id: 'test-admin' });
+describe('assertLocaleVisibility', () => {
+    it('permits an anonymous public read of a single locale', () => {
+        expect(() => assertLocaleVisibility(anonymous, 'pages', 'public', 'es')).not.toThrow();
+    });
+    it('rejects an anonymous editorial read even with readMode published', () => {
+        try {
+            assertLocaleVisibility(anonymous, 'pages', 'editorial', 'es');
+            expect.fail('expected ERR_UNAUTHENTICATED');
+        }
+        catch (err) {
+            expect(err).toBeInstanceOf(AuthError);
+            expect(err.code).toBe(AuthErrorCodes.UNAUTHENTICATED);
+        }
+    });
+    it('rejects an editorial read with no context', () => {
+        expect(() => assertLocaleVisibility(undefined, 'pages', 'editorial', 'es')).toThrow(AuthError);
+    });
+    it('permits an authenticated editorial read, including locale all', () => {
+        expect(() => assertLocaleVisibility(admin, 'pages', 'editorial', 'es')).not.toThrow();
+        expect(() => assertLocaleVisibility(admin, 'pages', 'editorial', 'all')).not.toThrow();
+    });
+    it('rejects a public locale all read, even for an authenticated actor', () => {
+        for (const ctx of [anonymous, admin]) {
+            try {
+                assertLocaleVisibility(ctx, 'pages', 'public', 'all');
+                expect.fail('expected ERR_VALIDATION');
+            }
+            catch (err) {
+                expect(err.code).toBe(ErrorCodes.VALIDATION);
+            }
+        }
+    });
+});

package/dist/auth/index.d.ts

@@ -7,5 +7,6 @@
  */
 export { applyBeforeRead, bindReadContextAuthority, compileBeforeReadFilters, } from './apply-before-read.js';
 export { assertActorCanPerform } from './assert-actor-can-perform.js';
+export { assertLocaleVisibility } from './assert-locale-visibility.js';
 export { type ActorAbilitySnapshot, filterReadableCollections, } from './filter-readable-collections.js';
 export { COLLECTION_ABILITY_VERBS, type CollectionAbilityResource, type CollectionAbilityResourceDescriptor, type CollectionAbilityVerb, collectionAbilityKey, type DocumentAbilityResource, type DocumentAbilityVerbFor, documentAbilityKey, registerCollectionAbilities, registerDocumentAbilities, registerSingletonAbilities, SINGLETON_ABILITY_VERBS, type SingletonAbilityResource, type SingletonAbilityResourceDescriptor, type SingletonAbilityVerb, } from './register-collection-abilities.js';

package/dist/auth/index.js

@@ -7,5 +7,6 @@
  */
 export { applyBeforeRead, bindReadContextAuthority, compileBeforeReadFilters, } from './apply-before-read.js';
 export { assertActorCanPerform } from './assert-actor-can-perform.js';
+export { assertLocaleVisibility } from './assert-locale-visibility.js';
 export { filterReadableCollections, } from './filter-readable-collections.js';
 export { COLLECTION_ABILITY_VERBS, collectionAbilityKey, documentAbilityKey, registerCollectionAbilities, registerDocumentAbilities, registerSingletonAbilities, SINGLETON_ABILITY_VERBS, } from './register-collection-abilities.js';

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export * from './@types/index.js';
-export { type ActorAbilitySnapshot, applyBeforeRead, assertActorCanPerform, bindReadContextAuthority, COLLECTION_ABILITY_VERBS, type CollectionAbilityResource, type CollectionAbilityResourceDescriptor, type CollectionAbilityVerb, collectionAbilityKey, compileBeforeReadFilters, type DocumentAbilityResource, type DocumentAbilityVerbFor, documentAbilityKey, filterReadableCollections, registerCollectionAbilities, registerDocumentAbilities, registerSingletonAbilities, SINGLETON_ABILITY_VERBS, type SingletonAbilityResource, type SingletonAbilityResourceDescriptor, type SingletonAbilityVerb, } from './auth/index.js';
+export { type ActorAbilitySnapshot, applyBeforeRead, assertActorCanPerform, assertLocaleVisibility, bindReadContextAuthority, COLLECTION_ABILITY_VERBS, type CollectionAbilityResource, type CollectionAbilityResourceDescriptor, type CollectionAbilityVerb, collectionAbilityKey, compileBeforeReadFilters, type DocumentAbilityResource, type DocumentAbilityVerbFor, documentAbilityKey, filterReadableCollections, registerCollectionAbilities, registerDocumentAbilities, registerSingletonAbilities, SINGLETON_ABILITY_VERBS, type SingletonAbilityResource, type SingletonAbilityResourceDescriptor, type SingletonAbilityVerb, } from './auth/index.js';
 export { defineAdminConfig, defineServerConfig, getAdminConfig, getCollectionAdminConfig, getCollectionDefinition, getServerConfig, getSingletonAdminConfig, orderByContentLocale, } from './config/config.js';
 export { type CollectionGroupBucket, groupCollectionsForAdmin, } from './config/group-collections.js';
 export { resolveRoutes } from './config/routes.js';

package/dist/index.js

@@ -11,7 +11,7 @@
 // breaking package-surface change.
 // ---------------------------------------------------------------------------
 export * from './@types/index.js';
-export { applyBeforeRead, assertActorCanPerform, bindReadContextAuthority, COLLECTION_ABILITY_VERBS, collectionAbilityKey, compileBeforeReadFilters, documentAbilityKey, filterReadableCollections, registerCollectionAbilities, registerDocumentAbilities, registerSingletonAbilities, SINGLETON_ABILITY_VERBS, } from './auth/index.js';
+export { applyBeforeRead, assertActorCanPerform, assertLocaleVisibility, bindReadContextAuthority, COLLECTION_ABILITY_VERBS, collectionAbilityKey, compileBeforeReadFilters, documentAbilityKey, filterReadableCollections, registerCollectionAbilities, registerDocumentAbilities, registerSingletonAbilities, SINGLETON_ABILITY_VERBS, } from './auth/index.js';
 export { defineAdminConfig, defineServerConfig, getAdminConfig, getCollectionAdminConfig, getCollectionDefinition, getServerConfig, getSingletonAdminConfig, orderByContentLocale, } from './config/config.js';
 export { groupCollectionsForAdmin, } from './config/group-collections.js';
 export { resolveRoutes } from './config/routes.js';

package/dist/services/document-lifecycle/internals.js

@@ -100,6 +100,9 @@ export async function applyRichTextEmbed(ctx, data) {
             requestContext,
             readContext,
             readMode: 'published',
+            // Snapshots copied into a saved parent are public delivery: an editor's
+            // authenticated session must not capture a withheld translation.
+            localeVisibility: 'public',
             locale: ctx.defaultLocale,
             richTextPopulate,
         }),

package/dist/services/document-lifecycle.test.node.js

@@ -1086,6 +1086,83 @@ describe('Document lifecycle service', () => {
                 patches: [],
             })).rejects.toSatisfy((err) => err instanceof BylineError && err.code === ErrorCodes.NOT_FOUND);
         });
+        it('writes a combined locale and content save in one transaction, locale first', async () => {
+            const afterSystemFieldsChange = vi.fn();
+            const afterUpdate = vi.fn();
+            const { db, getDocumentById, getDocumentSystemFieldsForUpdate, createDocumentVersion, withTransaction, } = createMockDb();
+            getDocumentById.mockResolvedValue({
+                document_version_id: 'previous',
+                fields: { title: 'Old' },
+            });
+            getDocumentSystemFieldsForUpdate.mockResolvedValue({
+                path: 'doc',
+                source_locale: 'en',
+                availableLocales: ['en'],
+            });
+            const order = [];
+            let outerSettled = false;
+            vi.mocked(db.commands.documents.setDocumentAvailableLocales).mockImplementation(async () => {
+                // Watch the outer guarded unit that is running this write.
+                const outer = withTransaction.mock.results[0]?.value;
+                if (outer == null)
+                    throw new Error('locale write ran outside a guarded unit');
+                void outer.finally(() => {
+                    outerSettled = true;
+                });
+                order.push(`locales:${db.revisions.isInTransaction()}`);
+            });
+            createDocumentVersion.mockImplementation(async () => {
+                // Version persistence may open a nested unit; it must still be inside
+                // the outer guarded unit that wrote the locales.
+                order.push(`version:${db.revisions.isInTransaction()}:outerOpen=${!outerSettled}`);
+                return { document: { id: 'ver-1', document_id: 'doc-1' }, fieldCount: 1 };
+            });
+            const definition = { ...minimalCollection, hooks: { afterSystemFieldsChange, afterUpdate } };
+            await updateDocumentWithPatches(buildCtx(db, definition), {
+                expectedRevision: 1,
+                documentId: 'doc-1',
+                patches: [{ kind: 'field.set', path: 'title', value: 'New' }],
+                availableLocales: ['en', 'fr'],
+            });
+            // Both writes run inside the same guarded unit of work, so the locale
+            // change and the new content version commit or roll back together.
+            expect(order).toEqual(['locales:true', 'version:true:outerOpen=true']);
+            expect(afterSystemFieldsChange).toHaveBeenCalledOnce();
+            expect(afterUpdate).toHaveBeenCalledOnce();
+        });
+        it('fails a combined save as a whole when the content version write fails', async () => {
+            const afterSystemFieldsChange = vi.fn();
+            const afterUpdate = vi.fn();
+            const { db, getDocumentById, getDocumentSystemFieldsForUpdate, createDocumentVersion, auditAppend, } = createMockDb();
+            getDocumentById.mockResolvedValue({
+                document_version_id: 'previous',
+                fields: { title: 'Old' },
+            });
+            getDocumentSystemFieldsForUpdate.mockResolvedValue({
+                path: 'doc',
+                source_locale: 'en',
+                availableLocales: ['en'],
+            });
+            createDocumentVersion.mockRejectedValue(new Error('version write failed'));
+            const auditInTransaction = [];
+            auditAppend.mockImplementation(async () => {
+                auditInTransaction.push(db.revisions.isInTransaction());
+                return { id: 'audit-1' };
+            });
+            const definition = { ...minimalCollection, hooks: { afterSystemFieldsChange, afterUpdate } };
+            await expect(updateDocumentWithPatches(buildCtx(db, definition), {
+                expectedRevision: 1,
+                documentId: 'doc-1',
+                patches: [{ kind: 'field.set', path: 'title', value: 'New' }],
+                availableLocales: ['en', 'fr'],
+            })).rejects.toThrow('version write failed');
+            // The locale write and its audit row ran inside the failed unit of work,
+            // which the adapter rolls back; no committed-change hook reports it.
+            expect(db.commands.documents.setDocumentAvailableLocales).toHaveBeenCalledOnce();
+            expect(auditInTransaction.every(Boolean)).toBe(true);
+            expect(afterSystemFieldsChange).not.toHaveBeenCalled();
+            expect(afterUpdate).not.toHaveBeenCalled();
+        });
         it('classifies a post-patch afterUpdate failure without replaying the version write', async () => {
             const afterUpdate = vi
                 .fn()
@@ -2189,6 +2266,64 @@ describe('Document lifecycle service', () => {
                 currentPath: 'new-slug',
             }));
         });
+        it('re-runs reconciliation on a no-op locale-only retry after a committed hook failure', async () => {
+            const { db, getDocumentSystemFieldsForUpdate, auditAppend } = createMockDb();
+            setupDoc(getDocumentSystemFieldsForUpdate);
+            const afterSystemFieldsChange = vi
+                .fn()
+                .mockRejectedValueOnce(new Error('search unavailable'))
+                .mockResolvedValue(undefined);
+            const ctx = buildCtx(db, {
+                ...minimalCollection,
+                hooks: { afterSystemFieldsChange },
+            });
+            await expect(updateDocumentSystemFields(ctx, {
+                expectedRevision: 1,
+                documentId: 'doc-1',
+                availableLocales: ['en', 'fr'],
+            })).rejects.toMatchObject({
+                code: ErrorCodes.DOCUMENT_HOOK_COMMITTED,
+                details: { revision: 2 },
+            });
+            // The committed locale set stays; the retry writes nothing new.
+            setupDoc(getDocumentSystemFieldsForUpdate, { availableLocales: ['en', 'fr'] });
+            const retry = await updateDocumentSystemFields(ctx, {
+                expectedRevision: 2,
+                documentId: 'doc-1',
+                availableLocales: ['en', 'fr'],
+                reconcile: true,
+            });
+            expect(retry).toMatchObject({ changed: false, reconciliation: true });
+            expect(db.commands.documents.setDocumentAvailableLocales).toHaveBeenCalledOnce();
+            expect(db.commands.documents.createDocumentVersion).not.toHaveBeenCalled();
+            expect(auditAppend).toHaveBeenCalledOnce();
+            expect(afterSystemFieldsChange).toHaveBeenCalledTimes(2);
+            expect(afterSystemFieldsChange).toHaveBeenLastCalledWith(expect.objectContaining({
+                requested: { path: false, availableLocales: true },
+                changed: { path: false, availableLocales: false },
+                reconciliation: true,
+                previousAvailableLocales: ['en', 'fr'],
+                currentAvailableLocales: ['en', 'fr'],
+            }));
+        });
+        it('does not invoke the hook for a plain no-op locale write', async () => {
+            const { db, getDocumentSystemFieldsForUpdate, auditAppend } = createMockDb();
+            setupDoc(getDocumentSystemFieldsForUpdate, { availableLocales: ['en', 'fr'] });
+            const afterSystemFieldsChange = vi.fn();
+            const ctx = buildCtx(db, {
+                ...minimalCollection,
+                hooks: { afterSystemFieldsChange },
+            });
+            const result = await updateDocumentSystemFields(ctx, {
+                expectedRevision: 1,
+                documentId: 'doc-1',
+                availableLocales: ['fr', 'en', 'fr'],
+            });
+            expect(result).toMatchObject({ changed: false });
+            expect(db.commands.documents.setDocumentAvailableLocales).not.toHaveBeenCalled();
+            expect(auditAppend).not.toHaveBeenCalled();
+            expect(afterSystemFieldsChange).not.toHaveBeenCalled();
+        });
         it('uses the locked transaction snapshot for audit and invalidation payloads', async () => {
             const { db, getDocumentById, getDocumentSystemFieldsForUpdate, auditAppend } = createMockDb();
             getDocumentById.mockResolvedValue({

package/dist/services/populate.d.ts

@@ -129,7 +129,7 @@
  *     added).
  */
 import { type RequestContext } from '@byline/auth';
-import type { CollectionDefinition, FieldSet, IDbAdapter, PopulateFieldSpec, PopulateSpec, ReadContext, ReadMode, RelatedDocumentValue, RelationField } from '../@types/index.js';
+import type { CollectionDefinition, FieldSet, IDbAdapter, LocaleVisibility, PopulateFieldSpec, PopulateSpec, ReadContext, ReadMode, RelatedDocumentValue, RelationField } from '../@types/index.js';
 export type { ReadContext } from '../@types/index.js';
 /** Build a fresh ReadContext. */
 export declare function createReadContext(overrides?: Partial<ReadContext>): ReadContext;
@@ -170,6 +170,14 @@ export interface PopulateOptions {
      * its last published version rather than leaking a draft.
      */
     readMode?: ReadMode;
+    /**
+     * Locale visibility forwarded to every target batch fetch and rich-text
+     * read. Each target resolves eligibility under its own collection opt-in,
+     * source locale, completeness ledger and checkbox set, so a parent's
+     * checked locale never authorizes a target's. Omitted ⇒ derived from
+     * `readMode` (`'published'` → `'public'`, otherwise `'editorial'`).
+     */
+    localeVisibility?: LocaleVisibility;
     /**
      * Request-scoped recursion guard. Omit to create a fresh context for
      * this top-level call. Threaded through by future read-side hooks to

package/dist/services/populate.js

@@ -132,6 +132,7 @@ import { createRequestContext } from '@byline/auth';
 import { compileBeforeReadFilters } from '../auth/apply-before-read.js';
 import { assertActorCanPerform } from '../auth/assert-actor-can-perform.js';
 import { ERR_READ_BUDGET_EXCEEDED } from '../lib/errors.js';
+import { resolveLocaleVisibility } from '../storage/locale-resolution.js';
 import { applyAfterRead } from './document-read.js';
 import { createRichTextDocumentReader, populateRichTextFields } from './richtext-populate.js';
 import { walkFieldTree } from './walk-field-tree.js';
@@ -161,6 +162,7 @@ export async function populateDocuments(opts) {
     const securityDomain = opts.securityDomain ?? {};
     const operationRequestContext = opts.requestContext ??
         createRequestContext({ readMode: opts.readMode ?? 'any', locale: opts.locale });
+    const localeVisibility = opts.localeVisibility ?? resolveLocaleVisibility(opts.readMode ?? 'any');
     const populate = opts.populate;
     const requestedDepth = opts.depth ?? (populate !== undefined ? 1 : 0);
     const maxDepth = Math.max(0, Math.min(requestedDepth, ctx.maxDepth));
@@ -248,6 +250,7 @@ export async function populateDocuments(opts) {
                     fields: selectList,
                     readMode: opts.readMode,
                     filters: targetFilters,
+                    localeVisibility,
                 });
             }
             const byId = new Map();
@@ -333,6 +336,7 @@ export async function populateDocuments(opts) {
                                 requestContext: opts.requestContext,
                                 readContext: ctx,
                                 readMode: opts.readMode ?? 'any',
+                                localeVisibility,
                                 locale: opts.locale,
                                 bypassBeforeRead: opts.bypassBeforeRead,
                                 richTextPopulate: opts.richTextPopulate,

package/dist/services/richtext-populate.d.ts

@@ -26,7 +26,7 @@
 import type { RequestContext } from '@byline/auth';
 import { type FieldSet, type RichTextField, type RichTextPopulateFn, type RichTextReadDocumentsFn } from '../@types/field-types.js';
 import type { CollectionDefinition } from '../@types/collection-types.js';
-import type { IDbAdapter, ReadContext, ReadMode } from '../@types/index.js';
+import type { IDbAdapter, LocaleVisibility, ReadContext, ReadMode } from '../@types/index.js';
 /**
  * One rich-text leaf yielded by `collectRichTextLeaves`. The walker hands
  * back a reference to the *parent container* (`parent[key]`) rather than
@@ -87,6 +87,12 @@ export declare function createRichTextDocumentReader(options: {
     requestContext: RequestContext;
     readContext: ReadContext;
     readMode: ReadMode;
+    /**
+     * Locale visibility for the batch fetch. Omitted ⇒ derived from `readMode`.
+     * Part of the materialization cache key, so a result read under one
+     * visibility is never reused for a read under another.
+     */
+    localeVisibility?: LocaleVisibility;
     locale?: string;
     bypassBeforeRead?: true;
     /** Private cache domain explicitly shared with the originating client read. */

package/dist/services/richtext-populate.js

@@ -10,6 +10,7 @@ import { bindReadContextAuthority, compileBeforeReadFilters } from '../auth/appl
 import { assertActorCanPerform } from '../auth/assert-actor-can-perform.js';
 import { resolveReadContextRoot } from '../auth/read-context-scope.js';
 import { ERR_READ_BUDGET_EXCEEDED, ERR_VALIDATION } from '../lib/errors.js';
+import { resolveLocaleVisibility } from '../storage/locale-resolution.js';
 import { applyAfterRead } from './document-read.js';
 import { walkFieldTree } from './walk-field-tree.js';
 /**
@@ -74,6 +75,7 @@ export async function populateRichTextFields(options) {
 /** Build the secure batch reader exposed to editor-agnostic adapters. */
 export function createRichTextDocumentReader(options) {
     const { db, collections, requestContext, readContext, readMode, locale, bypassBeforeRead, richTextPopulate, } = options;
+    const localeVisibility = options.localeVisibility ?? resolveLocaleVisibility(readMode);
     const securityDomain = options.securityDomain ?? {};
     const state = getRichTextReaderState(readContext);
     const read = async ({ collectionPath, documentIds, fields }) => {
@@ -116,7 +118,7 @@ export function createRichTextDocumentReader(options) {
         const resultById = new Map();
         const idsToFetch = [];
         for (const documentId of new Set(documentIds)) {
-            const key = richTextMaterializationKey(collectionId, documentId, requestContext.requestId, locale, readMode, projection);
+            const key = richTextMaterializationKey(collectionId, documentId, requestContext.requestId, locale, readMode, localeVisibility, projection);
             if (state.cache.has(key)) {
                 const cached = state.cache.get(key);
                 if (cached != null)
@@ -132,6 +134,7 @@ export function createRichTextDocumentReader(options) {
                 document_ids: idsToFetch,
                 fields,
                 readMode,
+                localeVisibility,
                 locale,
                 filters: filters && filters.length > 0 ? filters : undefined,
             }));
@@ -139,7 +142,7 @@ export function createRichTextDocumentReader(options) {
                 .filter((doc) => typeof doc.document_id === 'string')
                 .map((doc) => [doc.document_id, doc]));
             for (const documentId of idsToFetch) {
-                const materializationKey = richTextMaterializationKey(collectionId, documentId, requestContext.requestId, locale, readMode, projection);
+                const materializationKey = richTextMaterializationKey(collectionId, documentId, requestContext.requestId, locale, readMode, localeVisibility, projection);
                 // Earlier items in this batch may recursively populate a later target.
                 // Honour that completed/active state rather than reprocessing the stale
                 // raw row captured by the outer batch and overwriting its redacted cache.
@@ -219,8 +222,8 @@ function getRichTextReaderState(readContext) {
     richTextReaderStates.set(root, state);
     return state;
 }
-function richTextMaterializationKey(collectionId, documentId, requestId, locale, readMode, projection) {
-    return `${collectionId}:${documentId}:${requestId}:${locale ?? 'all'}:${readMode}:${projection}`;
+function richTextMaterializationKey(collectionId, documentId, requestId, locale, readMode, localeVisibility, projection) {
+    return `${collectionId}:${documentId}:${requestId}:${locale ?? 'all'}:${readMode}:${localeVisibility}:${projection}`;
 }
 // ---------------------------------------------------------------------------
 // Boot-time validation

package/dist/storage/index.d.ts

@@ -8,6 +8,7 @@
 export { fingerprintCollection } from './collection-fingerprint.js';
 export { assertDocumentVersionParent, type DocumentVersionParentAssertion, type DocumentVersionParentConflictReason, } from './document-version-parent.js';
 export { ALL_STORE_TYPES, type FieldStoreKind, type FieldStoreMapping, fieldTypeToStore, fieldTypeToStoreType, type StoreType, } from './field-store-map.js';
+export { deriveVersionLocaleLedger, resolveLocaleVisibility, resolveReadLocale, type VersionLocaleLedger, } from './locale-resolution.js';
 export { flattenFieldSetData } from './storage-flatten.js';
 export { extractFlattenedFieldValue, type RestoreResult, restoreFieldSetData, } from './storage-restore.js';
 export { resolveStoreTypes } from './storage-utils.js';

package/dist/storage/index.js

@@ -8,6 +8,7 @@
 export { fingerprintCollection } from './collection-fingerprint.js';
 export { assertDocumentVersionParent, } from './document-version-parent.js';
 export { ALL_STORE_TYPES, fieldTypeToStore, fieldTypeToStoreType, } from './field-store-map.js';
+export { deriveVersionLocaleLedger, resolveLocaleVisibility, resolveReadLocale, } from './locale-resolution.js';
 export { flattenFieldSetData } from './storage-flatten.js';
 export { extractFlattenedFieldValue, restoreFieldSetData, } from './storage-restore.js';
 export { resolveStoreTypes } from './storage-utils.js';

package/dist/storage/locale-resolution.d.ts

@@ -0,0 +1,76 @@
+/**
+ * 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 type { LocaleVisibility, MissingLocalePolicy, ReadMode } from '../@types/index.js';
+import type { FlattenedFieldValue } from './storage-row-types.js';
+/**
+ * One version's entry in the `byline_document_version_locales` ledger: the
+ * concrete locales its content is complete in, or `localeAgnostic` when the
+ * version carries only the `'all'` sentinel (no localized content).
+ */
+export interface VersionLocaleLedger {
+    availableLocales: readonly string[];
+    localeAgnostic: boolean;
+}
+/**
+ * Derive a completeness ledger from loaded store rows, using the same rule the
+ * write path records: a locale is complete when it covers every localized field
+ * path the source locale has; a version with no localized rows is
+ * locale-agnostic. Used only for versions written before the ledger existed and
+ * not yet backfilled. It can only see the rows a read loaded, so a projected
+ * read of such a version may still misjudge completeness.
+ */
+export declare function deriveVersionLocaleLedger(rows: readonly FlattenedFieldValue[], sourceLocale: string): VersionLocaleLedger;
+/**
+ * The per-document facts a locale-eligibility decision needs. `ledger` is the
+ * selected version's completeness ledger; `availableLocales` is the document's
+ * saved editorial checkbox set; `advertiseLocales` is the collection's opt-in
+ * to that control.
+ */
+export interface LocaleEligibility {
+    visibility: LocaleVisibility;
+    sourceLocale: string;
+    ledger: VersionLocaleLedger;
+    advertiseLocales: boolean;
+    availableLocales: readonly string[];
+}
+/**
+ * The locale visibility a read uses: an explicit `localeVisibility` wins;
+ * otherwise `status: 'any'` implies `'editorial'` and an omitted or
+ * `'published'` status implies `'public'`. Resolving visibility never grants
+ * access; callers still authorize `'editorial'` separately.
+ */
+export declare function resolveLocaleVisibility(status: ReadMode | undefined, explicit?: LocaleVisibility): LocaleVisibility;
+/** The outcome of one read's language decision for one document version. */
+export interface ReadLocaleDecision {
+    /** The locale to restore fields in; `undefined` for a multi-locale (`'all'`) read. */
+    restoreLocale: string | undefined;
+    /** The `resolvedLocale` read metadata: the locale the fields were selected in, or `null`. */
+    resolvedLocale: string | null;
+    /** `true` when localized values must be withheld and only non-localized values returned. */
+    withholdLocalized: boolean;
+}
+/**
+ * Decide, for one document version, which locale a read restores, what it
+ * reports as `resolvedLocale`, and whether localized values must be withheld.
+ * Shared by every storage adapter so the language decision is identical across
+ * engines and is made from the whole version, before any field projection.
+ *
+ *   - `locale: 'all'` restores locale maps and reports `null`.
+ *   - A locale-agnostic version restores the requested locale and reports `null`.
+ *   - `'fallback'` restores and reports the first eligible chain entry.
+ *   - `'omit'`, `'empty'` and an omitted policy are exact: an eligible locale is
+ *     restored and reported. Under `'public'` visibility an ineligible locale
+ *     withholds localized values and reports `null`; under `'editorial'` the
+ *     exact locale is restored even when partial.
+ */
+export declare function resolveReadLocale(params: {
+    locale: string;
+    chain: readonly string[];
+    onMissingLocale: MissingLocalePolicy | undefined;
+    eligibility: LocaleEligibility;
+}): ReadLocaleDecision;

package/dist/storage/locale-resolution.js

@@ -0,0 +1,122 @@
+/**
+ * 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
+ */
+/**
+ * Derive a completeness ledger from loaded store rows, using the same rule the
+ * write path records: a locale is complete when it covers every localized field
+ * path the source locale has; a version with no localized rows is
+ * locale-agnostic. Used only for versions written before the ledger existed and
+ * not yet backfilled. It can only see the rows a read loaded, so a projected
+ * read of such a version may still misjudge completeness.
+ */
+export function deriveVersionLocaleLedger(rows, sourceLocale) {
+    const pathsByLocale = new Map();
+    for (const row of rows) {
+        if (row.locale === 'all' || row.field_type === 'meta')
+            continue;
+        let paths = pathsByLocale.get(row.locale);
+        if (paths == null) {
+            paths = new Set();
+            pathsByLocale.set(row.locale, paths);
+        }
+        paths.add(row.field_path.join('.'));
+    }
+    if (pathsByLocale.size === 0)
+        return { availableLocales: [], localeAgnostic: true };
+    const canonical = pathsByLocale.get(sourceLocale) ?? new Set();
+    const availableLocales = [];
+    for (const [locale, paths] of pathsByLocale) {
+        let covers = true;
+        for (const path of canonical) {
+            if (!paths.has(path)) {
+                covers = false;
+                break;
+            }
+        }
+        if (covers)
+            availableLocales.push(locale);
+    }
+    return { availableLocales, localeAgnostic: false };
+}
+/**
+ * Whether `locale` may be delivered for one document version.
+ *
+ *   - A locale-agnostic version renders identically everywhere: always eligible.
+ *   - The source locale is always eligible, whatever its checkbox says.
+ *   - Any other locale must be complete on the selected version.
+ *   - Under `'public'` visibility in a collection with `advertiseLocales`, it
+ *     must also be checked in the document's editorial set. An empty set
+ *     authorizes no additional translation.
+ */
+function isLocaleEligible(locale, eligibility) {
+    const { visibility, sourceLocale, ledger, advertiseLocales, availableLocales } = eligibility;
+    if (ledger.localeAgnostic)
+        return true;
+    if (locale === sourceLocale)
+        return true;
+    if (!ledger.availableLocales.includes(locale))
+        return false;
+    if (visibility === 'editorial' || !advertiseLocales)
+        return true;
+    return availableLocales.includes(locale);
+}
+/**
+ * Walk `chain` (`[requested, …, floor]`) and return the first locale eligible
+ * under `eligibility`. Every candidate must pass, so a withheld intermediate
+ * locale can never be selected. The floor is terminal and returned when no
+ * earlier candidate qualifies.
+ */
+function resolveEligibleLocale(chain, eligibility) {
+    for (const candidate of chain) {
+        if (isLocaleEligible(candidate, eligibility))
+            return candidate;
+    }
+    // biome-ignore lint/style/noNonNullAssertion: a locale chain always has a floor
+    return chain[chain.length - 1];
+}
+/**
+ * The locale visibility a read uses: an explicit `localeVisibility` wins;
+ * otherwise `status: 'any'` implies `'editorial'` and an omitted or
+ * `'published'` status implies `'public'`. Resolving visibility never grants
+ * access; callers still authorize `'editorial'` separately.
+ */
+export function resolveLocaleVisibility(status, explicit) {
+    if (explicit != null)
+        return explicit;
+    return status === 'any' ? 'editorial' : 'public';
+}
+/**
+ * Decide, for one document version, which locale a read restores, what it
+ * reports as `resolvedLocale`, and whether localized values must be withheld.
+ * Shared by every storage adapter so the language decision is identical across
+ * engines and is made from the whole version, before any field projection.
+ *
+ *   - `locale: 'all'` restores locale maps and reports `null`.
+ *   - A locale-agnostic version restores the requested locale and reports `null`.
+ *   - `'fallback'` restores and reports the first eligible chain entry.
+ *   - `'omit'`, `'empty'` and an omitted policy are exact: an eligible locale is
+ *     restored and reported. Under `'public'` visibility an ineligible locale
+ *     withholds localized values and reports `null`; under `'editorial'` the
+ *     exact locale is restored even when partial.
+ */
+export function resolveReadLocale(params) {
+    const { locale, chain, onMissingLocale, eligibility } = params;
+    if (locale === 'all') {
+        return { restoreLocale: undefined, resolvedLocale: null, withholdLocalized: false };
+    }
+    if (eligibility.ledger.localeAgnostic) {
+        return { restoreLocale: locale, resolvedLocale: null, withholdLocalized: false };
+    }
+    if (onMissingLocale === 'fallback') {
+        const selected = resolveEligibleLocale(chain, eligibility);
+        return { restoreLocale: selected, resolvedLocale: selected, withholdLocalized: false };
+    }
+    if (eligibility.visibility === 'public' && !isLocaleEligible(locale, eligibility)) {
+        return { restoreLocale: locale, resolvedLocale: null, withholdLocalized: true };
+    }
+    return { restoreLocale: locale, resolvedLocale: locale, withholdLocalized: false };
+}

package/dist/storage/locale-resolution.test.node.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 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
+ */
+export {};

package/dist/storage/locale-resolution.test.node.js

@@ -0,0 +1,245 @@
+/**
+ * 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 { describe, expect, it } from 'vitest';
+import { deriveVersionLocaleLedger, resolveLocaleVisibility, resolveReadLocale, } from './locale-resolution.js';
+// The eligibility rule and the fallback walk are private to the module; these
+// helpers observe them through `resolveReadLocale`, the only adapter-facing
+// entry point. A locale is eligible exactly when a fallback read toward the
+// source selects it, and the walk's result is the locale that read restores.
+function isLocaleEligible(locale, eligibility) {
+    const chain = locale === eligibility.sourceLocale ? [locale] : [locale, eligibility.sourceLocale];
+    return (resolveReadLocale({ locale, chain, onMissingLocale: 'fallback', eligibility }).restoreLocale ===
+        locale);
+}
+function resolveEligibleLocale(chain, eligibility) {
+    const decision = resolveReadLocale({
+        locale: chain[0],
+        chain,
+        onMissingLocale: 'fallback',
+        eligibility,
+    });
+    return decision.restoreLocale;
+}
+describe('deriveVersionLocaleLedger', () => {
+    const row = (locale, path, field_type = 'text') => ({ locale, field_path: path.split('.'), field_type });
+    it('records the locales that cover every source-locale localized path', () => {
+        const ledger = deriveVersionLocaleLedger([
+            row('en', 'title'),
+            row('en', 'body'),
+            row('de', 'title'),
+            row('de', 'body'),
+            row('fr', 'title'),
+            row('all', 'sku'),
+            row('all', 'content.0', 'meta'),
+        ], 'en');
+        expect(ledger).toEqual({ availableLocales: ['en', 'de'], localeAgnostic: false });
+    });
+    it('marks a version with no localized rows as locale-agnostic', () => {
+        expect(deriveVersionLocaleLedger([row('all', 'sku')], 'en')).toEqual({
+            availableLocales: [],
+            localeAgnostic: true,
+        });
+    });
+});
+describe('isLocaleEligible', () => {
+    const base = {
+        visibility: 'public',
+        sourceLocale: 'en',
+        ledger: { availableLocales: ['en', 'es', 'de'], localeAgnostic: false },
+        advertiseLocales: true,
+        availableLocales: ['de'],
+    };
+    it('public: a complete and checked translation is eligible', () => {
+        expect(isLocaleEligible('de', base)).toBe(true);
+    });
+    it('public: a complete but unchecked translation is not eligible', () => {
+        expect(isLocaleEligible('es', base)).toBe(false);
+    });
+    it('public: a checked but incomplete translation is not eligible', () => {
+        expect(isLocaleEligible('fr', { ...base, availableLocales: ['fr'] })).toBe(false);
+    });
+    it('public: the source is eligible even when its checkbox is off', () => {
+        expect(isLocaleEligible('en', { ...base, availableLocales: [] })).toBe(true);
+    });
+    it('public: an empty advertised set authorizes no additional translation', () => {
+        expect(isLocaleEligible('de', { ...base, availableLocales: [] })).toBe(false);
+    });
+    it('public: a collection without advertiseLocales is gated by completeness alone', () => {
+        const optOut = { ...base, advertiseLocales: false, availableLocales: [] };
+        expect(isLocaleEligible('es', optOut)).toBe(true);
+        expect(isLocaleEligible('fr', optOut)).toBe(false);
+    });
+    it('a locale-agnostic version is eligible in every locale', () => {
+        const agnostic = { ...base, ledger: { availableLocales: [], localeAgnostic: true } };
+        expect(isLocaleEligible('fr', agnostic)).toBe(true);
+    });
+    it('editorial: a complete but unchecked translation is eligible', () => {
+        expect(isLocaleEligible('es', { ...base, visibility: 'editorial' })).toBe(true);
+    });
+    it('editorial: completeness is still required', () => {
+        expect(isLocaleEligible('fr', { ...base, visibility: 'editorial' })).toBe(false);
+    });
+});
+describe('resolveEligibleLocale', () => {
+    const base = {
+        visibility: 'public',
+        sourceLocale: 'en',
+        ledger: { availableLocales: ['en', 'es', 'es-MX'], localeAgnostic: false },
+        advertiseLocales: true,
+        availableLocales: [],
+    };
+    it('public: an unchecked translation falls back to the source', () => {
+        expect(resolveEligibleLocale(['es', 'en'], base)).toBe('en');
+    });
+    it('editorial: the same unchecked translation is selected', () => {
+        expect(resolveEligibleLocale(['es', 'en'], { ...base, visibility: 'editorial' })).toBe('es');
+    });
+    it('public: a withheld intermediate candidate is skipped', () => {
+        // Named fallback chains are not configurable yet; this pins that every
+        // candidate must satisfy the policy if they are added later.
+        const eligibility = { ...base, availableLocales: ['es'] };
+        expect(resolveEligibleLocale(['es-MX', 'es', 'en'], eligibility)).toBe('es');
+        expect(resolveEligibleLocale(['es-MX', 'es', 'en'], base)).toBe('en');
+    });
+    it('returns the floor when nothing earlier qualifies', () => {
+        expect(resolveEligibleLocale(['fr', 'en'], base)).toBe('en');
+    });
+});
+describe('resolveLocaleVisibility', () => {
+    it('defaults to public for an omitted or published status', () => {
+        expect(resolveLocaleVisibility(undefined)).toBe('public');
+        expect(resolveLocaleVisibility('published')).toBe('public');
+    });
+    it('defaults to editorial for status any', () => {
+        expect(resolveLocaleVisibility('any')).toBe('editorial');
+    });
+    it('an explicit value wins over the status default', () => {
+        expect(resolveLocaleVisibility('published', 'editorial')).toBe('editorial');
+        expect(resolveLocaleVisibility('any', 'public')).toBe('public');
+    });
+});
+describe('resolveReadLocale — the seven resolvedLocale result types', () => {
+    const eligibility = (overrides = {}) => ({
+        visibility: 'public',
+        sourceLocale: 'en',
+        // Spanish complete but unchecked; German partial (not in the ledger).
+        ledger: { availableLocales: ['en', 'es'], localeAgnostic: false },
+        advertiseLocales: true,
+        availableLocales: [],
+        ...overrides,
+    });
+    const chain = (locale) => (locale === 'en' ? ['en'] : [locale, 'en']);
+    it('R1: fallback reports the selected permitted locale, including the source', () => {
+        expect(resolveReadLocale({
+            locale: 'es',
+            chain: chain('es'),
+            onMissingLocale: 'fallback',
+            eligibility: eligibility({ availableLocales: ['es'] }),
+        })).toEqual({ restoreLocale: 'es', resolvedLocale: 'es', withholdLocalized: false });
+        expect(resolveReadLocale({
+            locale: 'es',
+            chain: chain('es'),
+            onMissingLocale: 'fallback',
+            eligibility: eligibility(),
+        })).toEqual({ restoreLocale: 'en', resolvedLocale: 'en', withholdLocalized: false });
+        expect(resolveReadLocale({
+            locale: 'es',
+            chain: chain('es'),
+            onMissingLocale: 'fallback',
+            eligibility: eligibility({ visibility: 'editorial' }),
+        })).toEqual({ restoreLocale: 'es', resolvedLocale: 'es', withholdLocalized: false });
+    });
+    it('R2: omit reports the requested locale', () => {
+        expect(resolveReadLocale({
+            locale: 'es',
+            chain: chain('es'),
+            onMissingLocale: 'omit',
+            eligibility: eligibility({ availableLocales: ['es'] }),
+        })).toEqual({ restoreLocale: 'es', resolvedLocale: 'es', withholdLocalized: false });
+    });
+    it('R3: public empty with an eligible locale reports it, with no fallback', () => {
+        expect(resolveReadLocale({
+            locale: 'es',
+            chain: chain('es'),
+            onMissingLocale: 'empty',
+            eligibility: eligibility({ availableLocales: ['es'] }),
+        })).toEqual({ restoreLocale: 'es', resolvedLocale: 'es', withholdLocalized: false });
+    });
+    it('R4: public empty with an unavailable translation withholds values and reports null', () => {
+        // Complete but unchecked.
+        expect(resolveReadLocale({
+            locale: 'es',
+            chain: chain('es'),
+            onMissingLocale: 'empty',
+            eligibility: eligibility(),
+        })).toEqual({ restoreLocale: 'es', resolvedLocale: null, withholdLocalized: true });
+        // Checked but incomplete.
+        expect(resolveReadLocale({
+            locale: 'de',
+            chain: chain('de'),
+            onMissingLocale: 'empty',
+            eligibility: eligibility({ availableLocales: ['de'] }),
+        })).toEqual({ restoreLocale: 'de', resolvedLocale: null, withholdLocalized: true });
+        // An omitted policy is exact, like empty.
+        expect(resolveReadLocale({
+            locale: 'es',
+            chain: chain('es'),
+            onMissingLocale: undefined,
+            eligibility: eligibility(),
+        }).withholdLocalized).toBe(true);
+    });
+    it('R4: public empty still serves the source even when its checkbox is off', () => {
+        expect(resolveReadLocale({
+            locale: 'en',
+            chain: chain('en'),
+            onMissingLocale: 'empty',
+            eligibility: eligibility(),
+        })).toEqual({ restoreLocale: 'en', resolvedLocale: 'en', withholdLocalized: false });
+    });
+    it('R5: editorial empty reports the requested locale even when partial', () => {
+        expect(resolveReadLocale({
+            locale: 'de',
+            chain: chain('de'),
+            onMissingLocale: 'empty',
+            eligibility: eligibility({ visibility: 'editorial' }),
+        })).toEqual({ restoreLocale: 'de', resolvedLocale: 'de', withholdLocalized: false });
+    });
+    it('R6: a multi-locale read reports null and restores locale maps', () => {
+        expect(resolveReadLocale({
+            locale: 'all',
+            chain: ['all'],
+            onMissingLocale: 'empty',
+            eligibility: eligibility({ visibility: 'editorial' }),
+        })).toEqual({ restoreLocale: undefined, resolvedLocale: null, withholdLocalized: false });
+    });
+    it('R7: a locale-agnostic version reports null under every policy', () => {
+        const agnostic = eligibility({ ledger: { availableLocales: [], localeAgnostic: true } });
+        for (const onMissingLocale of ['fallback', 'omit', 'empty', undefined]) {
+            expect(resolveReadLocale({
+                locale: 'es',
+                chain: chain('es'),
+                onMissingLocale,
+                eligibility: agnostic,
+            })).toEqual({ restoreLocale: 'es', resolvedLocale: null, withholdLocalized: false });
+        }
+    });
+    it('a non-advertised collection withholds an incomplete translation publicly', () => {
+        expect(resolveReadLocale({
+            locale: 'de',
+            chain: chain('de'),
+            onMissingLocale: 'empty',
+            eligibility: eligibility({ advertiseLocales: false }),
+        }).withholdLocalized).toBe(true);
+        expect(resolveReadLocale({
+            locale: 'es',
+            chain: chain('es'),
+            onMissingLocale: 'empty',
+            eligibility: eligibility({ advertiseLocales: false }),
+        })).toEqual({ restoreLocale: 'es', resolvedLocale: 'es', withholdLocalized: false });
+    });
+});

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/core",
   "private": false,
   "license": "MPL-2.0",
-  "version": "6.5.0",
+  "version": "6.7.0",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -87,7 +87,7 @@
     "sharp": "^0.35.4",
     "uuid": "^14.0.2",
     "zod": "^4.6.5",
-    "@byline/auth": "6.5.0"
+    "@byline/auth": "6.7.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.14",