worker

type Claim struct {
	// ID is the run's stable identifier, also used as the workflow
	// engine's ExecutionID.
	ID string

	// Spec is the opaque payload supplied when the run was enqueued.
	Spec []byte

	// Attempt is the 1-based attempt counter. First claim sets
	// Attempt = 1; each subsequent reclaim increments it.
	Attempt int

	// WorkerID is the worker that holds the lease. Populated by
	// ClaimQueued and used for fencing subsequent writes.
	WorkerID string

	// OrgID is the organization that owns this run.
	OrgID string

	// ProjectID is the project that owns this run.
	ProjectID string

	// ParentRunID is the parent run that enqueued this one, or
	// empty for top-level runs.
	ParentRunID string

	// WorkflowType classifies the run.
	WorkflowType string

	// InitiatedBy identifies who or what triggered this run.
	InitiatedBy string

	// CreditCost is the credit cost for this run.
	CreditCost int

	// CallbackURL is the webhook URL to notify on terminal status.
	CallbackURL string

	// Metadata carries the arbitrary tag map supplied at enqueue.
	Metadata map[string]string
}

type Config struct {
	// QueueStore is the backing persistence. Required.
	QueueStore QueueStore

	// Handler executes claimed runs. Required.
	Handler Handler

	// Stores, if set, builds the pre-fenced Checkpointer /
	// StepProgressStore / ActivityLogger on HandlerContext before
	// each call to Handle. When nil, HandlerContext's store fields
	// are left nil and the Handler must do its own wiring (useful
	// for in-memory tests or engine-less handlers).
	Stores HandlerStores

	// SignalStore, if set, is propagated into HandlerContext so
	// workflows can send and receive signals. Shared across runs.
	SignalStore workflow.SignalStore

	// WorkerID identifies this worker process for lease fencing.
	// Must be stable across the worker's lifetime. Defaults to
	// "worker-<hostname>-<random>".
	WorkerID string

	// IDGenerator returns a unique identifier for outbox rows
	// (triggers, webhook deliveries). Defaults to a 16-hex-char
	// random string. Consumers with custom ID schemes can override.
	IDGenerator func() string

	// Concurrency caps the number of runs executed in parallel.
	// Defaults to DefaultConcurrency.
	Concurrency int

	// PollInterval is how often the claim loop wakes up when idle.
	// Defaults to DefaultPollInterval.
	PollInterval time.Duration

	// HeartbeatInterval is how often the worker refreshes its lease
	// on an active run. Defaults to DefaultHeartbeatInterval.
	HeartbeatInterval time.Duration

	// StaleAfter is the threshold after which a run with no recent
	// heartbeat is considered stale and eligible for reclaim or
	// dead-lettering. Must be strictly greater than HeartbeatInterval
	// to avoid spurious reclaims. Defaults to DefaultStaleAfter.
	StaleAfter time.Duration

	// ReaperInterval is how often the reaper scans for stale runs.
	// Defaults to DefaultReaperInterval.
	ReaperInterval time.Duration

	// MaxAttempts caps retries. Runs that exceed it are dead-lettered
	// to StatusFailed instead of being reclaimed. Defaults to
	// DefaultMaxAttempts.
	MaxAttempts int

	// RunTimeout is the wall-clock timeout applied to each Handler
	// invocation. Defaults to DefaultRunTimeout.
	RunTimeout time.Duration

	// EventStore, if set, receives lifecycle events for each run.
	EventStore EventStore

	// TriggerStore, if set, enables the outbox pattern for workflow
	// chaining. Triggers returned in Outcome are persisted here and
	// processed asynchronously.
	TriggerStore TriggerStore

	// CreditStore, if set, enables credit debit/refund tracking
	// per run.
	CreditStore CreditStore

	// WebhookStore, if set, enables durable webhook delivery for
	// runs with a CallbackURL.
	WebhookStore WebhookStore

	// WebhookDeliverer performs the actual HTTP delivery. Required
	// when WebhookStore is set; ignored otherwise.
	WebhookDeliverer WebhookDeliverer

	// TriggerInterval is how often the trigger processor polls for
	// pending triggers. Defaults to DefaultTriggerInterval.
	TriggerInterval time.Duration

	// WebhookInterval is how often the webhook processor polls for
	// pending deliveries. Defaults to DefaultWebhookInterval.
	WebhookInterval time.Duration

	// ReconcileInterval is how often the credit reconciler runs.
	// Defaults to DefaultReconcileInterval.
	ReconcileInterval time.Duration

	// TriggerMaxAttempts caps trigger processing retries.
	// Defaults to DefaultTriggerMaxAttempts.
	TriggerMaxAttempts int

	// WebhookMaxAttempts caps webhook delivery retries.
	// Defaults to DefaultWebhookMaxAttempts.
	WebhookMaxAttempts int

	// Logger is the structured logger. Defaults to a discard logger.
	Logger *slog.Logger

	// Clock returns the current time. Injected for tests; defaults
	// to time.Now.
	Clock func() time.Time
}

type CreditStore interface {
	// Debit records a credit charge for a run. Idempotent: calling
	// Debit twice for the same runID is a no-op.
	Debit(ctx context.Context, orgID, runID, workflowType string, amount int) error

	// Refund records a credit refund for a failed run. Idempotent:
	// calling Refund twice for the same runID is a no-op.
	Refund(ctx context.Context, orgID, runID, workflowType string, amount int) error

	// HasRefund reports whether a refund exists for the given run.
	HasRefund(ctx context.Context, orgID, runID string) (bool, error)

	// Balance returns the net credit balance for an org. Positive
	// means credits consumed; negative means net refunds.
	Balance(ctx context.Context, orgID string) (int, error)
}

type DeadLetteredRun struct {
	ID           string
	OrgID        string
	WorkflowType string
	CreditCost   int
}

type Event struct {
	// Seq is a store-assigned sequence number for cursor-based
	// pagination. Zero on input to AppendEvent; set by the store.
	Seq int64

	RunID     string
	EventType string // "running", "completed", "failed", "suspended", "review"
	Attempt   int
	WorkerID  string
	StepName  string
	Payload   map[string]any
	CreatedAt time.Time
}

type EventStore interface {
	// AppendEvent records an event. The store assigns Seq.
	AppendEvent(ctx context.Context, event *Event) error

	// ListEvents returns events for a run with Seq > afterSeq,
	// ordered by Seq ascending.
	ListEvents(ctx context.Context, runID string, afterSeq int64) ([]*Event, error)

	// CleanupEvents deletes events older than the given time.
	// Returns the number of events deleted.
	CleanupEvents(ctx context.Context, olderThan time.Time) (int, error)
}

type FailedRun struct {
	ID           string
	OrgID        string
	WorkflowType string
	CreditCost   int
}

type Handler interface {
	Handle(ctx context.Context, hc *HandlerContext) Outcome
}

type HandlerContext struct {
	// Claim is the run being executed.
	Claim *Claim

	// Checkpointer is a lease-fenced workflow.Checkpointer scoped
	// to this claim. Writes that fail the (WorkerID, Attempt) fence
	// return worker.ErrLeaseLost. This is the only store in the
	// bundle that enforces lease fencing.
	Checkpointer workflow.Checkpointer

	// ProgressStore is a workflow.StepProgressStore scoped to this
	// claim. Step progress writes are derived observability data
	// and are not fenced — the "latest update wins" semantics mean
	// a stale writer cannot corrupt durable state.
	ProgressStore workflow.StepProgressStore

	// ActivityLogger is a workflow.ActivityLogger scoped to this
	// claim. Activity log writes are append-only and not fenced.
	ActivityLogger workflow.ActivityLogger

	// SignalStore is a workflow.SignalStore for signal/wait
	// coordination. Shared across runs and claims; not fenced.
	SignalStore workflow.SignalStore
}

type HandlerFunc func(ctx context.Context, hc *HandlerContext) Outcome

type HandlerStores interface {
	// NewCheckpointer returns a lease-fenced checkpointer whose
	// writes must return worker.ErrLeaseLost when the claim's
	// (WorkerID, Attempt) pair no longer owns the run.
	NewCheckpointer(claim *Claim) workflow.Checkpointer

	// NewStepProgressStore returns a step progress store for the
	// claim. The claim is usually ignored; lease fencing is not
	// required because writes are idempotent replacements.
	NewStepProgressStore(claim *Claim) workflow.StepProgressStore

	// NewActivityLogger returns an activity logger for the claim.
	// The claim is usually ignored; activity logs are append-only.
	NewActivityLogger(claim *Claim) workflow.ActivityLogger
}

type NewRun struct {
	// ID uniquely identifies the run. Required. Must be unique
	// across the QueueStore.
	ID string

	// Spec is an opaque payload — typically JSON describing the
	// workflow definition and inputs — that the Handler consumes at
	// execution time.
	Spec []byte

	// OrgID identifies the organization owning this run. Empty
	// means the run is not scoped to an org (single-tenant).
	OrgID string

	// ProjectID identifies the project (workspace, team, board,
	// environment — whatever the consumer product calls it) that
	// owns this run. Empty means the run is not scoped to a project.
	ProjectID string

	// ParentRunID is the run that enqueued this one via the
	// trigger outbox. Empty for top-level runs.
	ParentRunID string

	// WorkflowType classifies the run (e.g., "research", "indexing").
	WorkflowType string

	// InitiatedBy identifies who or what triggered this run.
	InitiatedBy string

	// CreditCost is the credit cost for this run. Zero means no
	// credit tracking. Consumers typically default this to 1.
	CreditCost int

	// CallbackURL is an optional webhook URL notified on completion
	// or failure.
	CallbackURL string

	// Metadata is an arbitrary string map persisted alongside the
	// run. Typical use: correlation IDs, feature flags, tenant tags,
	// anything that does not earn a first-class column. Backed by
	// JSONB in the postgres store.
	Metadata map[string]string
}

type Outcome struct {
	// Status is the final status to persist. Must be one of
	// StatusCompleted, StatusFailed, StatusSuspended, StatusReview.
	Status Status

	// Result is an optional opaque blob persisted alongside the
	// status. Typical use: JSON outputs, SuspensionInfo, etc.
	Result []byte

	// ErrorMessage is the human-readable failure reason. Set when
	// Status == StatusFailed; ignored otherwise.
	ErrorMessage string

	// Triggers lists child runs to enqueue via the outbox pattern
	// after the run completes. Ignored if no TriggerStore is
	// configured on the Worker.
	Triggers []NewRun
}

type QueueStore interface {
	// Enqueue inserts a new run in StatusQueued with attempt = 0.
	// Returns an error if a run with the same ID already exists.
	Enqueue(ctx context.Context, run NewRun) error

	// ClaimQueued atomically claims the oldest available StatusQueued
	// run for the given worker, transitioning it to StatusRunning
	// and incrementing its attempt counter.
	//
	// Returns (nil, nil) when no queued runs are available.
	ClaimQueued(ctx context.Context, workerID string) (*Claim, error)

	// Heartbeat refreshes the lease on a claimed run. Must fence on
	// (claim.WorkerID, claim.Attempt) and status == StatusRunning.
	Heartbeat(ctx context.Context, claim *Claim) error

	// Complete writes the terminal or dormant status for a claimed
	// run. Must fence on (claim.WorkerID, claim.Attempt).
	Complete(ctx context.Context, claim *Claim, outcome Outcome) error

	// ReclaimStale transitions StatusRunning runs whose heartbeats
	// are older than staleBefore back to StatusQueued, for runs with
	// attempt < maxAttempts. Runs whose IDs appear in excludeIDs are
	// never transitioned.
	//
	// Returns the number of runs reclaimed.
	ReclaimStale(ctx context.Context, staleBefore time.Time, maxAttempts int, excludeIDs []string) (int, error)

	// DeadLetterStale transitions StatusRunning runs whose heartbeats
	// are older than staleBefore to StatusFailed, for runs with
	// attempt >= maxAttempts. Runs whose IDs appear in excludeIDs
	// are never transitioned.
	//
	// Returns metadata for each dead-lettered run. The worker uses
	// this to emit observability events and refund credits inline.
	DeadLetterStale(ctx context.Context, staleBefore time.Time, maxAttempts int, excludeIDs []string) ([]DeadLetteredRun, error)

	// ListRefundPending returns failed runs that were debited
	// but have not yet been refunded. Used by the credit reconcile
	// loop as a backstop for DeadLetterStale's inline refund.
	//
	// Implementations that do not track credits can return an empty
	// slice — the reconcile loop will do nothing.
	ListRefundPending(ctx context.Context, limit int) ([]FailedRun, error)
}

type Status string

type Trigger struct {
	ID           string
	ParentRunID  string
	ChildSpec    NewRun
	Status       TriggerStatus
	Attempts     int
	ErrorMessage string
	ChildRunID   string
	CreatedAt    time.Time
	ProcessedAt  time.Time
}

type TriggerStatus string

type TriggerStore interface {
	InsertTriggers(ctx context.Context, triggers []Trigger) error
	ListPendingTriggers(ctx context.Context, limit int) ([]Trigger, error)
	MarkTriggerProcessing(ctx context.Context, id string) error
	MarkTriggerCompleted(ctx context.Context, id string, childRunID string) error
	IncrementTriggerAttempts(ctx context.Context, id string, errMsg string) error
	MarkTriggerFailed(ctx context.Context, id string, errMsg string) error
}

type WebhookDeliverer interface {
	Deliver(ctx context.Context, url string, payload []byte) error
}

type WebhookDelivery struct {
	ID          string
	RunID       string
	URL         string
	EventType   string // "workflow.completed", "workflow.failed", etc.
	Payload     []byte
	Status      string // "pending", "delivered", "failed"
	Attempts    int
	LastError   string
	CreatedAt   time.Time
	DeliveredAt time.Time
}

type WebhookStore interface {
	EnqueueWebhook(ctx context.Context, delivery *WebhookDelivery) error
	ListPendingWebhooks(ctx context.Context, limit int) ([]*WebhookDelivery, error)
	// MarkWebhookProcessing claims a webhook for delivery using a
	// compare-and-swap on status. Returns an error if the webhook was
	// already claimed by another worker.
	MarkWebhookProcessing(ctx context.Context, id string) error
	MarkWebhookDelivered(ctx context.Context, id string) error
	IncrementWebhookAttempts(ctx context.Context, id string, lastError string) error
	MarkWebhookFailed(ctx context.Context, id string, errMsg string) error
}

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