outboundsend

type DailyQuotaDeferredError struct {
	RetryAt time.Time
}

type DeliverOutcome struct {
	ProviderMessageID string
	SentAs            string
	Err               error
	// Permanent marks a non-retryable failure (validation / permanent 5xx): the
	// worker fails the message terminally instead of retrying.
	Permanent bool
	// Outage marks a provider-connection failure (relay unreachable/misconfigured):
	// the worker snoozes without burning an attempt (design §8), up to the retry
	// horizon. Mutually exclusive with Permanent in practice.
	Outage bool
	// AcceptanceUnknown marks a failure AFTER the whole body was handed to the
	// provider (the 250 never came): the provider may hold the message. Never
	// permanent; the next attempt is a new ordinal, and provider feedback
	// carrying the attempt header is the only authoritative answer.
	AcceptanceUnknown bool
	// SettlementErr reports that the provider ACCEPTED the message but the
	// local settlement did not commit. The send happened; the caller must not
	// resubmit.
	SettlementErr error
}

type Deliverer interface {
	Deliver(ctx context.Context, j *SendJob, auth sendingpolicy.ProviderAuthorization) DeliverOutcome
}

type HoldClass string

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

type Metrics interface {
	// OutboundQueueWait is the enqueue→worker-pickup latency of one send
	// attempt (River attempted_at − scheduled_at — due→pickup, never
	// cumulative message age).
	OutboundQueueWait(seconds float64)
	// OutboundTerminal records one terminal outcome for an outbound message.
	// outcome ∈ {sent, failed_suppressed, failed_provider,
	// failed_local_retries, failed_cancelled}.
	OutboundTerminal(outcome string)
	// OutboundTerminalLatency records eligibility→terminal latency for one
	// outbound message (the terminal write's occurred_at − submissionAnchor).
	// Observed at most once per message, co-located with OutboundTerminal so
	// the two share their exactly-once contract; a terminal whose occurred_at
	// precedes its anchor records the count with no latency sample.
	OutboundTerminalLatency(seconds float64)
	// OutboundAttempt records one submission attempt to the upstream relay.
	// outcome ∈ {success, temporary_failure, permanent_failure}.
	OutboundAttempt(outcome string, seconds float64)
	// OutboundRateDeferred records one submission deferred by the per-agent
	// fire-time rate gate — a snooze, not an attempt, and never terminal.
	OutboundRateDeferred()
}

type OperationResolver func(ctx context.Context, messageID string) (sendingpolicy.AcceptanceDecision, sendingpolicy.OperationRef, error)

type OutboundSendArgs struct {
	MessageID    string                      `json:"message_id"`
	OperationRef *sendingpolicy.OperationRef `json:"operation_ref,omitempty"`
}

type RateDecision = sendrate.Decision

type RateGate interface {
	Reserve(ctx context.Context, agentID string) (RateDecision, error)
	Window() time.Duration
}

type SendJob struct {
	MessageID string
	// UserID is the owning account — the tenant scope for the pre-provider
	// suppression guard (suppressions are per-account).
	UserID       string
	AgentID      string // exact sending agent for agent-scoped consent checks
	Domain       string // exact registered sender domain
	MessageType  string // send|reply|test; platform tests are ramp-exempt
	Status       string // messages.delivery_status
	EnvelopeFrom string
	Recipients   []string
	RawMessage   []byte // composed MIME
	SentAs       string // From identity decided at accept ("own_address"|"relay")
	// AcceptedAt is messages.created_at.
	AcceptedAt time.Time
	// ScheduledAt is messages.scheduled_at for a scheduled send (zero for an
	// immediate one).
	ScheduledAt time.Time
	// ReviewedAt is messages.reviewed_at — when a HITL hold was resolved into the
	// send pipeline, zero for a message that was never held.
	ReviewedAt time.Time
	// ProviderAccepted is set when authoritatively correlated provider-accept
	// evidence has been recorded for this message: the provider already has it,
	// so the worker settles the row as sent instead of re-submitting a duplicate.
	ProviderAccepted   bool
	ProviderAcceptedAt *time.Time
	// ProviderMessageID is the evidence-repaired provider id accompanying
	// ProviderAccepted (” when no evidence).
	ProviderMessageID string
	// LocalHoldClass / LocalHoldAnchor are the durable finite-hold pair a
	// previous execution persisted (empty/zero when never held). The deadline
	// is derived from them on every execution and never stored.
	LocalHoldClass  HoldClass
	LocalHoldAnchor time.Time
	// LastResumedAt is the owning account's last pause→active transition; a
	// first finite hold anchors no earlier than it, so a pause that preceded
	// the hold does not consume its horizon. Zero when unknown.
	LastResumedAt time.Time
	// TenantReadyAt is when the account's SES tenant became ready (zero until
	// it is). Drives the one-way tenant_setup → rate_ramp_or_provider move.
	TenantReadyAt time.Time
}

type SendWorker struct {
	river.WorkerDefaults[OutboundSendArgs]
	// contains filtered or unexported fields
}

type Store interface {
	// ClaimSend returns nil when the message is gone, trashed, terminal, or owned
	// by a different River job. It returns *DailyQuotaDeferredError (claim
	// released) when the account's daily send cap is exhausted at fire time.
	// (agent-delete cascade / TTL) — the worker treats a nil job as a no-op.
	ClaimSend(ctx context.Context, messageID string, jobID int64) (*SendJob, error)
	// ReleaseSend clears a side-effect-free attempt before River backoff.
	ReleaseSend(ctx context.Context, messageID string, jobID int64) error
	// RecordHold persists the message's finite-hold class and anchor. Terminal
	// writes clear the pair.
	RecordHold(ctx context.Context, messageID string, class HoldClass, anchor time.Time) error
	// MarkSent records the provider outcome monotonically from a pre-terminal
	// state, including when trash won after ClaimSend.
	MarkSent(ctx context.Context, messageID string, jobID int64, attempt int, occurredAt time.Time, providerMessageID, sentAs string) error
	// MarkFailed is the GUARDED terminal write (async-send-contract §3.1): if
	// provider-accept evidence has reached the row it settles the message as
	// sent (+ email.sent) instead; otherwise it sets delivery_status='failed'
	// with the given failure provenance + detail and emits email.failed — all
	// in one transaction. Callers therefore invoke it to "finalize a terminal
	// state", not to unconditionally fail.
	// The returned status reports what the guarded write actually did:
	// StatusFailed, StatusSent (evidence settle), or "" (no-op). The returned
	// time is the occurred_at the write actually used, and the returned
	// provider id is the evidence's provider message id on an evidence
	// settle (” otherwise), so the attempt that dialed can be settled with
	// it.
	MarkFailed(ctx context.Context, messageID string, jobID int64, attempt int, occurredAt time.Time, detail string, source delivery.FailureSource, reason messagelifecycle.ReasonCode, blockedRecipients []string) (delivery.Status, time.Time, string, error)
	PreserveTerminalFailure(ctx context.Context, messageID string, jobID int64, attempt int, occurredAt time.Time, detail string, source delivery.FailureSource, reason messagelifecycle.ReasonCode, blockedRecipients []string) error
	// DeferTerminalFailure records a final attempt's diagnostic + releases the
	// I/O claim WITHOUT declaring failed: the terminal reconciler declares the
	// outcome after the provider-evidence grace window (or settles the row as
	// sent when evidence arrives first).
	DeferTerminalFailure(ctx context.Context, messageID string, jobID int64, attempt int, occurredAt time.Time, detail string) error
	// RecordTemporaryFailure atomically records the retryable observation and
	// releases the send claim for River's next attempt.
	RecordTemporaryFailure(ctx context.Context, messageID string, jobID int64, attempt int, occurredAt time.Time, detail string) error
	// SuppressedRecipients returns the effective account-wide + exact-agent
	// subset — the last-line guard before provider I/O.
	SuppressedRecipients(ctx context.Context, userID, agentID string, recipients []string) ([]string, error)
}

type TerminalReconcileArgs struct{}

type TerminalReconcileWorker struct {
	river.WorkerDefaults[TerminalReconcileArgs]
	// contains filtered or unexported fields
}