reactive

type Action struct {
	// Type determines the action behavior.
	Type ActionType

	// PublishSubject for publish/publish_async actions.
	PublishSubject string

	// ExpectedResultType is the registered payload type name for async results.
	// Required for ActionPublishAsync so the engine can deserialize the callback.
	// Example: "workflow.planner-result.v1"
	ExpectedResultType string

	// BuildPayload constructs the typed payload from the rule context.
	// This replaces string interpolation entirely — it's a Go function that reads
	// typed fields from state and/or message and produces a typed payload.
	// Required for ActionPublish and ActionPublishAsync.
	BuildPayload PayloadBuilderFunc

	// MutateState updates the execution entity after the action completes.
	// For sync actions, called immediately with result=nil.
	// For async actions, called when the callback arrives with the typed result.
	// The mutated state is written back to KV, which may trigger other rules.
	MutateState StateMutatorFunc
}

type ActionType int

type CallbackFields struct {
	// TaskID uniquely identifies this async task.
	TaskID string `json:"task_id"`

	// CallbackSubject is where the executor should publish the result.
	CallbackSubject string `json:"callback_subject"`

	// ExecutionID is the workflow execution ID for direct lookup.
	ExecutionID string `json:"execution_id"`
}

type CallbackInjectable interface {
	InjectCallback(fields CallbackFields)
}

type Component struct {
	// contains filtered or unexported fields
}

type Condition struct {
	// Description is human-readable (for logging/debugging).
	Description string

	// Evaluate is the typed condition function.
	Evaluate ConditionFunc
}

type ConditionFunc func(ctx *RuleContext) bool

type ConditionResult struct {
	// Description is the condition's description.
	Description string

	// Passed indicates whether the condition evaluated to true.
	Passed bool
}

type Config struct {
	// Port configuration for inputs and outputs
	Ports *component.PortConfig `json:"ports,omitempty" schema:"type:ports,description:Port configuration for workflow inputs and outputs,category:basic"`

	// StateBucket is the KV bucket for workflow execution state
	StateBucket string `` /* 155-byte string literal not displayed */

	// CallbackStreamName is the JetStream stream for callback messages
	CallbackStreamName string `` /* 158-byte string literal not displayed */

	// EventStreamName is the JetStream stream for workflow events
	EventStreamName string `` /* 150-byte string literal not displayed */

	// DefaultTimeout is the default timeout for workflows without explicit timeout
	DefaultTimeout string `json:"default_timeout" schema:"type:string,description:Default timeout for workflows (e.g. 10m),default:10m,category:basic"`

	// DefaultMaxIterations is the default max iterations for loop workflows
	DefaultMaxIterations int `` /* 141-byte string literal not displayed */

	// CleanupRetention is how long to retain completed executions
	CleanupRetention string `` /* 142-byte string literal not displayed */

	// CleanupInterval is how often to run cleanup
	CleanupInterval string `` /* 134-byte string literal not displayed */

	// TaskTimeoutDefault is the default timeout for async tasks
	TaskTimeoutDefault string `json:"task_timeout_default" schema:"type:string,description:Default timeout for async tasks,default:5m,category:advanced"`

	// ConsumerNamePrefix is prepended to consumer names for uniqueness
	ConsumerNamePrefix string `json:"consumer_name_prefix,omitempty" schema:"type:string,description:Prefix for NATS consumer names,category:advanced"`

	// EnableMetrics enables Prometheus metrics
	EnableMetrics bool `json:"enable_metrics" schema:"type:bool,description:Enable Prometheus metrics,default:true,category:advanced"`
}

type ConsumerError struct {
	Stream   string
	Consumer string
	Op       string
	Cause    error
}

type Definition struct {
	// ID is the unique workflow identifier.
	ID string

	// Description is a human-readable description.
	Description string

	// StateBucket is the KV bucket for storing execution state.
	StateBucket string

	// StateFactory creates a zero-value instance of the workflow's concrete state type.
	// Must return a pointer to a struct that embeds ExecutionState.
	StateFactory func() any

	// MaxIterations limits loop iterations (0 = unlimited).
	MaxIterations int

	// Timeout is the maximum execution duration.
	Timeout time.Duration

	// Rules defines the reactive rules for this workflow.
	// Rules are evaluated in order; the first matching rule fires.
	Rules []RuleDef

	// Events defines typed event subjects for workflow lifecycle events.
	Events EventConfig
}

type DispatchError struct {
	Action  string
	Subject string
	Message string
	Cause   error
}

type DispatchResult struct {
	// TaskID is set for async actions to correlate callbacks.
	TaskID string

	// NewRevision is the KV revision after state mutation.
	NewRevision uint64

	// Published indicates if a message was published.
	Published bool

	// StateUpdated indicates if state was written to KV.
	StateUpdated bool

	// PartialFailure indicates the action partially succeeded but had errors.
	// For example, publish succeeded but state write failed.
	PartialFailure bool

	// PartialError contains the error message for partial failures.
	PartialError string
}

type Dispatcher struct {
	// contains filtered or unexported fields
}

type DispatcherOption func(*Dispatcher)

type Engine struct {
	// contains filtered or unexported fields
}

type EngineError struct {
	Op      string
	Message string
	Cause   error
}

type EngineMetrics struct {
	// contains filtered or unexported fields
}

type EngineOption func(*Engine)

type EvaluationResult struct {
	// RuleID is the ID of the rule that was evaluated.
	RuleID string

	// ShouldFire indicates whether the rule's conditions are met and it should fire.
	ShouldFire bool

	// Reason explains why the rule should or should not fire.
	Reason string

	// ConditionResults contains the result of each condition evaluation.
	ConditionResults []ConditionResult
}

type Evaluator struct {
	// contains filtered or unexported fields
}

type EventConfig struct {
	// OnComplete is the subject to publish when the workflow completes successfully.
	OnComplete string

	// OnFail is the subject to publish when the workflow fails.
	OnFail string

	// OnEscalate is the subject to publish when the workflow is escalated.
	OnEscalate string
}

type ExecutionState struct {
	// ID is the unique execution identifier (KV key).
	ID string `json:"id"`

	// WorkflowID references the workflow definition.
	WorkflowID string `json:"workflow_id"`

	// Phase is the current execution phase (typed enum per workflow).
	Phase string `json:"phase"`

	// Iteration tracks retry/loop count.
	Iteration int `json:"iteration"`

	// Status is the overall execution status.
	Status ExecutionStatus `json:"status"`

	// Error holds the last error message if any.
	Error string `json:"error,omitempty"`

	// PendingTaskID is set when waiting for an async callback.
	PendingTaskID string `json:"pending_task_id,omitempty"`

	// PendingRuleID identifies which rule is awaiting a callback.
	PendingRuleID string `json:"pending_rule_id,omitempty"`

	// Timestamps
	CreatedAt   time.Time  `json:"created_at"`
	UpdatedAt   time.Time  `json:"updated_at"`
	CompletedAt *time.Time `json:"completed_at,omitempty"`

	// Deadline is the absolute time when this execution times out.
	Deadline *time.Time `json:"deadline,omitempty"`

	// Timeline records rule firings for debugging.
	Timeline []TimelineEntry `json:"timeline,omitempty"`
}

type ExecutionStatus string

type KVOperation int

type KVWatchEvent struct {
	// Bucket is the KV bucket name.
	Bucket string

	// Key is the KV entry key.
	Key string

	// Value is the raw KV entry value (JSON).
	Value []byte

	// Revision is the KV entry revision.
	Revision uint64

	// Operation indicates the type of change.
	Operation KVOperation

	// Timestamp is when the event was received.
	Timestamp time.Time
}

type KVWatcher struct {
	// contains filtered or unexported fields
}

type MessageDeserializeError struct {
	Subject string
	Cause   error
}

type MetricsRecorder interface {
	RecordRuleEvaluation(workflowID, ruleID string, fired bool)
	RecordActionDispatch(workflowID, ruleID, actionType string)
	RecordExecutionCreated(workflowID string)
}

type PayloadBuilderFunc func(ctx *RuleContext) (message.Payload, error)

type Publisher interface {
	// Publish sends a message to a NATS subject.
	Publish(ctx context.Context, subject string, data []byte) error
}

type RegistryError struct {
	Op         string
	WorkflowID string
	Message    string
	Cause      error
}

type RuleBuilder struct {
	// contains filtered or unexported fields
}

type RuleContext struct {
	// State is the typed execution entity from KV.
	// Nil when trigger mode is TriggerMessageOnly.
	// Type assertion to concrete state type: ctx.State.(*PlanReviewState)
	State any

	// Message is the typed triggering message from NATS.
	// Nil when trigger mode is TriggerStateOnly.
	// Type assertion to concrete message type: ctx.Message.(*PlanReviewResult)
	Message any

	// KVRevision is the KV entry revision (for optimistic concurrency).
	// Zero when no KV state is involved.
	KVRevision uint64

	// Subject is the NATS subject the message arrived on (for subject-triggered rules).
	// Empty when trigger mode is TriggerStateOnly.
	Subject string

	// KVKey is the KV key that triggered the rule (for KV-triggered rules).
	// Empty when trigger mode is TriggerMessageOnly without state lookup.
	KVKey string
}

type RuleDef struct {
	// ID is the unique rule identifier within a workflow.
	ID string

	// Trigger defines what causes this rule to evaluate.
	Trigger TriggerSource

	// Conditions that must all be true for the rule to fire.
	// Evaluated against RuleContext which provides typed access to
	// both KV state and triggering message.
	Conditions []Condition

	// Logic determines how conditions are combined ("and" or "or").
	// Default is "and" (all conditions must be true).
	Logic string

	// Action to perform when conditions are met.
	Action Action

	// Cooldown prevents re-firing within this duration.
	Cooldown time.Duration

	// MaxFirings limits how many times this rule can fire per execution (0 = unlimited).
	MaxFirings int
}

type RuleWithWorkflow struct {
	Rule       *RuleDef
	Definition *Definition
}

type StateAccessor interface {
	GetExecutionState() *ExecutionState
}

type StateKeyError struct {
	Subject string
	Message string
}

type StateLoadError struct {
	Key   string
	Cause error
}

type StateMutatorFunc func(ctx *RuleContext, result any) error

type StateStore interface {
	// Get retrieves an entry by key.
	Get(ctx context.Context, key string) (jetstream.KeyValueEntry, error)

	// Put stores a value and returns the new revision.
	Put(ctx context.Context, key string, value []byte) (uint64, error)

	// Update performs a CAS update with explicit revision.
	// Returns ErrKVRevisionMismatch on conflict.
	Update(ctx context.Context, key string, value []byte, revision uint64) (uint64, error)
}

type SubjectConsumer struct {
	// contains filtered or unexported fields
}

type SubjectMessageEvent struct {
	// Subject is the NATS subject the message was received on.
	Subject string

	// Data is the raw message payload.
	Data []byte

	// Timestamp is when the message was received.
	Timestamp time.Time

	// StreamSequence is the sequence number in the stream.
	StreamSequence uint64

	// DeliveryCount is how many times this message has been delivered.
	DeliveryCount uint64
}

type SubjectMessageHandler func(ctx context.Context, event SubjectMessageEvent, msg jetstream.Msg)

type TimelineEntry struct {
	Timestamp   time.Time `json:"timestamp"`
	RuleID      string    `json:"rule_id"`
	TriggerMode string    `json:"trigger_mode"` // "kv", "message", "message+state"
	TriggerInfo string    `json:"trigger_info"` // KV key or NATS subject that triggered
	Action      string    `json:"action"`
	Phase       string    `json:"phase_after"`
	Iteration   int       `json:"iteration"`
}

type TriggerMode int

type TriggerSource struct {

	// WatchBucket is the KV bucket to watch for state changes.
	// When set without Subject, KV changes trigger rule evaluation.
	WatchBucket string `json:"watch_bucket,omitempty"`

	// WatchPattern is the key pattern within the bucket (supports NATS wildcards).
	WatchPattern string `json:"watch_pattern,omitempty"`

	// Subject is the NATS subject to consume messages from.
	// When set, message arrival triggers rule evaluation.
	// Supports NATS wildcards (e.g., "workflow.callback.plan-review.>").
	Subject string `json:"subject,omitempty"`

	// StreamName is the JetStream stream to consume from.
	// Required when Subject is set and durable consumption is needed.
	// When empty with Subject set, uses Core NATS subscription (ephemeral).
	StreamName string `json:"stream_name,omitempty"`

	// MessageFactory creates a zero-value instance of the expected message type
	// for typed deserialization. Required when Subject is set.
	MessageFactory func() any `json:"-"`

	// StateBucket is the KV bucket to load state from when a message triggers
	// the rule. This enables "event + state" patterns where the message arrival
	// is the trigger but conditions evaluate against both the message and the
	// accumulated KV state.
	//
	// When Subject is set AND StateBucket is set:
	//   - Message arrival triggers the rule
	//   - Engine loads state from StateBucket using StateKeyFunc
	//   - RuleContext contains both .Message and .State
	//
	// When only WatchBucket is set (no Subject):
	//   - KV change triggers the rule
	//   - RuleContext contains .State only (.Message is nil)
	//
	// When only Subject is set (no StateBucket or WatchBucket):
	//   - Message arrival triggers the rule
	//   - RuleContext contains .Message only (.State is nil)
	StateBucket string `json:"state_bucket,omitempty"`

	// StateKeyFunc extracts the KV key from the triggering message to load state.
	// Required when Subject + StateBucket are both set.
	// Example: func(msg any) string {
	//     return "plan-review." + msg.(*MyCallbackResult).TaskID
	// }
	StateKeyFunc func(msg any) string `json:"-"`
}

type UnmarshalError struct {
	Key   string
	Cause error
}

type ValidationError struct {
	Field   string
	Message string
}

type WatchError struct {
	Bucket  string
	Pattern string
	Cause   error
}

type WatchHandler func(ctx context.Context, event KVWatchEvent)

type WorkflowBuilder struct {
	// contains filtered or unexported fields
}

type WorkflowCompletionEvent struct {
	ExecutionID string    `json:"execution_id"`
	WorkflowID  string    `json:"workflow_id"`
	Status      string    `json:"status"`
	Phase       string    `json:"final_phase"`
	CompletedAt time.Time `json:"completed_at"`
}

type WorkflowEscalationEvent struct {
	ExecutionID string    `json:"execution_id"`
	WorkflowID  string    `json:"workflow_id"`
	Phase       string    `json:"phase"`
	Reason      string    `json:"reason"`
	EscalatedAt time.Time `json:"escalated_at"`
}

type WorkflowFailureEvent struct {
	ExecutionID string    `json:"execution_id"`
	WorkflowID  string    `json:"workflow_id"`
	Phase       string    `json:"phase"`
	Error       string    `json:"error"`
	FailedAt    time.Time `json:"failed_at"`
}

type WorkflowRegistry struct {
	// contains filtered or unexported fields
}