@byline/db-postgres 3.0.0 → 3.0.2

package/dist/database/schema/index.js

@@ -148,7 +148,7 @@ export const documentPaths = pgTable('byline_document_paths', {
 // 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/AVAILABLE-LOCALES.md.
+// 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()
@@ -172,7 +172,7 @@ export const documentAvailableLocales = pgTable('byline_document_available_local
 // 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/CONTENT-LOCALE-RESOLUTION.md.
+// scanning the store_* tables. See docs/I18N.md.
 export const documentVersionLocales = pgTable('byline_document_version_locales', {
     document_version_id: uuid('document_version_id')
         .notNull()
@@ -248,7 +248,7 @@ export const currentDocumentsView = pgView('byline_current_documents').as((qb) =
         // 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/DEFAULT-LOCALE-SWITCHING.md.
+        // See docs/I18N.md.
         source_locale: documents.source_locale,
     })
         .from(sq)

package/dist/index.d.ts

@@ -31,7 +31,7 @@ export interface PgAdapter extends IDbAdapter {
      * 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/CONTENT-LOCALE-RESOLUTION.md.
+     * docs/I18N.md.
      */
     backfillVersionLocales(): Promise<{
         rowsInserted: number;
@@ -42,7 +42,7 @@ export interface PgAdapter extends IDbAdapter {
      * 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/DEFAULT-LOCALE-SWITCHING.md.
+     * docs/I18N.md.
      */
     backfillSourceLocales(): Promise<{
         rowsUpdated: number;
@@ -53,7 +53,7 @@ export interface PgAdapter extends IDbAdapter {
      * 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/DEFAULT-LOCALE-SWITCHING.md.
+     * docs/I18N.md.
      */
     reAnchorDocument(params: {
         documentId: string;
@@ -83,7 +83,7 @@ export declare const pgAdapter: ({ connectionString, collections, defaultContent
      * 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/DEFAULT-LOCALE-SWITCHING.md.
+     * re-interpret existing data. See docs/I18N.md.
      */
     defaultContentLocale: string;
     /**

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

@@ -104,7 +104,7 @@ export declare class DocumentCommands implements IDocumentCommands {
          * `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/AVAILABLE-LOCALES.md.
+         * locale. See docs/I18N.md.
          */
         availableLocales?: string[];
         locale?: string;
@@ -139,7 +139,7 @@ export declare class DocumentCommands implements IDocumentCommands {
      * 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.
+     * See docs/I18N.md.
      */
     private writeVersionLocaleLedger;
     /**
@@ -152,8 +152,43 @@ export declare class DocumentCommands implements IDocumentCommands {
      * 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).
+     *
+     * When `excludeLocale` is provided, rows for that locale are skipped in the
+     * seven value-store tables — the carry-forward that powers `deleteDocumentLocale`
+     * (drop one locale's content, keep `'all'` + every other locale). The
+     * locale-agnostic `byline_store_meta` rows (block / array-item identities) are
+     * always copied wholesale, since a block's identity is shared across locales.
      */
     private copyAllVersionStoreRows;
+    /**
+     * deleteDocumentLocale
+     *
+     * Remove one content locale's data from a document by writing a **new
+     * immutable version** that carries forward every store row except the
+     * target locale's (the `'all'` rows and all other locales are kept). The
+     * prior version still holds the deleted locale, so the operation is
+     * recoverable via version restore, and a previously-published version keeps
+     * serving until the new version is published.
+     *
+     * The new version's status is supplied by the caller (the lifecycle service
+     * passes the workflow's default — a fresh draft, matching `copyToLocale`).
+     * The derived availability ledger is recomputed from the carried-forward
+     * rows, so the deleted locale drops out automatically. The default content
+     * locale (the document's anchor) must never be passed here — the lifecycle
+     * service enforces that.
+     *
+     * Mirrors `reAnchorDocument`'s new-version mechanics; defensively returns
+     * `null` when the document has no current version (the service validates
+     * existence first, so this is a guard).
+     */
+    deleteDocumentLocale(params: {
+        documentId: string;
+        locale: string;
+        status?: string;
+    }): Promise<{
+        newVersionId: string;
+        previousVersionId: string;
+    } | null>;
     /**
      * reAnchorDocument
      *
@@ -167,7 +202,7 @@ export declare class DocumentCommands implements IDocumentCommands {
      * 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.
+     * docs/I18N.md.
      */
     reAnchorDocument(params: {
         documentId: string;
@@ -185,7 +220,7 @@ export declare class DocumentCommands implements IDocumentCommands {
      * "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.
+     * writing. See docs/I18N.md.
      */
     reAnchorDocuments(params: {
         targetLocale: string;
@@ -211,7 +246,7 @@ export declare class DocumentCommands implements IDocumentCommands {
      * a version's computed locale set never changes. Returns the number of
      * `(version, locale)` rows inserted.
      *
-     * See docs/CONTENT-LOCALE-RESOLUTION.md.
+     * See docs/I18N.md.
      */
     backfillVersionLocales(): Promise<{
         rowsInserted: number;
@@ -230,7 +265,7 @@ export declare class DocumentCommands implements IDocumentCommands {
      *
      * Returns the number of document rows stamped.
      *
-     * See docs/DEFAULT-LOCALE-SWITCHING.md.
+     * See docs/I18N.md.
      */
     backfillSourceLocales(): Promise<{
         rowsUpdated: number;

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

@@ -77,7 +77,7 @@ export class DocumentCommands {
             // 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.
+            // See docs/I18N.md.
             let sourceLocale;
             if (documentId == null) {
                 documentId = uuidv7();
@@ -271,7 +271,7 @@ export class DocumentCommands {
             // 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.
+            // locale). Status-blind by design — see docs/I18N.md.
             await this.writeVersionLocaleLedger(tx, documentVersion.id, sourceLocale);
             return {
                 document: documentVersion,
@@ -289,7 +289,7 @@ export class DocumentCommands {
      * 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.
+     * See docs/I18N.md.
      */
     async writeVersionLocaleLedger(tx, versionId, sourceLocale) {
         await tx.execute(sql `
@@ -332,51 +332,61 @@ export class DocumentCommands {
      * 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).
+     *
+     * When `excludeLocale` is provided, rows for that locale are skipped in the
+     * seven value-store tables — the carry-forward that powers `deleteDocumentLocale`
+     * (drop one locale's content, keep `'all'` + every other locale). The
+     * locale-agnostic `byline_store_meta` rows (block / array-item identities) are
+     * always copied wholesale, since a block's identity is shared across locales.
      */
-    async copyAllVersionStoreRows(tx, fromVersionId, toVersionId) {
+    async copyAllVersionStoreRows(tx, fromVersionId, toVersionId, excludeLocale) {
         const from = sql `${fromVersionId}::uuid`;
         const to = sql `${toVersionId}::uuid`;
+        // Appended to each value-store WHERE so the dropped locale's rows are not
+        // carried into the new version. Empty fragment (copy everything) when no
+        // exclusion is requested — the `reAnchorDocument` snapshot path.
+        const localeFilter = excludeLocale ? sql ` AND locale <> ${excludeLocale}` : sql ``;
         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}
+      FROM byline_store_text WHERE document_version_id = ${from}${localeFilter}
     `);
         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}
+      FROM byline_store_numeric WHERE document_version_id = ${from}${localeFilter}
     `);
         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}
+      FROM byline_store_boolean WHERE document_version_id = ${from}${localeFilter}
     `);
         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}
+      FROM byline_store_datetime WHERE document_version_id = ${from}${localeFilter}
     `);
         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}
+      FROM byline_store_json WHERE document_version_id = ${from}${localeFilter}
     `);
         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}
+      FROM byline_store_relation WHERE document_version_id = ${from}${localeFilter}
     `);
         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}
+      FROM byline_store_file WHERE document_version_id = ${from}${localeFilter}
     `);
         await tx.execute(sql `
       INSERT INTO byline_store_meta
@@ -385,6 +395,67 @@ export class DocumentCommands {
       FROM byline_store_meta WHERE document_version_id = ${from}
     `);
     }
+    /**
+     * deleteDocumentLocale
+     *
+     * Remove one content locale's data from a document by writing a **new
+     * immutable version** that carries forward every store row except the
+     * target locale's (the `'all'` rows and all other locales are kept). The
+     * prior version still holds the deleted locale, so the operation is
+     * recoverable via version restore, and a previously-published version keeps
+     * serving until the new version is published.
+     *
+     * The new version's status is supplied by the caller (the lifecycle service
+     * passes the workflow's default — a fresh draft, matching `copyToLocale`).
+     * The derived availability ledger is recomputed from the carried-forward
+     * rows, so the deleted locale drops out automatically. The default content
+     * locale (the document's anchor) must never be passed here — the lifecycle
+     * service enforces that.
+     *
+     * Mirrors `reAnchorDocument`'s new-version mechanics; defensively returns
+     * `null` when the document has no current version (the service validates
+     * existence first, so this is a guard).
+     */
+    async deleteDocumentLocale(params) {
+        const { documentId, locale, status } = 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,
+                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 null;
+            const sourceLocale = current.sourceLocale ?? this.defaultContentLocale;
+            // 2. New immutable version: a snapshot of the current version with the
+            //    target locale's value rows dropped (meta + 'all' + other locales
+            //    carried forward).
+            const newVersionId = uuidv7();
+            await tx.insert(documentVersions).values({
+                id: newVersionId,
+                document_id: documentId,
+                collection_id: current.collectionId,
+                collection_version: current.collectionVersion,
+                event_type: 'delete_locale',
+                status: status ?? 'draft',
+                change_summary: `deleted content locale ${locale}`,
+            });
+            await this.copyAllVersionStoreRows(tx, current.versionId, newVersionId, locale);
+            // 3. Recompute the new version's availability ledger against the source
+            //    locale — the dropped locale no longer covers it, so it falls out.
+            await this.writeVersionLocaleLedger(tx, newVersionId, sourceLocale);
+            return { newVersionId, previousVersionId: current.versionId };
+        });
+    }
     /**
      * reAnchorDocument
      *
@@ -398,7 +469,7 @@ export class DocumentCommands {
      * 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.
+     * docs/I18N.md.
      */
     async reAnchorDocument(params) {
         const { documentId, targetLocale, dryRun = false } = params;
@@ -479,7 +550,7 @@ export class DocumentCommands {
      * "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.
+     * writing. See docs/I18N.md.
      */
     async reAnchorDocuments(params) {
         const { targetLocale, collectionId, dryRun = false } = params;
@@ -540,7 +611,7 @@ export class DocumentCommands {
      * a version's computed locale set never changes. Returns the number of
      * `(version, locale)` rows inserted.
      *
-     * See docs/CONTENT-LOCALE-RESOLUTION.md.
+     * See docs/I18N.md.
      */
     async backfillVersionLocales() {
         const result = await this.db.execute(sql `
@@ -598,7 +669,7 @@ export class DocumentCommands {
      *
      * Returns the number of document rows stamped.
      *
-     * See docs/DEFAULT-LOCALE-SWITCHING.md.
+     * See docs/I18N.md.
      */
     async backfillSourceLocales() {
         const result = await this.db

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

@@ -84,7 +84,7 @@ export declare class DocumentQueries implements IDocumentQueries {
      * 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.
+     * row-less lookups (findByPath). See docs/I18N.md.
      */
     private buildLocaleChain;
     /**
@@ -113,7 +113,7 @@ export declare class DocumentQueries implements IDocumentQueries {
      * 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.
+     * call. See docs/I18N.md.
      */
     private getAdvertisedLocalesByDocument;
     /**

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

@@ -105,7 +105,7 @@ export class DocumentQueries {
      * 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.
+     * row-less lookups (findByPath). See docs/I18N.md.
      */
     buildLocaleChain(requestedLocale, sourceLocale) {
         const floor = sourceLocale ?? this.defaultContentLocale;
@@ -171,7 +171,7 @@ export class DocumentQueries {
      * 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.
+     * call. See docs/I18N.md.
      */
     async getAdvertisedLocalesByDocument(documentIds) {
         const result = new Map();

package/dist/modules/storage/tests/storage-delete-locale.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 {};

package/dist/modules/storage/tests/storage-delete-locale.test.js

@@ -0,0 +1,155 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { setupTestDB, teardownTestDB } from '../../../lib/test-helper.js';
+let commandBuilders;
+let queryBuilders;
+const timestamp = Date.now();
+const DeleteLocaleCollectionConfig = {
+    path: `delete-locale-${timestamp}`,
+    labels: { singular: 'DeleteLocaleTest', plural: 'DeleteLocaleTests' },
+    fields: [
+        { name: 'title', type: 'text', localized: true },
+        // Non-localized → lives on `locale: 'all'` rows; must survive the delete.
+        { name: 'sku', type: 'text' },
+    ],
+};
+let testCollection = {};
+function readById(documentId, locale) {
+    return queryBuilders.documents.getDocumentById({
+        collection_id: testCollection.id,
+        document_id: documentId,
+        locale,
+    });
+}
+/**
+ * Create a fresh document with three localized titles (en/fr/de) and one
+ * shared non-localized field, returning the document id and the current
+ * (latest) version id.
+ */
+async function seedTrilingualDoc(titlePrefix) {
+    const v1 = await commandBuilders.documents.createDocumentVersion({
+        collectionId: testCollection.id,
+        collectionVersion: 1,
+        collectionConfig: DeleteLocaleCollectionConfig,
+        action: 'create',
+        documentData: { title: `${titlePrefix} EN`, sku: 'SKU-1' },
+        locale: 'en',
+        status: 'published',
+    });
+    const documentId = v1.document.document_id;
+    const v2 = await commandBuilders.documents.createDocumentVersion({
+        documentId,
+        collectionId: testCollection.id,
+        collectionVersion: 1,
+        collectionConfig: DeleteLocaleCollectionConfig,
+        action: 'update',
+        documentData: { title: `${titlePrefix} FR`, sku: 'SKU-1' },
+        locale: 'fr',
+        status: 'published',
+        previousVersionId: v1.document.id,
+    });
+    const v3 = await commandBuilders.documents.createDocumentVersion({
+        documentId,
+        collectionId: testCollection.id,
+        collectionVersion: 1,
+        collectionConfig: DeleteLocaleCollectionConfig,
+        action: 'update',
+        documentData: { title: `${titlePrefix} DE`, sku: 'SKU-1' },
+        locale: 'de',
+        status: 'published',
+        previousVersionId: v2.document.id,
+    });
+    return { documentId, currentVersionId: v3.document.id };
+}
+describe('deleteDocumentLocale integration', () => {
+    beforeAll(async () => {
+        const testDB = setupTestDB([DeleteLocaleCollectionConfig]);
+        commandBuilders = testDB.commandBuilders;
+        queryBuilders = testDB.queryBuilders;
+        const result = await commandBuilders.collections.create(DeleteLocaleCollectionConfig.path, DeleteLocaleCollectionConfig);
+        const collection = result[0];
+        if (collection == null) {
+            throw new Error('Failed to create test collection');
+        }
+        testCollection = { id: collection.id, name: collection.path };
+    });
+    afterAll(async () => {
+        try {
+            await commandBuilders.collections.delete(testCollection.id);
+        }
+        catch (error) {
+            console.error('Failed to cleanup test collection:', error);
+        }
+        await teardownTestDB();
+    });
+    it('drops the target locale from availability, keeps the others', async () => {
+        const { documentId } = await seedTrilingualDoc('Avail');
+        const before = await readById(documentId, 'en');
+        expect(before?._availableVersionLocales, 'all three locales present').toEqual([
+            'de',
+            'en',
+            'fr',
+        ]);
+        await commandBuilders.documents.deleteDocumentLocale({
+            documentId,
+            locale: 'fr',
+            status: 'draft',
+        });
+        const after = await readById(documentId, 'en');
+        expect(after?._availableVersionLocales, 'fr removed, de/en remain').toEqual(['de', 'en']);
+    });
+    it("keeps other locales' localized content and the shared non-localized field", async () => {
+        const { documentId } = await seedTrilingualDoc('Content');
+        await commandBuilders.documents.deleteDocumentLocale({
+            documentId,
+            locale: 'fr',
+            status: 'draft',
+        });
+        const de = await readById(documentId, 'de');
+        expect(de?.fields.title, 'de content untouched').toBe('Content DE');
+        expect(de?.fields.sku, "non-localized 'all' field preserved").toBe('SKU-1');
+        const en = await readById(documentId, 'en');
+        expect(en?.fields.title, 'default-locale content untouched').toBe('Content EN');
+    });
+    it('lands the new version with the supplied status (a fresh draft)', async () => {
+        const { documentId } = await seedTrilingualDoc('Status');
+        await commandBuilders.documents.deleteDocumentLocale({
+            documentId,
+            locale: 'fr',
+            status: 'draft',
+        });
+        const meta = await queryBuilders.documents.getCurrentVersionMetadata({
+            collection_id: testCollection.id,
+            document_id: documentId,
+        });
+        expect(meta?.status, 'delete-locale version is a draft').toBe('draft');
+    });
+    it('is recoverable — the prior version still holds the deleted locale', async () => {
+        const { documentId, currentVersionId } = await seedTrilingualDoc('Recover');
+        await commandBuilders.documents.deleteDocumentLocale({
+            documentId,
+            locale: 'fr',
+            status: 'draft',
+        });
+        // The pre-delete version is immutable and still carries the fr content.
+        const prior = (await queryBuilders.documents.getDocumentByVersion({
+            document_version_id: currentVersionId,
+            locale: 'fr',
+        }));
+        expect(prior?.fields.title, 'fr content survives in the prior version').toBe('Recover FR');
+    });
+    it('returns null for an unknown document', async () => {
+        const result = await commandBuilders.documents.deleteDocumentLocale({
+            documentId: crypto.randomUUID(),
+            locale: 'fr',
+            status: 'draft',
+        });
+        expect(result).toBeNull();
+    });
+});

package/dist/modules/storage/tests/storage-locale-fallback.test.js

@@ -278,26 +278,6 @@ describe('content-locale resolution & fallback', () => {
         const second = await commandBuilders.documents.backfillVersionLocales();
         expect(second.rowsInserted).toBe(0);
     });
-    it('backfillSourceLocales stamps NULL source_locale rows with the default locale', async () => {
-        const id = await createDoc({
-            title: { en: 'Hello', de: 'Hallo' },
-            body: { en: 'World', de: 'Welt' },
-            sku: 'S1',
-        });
-        // The write path now stamps source_locale on create (Slice 2), so simulate
-        // a row written before the column existed by nulling it — exactly the
-        // pre-existing-data shape backfill exists to repair.
-        await db.execute(sql `UPDATE byline_documents SET source_locale = NULL WHERE id = ${id}::uuid`);
-        const before = await db.execute(sql `SELECT source_locale FROM byline_documents WHERE id = ${id}::uuid`);
-        expect(before.rows[0].source_locale).toBeNull();
-        const result = await commandBuilders.documents.backfillSourceLocales();
-        expect(result.rowsUpdated).toBeGreaterThan(0);
-        const after = await db.execute(sql `SELECT source_locale FROM byline_documents WHERE id = ${id}::uuid`);
-        expect(after.rows[0].source_locale, 'stamped with the adapter default content locale (en)').toBe('en');
-        // Idempotent: a second run touches nothing (no NULL rows remain).
-        const second = await commandBuilders.documents.backfillSourceLocales();
-        expect(second.rowsUpdated).toBe(0);
-    });
     // --- source_locale write path (Slice 2) ----------------------------------
     it('records source_locale on create and writes the path row under it', async () => {
         const created = await commandBuilders.documents.createDocumentVersion({

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/db-postgres",
   "private": false,
   "license": "MPL-2.0",
-  "version": "3.0.0",
+  "version": "3.0.2",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -57,9 +57,9 @@
     "pg": "^8.21.0",
     "uuid": "^14.0.0",
     "zod": "^4.4.3",
-    "@byline/admin": "3.0.0",
-    "@byline/auth": "3.0.0",
-    "@byline/core": "3.0.0"
+    "@byline/admin": "3.0.2",
+    "@byline/auth": "3.0.2",
+    "@byline/core": "3.0.2"
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.15",