import { TextMutationReceipt, SDMutationReceipt } from '../types/index.js';
import { InsertInput } from '../insert/insert.js';
import { ReplaceMutationOptions, ReplaceInput, TrackedReplaceMutationOptions } from '../replace/replace.js';
import { StoryLocator } from '../types/story.types.js';
import { SDHtmlMarkdownCheckGuard } from '../capabilities/html-markdown-support.js';
export type ChangeMode = 'direct' | 'tracked';
/**
 * Shared semantic validation for the `changeMode` mutation option.
 *
 * Error-code policy (v2-tracked-change-decision-error-contract plan, WS3):
 *   - A `changeMode` value of the wrong type is a malformed shape and surfaces
 *     `VALIDATION_ERROR`, including dynamic calls without upstream schema validation.
 *   - A `changeMode` *string* outside the accepted enum is a semantic option
 *     error and fails closed with `INVALID_INPUT`, not the generic
 *     `VALIDATION_ERROR`. This keeps semantic option failures distinct from
 *     structural schema failures across every mutation API that accepts
 *     `changeMode`.
 */
export declare function validateChangeMode(value: unknown): void;
/**
 * Subset of MutationOptions that provides only revision guarding.
 *
 * Used by operations that don't participate in the plan engine (comments,
 * clearContent, trackChanges.decide) where changeMode and dryRun are not
 * applicable.
 */
export interface RevisionGuardOptions {
    /** Caller correlation for this operation only; echoed only on committed receipts, never persisted. */
    changeTag?: string;
    /** When provided, the engine rejects with REVISION_MISMATCH if the document has advanced past this revision. */
    expectedRevision?: string;
}
export interface MutationOptions extends RevisionGuardOptions {
    /**
     * Controls whether mutation applies directly or as a tracked change.
     * Defaults to `direct`.
     */
    changeMode?: ChangeMode;
    /**
     * When true, adapters validate and resolve the operation but must not mutate state.
     * Defaults to `false`.
     */
    dryRun?: boolean;
}
/** Display-only attribution for one tracked mutation. */
export interface TrackedAttribution {
    author?: {
        name: string;
    };
    /** ISO 8601 UTC revision timestamp. Omitted values use the transaction time. */
    date?: string;
}
export interface RichContentMutationOptions extends MutationOptions {
    author?: never;
    date?: never;
    /** Guard returned by `doc.capabilities.check` for an exact rich write. */
    supportCheck?: SDHtmlMarkdownCheckGuard;
}
export interface TrackedTextMutationOptions extends MutationOptions, TrackedAttribution {
    changeMode: 'tracked';
}
export type TrackedRichContentMutationOptions = TrackedTextMutationOptions & Pick<RichContentMutationOptions, 'supportCheck'>;
export type TextMutationOptions = (MutationOptions & {
    author?: never;
    date?: never;
}) | TrackedTextMutationOptions;
export declare function normalizeTextMutationOptions(options?: RichContentMutationOptions | TextMutationOptions): RichContentMutationOptions | TrackedTextMutationOptions;
export declare function normalizeRichMutationOptions(options: (MutationOptions & TrackedAttribution & Pick<RichContentMutationOptions, 'supportCheck'>) | undefined, supportCheckOperation?: 'insert' | 'replace'): RichContentMutationOptions | TrackedRichContentMutationOptions;
/**
 * Text insertion request: target-less insert at document end.
 *
 * Targeted inserts now route through `SelectionMutationAdapter`. This
 * request type only handles the no-target fallback (append to document end).
 */
export type InsertWriteRequest = {
    kind: 'insert';
    text: string;
    /** Target a specific document story (body, header, footer, footnote, endnote). */
    in?: StoryLocator;
};
/**
 * Alias for `InsertWriteRequest`. Retained because adapter utilities and
 * plan wrappers still reference this name.
 */
export type WriteRequest = InsertWriteRequest;
/**
 * Adapter interface for write operations. After the selection-first delete
 * cutover, only `insert` routes through `write()`. Delete and replace use
 * `SelectionMutationAdapter` instead.
 */
export interface WriteAdapter {
    readonly supportsParagraphContents?: boolean;
    readonly supportsNativeOoxml?: boolean;
    write(request: InsertWriteRequest, options?: TextMutationOptions): TextMutationReceipt;
    /** Structured insert for SDFragment or markdown/html content. Returns SDMutationReceipt. */
    insertStructured(input: InsertInput, options?: RichContentMutationOptions | TrackedRichContentMutationOptions): SDMutationReceipt;
    /** Structured replace for SDFragment or markdown/html content. Returns SDMutationReceipt. */
    replaceStructured(input: ReplaceInput, options?: ReplaceMutationOptions | TrackedReplaceMutationOptions): SDMutationReceipt;
}
export declare function normalizeMutationOptions(options?: MutationOptions | RichContentMutationOptions, supportCheckOperation?: 'insert' | 'replace'): RichContentMutationOptions;
export declare function executeWrite(adapter: WriteAdapter, request: InsertWriteRequest, options?: TextMutationOptions): TextMutationReceipt;