sessionruntime

type ActiveRunUpdate func(snapshot Snapshot, now time.Time) (Snapshot, bool, error)

type Admission struct {
	RunID string
	// TurnID and TurnPosition are decided at admission so the eventual terminal
	// write targets a turn that already exists on paper.
	TurnID       string
	TurnPosition int64
	State        ledger.State
	// Replay is true when this invocation was already admitted. The rest of the
	// struct then describes the original run, whatever state it has reached.
	Replay bool
	// Started is true when this call took ownership and began execution. It is
	// false for a replay of a run someone else owns and for a replay of a
	// finished run.
	Started bool
	// Cursor is the position at which this run became observable. A caller that
	// both starts runs and subscribes to the session uses it to place the run in
	// the stream it is already reading, rather than guessing whether a snapshot
	// it holds predates its own submission (SR-OBS-002).
	//
	// It is set only when Started. A replay reserved nothing, so this call
	// produced no position; where the session stands now is a different fact,
	// and the subscription's snapshot is the authoritative answer to it.
	Cursor Cursor
	// Handle names the run this process now owns, including the fencing token
	// its durable writes must carry. It is meaningful only when Started.
	Handle RunHandle
}

type AdmitInput struct {
	BotID     string
	SessionID string
	// InvocationID is the caller's retry identity. Callers that cannot mint one
	// must derive it deterministically from their source (for example a channel
	// message id), because a fresh id per attempt turns a retry into a second
	// run.
	InvocationID string
	// Payload is the canonically encoded submission. Its fingerprint decides
	// whether a repeated invocation_id is the same submit or a conflict, so the
	// encoding must be stable for equal inputs — same key order, no timestamps,
	// no request ids.
	Payload []byte
	// Execution is the owner-side plumbing used only if this call wins the
	// claim. A replay that finds the run already owned never touches it.
	Execution Execution
}

type Backend interface {
	Now(ctx context.Context) (time.Time, error)
	// Load returns a snapshot the caller owns and may freely mutate.
	Load(ctx context.Context, key Key) (Snapshot, bool, error)
	Update(ctx context.Context, key Key, update SnapshotUpdate) (Snapshot, bool, error)
	Publish(ctx context.Context, event Event) error
	Subscribe(ctx context.Context, key Key) (Subscription, error)
	Close() error
}

type Command struct {
	Type         string `json:"type"`
	ID           string `json:"id,omitempty"`
	ReplyOwnerID string `json:"reply_owner_id,omitempty"`
	BotID        string `json:"bot_id"`
	SessionID    string `json:"session_id"`
	RunID        string `json:"run_id"`
	Generation   string `json:"generation"`
	FencingToken int64  `json:"fencing_token,omitempty"`
	TargetID     string `json:"target_id,omitempty"`
	// DecisionResolved means the command target was resolved from PostgreSQL
	// before routing. Owner-side execution must not consult the live UI
	// projection again: it is derived state and may lag the durable decision.
	DecisionResolved bool            `json:"decision_resolved,omitempty"`
	SteerID          string          `json:"steer_id,omitempty"`
	Text             string          `json:"text,omitempty"`
	Payload          json.RawMessage `json:"payload,omitempty"`
	PayloadHash      string          `json:"payload_hash,omitempty"`
	ErrorCode        string          `json:"error_code,omitempty"`
	Error            string          `json:"error,omitempty"`
	CreatedAt        time.Time       `json:"created_at"`
	ExpiresAt        time.Time       `json:"expires_at,omitempty"`
}

type CommandSubscription struct {
	C     <-chan Command
	Close func()
}

type CurrentRunPatch struct {
	RunID               string      `json:"run_id"`
	Status              *string     `json:"status,omitempty"`
	ErrorCode           *string     `json:"error_code,omitempty"`
	Error               *string     `json:"error,omitempty"`
	Steer               *SteerState `json:"steer,omitempty"`
	UpdatedAt           *time.Time  `json:"updated_at,omitempty"`
	OwnerLeaseExpiresAt *time.Time  `json:"owner_lease_expires_at,omitempty"`
}

type CurrentRunView struct {
	RunID string `json:"run_id" validate:"required" format:"uuid"`
	// TurnID is the durable turn this run writes into, allocated at admission.
	// It is part of the observable view because SR-OBS-003 requires every
	// subscriber to agree on the run's turn, and a subscriber that only learns
	// the run id cannot line the run up against persisted history.
	TurnID string `json:"turn_id" validate:"required" format:"uuid"`
	// InvocationID is the caller-supplied intent identity recorded at admission
	// (session_runs.invocation_id). It rides the live view so the client that
	// originated the send can match projection frames to its optimistic turn by
	// reading the frame, instead of inferring the pairing from arrival timing
	// while waiting for the acceptance that names the two. Subscribers that did
	// not originate the run see an id unknown to them and treat the turn as
	// foreign — which is the correct standalone rendering for cross-device runs.
	InvocationID        string               `json:"invocation_id,omitempty"`
	Generation          string               `json:"generation"`
	Status              string               `json:"status"`
	OwnerID             string               `json:"owner_id,omitempty"`
	OwnerLeaseExpiresAt *time.Time           `json:"owner_lease_expires_at,omitempty"`
	StartedAt           time.Time            `json:"started_at"`
	UpdatedAt           time.Time            `json:"updated_at"`
	Messages            []chatview.UIMessage `json:"messages"`
	RequestUserTurn     *chatview.UITurn     `json:"request_user_turn,omitempty"`
	ErrorCode           string               `json:"error_code,omitempty"`
	Error               string               `json:"error,omitempty"`
	Steer               *SteerState          `json:"steer,omitempty"`
	Operation           *RunOperationView    `json:"operation,omitempty"`
}

type Cursor struct {
	Epoch string `json:"epoch,omitempty"`
	Seq   int64  `json:"seq"`
}

type DecisionFenceActivator interface {
	ReclaimWaitingDecision(
		ctx context.Context,
		botID, sessionID, runID, ownerID, liveGeneration string,
		previousToken, newToken int64,
		decisionKind, decisionID string,
	) error
}

type DecisionResponse struct {
	ControlID  string
	Type       string
	DecisionID string
	BotID      string
	SessionID  string
	RunID      string
	Payload    json.RawMessage
}

type DecisionResponseResult struct {
	Handled bool
	Applied bool
}

type DecisionStore interface {
	ResolveRuntimeDecision(ctx context.Context, commandType, decisionID string) (DecisionTarget, error)
	PendingRuntimeDecision(ctx context.Context, runID string) (DecisionTarget, bool, error)
}

type DecisionTarget struct {
	Type         string
	ID           string
	BotID        string
	SessionID    string
	RunID        string
	TurnID       string
	Status       string
	FencingToken int64
	ControlID    string
	PayloadHash  string
}

type DistributedBackend interface {
	Backend
	UpdateActiveRun(ctx context.Context, key Key, runID, generation string, update ActiveRunUpdate) (Snapshot, bool, error)
	StartRun(ctx context.Context, key Key, ref RunRef, update SnapshotUpdate) (Snapshot, bool, error)
	ReleaseRun(ctx context.Context, key Key, ref RunRef, update ActiveRunUpdate) (Snapshot, bool, error)
	RenewLease(ctx context.Context, key Key, runID, ownerID, generation string, renewedAt, expiresAt time.Time) error
	ValidateRunOwnership(ctx context.Context, key Key, ref RunRef) error
	LoadRunRef(ctx context.Context, key Key, runID string) (RunRef, bool, error)
	DeleteRunRef(ctx context.Context, ref RunRef) (bool, error)
	PublishCommand(ctx context.Context, ownerID string, command Command) error
	SubscribeCommands(ctx context.Context, ownerID string) (CommandSubscription, error)
	StoreCommandResult(ctx context.Context, result Command, ttl time.Duration) error
	LoadCommandResult(ctx context.Context, commandID string) (Command, bool, error)
}

type Event struct {
	Type      string        `json:"type"`
	BotID     string        `json:"bot_id"`
	SessionID string        `json:"session_id"`
	Epoch     string        `json:"epoch,omitempty"`
	RunID     string        `json:"run_id,omitempty"`
	Seq       int64         `json:"seq"`
	UpdatedAt *time.Time    `json:"updated_at,omitempty"`
	Snapshot  *Snapshot     `json:"snapshot,omitempty"`
	Delta     *RuntimeDelta `json:"delta,omitempty"`
	Message   string        `json:"message,omitempty"`
}

type Execution struct {
	// Admission persists the run's user turn and any replacement operation, and
	// returns the view subscribers should see when the run leaves admitting. It
	// runs after ownership is established, so its writes can be fenced with
	// RunHandle.FencingToken.
	Admission func(ctx context.Context, handle RunHandle) (RunAdmissionView, error)
	// AbortCh and Cancel are how a routed abort reaches this run. A run without
	// them is durably abortable but cannot be interrupted mid-turn.
	AbortCh chan<- struct{}
	Cancel  context.CancelFunc
	// InjectCh receives steering messages; nil means this caller does not
	// support steering. The caller owns channel closure; the runtime only stops
	// sending during teardown.
	InjectCh chan<- turn.InjectMessage
	// OwnershipCancel revokes the caller's execution context when the lease is
	// lost, so a superseded owner stops producing output rather than racing the
	// fence it can no longer pass.
	OwnershipCancel context.CancelCauseFunc
}

type FenceActivator interface {
	Activate(ctx context.Context, botID, sessionID string, token int64) error
}

type HistoryResetBackend interface {
	AcquireHistoryReset(ctx context.Context, scope ResetScope, token string, ttl time.Duration) (ResetLease, bool, error)
	RenewHistoryReset(ctx context.Context, lease ResetLease, ttl time.Duration) (ResetLease, bool, error)
	ReleaseHistoryReset(ctx context.Context, lease ResetLease) (bool, error)
	EffectiveHistoryReset(ctx context.Context, scope ResetScope) (ResetLease, bool, error)
}

type HistoryResetHandler func(context.Context, ResetScope) error

type Key struct {
	BotID     string `json:"bot_id"`
	SessionID string `json:"session_id"`
}

type LeaseCandidate struct {
	Key          Key
	RunID        string
	FencingToken int64
	// ExpiresAt is the deadline recorded in the index, sampled on the backend's
	// clock rather than the reaper's.
	ExpiresAt time.Time
}

type LivenessBackend interface {
	// LivenessGeneration identifies this incarnation of the live backend. It is
	// created once and read by everyone, so a value different from the one
	// stamped on a run means the backend that claimed that run is gone and its
	// in-flight state cannot be recovered.
	LivenessGeneration(ctx context.Context) (string, error)

	// ExpiredLeaseCandidates returns up to limit entries whose lease deadline
	// has passed. The backend samples its own clock: a reaper with a skewed
	// clock must not be able to declare a healthy owner dead. Candidates are
	// returned, not claimed — the leader is single, so a visibility timeout
	// would add a second failure mode without removing one.
	ExpiredLeaseCandidates(ctx context.Context, limit int64) ([]LeaseCandidate, error)

	// ReleaseLeaseCandidate removes an index entry, but only while the entry
	// still carries the token the candidate was read with. A run reclaimed
	// between read and release keeps its new entry.
	ReleaseLeaseCandidate(ctx context.Context, candidate LeaseCandidate) (bool, error)

	// AcquireLeaderLease elects the single cluster-wide reaper. Renewal is the
	// same call: an existing holder re-acquires its own lease. Failover is safe
	// because every reaper duty is an idempotent fenced transition, so a new
	// leader repeating work the old one had started changes nothing.
	AcquireLeaderLease(ctx context.Context, ownerID string, ttl time.Duration) (bool, error)

	// ReleaseLeaderLease hands leadership back on graceful shutdown so a peer
	// takes over in one tick instead of one lease period.
	ReleaseLeaderLease(ctx context.Context, ownerID string) error
}

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

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

type Options struct {
	OwnerID       string
	StateTTL      time.Duration
	OwnerLeaseTTL time.Duration
	// BackendLossGrace comes from config because a Redis restart budget depends
	// on the deployment. Everything else below OwnerLeaseTTL is derived.
	BackendLossGrace time.Duration
	// Cluster mirrors session_runtime.cluster.
	Cluster bool
	// Ledger is the durable session run store.
	Ledger ledger.Store
	// Fence applies the persistence-ownership cutover for a claimed run. It is
	// required together with Ledger.
	Fence                  FenceActivator
	CommandAckTTL          time.Duration
	CommandWorkerLimit     int
	Logger                 *slog.Logger
	EpochGenerator         func() string
	RunGenerationGenerator func() string
	// ScanBatchSize and MaxScanBatchesPerTick exist so tests can watch recovery
	// page rather than to be tuned in production; both default to package
	// constants.
	ScanBatchSize         int32
	MaxScanBatchesPerTick int
}

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

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

type RedisOptions struct {
	URL       string
	KeyPrefix string
	StateTTL  time.Duration
}

type ResetLease struct {
	Scope     ResetScope `json:"scope"`
	Token     string     `json:"token"`
	ExpiresAt time.Time  `json:"expires_at"`
}

type ResetScope struct {
	BotID     string `json:"bot_id"`
	SessionID string `json:"session_id,omitempty"`
}

type RunAdmissionView struct {
	RequestUserTurn *chatview.UITurn
	Operation       *RunOperationView
}

type RunHandle struct {
	BotID      string
	SessionID  string
	RunID      string
	TurnID     string
	Generation string
	// FencingToken is the ledger ownership token for this run. Callers need it
	// to fence their own durable writes, which is why it travels with the
	// handle rather than staying inside the runtime. It is zero for runs
	// started through the pre-ledger entry points.
	FencingToken int64
}

type RunOperationView struct {
	Kind                 string           `json:"kind" validate:"required" enums:"retry,edit"`
	ReplaceFromMessageID string           `json:"replace_from_message_id" validate:"required"`
	ReplacementUserTurn  *chatview.UITurn `json:"replacement_user_turn,omitempty"`
}

type RunRef struct {
	BotID      string `json:"bot_id"`
	SessionID  string `json:"session_id"`
	RunID      string `json:"run_id"`
	OwnerID    string `json:"owner_id"`
	Generation string `json:"generation"`
	// FencingToken is the durable ownership token this reservation was made
	// with. It is stored with the ref so the lease index entry can be written
	// and removed from the backend's own copy, without a caller having to
	// reconstruct a token it may no longer hold. Zero means the run has no
	// ledger identity and therefore nothing for the reaper to transition.
	FencingToken int64 `json:"fencing_token,omitempty"`
}

type RuntimeDelta struct {
	CurrentRunView  *CurrentRunView         `json:"current_run_view,omitempty"`
	Run             *CurrentRunPatch        `json:"run,omitempty"`
	MessageAppends  []RuntimeMessageAppend  `json:"message_appends,omitempty"`
	ProgressAppends []RuntimeProgressAppend `json:"progress_appends,omitempty"`
	MessageUpserts  []chatview.UIMessage    `json:"message_upserts,omitempty"`
	ResetMessages   bool                    `json:"reset_messages,omitempty"`
}

type RuntimeMessageAppend struct {
	ID      int                    `json:"id"`
	Type    chatview.UIMessageType `json:"type"`
	Content string                 `json:"content"`
}

type RuntimeProgressAppend struct {
	ID       int `json:"id"`
	Progress any `json:"progress"`
	Input    any `json:"input,omitempty"`
}

type Snapshot struct {
	BotID          string          `json:"bot_id"`
	SessionID      string          `json:"session_id"`
	Epoch          string          `json:"epoch"`
	Seq            int64           `json:"seq"`
	CurrentRunView *CurrentRunView `json:"current_run_view,omitempty"`
	UpdatedAt      time.Time       `json:"updated_at"`
}

type SnapshotUpdate func(snapshot Snapshot, exists bool) (Snapshot, bool, error)

type SteerState struct {
	ID        string    `json:"id"`
	Status    string    `json:"status"`
	Text      string    `json:"text,omitempty"`
	Error     string    `json:"error,omitempty"`
	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
}

type Subscription struct {
	C     <-chan Event
	Close func()
}

type TerminalRun struct {
	RunID        string
	BotID        string
	SessionID    string
	FencingToken int64
	State        string
	ErrorCode    string
}