/**
 * request-lifecycle — pure state machine for Human Function requests.
 *
 * No I/O, no framework deps. Safe to import in any context (browser, workers,
 * Node, edge).
 *
 * Request kinds: approve | ask | decide | review | do | notify
 *
 * Status graph:
 *   pending     → claimed                          (claim)
 *   claimed     → in_progress                      (startProgress)
 *   claimed     → released                         (release)
 *   in_progress → released                         (release)
 *   in_progress → completed                        (resolve)
 *   claimed     → completed  (shortcut — no startProgress required)
 *   pending | claimed | in_progress → timeout      (timeout)
 *   pending | claimed | in_progress → escalated    (escalate)
 *   pending | claimed | in_progress → cancelled    (cancel)
 *
 * Fail-closed: invalid transitions return an Error, never mutate the input.
 *
 * All 6 request kinds (approve | ask | decide | review | do | notify) share
 * the same transition surface — kind-specific behaviour is encoded in the
 * item's payload fields, not in the state machine itself.
 */
/**
 * The six canonical kinds of Human Function requests.
 *
 * These are THE canonical names, matching the Cascade execution model verbs
 * per CONTEXT.md (ADR 0001) and the management.studio FunctionKind surface.
 *
 * The verbose `HumanRequest.type` values (`approval | question | task |
 * decision | review | notification`) from the v2.1.4 published package are
 * kept as **deprecated aliases** for backward compatibility with existing
 * consumers. Use `legacyKindToRequestKind` to convert them.
 *
 * Mapping (legacy → canonical):
 *   'approval'     → 'approve'
 *   'question'     → 'ask'
 *   'task'         → 'do'
 *   'decision'     → 'decide'
 *   'review'       → 'review'   (unchanged)
 *   'notification' → 'notify'
 */
export type RequestKind = 'approve' | 'ask' | 'decide' | 'review' | 'do' | 'notify';
/**
 * Legacy kind values from HumanRequest.type (v2.1.4).
 *
 * @deprecated Use `RequestKind` instead. These verbose names are kept only
 * for backward compatibility with existing consumers of `human-in-the-loop@2.1.4`.
 * Migrate callers to the canonical single-word verbs (`RequestKind`).
 */
export type LegacyRequestKind = 'approval' | 'question' | 'task' | 'decision' | 'review' | 'notification';
/**
 * Mapping from legacy `HumanRequest.type` values to canonical `RequestKind`.
 *
 * @deprecated Exists only for migration of existing consumers. New code
 * should use `RequestKind` values directly.
 */
export declare const LEGACY_KIND_MAP: Record<LegacyRequestKind, RequestKind>;
/**
 * Convert a legacy `HumanRequest.type` value to the canonical `RequestKind`.
 *
 * Use this helper when consuming requests from existing v2.1.4 stores or
 * API responses that still carry the verbose type names.
 *
 * @param legacyKind - The legacy `HumanRequest.type` value
 * @returns The canonical `RequestKind`
 *
 * @deprecated Migration helper only. New code should produce `RequestKind`
 * values directly.
 *
 * @example
 * legacyKindToRequestKind('approval') // → 'approve'
 * legacyKindToRequestKind('question') // → 'ask'
 */
export declare function legacyKindToRequestKind(legacyKind: LegacyRequestKind): RequestKind;
/**
 * Status of a lifecycle item.
 *
 * Extends HumanRequestStatus from types.ts with the management.studio-proven
 * status set (adds 'claimed' and 'released' for queue-hold semantics).
 */
export type LifecycleStatus = 'pending' | 'claimed' | 'in_progress' | 'completed' | 'released' | 'timeout' | 'escalated' | 'cancelled';
/**
 * Priority level for lifecycle items.
 *
 * Matches Priority from types.ts — re-declared here so this module has
 * no import dependencies (pure portability).
 */
export type LifecyclePriority = 'low' | 'normal' | 'high' | 'critical';
/**
 * A lightweight reference to the artifact (Object in the SVO triple)
 * being acted upon by a Human Function.
 */
export interface ArtifactRef {
    /** Resource kind (e.g. 'Invoice', 'Refund', 'PullRequest') */
    kind: string;
    /** Unique ID of the artifact */
    id: string;
    /** Human-readable title */
    title?: string;
    /** URL to the artifact if navigable */
    url?: string;
    /** Arbitrary context fields from the originating Workflow */
    context?: Record<string, unknown>;
}
/**
 * Cascade provenance — where the Human Function originated.
 */
export interface CascadeRef {
    workflowId?: string;
    workflowTitle?: string;
    cascadeId?: string;
    /** ID of the function that produced this item; used for escalation threading */
    functionId?: string;
}
/**
 * The resolution recorded when a Human Function reaches 'completed'.
 */
export interface Resolution {
    /**
     * Action verb: 'approve' | 'reject' | 'answered' | 'decided' | 'reviewed' | 'done'
     * For 'notify' kind the typical verb is 'acknowledged'.
     */
    verb: string;
    /** Who resolved it (personId / assignee identifier) */
    resolvedBy: string;
    /** When it was resolved */
    resolvedAt: Date;
    /** Optional comments from the resolver */
    comments?: string;
    /** Arbitrary additional data (approval code, decision value, etc.) */
    data?: Record<string, unknown>;
}
/**
 * A Human Function lifecycle item.
 *
 * This is the canonical upstream type. It reconciles with the management.studio
 * fixture HumanFunction shape (hitl-queue/types.ts) and extends the package's
 * existing HumanRequest<TInput, TOutput> with queue-specific fields.
 *
 * The state machine operates on this type.
 */
export interface LifecycleItem {
    /** Unique ID */
    id: string;
    /** Request kind — drives resolution UI and verb set */
    kind: RequestKind;
    /**
     * Kind-specific payload. Exactly one of these is populated based on `kind`:
     *   ask    → askPayload
     *   decide → decidePayload
     *   review → reviewPayload
     *   do     → doPayload
     *   approve / notify — no extra payload needed
     */
    askPayload?: {
        question: string;
        suggestions?: string[];
        /** If set, the answer must be one of these values */
        outputSchema?: string[];
    };
    decidePayload?: {
        options: string[];
        criteria?: string;
    };
    reviewPayload?: {
        content: string;
        criteria?: string;
    };
    doPayload?: {
        instructions: string;
        tools?: string[];
    };
    /** Current lifecycle status */
    status: LifecycleStatus;
    /** Priority — drives queue sort order */
    priority: LifecyclePriority;
    /** Human-readable title */
    title: string;
    /** Detailed description */
    description?: string;
    /** The artifact (Thing) this Function is about — the Action Object */
    artifact: ArtifactRef;
    /** The Person (or team/role) this Function is assigned to */
    assignee: string;
    /** Team scope */
    teamId?: string;
    /** Business scope */
    businessId?: string;
    /** Studio scope */
    studioId?: string;
    cascade?: CascadeRef;
    /** When the Function was created */
    createdAt: Date;
    /** When the SLA deadline fires */
    slaDeadline: Date;
    /** When the item was last updated */
    updatedAt: Date;
    /** Who claimed it (assignee identifier), if claimed */
    claimedBy?: string;
    /** When it was claimed */
    claimedAt?: Date;
    /** When it reached a terminal status */
    completedAt?: Date;
    /** The resolution (set when status becomes 'completed') */
    resolution?: Resolution;
}
export interface ClaimInput {
    /** Identifier of the claimer (personId / assignee id) */
    claimedBy: string;
    /** When the claim happened (defaults to now) */
    claimedAt?: Date;
}
export interface StartProgressInput {
    /** When work started (defaults to now) */
    startedAt?: Date;
}
export interface ReleaseInput {
    /** Identifier of who released the item */
    releasedBy: string;
}
export interface ResolveInput {
    /** Action verb: 'approve' | 'reject' | 'answered' | 'decided' | 'reviewed' | 'done' */
    verb: string;
    /** Who resolved it */
    resolvedBy: string;
    /** When resolved (defaults to now) */
    resolvedAt?: Date;
    /** Optional comments */
    comments?: string;
    /** Optional arbitrary additional data */
    data?: Record<string, unknown>;
}
export interface TimeoutInput {
    /** When the timeout occurred (defaults to now) */
    timedOutAt?: Date;
}
export interface EscalateInput {
    /** When escalation occurred (defaults to now) */
    escalatedAt?: Date;
    /** Optional human-readable reason for escalation */
    reason?: string;
}
export interface CancelInput {
    /** When cancellation occurred (defaults to now) */
    cancelledAt?: Date;
    /** Optional reason for cancellation */
    reason?: string;
}
/**
 * claim — pending → claimed
 *
 * Locks the item to a specific claimer so others cannot claim it.
 * Fail-closed: returns Error if item is not pending.
 */
export declare function claim(item: LifecycleItem, input: ClaimInput): LifecycleItem | Error;
/**
 * startProgress — claimed → in_progress
 *
 * Moves from claimed to in_progress (work has started).
 * Fail-closed: returns Error if item is not claimed.
 */
export declare function startProgress(item: LifecycleItem, input: StartProgressInput): LifecycleItem | Error;
/**
 * release — claimed | in_progress → released
 *
 * Returns the item to the queue (e.g. IC cannot handle it right now).
 * Strips claimer info so the item is available for re-claiming.
 * Fail-closed: returns Error if item is not claimed or in_progress.
 */
export declare function release(item: LifecycleItem, input: ReleaseInput): LifecycleItem | Error;
/**
 * resolve — in_progress | claimed → completed
 *
 * Records the final resolution (approve, reject, answered, decided, etc.).
 *
 * UX note: claim → (optional startProgress) → resolve.
 * Resolving directly from 'claimed' is allowed as a shortcut for
 * approve/reject flows where clicking a button is the entire resolution.
 *
 * Fail-closed: returns Error if item is not in_progress or claimed.
 */
export declare function resolve(item: LifecycleItem, input: ResolveInput): LifecycleItem | Error;
/**
 * timeout — pending | claimed | in_progress → timeout
 *
 * SLA breach: item was not resolved in time.
 * Fail-closed: returns Error if item is already terminal.
 */
export declare function timeout(item: LifecycleItem, input: TimeoutInput): LifecycleItem | Error;
/**
 * escalate — pending | claimed | in_progress → escalated
 *
 * Manual or policy-driven escalation to a higher tier.
 * Fail-closed: returns Error if item is already terminal.
 */
export declare function escalate(item: LifecycleItem, input: EscalateInput): LifecycleItem | Error;
/**
 * cancel — pending | claimed | in_progress → cancelled
 *
 * Workflow-side cancellation before resolution.
 * Fail-closed: returns Error if item is already terminal.
 */
export declare function cancel(item: LifecycleItem, input: CancelInput): LifecycleItem | Error;
/**
 * forAssignee — filter items by assignee identifier.
 *
 * Returns only items where item.assignee === assigneeId.
 * Does NOT filter by status — callers can filter further if needed.
 * Pure — does not mutate the input array.
 */
export declare function forAssignee(items: LifecycleItem[], assigneeId: string): LifecycleItem[];
/**
 * sortByPriorityThenSLA — sort items for queue display.
 *
 * Primary:   priority descending (critical → high → normal → low).
 * Secondary: SLA proximity ascending (closest to deadline first).
 *
 * Items with the same priority that are closest to their SLA deadline
 * appear first — i.e., the most urgent work bubbles to the top.
 *
 * Pure — does not mutate the input array.
 */
export declare function sortByPriorityThenSLA(items: LifecycleItem[], now: Date): LifecycleItem[];
/**
 * timeToDeadline — milliseconds until the SLA deadline from `now`.
 *
 * Negative value means SLA has already breached.
 */
export declare function timeToDeadline(item: LifecycleItem, now: Date): number;
/**
 * isBreached — true if the SLA deadline has passed.
 */
export declare function isBreached(item: LifecycleItem, now: Date): boolean;
//# sourceMappingURL=request-lifecycle.d.ts.map