package run

import "time"

// RecoveryObservation is the immutable authoritative runtime observation for one
// awaiting callback responder, sampled from the daemon/Hub Agent runtime overlay
// under a machine observation guard that prevents authoritative turn-state
// replacement while the guard is held.
//
// The RecoveryRunner resolves the responder's machine BEFORE acquiring the
// guard, then acquires the guard, samples the observation, and passes ONLY this
// immutable value into the row-locked RecoveryTick transaction. The store never
// re-reads runtime state and never invokes any Hub/machine-resolution callback
// inside the transaction: the guard held by the caller across the transaction
// commit is what proves the observation is current. A recovery caller that
// cannot acquire the guard (unknown/offline) never reaches the tick and causes
// zero transition/write.
type RecoveryObservation struct {
	// MachineID is the durable machine that owns the responder. It is resolved
	// before the guard is acquired, never while holding the guard.
	MachineID string
	// SessionGeneration is the current daemon connection/session generation at
	// the observation. It is empty when the machine is not connected or the
	// daemon does not report a session generation.
	SessionGeneration string
	// AgentSession is the current Agent session (from agentSessions) at the
	// observation. It is empty when the machine is not connected or the agent has
	// no session.
	AgentSession string
	// StateGeneration is the transport generation that produced the stored state
	// record. It is empty when no record is known.
	StateGeneration string
	// StateSession is the Agent session that produced the stored state record. It
	// is empty when no record is known or the state is generation-bound with no
	// per-Agent session.
	StateSession string
	// Connected reports whether the daemon was connected when the observation
	// was sampled.
	Connected bool
	// ConnectedAt is when the current connection established. It is the stable
	// grace anchor for the bounded snapshot window; ok=false-connected
	// observations carry a zero value.
	ConnectedAt time.Time
	// State is the real Agent turn-execution state (active/queued/idle) when
	// StateKnown is true; empty otherwise.
	State string
	// StateKnown reports whether the daemon reported a real per-agent turn
	// state for the responder at the observation.
	StateKnown bool
	// Revision is the per-agent turn-state revision at the observation (0 when
	// unknown or legacy).
	Revision int64
	// HighWater is the connection's turn-state high-water watermark at the
	// observation.
	HighWater int64
	// Working is the derived recovery judgment (true = real active/queued turn,
	// not recoverable). It is computed by the observation reader.
	Working bool
	// Known is the derived recovery judgment (true = the reader can determine
	// whether the responder is working or idle; false = unknown/offline/deferred).
	Known bool
	// Reason is a compact diagnostic reason for the judgment. It is best-effort
	// observability and never gates the recovery decision.
	Reason string
}