@byline/db-postgres 2.7.0 → 3.0.1

package/dist/database/schema/index.d.ts

@@ -260,6 +260,25 @@ export declare const documents: import("drizzle-orm/pg-core").PgTableWithColumns
         }, {}, {
             pgColumnBuilderBrand: "PgCustomColumnBuilderBrand";
         }>;
+        source_locale: import("drizzle-orm/pg-core").PgColumn<{
+            name: "source_locale";
+            tableName: "byline_documents";
+            dataType: "string";
+            columnType: "PgVarchar";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: 10;
+        }>;
     };
     dialect: "pg";
 }>;
@@ -591,6 +610,143 @@ export declare const documentPaths: import("drizzle-orm/pg-core").PgTableWithCol
     };
     dialect: "pg";
 }>;
+export declare const documentAvailableLocales: import("drizzle-orm/pg-core").PgTableWithColumns<{
+    name: "byline_document_available_locales";
+    schema: undefined;
+    columns: {
+        created_at: import("drizzle-orm/pg-core").PgColumn<{
+            name: string;
+            tableName: "byline_document_available_locales";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        updated_at: import("drizzle-orm/pg-core").PgColumn<{
+            name: string;
+            tableName: "byline_document_available_locales";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        document_id: import("drizzle-orm/pg-core").PgColumn<{
+            name: "document_id";
+            tableName: "byline_document_available_locales";
+            dataType: "string";
+            columnType: "PgUUID";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        locale: import("drizzle-orm/pg-core").PgColumn<{
+            name: "locale";
+            tableName: "byline_document_available_locales";
+            dataType: "string";
+            columnType: "PgVarchar";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: 10;
+        }>;
+        collection_id: import("drizzle-orm/pg-core").PgColumn<{
+            name: "collection_id";
+            tableName: "byline_document_available_locales";
+            dataType: "string";
+            columnType: "PgUUID";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+    };
+    dialect: "pg";
+}>;
+export declare const documentVersionLocales: import("drizzle-orm/pg-core").PgTableWithColumns<{
+    name: "byline_document_version_locales";
+    schema: undefined;
+    columns: {
+        document_version_id: import("drizzle-orm/pg-core").PgColumn<{
+            name: "document_version_id";
+            tableName: "byline_document_version_locales";
+            dataType: "string";
+            columnType: "PgUUID";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        locale: import("drizzle-orm/pg-core").PgColumn<{
+            name: "locale";
+            tableName: "byline_document_version_locales";
+            dataType: "string";
+            columnType: "PgVarchar";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: 10;
+        }>;
+    };
+    dialect: "pg";
+}>;
 export declare const documentRelationships: import("drizzle-orm/pg-core").PgTableWithColumns<{
     name: "byline_document_relationships";
     schema: undefined;
@@ -854,6 +1010,23 @@ export declare const currentDocumentsView: import("drizzle-orm/pg-core").PgViewW
         identity: undefined;
         generated: undefined;
     }, {}, {}>;
+    source_locale: import("drizzle-orm/pg-core").PgColumn<{
+        name: "source_locale";
+        tableName: "byline_current_documents";
+        dataType: "string";
+        columnType: "PgVarchar";
+        data: string;
+        driverParam: string;
+        notNull: true;
+        hasDefault: false;
+        isPrimaryKey: false;
+        isAutoincrement: false;
+        hasRuntimeDefault: false;
+        enumValues: [string, ...string[]];
+        baseColumn: never;
+        identity: undefined;
+        generated: undefined;
+    }, {}, {}>;
 }>;
 export declare const currentPublishedDocumentsView: import("drizzle-orm/pg-core").PgViewWithSelection<"byline_current_published_documents", false, {
     id: import("drizzle-orm/pg-core").PgColumn<{
@@ -1060,6 +1233,23 @@ export declare const currentPublishedDocumentsView: import("drizzle-orm/pg-core"
         identity: undefined;
         generated: undefined;
     }, {}, {}>;
+    source_locale: import("drizzle-orm/pg-core").PgColumn<{
+        name: "source_locale";
+        tableName: "byline_current_published_documents";
+        dataType: "string";
+        columnType: "PgVarchar";
+        data: string;
+        driverParam: string;
+        notNull: true;
+        hasDefault: false;
+        isPrimaryKey: false;
+        isAutoincrement: false;
+        hasRuntimeDefault: false;
+        enumValues: [string, ...string[]];
+        baseColumn: never;
+        identity: undefined;
+        generated: undefined;
+    }, {}, {}>;
 }>;
 export declare const textStore: import("drizzle-orm/pg-core").PgTableWithColumns<{
     name: "byline_store_text";

package/dist/database/schema/index.js

@@ -6,7 +6,7 @@
  * Copyright (c) Infonomic Company Limited
  */
 import { eq, relations, sql } from 'drizzle-orm';
-import { bigint, boolean, customType, date, decimal, index, integer, jsonb, pgTable, pgView, real, text, time, timestamp, unique, uuid, varchar, } from 'drizzle-orm/pg-core';
+import { bigint, boolean, customType, date, decimal, index, integer, jsonb, pgTable, pgView, primaryKey, real, text, time, timestamp, unique, uuid, varchar, } from 'drizzle-orm/pg-core';
 import { createdAt, timestamps } from './common.js';
 /**
  * `varchar(...)` with explicit byte-wise (C) collation.
@@ -63,6 +63,16 @@ export const documents = pgTable('byline_documents', {
     // comparison — the fractional-index algorithm requires this. See
     // `varcharByteSorted` above and docs/COLLECTIONS.md (Orderable collections).
     order_key: varcharByteSorted('order_key', { length: 128 }),
+    // The content locale this document was first authored in — its per-document
+    // data anchor. Set once at creation (= the global default content locale at
+    // that moment) and immutable in normal operation; changed only by the
+    // deliberate re-anchor operation. Re-bases the fallback floor, the path
+    // locale, and the completeness ledger off the mutable global config onto
+    // the document's own truth, so switching `i18n.content.defaultLocale` no
+    // longer silently re-interprets existing data. Backfilled by
+    // `backfillSourceLocales()` (boot-auto via initBylineCore).
+    //
+    source_locale: varchar('source_locale', { length: 10 }).notNull(),
     ...timestamps,
 }, (table) => [
     index('idx_documents_collection').on(table.collection_id),
@@ -129,6 +139,46 @@ export const documentPaths = pgTable('byline_document_paths', {
     // Reverse lookup by document.
     index('idx_document_paths_document_id').on(table.document_id),
 ]);
+// Document → advertised content locales. One row per (logical document,
+// advertised locale) — the editorial "advertise these locales" set an editor
+// curates per document. The deliberate counterpart to the derived,
+// version-grained `byline_document_version_locales` ledger: this is intent
+// ("I want these advertised"), the ledger is fact ("this version is complete
+// in these"). Document-grain and sticky across versions — editorial intent
+// carries forward across edits and survives restore. Surfaced on reads as
+// `availableLocales`; the public advertised set is the intersection with the
+// ledger's `_availableVersionLocales`. Replaced wholesale on write (the lifecycle
+// deletes then re-inserts the set), never appended. See docs/I18N.md.
+export const documentAvailableLocales = pgTable('byline_document_available_locales', {
+    document_id: uuid('document_id')
+        .notNull()
+        .references(() => documents.id, { onDelete: 'cascade' }),
+    locale: varchar('locale', { length: 10 }).notNull(),
+    collection_id: uuid('collection_id')
+        .notNull()
+        .references(() => collections.id, { onDelete: 'cascade' }),
+    ...timestamps,
+}, (table) => [
+    // One row per (logical document, advertised locale).
+    primaryKey({ columns: [table.document_id, table.locale] }),
+    // Reverse lookup by document for the read projection.
+    index('idx_document_available_locales_document_id').on(table.document_id),
+]);
+// Document version → available content locales. One row per (version, locale)
+// for every locale the version's content is *complete* in — path-coverage
+// against the default content locale: a locale is recorded only when it covers
+// every localized field path the default locale has. A version with no
+// localized content at all gets a single `'all'` sentinel row (it renders
+// identically in any locale). Computed status-blind at write time and frozen
+// on the immutable version, so restore / point-in-time reads stay consistent.
+// Drives `localeFallback: 'strict'` reads via an indexed EXISTS gate without
+// scanning the store_* tables. See docs/I18N.md.
+export const documentVersionLocales = pgTable('byline_document_version_locales', {
+    document_version_id: uuid('document_version_id')
+        .notNull()
+        .references(() => documentVersions.id, { onDelete: 'cascade' }),
+    locale: varchar('locale', { length: 10 }).notNull(),
+}, (table) => [primaryKey({ columns: [table.document_version_id, table.locale] })]);
 // Document Relationships (Parent/Child) - Many-to-Many
 export const documentRelationships = pgTable('byline_document_relationships', {
     // Note: These reference the logical `document_id`, not the version `id`.
@@ -194,6 +244,12 @@ export const currentDocumentsView = pgView('byline_current_documents').as((qb) =
         created_by: sq.created_by,
         change_summary: sq.change_summary,
         order_key: documents.order_key,
+        // The document's content-locale anchor, projected here so locale-aware
+        // read paths (`buildLocaleChain` / `pathProjection` / field-fallback)
+        // re-base onto the per-document source rather than the mutable global
+        // default — a primary-key join, already present for `order_key`.
+        // See docs/I18N.md.
+        source_locale: documents.source_locale,
     })
         .from(sq)
         .innerJoin(documents, eq(documents.id, sq.document_id))
@@ -237,6 +293,9 @@ export const currentPublishedDocumentsView = pgView('byline_current_published_do
         created_by: sq.created_by,
         change_summary: sq.change_summary,
         order_key: documents.order_key,
+        // See `currentDocumentsView` — the per-document content-locale anchor,
+        // carried for locale-aware reads. PK join, already present.
+        source_locale: documents.source_locale,
     })
         .from(sq)
         .innerJoin(documents, eq(documents.id, sq.document_id))

package/dist/index.d.ts

@@ -9,6 +9,8 @@ import type { CollectionDefinition, IDbAdapter } from '@byline/core';
 import { type NodePgDatabase } from 'drizzle-orm/node-postgres';
 import pg from 'pg';
 import * as schema from './database/schema/index.js';
+import { type ReAnchorReport, type ReAnchorResult } from './modules/storage/storage-commands.js';
+export type { ReAnchorReport, ReAnchorResult, ReAnchorStatus, } from './modules/storage/storage-commands.js';
 /**
  * Public return type of `pgAdapter`. Extends `IDbAdapter` with concrete
  * Drizzle + pg handles so integrations that need the raw database (the
@@ -23,16 +25,65 @@ export interface PgAdapter extends IDbAdapter {
     drizzle: NodePgDatabase<typeof schema>;
     /** The pg connection pool — exposed for housekeeping and teardown. */
     pool: pg.Pool;
+    /**
+     * One-time maintenance: populate the version-locale availability ledger
+     * (`byline_document_version_locales`) for versions written before it
+     * existed, so `localeFallback: 'strict'` reads can see pre-existing
+     * documents. Idempotent; uses the configured default content locale. Kept
+     * off the core `IDbAdapter` contract (no service depends on it) — see
+     * docs/I18N.md.
+     */
+    backfillVersionLocales(): Promise<{
+        rowsInserted: number;
+    }>;
+    /**
+     * One-time maintenance: stamp `byline_documents.source_locale` for documents
+     * created before the column existed, setting NULL rows to the configured
+     * default content locale (the anchor they were implicitly authored against).
+     * Idempotent; run automatically at boot by `initBylineCore` (also exposed on
+     * the core `IDbAdapter` contract as an optional method) — see
+     * docs/I18N.md.
+     */
+    backfillSourceLocales(): Promise<{
+        rowsUpdated: number;
+    }>;
+    /**
+     * Re-anchor 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. Writes a new immutable
+     * version. `dryRun` reports the would-be outcome without writing. Off the
+     * core `IDbAdapter` contract (maintenance/admin operation) — see
+     * docs/I18N.md.
+     */
+    reAnchorDocument(params: {
+        documentId: string;
+        targetLocale: string;
+        dryRun?: boolean;
+    }): Promise<ReAnchorResult>;
+    /**
+     * Bulk re-anchor every fully-translated document (optionally within one
+     * collection) onto `targetLocale`, skipping and reporting the rest. Each
+     * document is its own transaction — idempotent and resumable. This is the
+     * "switched the default content locale, move everything that's ready" command.
+     */
+    reAnchorDocuments(params: {
+        targetLocale: string;
+        collectionId?: string;
+        dryRun?: boolean;
+    }): Promise<ReAnchorReport>;
 }
 export declare const pgAdapter: ({ connectionString, collections, defaultContentLocale, max, idleTimeoutMillis, connectionTimeoutMillis, }: {
     connectionString: string;
     collections: CollectionDefinition[];
     /**
      * The installation's default content locale, sourced from
-     * `ServerConfig.i18n.content.defaultLocale`. Used by the storage layer
-     * for path resolution: read functions build a `[requested, default]`
-     * fallback chain when looking up `byline_document_paths`, and write
-     * functions tag default-locale path rows with this value.
+     * `ServerConfig.i18n.content.defaultLocale`. Used by the storage layer as
+     * the **fallback** anchor only: new documents are stamped with it as their
+     * `source_locale`, and it is the floor for row-less lookups (findByPath) and
+     * for documents whose `source_locale` is not yet backfilled. Per-document
+     * reads and writes otherwise re-base onto each document's own `source_locale`
+     * (carried on the current-documents views), so changing this value does not
+     * re-interpret existing data. See docs/I18N.md.
      */
     defaultContentLocale: string;
     /**

package/dist/index.js

@@ -9,7 +9,7 @@ import { drizzle } from 'drizzle-orm/node-postgres';
 import pg from 'pg';
 import * as schema from './database/schema/index.js';
 import { createCounterCommands } from './modules/counters/counters-commands.js';
-import { createCommandBuilders } from './modules/storage/storage-commands.js';
+import { createCommandBuilders, } from './modules/storage/storage-commands.js';
 import { createQueryBuilders } from './modules/storage/storage-queries.js';
 export const pgAdapter = ({ connectionString, collections, defaultContentLocale, max = 20, idleTimeoutMillis = 2000, connectionTimeoutMillis = 30000, }) => {
     const pool = new pg.Pool({
@@ -30,5 +30,9 @@ export const pgAdapter = ({ connectionString, collections, defaultContentLocale,
         queries: queryBuilders,
         drizzle: db,
         pool,
+        backfillVersionLocales: () => commandBuilders.documents.backfillVersionLocales(),
+        backfillSourceLocales: () => commandBuilders.documents.backfillSourceLocales(),
+        reAnchorDocument: (params) => commandBuilders.documents.reAnchorDocument(params),
+        reAnchorDocuments: (params) => commandBuilders.documents.reAnchorDocuments(params),
     };
 };

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

@@ -9,6 +9,29 @@ import type { CollectionDefinition, ICollectionCommands, IDocumentCommands } fro
 import type { NodePgDatabase } from 'drizzle-orm/node-postgres';
 import type * as schema from '../../database/schema/index.js';
 type DatabaseConnection = NodePgDatabase<typeof schema>;
+/** Outcome of re-anchoring a single document's content source locale. */
+export type ReAnchorStatus = 'reanchored' | 'skipped-incomplete' | 'already-anchored' | 'not-found';
+export interface ReAnchorResult {
+    documentId: string;
+    status: ReAnchorStatus;
+    /** The document's source locale before the operation (when known). */
+    fromLocale?: string;
+    /** The target source locale. */
+    toLocale: string;
+    /** The new version id written on a successful re-anchor. */
+    newVersionId?: string;
+}
+export interface ReAnchorReport {
+    targetLocale: string;
+    dryRun: boolean;
+    total: number;
+    reanchored: number;
+    skippedIncomplete: number;
+    alreadyAnchored: number;
+    notFound: number;
+    /** Per-document outcomes, for logging / inspection. */
+    results: ReAnchorResult[];
+}
 /**
  * CollectionCommands
  */
@@ -70,11 +93,20 @@ export declare class DocumentCommands implements IDocumentCommands {
         documentData: any;
         /**
          * Optional. When provided, upserts a row into byline_document_paths
-         * keyed by (document_id, this.defaultContentLocale). Omitted by the
-         * lifecycle for non-default-locale (translation) saves so the
-         * existing path row is left untouched.
+         * keyed by (document_id, <document source_locale>). Omitted by the
+         * lifecycle for non-source-locale (translation) saves so the existing
+         * path row is left untouched.
          */
         path?: string;
+        /**
+         * Optional. When provided, replaces the document's advertised-locale set
+         * in byline_document_available_locales wholesale (delete-then-insert).
+         * `undefined` leaves the existing set untouched (sticky across versions,
+         * like `path`); an empty array clears it (advertise nothing). The locale
+         * values are the advertised content locales themselves, not the default
+         * locale. See docs/I18N.md.
+         */
+        availableLocales?: string[];
         locale?: string;
         status?: string;
         createdBy?: string;
@@ -97,6 +129,112 @@ export declare class DocumentCommands implements IDocumentCommands {
         };
         fieldCount: number;
     }>;
+    /**
+     * 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/I18N.md.
+     */
+    private writeVersionLocaleLedger;
+    /**
+     * 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).
+     */
+    private copyAllVersionStoreRows;
+    /**
+     * 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/I18N.md.
+     */
+    reAnchorDocument(params: {
+        documentId: string;
+        targetLocale: string;
+        dryRun?: boolean;
+    }): Promise<ReAnchorResult>;
+    /**
+     * 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/I18N.md.
+     */
+    reAnchorDocuments(params: {
+        targetLocale: string;
+        collectionId?: string;
+        dryRun?: boolean;
+    }): Promise<ReAnchorReport>;
+    /**
+     * 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/I18N.md.
+     */
+    backfillVersionLocales(): Promise<{
+        rowsInserted: number;
+    }>;
+    /**
+     * 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/I18N.md.
+     */
+    backfillSourceLocales(): Promise<{
+        rowsUpdated: number;
+    }>;
     /**
      * setDocumentStatus
      *