import { TextMutationReceipt, SDMutationReceipt } from '../types/index.js';
import { InsertInput } from '../insert/insert.js';
import { ReplaceInput } 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 is left
 *     to upstream structural/schema validation (which surfaces
 *     `VALIDATION_ERROR`). This validator does not touch non-string values.
 *   - 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 {
    /** 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;
}
export interface RichContentMutationOptions extends MutationOptions {
    /** Guard returned by `doc.capabilities.check` for an exact rich write. */
    supportCheck?: SDHtmlMarkdownCheckGuard;
}
/**
 * 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 {
    write(request: InsertWriteRequest, options?: MutationOptions): TextMutationReceipt;
    /** Structured insert for SDFragment or markdown/html content. Returns SDMutationReceipt. */
    insertStructured(input: InsertInput, options?: RichContentMutationOptions): SDMutationReceipt;
    /** Structured replace for SDFragment or markdown/html content. Returns SDMutationReceipt. */
    replaceStructured(input: ReplaceInput, options?: RichContentMutationOptions): SDMutationReceipt;
}
export declare function normalizeMutationOptions(options?: MutationOptions | RichContentMutationOptions, supportCheckOperation?: 'insert' | 'replace'): RichContentMutationOptions;
export declare function executeWrite(adapter: WriteAdapter, request: InsertWriteRequest, options?: MutationOptions): TextMutationReceipt;