@byline/core 2.6.1 → 3.0.0

package/dist/@types/collection-types.d.ts

@@ -713,6 +713,25 @@ export interface CollectionDefinition {
      * without `useAsPath` receive a UUID `path` instead.
      */
     useAsPath?: string;
+    /**
+     * Opts this collection into the `availableLocales` editorial advertising
+     * control — the deliberate "advertise these content locales" set an editor
+     * curates per document, stored document-grain in
+     * `byline_document_available_locales` (mirrors `byline_document_paths`) and
+     * surfaced on reads as `availableLocales`. It is the editorial counterpart
+     * to the derived, ledger-backed `_availableVersionLocales` (path-coverage
+     * fact); the public advertised set is their intersection
+     * (`availableLocales ∩ _availableVersionLocales`).
+     *
+     * Like `useAsPath`, the value is system metadata edited via a non-field
+     * sidebar widget — `availableLocales` is a reserved name and cannot be
+     * declared as a field. Advertising locales is only meaningful when the
+     * collection has at least one `localized` field, so the validator rejects
+     * `advertiseLocales: true` on a collection with none.
+     *
+     * See `docs/AVAILABLE-LOCALES.md`.
+     */
+    advertiseLocales?: boolean;
     /**
      * Optional host-defined function that composes a renderable root-relative
      * path for a document in this collection. Called server-side by the

package/dist/@types/db-types.d.ts

@@ -16,6 +16,32 @@ import type { QueryPredicate } from './query-predicate.js';
  *                     defaults to this).
  */
 export type ReadMode = 'any' | 'published';
+/**
+ * What a read does when the requested content locale is missing (the value of
+ * the `onMissingLocale` read option).
+ *
+ *   - `'empty'`    — no field-level fallback. Restore the requested locale
+ *                    exactly, leaving untranslated localized fields empty. The
+ *                    raw per-locale view the admin editor needs (empty =
+ *                    "not translated yet"). The document is always returned.
+ *   - `'fallback'` — fall back through the locale chain to the default content
+ *                    locale, restoring the whole document in one effective
+ *                    locale (never mixing). A detail read still returns the
+ *                    document; a list read still includes it. The
+ *                    `@byline/client` default — public consumers "just work".
+ *   - `'omit'`     — only surface documents available in the requested locale.
+ *                    A detail read returns `null` (→ 404) when the requested
+ *                    locale is unavailable; a list read excludes such documents.
+ *                    Available documents restore the requested locale exactly.
+ *                    Backed by the `byline_document_version_locales` ledger.
+ *
+ * At the adapter layer an omitted value behaves as `'empty'` (exact-match, the
+ * safe default for internal/direct reads); `@byline/client` defaults it to
+ * `'fallback'` for application reads. Availability follows path-coverage against
+ * the default content locale; a document with no localized content is available
+ * in every locale. See `docs/CONTENT-LOCALE-RESOLUTION.md`.
+ */
+export type MissingLocalePolicy = 'empty' | 'fallback' | 'omit';
 /**
  * Request-scoped context shared across every read and populate walk in one
  * logical request. Threaded through populate, `afterRead` hooks, and any
@@ -182,6 +208,18 @@ export interface IDbAdapter {
         collections: ICollectionQueries;
         documents: IDocumentQueries;
     };
+    /**
+     * Optional maintenance: stamp `source_locale` (the per-document content
+     * anchor) on documents created before the column existed, setting NULL rows
+     * to the adapter's configured default content locale. Called idempotently at
+     * boot by `initBylineCore` so in-place upgrades self-heal without a manual
+     * step or a migrate-ordering constraint — a no-op (zero rows) once every
+     * document is stamped. Optional so adapters that don't model `source_locale`
+     * need not implement it. See docs/DEFAULT-LOCALE-SWITCHING.md.
+     */
+    backfillSourceLocales?: () => Promise<{
+        rowsUpdated: number;
+    }>;
 }
 /**
  * Adapter capability for the shared-pool counter mechanism backing the
@@ -271,6 +309,15 @@ export interface IDocumentCommands {
          * surface as `ERR_PATH_CONFLICT` from the lifecycle layer.
          */
         path?: string;
+        /**
+         * Optional. When provided, the adapter replaces the document's rows in
+         * `byline_document_available_locales` (document-grain) wholesale — the
+         * editorial advertised-locale set. `undefined` leaves the existing set
+         * untouched (sticky across versions, like `path`); `[]` clears it. The
+         * locale values are the advertised content locales themselves, not the
+         * write locale. See `docs/AVAILABLE-LOCALES.md`.
+         */
+        availableLocales?: string[];
         locale?: string;
         status?: string;
         createdBy?: string;
@@ -375,6 +422,9 @@ export interface IDocumentQueries {
          * never silently leaks into a live site.
          */
         lenient?: boolean;
+        /** See `MissingLocalePolicy`. `'omit'` returns `null` when the document
+         *  is not available in the requested locale. Omitted ⇒ `'empty'`. */
+        onMissingLocale?: MissingLocalePolicy;
     }): Promise<any | null>;
     /**
      * Fetch only the current version's metadata row (no field reconstruction).
@@ -411,6 +461,9 @@ export interface IDocumentQueries {
         filters?: DocumentFilter[];
         /** See `getDocumentById.requestContext`. */
         requestContext?: RequestContext;
+        /** See `MissingLocalePolicy`. `'omit'` returns `null` when the document
+         *  is not available in the requested locale. Omitted ⇒ `'empty'`. */
+        onMissingLocale?: MissingLocalePolicy;
     }): Promise<any | null>;
     getDocumentByVersion(params: {
         document_version_id: string;
@@ -549,6 +602,10 @@ export interface IDocumentQueries {
         readMode?: ReadMode;
         /** See `getDocumentById.requestContext`. */
         requestContext?: RequestContext;
+        /** See `MissingLocalePolicy`. `'omit'` excludes documents not available
+         *  in the requested locale (filtered at the SQL layer so pagination stays
+         *  correct). Omitted ⇒ `'empty'`. */
+        onMissingLocale?: MissingLocalePolicy;
     }): Promise<{
         documents: any[];
         total: number;

package/dist/@types/site-config.d.ts

@@ -53,8 +53,47 @@ export interface BaseConfig {
             }>;
         };
         content: {
+            /**
+             * The default **content** locale: the locale new documents are authored
+             * in, and the locale served for a request that doesn't specify one.
+             *
+             * As of the source_locale work this is **no longer the per-document data
+             * anchor.** Each document records its own `source_locale` at creation
+             * (= this value at that moment) and rides it for the read fallback floor,
+             * its path locale, and the completeness ledger — so changing this value
+             * is safe for existing data: they keep reading against the locale they
+             * were authored in. New documents created after the change anchor to the
+             * new value. See docs/DEFAULT-LOCALE-SWITCHING.md.
+             *
+             * (Switching this on a live system still needs the one-time
+             * `backfillSourceLocales()` maintenance step to have stamped any rows
+             * that predate the `source_locale` column.)
+             */
             defaultLocale: string;
             locales: string[];
+            /**
+             * Optional display names for the content locales a document can be
+             * published in. Mirrors `interface.localeDefinitions`, but for the
+             * *content* dimension rather than the admin chrome.
+             *
+             * Byline itself does not render these — the content-locale set has
+             * no admin switcher. They exist so a host frontend can advertise
+             * content languages (hreflang clusters, "read this in…" affordances,
+             * sitemap alternates) with author-controlled labels — `Français`
+             * rather than the lowercase `français` that CLDR's
+             * `Intl.DisplayNames` returns for romance languages — read straight
+             * off `getServerConfig().i18n.content.localeDefinitions` instead of
+             * maintaining a parallel label map.
+             *
+             * Hosts that omit this can resolve labels per-code via
+             * `Intl.DisplayNames`; hosts that provide it for some codes still
+             * fall back for the rest. Entries for codes outside `locales` are
+             * silently ignored.
+             */
+            localeDefinitions?: ReadonlyArray<{
+                code: string;
+                nativeName: string;
+            }>;
         };
         /**
          * Admin interface translation registry — a `TranslationBundle`

package/dist/config/validate-collections.d.ts

@@ -24,6 +24,11 @@ export declare const RESERVED_FIELD_NAMES: ReadonlySet<string>;
  *  - When `useAsPath` is set, the referenced field must exist at the
  *    top level of the collection and be of a type the slugifier can
  *    sensibly consume (text-like or date-like).
+ *  - No field may be named `availableLocales`; collections opt into the
+ *    editorial available-locales control via `advertiseLocales: true`.
+ *  - When `advertiseLocales` is `true`, the collection must have at least
+ *    one `localized` field — advertising content locales is meaningless
+ *    otherwise.
  *
  * Throws a plain `Error` (not a `BylineError`) because configuration
  * validation runs at startup, before the logger and error registry are

package/dist/config/validate-collections.js

@@ -12,7 +12,15 @@
  * store tables from installations whose schemas declared these names as
  * user fields before they were promoted to system attributes.
  */
-export const RESERVED_FIELD_NAMES = new Set(['path']);
+export const RESERVED_FIELD_NAMES = new Set(['path', 'availableLocales']);
+/**
+ * Per-reserved-name hint pointing the user at the collection-level directive
+ * that replaces declaring the name as a field.
+ */
+const RESERVED_FIELD_HINTS = {
+    path: "Use `useAsPath: '<sourceField>'` on the collection definition instead.",
+    availableLocales: 'Use `advertiseLocales: true` on the collection definition instead.',
+};
 const USE_AS_PATH_SOURCE_TYPES = new Set([
     'text',
     'textArea',
@@ -21,6 +29,20 @@ const USE_AS_PATH_SOURCE_TYPES = new Set([
     'datetime',
     'time',
 ]);
+/**
+ * True when any field in the tree (at any nesting depth) is `localized`.
+ * Used to gate `advertiseLocales` — advertising content locales is only
+ * meaningful when the collection has locale-varying content.
+ */
+function hasLocalizedField(fields) {
+    let found = false;
+    walkFields(fields, (field) => {
+        if ('localized' in field && field.localized === true) {
+            found = true;
+        }
+    });
+    return found;
+}
 function walkFields(fields, visit) {
     for (const field of fields) {
         visit(field);
@@ -44,6 +66,11 @@ function walkFields(fields, visit) {
  *  - When `useAsPath` is set, the referenced field must exist at the
  *    top level of the collection and be of a type the slugifier can
  *    sensibly consume (text-like or date-like).
+ *  - No field may be named `availableLocales`; collections opt into the
+ *    editorial available-locales control via `advertiseLocales: true`.
+ *  - When `advertiseLocales` is `true`, the collection must have at least
+ *    one `localized` field — advertising content locales is meaningless
+ *    otherwise.
  *
  * Throws a plain `Error` (not a `BylineError`) because configuration
  * validation runs at startup, before the logger and error registry are
@@ -53,7 +80,8 @@ export function validateCollections(collections) {
     for (const collection of collections) {
         walkFields(collection.fields, (field) => {
             if ('name' in field && RESERVED_FIELD_NAMES.has(field.name)) {
-                throw new Error(`Collection "${collection.path}" declares a field named "${field.name}", which is a reserved system attribute. Use \`useAsPath: '<sourceField>'\` on the collection definition instead.`);
+                const hint = RESERVED_FIELD_HINTS[field.name] ?? '';
+                throw new Error(`Collection "${collection.path}" declares a field named "${field.name}", which is a reserved system attribute.${hint ? ` ${hint}` : ''}`);
             }
         });
         if (collection.useAsPath != null) {
@@ -65,5 +93,8 @@ export function validateCollections(collections) {
                 throw new Error(`Collection "${collection.path}" sets \`useAsPath: '${collection.useAsPath}'\` but field "${collection.useAsPath}" has type "${source.type}". Supported source types: ${[...USE_AS_PATH_SOURCE_TYPES].join(', ')}.`);
             }
         }
+        if (collection.advertiseLocales === true && !hasLocalizedField(collection.fields)) {
+            throw new Error(`Collection "${collection.path}" sets \`advertiseLocales: true\` but has no localized fields. The available-locales control advertises content locales, which is only meaningful when at least one field is \`localized\`.`);
+        }
     }
 }

package/dist/config/validate-collections.test.node.js

@@ -145,4 +145,73 @@ describe('validateCollections', () => {
         };
         expect(() => validateCollections([collection])).toThrow(/no top-level field with that name/);
     });
+    it('rejects a top-level field named "availableLocales"', () => {
+        const collection = {
+            ...baseCollection,
+            fields: [
+                { name: 'title', label: 'Title', type: 'text' },
+                { name: 'availableLocales', label: 'Available Locales', type: 'text' },
+            ],
+        };
+        expect(() => validateCollections([collection])).toThrow(/reserved system attribute/);
+    });
+    it('points the user at advertiseLocales when "availableLocales" is declared as a field', () => {
+        const collection = {
+            ...baseCollection,
+            fields: [
+                { name: 'title', label: 'Title', type: 'text' },
+                { name: 'availableLocales', label: 'Available Locales', type: 'text' },
+            ],
+        };
+        expect(() => validateCollections([collection])).toThrow(/advertiseLocales: true/);
+    });
+    it('rejects a nested "availableLocales" field inside a group', () => {
+        const collection = {
+            ...baseCollection,
+            fields: [
+                {
+                    name: 'meta',
+                    label: 'Meta',
+                    type: 'group',
+                    fields: [{ name: 'availableLocales', label: 'Available Locales', type: 'text' }],
+                },
+            ],
+        };
+        expect(() => validateCollections([collection])).toThrow(/reserved system attribute/);
+    });
+    it('accepts advertiseLocales: true when the collection has a localized field', () => {
+        const collection = {
+            ...baseCollection,
+            fields: [{ name: 'title', label: 'Title', type: 'text', localized: true }],
+            advertiseLocales: true,
+        };
+        expect(() => validateCollections([collection])).not.toThrow();
+    });
+    it('accepts advertiseLocales: true with a nested localized field', () => {
+        const collection = {
+            ...baseCollection,
+            fields: [
+                { name: 'title', label: 'Title', type: 'text' },
+                {
+                    name: 'meta',
+                    label: 'Meta',
+                    type: 'group',
+                    fields: [{ name: 'summary', label: 'Summary', type: 'textArea', localized: true }],
+                },
+            ],
+            advertiseLocales: true,
+        };
+        expect(() => validateCollections([collection])).not.toThrow();
+    });
+    it('rejects advertiseLocales: true when the collection has no localized fields', () => {
+        const collection = {
+            ...baseCollection,
+            fields: [{ name: 'title', label: 'Title', type: 'text' }],
+            advertiseLocales: true,
+        };
+        expect(() => validateCollections([collection])).toThrow(/no localized fields/);
+    });
+    it('accepts advertiseLocales omitted regardless of localized fields', () => {
+        expect(() => validateCollections([baseCollection])).not.toThrow();
+    });
 });

package/dist/core.js

@@ -88,6 +88,21 @@ export const initBylineCore = async (config, pinoLogger) => {
         db: composed.db,
         logger: composed.logger,
     });
+    // Idempotently stamp `source_locale` on any documents created before that
+    // column existed (it ships nullable and is backfilled here rather than via a
+    // NOT NULL migration, so a vanilla `drizzle:migrate` on a populated database
+    // never fails on the constraint). Uses the adapter's configured default
+    // content locale — the anchor those rows were implicitly authored against —
+    // and is a no-op (zero rows) once every document is stamped. Self-heals
+    // in-place upgrades without a manual maintenance step. The write path stamps
+    // new documents directly, so steady-state boots touch nothing. See
+    // docs/DEFAULT-LOCALE-SWITCHING.md.
+    if (typeof composed.db.backfillSourceLocales === 'function') {
+        const { rowsUpdated } = await composed.db.backfillSourceLocales();
+        if (rowsUpdated > 0) {
+            composed.logger.info({ rowsUpdated }, `[i18n] stamped source_locale on ${rowsUpdated} pre-existing document(s)`);
+        }
+    }
     const getCollectionRecord = (path) => {
         const record = collectionRecords.get(path);
         if (!record) {

package/dist/schemas/zod/builder.d.ts

@@ -5,6 +5,7 @@ export declare const createBaseSchema: (collection?: CollectionDefinition) => z.
     id: z.ZodUUID;
     versionId: z.ZodOptional<z.ZodUUID>;
     path: z.ZodOptional<z.ZodString>;
+    sourceLocale: z.ZodOptional<z.ZodString>;
     status: z.ZodEnum<{
         [x: string]: string;
     }>;
@@ -36,6 +37,7 @@ export declare const createCollectionSchemasForPath: (path: string) => {
         id: z.ZodUUID;
         versionId: z.ZodOptional<z.ZodUUID>;
         path: z.ZodOptional<z.ZodString>;
+        sourceLocale: z.ZodOptional<z.ZodString>;
         status: z.ZodEnum<{
             [x: string]: string;
         }>;
@@ -53,6 +55,7 @@ export declare const createCollectionSchemasForPath: (path: string) => {
         id: z.ZodUUID;
         versionId: z.ZodOptional<z.ZodUUID>;
         path: z.ZodOptional<z.ZodString>;
+        sourceLocale: z.ZodOptional<z.ZodString>;
         status: z.ZodEnum<{
             [x: string]: string;
         }>;
@@ -68,6 +71,7 @@ export declare const createCollectionSchemasForPath: (path: string) => {
             id: z.ZodUUID;
             versionId: z.ZodOptional<z.ZodUUID>;
             path: z.ZodOptional<z.ZodString>;
+            sourceLocale: z.ZodOptional<z.ZodString>;
             status: z.ZodEnum<{
                 [x: string]: string;
             }>;
@@ -102,6 +106,7 @@ export declare const createCollectionSchemasForPath: (path: string) => {
             id: z.ZodUUID;
             versionId: z.ZodOptional<z.ZodUUID>;
             path: z.ZodOptional<z.ZodString>;
+            sourceLocale: z.ZodOptional<z.ZodString>;
             status: z.ZodEnum<{
                 [x: string]: string;
             }>;
@@ -128,6 +133,7 @@ export declare const createCollectionSchemasForPath: (path: string) => {
         id: z.ZodUUID;
         versionId: z.ZodOptional<z.ZodUUID>;
         path: z.ZodOptional<z.ZodString>;
+        sourceLocale: z.ZodOptional<z.ZodString>;
         status: z.ZodEnum<{
             [x: string]: string;
         }>;
@@ -144,6 +150,7 @@ export declare const createCollectionSchemas: (collection: CollectionDefinition)
         id: z.ZodUUID;
         versionId: z.ZodOptional<z.ZodUUID>;
         path: z.ZodOptional<z.ZodString>;
+        sourceLocale: z.ZodOptional<z.ZodString>;
         status: z.ZodEnum<{
             [x: string]: string;
         }>;
@@ -161,6 +168,7 @@ export declare const createCollectionSchemas: (collection: CollectionDefinition)
         id: z.ZodUUID;
         versionId: z.ZodOptional<z.ZodUUID>;
         path: z.ZodOptional<z.ZodString>;
+        sourceLocale: z.ZodOptional<z.ZodString>;
         status: z.ZodEnum<{
             [x: string]: string;
         }>;
@@ -176,6 +184,7 @@ export declare const createCollectionSchemas: (collection: CollectionDefinition)
             id: z.ZodUUID;
             versionId: z.ZodOptional<z.ZodUUID>;
             path: z.ZodOptional<z.ZodString>;
+            sourceLocale: z.ZodOptional<z.ZodString>;
             status: z.ZodEnum<{
                 [x: string]: string;
             }>;
@@ -210,6 +219,7 @@ export declare const createCollectionSchemas: (collection: CollectionDefinition)
             id: z.ZodUUID;
             versionId: z.ZodOptional<z.ZodUUID>;
             path: z.ZodOptional<z.ZodString>;
+            sourceLocale: z.ZodOptional<z.ZodString>;
             status: z.ZodEnum<{
                 [x: string]: string;
             }>;
@@ -236,6 +246,7 @@ export declare const createCollectionSchemas: (collection: CollectionDefinition)
         id: z.ZodUUID;
         versionId: z.ZodOptional<z.ZodUUID>;
         path: z.ZodOptional<z.ZodString>;
+        sourceLocale: z.ZodOptional<z.ZodString>;
         status: z.ZodEnum<{
             [x: string]: string;
         }>;
@@ -252,6 +263,7 @@ export declare const createTypedCollectionSchemas: (collection: CollectionDefini
         id: z.ZodUUID;
         versionId: z.ZodOptional<z.ZodUUID>;
         path: z.ZodOptional<z.ZodString>;
+        sourceLocale: z.ZodOptional<z.ZodString>;
         status: z.ZodEnum<{
             [x: string]: string;
         }>;
@@ -269,6 +281,7 @@ export declare const createTypedCollectionSchemas: (collection: CollectionDefini
         id: z.ZodUUID;
         versionId: z.ZodOptional<z.ZodUUID>;
         path: z.ZodOptional<z.ZodString>;
+        sourceLocale: z.ZodOptional<z.ZodString>;
         status: z.ZodEnum<{
             [x: string]: string;
         }>;
@@ -284,6 +297,7 @@ export declare const createTypedCollectionSchemas: (collection: CollectionDefini
             id: z.ZodUUID;
             versionId: z.ZodOptional<z.ZodUUID>;
             path: z.ZodOptional<z.ZodString>;
+            sourceLocale: z.ZodOptional<z.ZodString>;
             status: z.ZodEnum<{
                 [x: string]: string;
             }>;
@@ -318,6 +332,7 @@ export declare const createTypedCollectionSchemas: (collection: CollectionDefini
             id: z.ZodUUID;
             versionId: z.ZodOptional<z.ZodUUID>;
             path: z.ZodOptional<z.ZodString>;
+            sourceLocale: z.ZodOptional<z.ZodString>;
             status: z.ZodEnum<{
                 [x: string]: string;
             }>;
@@ -344,6 +359,7 @@ export declare const createTypedCollectionSchemas: (collection: CollectionDefini
         id: z.ZodUUID;
         versionId: z.ZodOptional<z.ZodUUID>;
         path: z.ZodOptional<z.ZodString>;
+        sourceLocale: z.ZodOptional<z.ZodString>;
         status: z.ZodEnum<{
             [x: string]: string;
         }>;
@@ -360,6 +376,7 @@ export declare const createTypedCollectionSchemasForPath: (path: string) => {
         id: z.ZodUUID;
         versionId: z.ZodOptional<z.ZodUUID>;
         path: z.ZodOptional<z.ZodString>;
+        sourceLocale: z.ZodOptional<z.ZodString>;
         status: z.ZodEnum<{
             [x: string]: string;
         }>;
@@ -377,6 +394,7 @@ export declare const createTypedCollectionSchemasForPath: (path: string) => {
         id: z.ZodUUID;
         versionId: z.ZodOptional<z.ZodUUID>;
         path: z.ZodOptional<z.ZodString>;
+        sourceLocale: z.ZodOptional<z.ZodString>;
         status: z.ZodEnum<{
             [x: string]: string;
         }>;
@@ -392,6 +410,7 @@ export declare const createTypedCollectionSchemasForPath: (path: string) => {
             id: z.ZodUUID;
             versionId: z.ZodOptional<z.ZodUUID>;
             path: z.ZodOptional<z.ZodString>;
+            sourceLocale: z.ZodOptional<z.ZodString>;
             status: z.ZodEnum<{
                 [x: string]: string;
             }>;
@@ -426,6 +445,7 @@ export declare const createTypedCollectionSchemasForPath: (path: string) => {
             id: z.ZodUUID;
             versionId: z.ZodOptional<z.ZodUUID>;
             path: z.ZodOptional<z.ZodString>;
+            sourceLocale: z.ZodOptional<z.ZodString>;
             status: z.ZodEnum<{
                 [x: string]: string;
             }>;
@@ -452,6 +472,7 @@ export declare const createTypedCollectionSchemasForPath: (path: string) => {
         id: z.ZodUUID;
         versionId: z.ZodOptional<z.ZodUUID>;
         path: z.ZodOptional<z.ZodString>;
+        sourceLocale: z.ZodOptional<z.ZodString>;
         status: z.ZodEnum<{
             [x: string]: string;
         }>;

package/dist/schemas/zod/builder.js

@@ -197,6 +197,10 @@ export const createBaseSchema = (collection) => {
         id: z.uuid(),
         versionId: z.uuid().optional(),
         path: z.string().optional(),
+        // The document's content source-locale anchor (see docs/DEFAULT-LOCALE-SWITCHING.md).
+        // Carried through list/get responses so the admin can badge it; Zod would
+        // otherwise strip it as an undeclared key.
+        sourceLocale: z.string().optional(),
         status: statusEnum,
         hasPublishedVersion: z.boolean().optional(),
         createdAt: z.iso.datetime(),

package/dist/services/document-lifecycle.d.ts

@@ -180,6 +180,14 @@ export declare function createDocument(ctx: DocumentLifecycleContext, params: {
      * lifecycle derives the value from `definition.useAsPath`.
      */
     path?: string;
+    /**
+     * The editorial advertised-locale set (from the admin available-locales
+     * sidebar widget). Document-grain and sticky like `path`: passed straight
+     * to the storage primitive, which replaces the document's rows wholesale.
+     * `undefined` writes nothing (a new document starts with an empty set —
+     * the safe opt-in default); `[]` clears it. See docs/AVAILABLE-LOCALES.md.
+     */
+    availableLocales?: string[];
 }): Promise<CreateDocumentResult>;
 /**
  * Update a document via full replacement (PUT semantics).
@@ -205,6 +213,13 @@ export declare function updateDocument(ctx: DocumentLifecycleContext, params: {
      * action driven by the admin path widget.
      */
     path?: string;
+    /**
+     * The editorial advertised-locale set. `undefined` leaves the existing
+     * set untouched (sticky — document-grain, like `path`); an explicit array
+     * (empty included) replaces it wholesale. Driven by the admin
+     * available-locales sidebar widget. See docs/AVAILABLE-LOCALES.md.
+     */
+    availableLocales?: string[];
 }): Promise<UpdateDocumentResult>;
 /**
  * Update a document via patch application.
@@ -233,6 +248,13 @@ export declare function updateDocumentWithPatches(ctx: DocumentLifecycleContext,
      * the previous version.
      */
     path?: string;
+    /**
+     * The editorial advertised-locale set (typically supplied alongside
+     * patches when the admin available-locales widget has been edited).
+     * `undefined` leaves the existing set untouched (sticky); an explicit
+     * array replaces it wholesale. See docs/AVAILABLE-LOCALES.md.
+     */
+    availableLocales?: string[];
 }): Promise<UpdateDocumentWithPatchesResult>;
 /**
  * Change a document's workflow status.

package/dist/services/document-lifecycle.js

@@ -128,22 +128,25 @@ function rethrowPathConflict(err, path, locale) {
  * path write entirely (no upsert).
  */
 function resolvePathForUpdate(args) {
-    const { explicitPath, currentPath, requestLocale, defaultLocale, documentId, logger } = args;
-    if (requestLocale === defaultLocale) {
-        // Default-locale write: pass path through when supplied; otherwise
-        // skip the write (existing path row stays as-is — sticky).
+    const { explicitPath, currentPath, requestLocale, sourceLocale, documentId, logger } = args;
+    if (requestLocale === sourceLocale) {
+        // Source-locale write: pass path through when supplied; otherwise
+        // skip the write (existing path row stays as-is — sticky). The path row
+        // lives under the document's source_locale (its anchor), not the mutable
+        // global default — so this stays correct after the global default is
+        // switched. See docs/DEFAULT-LOCALE-SWITCHING.md.
         return explicitPath ?? undefined;
     }
-    // Non-default-locale write: reject any path change with a warn so the
-    // operation succeeds but the editor / API caller is informed.
+    // Non-source-locale (translation) write: reject any path change with a warn
+    // so the operation succeeds but the editor / API caller is informed.
     if (explicitPath !== null && explicitPath !== currentPath) {
         logger?.warn({
             documentId,
             requestedLocale: requestLocale,
-            defaultLocale,
+            sourceLocale,
             suppliedPath: explicitPath,
             currentPath,
-        }, 'path changes apply only on default-locale writes; ignored on translation save');
+        }, 'path changes apply only on source-locale writes; ignored on translation save');
     }
     return undefined;
 }
@@ -239,6 +242,7 @@ export async function createDocument(ctx, params) {
             action: 'create',
             documentData: data,
             path: resolvedPath,
+            availableLocales: params.availableLocales,
             status: params.status ?? data.status ?? getDefaultStatus(definition),
             locale: params.locale ?? defaultLocale,
             orderKey,
@@ -300,11 +304,15 @@ export async function updateDocument(ctx, params) {
         const defaultStatus = getDefaultStatus(definition);
         const explicitPath = typeof params.path === 'string' && params.path.length > 0 ? params.path : null;
         const requestLocale = params.locale ?? defaultLocale;
+        // The document's own content-locale anchor governs which save writes the
+        // path row — not the mutable global default. Falls back to the global
+        // default for rows predating source_locale (not yet backfilled).
+        const sourceLocale = originalData.source_locale ?? defaultLocale;
         const pathForCommand = resolvePathForUpdate({
             explicitPath,
             currentPath: originalData.path,
             requestLocale,
-            defaultLocale,
+            sourceLocale,
             documentId: params.documentId,
             logger: ctx.logger,
         });
@@ -318,6 +326,7 @@ export async function updateDocument(ctx, params) {
             action: 'update',
             documentData: data,
             path: pathForCommand,
+            availableLocales: params.availableLocales,
             status: defaultStatus,
             locale: requestLocale,
             previousVersionId: originalData.document_version_id,
@@ -407,11 +416,15 @@ export async function updateDocumentWithPatches(ctx, params) {
         const defaultStatus = getDefaultStatus(definition);
         const explicitPath = typeof params.path === 'string' && params.path.length > 0 ? params.path : null;
         const requestLocale = params.locale ?? defaultLocale;
+        // The document's own content-locale anchor governs which save writes the
+        // path row — not the mutable global default. Falls back to the global
+        // default for rows predating source_locale (not yet backfilled).
+        const sourceLocale = originalData.source_locale ?? defaultLocale;
         const pathForCommand = resolvePathForUpdate({
             explicitPath,
             currentPath: originalData.path,
             requestLocale,
-            defaultLocale,
+            sourceLocale,
             documentId: params.documentId,
             logger: ctx.logger,
         });
@@ -425,6 +438,7 @@ export async function updateDocumentWithPatches(ctx, params) {
             action: 'update',
             documentData: nextData,
             path: pathForCommand,
+            availableLocales: params.availableLocales,
             status: defaultStatus,
             locale: requestLocale,
             previousVersionId: originalData.document_version_id,

package/dist/services/document-lifecycle.test.node.js

@@ -374,11 +374,12 @@ describe('Document lifecycle service', () => {
             });
             expect(createDocumentVersion.mock.calls[0]?.[0].status).toBe('draft');
         });
-        it('drops path changes silently with a logger.warn on non-default-locale (translation) saves', async () => {
+        it('drops path changes silently with a logger.warn on non-source-locale (translation) saves', async () => {
             const { db, getDocumentById, createDocumentVersion } = createMockDb();
             getDocumentById.mockResolvedValue({
                 document_version_id: 'prev-ver',
                 path: 'about',
+                source_locale: 'en',
                 status: 'draft',
                 fields: { title: 'About' },
             });
@@ -400,10 +401,31 @@ describe('Document lifecycle service', () => {
             expect(warn).toHaveBeenCalledWith(expect.objectContaining({
                 documentId: 'doc-1',
                 requestedLocale: 'fr',
-                defaultLocale: 'en',
+                sourceLocale: 'en',
                 suppliedPath: 'a-propos',
                 currentPath: 'about',
-            }), expect.stringContaining('path changes apply only on default-locale writes'));
+            }), expect.stringContaining('path changes apply only on source-locale writes'));
+        });
+        it('writes the path on a source-locale save even when it differs from the global default', async () => {
+            // Document anchored to de (re-anchored, or authored before a global
+            // default switch); the global default is en. A de save is the
+            // source-locale write, so the supplied path must flow through.
+            const { db, getDocumentById, createDocumentVersion } = createMockDb();
+            getDocumentById.mockResolvedValue({
+                document_version_id: 'prev-ver',
+                path: 'ueber-uns',
+                source_locale: 'de',
+                status: 'draft',
+                fields: { title: 'Über uns' },
+            });
+            const ctx = buildCtx(db);
+            await updateDocument(ctx, {
+                documentId: 'doc-1',
+                data: { title: 'Über uns — neu' },
+                locale: 'de',
+                path: 'ueber-uns-neu',
+            });
+            expect(createDocumentVersion.mock.calls[0]?.[0].path).toBe('ueber-uns-neu');
         });
         it('does not warn when a translation save supplies the same path as current', async () => {
             const { db, getDocumentById } = createMockDb();

package/dist/storage/collection-fingerprint.js

@@ -115,6 +115,8 @@ function canonicalCollection(def) {
         out.useAsPath = def.useAsPath;
     if (def.useAsTitle !== undefined)
         out.useAsTitle = def.useAsTitle;
+    if (def.advertiseLocales !== undefined)
+        out.advertiseLocales = def.advertiseLocales;
     return out;
 }
 // ---------------------------------------------------------------------------

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/core",
   "private": false,
   "license": "MPL-2.0",
-  "version": "2.6.1",
+  "version": "3.0.0",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -79,7 +79,7 @@
     "sharp": "^0.34.5",
     "uuid": "^14.0.0",
     "zod": "^4.4.3",
-    "@byline/auth": "2.6.1"
+    "@byline/auth": "3.0.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.15",