@byline/db-postgres 2.6.1 → 3.0.0

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

@@ -5,9 +5,9 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
-import { and, eq, ne, sql } from 'drizzle-orm';
+import { and, desc, eq, ne, sql } from 'drizzle-orm';
 import { v7 as uuidv7 } from 'uuid';
-import { booleanStore, collections, datetimeStore, documentPaths, documents, documentVersions, fileStore, jsonStore, metaStore, numericStore, relationStore, textStore, } from '../../database/schema/index.js';
+import { booleanStore, collections, datetimeStore, documentAvailableLocales, documentPaths, documents, documentVersionLocales, documentVersions, fileStore, jsonStore, metaStore, numericStore, relationStore, textStore, } from '../../database/schema/index.js';
 import { flattenFieldSetData } from './storage-flatten.js';
 import { prepareFieldInsertBuckets } from './storage-insert.js';
 import { getFirstOrThrow } from './storage-utils.js';
@@ -68,19 +68,39 @@ export class DocumentCommands {
     async createDocumentVersion(params) {
         return await this.db.transaction(async (tx) => {
             let documentId = params.documentId;
-            // 1. Create the main document if needed
+            // 1. Create the main document if needed, and resolve the document's
+            // `source_locale` — its per-document data anchor. A brand-new document
+            // is anchored to the configured default content locale (the locale it is
+            // authored in; `createDocument` enforces create-in-default). An existing
+            // document carries its own anchor on `byline_documents`; read it so the
+            // path row and the completeness ledger below key off *this document's*
+            // source locale rather than the mutable global default. NULL (a row not
+            // yet touched by `backfillSourceLocales`) falls back to the configured
+            // default — the value it was implicitly authored against.
+            // See docs/DEFAULT-LOCALE-SWITCHING.md.
+            let sourceLocale;
             if (documentId == null) {
                 documentId = uuidv7();
+                sourceLocale = this.defaultContentLocale;
                 const _document = await tx
                     .insert(documents)
                     .values({
                     id: documentId,
                     collection_id: params.collectionId,
                     order_key: params.orderKey ?? null,
+                    source_locale: sourceLocale,
                 })
                     .returning()
                     .then(getFirstOrThrow('Failed to create document'));
             }
+            else {
+                const existing = await tx
+                    .select({ source_locale: documents.source_locale })
+                    .from(documents)
+                    .where(eq(documents.id, documentId))
+                    .then(getFirstOrThrow('Failed to load document for new version'));
+                sourceLocale = existing.source_locale ?? this.defaultContentLocale;
+            }
             // 2. Create the document version
             const documentVersion = await tx
                 .insert(documentVersions)
@@ -94,18 +114,20 @@ export class DocumentCommands {
             })
                 .returning()
                 .then(getFirstOrThrow('Failed to create document version'));
-            // 2a. Upsert the document_paths row when a path is supplied. Path
-            // is only ever written under the installation's default content
-            // locale in phase 1; the lifecycle layer skips this param for
-            // non-default-locale (translation) saves. Unique-constraint
-            // violations on (collection_id, locale, path) bubble up as a
-            // Postgres error which the lifecycle wraps as ERR_PATH_CONFLICT.
+            // 2a. Upsert the document_paths row when a path is supplied. The path
+            // row lives under the document's `source_locale` (its data anchor),
+            // not the mutable global default — so a re-anchored document, or any
+            // document read after the global default is switched, still resolves by
+            // path. The lifecycle layer skips this param for non-source-locale
+            // (translation) saves. Unique-constraint violations on
+            // (collection_id, locale, path) bubble up as a Postgres error which the
+            // lifecycle wraps as ERR_PATH_CONFLICT.
             if (params.path !== undefined) {
                 await tx
                     .insert(documentPaths)
                     .values({
                     document_id: documentId,
-                    locale: this.defaultContentLocale,
+                    locale: sourceLocale,
                     collection_id: params.collectionId,
                     path: params.path,
                 })
@@ -118,6 +140,25 @@ export class DocumentCommands {
                     },
                 });
             }
+            // 2b. Replace the document_available_locales rows when an editorial set
+            // is supplied. Document-grain and sticky across versions: `undefined`
+            // leaves the existing set untouched (the lifecycle omits the param on
+            // saves that don't touch advertising), while an explicit array — empty
+            // included — replaces it wholesale. Deduplicated so a caller-supplied
+            // duplicate doesn't collide on the (document_id, locale) primary key.
+            if (params.availableLocales !== undefined) {
+                await tx
+                    .delete(documentAvailableLocales)
+                    .where(eq(documentAvailableLocales.document_id, documentId));
+                const locales = [...new Set(params.availableLocales)];
+                if (locales.length > 0) {
+                    await tx.insert(documentAvailableLocales).values(locales.map((locale) => ({
+                        document_id: documentId,
+                        locale,
+                        collection_id: params.collectionId,
+                    })));
+                }
+            }
             // 3. Flatten the document data to field values
             const flattenedFields = flattenFieldSetData(params.collectionConfig.fields, params.documentData, params.locale ?? 'all');
             // 4. Batch-insert all field values, grouped by store type
@@ -223,12 +264,349 @@ export class DocumentCommands {
           ON CONFLICT (document_version_id, field_path, locale) DO NOTHING
         `);
             }
+            // 6. Record the version's available content locales for
+            // `localeFallback: 'strict'` reads. A locale is "available" when it
+            // covers every localized field path the default content locale has
+            // (path-coverage). Derived from the *persisted* localized rows, so it
+            // accounts for the per-locale carry-forward in step 5 — not just the
+            // freshly-flattened locale. A version with no localized content at all
+            // records a single `'all'` sentinel (it renders identically in any
+            // locale). Status-blind by design — see docs/CONTENT-LOCALE-RESOLUTION.md.
+            await this.writeVersionLocaleLedger(tx, documentVersion.id, sourceLocale);
             return {
                 document: documentVersion,
                 fieldCount: flattenedFields.length,
             };
         });
     }
+    /**
+     * writeVersionLocaleLedger
+     *
+     * Compute and insert a version's `byline_document_version_locales` rows: a
+     * locale is recorded when it covers every localized field path the version's
+     * `sourceLocale` has (path-coverage), and a version with no localized content
+     * records a single `'all'` sentinel. Reads the version's persisted store rows,
+     * so callers must have written them first. Shared by the create write path
+     * (step 6) and `reAnchorDocument` (which recomputes against the new source).
+     * Assumes the version has no ledger rows yet (a freshly-inserted version).
+     * See docs/CONTENT-LOCALE-RESOLUTION.md and docs/DEFAULT-LOCALE-SWITCHING.md.
+     */
+    async writeVersionLocaleLedger(tx, versionId, sourceLocale) {
+        await tx.execute(sql `
+      WITH loc AS (
+        SELECT field_path, locale FROM byline_store_text     WHERE document_version_id = ${versionId}::uuid AND locale <> 'all'
+        UNION SELECT field_path, locale FROM byline_store_numeric  WHERE document_version_id = ${versionId}::uuid AND locale <> 'all'
+        UNION SELECT field_path, locale FROM byline_store_boolean  WHERE document_version_id = ${versionId}::uuid AND locale <> 'all'
+        UNION SELECT field_path, locale FROM byline_store_datetime WHERE document_version_id = ${versionId}::uuid AND locale <> 'all'
+        UNION SELECT field_path, locale FROM byline_store_file     WHERE document_version_id = ${versionId}::uuid AND locale <> 'all'
+        UNION SELECT field_path, locale FROM byline_store_relation WHERE document_version_id = ${versionId}::uuid AND locale <> 'all'
+        UNION SELECT field_path, locale FROM byline_store_json     WHERE document_version_id = ${versionId}::uuid AND locale <> 'all'
+      ),
+      canonical AS (
+        SELECT field_path FROM loc WHERE locale = ${sourceLocale}
+      ),
+      covering AS (
+        SELECT l.locale
+        FROM loc l
+        GROUP BY l.locale
+        HAVING NOT EXISTS (
+          SELECT 1 FROM canonical c
+          WHERE NOT EXISTS (
+            SELECT 1 FROM loc l2 WHERE l2.locale = l.locale AND l2.field_path = c.field_path
+          )
+        )
+      )
+      INSERT INTO byline_document_version_locales (document_version_id, locale)
+      SELECT ${versionId}::uuid, locale FROM covering
+      UNION ALL
+      SELECT ${versionId}::uuid, 'all' WHERE NOT EXISTS (SELECT 1 FROM loc)
+    `);
+    }
+    /**
+     * copyAllVersionStoreRows
+     *
+     * Copy every store row — all eight tables, all locales, including the `meta`
+     * identity rows (so block / array-item `_id`s are preserved) — from one
+     * document version to another, verbatim. New `id`s are minted; the target
+     * `document_version_id` is rebound; timestamps are refreshed. The target
+     * version is assumed fresh (no rows), so no conflict handling is needed.
+     * Used by `reAnchorDocument` to snapshot the current version into the new
+     * re-anchored one without re-flattening (lossless, identity-preserving).
+     */
+    async copyAllVersionStoreRows(tx, fromVersionId, toVersionId) {
+        const from = sql `${fromVersionId}::uuid`;
+        const to = sql `${toVersionId}::uuid`;
+        await tx.execute(sql `
+      INSERT INTO byline_store_text
+        (id, document_version_id, collection_id, field_path, field_name, locale, parent_path, value, word_count, created_at, updated_at)
+      SELECT gen_random_uuid(), ${to}, collection_id, field_path, field_name, locale, parent_path, value, word_count, NOW(), NOW()
+      FROM byline_store_text WHERE document_version_id = ${from}
+    `);
+        await tx.execute(sql `
+      INSERT INTO byline_store_numeric
+        (id, document_version_id, collection_id, field_path, field_name, locale, parent_path, number_type, value_integer, value_decimal, value_float, created_at, updated_at)
+      SELECT gen_random_uuid(), ${to}, collection_id, field_path, field_name, locale, parent_path, number_type, value_integer, value_decimal, value_float, NOW(), NOW()
+      FROM byline_store_numeric WHERE document_version_id = ${from}
+    `);
+        await tx.execute(sql `
+      INSERT INTO byline_store_boolean
+        (id, document_version_id, collection_id, field_path, field_name, locale, parent_path, value, created_at, updated_at)
+      SELECT gen_random_uuid(), ${to}, collection_id, field_path, field_name, locale, parent_path, value, NOW(), NOW()
+      FROM byline_store_boolean WHERE document_version_id = ${from}
+    `);
+        await tx.execute(sql `
+      INSERT INTO byline_store_datetime
+        (id, document_version_id, collection_id, field_path, field_name, locale, parent_path, date_type, value_date, value_time, value_timestamp_tz, created_at, updated_at)
+      SELECT gen_random_uuid(), ${to}, collection_id, field_path, field_name, locale, parent_path, date_type, value_date, value_time, value_timestamp_tz, NOW(), NOW()
+      FROM byline_store_datetime WHERE document_version_id = ${from}
+    `);
+        await tx.execute(sql `
+      INSERT INTO byline_store_json
+        (id, document_version_id, collection_id, field_path, field_name, locale, parent_path, value, json_schema, object_keys, created_at, updated_at)
+      SELECT gen_random_uuid(), ${to}, collection_id, field_path, field_name, locale, parent_path, value, json_schema, object_keys, NOW(), NOW()
+      FROM byline_store_json WHERE document_version_id = ${from}
+    `);
+        await tx.execute(sql `
+      INSERT INTO byline_store_relation
+        (id, document_version_id, collection_id, field_path, field_name, locale, parent_path, target_document_id, target_collection_id, relationship_type, cascade_delete, created_at, updated_at)
+      SELECT gen_random_uuid(), ${to}, collection_id, field_path, field_name, locale, parent_path, target_document_id, target_collection_id, relationship_type, cascade_delete, NOW(), NOW()
+      FROM byline_store_relation WHERE document_version_id = ${from}
+    `);
+        await tx.execute(sql `
+      INSERT INTO byline_store_file
+        (id, document_version_id, collection_id, field_path, field_name, locale, parent_path, file_id, filename, original_filename, mime_type, file_size, file_hash, storage_provider, storage_path, storage_url, image_width, image_height, image_format, processing_status, thumbnail_generated, created_at, updated_at)
+      SELECT gen_random_uuid(), ${to}, collection_id, field_path, field_name, locale, parent_path, file_id, filename, original_filename, mime_type, file_size, file_hash, storage_provider, storage_path, storage_url, image_width, image_height, image_format, processing_status, thumbnail_generated, NOW(), NOW()
+      FROM byline_store_file WHERE document_version_id = ${from}
+    `);
+        await tx.execute(sql `
+      INSERT INTO byline_store_meta
+        (id, document_version_id, collection_id, type, path, item_id, meta, created_at, updated_at)
+      SELECT gen_random_uuid(), ${to}, collection_id, type, path, item_id, meta, NOW(), NOW()
+      FROM byline_store_meta WHERE document_version_id = ${from}
+    `);
+    }
+    /**
+     * reAnchorDocument
+     *
+     * Change a single document's content source locale to `targetLocale` — its
+     * fallback floor, path locale, and completeness yardstick. Refuses unless the
+     * document is **complete** in the target (the current version's ledger covers
+     * it, or the document is locale-agnostic) — never manufactures a primary
+     * language with holes. In one transaction: flips `source_locale`, moves the
+     * path row onto the new locale (keeping the slug), writes a **new version**
+     * that is a verbatim copy of the current one (immutable version event,
+     * identities preserved), and computes that version's ledger against the new
+     * source. `dryRun` performs only the eligibility check and reports the
+     * outcome that *would* result, writing nothing. See
+     * docs/DEFAULT-LOCALE-SWITCHING.md.
+     */
+    async reAnchorDocument(params) {
+        const { documentId, targetLocale, dryRun = false } = params;
+        return this.db.transaction(async (tx) => {
+            // 1. Current (latest, non-deleted) version + the document's anchor.
+            const current = await tx
+                .select({
+                versionId: documentVersions.id,
+                collectionId: documentVersions.collection_id,
+                collectionVersion: documentVersions.collection_version,
+                status: documentVersions.status,
+                sourceLocale: documents.source_locale,
+            })
+                .from(documentVersions)
+                .innerJoin(documents, eq(documents.id, documentVersions.document_id))
+                .where(and(eq(documentVersions.document_id, documentId), eq(documentVersions.is_deleted, false)))
+                .orderBy(desc(documentVersions.id))
+                .limit(1)
+                .then((rows) => rows[0]);
+            if (current == null) {
+                return { documentId, status: 'not-found', toLocale: targetLocale };
+            }
+            const fromLocale = current.sourceLocale ?? this.defaultContentLocale;
+            if (fromLocale === targetLocale) {
+                return { documentId, status: 'already-anchored', fromLocale, toLocale: targetLocale };
+            }
+            // 2. Eligibility: the current version must be complete in the target —
+            //    its ledger contains the target locale, or it is locale-agnostic
+            //    (the `'all'` sentinel → renders identically in any locale).
+            const ledgerRows = await tx
+                .select({ locale: documentVersionLocales.locale })
+                .from(documentVersionLocales)
+                .where(eq(documentVersionLocales.document_version_id, current.versionId));
+            const ledger = new Set(ledgerRows.map((r) => r.locale));
+            const complete = ledger.has(targetLocale) || ledger.has('all');
+            if (!complete) {
+                return { documentId, status: 'skipped-incomplete', fromLocale, toLocale: targetLocale };
+            }
+            if (dryRun) {
+                return { documentId, status: 'reanchored', fromLocale, toLocale: targetLocale };
+            }
+            // 3. Flip the document's content anchor.
+            await tx
+                .update(documents)
+                .set({ source_locale: targetLocale })
+                .where(eq(documents.id, documentId));
+            // 4. Move the path row onto the new source locale (re-tag the slug, do
+            //    not regenerate it — the document's URL is unchanged).
+            await tx
+                .update(documentPaths)
+                .set({ locale: targetLocale, updated_at: new Date() })
+                .where(and(eq(documentPaths.document_id, documentId), eq(documentPaths.locale, fromLocale)));
+            // 5. New immutable version: a verbatim snapshot of the current version.
+            const newVersionId = uuidv7();
+            await tx.insert(documentVersions).values({
+                id: newVersionId,
+                document_id: documentId,
+                collection_id: current.collectionId,
+                collection_version: current.collectionVersion,
+                event_type: 'update',
+                status: current.status ?? 'draft',
+                change_summary: `re-anchored content source locale ${fromLocale} → ${targetLocale}`,
+            });
+            await this.copyAllVersionStoreRows(tx, current.versionId, newVersionId);
+            // 6. Ledger for the new version, computed against the new source locale.
+            await this.writeVersionLocaleLedger(tx, newVersionId, targetLocale);
+            return { documentId, status: 'reanchored', fromLocale, toLocale: targetLocale, newVersionId };
+        });
+    }
+    /**
+     * reAnchorDocuments
+     *
+     * Bulk re-anchor: walk every (non-deleted) logical document — optionally
+     * scoped to one collection — and re-anchor each that is complete in
+     * `targetLocale`, skipping (and reporting) the rest. Each document runs in its
+     * own transaction via `reAnchorDocument`, so one failure or skip never rolls
+     * back the others; the command is idempotent and resumable. This is the
+     * "client switched the default content locale, move every fully-translated
+     * document onto it" operation; the `skipped-incomplete` results double as the
+     * outstanding-translation backlog. `dryRun` reports what would happen without
+     * writing. See docs/DEFAULT-LOCALE-SWITCHING.md.
+     */
+    async reAnchorDocuments(params) {
+        const { targetLocale, collectionId, dryRun = false } = params;
+        const conditions = [eq(documentVersions.is_deleted, false)];
+        if (collectionId) {
+            conditions.push(eq(documentVersions.collection_id, collectionId));
+        }
+        const docs = await this.db
+            .selectDistinct({ documentId: documentVersions.document_id })
+            .from(documentVersions)
+            .where(and(...conditions));
+        const report = {
+            targetLocale,
+            dryRun,
+            total: docs.length,
+            reanchored: 0,
+            skippedIncomplete: 0,
+            alreadyAnchored: 0,
+            notFound: 0,
+            results: [],
+        };
+        for (const { documentId } of docs) {
+            const result = await this.reAnchorDocument({ documentId, targetLocale, dryRun });
+            report.results.push(result);
+            switch (result.status) {
+                case 'reanchored':
+                    report.reanchored++;
+                    break;
+                case 'skipped-incomplete':
+                    report.skippedIncomplete++;
+                    break;
+                case 'already-anchored':
+                    report.alreadyAnchored++;
+                    break;
+                case 'not-found':
+                    report.notFound++;
+                    break;
+            }
+        }
+        return report;
+    }
+    /**
+     * backfillVersionLocales
+     *
+     * One-time maintenance: populate `byline_document_version_locales` for
+     * versions written *before* the ledger existed (i.e. before the migration
+     * that added it). Going forward `createDocumentVersion` step 6 keeps the
+     * ledger current; this fills the historical gap so `localeFallback:
+     * 'strict'` reads can see pre-existing documents.
+     *
+     * Same path-coverage rule as the write path, applied set-wise across every
+     * version in one statement. The `canonical` anchor is each document's own
+     * `source_locale` (joined via `byline_document_versions` → `byline_documents`),
+     * falling back to the adapter's configured default content locale for rows
+     * not yet stamped by `backfillSourceLocales` — mirroring the per-document
+     * anchor the write path uses, rather than a single global locale. Idempotent
+     * — safe to re-run (PK + `ON CONFLICT DO NOTHING`); versions are immutable, so
+     * a version's computed locale set never changes. Returns the number of
+     * `(version, locale)` rows inserted.
+     *
+     * See docs/CONTENT-LOCALE-RESOLUTION.md.
+     */
+    async backfillVersionLocales() {
+        const result = await this.db.execute(sql `
+      WITH loc AS (
+        SELECT document_version_id, field_path, locale FROM byline_store_text     WHERE locale <> 'all'
+        UNION SELECT document_version_id, field_path, locale FROM byline_store_numeric  WHERE locale <> 'all'
+        UNION SELECT document_version_id, field_path, locale FROM byline_store_boolean  WHERE locale <> 'all'
+        UNION SELECT document_version_id, field_path, locale FROM byline_store_datetime WHERE locale <> 'all'
+        UNION SELECT document_version_id, field_path, locale FROM byline_store_file     WHERE locale <> 'all'
+        UNION SELECT document_version_id, field_path, locale FROM byline_store_relation WHERE locale <> 'all'
+        UNION SELECT document_version_id, field_path, locale FROM byline_store_json     WHERE locale <> 'all'
+      ),
+      canonical AS (
+        SELECT l.document_version_id, l.field_path
+        FROM loc l
+        JOIN byline_document_versions v ON v.id = l.document_version_id
+        JOIN byline_documents d ON d.id = v.document_id
+        WHERE l.locale = COALESCE(d.source_locale, ${this.defaultContentLocale})
+      ),
+      covering AS (
+        SELECT l.document_version_id, l.locale
+        FROM loc l
+        GROUP BY l.document_version_id, l.locale
+        HAVING NOT EXISTS (
+          SELECT 1 FROM canonical c
+          WHERE c.document_version_id = l.document_version_id
+            AND NOT EXISTS (
+              SELECT 1 FROM loc l2
+              WHERE l2.document_version_id = l.document_version_id
+                AND l2.locale = l.locale
+                AND l2.field_path = c.field_path
+            )
+        )
+      )
+      INSERT INTO byline_document_version_locales (document_version_id, locale)
+      SELECT document_version_id, locale FROM covering
+      UNION ALL
+      SELECT v.id, 'all' FROM byline_document_versions v
+      WHERE NOT EXISTS (SELECT 1 FROM loc WHERE loc.document_version_id = v.id)
+      ON CONFLICT DO NOTHING
+    `);
+        return { rowsInserted: result.rowCount ?? 0 };
+    }
+    /**
+     * backfillSourceLocales
+     *
+     * One-time maintenance: stamp `byline_documents.source_locale` for documents
+     * created *before* the column existed. Sets every row whose `source_locale`
+     * is still NULL to the adapter's configured default content locale — the
+     * anchor those documents were implicitly authored against (a static SQL
+     * migration cannot know the configured default, mirroring
+     * `backfillVersionLocales`). Idempotent: only touches NULL rows, so re-runs
+     * and rows already stamped by the write path are left alone. Must run before
+     * the follow-up migration that sets the column NOT NULL.
+     *
+     * Returns the number of document rows stamped.
+     *
+     * See docs/DEFAULT-LOCALE-SWITCHING.md.
+     */
+    async backfillSourceLocales() {
+        const result = await this.db
+            .update(documents)
+            .set({ source_locale: this.defaultContentLocale })
+            .where(sql `${documents.source_locale} IS NULL`);
+        return { rowsUpdated: result.rowCount ?? 0 };
+    }
     /**
      * setDocumentStatus
      *

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

@@ -5,7 +5,7 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
-import type { CollectionDefinition, DocumentFilter, FieldSort, ICollectionQueries, IDocumentQueries, ReadMode } from '@byline/core';
+import type { CollectionDefinition, DocumentFilter, FieldSort, FlattenedStore, ICollectionQueries, IDocumentQueries, MissingLocalePolicy, ReadMode } from '@byline/core';
 import type { NodePgDatabase } from 'drizzle-orm/node-postgres';
 import type * as schema from '../../database/schema/index.js';
 type DatabaseConnection = NodePgDatabase<typeof schema>;
@@ -78,16 +78,44 @@ export declare class DocumentQueries implements IDocumentQueries {
      */
     private pickCurrentView;
     /**
-     * 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/DEFAULT-LOCALE-SWITCHING.md.
      */
     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.
+     */
+    private localeAvailabilityExists;
+    /**
+     * 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.
+     */
+    private getAvailableLocalesByVersion;
+    /**
+     * 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/AVAILABLE-LOCALES.md.
+     */
+    private getAdvertisedLocalesByDocument;
     /**
      * Emit a SQL fragment that resolves the path string for a document via
      * the locale priority chain. Used as a projected column expression
@@ -137,6 +165,24 @@ export declare class DocumentQueries implements IDocumentQueries {
      * outer `=` predicate fail cleanly (no document found).
      */
     private resolveDocumentIdByPath;
+    /**
+     * 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.
+     */
+    private resolveEffectiveLocale;
     /**
      * Reconstruct document fields from unified row values using schema-aware
      * restoration. Meta rows (from store_meta) are converted to
@@ -178,7 +224,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, }: {
+    getDocumentById({ collection_id, document_id, locale, reconstruct, readMode, filters, lenient, onMissingLocale, }: {
         collection_id: string;
         document_id: string;
         locale?: string;
@@ -186,31 +232,62 @@ export declare class DocumentQueries implements IDocumentQueries {
         readMode?: ReadMode;
         filters?: DocumentFilter[];
         lenient?: boolean;
+        onMissingLocale?: MissingLocalePolicy;
     }): Promise<{
         restoreWarnings?: string[] | undefined;
         document_version_id: string;
         document_id: string;
         path: string;
+        source_locale: string;
         status: string | null;
         created_at: Date;
         updated_at: Date;
         fields: any;
+        availableLocales: string[];
+        _availableVersionLocales: string[];
+        _localeAgnostic: boolean;
+    } | {
+        document_version_id: string;
+        document_id: string;
+        path: string;
+        source_locale: string;
+        status: string | null;
+        created_at: Date;
+        updated_at: Date;
+        fields: FlattenedStore[];
     } | null>;
-    getDocumentByPath({ collection_id, path, locale, reconstruct, readMode, filters, }: {
+    getDocumentByPath({ collection_id, path, locale, reconstruct, readMode, filters, onMissingLocale, }: {
         collection_id: string;
         path: string;
         locale?: string;
         reconstruct: boolean;
         readMode?: ReadMode;
         filters?: DocumentFilter[];
+        onMissingLocale?: MissingLocalePolicy;
     }): Promise<{
         document_version_id: string;
         document_id: string;
         path: string;
+        source_locale: string;
         status: string | null;
         created_at: Date;
         updated_at: Date;
         fields: any;
+        availableLocales: string[];
+        _availableVersionLocales: string[];
+        _localeAgnostic: boolean;
+    } | {
+        document_version_id: string;
+        document_id: string;
+        path: string;
+        source_locale: string;
+        status: string | null;
+        created_at: Date;
+        updated_at: Date;
+        fields: FlattenedStore[];
+        availableLocales?: undefined;
+        _availableVersionLocales?: undefined;
+        _localeAgnostic?: undefined;
     } | null>;
     /**
      * getDocumentByVersion — fetches a specific version and reconstructs its fields.
@@ -392,7 +469,7 @@ export declare class DocumentQueries implements IDocumentQueries {
      * Document-level 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, }: {
+    findDocuments({ collection_id, filters, status, pathFilter, query, sort, orderBy, orderDirection, locale, page, pageSize, fields: requestedFields, readMode, onMissingLocale, }: {
         collection_id: string;
         filters?: DocumentFilter[];
         status?: string;
@@ -409,6 +486,7 @@ export declare class DocumentQueries implements IDocumentQueries {
         pageSize?: number;
         fields?: string[];
         readMode?: ReadMode;
+        onMissingLocale?: MissingLocalePolicy;
     }): Promise<{
         documents: any[];
         total: number;