@byline/db-postgres 2.7.0 → 3.0.1

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

@@ -11,10 +11,18 @@
 // either deferring adapter construction or accepting a lazy logger parameter.
 import { ERR_DATABASE, ERR_NOT_FOUND, getLogger } from '@byline/core';
 import { and, desc, eq, inArray, isNotNull, sql } from 'drizzle-orm';
-import { collections, currentDocumentsView, currentPublishedDocumentsView, documentPaths, documents, documentVersions, metaStore, } from '../../database/schema/index.js';
+import { collections, currentDocumentsView, currentPublishedDocumentsView, documentAvailableLocales, documentPaths, documents, documentVersionLocales, documentVersions, metaStore, } from '../../database/schema/index.js';
 import { extractFlattenedFieldValue, restoreFieldSetData } from './storage-restore.js';
 import { allStoreTypes, storeSelectList, storeTableNames, } from './storage-store-manifest.js';
 import { resolveStoreTypes } 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
  */
@@ -91,20 +99,102 @@ export class DocumentQueries {
         return readMode === 'published' ? currentPublishedDocumentsView : currentDocumentsView;
     }
     /**
-     * Build the locale priority chain for path resolution:
-     * `[requested, default]`, deduplicated when both are the same.
-     *
-     * Used by every read path that touches `byline_document_paths`. In
-     * phase 1 only the default-locale row is ever populated, so a non-
-     * default `requested` locale always falls through to the default —
-     * but the chain shape is correct for phase 2 when per-locale rows
-     * begin to exist.
+     * Build the locale priority chain for fallback resolution:
+     * `[requested, floor]`, deduplicated when both are the same. The floor is
+     * the document's own `source_locale` anchor when known (so a re-anchored
+     * document, or any document read after the global default is switched, falls
+     * back to the locale it was actually authored in) — otherwise the configured
+     * global default, which is correct for not-yet-anchored rows and for
+     * row-less lookups (findByPath). See docs/I18N.md.
+     */
+    buildLocaleChain(requestedLocale, sourceLocale) {
+        const floor = sourceLocale ?? this.defaultContentLocale;
+        const requested = requestedLocale ?? floor;
+        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.
+     */
+    localeAvailabilityExists(versionId, locale, onMissingLocale) {
+        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')
+    )`;
+    }
+    /**
+     * Batch-fetch the version-locale availability sets from the
+     * `byline_document_version_locales` ledger. For each version returns the
+     * concrete locales its content is complete in (`availableLocales`, sorted),
+     * or `localeAgnostic: true` when the version carries only the `'all'`
+     * sentinel (no localized content → renders identically in every locale).
+     * Drives the `_availableVersionLocales` read metadata. One indexed query per call.
      */
-    buildLocaleChain(requestedLocale) {
-        const requested = requestedLocale ?? this.defaultContentLocale;
-        return requested === this.defaultContentLocale
-            ? [requested]
-            : [requested, this.defaultContentLocale];
+    async getAvailableLocalesByVersion(versionIds) {
+        const result = new Map();
+        if (versionIds.length === 0)
+            return result;
+        const rows = await this.db
+            .select({
+            vid: documentVersionLocales.document_version_id,
+            locale: documentVersionLocales.locale,
+        })
+            .from(documentVersionLocales)
+            .where(inArray(documentVersionLocales.document_version_id, versionIds));
+        for (const row of rows) {
+            let entry = result.get(row.vid);
+            if (entry == null) {
+                entry = { availableLocales: [], localeAgnostic: false };
+                result.set(row.vid, entry);
+            }
+            if (row.locale === 'all')
+                entry.localeAgnostic = true;
+            else
+                entry.availableLocales.push(row.locale);
+        }
+        for (const entry of result.values())
+            entry.availableLocales.sort();
+        return result;
+    }
+    /**
+     * Batch-fetch the editorial advertised-locale sets from
+     * `byline_document_available_locales` (document-grain). For each logical
+     * document returns the sorted set of locales the editor has elected to
+     * advertise. Surfaced on reads as `availableLocales` — the deliberate
+     * counterpart to the version-grain `_availableVersionLocales` ledger fact;
+     * the public advertised set is their intersection. One indexed query per
+     * call. See docs/I18N.md.
+     */
+    async getAdvertisedLocalesByDocument(documentIds) {
+        const result = new Map();
+        if (documentIds.length === 0)
+            return result;
+        const rows = await this.db
+            .select({
+            did: documentAvailableLocales.document_id,
+            locale: documentAvailableLocales.locale,
+        })
+            .from(documentAvailableLocales)
+            .where(inArray(documentAvailableLocales.document_id, documentIds));
+        for (const row of rows) {
+            let arr = result.get(row.did);
+            if (arr == null) {
+                arr = [];
+                result.set(row.did, arr);
+            }
+            arr.push(row.locale);
+        }
+        for (const arr of result.values())
+            arr.sort();
+        return result;
     }
     /**
      * Emit a SQL fragment that resolves the path string for a document via
@@ -119,13 +209,21 @@ export class DocumentQueries {
      *  LIMIT 1)
      * ```
      */
-    pathProjection(documentIdCol, requestedLocale) {
-        const chain = this.buildLocaleChain(requestedLocale);
-        // Build a `ARRAY[$1, $2, ...]::text[]` literal so each locale is its
-        // own parameter. Passing a JS array as a single `${chain}` placeholder
+    pathProjection(documentIdCol, requestedLocale, sourceLocaleCol) {
+        // The fallback floor: the row's `source_locale` column when supplied
+        // (COALESCE-guarded for not-yet-anchored NULL rows), otherwise the
+        // configured global default. The chain is `[requested, floor]`; a runtime
+        // duplicate (requested === floor) is harmless — `array_position` picks the
+        // first match and `LIMIT 1` collapses it.
+        const floorSql = sourceLocaleCol
+            ? sql `COALESCE(${sourceLocaleCol}, ${this.defaultContentLocale})`
+            : sql `${this.defaultContentLocale}`;
+        const requestedSql = requestedLocale != null ? sql `${requestedLocale}` : floorSql;
+        // Build a `ARRAY[$1, $2]::text[]` literal so each locale is its own
+        // parameter. Passing a JS array as a single `${chain}` placeholder
         // serialises as a scalar string (`'en'`), which Postgres rejects when
         // cast to `text[]` ("malformed array literal").
-        const chainSql = sql.join(chain.map((l) => sql `${l}`), sql `, `);
+        const chainSql = sql.join([requestedSql, floorSql], sql `, `);
         return sql `(
       SELECT ${documentPaths.path} FROM ${documentPaths}
       WHERE ${documentPaths.document_id} = ${documentIdCol}
@@ -155,7 +253,8 @@ export class DocumentQueries {
             updated_at: view.updated_at,
             created_by: view.created_by,
             change_summary: view.change_summary,
-            path: this.pathProjection(sql `${view.document_id}`, requestedLocale),
+            source_locale: view.source_locale,
+            path: this.pathProjection(sql `${view.document_id}`, requestedLocale, sql `${view.source_locale}`),
         };
     }
     /**
@@ -165,6 +264,11 @@ export class DocumentQueries {
      * the locale priority chain, since it no longer lives on the version row.
      */
     documentVersionsProjection(requestedLocale) {
+        // `source_locale` lives on `byline_documents` (document-grain), not the
+        // version row — resolve it via a correlated subquery so point-in-time
+        // history reads re-base their fallback floor onto the document's anchor,
+        // consistent with the current-documents views.
+        const sourceLocaleSql = sql `(SELECT source_locale FROM byline_documents WHERE id = ${documentVersions.document_id})`;
         return {
             id: documentVersions.id,
             document_id: documentVersions.document_id,
@@ -177,7 +281,8 @@ export class DocumentQueries {
             updated_at: documentVersions.updated_at,
             created_by: documentVersions.created_by,
             change_summary: documentVersions.change_summary,
-            path: this.pathProjection(sql `${documentVersions.document_id}`, requestedLocale),
+            source_locale: sourceLocaleSql,
+            path: this.pathProjection(sql `${documentVersions.document_id}`, requestedLocale, sourceLocaleSql),
         };
     }
     /**
@@ -210,6 +315,52 @@ export class DocumentQueries {
       LIMIT 1
     )`;
     }
+    /**
+     * 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.
+     *
+     * Phase-1 availability rule — **path-coverage against the default locale**:
+     * the default (terminal) locale defines the canonical set of localized field
+     * paths; a candidate locale `L` is available iff it covers every one of them.
+     * This needs only the rows already in hand (no schema walk) and is correct
+     * because Byline shares document structure across locales (meta rows are
+     * `'all'`) — only leaf values vary per locale.
+     *
+     * Edge cases: an empty canonical set (the version has no localized content)
+     * means any requested locale is trivially available, so the requested locale
+     * is returned and the (non-localized, `'all'`) values render identically. The
+     * chain always terminates at the default locale, guaranteeing a return value.
+     */
+    resolveEffectiveLocale(flattenedData, chain) {
+        // biome-ignore lint/style/noNonNullAssertion: chain is non-empty by construction
+        const defaultLocale = chain[chain.length - 1];
+        // Localized field paths present, grouped by locale. Skip `'all'` rows
+        // (non-localized values + meta) — they don't participate in coverage.
+        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; // terminal — return default below
+            // No canonical localized content → any locale is trivially available.
+            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
@@ -223,7 +374,7 @@ export class DocumentQueries {
      * how to surface them (the admin edit path uses this to render a
      * "best-effort load" banner against an out-of-date document).
      */
-    reconstructFromUnifiedRows(unifiedFieldValues, definition, locale, metaRows, lenient = false) {
+    reconstructFromUnifiedRows(unifiedFieldValues, definition, locale, metaRows, lenient = false, onMissingLocale, sourceLocale) {
         const flattenedData = unifiedFieldValues.map((row) => extractFlattenedFieldValue(row));
         if (metaRows) {
             for (const meta of metaRows) {
@@ -236,7 +387,17 @@ export class DocumentQueries {
                 });
             }
         }
-        const resolveLocale = locale !== 'all' ? locale : undefined;
+        // Concrete locale: with `onMissingLocale: 'fallback'`, restore the whole
+        // document in a single effective locale chosen from the fallback chain
+        // (never mixing locales across fields). Otherwise restore the requested
+        // locale exactly — empty where untranslated, the raw per-locale view the
+        // admin editor needs (`'empty'`/`'omit'`/unset). `'all'` keeps the
+        // per-locale map shape (admin multi-locale read).
+        const resolveLocale = locale === 'all'
+            ? undefined
+            : onMissingLocale === 'fallback'
+                ? this.resolveEffectiveLocale(flattenedData, this.buildLocaleChain(locale, sourceLocale))
+                : locale;
         const { data, warnings } = restoreFieldSetData(definition.fields, flattenedData, resolveLocale);
         if (!lenient && warnings.length > 0) {
             throw ERR_DATABASE({
@@ -286,7 +447,7 @@ 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, }) {
+    async getDocumentById({ collection_id, document_id, locale = 'en', reconstruct = true, readMode, filters, lenient = false, onMissingLocale, }) {
         const view = this.pickCurrentView(readMode);
         // 1. Get current version (or current published version, per readMode)
         const baseConditions = [
@@ -298,12 +459,18 @@ export class DocumentQueries {
                 docVersionId: sql `${view.id}`,
                 documentId: sql `${view.document_id}`,
                 status: sql `${view.status}`,
-                path: this.pathProjection(sql `${view.document_id}`, locale),
+                path: this.pathProjection(sql `${view.document_id}`, locale, sql `${view.source_locale}`),
             };
             for (const f of filters) {
                 baseConditions.push(this.buildFilterExists(f, locale, outerScope, readMode, 0));
             }
         }
+        // `onMissingLocale: 'omit'` — resolve to null when the document is not
+        // available in the requested locale (no version-locale ledger row).
+        const strictGate = this.localeAvailabilityExists(sql `${view.id}`, locale, onMissingLocale);
+        if (strictGate) {
+            baseConditions.push(strictGate);
+        }
         const [document] = await this.db
             .select(this.viewProjection(view, locale))
             .from(view)
@@ -312,7 +479,7 @@ export class DocumentQueries {
             return null;
         }
         // 2. Get all field values for this document
-        const unifiedFieldValues = await this.getAllFieldValues(document.id, locale);
+        const unifiedFieldValues = await this.getAllFieldValues(document.id, locale, document.source_locale);
         // 3. If reconstruct is true, reconstruct the fields and attach meta
         if (reconstruct === true) {
             const definition = await this.getDefinitionForCollection(collection_id);
@@ -325,15 +492,21 @@ export class DocumentQueries {
             })
                 .from(metaStore)
                 .where(eq(metaStore.document_version_id, document.id));
-            const { fields, warnings } = this.reconstructFromUnifiedRows(unifiedFieldValues, definition, locale, metaRows, lenient);
+            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);
             return {
                 document_version_id: document.id,
                 document_id: document.document_id,
                 path: document.path ?? '',
+                source_locale: document.source_locale ?? null,
                 status: document.status,
                 created_at: document.created_at,
                 updated_at: document.updated_at,
                 fields,
+                availableLocales: advertised ?? [],
+                _availableVersionLocales: availability?.availableLocales ?? [],
+                _localeAgnostic: availability?.localeAgnostic ?? false,
                 ...(lenient && warnings.length > 0 ? { restoreWarnings: warnings } : {}),
             };
         }
@@ -343,13 +516,14 @@ export class DocumentQueries {
             document_version_id: document.id,
             document_id: document.document_id,
             path: document.path ?? '',
+            source_locale: document.source_locale ?? null,
             status: document.status,
             created_at: document.created_at,
             updated_at: document.updated_at,
             fields: fieldValues,
         };
     }
-    async getDocumentByPath({ collection_id, path, locale = 'en', reconstruct = true, readMode, filters, }) {
+    async getDocumentByPath({ collection_id, path, locale = 'en', reconstruct = true, readMode, filters, onMissingLocale, }) {
         const view = this.pickCurrentView(readMode);
         // 1. Get current version (or current published version, per readMode)
         //
@@ -366,12 +540,18 @@ export class DocumentQueries {
                 docVersionId: sql `${view.id}`,
                 documentId: sql `${view.document_id}`,
                 status: sql `${view.status}`,
-                path: this.pathProjection(sql `${view.document_id}`, locale),
+                path: this.pathProjection(sql `${view.document_id}`, locale, sql `${view.source_locale}`),
             };
             for (const f of filters) {
                 baseConditions.push(this.buildFilterExists(f, locale, outerScope, readMode, 0));
             }
         }
+        // `onMissingLocale: 'omit'` — resolve to null when the document is not
+        // available in the requested locale (no version-locale ledger row).
+        const strictGate = this.localeAvailabilityExists(sql `${view.id}`, locale, onMissingLocale);
+        if (strictGate) {
+            baseConditions.push(strictGate);
+        }
         const [document] = await this.db
             .select(this.viewProjection(view, locale))
             .from(view)
@@ -380,7 +560,7 @@ export class DocumentQueries {
             return null;
         }
         // 2. Get all field values for this document
-        const unifiedFieldValues = await this.getAllFieldValues(document.id, locale);
+        const unifiedFieldValues = await this.getAllFieldValues(document.id, locale, document.source_locale);
         // 3. If reconstruct is true, reconstruct the fields and attach meta
         if (reconstruct === true) {
             const definition = await this.getDefinitionForCollection(collection_id);
@@ -393,15 +573,21 @@ export class DocumentQueries {
             })
                 .from(metaStore)
                 .where(eq(metaStore.document_version_id, document.id));
-            const { fields } = this.reconstructFromUnifiedRows(unifiedFieldValues, definition, locale, metaRows);
+            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);
             return {
                 document_version_id: document.id,
                 document_id: document.document_id,
                 path: document.path ?? '',
+                source_locale: document.source_locale ?? null,
                 status: document.status,
                 created_at: document.created_at,
                 updated_at: document.updated_at,
                 fields,
+                availableLocales: advertised ?? [],
+                _availableVersionLocales: availability?.availableLocales ?? [],
+                _localeAgnostic: availability?.localeAgnostic ?? false,
             };
         }
         // Non-reconstructed: return raw flattened values
@@ -410,6 +596,7 @@ export class DocumentQueries {
             document_version_id: document.id,
             document_id: document.document_id,
             path: document.path ?? '',
+            source_locale: document.source_locale ?? null,
             status: document.status,
             created_at: document.created_at,
             updated_at: document.updated_at,
@@ -431,7 +618,7 @@ export class DocumentQueries {
                 details: { documentVersionId: document_version_id },
             }).log(getLogger());
         }
-        const unifiedFieldValues = await this.getAllFieldValues(document.id, locale);
+        const unifiedFieldValues = await this.getAllFieldValues(document.id, locale, document.source_locale);
         const definition = await this.getDefinitionForCollection(document.collection_id);
         const metaRows = await this.db
             .select({
@@ -442,11 +629,12 @@ export class DocumentQueries {
         })
             .from(metaStore)
             .where(eq(metaStore.document_version_id, document.id));
-        const { fields } = this.reconstructFromUnifiedRows(unifiedFieldValues, definition, locale, metaRows);
+        const { fields } = this.reconstructFromUnifiedRows(unifiedFieldValues, definition, locale, metaRows, false, undefined, document.source_locale);
         const documentWithFields = {
             document_version_id: document.id,
             document_id: document.document_id,
             path: document.path ?? '',
+            source_locale: document.source_locale ?? null,
             status: document.status,
             created_at: document.created_at,
             updated_at: document.updated_at,
@@ -500,7 +688,7 @@ export class DocumentQueries {
                 docVersionId: sql `${view.id}`,
                 documentId: sql `${view.document_id}`,
                 status: sql `${view.status}`,
-                path: this.pathProjection(sql `${view.document_id}`, filterLocale),
+                path: this.pathProjection(sql `${view.document_id}`, filterLocale, sql `${view.source_locale}`),
             };
             for (const f of filters) {
                 baseConditions.push(this.buildFilterExists(f, filterLocale, outerScope, readMode, 0));
@@ -510,7 +698,15 @@ export class DocumentQueries {
             .select(this.viewProjection(view, filterLocale))
             .from(view)
             .where(and(...baseConditions));
-        return this.reconstructDocuments({ documents: docs, locale, fields });
+        // Populated relation targets always fall back through the locale chain so
+        // a populated tree never has holes — independent of the outer read's
+        // `onMissingLocale`. (A no-op when `locale === 'all'`, which keeps the map.)
+        return this.reconstructDocuments({
+            documents: docs,
+            locale,
+            fields,
+            onMissingLocale: 'fallback',
+        });
     }
     /**
      * getDocumentHistory — paginated version history for a document,
@@ -702,7 +898,7 @@ export class DocumentQueries {
      * reconstructDocuments — retrieve field values and reconstruct multiple documents.
      * Supports selective field loading via the `fields` parameter.
      */
-    async reconstructDocuments({ documents, locale = 'all', fields: requestedFields, }) {
+    async reconstructDocuments({ documents, locale = 'all', fields: requestedFields, onMissingLocale, }) {
         if (documents.length === 0)
             return [];
         const versionIds = documents.map((v) => v.id);
@@ -714,8 +910,14 @@ export class DocumentQueries {
         const storeTypes = requestedFields?.length
             ? resolveStoreTypes(definition.fields, requestedFields)
             : undefined;
+        // The distinct fallback floors for the batch — each document's own
+        // `source_locale` anchor — so the field fetch pulls every locale a row in
+        // this page might fall back to, not just the global default.
+        const floorLocales = [
+            ...new Set(documents.map((d) => d.source_locale).filter((l) => l != null)),
+        ];
         // Get field values for all versions in one query
-        const allFieldValues = await this.getAllFieldValuesForMultipleVersions(versionIds, locale, storeTypes);
+        const allFieldValues = await this.getAllFieldValuesForMultipleVersions(versionIds, locale, storeTypes, floorLocales);
         // Group field values by document version
         const fieldValuesByVersion = new Map();
         for (const fieldValue of allFieldValues) {
@@ -753,7 +955,7 @@ export class DocumentQueries {
         for (const doc of documents) {
             const versionFieldValues = fieldValuesByVersion.get(doc.id) || [];
             const docMetaRows = (metaByVersion.get(doc.id) ?? []);
-            const { fields } = this.reconstructFromUnifiedRows(versionFieldValues, definition, locale, docMetaRows);
+            const { fields } = this.reconstructFromUnifiedRows(versionFieldValues, definition, locale, docMetaRows, false, onMissingLocale, doc.source_locale);
             // 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)
@@ -765,6 +967,7 @@ export class DocumentQueries {
                 document_version_id: doc.id,
                 document_id: doc.document_id,
                 path: doc.path ?? '',
+                source_locale: doc.source_locale ?? null,
                 status: doc.status,
                 created_at: doc.created_at,
                 updated_at: doc.updated_at,
@@ -778,8 +981,8 @@ export class DocumentQueries {
      * Gets all field values for a single document version.
      * Delegates to the multi-version dynamic UNION ALL builder.
      */
-    async getAllFieldValues(documentVersionId, locale = 'all') {
-        return this.getAllFieldValuesForMultipleVersions([documentVersionId], locale);
+    async getAllFieldValues(documentVersionId, locale = 'all', sourceLocale) {
+        return this.getAllFieldValuesForMultipleVersions([documentVersionId], locale, undefined, sourceLocale ? [sourceLocale] : undefined);
     }
     /**
      * Gets field values for multiple versions in a single query.
@@ -788,10 +991,24 @@ export class DocumentQueries {
      * the UNION ALL — this is the selective field loading optimisation for
      * list views that only need a subset of fields.
      */
-    async getAllFieldValuesForMultipleVersions(documentVersionIds, locale = 'all', storeTypes) {
+    async getAllFieldValuesForMultipleVersions(documentVersionIds, locale = 'all', storeTypes, floorLocales) {
         if (documentVersionIds.length === 0)
             return [];
-        const localeCondition = locale === 'all' ? sql `` : sql `AND (locale = ${locale} OR locale = 'all')`;
+        // For a concrete locale, fetch the requested locale plus every fallback
+        // floor in the batch, plus non-localized `'all'` rows. The floors are the
+        // documents' own `source_locale` anchors (passed by the caller, which has
+        // them on the row) so a document authored in a non-default locale still
+        // has its fallback rows fetched; they default to the global default when
+        // unknown. Per-version effective-locale resolution (see
+        // `resolveEffectiveLocale`) then picks one locale to restore from. `'all'`
+        // skips the filter (admin multi-locale read).
+        let localeCondition = sql ``;
+        if (locale !== 'all') {
+            const floors = floorLocales?.length ? floorLocales : [this.defaultContentLocale];
+            const chain = [...new Set([locale, ...floors])];
+            const chainSql = sql.join(chain.map((l) => sql `${l}`), sql `, `);
+            localeCondition = sql `AND (locale = ANY(ARRAY[${chainSql}]::text[]) OR locale = 'all')`;
+        }
         const documentCondition = sql `document_version_id = ANY(ARRAY[${sql.join(documentVersionIds.map((id) => sql `${id}::uuid`), sql `, `)}])`;
         const typesToQuery = storeTypes ?? new Set(allStoreTypes);
         // Build UNION ALL from only the required store tables.
@@ -824,7 +1041,7 @@ export class DocumentQueries {
      * Document-level 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, }) {
+    async findDocuments({ collection_id, filters = [], status, pathFilter, query, sort, orderBy = 'created_at', orderDirection = 'desc', locale = 'en', page = 1, pageSize = 20, fields: requestedFields, readMode, onMissingLocale, }) {
         const offset = (page - 1) * pageSize;
         const sourceTable = readMode === 'published'
             ? sql.raw('byline_current_published_documents')
@@ -834,8 +1051,14 @@ export class DocumentQueries {
         if (status) {
             conditions.push(sql `d.status = ${status}`);
         }
+        // `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);
+        if (strictGate) {
+            conditions.push(strictGate);
+        }
         if (pathFilter) {
-            conditions.push(this.buildFilterCondition(this.pathProjection(sql `d.document_id`, locale), pathFilter.operator, pathFilter.value));
+            conditions.push(this.buildFilterCondition(this.pathProjection(sql `d.document_id`, locale, sql `d.source_locale`), pathFilter.operator, pathFilter.value));
         }
         // Text search across configured search fields via EXISTS on store_text.
         if (query) {
@@ -857,7 +1080,7 @@ export class DocumentQueries {
                 docVersionId: sql `d.id`,
                 documentId: sql `d.document_id`,
                 status: sql `d.status`,
-                path: this.pathProjection(sql `d.document_id`, locale),
+                path: this.pathProjection(sql `d.document_id`, locale, sql `d.source_locale`),
             }, readMode, 0));
         }
         const whereClause = sql.join(conditions, sql ` AND `);
@@ -907,7 +1130,7 @@ export class DocumentQueries {
         // keyed by document_id + locale). Project it via the locale-aware
         // subquery so the result rows still carry `path` for the in-memory
         // Document shape.
-        const pathProjectionSql = this.pathProjection(sql `d.document_id`, locale);
+        const pathProjectionSql = this.pathProjection(sql `d.document_id`, locale, sql `d.source_locale`);
         const mainQuery = sql `
       SELECT d.*, ${pathProjectionSql} AS path
       FROM ${sourceTable} d
@@ -931,12 +1154,25 @@ export class DocumentQueries {
             updated_at: new Date(row.updated_at),
             created_by: row.created_by,
             change_summary: row.change_summary,
+            source_locale: row.source_locale ?? null,
         }));
         const documents = await this.reconstructDocuments({
             documents: currentDocuments,
             locale,
             fields: requestedFields,
+            onMissingLocale,
         });
+        // 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 };
     }
     /**
@@ -1047,8 +1283,9 @@ export class DocumentQueries {
             documentId: sql.raw(`td${depth}.document_id`),
             status: sql.raw(`td${depth}.status`),
             // `td${depth}.path` no longer exists on the view; resolve via the
-            // locale priority chain against byline_document_paths instead.
-            path: this.pathProjection(sql.raw(`td${depth}.document_id`), locale),
+            // 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`)),
         };
         const nestedConditions = filter.nested.map((nested) => this.buildFilterExists(nested, locale, innerScope, readMode, depth + 1));
         const nestedAnd = nestedConditions.length > 0 ? sql ` AND ${sql.join(nestedConditions, sql ` AND `)}` : sql ``;

package/dist/modules/storage/tests/storage-document-available-locales.test.d.ts

@@ -0,0 +1,8 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+export {};