/**
 * Wait / human-gate host API (events doc v0.1.2 §2.4, Step 8 of 10).
 *
 * Three operations:
 *   - `createWait`  — declares a wait activity; writes `waitCreated`.
 *   - `resolveWait` — closes a wait by external decision; writes
 *                     `waitResolved` + activity terminal.
 *   - `expireWait`  — closes a wait by deadline; writes
 *                     `waitDeadlineExceeded` + activity terminal.
 *
 * Spec contract (§2.4):
 *   - `waitResolved` is NOT a terminal event; activity terminal follows.
 *   - `approved` resolution → `activitySucceeded`.
 *   - `rejected` resolution → `activityFailed { WaitDeadlineExceeded?, userFault }`.
 *     Per spec the errorCode for rejection isn't explicitly enumerated;
 *     v0 picks `userFault` class with a reusable code so dashboards can
 *     filter.  We use `InputValidationFailed` — closest fit from the
 *     existing enum (rejection is "input not accepted").
 *   - `external` resolution → `activitySucceeded` with the resolution
 *     reflected in `externalRefs.resolution = 'external'`.
 *   - `waitDeadlineExceeded` → either `activityFailed` ({WaitDeadlineExceeded,
 *     userFault}) when `onTimeout='fail'` (default), or
 *     `activitySucceeded { externalRefs.defaultedToTimeout=true }` when
 *     `onTimeout='success'` (spec §6 open Q7 resolved at Step 8).
 *
 * Step 8 does NOT:
 *   - schedule deadline timers (caller wires them up; we just write the
 *     event when the timer fires);
 *   - implement cancel propagation (Step 9).
 */
import type { EventLog } from './events/append.js';
import type { OutputRef } from './events/payloads.js';
import type { ActivityFailedEvent, ActivitySucceededEvent, WaitCreatedEvent, WaitDeadlineExceededEvent, WaitResolvedEvent } from './events/types.js';
import type { WorkflowDefinition } from './definition.js';
export type WaitKind = 'human-gate' | 'time' | 'condition';
export type WaitResolution = 'approved' | 'rejected' | 'external';
export type WaitOnTimeout = 'fail' | 'success';
export type CreateWaitInput = {
    activityId: string;
    attemptId: string;
    nodeId: string;
    waitKind: WaitKind;
    /** Wall-clock ms epoch.  Required for `time` kind, optional otherwise. */
    deadlineAt?: number;
    /** Human-readable prompt (rendered to approvers / dashboards).  Small
     *  prompts go here inline; large ones spill to `promptRef` per
     *  `checkWaitCreatedPromptInvariant` (mutually exclusive). */
    prompt?: string;
    /** Blob spill for prompts that don't fit in the inline envelope.
     *  Consumers (card-builder / dashboard) read the blob on demand;
     *  replay never touches it. */
    promptRef?: OutputRef;
    /** Required short preview when `promptRef` is set so cards / dashboards
     *  can render without reading the blob.  Up to 500 chars (schema cap);
     *  producer is responsible for keeping bytes reasonable for UTF-8. */
    promptPreview?: string;
    /** Optional open_id allow list for human-gate card actions. */
    approvers?: string[];
    /** What to write as the activity terminal when the deadline fires
     *  without resolution.  Default `fail` (spec default). */
    onTimeout?: WaitOnTimeout;
};
export type ResolveWaitInput = {
    activityId: string;
    attemptId: string;
    resolution: WaitResolution;
    /** Identifier of the resolver — open_id / system actor name. */
    by: string;
    comment?: string;
    /**
     * Extra business output to record in the resulting
     * `activitySucceeded.externalRefs` (only used when the resolution
     * leads to success — approved / external).  Ignored for rejected.
     */
    output?: Record<string, unknown>;
};
export type ExpireWaitInput = {
    activityId: string;
    attemptId: string;
    /** Wall-clock ms at which the deadline was scheduled. */
    deadlineAt: number;
    /** Wall-clock ms when the timer actually fired (may be slightly later
     *  due to scheduler latency). */
    exceededAtMs: number;
    /** Policy for the resulting activity terminal.  Default `fail`. */
    onTimeout?: WaitOnTimeout;
};
export type ResolveWaitResult = {
    resolutionEvent: WaitResolvedEvent;
    terminalEvent: ActivitySucceededEvent | ActivityFailedEvent;
    /** Convenience surface of the resolution event's eventId — useful as
     *  the loop runtime's `waitResolvedEventId` audit anchor without
     *  reaching into `.resolutionEvent.eventId`. */
    waitResolvedEventId: string;
};
/**
 * Optional context for resolveWait.  When `def` is supplied, resolveWait
 * recognises `decision` nodes (v0.2 loop terminators) and writes their
 * terminal as `activitySucceeded` with a fixed `{resolution, by, comment?}`
 * output blob — including the `rejected` case, which for plain nodes
 * still maps to `activityFailed`.  See /tmp/wf-loop-v02.md §4.3 N2.
 */
export type ResolveWaitContext = {
    def?: WorkflowDefinition;
};
export type ExpireWaitResult = {
    deadlineEvent: WaitDeadlineExceededEvent;
    terminalEvent: ActivitySucceededEvent | ActivityFailedEvent;
};
/**
 * Declare a wait activity.  Writes `waitCreated`.  The caller is
 * responsible for advancing the parent node into `waiting` via
 * `nodeWaiting` (scheduling concern, not host-API).
 */
export declare function createWait(log: EventLog, input: CreateWaitInput): Promise<WaitCreatedEvent>;
/**
 * Close a wait via external decision.  Writes `waitResolved` followed
 * by the activity terminal.  The terminal mapping is fixed by spec
 * §2.4 for plain nodes:
 *   - approved → activitySucceeded
 *   - rejected → activityFailed { InputValidationFailed, userFault }
 *   - external → activitySucceeded { externalRefs.resolution='external' }
 *
 * For v0.2 `decision` nodes (loop terminators), the mapping is different:
 * BOTH approve and reject resolve to `activitySucceeded` with a fixed
 * `{resolution, by, comment?}` output blob — rejection is a legal
 * decision output, not a failure.  Pass `ctx.def` so resolveWait can
 * look up the node type via `parseActivityId(activityId).nodeId`.
 */
export declare function resolveWait(log: EventLog, input: ResolveWaitInput, ctx?: ResolveWaitContext): Promise<ResolveWaitResult>;
/**
 * Close a wait via deadline expiry.  Writes `waitDeadlineExceeded`
 * followed by the activity terminal driven by `onTimeout` (default
 * `fail`).
 *
 * The terminal policy:
 *   - fail (default) → activityFailed { WaitDeadlineExceeded, userFault }
 *   - success        → activitySucceeded { externalRefs.defaultedToTimeout=true }
 */
export declare function expireWait(log: EventLog, input: ExpireWaitInput): Promise<ExpireWaitResult>;
//# sourceMappingURL=wait.d.ts.map