ledger

type AdmitParams struct {
	// ResumeRunID is checked inside the admission transaction, under the parent lock.
	ResumeRunID      string
	RunID            string
	BotID            string
	SessionID        string
	InvocationID     string
	TurnID           string
	Input            []byte
	InputFingerprint string
}

type ClaimParams struct {
	RunID string
	// OwnerID is empty for a single-instance memory backend, where there is
	// only ever one owner and no cross-process claim to arbitrate.
	OwnerID        string
	FencingToken   int64
	LiveGeneration string
}

type Cursor struct {
	LiveGeneration string
	RunID          string
}

type FinalizeParams struct {
	RunID        string
	FencingToken int64
	State        State
	ErrorCode    string
	// ExpectedState is optional. Shutdown uses it to avoid terminalizing a
	// decision that parked after its classification read.
	ExpectedState State
}

type OrphanQuery struct {
	MinAge time.Duration
	Limit  int32
}

type OrphanResetStore interface {
	FenceAndFinalizeOrphan(ctx context.Context, reset ResetLease, run Run) (Run, bool, error)
}

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

type PrepareFinishParams struct {
	RunID                string
	FencingToken         int64
	State                State
	ErrorCode            string
	AllowWaitingDecision bool
}

type ResetLease struct {
	Scope     string
	BotID     string
	SessionID string
	Token     string
	ExpiresAt time.Time
}

type ResetStore interface {
	AcquireReset(ctx context.Context, lease ResetLease, ttl time.Duration) (ResetLease, bool, error)
	RenewReset(ctx context.Context, lease ResetLease, ttl time.Duration) (ResetLease, bool, error)
	ReleaseReset(ctx context.Context, lease ResetLease) (bool, error)
	EffectiveReset(ctx context.Context, botID, sessionID string) (ResetLease, bool, error)
	ActiveRunsByBot(ctx context.Context, botID string) ([]Run, error)
	// SessionIDsByBot lists every session a bot-wide reset covers, so the
	// live projections of all of them can be invalidated with the history.
	SessionIDsByBot(ctx context.Context, botID string) ([]string, error)
}

type Run struct {
	RunID        string
	BotID        string
	SessionID    string
	InvocationID string
	// TurnID and TurnPosition are allocated at admission so that a terminal
	// write targets a pre-decided turn. Combined with the existing unique index
	// on (turn_id, turn_message_seq), that makes terminal replay idempotent
	// without any new machinery.
	TurnID       string
	TurnPosition int64

	State            State
	Input            []byte
	InputFingerprint string

	OwnerID      string
	FencingToken int64
	OwnerSince   time.Time
	// LiveGeneration is the live backend incarnation that claimed this run. It
	// is stamped once and never updated, which is what makes it a stable keyset
	// cursor for the fail-closed recovery sweep.
	LiveGeneration string

	AbortRequestedAt  time.Time
	ProposedState     State
	ProposedErrorCode string
	// ProposedErrorMessage and ErrorMessage are read from rows written before
	// the ledger stopped recording error text. Nothing writes them: a run's
	// failure is its code, and the cause belongs to the run's result record.
	ProposedErrorMessage string
	FinishProposedAt     time.Time
	ErrorCode            string
	ErrorMessage         string
	CreatedAt            time.Time
	UpdatedAt            time.Time
}

type StaleGenerationQuery struct {
	CurrentGeneration string
	After             Cursor
	Limit             int32
}

type State string

type Store interface {
	// Admit persists one admission. created is false when this invocation was
	// already admitted, in which case the original row is returned unchanged
	// and no turn position is consumed. Callers compare InputFingerprint to
	// decide between "same submit, same answer" and a conflict.
	//
	// It returns ErrSessionBusy when the session already has a different active
	// run. Nothing is persisted in that case, so the same invocation may be
	// submitted again later. An implementation is expected to reject busy
	// cheaply — contention is ordinary traffic here, not an exceptional event.
	Admit(ctx context.Context, params AdmitParams) (run Run, created bool, err error)

	Get(ctx context.Context, runID string) (Run, error)
	GetByInvocation(ctx context.Context, sessionID, invocationID string) (Run, error)
	// ActiveRun returns the session's single active run, or ErrRunNotFound.
	ActiveRun(ctx context.Context, sessionID string) (Run, error)
	// LatestRun backs the snapshot fallback when live state is gone: it answers
	// what PostgreSQL can prove about the most recent run and nothing more.
	LatestRun(ctx context.Context, sessionID string) (Run, error)

	// NextFencingToken draws from the monotonic sequence shared with the
	// PostgreSQL persistence fence, so one token orders both.
	NextFencingToken(ctx context.Context) (int64, error)

	Claim(ctx context.Context, params ClaimParams) (run Run, applied bool, err error)
	SetWaitingDecision(ctx context.Context, runID string, fencingToken int64) (run Run, applied bool, err error)
	Resume(ctx context.Context, runID string, fencingToken int64) (run Run, applied bool, err error)
	PrepareFinish(ctx context.Context, params PrepareFinishParams) (run Run, applied bool, err error)
	Finalize(ctx context.Context, params FinalizeParams) (run Run, applied bool, err error)

	// RequestAbort records the intent, which is not fenced: an abort may arrive
	// at any instance and the owner applies it.
	RequestAbort(ctx context.Context, runID string) (run Run, applied bool, err error)

	StaleGenerationRuns(ctx context.Context, query StaleGenerationQuery) ([]Run, error)
	OrphanedRuns(ctx context.Context, query OrphanQuery) ([]Run, error)
}