/**
 * Pure derivation functions for the execution waterfall timeline.
 *
 * Converts an append-only event list into positioned waterfall entries
 * (horizontal bars on a time axis) and a scale specification for the
 * time axis labels/ticks.
 *
 * No React dependency — independently importable and testable (DD-003).
 *
 * @since T07 (Execution Waterfall Timeline)
 */
import type { WorkflowExecutionEvent } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/event_pb";
import type { WorkflowTaskKind } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/enum_pb";
import type { DerivedTaskState } from "../../internal/store/workflow-execution-event-store.js";
/** A single task row in the waterfall timeline. */
export interface WaterfallEntry {
    readonly taskName: string;
    readonly taskKind: WorkflowTaskKind;
    readonly status: DerivedTaskState["status"] | "not_reached";
    /** Milliseconds offset from execution start. */
    readonly startMs: number;
    /** Milliseconds offset from execution start. `null` when task is still running. */
    readonly endMs: number | null;
    /** Duration from event payload, or computed from start/end. */
    readonly durationMs: number;
    readonly costMicros: bigint;
    readonly tokensUsed: bigint;
    /** Individual retry attempt segments (first attempt is always present). */
    readonly attempts: readonly WaterfallAttempt[];
    /** Nested spans (agent calls, tool calls). Populated when events exist. */
    readonly children: readonly WaterfallSpan[];
    /** Approval wait duration in ms, for compound bar segment. `null` if no approval. */
    readonly approvalWaitMs: number | null;
}
/** One attempt within a retried task. */
export interface WaterfallAttempt {
    readonly attemptNumber: number;
    /** Milliseconds offset from execution start. */
    readonly startMs: number;
    /** `null` when the attempt is still running. */
    readonly endMs: number | null;
    readonly status: "completed" | "failed" | "running";
    /** Backoff delay in ms before this attempt (0 for the first attempt). */
    readonly backoffMs: number;
}
/** A nested span within a task bar (e.g., agent call). */
export interface WaterfallSpan {
    readonly label: string;
    /** Milliseconds offset from execution start. */
    readonly startMs: number;
    /** `null` when span is still active. */
    readonly endMs: number | null;
    readonly spanType: "agent_call" | "tool_call";
}
/** Time axis specification for the waterfall. */
export interface WaterfallScale {
    /** Total visible range in milliseconds. */
    readonly totalMs: number;
    /** Tick positions as ms offsets from execution start. */
    readonly ticks: readonly number[];
    /** Label interval — every Nth tick gets a label. */
    readonly labelEveryN: number;
}
/**
 * Derives positioned waterfall entries from an ordered event list.
 *
 * Walks the event list once (O(n)) to build entries with absolute
 * time positions relative to execution start. Handles retries as
 * stacked attempt segments and agent calls as nested child spans.
 *
 * @param events - Events ordered by sequence_number ascending.
 * @param executionStartIso - ISO 8601 timestamp of execution start
 *   (from `execution_started.occurred_at`). When empty/absent, falls
 *   back to the first event's `occurred_at`.
 */
export declare function deriveWaterfallEntries(events: readonly WorkflowExecutionEvent[], executionStartIso: string): readonly WaterfallEntry[];
/**
 * Computes a time axis scale for the waterfall.
 *
 * @param entries - Waterfall entries (used to find the max extent).
 * @param executionDurationMs - Total execution duration. When the execution
 *   is still running, pass `Date.now() - executionStartEpoch`.
 */
export declare function deriveWaterfallScale(entries: readonly WaterfallEntry[], executionDurationMs: number): WaterfallScale;
//# sourceMappingURL=derive-waterfall-entries.d.ts.map