/**
 * 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 { LockedDocumentRevision } from '../../@types/index.js';
import type { DocumentLifecycleContext } from './context.js';
export interface UpdateDocumentSystemFieldsResult {
    documentId: string;
    revision: number;
    /** The path actually written, or `undefined` when no path write occurred. */
    path?: string;
    /** Whether either system field actually changed. */
    changed: boolean;
    /** Whether a no-op request emitted the reconciliation hook. */
    reconciliation: boolean;
    pathChanged: boolean;
    availableLocalesChanged: boolean;
    /** Whether the advertised-locale set was actually rewritten this call. */
    availableLocalesWritten: boolean;
}
/**
 * Write a document's system-managed, document-grain fields — `path` and the
 * editorial `availableLocales` set — **without** minting a new version or
 * touching workflow status.
 *
 * These fields are document-grain (they live in `byline_document_paths` and
 * `byline_document_available_locales`, keyed by logical document, sticky across
 * versions), so a workflow status change would falsely imply the edit is gated
 * behind publish. It is not: the write is immediate and applies across every
 * version. This service backs the admin path / available-locales widgets'
 * direct-write Save (the `direct-write` and `both` dirty-reason cases). The
 * public *advertised* set remains the intersection of `availableLocales` with
 * the resolved version's completeness ledger. See docs/08-internationalization/index.md.
 *
 * Flow:
 *   1. `assertActorCanPerform('update')` — same auth gate as content writes.
 *   2. Inside the audit transaction, lock the logical document and read its
 *      authoritative source locale, path, and advertised locales.
 *   3. Path (when supplied): `resolvePathForUpdate` enforces the source-locale
 *      rule (translation-locale path edits are dropped with a warn); a real
 *      change is written via `updateDocumentPath`, mapping the unique-constraint
 *      violation to `ERR_PATH_CONFLICT`.
 *   4. `availableLocales` (when supplied): rewritten wholesale via
 *      `setDocumentAvailableLocales`.
 *
 * Content hooks do not fire because these are not content writes. Actual
 * changes emit `afterSystemFieldsChange` after the audited write commits. A
 * caller can pass `reconcile: true` to emit the same hook for a no-op retry
 * after an earlier post-commit hook failure. Hook failures reject the call but
 * never roll back the already-committed write/audit.
 * Accountability for these mutations is the document-grain audit log: each
 * changed field records a `document.path.changed` /
 * `document.locales.changed` row atomically with the write.
 *
 * @throws {BylineError} ERR_NOT_FOUND if the document does not exist.
 * @throws {BylineError} ERR_PATH_CONFLICT if the path is already in use.
 */
export declare function updateDocumentSystemFields(ctx: DocumentLifecycleContext, params: {
    documentId: string;
    expectedRevision: number;
    locale?: string;
    /**
     * Explicit path override from the path widget. `null` / empty / omitted
     * means "no path write" (the existing row stays sticky). A non-empty
     * string is written when the request locale is the document's source
     * locale; on a translation locale it is dropped with a warn.
     */
    path?: string | null;
    /**
     * The editorial advertised-locale set from the available-locales widget.
     * `undefined` means "no advertised-locale write"; an explicit array — `[]`
     * included — replaces the set wholesale.
     */
    availableLocales?: string[];
    /** Re-run `afterSystemFieldsChange` when requested values are already current. */
    reconcile?: boolean;
}): Promise<UpdateDocumentSystemFieldsResult>;
export type SystemFieldMutationParams = Parameters<typeof updateDocumentSystemFields>[1];
/** Internal storage phase; caller owns the document guard and revision advancement. */
export declare function writeSystemFieldsInTransaction(ctx: DocumentLifecycleContext, params: SystemFieldMutationParams, locked: LockedDocumentRevision): Promise<{
    requested: {
        path: boolean;
        availableLocales: boolean;
    };
    pathForCommand: string | undefined;
    pathChanged: boolean;
    availableLocalesChanged: boolean;
    previousPath: string | undefined;
    currentPath: string | undefined;
    previousAvailableLocales: string[];
    currentAvailableLocales: string[];
}>;
export declare function finishSystemFieldMutation(ctx: DocumentLifecycleContext, params: SystemFieldMutationParams, outcome: Awaited<ReturnType<typeof writeSystemFieldsInTransaction>> & {
    documentVersionId: string;
}, revision: number): Promise<UpdateDocumentSystemFieldsResult>;