rollout

type Action string

type Decision struct {
	Action  Action       `json:"action"`
	Step    int          `json:"step"` // live step index, -1 = not started
	Next    int          `json:"next"` // step an advance proposes, else -1
	Reasons []string     `json:"reasons"`
	Gates   []GateResult `json:"gates"`
	// AwaitingApproval: everything but the approval gate passed.
	AwaitingApproval bool `json:"awaitingApproval,omitempty"`
	// Source is the evidence source of a breach: promote.SourceGateway,
	// promote.SourceCLI or "scorecard". Only gateway evidence may auto-kill.
	Source string `json:"source,omitempty"`
	// Frozen is the change freeze holding an advance or completion (ADR-0030);
	// rollback and pause are never held.
	Frozen string `json:"frozen,omitempty"`
	// Quorum is the approval quorum the advance needs, when a governance rule
	// covers it.
	Quorum *policy.QuorumResult `json:"quorum,omitempty"`
}

type DirStore string

type DocStore struct{ DB Docs }

type Docs interface {
	GetDoc(ctx context.Context, kind, name string) ([]byte, bool, error)
	PutDoc(ctx context.Context, kind, name string, body []byte) error
}

type Entry struct {
	Seq    int       `json:"seq"`
	At     time.Time `json:"at"`
	Event  string    `json:"event"`
	Index  int       `json:"index"` // step index for enter
	Step   string    `json:"step,omitempty"`
	Detail string    `json:"detail,omitempty"`
	Key    string    `json:"key,omitempty"`    // action entries: what was done
	Source string    `json:"source,omitempty"` // halt entries: evidence source of the breach
	Reason string    `json:"reason,omitempty"` // halt entries: why
	Prev   string    `json:"prev"`             // previous entry's Hash ("" for the first)
	Hash   string    `json:"hash"`             // sha256 over this entry with Hash empty
}

type Evidence struct {
	// Report is the backing experiment evaluated with the step's guardrails
	// and minSamples (see GateExperiment); nil = no metric evidence.
	Report *promote.Report `json:"report,omitempty"`
	// Scorecard is the step's eval scorecard; nil with ScorecardErr = unreadable.
	Scorecard    *eval.Scorecard `json:"-"`
	ScorecardErr string          `json:"scorecardError,omitempty"`
	// Approved: a human is advancing this step by hand (`halo rollout advance`).
	// It does not satisfy an approval quorum (Quorum).
	Approved bool `json:"approved,omitempty"`
	// Freeze is the change freeze covering the advance; nil = not frozen.
	Freeze *policy.FreezeStatus `json:"freeze,omitempty"`
	// Quorum is the approval quorum covering the advance (ADR-0030); nil = no
	// governance rule covers it. It replaces the approval gate.
	Quorum *policy.QuorumResult `json:"quorum,omitempty"`
}

type GateResult struct {
	Gate      string `json:"gate"` // bake | samples | guardrail:<metric> | scorecard | approval
	Status    string `json:"status"`
	Value     string `json:"value,omitempty"`
	Threshold string `json:"threshold,omitempty"`
	Detail    string `json:"detail,omitempty"`
}

type Governance struct {
	Incident  *policy.ActiveFreeze `json:"incident,omitempty"` // nil = none
	Approvals []policy.Approval    `json:"approvals,omitempty"`
	// Requester proposes the advance ("" = the controller): their own
	// approval never counts.
	Requester string `json:"-"`
}

type SimEvent struct {
	At       string       `json:"at"` // elapsed since start, e.g. "T+2d4h"
	Elapsed  int64        `json:"elapsedSeconds"`
	Step     string       `json:"step"`
	Action   Action       `json:"action"`
	Reasons  []string     `json:"reasons"`
	Gates    []GateResult `json:"gates"`
	Approved bool         `json:"approved,omitempty"`
}

type SimOptions struct {
	Scenario string        // default healthy
	Tick     time.Duration // default 1h
	Horizon  time.Duration // default 120d
	// UnitsPerHour is how many new users the experiment sees per hour at 100%; default 1000.
	UnitsPerHour int
	// BreachStep is the step index a regression starts at (default: the second
	// step with metric gates, else the first).
	BreachStep *int
	// ApproveAfter is how long a simulated human takes to approve; default 4h.
	ApproveAfter time.Duration
	Seed         uint64
	// Recorded, when set, replaces synthetic evidence: one entry per tick (the
	// last repeats). Scorecards still come from the policy dir.
	Recorded []Evidence
}

type SimResult struct {
	Rollout  string     `json:"rollout"`
	Scenario string     `json:"scenario"`
	Outcome  Action     `json:"outcome"` // complete | rollback | pause | hold (horizon reached)
	Duration string     `json:"duration"`
	Events   []SimEvent `json:"events"`
}

type State struct {
	Rollout   string    `json:"rollout"`
	Step      int       `json:"step"` // -1 = not started
	StepName  string    `json:"stepName,omitempty"`
	EnteredAt time.Time `json:"enteredAt"`
	// Halted is "rollback" or "pause" once the controller acted on a breach;
	// it holds the rollout until the policy leaves "active".
	Halted     string `json:"halted,omitempty"`
	HaltSource string `json:"haltSource,omitempty"`
	HaltReason string `json:"haltReason,omitempty"`
	// Done maps idempotency keys (see Key) to details such as PR URLs.
	Done    map[string]string `json:"done,omitempty"`
	Last    *Decision         `json:"last,omitempty"` // last decision: status views only
	LastAt  time.Time         `json:"lastAt"`
	History []Entry           `json:"history"`
}

type StateStore interface {
	Load(ctx context.Context, name string) (State, error)
	Save(ctx context.Context, s *State) error
}

type Timeline struct {
	Rollout    string         `json:"rollout"`
	Axis       string         `json:"axis"`
	Status     string         `json:"status"`
	Experiment string         `json:"experiment"`
	Change     string         `json:"change"`
	Steps      []TimelineStep `json:"steps"`
	// MinDuration is the sum of all bakes: the soonest completion.
	MinDuration string `json:"minDuration"`
}

type TimelineStep struct {
	Index      int      `json:"index"`
	Name       string   `json:"name"`
	Strategy   string   `json:"strategy"`
	Ring       string   `json:"ring"`
	Percent    float64  `json:"percent"`
	Exposure   string   `json:"exposure"`
	Bake       string   `json:"bake,omitempty"`
	MinSamples int      `json:"minSamples,omitempty"`
	Gates      []string `json:"gates"`
	OnFailure  string   `json:"onFailure"`
	// EarliestStart is the sum of earlier bakes: the soonest the step can be
	// live if every gate passes on time and every PR merges at once.
	EarliestStart string `json:"earliestStart"`
	Live          bool   `json:"live,omitempty"`
}