protocol

import "github.com/danmestas/dagnats/protocol"

const (
    AnnotationSeverityError   = "error"
    AnnotationSeverityWarning = "warning"
    AnnotationSeverityNotice  = "notice"
)

const (
    // LogChunkBytesMax bounds a single LogChunk's Data payload. A
    // worker Write() larger than this is split into multiple chunks
    // (worker/log_writer.go) rather than growing one chunk unbounded.
    LogChunkBytesMax = 64 * 1024

    // LogStepBytesMax bounds the total bytes (both out and err
    // streams combined) captured for one step. Once hit, exactly one
    // LogMarkerTruncated chunk is emitted and further writes for that
    // step are dropped — bounded storage beats an unbounded log flood
    // from a runaway process.
    LogStepBytesMax = 64 * 1024 * 1024

    // LogReadChunksMax bounds a single non-follow GET /runs/{id}/logs
    // response.
    LogReadChunksMax = 1024

    // LogFollowDurationMax bounds a single SSE follow connection.
    LogFollowDurationMax = 1 * time.Hour

    // LogFollowConcurrentMax bounds concurrent SSE follow connections
    // per server process.
    LogFollowConcurrentMax = 256
)

const (
    LogStreamOut    = "out"
    LogStreamErr    = "err"
    LogStreamMarker = "marker"
)

const (
    // LogMarkerCompleted is emitted by Complete.
    LogMarkerCompleted = "completed"
    // LogMarkerFailed is emitted by Fail, FailPermanent, and
    // FailRetryAfter — all three represent this attempt ending in
    // failure, whether or not the engine will retry. BEFORE the
    // resolution publish, so a consumer following the lane sees the
    // marker before (or with) the terminal step.failed event and
    // GET .../logs?from=failure has a recorded position to resolve via
    // GetLastMsgForSubject rather than a scan.
    LogMarkerFailed = "failed"
    // LogMarkerContinued is emitted by Continue (agent-loop iteration
    // boundary) — this attempt's subject is done; the next iteration
    // gets a new attempt-scoped subject.
    LogMarkerContinued = "continued"
    // LogMarkerPaused is emitted by Pause — this attempt is done; a
    // resumed step (LoadCheckpoint) gets a new attempt-scoped subject.
    LogMarkerPaused = "paused"
    // LogMarkerFenced is emitted when a journal step's delivery is
    // fenced by a later claim (ADR-026): this attempt's subject is done
    // and its successor's is already open; nothing failed.
    LogMarkerFenced = "fenced"
    // LogMarkerTruncated is emitted at most once, the moment
    // LogStepBytesMax is reached, BEFORE the attempt-ending marker
    // (which still lands last) — no out/err chunk follows it, but the
    // terminal marker always does.
    LogMarkerTruncated = "truncated"
)

const AnnotationsMax = 1000

const CancelSubjectPrefix = "dagnats.cancel."

const LoopStateMaxBytesDefault = 256 << 10

func CancelSubject(runID string) string

type Annotation struct {
    Path     string `json:"path"`
    Line     int    `json:"line"`
    Column   int    `json:"column,omitempty"`
    Severity string `json:"severity"`
    Message  string `json:"message"`
}

type Annotations struct {
    Annotations []Annotation `json:"annotations"`
}

type ContinueWait struct {
    DelayMs int64      `json:"delay_ms,omitempty"`
    Until   *time.Time `json:"until,omitempty"`
    Input   bool       `json:"input,omitempty"`
}

func (w *ContinueWait) IsZero() bool

func (w *ContinueWait) WakeAt(now time.Time) (time.Time, bool)

type Event struct {
    Type          EventType       `json:"type"`
    RunID         string          `json:"run_id"`
    StepID        string          `json:"step_id,omitempty"`
    Timestamp     time.Time       `json:"timestamp"`
    Payload       json.RawMessage `json:"payload,omitempty"`
    TraceParent   string          `json:"trace_parent,omitempty"`
    TraceState    string          `json:"trace_state,omitempty"`
    WorkerID      string          `json:"worker_id,omitempty"`
    AttemptNumber int             `json:"attempt_number,omitempty"`
    // Iteration and DispatchNonce, with AttemptNumber, identify the
    // dispatch a step.continue, step.completed or step.failed answers
    // (#801). The engine accepts such an event only while the step is
    // Running on that iteration and attempt, with that nonce. Iteration
    // is a pointer because iteration 0 must be distinguishable from an
    // event an older worker sent without the field: an event without
    // Iteration carries no identity (see HasIdentity), and the engine
    // accepts it only while it is configured to accept legacy events.
    Iteration     *int   `json:"iteration,omitempty"`
    DispatchNonce string `json:"dispatch_nonce,omitempty"`
    // JournalSeq is the AGENT_JOURNAL sequence of the commit record a
    // journal step wrote before this step.continue, step.completed or
    // step.failed (ADR-026). Zero for a step without a journal.
    JournalSeq uint64 `json:"journal_seq,omitempty"`
    // InputRequestID is the submission a step.input.queued event
    // announces (ADR-027); it keys the event's msg-id so every
    // submission is its own event.
    InputRequestID string `json:"input_request_id,omitempty"`
}

func NewInputQueuedEvent(runID, stepID, requestID string) Event

func NewStepEvent(eventType EventType, runID string, stepID string, payload []byte) Event

func NewWorkflowEvent(eventType EventType, runID string, payload []byte) Event

func UnmarshalEvent(data []byte) (Event, error)

func (e Event) HasIdentity() bool

func (e Event) Marshal() ([]byte, error)

func (e Event) NATSMsgID() string

func (e Event) NATSSubject() string

func (e *Event) SetIdentity(iteration, attempt int, nonce string)

type EventType string

const (
    EventWorkflowStarted          EventType = "workflow.started"
    EventStepQueued               EventType = "step.queued"
    EventStepStarted              EventType = "step.started"
    EventStepCompleted            EventType = "step.completed"
    EventStepFailed               EventType = "step.failed"
    EventStepContinue             EventType = "step.continue"
    EventStepMapStarted           EventType = "step.map.started"
    EventStepMapCompleted         EventType = "step.map.completed"
    EventStepMapInstanceCompleted EventType = "step.map.instance.completed"
    EventStepSleepStarted         EventType = "step.sleep.started"
    EventStepSleepCompleted       EventType = "step.sleep.completed"
    EventStepWaitStarted          EventType = "step.wait.started"
    EventStepWaitMatched          EventType = "step.wait.matched"
    EventStepWaitTimeout          EventType = "step.wait.timeout"
    EventWorkflowCompleted        EventType = "workflow.completed"
    EventWorkflowFailed           EventType = "workflow.failed"
    EventWorkflowSpawn            EventType = "workflow.spawn"
    EventWorkflowChildCompleted   EventType = "workflow.child.completed"
    EventWorkflowChildFailed      EventType = "workflow.child.failed"
    EventWorkflowCancelled        EventType = "workflow.cancelled"
    EventStepCancelled            EventType = "step.cancelled"
    EventCompensateStarted        EventType = "compensate.started"
    EventCompensateStepCompleted  EventType = "compensate.step.completed"
    EventCompensateFailed         EventType = "compensate.failed"
    EventCompensateCompleted      EventType = "compensate.completed"
    EventApprovalRequested        EventType = "approval.requested"
    EventApprovalGranted          EventType = "approval.granted"
    EventApprovalRejected         EventType = "approval.rejected"
    EventApprovalExpired          EventType = "approval.expired"
    EventPlannerMaterialized      EventType = "planner.materialized"
    // EventStepInputQueued is published by the API when an input is
    // submitted to a step (ADR-027): it wakes a step waiting for input
    // and lets the engine settle inputs for a finished step. Its
    // msg-id carries the request id, so each submission is one event.
    EventStepInputQueued EventType = "step.input.queued"
    // EventStepWaitElapsed is published by the loop_wait timer when a
    // step's Delay or Until wait is over (ADR-027). It names the
    // dispatch it wakes, so a late fire cannot wake a later wait.
    EventStepWaitElapsed EventType = "step.wait.elapsed"
)

type FailureType string

const (
    FailureTypeRetriable    FailureType = "retriable"
    FailureTypeNonRetriable FailureType = "non_retriable"
    FailureTypeRetryAfter   FailureType = "retry_after"
)

type LogChunk struct {
    Seq       uint64    `json:"seq"`
    Attempt   int       `json:"attempt"`
    Iteration int       `json:"iteration"`
    TS        time.Time `json:"ts"`
    Stream    string    `json:"stream"`
    Data      []byte    `json:"data"`
}

type QueueGroup struct {
    TaskType     string `json:"task_type"`
    Pending      int64  `json:"pending"`
    OldestWaitMs *int64 `json:"oldest_wait_ms,omitempty"`
}

type QueueSnapshot struct {
    Groups     []QueueGroup `json:"groups"`
    SnapshotAt time.Time    `json:"snapshot_at"`
    Truncated  bool         `json:"truncated,omitempty"`
}

type RunEvent struct {
    Type        RunEventType      `json:"type"`
    RunID       string            `json:"run_id"`
    WorkflowID  string            `json:"workflow_id"`
    Status      string            `json:"status"`
    CreatedAt   time.Time         `json:"created_at"`
    CompletedAt *time.Time        `json:"completed_at,omitempty"`
    Labels      map[string]string `json:"labels,omitempty"`
    TraceParent string            `json:"trace_parent,omitempty"`
    // TriggerDepth is the source run's dag.WorkflowRun.TriggerDepth,
    // copied here at finalization time (#634) so a run_terminal
    // trigger consuming this event can compute the depth of the run
    // it is about to start (source depth + 1) WITHOUT a second lookup
    // of the source run. Additive: omitempty, older events decode to
    // 0 which is also the correct depth for every manual/HTTP/cron
    // -started run.
    TriggerDepth int `json:"trigger_depth,omitempty"`
}

type RunEventType string

const (
    RunEventCompleted RunEventType = "run.completed"
    RunEventFailed    RunEventType = "run.failed"
    RunEventCancelled RunEventType = "run.cancelled"
)

type StepContinuePayload struct {
    Output json.RawMessage `json:"output,omitempty"`
    State  []byte          `json:"state,omitempty"`
    // StateSet marks State as the state to commit even when it is
    // empty: a handler that checkpointed nil clears the saved state,
    // where an absent State (an event without it) leaves it alone.
    StateSet bool `json:"state_set,omitempty"`
    // Wait is the durable wait the handler asked for before the next
    // iteration (ADR-027): the engine schedules it and no worker holds
    // a claim meanwhile. Absent: the next iteration is sent at once
    // (after any loop_delay).
    Wait *ContinueWait `json:"wait,omitempty"`
}

type StepFailedPayload struct {
    Error        string      `json:"error"`
    FailureType  FailureType `json:"failure_type,omitempty"`
    RetryAfterMs int64       `json:"retry_after_ms,omitempty"`
}

type TaskPayload struct {
    TaskID    string          `json:"task_id"` // {runID}.{stepID}
    RunID     string          `json:"run_id"`
    StepID    string          `json:"step_id"`
    Iteration int             `json:"iteration,omitempty"`
    Attempt   int             `json:"attempt,omitempty"`
    Input     json.RawMessage `json:"input,omitempty"`
    // Metadata is static per-step config copied from StepDef.Metadata,
    // delivered to workers via TaskContext.Metadata(). Nil when the step
    // declared no metadata.
    Metadata map[string]string `json:"metadata,omitempty"`
    // RequiredCapabilities is copied verbatim from StepDef.RequiredCapabilities
    // at enqueue time. The worker reads it to gate capability handles (e.g.
    // the control plane). Nil = no capabilities declared (today's behavior).
    RequiredCapabilities []string `json:"required_capabilities,omitempty"`
    // DispatchNonce is the per-dispatch run-binding token (#380, ADR-021
    // Phase A). The engine stamps the same value on StepState.DispatchNonce
    // and here. The worker carries it on control-plane requests so the
    // server can verify the caller received this exact dispatch. Additive,
    // omitempty: legacy payloads deserialize to "" and the server rejects an
    // empty/mismatched nonce on the control-plane path.
    DispatchNonce string `json:"dispatch_nonce,omitempty"`
    // WorkflowName is the workflow definition's name (#503), stamped by the
    // engine at every publish site so SigNoz can filter/group task spans by
    // workflow instead of every run collapsing into one undifferentiated
    // span name. Additive, omitempty: legacy payloads deserialize to "" and
    // the worker simply omits the workflow_name span attribute in that case.
    WorkflowName string `json:"workflow_name,omitempty"`
    // TraceParent/TraceState carry the W3C trace context the HTTP bridge
    // stamps on each polled task (#534, #537) so a worker's execution
    // span parents onto bridge.dispatch instead of orphaning.
    //
    // The tags are the W3C wire names, deliberately UN-underscored —
    // unlike protocol.Event's persisted trace_parent/trace_state a few
    // types below. Renaming either to match the other silently drops the
    // field on decode: the poll path uses plain json.Decode with no
    // DisallowUnknownFields, so a mismatch is invisible at runtime.
    // Additive and omitempty: pre-#537 responses decode to "".
    //
    // Use observe.TraceContextFromTask to turn these into a parent
    // context rather than parsing them by hand.
    TraceParent string `json:"traceparent,omitempty"`
    TraceState  string `json:"tracestate,omitempty"`
    // State is the agent-loop state the step last committed through a
    // step.continue event (#801). The engine stores it in the run
    // snapshot alongside the iteration it belongs to and hands it to
    // every later dispatch of the step: the next iteration, a retry of
    // the current one, and a dispatch sent again after an engine crash.
    // Opaque bytes; TaskContext.LoadCheckpoint returns them. Additive:
    // legacy payloads deserialize to nil.
    State []byte `json:"state,omitempty"`
    // StateMaxBytes is the engine's cap on State, stamped on every
    // dispatch so a worker can refuse an oversized Continue before
    // publishing it, with the same number the engine would enforce.
    // Zero (a legacy payload) means LoopStateMaxBytesDefault.
    StateMaxBytes int `json:"state_max_bytes,omitempty"`
}

type TaskResolution struct {
    Action     string          `json:"action"`
    Output     json.RawMessage `json:"output,omitempty"`
    Error      string          `json:"error,omitempty"`
    Name       string          `json:"name,omitempty"`
    DurationMs int64           `json:"duration_ms,omitempty"`
    Checkpoint json.RawMessage `json:"checkpoint,omitempty"`
    Data       json.RawMessage `json:"data,omitempty"`
}

type WorkerStatusSnapshot struct {
    WorkerID              string `json:"worker_id"`
    CancelledTasksSkipped uint64 `json:"cancelled_tasks_skipped"`
}