@byline/db-mysql 6.5.0 → 6.7.0

package/dist/modules/storage/storage-queries.d.ts

@@ -22,7 +22,7 @@
  * `getDocumentSystemFieldsForUpdate`. `DocumentQueries` now declares
  * `implements IDocumentQueries`.
  */
-import type { CollectionDefinition, DocumentFilter, FieldFilterOperator, FieldSort, FlattenedStore, ICollectionQueries, IDocumentQueries, MissingLocalePolicy, ReadMode } from '@byline/core';
+import type { CollectionDefinition, DocumentFilter, FieldFilterOperator, FieldSort, FlattenedStore, ICollectionQueries, IDocumentQueries, LocaleVisibility, MissingLocalePolicy, ReadMode } from '@byline/core';
 import type { MySql2Database } from 'drizzle-orm/mysql2';
 import { DocumentPublishScheduleQueries } from './publish-schedules.js';
 import type * as schema from '../../database/schema/index.js';
@@ -138,16 +138,55 @@ export declare class DocumentQueries implements IDocumentQueries {
      */
     private buildLocaleChain;
     /**
-     * Build the `onMissingLocale: 'omit'` availability gate — an EXISTS against
-     * the version-locale ledger (`byline_document_version_locales`) that keeps
-     * only documents available in the requested locale. The `'all'` sentinel row
-     * covers locale-agnostic documents (no localized content). Returns `null`
-     * when the gate does not apply — a non-`'omit'` policy (`'empty'` /
-     * `'fallback'` / unset), or the admin sentinel `'all'` read — so callers can
-     * conditionally push it into a WHERE. No dialect-specific SQL — ports
-     * unchanged from pg.
+     * Build the `onMissingLocale: 'omit'` availability gate: keeps only
+     * documents whose selected version may be delivered in the requested
+     * locale, as an EXISTS-based predicate so counting and pagination stay
+     * correct. It mirrors `resolveReadLocale` in `@byline/core`:
+     *
+     *   - the document's source locale is always admitted, with or without a
+     *     ledger row (no checkbox needed);
+     *   - a locale-agnostic version (the ledger's `'all'` sentinel) is admitted;
+     *   - any other locale must be complete in the version's ledger, and under
+     *     `'public'` visibility in a collection with `advertiseLocales` it must
+     *     also be checked in `byline_document_available_locales`.
+     *
+     * Returns `null` when the gate does not apply (a non-`'omit'` policy, or the
+     * admin sentinel `'all'`), so callers can conditionally push it into a WHERE.
      */
     private localeAvailabilityExists;
+    /**
+     * SQL predicate: may `locale` be delivered for this document version? The
+     * SQL twin of `isLocaleEligible` in `@byline/core` — the source is always
+     * eligible; a locale-agnostic version (`'all'` sentinel) is eligible; any
+     * other locale must be complete in the version's ledger and, under
+     * `'public'` visibility in a collection with `advertiseLocales`, checked in
+     * `byline_document_available_locales`.
+     */
+    private localeEligibleSql;
+    /**
+     * SQL for the content locale a document's localized values are matched in,
+     * mirroring `resolveReadLocale`: under `'fallback'` the requested locale
+     * when eligible, otherwise the document's source; under `'omit'` the
+     * requested locale (the gate already guarantees eligibility); under a
+     * public exact read the requested locale when eligible, otherwise `NULL`
+     * (withheld values match nothing and are not replaced by the source); under
+     * an editorial exact read the requested locale, partial or not.
+     */
+    private effectiveLocaleSql;
+    /**
+     * The filter policy for a public-capable tree structural read: only when the
+     * caller supplies `localeVisibility` (editing reads omit it and keep exact
+     * requested-locale matching) and there are predicates to evaluate. Tree
+     * edges stay within one collection, resolved from the anchor document when
+     * the caller has only a document id.
+     */
+    private treeFilterPolicy;
+    /**
+     * Build the filter locale policy for a read: its missing-locale policy and
+     * visibility, plus the `advertiseLocales` flag of the read's collection and
+     * of every collection a relation filter hops into.
+     */
+    private buildFilterLocalePolicy;
     /**
      * Batch-fetch the version-locale availability sets from the
      * `byline_document_version_locales` ledger. For each version returns the
@@ -221,14 +260,6 @@ export declare class DocumentQueries implements IDocumentQueries {
      * the locale priority chain, since it no longer lives on the version row.
      */
     private documentVersionsProjection;
-    /**
-     * Resolve the single effective content locale a version should be restored
-     * in, walking the fallback chain (`[requested, default]`) and returning the
-     * first locale the version is *available* in. Pure JS/data-structure code
-     * — no SQL — ports unchanged from pg. See pg's docblock for the full
-     * phase-1 availability rule.
-     */
-    private resolveEffectiveLocale;
     /**
      * Reconstruct document fields from unified row values using schema-aware
      * restoration. Meta rows (from store_meta) are converted to
@@ -278,7 +309,7 @@ export declare class DocumentQueries implements IDocumentQueries {
      * rather than thrown. This is the admin edit path's "best-effort load"
      * mode for documents written under a previous collection schema.
      */
-    getDocumentById({ collection_id, document_id, locale, reconstruct, readMode, filters, lenient, onMissingLocale, }: {
+    getDocumentById({ collection_id, document_id, locale, reconstruct, readMode, filters, lenient, onMissingLocale, localeVisibility, }: {
         collection_id: string;
         document_id: string;
         locale?: string;
@@ -287,6 +318,7 @@ export declare class DocumentQueries implements IDocumentQueries {
         filters?: DocumentFilter[];
         lenient?: boolean;
         onMissingLocale?: MissingLocalePolicy;
+        localeVisibility?: LocaleVisibility;
     }): Promise<{
         document_version_id: string;
         document_id: string;
@@ -298,6 +330,7 @@ export declare class DocumentQueries implements IDocumentQueries {
         updated_at: Date;
         created_by: string | null;
         fields: any;
+        resolved_locale: string | null;
         availableLocales: string[];
         _availableVersionLocales: string[];
         _localeAgnostic: boolean;
@@ -320,7 +353,7 @@ export declare class DocumentQueries implements IDocumentQueries {
      * current version. See `resolveDocumentIdByPath` for the locale-chain
      * SQL.
      */
-    getDocumentByPath({ collection_id, path, locale, reconstruct, readMode, filters, onMissingLocale, }: {
+    getDocumentByPath({ collection_id, path, locale, reconstruct, readMode, filters, onMissingLocale, localeVisibility, }: {
         collection_id: string;
         path: string;
         locale?: string;
@@ -328,6 +361,7 @@ export declare class DocumentQueries implements IDocumentQueries {
         readMode?: ReadMode;
         filters?: DocumentFilter[];
         onMissingLocale?: MissingLocalePolicy;
+        localeVisibility?: LocaleVisibility;
     }): Promise<{
         document_version_id: string;
         document_id: string;
@@ -339,10 +373,12 @@ export declare class DocumentQueries implements IDocumentQueries {
         updated_at: Date;
         created_by: string | null;
         fields: any;
+        resolved_locale: string | null;
         availableLocales: string[];
         _availableVersionLocales: string[];
         _localeAgnostic: boolean;
     } | {
+        resolved_locale?: undefined;
         availableLocales?: undefined;
         _availableVersionLocales?: undefined;
         _localeAgnostic?: undefined;
@@ -389,13 +425,14 @@ export declare class DocumentQueries implements IDocumentQueries {
      * `store_relation` rows carry `target_document_id` (not version ID), so
      * populate collects those IDs and resolves them here in one round trip.
      */
-    getDocumentsByDocumentIds({ collection_id, document_ids, locale, fields, readMode, filters, }: {
+    getDocumentsByDocumentIds({ collection_id, document_ids, locale, fields, readMode, filters, localeVisibility, }: {
         collection_id: string;
         document_ids: string[];
         locale?: string;
         fields?: string[];
         readMode?: ReadMode;
         filters?: DocumentFilter[];
+        localeVisibility?: LocaleVisibility;
     }): Promise<any[]>;
     /**
      * getDocumentHistory — paginated version history for a document,
@@ -519,12 +556,13 @@ export declare class DocumentQueries implements IDocumentQueries {
      * MySQL has no cast syntax for a UUID-shaped `CHAR(36)` column, and the
      * driver already binds the plain string correctly.
      */
-    getTreeAncestors({ document_id, maxDepth, readMode, locale, filters, }: {
+    getTreeAncestors({ document_id, maxDepth, readMode, locale, filters, localeVisibility, }: {
         document_id: string;
         maxDepth?: number;
         readMode?: ReadMode;
         locale?: string;
         filters?: DocumentFilter[];
+        localeVisibility?: LocaleVisibility;
     }): Promise<Array<{
         document_id: string;
         depth: number;
@@ -553,11 +591,12 @@ export declare class DocumentQueries implements IDocumentQueries {
      * (which returns `[]` for both) conflates. `::uuid` cast dropped, same as
      * `getTreeAncestors`.
      */
-    getTreeParent({ document_id, readMode, locale, filters, }: {
+    getTreeParent({ document_id, readMode, locale, filters, localeVisibility, }: {
         document_id: string;
         readMode?: ReadMode;
         locale?: string;
         filters?: DocumentFilter[];
+        localeVisibility?: LocaleVisibility;
     }): Promise<{
         placed: boolean;
         parentDocumentId: string | null;
@@ -623,13 +662,14 @@ export declare class DocumentQueries implements IDocumentQueries {
      *     reverts to the *connection's* default collation, not the source
      *     column's, so both clauses are required, not just one).
      */
-    getTreeSubtree({ collectionId, rootDocumentId, maxDepth, readMode, locale, filters, }: {
+    getTreeSubtree({ collectionId, rootDocumentId, maxDepth, readMode, locale, filters, localeVisibility, }: {
         collectionId: string;
         rootDocumentId?: string | null;
         maxDepth?: number;
         readMode?: ReadMode;
         locale?: string;
         filters?: DocumentFilter[];
+        localeVisibility?: LocaleVisibility;
     }): Promise<Array<{
         document_id: string;
         parent_document_id: string | null;
@@ -697,7 +737,7 @@ export declare class DocumentQueries implements IDocumentQueries {
      * conditions (status, path) are applied directly on the current_documents
      * view.
      */
-    findDocuments({ collection_id, filters, status, pathFilter, query, sort, orderBy, orderDirection, locale, page, pageSize, fields: requestedFields, readMode, onMissingLocale, }: {
+    findDocuments({ collection_id, filters, status, pathFilter, query, sort, orderBy, orderDirection, locale, page, pageSize, fields: requestedFields, readMode, onMissingLocale, localeVisibility, }: {
         collection_id: string;
         filters?: DocumentFilter[];
         status?: string;
@@ -715,6 +755,7 @@ export declare class DocumentQueries implements IDocumentQueries {
         fields?: string[];
         readMode?: ReadMode;
         onMissingLocale?: MissingLocalePolicy;
+        localeVisibility?: LocaleVisibility;
     }): Promise<{
         documents: any[];
         total: number;

package/dist/modules/storage/storage-queries.js

@@ -22,21 +22,13 @@
  * `getDocumentSystemFieldsForUpdate`. `DocumentQueries` now declares
  * `implements IDocumentQueries`.
  */
-import { ERR_DATABASE, ERR_NOT_FOUND, extractFlattenedFieldValue, getLogger, orderByContentLocale, resolveIdentityField, resolveStoreTypes, restoreFieldSetData, } from '@byline/core';
+import { deriveVersionLocaleLedger, ERR_DATABASE, ERR_NOT_FOUND, extractFlattenedFieldValue, getLogger, orderByContentLocale, resolveIdentityField, resolveReadLocale, resolveStoreTypes, restoreFieldSetData, } from '@byline/core';
 import { and, desc, eq, inArray, isNotNull, isNull, sql } from 'drizzle-orm';
 import { collections, currentDocumentsView, currentPublishedDocumentsView, documentAvailableLocales, documentPaths, documentRelationships, documents, documentVersionLocales, documentVersions, metaStore, } from '../../database/schema/index.js';
 import { DocumentPublishScheduleQueries } from './publish-schedules.js';
 import { normalizeRow } from './normalize-row.js';
 import { allStoreTypes, storeSelectList, storeTableNames, } from './storage-store-manifest.js';
 import { toDate } from './storage-utils.js';
-/** True when `a` contains every member of `b`. */
-function isSuperset(a, b) {
-    for (const item of b) {
-        if (!a.has(item))
-            return false;
-    }
-    return true;
-}
 /**
  * CollectionQueries
  *
@@ -180,24 +172,130 @@ export class DocumentQueries {
         return requested === floor ? [requested] : [requested, floor];
     }
     /**
-     * Build the `onMissingLocale: 'omit'` availability gate — an EXISTS against
-     * the version-locale ledger (`byline_document_version_locales`) that keeps
-     * only documents available in the requested locale. The `'all'` sentinel row
-     * covers locale-agnostic documents (no localized content). Returns `null`
-     * when the gate does not apply — a non-`'omit'` policy (`'empty'` /
-     * `'fallback'` / unset), or the admin sentinel `'all'` read — so callers can
-     * conditionally push it into a WHERE. No dialect-specific SQL — ports
-     * unchanged from pg.
+     * Build the `onMissingLocale: 'omit'` availability gate: keeps only
+     * documents whose selected version may be delivered in the requested
+     * locale, as an EXISTS-based predicate so counting and pagination stay
+     * correct. It mirrors `resolveReadLocale` in `@byline/core`:
+     *
+     *   - the document's source locale is always admitted, with or without a
+     *     ledger row (no checkbox needed);
+     *   - a locale-agnostic version (the ledger's `'all'` sentinel) is admitted;
+     *   - any other locale must be complete in the version's ledger, and under
+     *     `'public'` visibility in a collection with `advertiseLocales` it must
+     *     also be checked in `byline_document_available_locales`.
+     *
+     * Returns `null` when the gate does not apply (a non-`'omit'` policy, or the
+     * admin sentinel `'all'`), so callers can conditionally push it into a WHERE.
      */
-    localeAvailabilityExists(versionId, locale, onMissingLocale) {
+    localeAvailabilityExists(versionId, locale, onMissingLocale, gate) {
         if (onMissingLocale !== 'omit' || locale === 'all')
             return null;
-        return sql `EXISTS (
-      SELECT 1 FROM byline_document_version_locales dvl
-      WHERE dvl.document_version_id = ${versionId}
-        AND (dvl.locale = ${locale} OR dvl.locale = 'all')
+        return this.localeEligibleSql({ versionId, documentId: gate.documentId, sourceLocale: gate.sourceLocale }, locale, gate.visibility, gate.advertiseLocales);
+    }
+    /**
+     * SQL predicate: may `locale` be delivered for this document version? The
+     * SQL twin of `isLocaleEligible` in `@byline/core` — the source is always
+     * eligible; a locale-agnostic version (`'all'` sentinel) is eligible; any
+     * other locale must be complete in the version's ledger and, under
+     * `'public'` visibility in a collection with `advertiseLocales`, checked in
+     * `byline_document_available_locales`.
+     */
+    localeEligibleSql(row, locale, visibility, advertiseLocales) {
+        const checked = visibility === 'public' && advertiseLocales
+            ? sql `AND EXISTS (
+            SELECT 1 FROM byline_document_available_locales dal
+            WHERE dal.document_id = ${row.documentId}
+              AND dal.locale = ${locale}
+          )`
+            : sql ``;
+        return sql `(
+      COALESCE(${row.sourceLocale}, ${this.defaultContentLocale}) = ${locale}
+      OR EXISTS (
+        SELECT 1 FROM byline_document_version_locales dvl
+        WHERE dvl.document_version_id = ${row.versionId}
+          AND dvl.locale = 'all'
+      )
+      OR (
+        EXISTS (
+          SELECT 1 FROM byline_document_version_locales dvl
+          WHERE dvl.document_version_id = ${row.versionId}
+            AND dvl.locale = ${locale}
+        )
+        ${checked}
+      )
     )`;
     }
+    /**
+     * SQL for the content locale a document's localized values are matched in,
+     * mirroring `resolveReadLocale`: under `'fallback'` the requested locale
+     * when eligible, otherwise the document's source; under `'omit'` the
+     * requested locale (the gate already guarantees eligibility); under a
+     * public exact read the requested locale when eligible, otherwise `NULL`
+     * (withheld values match nothing and are not replaced by the source); under
+     * an editorial exact read the requested locale, partial or not.
+     */
+    effectiveLocaleSql(row, locale, onMissingLocale, visibility, advertiseLocales) {
+        if (locale === 'all' || onMissingLocale === 'omit')
+            return sql `${locale}`;
+        const eligible = this.localeEligibleSql(row, locale, visibility, advertiseLocales);
+        if (onMissingLocale === 'fallback') {
+            return sql `(CASE WHEN ${eligible} THEN ${locale} ELSE COALESCE(${row.sourceLocale}, ${this.defaultContentLocale}) END)`;
+        }
+        if (visibility === 'public')
+            return sql `(CASE WHEN ${eligible} THEN ${locale} END)`;
+        return sql `${locale}`;
+    }
+    /**
+     * The filter policy for a public-capable tree structural read: only when the
+     * caller supplies `localeVisibility` (editing reads omit it and keep exact
+     * requested-locale matching) and there are predicates to evaluate. Tree
+     * edges stay within one collection, resolved from the anchor document when
+     * the caller has only a document id.
+     */
+    async treeFilterPolicy(filters, visibility, anchor) {
+        if (visibility == null || !filters?.length)
+            return undefined;
+        let collectionId = anchor.collectionId;
+        if (collectionId == null && anchor.documentId != null) {
+            const [row] = await this.db
+                .select({ collection_id: documents.collection_id })
+                .from(documents)
+                .where(eq(documents.id, anchor.documentId))
+                .limit(1);
+            collectionId = row?.collection_id;
+        }
+        if (collectionId == null)
+            return undefined;
+        return {
+            collectionId,
+            policy: await this.buildFilterLocalePolicy(collectionId, filters, 'fallback', visibility),
+        };
+    }
+    /**
+     * Build the filter locale policy for a read: its missing-locale policy and
+     * visibility, plus the `advertiseLocales` flag of the read's collection and
+     * of every collection a relation filter hops into.
+     */
+    async buildFilterLocalePolicy(collectionId, filters, onMissingLocale, visibility) {
+        const ids = new Set([collectionId]);
+        const walk = (list) => {
+            for (const filter of list) {
+                if (filter.kind === 'relation') {
+                    ids.add(filter.targetCollectionId);
+                    walk(filter.nested);
+                }
+                else if (filter.kind === 'and' || filter.kind === 'or') {
+                    walk(filter.children);
+                }
+            }
+        };
+        walk(filters);
+        const advertiseByCollectionId = new Map();
+        for (const id of ids) {
+            advertiseByCollectionId.set(id, (await this.getDefinitionForCollection(id)).advertiseLocales === true);
+        }
+        return { onMissingLocale, visibility, advertiseByCollectionId };
+    }
     /**
      * Batch-fetch the version-locale availability sets from the
      * `byline_document_version_locales` ledger. For each version returns the
@@ -317,15 +415,45 @@ export class DocumentQueries {
      * predicate fail cleanly (no document found).
      */
     resolveDocumentIdByPath(collection_id, path, requestedLocale) {
-        const chain = this.buildLocaleChain(requestedLocale);
-        const chainSql = sql.join(chain.map((l) => sql `${l}`), sql `, `);
+        // Identity resolution for a slug, which is unique per (collection, locale):
+        //
+        //   rank 0: the path row under the requested locale;
+        //   rank 1: the path row under the installation default (the previous
+        //           winner, so it is never displaced);
+        //   rank 2: a row under *that document's* own source locale, so a document
+        //           whose source differs from the current default stays reachable.
+        //
+        // Ranks 0 and 1 hold at most one row each (the unique constraint). Rank 2
+        // can hold several documents that share the slug under different sources;
+        // only a unique candidate is accepted, so an ambiguous lookup resolves to
+        // nothing (fail closed) instead of an arbitrary document. Content
+        // eligibility is decided afterwards, on reconstruction, so matching a path
+        // never grants a translation.
+        const requested = requestedLocale ?? this.defaultContentLocale;
+        const def = this.defaultContentLocale;
+        const rank = sql `CASE
+      WHEN ${documentPaths.locale} = ${requested} THEN 0
+      WHEN ${documentPaths.locale} = ${def} THEN 1
+      ELSE 2
+    END`;
         return sql `(
-      SELECT ${documentPaths.document_id} FROM ${documentPaths}
-      WHERE ${documentPaths.collection_id} = ${collection_id}
-        AND ${documentPaths.path} = ${path}
-        AND ${documentPaths.alive} = true
-        AND ${documentPaths.locale} IN (${chainSql})
-      ORDER BY FIELD(${documentPaths.locale}, ${chainSql})
+      SELECT candidate.document_id FROM (
+        SELECT ${documentPaths.document_id} AS document_id,
+          ${rank} AS path_rank,
+          COUNT(*) OVER (PARTITION BY ${rank}) AS rank_peers
+        FROM ${documentPaths}
+        INNER JOIN ${documents} ON ${documents.id} = ${documentPaths.document_id}
+        WHERE ${documentPaths.collection_id} = ${collection_id}
+          AND ${documentPaths.path} = ${path}
+          AND ${documentPaths.alive} = true
+          AND (
+            ${documentPaths.locale} = ${requested}
+            OR ${documentPaths.locale} = ${def}
+            OR ${documentPaths.locale} = COALESCE(${documents.source_locale}, ${def})
+          )
+      ) candidate
+      WHERE candidate.rank_peers = 1
+      ORDER BY candidate.path_rank
       LIMIT 1
     )`;
     }
@@ -377,39 +505,6 @@ export class DocumentQueries {
             path: this.pathProjection(sql `${documentVersions.document_id}`, requestedLocale, sourceLocaleSql),
         };
     }
-    /**
-     * Resolve the single effective content locale a version should be restored
-     * in, walking the fallback chain (`[requested, default]`) and returning the
-     * first locale the version is *available* in. Pure JS/data-structure code
-     * — no SQL — ports unchanged from pg. See pg's docblock for the full
-     * phase-1 availability rule.
-     */
-    resolveEffectiveLocale(flattenedData, chain) {
-        // biome-ignore lint/style/noNonNullAssertion: chain is non-empty by construction
-        const defaultLocale = chain[chain.length - 1];
-        const pathsByLocale = new Map();
-        for (const row of flattenedData) {
-            if (row.locale === 'all' || row.field_type === 'meta')
-                continue;
-            let set = pathsByLocale.get(row.locale);
-            if (set == null) {
-                set = new Set();
-                pathsByLocale.set(row.locale, set);
-            }
-            set.add(row.field_path.join('.'));
-        }
-        const canonical = pathsByLocale.get(defaultLocale) ?? new Set();
-        for (const candidate of chain) {
-            if (candidate === defaultLocale)
-                break;
-            if (canonical.size === 0)
-                return candidate;
-            const covered = pathsByLocale.get(candidate);
-            if (covered != null && isSuperset(covered, canonical))
-                return candidate;
-        }
-        return defaultLocale;
-    }
     /**
      * Reconstruct document fields from unified row values using schema-aware
      * restoration. Meta rows (from store_meta) are converted to
@@ -417,7 +512,7 @@ export class DocumentQueries {
      * _id and _type for blocks and array items inline. Pure JS/core-delegate
      * code — ports unchanged from pg.
      */
-    reconstructFromUnifiedRows(unifiedFieldValues, definition, locale, metaRows, lenient = false, onMissingLocale, sourceLocale) {
+    reconstructFromUnifiedRows(unifiedFieldValues, definition, locale, metaRows, lenient = false, onMissingLocale, sourceLocale, localeContext) {
         const flattenedData = unifiedFieldValues.map((row) => extractFlattenedFieldValue(row));
         if (metaRows) {
             for (const meta of metaRows) {
@@ -430,19 +525,50 @@ export class DocumentQueries {
                 });
             }
         }
-        const resolveLocale = locale === 'all'
-            ? undefined
-            : onMissingLocale === 'fallback'
-                ? this.resolveEffectiveLocale(flattenedData, this.buildLocaleChain(locale, sourceLocale))
-                : locale;
-        const { data, warnings } = restoreFieldSetData(definition.fields, flattenedData, resolveLocale);
+        // One language decision per version, made from the whole version before
+        // any field projection (`resolveReadLocale` in `@byline/core`). The
+        // completeness ledger covers every store table, so a projected read decides
+        // exactly as a full read would; a version with no ledger rows (written
+        // before the ledger and not yet backfilled) derives one from the loaded
+        // rows. Omitted visibility is `'editorial'`: direct adapter reads are
+        // trusted primitives. Under `'public'`, an exact read of an ineligible
+        // locale withholds every localized value (only `'all'` rows and structural
+        // meta rows are restored). `'all'` keeps the per-locale map shape.
+        // The selected version's ledger, derived from the loaded rows only when
+        // the version has no ledger rows. Also the source of `localeAgnostic`,
+        // which every reconstructed result reports, multi-locale reads included.
+        const floor = sourceLocale ?? this.defaultContentLocale;
+        const ledger = localeContext?.ledger ?? deriveVersionLocaleLedger(flattenedData, floor);
+        let resolveLocale;
+        let resolvedLocale = null;
+        let rows = flattenedData;
+        if (locale !== 'all') {
+            const decision = resolveReadLocale({
+                locale,
+                chain: this.buildLocaleChain(locale, sourceLocale),
+                onMissingLocale,
+                eligibility: {
+                    visibility: localeContext?.visibility ?? 'editorial',
+                    sourceLocale: floor,
+                    ledger,
+                    advertiseLocales: definition.advertiseLocales === true,
+                    availableLocales: localeContext?.availableLocales ?? [],
+                },
+            });
+            resolveLocale = decision.restoreLocale;
+            resolvedLocale = decision.resolvedLocale;
+            if (decision.withholdLocalized) {
+                rows = flattenedData.filter((row) => row.locale === 'all' || row.field_type === 'meta');
+            }
+        }
+        const { data, warnings } = restoreFieldSetData(definition.fields, rows, resolveLocale);
         if (!lenient && warnings.length > 0) {
             throw ERR_DATABASE({
                 message: `document reconstruction failed with ${warnings.length} warnings`,
                 details: { warnings },
             }).log(getLogger());
         }
-        return { fields: data, warnings };
+        return { fields: data, warnings, resolvedLocale, localeAgnostic: ledger.localeAgnostic };
     }
     /**
      * getCurrentVersionMetadata — narrow metadata fetch for the current version.
@@ -504,24 +630,38 @@ export class DocumentQueries {
      * rather than thrown. This is the admin edit path's "best-effort load"
      * mode for documents written under a previous collection schema.
      */
-    async getDocumentById({ collection_id, document_id, locale = 'en', reconstruct = true, readMode, filters, lenient = false, onMissingLocale, }) {
+    async getDocumentById({ collection_id, document_id, locale = 'en', reconstruct = true, readMode, filters, lenient = false, onMissingLocale, localeVisibility, }) {
         const view = this.pickCurrentView(readMode);
         const baseConditions = [
             eq(view.collection_id, collection_id),
             eq(view.document_id, document_id),
         ];
         if (filters?.length) {
+            const policy = await this.buildFilterLocalePolicy(collection_id, filters, onMissingLocale, localeVisibility);
+            const row = {
+                versionId: sql `${view.id}`,
+                documentId: sql `${view.document_id}`,
+                sourceLocale: sql `${view.source_locale}`,
+            };
             const outerScope = {
                 docVersionId: sql `${view.id}`,
                 documentId: sql `${view.document_id}`,
                 status: sql `${view.status}`,
                 path: this.pathProjection(sql `${view.document_id}`, locale, sql `${view.source_locale}`),
+                effectiveLocale: this.effectiveLocaleSql(row, locale, onMissingLocale, localeVisibility, policy.advertiseByCollectionId.get(collection_id) ?? false),
+                policy,
             };
             for (const f of filters) {
                 baseConditions.push(this.buildFilterExists(f, locale, outerScope, readMode, 0));
             }
         }
-        const strictGate = this.localeAvailabilityExists(sql `${view.id}`, locale, onMissingLocale);
+        const strictGate = this.localeAvailabilityExists(sql `${view.id}`, locale, onMissingLocale, {
+            documentId: sql `${view.document_id}`,
+            sourceLocale: sql `${view.source_locale}`,
+            visibility: localeVisibility,
+            advertiseLocales: onMissingLocale === 'omit' &&
+                (await this.getDefinitionForCollection(collection_id)).advertiseLocales === true,
+        });
         if (strictGate) {
             baseConditions.push(strictGate);
         }
@@ -544,9 +684,9 @@ export class DocumentQueries {
             })
                 .from(metaStore)
                 .where(eq(metaStore.document_version_id, document.id));
-            const { fields, warnings } = this.reconstructFromUnifiedRows(unifiedFieldValues, definition, locale, metaRows, lenient, onMissingLocale, document.source_locale);
             const availability = (await this.getAvailableLocalesByVersion([document.id])).get(document.id);
             const advertised = (await this.getAdvertisedLocalesByDocument([document.document_id])).get(document.document_id);
+            const { fields, warnings, resolvedLocale, localeAgnostic } = this.reconstructFromUnifiedRows(unifiedFieldValues, definition, locale, metaRows, lenient, onMissingLocale, document.source_locale, { visibility: localeVisibility, ledger: availability, availableLocales: advertised });
             return {
                 document_version_id: document.id,
                 document_id: document.document_id,
@@ -558,9 +698,10 @@ export class DocumentQueries {
                 updated_at: document.updated_at,
                 created_by: document.created_by ?? null,
                 fields,
+                resolved_locale: resolvedLocale,
                 availableLocales: advertised ?? [],
                 _availableVersionLocales: availability?.availableLocales ?? [],
-                _localeAgnostic: availability?.localeAgnostic ?? false,
+                _localeAgnostic: localeAgnostic,
                 ...(lenient && warnings.length > 0 ? { restoreWarnings: warnings } : {}),
             };
         }
@@ -584,24 +725,38 @@ export class DocumentQueries {
      * current version. See `resolveDocumentIdByPath` for the locale-chain
      * SQL.
      */
-    async getDocumentByPath({ collection_id, path, locale = 'en', reconstruct = true, readMode, filters, onMissingLocale, }) {
+    async getDocumentByPath({ collection_id, path, locale = 'en', reconstruct = true, readMode, filters, onMissingLocale, localeVisibility, }) {
         const view = this.pickCurrentView(readMode);
         const baseConditions = [
             eq(view.collection_id, collection_id),
             sql `${view.document_id} = ${this.resolveDocumentIdByPath(collection_id, path, locale)}`,
         ];
         if (filters?.length) {
+            const policy = await this.buildFilterLocalePolicy(collection_id, filters, onMissingLocale, localeVisibility);
+            const row = {
+                versionId: sql `${view.id}`,
+                documentId: sql `${view.document_id}`,
+                sourceLocale: sql `${view.source_locale}`,
+            };
             const outerScope = {
                 docVersionId: sql `${view.id}`,
                 documentId: sql `${view.document_id}`,
                 status: sql `${view.status}`,
                 path: this.pathProjection(sql `${view.document_id}`, locale, sql `${view.source_locale}`),
+                effectiveLocale: this.effectiveLocaleSql(row, locale, onMissingLocale, localeVisibility, policy.advertiseByCollectionId.get(collection_id) ?? false),
+                policy,
             };
             for (const f of filters) {
                 baseConditions.push(this.buildFilterExists(f, locale, outerScope, readMode, 0));
             }
         }
-        const strictGate = this.localeAvailabilityExists(sql `${view.id}`, locale, onMissingLocale);
+        const strictGate = this.localeAvailabilityExists(sql `${view.id}`, locale, onMissingLocale, {
+            documentId: sql `${view.document_id}`,
+            sourceLocale: sql `${view.source_locale}`,
+            visibility: localeVisibility,
+            advertiseLocales: onMissingLocale === 'omit' &&
+                (await this.getDefinitionForCollection(collection_id)).advertiseLocales === true,
+        });
         if (strictGate) {
             baseConditions.push(strictGate);
         }
@@ -624,9 +779,9 @@ export class DocumentQueries {
             })
                 .from(metaStore)
                 .where(eq(metaStore.document_version_id, document.id));
-            const { fields } = this.reconstructFromUnifiedRows(unifiedFieldValues, definition, locale, metaRows, false, onMissingLocale, document.source_locale);
             const availability = (await this.getAvailableLocalesByVersion([document.id])).get(document.id);
             const advertised = (await this.getAdvertisedLocalesByDocument([document.document_id])).get(document.document_id);
+            const { fields, resolvedLocale, localeAgnostic } = this.reconstructFromUnifiedRows(unifiedFieldValues, definition, locale, metaRows, false, onMissingLocale, document.source_locale, { visibility: localeVisibility, ledger: availability, availableLocales: advertised });
             return {
                 document_version_id: document.id,
                 document_id: document.document_id,
@@ -638,9 +793,10 @@ export class DocumentQueries {
                 updated_at: document.updated_at,
                 created_by: document.created_by ?? null,
                 fields,
+                resolved_locale: resolvedLocale,
                 availableLocales: advertised ?? [],
                 _availableVersionLocales: availability?.availableLocales ?? [],
-                _localeAgnostic: availability?.localeAgnostic ?? false,
+                _localeAgnostic: localeAgnostic,
             };
         }
         const fieldValues = this.convertUnionRowToFlattenedStores(unifiedFieldValues);
@@ -696,7 +852,8 @@ export class DocumentQueries {
         })
             .from(metaStore)
             .where(eq(metaStore.document_version_id, document.id));
-        const { fields } = this.reconstructFromUnifiedRows(unifiedFieldValues, definition, locale, metaRows, false, undefined, document.source_locale);
+        const ledger = (await this.getAvailableLocalesByVersion([document.id])).get(document.id);
+        const { fields, resolvedLocale, localeAgnostic } = this.reconstructFromUnifiedRows(unifiedFieldValues, definition, locale, metaRows, false, undefined, document.source_locale, { ledger });
         return {
             document_version_id: document.id,
             document_id: document.document_id,
@@ -706,6 +863,8 @@ export class DocumentQueries {
             created_at: document.created_at,
             updated_at: document.updated_at,
             fields,
+            resolved_locale: resolvedLocale,
+            _localeAgnostic: localeAgnostic,
         };
     }
     /**
@@ -735,7 +894,7 @@ export class DocumentQueries {
      * `store_relation` rows carry `target_document_id` (not version ID), so
      * populate collects those IDs and resolves them here in one round trip.
      */
-    async getDocumentsByDocumentIds({ collection_id, document_ids, locale = 'all', fields, readMode, filters, }) {
+    async getDocumentsByDocumentIds({ collection_id, document_ids, locale = 'all', fields, readMode, filters, localeVisibility, }) {
         if (document_ids.length === 0)
             return [];
         const view = this.pickCurrentView(readMode);
@@ -750,11 +909,20 @@ export class DocumentQueries {
             inArray(view.document_id, document_ids),
         ];
         if (filters?.length) {
+            // Populate shows targets under fallback, so their predicates match in
+            // each target's effective fallback locale.
+            const policy = await this.buildFilterLocalePolicy(collection_id, filters, 'fallback', localeVisibility);
             const outerScope = {
                 docVersionId: sql `${view.id}`,
                 documentId: sql `${view.document_id}`,
                 status: sql `${view.status}`,
                 path: this.pathProjection(sql `${view.document_id}`, filterLocale, sql `${view.source_locale}`),
+                effectiveLocale: this.effectiveLocaleSql({
+                    versionId: sql `${view.id}`,
+                    documentId: sql `${view.document_id}`,
+                    sourceLocale: sql `${view.source_locale}`,
+                }, filterLocale, 'fallback', localeVisibility, policy.advertiseByCollectionId.get(collection_id) ?? false),
+                policy,
             };
             for (const f of filters) {
                 baseConditions.push(this.buildFilterExists(f, filterLocale, outerScope, readMode, 0));
@@ -772,6 +940,7 @@ export class DocumentQueries {
             locale,
             fields,
             onMissingLocale: 'fallback',
+            localeVisibility,
         });
     }
     /**
@@ -965,10 +1134,16 @@ export class DocumentQueries {
      * MySQL has no cast syntax for a UUID-shaped `CHAR(36)` column, and the
      * driver already binds the plain string correctly.
      */
-    async getTreeAncestors({ document_id, maxDepth = 10_000, readMode = 'any', locale = this.defaultContentLocale, filters, }) {
-        const childGate = this.buildTreeVisibility(sql `child_document_id`, filters, locale, readMode, 'cv0');
-        const anchorParentGate = this.buildTreeVisibility(sql `parent_document_id`, filters, locale, readMode, 'pv0');
-        const recursiveParentGate = this.buildTreeVisibility(sql `r.parent_document_id`, filters, locale, readMode, 'pv1');
+    async getTreeAncestors({ document_id, maxDepth = 10_000, readMode = 'any', locale = this.defaultContentLocale, filters, localeVisibility, }) {
+        // Public-capable structural reads evaluate `beforeRead` predicates in the
+        // locale hydration will show (fallback, under the read's visibility), so a
+        // node is neither dropped nor admitted on a withheld translation.
+        const treePolicy = await this.treeFilterPolicy(filters, localeVisibility, {
+            documentId: document_id,
+        });
+        const childGate = this.buildTreeVisibility(sql `child_document_id`, filters, locale, readMode, 'cv0', treePolicy);
+        const anchorParentGate = this.buildTreeVisibility(sql `parent_document_id`, filters, locale, readMode, 'pv0', treePolicy);
+        const recursiveParentGate = this.buildTreeVisibility(sql `r.parent_document_id`, filters, locale, readMode, 'pv1', treePolicy);
         const query = sql `
       WITH RECURSIVE ancestors AS (
         SELECT parent_document_id AS ancestor_id, child_document_id AS node_id, 1 AS depth
@@ -1022,9 +1197,15 @@ export class DocumentQueries {
      * (which returns `[]` for both) conflates. `::uuid` cast dropped, same as
      * `getTreeAncestors`.
      */
-    async getTreeParent({ document_id, readMode = 'any', locale = this.defaultContentLocale, filters, }) {
-        const childGate = this.buildTreeVisibility(sql `r.child_document_id`, filters, locale, readMode, 'cv0');
-        const parentGate = this.buildTreeVisibility(sql `r.parent_document_id`, filters, locale, readMode, 'pv0');
+    async getTreeParent({ document_id, readMode = 'any', locale = this.defaultContentLocale, filters, localeVisibility, }) {
+        // Public-capable structural reads evaluate `beforeRead` predicates in the
+        // locale hydration will show (fallback, under the read's visibility), so a
+        // node is neither dropped nor admitted on a withheld translation.
+        const treePolicy = await this.treeFilterPolicy(filters, localeVisibility, {
+            documentId: document_id,
+        });
+        const childGate = this.buildTreeVisibility(sql `r.child_document_id`, filters, locale, readMode, 'cv0', treePolicy);
+        const parentGate = this.buildTreeVisibility(sql `r.parent_document_id`, filters, locale, readMode, 'pv0', treePolicy);
         const query = sql `
       SELECT r.parent_document_id,
              CASE WHEN r.parent_document_id IS NULL THEN TRUE ELSE ${parentGate} END AS parent_visible
@@ -1102,12 +1283,16 @@ export class DocumentQueries {
      *     reverts to the *connection's* default collation, not the source
      *     column's, so both clauses are required, not just one).
      */
-    async getTreeSubtree({ collectionId, rootDocumentId = null, maxDepth = 10_000, readMode = 'any', locale = this.defaultContentLocale, filters, }) {
+    async getTreeSubtree({ collectionId, rootDocumentId = null, maxDepth = 10_000, readMode = 'any', locale = this.defaultContentLocale, filters, localeVisibility, }) {
+        // Public-capable structural reads evaluate `beforeRead` predicates in the
+        // locale hydration will show (fallback, under the read's visibility), so a
+        // node is neither dropped nor admitted on a withheld translation.
+        const treePolicy = await this.treeFilterPolicy(filters, localeVisibility, { collectionId });
         const rootCondition = rootDocumentId == null
             ? sql `r.parent_document_id IS NULL`
             : sql `r.child_document_id = ${rootDocumentId}`;
-        const anchorGate = this.buildTreeVisibility(sql `r.child_document_id`, filters, locale, readMode, 'sv0');
-        const childGate = this.buildTreeVisibility(sql `r.child_document_id`, filters, locale, readMode, 'sv1');
+        const anchorGate = this.buildTreeVisibility(sql `r.child_document_id`, filters, locale, readMode, 'sv0', treePolicy);
+        const childGate = this.buildTreeVisibility(sql `r.child_document_id`, filters, locale, readMode, 'sv1', treePolicy);
         const query = sql `
       WITH RECURSIVE subtree AS (
         SELECT r.child_document_id, r.parent_document_id, r.order_key,
@@ -1180,10 +1365,17 @@ export class DocumentQueries {
      * dialect-specific work is one level down, in
      * `getAllFieldValuesForMultipleVersions`).
      */
-    async reconstructDocuments({ documents: docs, locale = 'all', fields: requestedFields, onMissingLocale, }) {
+    async reconstructDocuments({ documents: docs, locale = 'all', fields: requestedFields, onMissingLocale, localeVisibility, ledgers, advertised, }) {
         if (docs.length === 0)
             return [];
         const versionIds = docs.map((v) => v.id);
+        const concrete = locale !== 'all';
+        const versionLedgers = ledgers ?? (await this.getAvailableLocalesByVersion(versionIds));
+        // The checkbox set only matters to a public decision.
+        const documentAdvertised = advertised ??
+            (concrete && localeVisibility === 'public'
+                ? await this.getAdvertisedLocalesByDocument(docs.map((d) => d.document_id))
+                : undefined);
         // Resolve definition once for the batch (safe — early return above guarantees length > 0)
         const firstDoc = docs[0];
         const definition = await this.getDefinitionForCollection(firstDoc.collection_id);
@@ -1237,7 +1429,11 @@ export class DocumentQueries {
         for (const doc of docs) {
             const versionFieldValues = fieldValuesByVersion.get(doc.id) || [];
             const docMetaRows = (metaByVersion.get(doc.id) ?? []);
-            const { fields } = this.reconstructFromUnifiedRows(versionFieldValues, definition, locale, docMetaRows, false, onMissingLocale, doc.source_locale);
+            const { fields, resolvedLocale, localeAgnostic } = this.reconstructFromUnifiedRows(versionFieldValues, definition, locale, docMetaRows, false, onMissingLocale, doc.source_locale, {
+                visibility: localeVisibility,
+                ledger: versionLedgers?.get(doc.id),
+                availableLocales: documentAdvertised?.get(doc.document_id),
+            });
             // When specific fields were requested, trim the reconstructed object
             // to only those fields. Store-level filtering avoids querying unused
             // tables, but fields sharing a store (e.g. price + views in numeric)
@@ -1256,6 +1452,8 @@ export class DocumentQueries {
                 updated_at: doc.updated_at,
                 created_by: doc.created_by ?? null,
                 fields: trimmedFields,
+                resolved_locale: resolvedLocale,
+                _localeAgnostic: localeAgnostic,
             };
             result.push(documentWithFields);
         }
@@ -1335,7 +1533,7 @@ export class DocumentQueries {
      * conditions (status, path) are applied directly on the current_documents
      * view.
      */
-    async findDocuments({ collection_id, filters = [], status, pathFilter, query, sort, orderBy = 'created_at', orderDirection = 'desc', locale = 'en', page = 1, pageSize = 20, fields: requestedFields, readMode, onMissingLocale, }) {
+    async findDocuments({ collection_id, filters = [], status, pathFilter, query, sort, orderBy = 'created_at', orderDirection = 'desc', locale = 'en', page = 1, pageSize = 20, fields: requestedFields, readMode, onMissingLocale, localeVisibility, }) {
         const offset = (page - 1) * pageSize;
         const sourceTable = readMode === 'published'
             ? sql.raw('byline_current_published_documents')
@@ -1345,9 +1543,21 @@ export class DocumentQueries {
         if (status) {
             conditions.push(sql `d.status = ${status}`);
         }
+        // The locale each row's localized values are matched in by filters, the
+        // list text query and field sorts: exactly the locale reconstruction will
+        // show for that row, so a withheld or incomplete translation can neither
+        // match nor influence ordering while the response displays the source.
+        const filterPolicy = await this.buildFilterLocalePolicy(collection_id, filters, onMissingLocale, localeVisibility);
+        const effectiveLocale = this.effectiveLocaleSql({ versionId: sql `d.id`, documentId: sql `d.document_id`, sourceLocale: sql `d.source_locale` }, locale, onMissingLocale, localeVisibility, filterPolicy.advertiseByCollectionId.get(collection_id) ?? false);
         // `onMissingLocale: 'omit'` — exclude documents not available in the
         // requested locale (filtered at the SQL layer so pagination stays correct).
-        const strictGate = this.localeAvailabilityExists(sql `d.id`, locale, onMissingLocale);
+        const strictGate = this.localeAvailabilityExists(sql `d.id`, locale, onMissingLocale, {
+            documentId: sql `d.document_id`,
+            sourceLocale: sql `d.source_locale`,
+            visibility: localeVisibility,
+            advertiseLocales: onMissingLocale === 'omit' &&
+                (await this.getDefinitionForCollection(collection_id)).advertiseLocales === true,
+        });
         if (strictGate) {
             conditions.push(strictGate);
         }
@@ -1370,19 +1580,22 @@ export class DocumentQueries {
             conditions.push(sql `EXISTS (
         SELECT 1 FROM byline_store_text
         WHERE document_version_id = d.id
-          AND (locale = ${locale} OR locale = 'all')
+          AND (locale = ${effectiveLocale} OR locale = 'all')
           AND (${sql.join(searchConditions, sql ` OR `)})
       )`);
         }
         // Field-level / relation-level EXISTS subqueries. Each relation hop
         // introduces its own alias scope (`r${depth}`, `td${depth}`) so nested
-        // EXISTS clauses don't shadow their outer relation's aliases.
+        // EXISTS clauses don't shadow their outer relation's aliases. Localized
+        // values are matched in each document's effective locale (`effectiveLocale`).
         for (const filter of filters) {
             conditions.push(this.buildFilterExists(filter, locale, {
                 docVersionId: sql `d.id`,
                 documentId: sql `d.document_id`,
                 status: sql `d.status`,
                 path: this.pathProjection(sql `d.document_id`, locale, sql `d.source_locale`),
+                effectiveLocale,
+                policy: filterPolicy,
             }, readMode, 0));
         }
         const whereClause = sql.join(conditions, sql ` AND `);
@@ -1398,7 +1611,7 @@ export class DocumentQueries {
           FROM ${sql.raw(storeTable)}
           WHERE document_version_id = d.id
             AND field_name = ${sort.fieldName}
-            AND (locale = ${locale} OR locale = 'all')
+            AND (locale = ${effectiveLocale} OR locale = 'all')
           LIMIT 1
         ) _sort ON true`;
                 // MySQL has no `NULLS LAST`. `DESC` already sorts NULL last by
@@ -1481,22 +1694,25 @@ export class DocumentQueries {
             change_summary: row.change_summary,
             source_locale: row.source_locale ?? null,
         }));
+        // The version-locale availability for the whole page (one batched
+        // indexed query). It selects each row's effective locale under
+        // `'fallback'` and is attached per row below so list consumers can render
+        // language affordances / hreflang without a follow-up fetch.
+        const availability = await this.getAvailableLocalesByVersion(currentDocuments.map((d) => d.id));
+        const advertised = await this.getAdvertisedLocalesByDocument(currentDocuments.map((d) => d.document_id));
         const documents = await this.reconstructDocuments({
             documents: currentDocuments,
             locale,
             fields: requestedFields,
             onMissingLocale,
+            localeVisibility,
+            ledgers: availability,
+            advertised,
         });
-        // Attach the version-locale availability metadata per row (one batched
-        // indexed query for the whole page) so list consumers can render
-        // language affordances / hreflang without a follow-up fetch.
-        const availability = await this.getAvailableLocalesByVersion(documents.map((d) => d.document_version_id));
-        const advertised = await this.getAdvertisedLocalesByDocument(documents.map((d) => d.document_id));
         for (const doc of documents) {
             const a = availability.get(doc.document_version_id);
             doc.availableLocales = advertised.get(doc.document_id) ?? [];
             doc._availableVersionLocales = a?.availableLocales ?? [];
-            doc._localeAgnostic = a?.localeAgnostic ?? false;
         }
         return { documents, total };
     }
@@ -1506,7 +1722,7 @@ export class DocumentQueries {
      * SQL of its own (its nested `buildFilterExists` calls carry the
      * dialect-specific bits).
      */
-    buildTreeVisibility(documentId, filters, locale, readMode, aliasName) {
+    buildTreeVisibility(documentId, filters, locale, readMode, aliasName, treePolicy) {
         const view = readMode === 'published'
             ? sql.raw('byline_current_published_documents')
             : sql.raw('byline_current_documents');
@@ -1516,6 +1732,14 @@ export class DocumentQueries {
             documentId: sql `${alias}.document_id`,
             status: sql `${alias}.status`,
             path: this.pathProjection(sql `${alias}.document_id`, locale, sql `${alias}.source_locale`),
+            effectiveLocale: treePolicy
+                ? this.effectiveLocaleSql({
+                    versionId: sql `${alias}.id`,
+                    documentId: sql `${alias}.document_id`,
+                    sourceLocale: sql `${alias}.source_locale`,
+                }, locale, 'fallback', treePolicy.policy.visibility, treePolicy.policy.advertiseByCollectionId.get(treePolicy.collectionId) ?? false)
+                : undefined,
+            policy: treePolicy?.policy,
         };
         const filterSql = (filters ?? []).map((filter) => this.buildFilterExists(filter, locale, scope, readMode, 0));
         const filterClause = filterSql.length > 0 ? sql ` AND ${sql.join(filterSql, sql ` AND `)}` : sql ``;
@@ -1537,7 +1761,7 @@ export class DocumentQueries {
     buildFilterExists(filter, locale, outerScope, readMode, depth) {
         switch (filter.kind) {
             case 'field':
-                return this.buildFieldExists(filter, locale, outerScope.docVersionId);
+                return this.buildFieldExists(filter, outerScope.effectiveLocale ?? sql `${locale}`, outerScope.docVersionId);
             case 'relation':
                 return this.buildRelationExists(filter, locale, outerScope, readMode, depth);
             case 'and':
@@ -1628,6 +1852,17 @@ export class DocumentQueries {
             // locale priority chain against byline_document_paths instead, anchored
             // to the target document's own `source_locale`.
             path: this.pathProjection(sql.raw(`td${depth}.document_id`), locale, sql.raw(`td${depth}.source_locale`)),
+            // Each target is matched in its own effective locale (populate shows
+            // targets under fallback), judged by its own source, ledger, checkboxes
+            // and collection opt-in.
+            effectiveLocale: outerScope.policy
+                ? this.effectiveLocaleSql({
+                    versionId: sql.raw(`td${depth}.id`),
+                    documentId: sql.raw(`td${depth}.document_id`),
+                    sourceLocale: sql.raw(`td${depth}.source_locale`),
+                }, locale, 'fallback', outerScope.policy.visibility, outerScope.policy.advertiseByCollectionId.get(filter.targetCollectionId) ?? false)
+                : undefined,
+            policy: outerScope.policy,
         };
         const nestedConditions = filter.nested.map((nested) => this.buildFilterExists(nested, locale, innerScope, readMode, depth + 1));
         const quantifier = filter.quantifier ?? 'some';
@@ -1661,7 +1896,7 @@ export class DocumentQueries {
       WHERE ${rAlias}.document_version_id = ${outerScope.docVersionId}
         AND ${fieldMatch}
         AND ${rAlias}.target_collection_id = ${filter.targetCollectionId}
-        AND (${rAlias}.locale = ${locale} OR ${rAlias}.locale = 'all')${nestedAnd}
+        AND (${rAlias}.locale = ${outerScope.effectiveLocale ?? sql `${locale}`} OR ${rAlias}.locale = 'all')${nestedAnd}
     )`;
         return quantifier === 'some' ? existsSql : sql `NOT ${existsSql}`;
     }

package/dist/modules/storage/tests/storage-queries.test.js

@@ -5,8 +5,11 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
+import { sql } from 'drizzle-orm';
 import { afterAll, beforeAll, describe, expect, it } from 'vitest';
 import { setupTestDB, teardownTestDB } from '../../../lib/test-helper.js';
+import { createCommandBuilders } from '../storage-commands.js';
+import { createQueryBuilders } from '../storage-queries.js';
 const timestamp = Date.now();
 function first(rows) {
     const row = rows[0];
@@ -154,6 +157,210 @@ const DatesCollectionConfig = {
  * existing suite exercised a `date`/`datetime` field through this path, so
  * nothing caught the un-coerced string before this test.
  */
+const ProjectedLocaleCollectionConfig = {
+    path: `queries-test-projected-locale-${timestamp}`,
+    labels: { singular: 'Projected', plural: 'Projected' },
+    fields: [
+        { name: 'title', type: 'text', localized: true, optional: true },
+        // A localized field in a different store (JSON) from the title (text), so
+        // a title-only projection cannot see whether it is translated.
+        { name: 'summary', type: 'richText', localized: true, optional: true },
+    ],
+};
+describe('fallback locale selection under a changed default (mysql, live database)', () => {
+    let testDb;
+    let collectionId;
+    beforeAll(async () => {
+        testDb = setupTestDB([ProjectedLocaleCollectionConfig]);
+        const created = first(await testDb.commandBuilders.collections.create(ProjectedLocaleCollectionConfig.path, ProjectedLocaleCollectionConfig));
+        collectionId = created.id;
+    });
+    afterAll(async () => {
+        // `teardownTestDB()` is called once, at the very end of this file.
+        await testDb.commandBuilders.collections.delete(collectionId);
+    });
+    it('path lookup finds a document whose source differs from the current default', async () => {
+        const created = await testDb.commandBuilders.documents.createDocumentVersion({
+            collectionId,
+            collectionVersion: 1,
+            collectionConfig: ProjectedLocaleCollectionConfig,
+            action: 'create',
+            documentData: { title: { en: 'Path EN', es: 'Path ES' } },
+            path: `path-src-${timestamp}`,
+            locale: 'all',
+            status: 'published',
+        });
+        const id = created.document.document_id;
+        const frQueries = createQueryBuilders(testDb.db, [ProjectedLocaleCollectionConfig], 'fr', testDb.dbManager);
+        for (const locale of ['fr', 'es', 'en']) {
+            const byPath = await frQueries.documents.getDocumentByPath({
+                collection_id: collectionId,
+                path: `path-src-${timestamp}`,
+                locale,
+                reconstruct: true,
+                onMissingLocale: 'fallback',
+            });
+            expect(byPath?.document_id, `path lookup in ${locale}`).toBe(id);
+            const byId = (await frQueries.documents.getDocumentById({
+                collection_id: collectionId,
+                document_id: id,
+                locale,
+                onMissingLocale: 'fallback',
+            }));
+            const { documents } = await frQueries.documents.findDocuments({
+                collection_id: collectionId,
+                locale,
+                onMissingLocale: 'fallback',
+                pageSize: 200,
+            });
+            const listed = documents.find((d) => d.document_id === id);
+            expect(byPath?.fields.title).toBe(byId?.fields.title);
+            expect(listed?.fields.title).toBe(byId?.fields.title);
+            expect(byPath?.resolved_locale).toBe(byId?.resolved_locale);
+            expect(listed?.resolved_locale).toBe(byId?.resolved_locale);
+        }
+    });
+    it('path lookup never returns an arbitrary document when slugs collide', async () => {
+        const slug = `shared-${timestamp}`;
+        const frCommands = createCommandBuilders(testDb.dbManager, 'fr');
+        const make = async (commands, title) => (await commands.documents.createDocumentVersion({
+            collectionId,
+            collectionVersion: 1,
+            collectionConfig: ProjectedLocaleCollectionConfig,
+            action: 'create',
+            documentData: { title },
+            path: slug,
+            locale: 'all',
+            status: 'published',
+        })).document.document_id;
+        const a = await make(testDb.commandBuilders, { en: 'A EN' });
+        const b = await make(frCommands, { fr: 'B FR' });
+        const lookup = (defaultLocale, locale, path = slug) => createQueryBuilders(testDb.db, [ProjectedLocaleCollectionConfig], defaultLocale, testDb.dbManager)
+            .documents.getDocumentByPath({
+            collection_id: collectionId,
+            path,
+            locale,
+            reconstruct: true,
+            onMissingLocale: 'fallback',
+        })
+            .then((doc) => doc?.document_id ?? null);
+        expect(await lookup('fr', 'en')).toBe(a);
+        expect(await lookup('en', 'fr')).toBe(b);
+        expect(await lookup('fr', 'es')).toBe(b);
+        expect(await lookup('en', 'es')).toBe(a);
+        expect(await lookup('de', 'es')).toBeNull();
+        const solo = `solo-${timestamp}`;
+        const c = (await testDb.commandBuilders.documents.createDocumentVersion({
+            collectionId,
+            collectionVersion: 1,
+            collectionConfig: ProjectedLocaleCollectionConfig,
+            action: 'create',
+            documentData: { title: { en: 'C EN' } },
+            path: solo,
+            locale: 'all',
+            status: 'published',
+        })).document.document_id;
+        expect(await lookup('de', 'es', solo)).toBe(c);
+    });
+    it('filters match each document in its own source across a mixed-source page', async () => {
+        const frCommands = createCommandBuilders(testDb.dbManager, 'fr');
+        const make = async (commands, title) => (await commands.documents.createDocumentVersion({
+            collectionId,
+            collectionVersion: 1,
+            collectionConfig: ProjectedLocaleCollectionConfig,
+            action: 'create',
+            documentData: { title },
+            path: `mixed-${timestamp}-${Object.keys(title)[0]}`,
+            locale: 'all',
+            status: 'published',
+        })).document.document_id;
+        const a = await make(testDb.commandBuilders, { en: 'Mixed A EN' });
+        const b = await make(frCommands, { fr: 'Mixed B FR' });
+        const matching = async (value) => (await testDb.queryBuilders.documents.findDocuments({
+            collection_id: collectionId,
+            locale: 'es',
+            onMissingLocale: 'fallback',
+            localeVisibility: 'public',
+            filters: [
+                {
+                    kind: 'field',
+                    fieldName: 'title',
+                    storeType: 'text',
+                    valueColumn: 'value',
+                    operator: '$eq',
+                    value,
+                },
+            ],
+            pageSize: 200,
+        })).documents.map((d) => d.document_id);
+        expect(await matching('Mixed A EN')).toEqual([a]);
+        expect(await matching('Mixed B FR')).toEqual([b]);
+    });
+    it('a translated path row cannot bypass content eligibility', async () => {
+        // German is incomplete (title only; the summary is untranslated).
+        const created = await testDb.commandBuilders.documents.createDocumentVersion({
+            collectionId,
+            collectionVersion: 1,
+            collectionConfig: ProjectedLocaleCollectionConfig,
+            action: 'create',
+            documentData: {
+                title: { en: 'Slug EN', de: 'Slug DE' },
+                summary: { en: { root: { type: 'root', children: [{ type: 'text', text: 'S' }] } } },
+            },
+            path: `slug-src-${timestamp}`,
+            locale: 'all',
+            status: 'published',
+        });
+        const id = created.document.document_id;
+        await testDb.db.execute(sql `
+      INSERT INTO byline_document_paths (document_id, collection_id, locale, path)
+      VALUES (${id}, ${collectionId}, 'de', ${`slug-de-${timestamp}`})
+    `);
+        const byPath = await testDb.queryBuilders.documents.getDocumentByPath({
+            collection_id: collectionId,
+            path: `slug-de-${timestamp}`,
+            locale: 'de',
+            reconstruct: true,
+            onMissingLocale: 'fallback',
+            localeVisibility: 'public',
+        });
+        expect(byPath?.document_id).toBe(id);
+        expect(byPath?.fields.title, 'the incomplete translation is not delivered').toBe('Slug EN');
+        expect(byPath?.resolved_locale).toBe('en');
+    });
+    it('a projected list falls back to the document source, not the changed default', async () => {
+        const richText = (text) => ({
+            root: { type: 'root', children: [{ type: 'text', text }] },
+        });
+        // Source 'en' (the helper's default). French is translated in the text
+        // store but not in the JSON-store summary, so French is incomplete.
+        const created = await testDb.commandBuilders.documents.createDocumentVersion({
+            collectionId,
+            collectionVersion: 1,
+            collectionConfig: ProjectedLocaleCollectionConfig,
+            action: 'create',
+            documentData: {
+                title: { en: 'Projected EN', fr: 'Projected FR' },
+                summary: { en: richText('Summary EN') },
+            },
+            path: `projected-${timestamp}`,
+            locale: 'all',
+            status: 'published',
+        });
+        // The installation default is now 'fr', which differs from the source.
+        const frQueries = createQueryBuilders(testDb.db, [ProjectedLocaleCollectionConfig], 'fr', testDb.dbManager);
+        const { documents } = await frQueries.documents.findDocuments({
+            collection_id: collectionId,
+            locale: 'fr',
+            onMissingLocale: 'fallback',
+            fields: ['title'],
+            pageSize: 200,
+        });
+        // The chain is [fr, en]: French is incomplete in the ledger, so the read
+        // resolves to the source 'en', even though only the text store was loaded.
+        expect(documents.find((d) => d.document_id === created.document.document_id)?.fields.title).toBe('Projected EN');
+    });
+});
 describe('date/datetime field values are real Date objects on read (mysql, live database)', () => {
     let testDb;
     let collectionId;

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/db-mysql",
   "private": false,
   "license": "MPL-2.0",
-  "version": "6.5.0",
+  "version": "6.7.0",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -50,8 +50,8 @@
     "drizzle-orm": "^0.45.2",
     "mysql2": "^3.24.4",
     "uuid": "^14.0.2",
-    "@byline/admin": "6.5.0",
-    "@byline/core": "6.5.0"
+    "@byline/admin": "6.7.0",
+    "@byline/core": "6.7.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.14",
@@ -64,8 +64,8 @@
     "tsc-alias": "^1.9.5",
     "typescript": "^7.0.2",
     "vitest": "^5.0.1",
-    "@byline/auth": "6.5.0",
-    "@byline/client": "6.5.0",
+    "@byline/client": "6.7.0",
+    "@byline/auth": "6.7.0",
     "@byline/db-conformance": "0.0.10"
   },
   "publishConfig": {