import type { MappedItem, ProcessInstance, ProcessProject, ProcessTurnTerminalLifecycleStatus, TurnId } from "@leitwerk-dev/domain";
import type { LlmTurnDefinition } from "./define-process.js";
import type { Codec, ProcessTurnOutcomeEvent } from "./extension-api.js";
/** @public */
type MaybePromise<T> = T | Promise<T>;
/** Maximum length of a mapped item key. @internal */
export declare const MAPPED_ITEM_KEY_MAX_LENGTH = 200;
/** Maximum length of a mapped item label. @internal */
export declare const MAPPED_ITEM_LABEL_MAX_LENGTH = 200;
/** Maximum number of items frozen by one mapped run. @internal */
export declare const MAPPED_ITEM_MAX_COUNT = 500;
/** Graph trigger used by a mapped turn's collection route. @internal */
export declare const MAPPED_COLLECT_TRIGGER: "collect";
/** @internal */
export declare function mappedCollectTrigger(branchId?: string): string;
/** Durable snapshot of process data available to mapped-turn server callbacks. @public */
export interface MappedTurnServerContext<TParams = unknown, TState = unknown> {
    /** @public */
    readonly process: ProcessInstance;
    /** @internal */
    readonly projects: readonly ProcessProject[];
    /** @public */
    readonly params: TParams;
    /** @public */
    readonly state: TState;
}
/** Active item of a mapped LLM turn, as delivered to one worker turn. @public */
export interface MappedTurnItemContext<TItem = unknown> {
    /** Frozen, codec-validated item value. @public */
    readonly item: TItem;
    /** Stable key unique within the run. @public */
    readonly itemKey: string;
    /** Short plain-text label shown to operators. @public */
    readonly itemLabel: string;
    /** Zero-based position in the frozen order. @public */
    readonly itemIndex: number;
    /** Number of frozen items in the run. @public */
    readonly itemCount: number;
}
/** Serialized active item carried by worker payloads and turn records. @internal */
export interface MappedTurnIteration extends MappedTurnItemContext<unknown> {
    /** @internal */
    readonly runId: string;
}
/** @public */
export interface MappedItemInput<TItem = unknown> {
    /** @public */
    readonly item: TItem;
    /** @public */
    readonly index: number;
}
/** @public */
export interface MappedSnapshotInput<TParams = unknown, TState = unknown, TItem = unknown> {
    /** @public */
    readonly params: TParams;
    /** @public */
    readonly state: TState;
    /** @public */
    readonly items: readonly TItem[];
}
/** Context passed to a mapped outcome's `yield` callback. @public */
export interface MappedOutcomeContext<TParams = unknown, TState = unknown, TItem = unknown> extends MappedTurnServerContext<TParams, TState>, MappedTurnItemContext<TItem> {
}
/** @public */
export interface MappedYieldInput<TParams = unknown, TState = unknown, TItem = unknown> {
    /** @public */
    readonly ctx: MappedOutcomeContext<TParams, TState, TItem>;
    /** @public */
    readonly event: ProcessTurnOutcomeEvent;
}
/** @public */
export type MappedItemYield<TParams = unknown, TState = unknown, TItem = unknown, TResult = unknown> = (input: MappedYieldInput<TParams, TState, TItem>) => MaybePromise<TResult>;
/** @public */
export type MappedCollect<TParams = unknown, TState = unknown, TResult = unknown> = (ctx: MappedTurnServerContext<TParams, TState>, orderedResults: readonly TResult[]) => MaybePromise<TState>;
/** Route applied once, after collection. @internal */
export type MappedCollectRouting<TParams = unknown, TState = unknown> = {
    /** @internal */
    kind: "static";
    /** @internal */
    to?: TurnId;
    /** @internal */
    lifecycleStatus?: ProcessTurnTerminalLifecycleStatus;
} | {
    /** @internal */
    kind: "branches";
    /** @internal */
    branches: Readonly<Record<string, TurnId>>;
    /** @internal */
    choose(ctx: MappedTurnServerContext<TParams, TState>): MaybePromise<string>;
};
/**
 * Durable sequential iteration of one LLM turn over frozen items. Items run one
 * at a time; each item yields a typed result, and business state and routing
 * change once, when all results are collected.
 * @public
 */
export interface MappedLlmTurnSpec<TParams = unknown, TState = unknown, TItem = unknown, TResult = unknown> {
    /** Evaluated once when the turn is entered. @public */
    items(ctx: MappedTurnServerContext<TParams, TState>): readonly unknown[] | null | undefined;
    /** @public */
    itemCodec: Codec<TItem>;
    /** @public */
    resultCodec: Codec<TResult>;
    /** @public */
    key(input: MappedItemInput<TItem>): string;
    /** Defaults to the item key. @public */
    label?(input: MappedItemInput<TItem>): string;
    /** Applied in the freezing transaction, before any item starts. @public */
    stateAfterSnapshot?(input: MappedSnapshotInput<TParams, TState, TItem>): TState;
    /** @internal */
    yields: Readonly<Record<string, MappedItemYield<TParams, TState, TItem, TResult>>>;
    /** @internal */
    collect: MappedCollect<TParams, TState, TResult>;
    /** @internal */
    routing: MappedCollectRouting<TParams, TState>;
}
/** @internal */
export type FrozenMappedItem = Pick<MappedItem, "itemIndex" | "itemKey" | "label" | "itemJson">;
/** @internal */
export interface MappedFreezeResult<TState = unknown> {
    /** @internal */
    items: FrozenMappedItem[];
    /** State to persist in the freezing transaction, when `stateAfterSnapshot` is declared. @internal */
    state?: TState;
}
/** @internal */
export interface MappedCollectResult<TState = unknown> {
    /** @internal */
    state: TState;
    /** @internal */
    route: {
        /** @internal */
        trigger: string;
        /** @internal */
        nextTurnId?: TurnId;
        /** @internal */
        lifecycleStatus?: ProcessTurnTerminalLifecycleStatus;
    };
}
/** @internal */
export declare function validateMappedTurn<TOutcome extends string, TParams, TState>(turnId: string, turnDef: LlmTurnDefinition<TOutcome, TParams, TState>): string[];
/** Evaluates, validates, and serializes the items of a mapped turn. @internal */
export declare function freezeMappedItems<TParams, TState>(turnId: TurnId, spec: MappedLlmTurnSpec<TParams, TState>, ctx: MappedTurnServerContext<TParams, TState>): MappedFreezeResult<TState>;
/** Maps one item outcome to its serialized, codec-validated result. @internal */
export declare function yieldMappedItemResult<TParams, TState>(input: {
    /** @internal */
    turnId: TurnId;
    /** @internal */
    spec: MappedLlmTurnSpec<TParams, TState>;
    /** @internal */
    ctx: MappedTurnServerContext<TParams, TState>;
    /** @internal */
    iteration: MappedTurnIteration;
    /** @internal */
    event: ProcessTurnOutcomeEvent;
}): Promise<string>;
/** Collects ordered results once and resolves the turn's single business route. @internal */
export declare function collectMappedResults<TParams, TState>(input: {
    /** @internal */
    turnId: TurnId;
    /** @internal */
    spec: MappedLlmTurnSpec<TParams, TState>;
    /** @internal */
    ctx: MappedTurnServerContext<TParams, TState>;
    /** Serialized results in frozen item order. @internal */
    resultJsons: readonly string[];
}): Promise<MappedCollectResult<TState>>;
export {};
//# sourceMappingURL=mapped-turn.d.ts.map