@byline/core 6.6.0 → 6.7.1

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.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/config/resolve-item-view-columns.test.node.js

@@ -0,0 +1,30 @@
+/**
+ * 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 { resolveItemViewColumns } from './config.js';
+const itemViewCols = [{ fieldName: 'title', label: 'Title' }];
+const pickerCols = [{ fieldName: 'name', label: 'Name' }];
+const cfg = (over) => ({ slug: 'x', ...over });
+describe('resolveItemViewColumns', () => {
+    it('returns itemView when present', () => {
+        expect(resolveItemViewColumns(cfg({ itemView: itemViewCols }))).toBe(itemViewCols);
+    });
+    it('falls back to the deprecated picker alias', () => {
+        expect(resolveItemViewColumns(cfg({ picker: pickerCols }))).toBe(pickerCols);
+    });
+    it('prefers itemView over picker when both are present', () => {
+        expect(resolveItemViewColumns(cfg({ itemView: itemViewCols, picker: pickerCols }))).toBe(itemViewCols);
+    });
+    it('returns undefined when neither is set', () => {
+        expect(resolveItemViewColumns(cfg({}))).toBeUndefined();
+    });
+    it('tolerates null / undefined config', () => {
+        expect(resolveItemViewColumns(null)).toBeUndefined();
+        expect(resolveItemViewColumns(undefined)).toBeUndefined();
+    });
+});

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';