@byline/core 3.5.1 → 3.7.0

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

@@ -665,4 +665,26 @@ export interface RichTextEmbedContext {
  * each field's `embedRelationsOnSave` flag.
  */
 export type RichTextEmbedFn = (ctx: RichTextEmbedContext) => Promise<void>;
+/**
+ * Context passed to the richtext markdown serializer for one rich-text
+ * field value. Read-only and synchronous — the export surface walks the
+ * stored editor JSON directly (no editor instantiation, no DB reads).
+ */
+export interface RichTextToMarkdownContext {
+    /** The richText field's value (raw editor JSON, possibly stringified). */
+    value: unknown;
+    /** Field path within the document — e.g. `'body'` or `'content.0.caption'`. */
+    fieldPath: string;
+    /** Collection path the document belongs to. */
+    collectionPath: string;
+}
+/**
+ * Server-side markdown serializer contract for the agent-readable export
+ * surface (`documentToMarkdown`, `.md` routes, `llms.txt`). Editor
+ * adapters export an implementation (e.g. `lexicalToMarkdown` from
+ * `@byline/richtext-lexical/server`); installations register one via
+ * `ServerConfig.fields.richText.toMarkdown`. One-way and lossy-tolerant
+ * by contract — output is never re-imported.
+ */
+export type RichTextToMarkdownFn = (ctx: RichTextToMarkdownContext) => string;
 export {};

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

@@ -10,7 +10,7 @@ import type { SlugifierFn } from '../utils/slugify.js';
 import type { CollectionAdminConfig } from './admin-types.js';
 import type { CollectionDefinition } from './collection-types.js';
 import type { IDbAdapter } from './db-types.js';
-import type { RichTextEditorComponent, RichTextEmbedFn, RichTextPopulateFn } from './field-types.js';
+import type { RichTextEditorComponent, RichTextEmbedFn, RichTextPopulateFn, RichTextToMarkdownFn } from './field-types.js';
 import type { IStorageProvider } from './storage-types.js';
 export type DbAdapterFn = (args: {
     connectionString: string;
@@ -307,6 +307,13 @@ export interface ServerConfig<TAdminStore = unknown> extends BaseConfig {
         richText?: {
             populate?: RichTextPopulateFn;
             embed?: RichTextEmbedFn;
+            /**
+             * `toMarkdown` — one-way markdown serializer for the agent-readable
+             * export surface (`documentToMarkdown`, `.md` routes, `llms.txt`).
+             * Optional: only installations that expose a markdown surface need
+             * it. Synchronous and read-only — it walks stored editor JSON.
+             */
+            toMarkdown?: RichTextToMarkdownFn;
         };
     };
 }

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

@@ -0,0 +1,79 @@
+/**
+ * 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 type { RequestContext } from '@byline/auth';
+import type { CollectionDefinition, IDbAdapter, IStorageProvider } from '../../@types/index.js';
+import type { BylineLogger } from '../../lib/logger.js';
+import type { SlugifierFn } from '../../utils/slugify.js';
+/**
+ * The shared context every lifecycle function requires. Built once per
+ * request by the API route layer and passed through.
+ */
+export interface DocumentLifecycleContext {
+    /** The database adapter returned by `getServerConfig().db`. */
+    db: IDbAdapter;
+    /** The resolved `CollectionDefinition` (includes `hooks`). */
+    definition: CollectionDefinition;
+    /** The database-level collection row ID. */
+    collectionId: string;
+    /**
+     * The collection's current schema version. Stamped onto every
+     * `documentVersions` row written during the lifecycle call so that
+     * Phase-2 in-memory migration can later resolve each document against
+     * the shape it was authored under. Callers resolve this from the core
+     * registry (`core.getCollectionRecord(path).version`).
+     */
+    collectionVersion: number;
+    /** The collection `path` string (e.g. `'docs'`, `'news'`). */
+    collectionPath: string;
+    /**
+     * Storage provider for this collection. Required when the collection
+     * has any upload-capable image/file field, so that the original files
+     * and their persisted variants can be cleaned up on document deletion.
+     *
+     * Resolved by the route layer as:
+     *   `field.upload?.storage ?? serverConfig.storage`
+     *
+     * Optional — callers whose collections have no upload-capable fields
+     * are unaffected.
+     */
+    storage?: IStorageProvider;
+    /** Structured logger instance. Provided via the DI registry. */
+    logger: BylineLogger;
+    /**
+     * The default content locale (e.g. `'en'`). Used to anchor `path`
+     * derivation: the slugifier always runs against the default-locale
+     * source value, and creating a brand-new document in any other locale
+     * is rejected.
+     *
+     * Sourced by callers from `ServerConfig.i18n.content.defaultLocale`.
+     */
+    defaultLocale: string;
+    /**
+     * Installation slugifier. When omitted, the lifecycle falls back to
+     * the default `slugify` exported from `@byline/core`.
+     */
+    slugifier?: SlugifierFn;
+    /**
+     * Request-scoped context carrying the authenticated actor, request id,
+     * and related per-request metadata.
+     *
+     * Plumbing only in Phase 0 of the auth roadmap — present on the context
+     * so every lifecycle service can accept and forward it, but no ability
+     * assertions are performed yet. Phase 4 turns enforcement on: lifecycle
+     * entry points will call `context.requestContext?.actor?.assertAbility(...)`
+     * before any storage mutation.
+     *
+     * Optional so that internal-tooling callers (seed scripts, migration
+     * tools) continue to compile. Production write paths always supply it
+     * — `assertActorCanPerform` runs at every lifecycle entry and rejects
+     * a missing context.
+     *
+     * See docs/AUTHN-AUTHZ.md.
+     */
+    requestContext?: RequestContext;
+}

package/dist/services/document-lifecycle/context.js

@@ -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/services/document-lifecycle/copy-to-locale.d.ts

@@ -0,0 +1,62 @@
+/**
+ * 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 type { DocumentLifecycleContext } from './context.js';
+export interface CopyToLocaleResult {
+    documentId: string;
+    documentVersionId: string;
+    /** Source locale read for the copy. */
+    sourceLocale: string;
+    /** Target locale into which the source's localized leaves were written. */
+    targetLocale: string;
+    /**
+     * Number of localized field values copied from source to target. Useful
+     * for UI toasts ("Copied 4 fields from EN to FR"). A zero result means
+     * the source had no localized content to copy into the target under the
+     * chosen merge rule (e.g. `overwrite: false` and target was already
+     * fully populated).
+     */
+    fieldsUpdated: number;
+}
+/**
+ * Copy a document's content from one locale into another, in place on
+ * the same document.
+ *
+ * Reads the source and target locales separately (the storage layer
+ * resolves localized fields to flat single-locale shapes when given a
+ * specific `resolveLocale`). A schema-aware merge walker decides, leaf
+ * by leaf, whether to take the source's value or keep the target's,
+ * driven by the `overwrite` flag. The merged tree is written via
+ * `createDocumentVersion({ action: 'copy_to_locale', locale: target })`
+ * — the existing cross-locale carry-forward in the storage primitive
+ * preserves every *other* locale's rows untouched.
+ *
+ * Non-localized fields are never altered by this operation: they live
+ * on `locale: 'all'` rows and the merge walker passes the target's
+ * value through so the write does not blank them.
+ *
+ * Path is sticky and lives on default-locale only; this operation never
+ * touches `byline_document_paths`. Status resets to the workflow
+ * default — translations land as drafts.
+ *
+ * Flow:
+ *   1. `assertActorCanPerform('update')` — same gate as a translation save.
+ *   2. Reject if `sourceLocale === targetLocale`.
+ *   3. Fetch source via `getDocumentById({ locale: sourceLocale })`.
+ *   4. Fetch target via `getDocumentById({ locale: targetLocale })`.
+ *   5. `mergeLocaleData(definition.fields, source.fields, target.fields, overwrite)`.
+ *   6. `hooks.beforeUpdate({ data, originalData, collectionPath, copyToLocale })`.
+ *   7. `createDocumentVersion({ documentId, action: 'copy_to_locale',
+ *      locale: targetLocale, documentData, previousVersionId, status })`.
+ *   8. `hooks.afterUpdate({ ..., copyToLocale })`.
+ */
+export declare function copyToLocale(ctx: DocumentLifecycleContext, params: {
+    documentId: string;
+    sourceLocale: string;
+    targetLocale: string;
+    overwrite: boolean;
+}): Promise<CopyToLocaleResult>;

package/dist/services/document-lifecycle/copy-to-locale.js

@@ -0,0 +1,157 @@
+/**
+ * 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 { resolveHooks } from '../../@types/index.js';
+import { assertActorCanPerform } from '../../auth/assert-actor-can-perform.js';
+import { ERR_NOT_FOUND, ERR_VALIDATION } from '../../lib/errors.js';
+import { withLogContext } from '../../lib/logger.js';
+import { getDefaultStatus } from '../../workflow/workflow.js';
+import { applyRichTextEmbed, extractVersionId, invokeHook } from './internals.js';
+import { mergeLocaleData } from './merge-locale-data.js';
+/**
+ * Copy a document's content from one locale into another, in place on
+ * the same document.
+ *
+ * Reads the source and target locales separately (the storage layer
+ * resolves localized fields to flat single-locale shapes when given a
+ * specific `resolveLocale`). A schema-aware merge walker decides, leaf
+ * by leaf, whether to take the source's value or keep the target's,
+ * driven by the `overwrite` flag. The merged tree is written via
+ * `createDocumentVersion({ action: 'copy_to_locale', locale: target })`
+ * — the existing cross-locale carry-forward in the storage primitive
+ * preserves every *other* locale's rows untouched.
+ *
+ * Non-localized fields are never altered by this operation: they live
+ * on `locale: 'all'` rows and the merge walker passes the target's
+ * value through so the write does not blank them.
+ *
+ * Path is sticky and lives on default-locale only; this operation never
+ * touches `byline_document_paths`. Status resets to the workflow
+ * default — translations land as drafts.
+ *
+ * Flow:
+ *   1. `assertActorCanPerform('update')` — same gate as a translation save.
+ *   2. Reject if `sourceLocale === targetLocale`.
+ *   3. Fetch source via `getDocumentById({ locale: sourceLocale })`.
+ *   4. Fetch target via `getDocumentById({ locale: targetLocale })`.
+ *   5. `mergeLocaleData(definition.fields, source.fields, target.fields, overwrite)`.
+ *   6. `hooks.beforeUpdate({ data, originalData, collectionPath, copyToLocale })`.
+ *   7. `createDocumentVersion({ documentId, action: 'copy_to_locale',
+ *      locale: targetLocale, documentData, previousVersionId, status })`.
+ *   8. `hooks.afterUpdate({ ..., copyToLocale })`.
+ */
+export async function copyToLocale(ctx, params) {
+    return withLogContext({ domain: 'services', module: 'lifecycle', function: 'copyToLocale' }, async () => {
+        const { db, definition, collectionId, collectionPath } = ctx;
+        assertActorCanPerform(ctx.requestContext, collectionPath, 'update');
+        if (params.sourceLocale === params.targetLocale) {
+            throw ERR_VALIDATION({
+                message: 'sourceLocale and targetLocale must differ',
+                details: {
+                    documentId: params.documentId,
+                    sourceLocale: params.sourceLocale,
+                    targetLocale: params.targetLocale,
+                },
+            }).log(ctx.logger);
+        }
+        // 1. Source read.
+        const source = await db.queries.documents.getDocumentById({
+            collection_id: collectionId,
+            document_id: params.documentId,
+            locale: params.sourceLocale,
+            reconstruct: true,
+            lenient: true,
+            requestContext: ctx.requestContext,
+        });
+        if (source == null) {
+            throw ERR_NOT_FOUND({
+                message: 'document not found in source locale',
+                details: {
+                    documentId: params.documentId,
+                    sourceLocale: params.sourceLocale,
+                    collectionPath,
+                },
+            }).log(ctx.logger);
+        }
+        // 2. Target read — needed for both originalData (hooks) and to
+        //    preserve non-localized values + structural shape.
+        const target = await db.queries.documents.getDocumentById({
+            collection_id: collectionId,
+            document_id: params.documentId,
+            locale: params.targetLocale,
+            reconstruct: true,
+            lenient: true,
+            requestContext: ctx.requestContext,
+        });
+        if (target == null) {
+            throw ERR_NOT_FOUND({
+                message: 'document not found in target locale',
+                details: {
+                    documentId: params.documentId,
+                    targetLocale: params.targetLocale,
+                    collectionPath,
+                },
+            }).log(ctx.logger);
+        }
+        const sourceRecord = source;
+        const targetRecord = target;
+        const sourceFields = sourceRecord.fields ?? {};
+        const targetFields = targetRecord.fields ?? {};
+        // 3. Merge.
+        const merged = mergeLocaleData(definition.fields, sourceFields, targetFields, params.overwrite);
+        // 4. Hooks see the target-locale view as originalData (consistent
+        //    with how updateDocument scopes originalData to the active
+        //    locale) and the merged payload as the next `data`.
+        const hooks = await resolveHooks(definition);
+        const copyToLocaleMarker = {
+            sourceLocale: params.sourceLocale,
+            targetLocale: params.targetLocale,
+        };
+        await invokeHook(hooks?.beforeUpdate, {
+            data: merged.data,
+            originalData: targetFields,
+            collectionPath,
+            copyToLocale: copyToLocaleMarker,
+        });
+        // 5. Write. previousVersionId threads the current version id so the
+        //    storage primitive's cross-locale carry-forward fires for every
+        //    *other* locale (not source, not target — those rows are
+        //    rewritten by this call).
+        const previousVersionId = targetRecord.document_version_id ?? undefined;
+        await applyRichTextEmbed(ctx, merged.data);
+        const writeResult = await db.commands.documents.createDocumentVersion({
+            documentId: params.documentId,
+            collectionId,
+            collectionVersion: ctx.collectionVersion,
+            collectionConfig: definition,
+            action: 'copy_to_locale',
+            documentData: merged.data,
+            status: getDefaultStatus(definition),
+            locale: params.targetLocale,
+            previousVersionId,
+        });
+        const documentVersionId = extractVersionId(writeResult.document);
+        await invokeHook(hooks?.afterUpdate, {
+            data: merged.data,
+            originalData: targetFields,
+            collectionPath,
+            documentId: params.documentId,
+            documentVersionId,
+            // Path is sticky and source-locale-anchored; copy-to-locale never
+            // touches it. Read it off the target envelope.
+            path: targetRecord.path ?? '',
+            copyToLocale: copyToLocaleMarker,
+        });
+        return {
+            documentId: params.documentId,
+            documentVersionId,
+            sourceLocale: params.sourceLocale,
+            targetLocale: params.targetLocale,
+            fieldsUpdated: merged.fieldsUpdated,
+        };
+    });
+}

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

@@ -0,0 +1,45 @@
+/**
+ * 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 type { DocumentLifecycleContext } from './context.js';
+export interface CreateDocumentResult {
+    documentId: string;
+    documentVersionId: string;
+}
+/**
+ * Create a new document.
+ *
+ * Flow:
+ *   1. Default-locale enforcement: reject if `params.locale` is anything
+ *      other than the configured default content locale (a brand-new
+ *      document's canonical `path` lives in the default locale).
+ *   2. `normaliseDateFields(data)`
+ *   3. `hooks.beforeCreate({ data, collectionPath })`
+ *   4. Resolve `path` — explicit `params.path` → derive via `useAsPath`
+ *      → UUID fallback.
+ *   5. `db.commands.documents.createDocumentVersion(...)` (action = 'create')
+ *   6. `hooks.afterCreate({ data, collectionPath, documentId, documentVersionId })`
+ */
+export declare function createDocument(ctx: DocumentLifecycleContext, params: {
+    data: Record<string, any>;
+    locale?: string;
+    status?: string;
+    /**
+     * Explicit, user-supplied path (e.g. from the admin sidebar widget
+     * or an SDK caller importing legacy content). When omitted, the
+     * 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/I18N.md.
+     */
+    availableLocales?: string[];
+}): Promise<CreateDocumentResult>;

package/dist/services/document-lifecycle/create.js

@@ -0,0 +1,91 @@
+/**
+ * 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 { resolveHooks } from '../../@types/index.js';
+import { assertActorCanPerform } from '../../auth/assert-actor-can-perform.js';
+import { ERR_VALIDATION } from '../../lib/errors.js';
+import { withLogContext } from '../../lib/logger.js';
+import { normaliseDateFields } from '../../utils/normalise-dates.js';
+import { slugify } from '../../utils/slugify.js';
+import { getDefaultStatus } from '../../workflow/workflow.js';
+import { assignCounterValues } from '../assign-counter-values.js';
+import { applyRichTextEmbed, derivePath, extractDocumentId, extractVersionId, invokeHook, maybeAppendOrderKey, rethrowPathConflict, } from './internals.js';
+/**
+ * Create a new document.
+ *
+ * Flow:
+ *   1. Default-locale enforcement: reject if `params.locale` is anything
+ *      other than the configured default content locale (a brand-new
+ *      document's canonical `path` lives in the default locale).
+ *   2. `normaliseDateFields(data)`
+ *   3. `hooks.beforeCreate({ data, collectionPath })`
+ *   4. Resolve `path` — explicit `params.path` → derive via `useAsPath`
+ *      → UUID fallback.
+ *   5. `db.commands.documents.createDocumentVersion(...)` (action = 'create')
+ *   6. `hooks.afterCreate({ data, collectionPath, documentId, documentVersionId })`
+ */
+export async function createDocument(ctx, params) {
+    return withLogContext({ domain: 'services', module: 'lifecycle', function: 'createDocument' }, async () => {
+        const { db, definition, collectionId, collectionPath, defaultLocale } = ctx;
+        assertActorCanPerform(ctx.requestContext, collectionPath, 'create');
+        const slugifier = ctx.slugifier ?? slugify;
+        const hooks = await resolveHooks(definition);
+        const data = params.data;
+        if (params.locale != null && params.locale !== defaultLocale) {
+            throw ERR_VALIDATION({
+                message: `documents must be created in the default content locale ('${defaultLocale}'); received '${params.locale}'. Create the default-locale version first, then add localised versions via update.`,
+                details: { defaultLocale, providedLocale: params.locale, collectionPath },
+            }).log(ctx.logger);
+        }
+        normaliseDateFields(data);
+        await invokeHook(hooks?.beforeCreate, { data, collectionPath });
+        // Allocate counter-field values after beforeCreate so user-land hooks
+        // can run their own logic on the raw payload, but before the flatten/
+        // insert pass so the assigned values are persisted on the same write.
+        // Caller-supplied counter values are overwritten — counters are
+        // allocator-assigned, never user-set.
+        await assignCounterValues({
+            fields: definition.fields,
+            data,
+            counters: db.commands.counters,
+        });
+        const explicitPath = typeof params.path === 'string' && params.path.length > 0 ? params.path : null;
+        const resolvedPath = explicitPath ?? derivePath(definition, data, defaultLocale, slugifier);
+        // Append-at-end order_key for `orderable: true` collections.
+        // Computed before the insert so the single createDocumentVersion call
+        // carries the key into the byline_documents row. No effect when the
+        // admin config opts out or isn't registered.
+        const orderKey = await maybeAppendOrderKey(ctx, collectionPath);
+        // Refresh embedded relation envelopes inside rich-text fields
+        // (internal-link / inline-image nodes) before flatten-and-persist.
+        await applyRichTextEmbed(ctx, data);
+        const result = await db.commands.documents
+            .createDocumentVersion({
+            collectionId,
+            collectionVersion: ctx.collectionVersion,
+            collectionConfig: definition,
+            action: 'create',
+            documentData: data,
+            path: resolvedPath,
+            availableLocales: params.availableLocales,
+            status: params.status ?? data.status ?? getDefaultStatus(definition),
+            locale: params.locale ?? defaultLocale,
+            orderKey,
+        })
+            .catch((err) => rethrowPathConflict(err, resolvedPath, defaultLocale));
+        const documentId = extractDocumentId(result.document);
+        const documentVersionId = extractVersionId(result.document);
+        await invokeHook(hooks?.afterCreate, {
+            data,
+            collectionPath,
+            documentId,
+            documentVersionId,
+            path: resolvedPath,
+        });
+        return { documentId, documentVersionId };
+    });
+}

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

@@ -0,0 +1,44 @@
+/**
+ * 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 type { DocumentLifecycleContext } from './context.js';
+export interface DeleteLocaleResult {
+    documentId: string;
+    /** The newly-created version that omits the deleted locale's content. */
+    documentVersionId: string;
+    /** The content locale that was removed. */
+    locale: string;
+}
+/**
+ * Remove one content locale's data from a document, in place on the same
+ * document, by writing a new immutable version that omits that locale's
+ * store rows (every other locale and all non-localized `'all'` rows are
+ * carried forward by the storage primitive).
+ *
+ * The default content locale is the document's anchor (path + source_locale)
+ * and can never be removed — rejected up front. The new version lands as the
+ * workflow's default status (a fresh draft), exactly like `copyToLocale`: the
+ * previously-published version keeps serving — including the locale being
+ * removed — until the new version is reviewed and published. The deletion is
+ * recoverable: the prior version still holds the locale, so restoring it
+ * brings the content back.
+ *
+ * Flow:
+ *   1. `assertActorCanPerform('update')` — removing a translation is an edit.
+ *   2. Reject `locale === defaultLocale`.
+ *   3. Read the document in the target locale (validates existence; supplies
+ *      `originalData` for hooks and the availability set for the presence
+ *      check).
+ *   4. Reject when the locale has no content to delete.
+ *   5. `hooks.beforeUpdate({ …, deleteLocale: { locale } })`.
+ *   6. `db.commands.documents.deleteDocumentLocale({ …, status: default })`.
+ *   7. `hooks.afterUpdate({ …, deleteLocale: { locale } })`.
+ */
+export declare function deleteLocale(ctx: DocumentLifecycleContext, params: {
+    documentId: string;
+    locale: string;
+}): Promise<DeleteLocaleResult>;

package/dist/services/document-lifecycle/delete-locale.js

@@ -0,0 +1,117 @@
+/**
+ * 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 { resolveHooks } from '../../@types/index.js';
+import { assertActorCanPerform } from '../../auth/assert-actor-can-perform.js';
+import { ERR_NOT_FOUND, ERR_VALIDATION } from '../../lib/errors.js';
+import { withLogContext } from '../../lib/logger.js';
+import { getDefaultStatus } from '../../workflow/workflow.js';
+import { invokeHook } from './internals.js';
+/**
+ * Remove one content locale's data from a document, in place on the same
+ * document, by writing a new immutable version that omits that locale's
+ * store rows (every other locale and all non-localized `'all'` rows are
+ * carried forward by the storage primitive).
+ *
+ * The default content locale is the document's anchor (path + source_locale)
+ * and can never be removed — rejected up front. The new version lands as the
+ * workflow's default status (a fresh draft), exactly like `copyToLocale`: the
+ * previously-published version keeps serving — including the locale being
+ * removed — until the new version is reviewed and published. The deletion is
+ * recoverable: the prior version still holds the locale, so restoring it
+ * brings the content back.
+ *
+ * Flow:
+ *   1. `assertActorCanPerform('update')` — removing a translation is an edit.
+ *   2. Reject `locale === defaultLocale`.
+ *   3. Read the document in the target locale (validates existence; supplies
+ *      `originalData` for hooks and the availability set for the presence
+ *      check).
+ *   4. Reject when the locale has no content to delete.
+ *   5. `hooks.beforeUpdate({ …, deleteLocale: { locale } })`.
+ *   6. `db.commands.documents.deleteDocumentLocale({ …, status: default })`.
+ *   7. `hooks.afterUpdate({ …, deleteLocale: { locale } })`.
+ */
+export async function deleteLocale(ctx, params) {
+    return withLogContext({ domain: 'services', module: 'lifecycle', function: 'deleteLocale' }, async () => {
+        const { db, definition, collectionId, collectionPath, defaultLocale } = ctx;
+        assertActorCanPerform(ctx.requestContext, collectionPath, 'update');
+        // The default locale anchors the document's path and source_locale —
+        // it cannot be deleted (the other locales fall back to it).
+        if (params.locale === defaultLocale) {
+            throw ERR_VALIDATION({
+                message: `cannot delete the default content locale ('${defaultLocale}')`,
+                details: { documentId: params.documentId, locale: params.locale, collectionPath },
+            }).log(ctx.logger);
+        }
+        // Read the document in the locale being removed — validates existence,
+        // supplies originalData for hooks, and the availability set for the
+        // content-presence check below.
+        const target = await db.queries.documents.getDocumentById({
+            collection_id: collectionId,
+            document_id: params.documentId,
+            locale: params.locale,
+            reconstruct: true,
+            lenient: true,
+            requestContext: ctx.requestContext,
+        });
+        if (target == null) {
+            throw ERR_NOT_FOUND({
+                message: 'document not found',
+                details: { documentId: params.documentId, collectionPath },
+            }).log(ctx.logger);
+        }
+        const targetRecord = target;
+        // `_availableVersionLocales` is the derived (path-coverage) set; it is
+        // the same source the editor's Delete-Locale picker is built from, so a
+        // locale offered in the UI resolves here. A partially-translated locale
+        // that never reached full coverage is not deletable through this path.
+        const available = targetRecord._availableVersionLocales ?? [];
+        if (!available.includes(params.locale)) {
+            throw ERR_NOT_FOUND({
+                message: `locale '${params.locale}' has no content to delete`,
+                details: { documentId: params.documentId, locale: params.locale, collectionPath },
+            }).log(ctx.logger);
+        }
+        const hooks = await resolveHooks(definition);
+        const deleteLocaleMarker = { locale: params.locale };
+        const originalData = targetRecord.fields ?? {};
+        await invokeHook(hooks?.beforeUpdate, {
+            data: originalData,
+            originalData,
+            collectionPath,
+            deleteLocale: deleteLocaleMarker,
+        });
+        const result = await db.commands.documents.deleteDocumentLocale({
+            documentId: params.documentId,
+            locale: params.locale,
+            status: getDefaultStatus(definition),
+        });
+        if (result == null) {
+            throw ERR_NOT_FOUND({
+                message: 'document not found',
+                details: { documentId: params.documentId, collectionPath },
+            }).log(ctx.logger);
+        }
+        await invokeHook(hooks?.afterUpdate, {
+            data: originalData,
+            originalData,
+            collectionPath,
+            documentId: params.documentId,
+            documentVersionId: result.newVersionId,
+            // Path is sticky and source-locale-anchored; deleting a translation
+            // never touches it. Read it off the target envelope.
+            path: targetRecord.path ?? '',
+            deleteLocale: deleteLocaleMarker,
+        });
+        return {
+            documentId: params.documentId,
+            documentVersionId: result.newVersionId,
+            locale: params.locale,
+        };
+    });
+}