riverworkflow

type Signal struct {
	// Attempt is the workflow attempt number from when this signal was emitted.
	Attempt int
	// CreatedAt is when the signal row was inserted.
	CreatedAt time.Time
	// ID is the unique identifier of the signal row.
	ID int64
	// Key identifies the signal stream within the workflow.
	Key string
	// Payload is the JSON payload associated with the signal.
	Payload json.RawMessage
	// Source is immutable JSON metadata describing the emitter for audit and
	// correlation.
	Source json.RawMessage
	// WorkflowID is the ID of the workflow that this signal belongs to.
	WorkflowID string
}

type SignalAttemptMismatchError struct {
	// RequestedAttempt is the attempt requested by the emitter.
	RequestedAttempt int
	// SignalAttempt is the attempt stamped on the inserted signal row.
	SignalAttempt int
	// WorkflowID is the ID of the workflow associated with the signal.
	WorkflowID string
}

type SignalKeyUndeclaredError struct {
	Key string

	TaskName   string
	WorkflowID string
}

type SignalPayloadMismatchError struct {
	// SignalID is the existing signal ID returned by the idempotent insert path.
	SignalID *int64
	// WorkflowID is the ID of the workflow associated with the signal.
	WorkflowID string
}

type SignalTaskDeclaresNoSignalKeysError struct {
	TaskName   string
	WorkflowID string
}

type SignalUnknownTaskError struct {
	TaskName   string
	WorkflowID string
}

type Timer struct {/* contains filtered or unexported fields */}

type TimerAnchor struct {
	// Kind identifies the source time used to resolve a relative timer.
	Kind TimerAnchorKind
	// TaskName is the dependency task name for task-finalized timers.
	TaskName string
}

type TimerAnchorKind string

const (
	// TimerAnchorKindTaskFinalizedAt anchors relative timers to a dependency
	// task's finalization time.
	TimerAnchorKindTaskFinalizedAt TimerAnchorKind = "task_finalized_at"

	// TimerAnchorKindWaitStartedAt anchors relative timers to wait start time.
	TimerAnchorKindWaitStartedAt TimerAnchorKind = "wait_started_at"

	// TimerAnchorKindWorkflowCreatedAt anchors relative timers to workflow
	// creation time.
	TimerAnchorKindWorkflowCreatedAt TimerAnchorKind = "workflow_created_at"
)

type Wait struct {
	// Evidence summarizes the bounded final evaluator evidence exposed for this
	// wait.
	Evidence *WaitEvidence
	// Expr is the effective CEL expression over terms and raw inputs.
	Expr string
	// Inputs contains the loaded input view for the wait.
	Inputs WaitInputState
	// Phase summarizes the wait lifecycle.
	Phase WaitPhase
	// ResolvedAt is when the wait became resolved, when known.
	ResolvedAt *time.Time
	// StartedAt is when the wait became active, when known.
	StartedAt *time.Time
	// Summary is the bounded human-facing explanation captured when the wait
	// resolved.
	Summary string
	// Terms contains authored terms in authored order with satisfied state when
	// known.
	Terms []WaitTermStatus
}

type WaitDepDiagnostic struct {
	Available   bool
	FinalizedAt *time.Time
	State       string
	TaskName    string
}

type WaitDepInput struct {
	// Result contains final evidence for this dependency when the wait has
	// resolved.
	Result *WaitDepInputResult
	// TaskName is the dependency task name.
	TaskName string
}

type WaitDepInputResult struct {
	// Available reports whether the dependency output was available at result
	// capture time.
	Available bool
	// FinalizedAt is when the dependency finalized, if known.
	FinalizedAt *time.Time
	// State is the dependency job state, when known.
	State string
}

type WaitDiagnostics struct {
	// EvalError describes a live CEL evaluation failure, when evaluation failed.
	EvalError error
	// ExprResult is the live top-level expression result when evaluation
	// succeeded.
	ExprResult *bool
	// Inputs contains live input diagnostics.
	Inputs WaitDiagnosticsInputs
	// InspectedAt is when diagnostics were gathered, in UTC.
	InspectedAt time.Time
	// Phase is the loaded wait phase.
	Phase WaitPhase
	// SignalScanCount is the number of signal rows loaded across all declared
	// signal keys before evaluation.
	SignalScanCount int
	// SignalScanLimit is the cap that was applied to the signal scan.
	SignalScanLimit int
	// Terms contains live term diagnostics in authored order.
	Terms []WaitTermDiagnostic
	// Truncated reports that more matching signal rows existed for the
	// current attempt than SignalScanLimit allowed, so the evaluator only
	// observed a capped prefix. A complete scan that loaded exactly
	// SignalScanLimit rows leaves Truncated false. When true, the
	// following fields are best-effort because they are derived from the
	// capped prefix rather than the full signal stream: ExprResult,
	// EvalError, per-term MatchedCount and Satisfied, and per-signal-input
	// IncludedCount and LastID. Re-run with a higher
	// [WorkflowWaitDiagnosticsOpts.SignalScanLimit] (up to its max)
	// for a more complete scan.
	Truncated bool
	// WorkflowAttempt is the workflow attempt used for diagnostics.
	WorkflowAttempt int
}

type WaitDiagnosticsInputs struct {
	Deps    []WaitDepDiagnostic
	Signals []WaitSignalDiagnostic
	Timers  []WaitTimerDiagnostic
}

type WaitEvidence struct {
	// EvaluatedAt is when the evaluator captured this evidence.
	EvaluatedAt time.Time
	// WorkflowAttempt is the workflow attempt used for the evaluation.
	WorkflowAttempt int
}

type WaitInputState struct {
	// Deps contains dependency task inputs referenced by the wait.
	Deps []WaitDepInput
	// Signals contains declared signal key inputs.
	Signals []WaitSignalInput
	// Timers contains declared timer inputs.
	Timers []WaitTimerInput
}

type WaitInputs struct {
	// Signals declares workflow signal keys available through `signals`.
	Signals []string
	// Timers declares timers available through `timers`.
	Timers []Timer
	// contains filtered or unexported fields
}

type WaitMetadataDecodeError struct {
	// Err is the underlying decode failure.
	Err error
	// Field is the metadata field that failed decoding.
	Field string
}

type WaitPhase int

const (
	// WaitPhaseNotStarted indicates a wait exists but has not
	// started evaluating yet.
	WaitPhaseNotStarted WaitPhase = iota

	// WaitPhaseWaiting indicates a wait is active but not yet resolved.
	WaitPhaseWaiting

	// WaitPhaseResolved indicates a wait is resolved.
	WaitPhaseResolved
)

type WaitSignalDiagnostic struct {
	IncludedCount int64
	Key           string
	LastID        *int64
}

type WaitSignalInput struct {
	// Key identifies the signal stream within the workflow.
	Key string
	// Result contains final evidence for this signal key when the wait has
	// resolved.
	Result *WaitSignalInputResult
}

type WaitSignalInputResult struct {
	// IncludedCount is the number of signal rows included by the final evidence
	// boundary for the key.
	IncludedCount int64
	// LastIncludedID is the maximum included signal ID for the key.
	LastIncludedID *int64
}

type WaitSpec struct {
	// Expr is the top-level CEL expression. It may be omitted for single-term
	// waits.
	Expr string
	// Inputs declares signal and timer inputs available to Expr and generic
	// terms.
	Inputs WaitInputs
	// Terms declares optional named predicates available as booleans to Expr.
	Terms []WaitTermSpec
}

type WaitTaskDeclaresNoWaitError struct {
	TaskName   string
	WorkflowID string
}

type WaitTermDiagnostic struct {
	LastMatchedID *int64
	MatchedCount  int64
	Name          string
	RequiredCount int64
	Satisfied     bool
}

type WaitTermKind string

const (
	// WaitTermKindGeneric identifies a generic CEL term over raw inputs.
	WaitTermKindGeneric WaitTermKind = "generic"

	// WaitTermKindSignal identifies a structured signal term.
	WaitTermKindSignal WaitTermKind = "signal"

	// WaitTermKindTimer identifies a structured timer term.
	WaitTermKindTimer WaitTermKind = "timer"
)

type WaitTermSpec struct {/* contains filtered or unexported fields */}

type WaitTermStatus struct {
	// Expr is the authored CEL expression for generic and signal terms. Timer
	// terms do not have an authored CEL expression.
	Expr string
	// Kind identifies the authored term kind.
	Kind WaitTermKind
	// Label is the authored label, when available.
	Label string
	// Name is the authored term name.
	Name string
	// RequiredCount is the authored minimum matched-signal count for
	// structured signal terms; zero for non-signal terms. It is populated
	// from the spec regardless of resolution state, so callers can surface
	// the required quorum on a still-pending wait.
	RequiredCount int64
	// Result contains final term evidence when the wait has resolved.
	Result *WaitTermStatusResult
	// SignalKey is the authored signal key for structured signal terms.
	SignalKey string
	// TimerName is the authored timer name for structured timer terms.
	TimerName string
}

type WaitTermStatusResult struct {
	// LastMatchedID is the maximum matched signal ID for structured signal
	// terms.
	LastMatchedID *int64
	// MatchedCount is the number of matched signal rows for structured signal
	// terms.
	MatchedCount int64
	// Satisfied reports whether the term evaluated true.
	Satisfied bool
}

type WaitTimerDiagnostic struct {
	FireAt *time.Time
	Fired  bool
	Name   string
}

type WaitTimerInput struct {
	// After is the declared relative duration for timers authored with `after`.
	After *time.Duration
	// Anchor describes how a relative timer is anchored.
	Anchor *TimerAnchor
	// FireAt is the effective absolute fire time when known. For authored
	// absolute timers this is the declared fire time. For relative timers it is
	// populated once the wait is active and the anchor has been resolved.
	FireAt *time.Time
	// Name is the timer name referenced by wait expressions.
	Name string
	// Result contains final evidence for this timer when the wait has resolved.
	Result *WaitTimerInputResult
}

type WaitTimerInputResult struct {
	// FireAt is the timer's effective fire time when known.
	FireAt *time.Time
	// Fired reports whether the timer had fired at result capture time.
	Fired bool
}

type WaitValidationError struct {
	// Err is the underlying validation failure.
	Err error
	// TaskName is the workflow task whose wait failed validation,
	// when available.
	TaskName string
	// WaitExpr is the top-level wait CEL expression being
	// validated, when available.
	WaitExpr string
	// WorkflowID is the ID of the workflow containing the failing task, when
	// available.
	WorkflowID string
}