diff --git a/internal/app/archie/run.go b/internal/app/archie/run.go index 9b71869b0..d058cd70b 100644 --- a/internal/app/archie/run.go +++ b/internal/app/archie/run.go @@ -86,10 +86,10 @@ func Run(ctx context.Context, configPath string) error { engine := runs.New(db, log.With("module", "runs"), runs.Options{Owner: owner()}) // A workflow takes its context from the run handle, as a handler takes it // from the request. - judge, classes := newJudgement(db, log, conns) + judge, classes := newJudgement(db, log, conns, settings) // An approval request is carried by deliveries, and its answer wakes the run // that is waiting on it. - allow := approvals.NewModule(db, log.With("module", "approvals"), orgID, tell, engine) + allow := approvals.NewModule(db, log.With("module", "approvals"), orgID, tell, engine, classes, settings) allow.Routes(mux, guard) classes.Routes(mux, guard, allow) engine.Register("investigate", runs.Investigate(settings, conns, judge, allow, tell)) //nolint:contextcheck // see above @@ -121,11 +121,11 @@ func work(ctx context.Context, loops ...func(context.Context)) func() { } // newJudgement returns the judgement module and the action classes its -// precedent guard reads. -func newJudgement(db *sqlx.DB, log *slog.Logger, conns judgement.Tools) (*judgement.Module, *judgement.Classes) { +// precedent guard reads. A failed action tightens its class. +func newJudgement(db *sqlx.DB, log *slog.Logger, conns judgement.Tools, freezes judgement.Freezes) (*judgement.Module, *judgement.Classes) { classes := judgement.NewClasses(db, log.With("module", "judgement"), orgID) return judgement.NewModule(db, log.With("module", "judgement"), orgID, conns, nil, - []judgement.Guard{judgement.Reversibility{}, judgement.Precedent{Classes: classes}}), classes + []judgement.Guard{judgement.Reversibility{}, judgement.Precedent{Classes: classes}, judgement.Freeze{Freezes: freezes}}, classes), classes } // orgID is the one organisation until hosting is multi-tenant. diff --git a/internal/platform/pg/migrations/00021_judgement_autonomy.sql b/internal/platform/pg/migrations/00021_judgement_autonomy.sql new file mode 100644 index 000000000..f377543e0 --- /dev/null +++ b/internal/platform/pg/migrations/00021_judgement_autonomy.sql @@ -0,0 +1,52 @@ +-- +goose Up +-- A class earns autonomy from consecutive approvals. Each approval is kept as +-- evidence and stops counting when the class is tightened or raised. +ALTER TABLE judgement.classes ADD COLUMN tightened_at timestamptz; +ALTER TABLE judgement.classes ADD COLUMN tightened_because text; + +CREATE TABLE judgement.class_approvals ( + id uuid PRIMARY KEY, + org_id text NOT NULL, + class_id uuid NOT NULL REFERENCES judgement.classes (id), + decision_id uuid NOT NULL UNIQUE, + by text NOT NULL, + at timestamptz NOT NULL, + counted boolean NOT NULL DEFAULT true +); + +CREATE INDEX class_approvals_counted ON judgement.class_approvals (class_id, at) WHERE counted; + +-- A raise is Archie's proposal to loosen a class by one level. It is asked of a +-- person as an approval request, and keeps the approvals that earned it. +CREATE TABLE judgement.class_raises ( + id uuid PRIMARY KEY, + org_id text NOT NULL, + class_id uuid NOT NULL REFERENCES judgement.classes (id), + from_level text NOT NULL, + to_level text NOT NULL, + evidence jsonb NOT NULL, + state text NOT NULL CHECK (state IN ('pending', 'approved', 'denied', 'expired', 'superseded')), + deadline timestamptz NOT NULL, + proposed_at timestamptz NOT NULL, + answered_by text, + answered_at timestamptz +); + +CREATE UNIQUE INDEX class_raises_one_pending ON judgement.class_raises (class_id) WHERE state = 'pending'; +CREATE INDEX class_raises_by_class ON judgement.class_raises (class_id, proposed_at); + +-- An approval request is either for an action or for a raise; for a raise, +-- decision_id holds the raise's id and no run waits on it. +ALTER TABLE approvals.requests ADD COLUMN kind text NOT NULL DEFAULT 'action' CHECK (kind IN ('action', 'raise')); + +ALTER TABLE governance.settings ADD COLUMN raise_after integer NOT NULL DEFAULT 3 CHECK (raise_after >= 1); +ALTER TABLE governance.settings ADD COLUMN frozen boolean NOT NULL DEFAULT false; + +-- +goose Down +ALTER TABLE governance.settings DROP COLUMN frozen; +ALTER TABLE governance.settings DROP COLUMN raise_after; +ALTER TABLE approvals.requests DROP COLUMN kind; +DROP TABLE judgement.class_raises; +DROP TABLE judgement.class_approvals; +ALTER TABLE judgement.classes DROP COLUMN tightened_because; +ALTER TABLE judgement.classes DROP COLUMN tightened_at; diff --git a/modules/approvals/approvals.go b/modules/approvals/approvals.go index 201cd6120..9ffa8e9c8 100644 --- a/modules/approvals/approvals.go +++ b/modules/approvals/approvals.go @@ -47,9 +47,17 @@ var ( ErrExpired = errors.New("that request has expired") ) +// The kinds of request. A raise asks whether an action class may act with one +// level more autonomy; no run waits on it. +const ( + KindAction = "action" + KindRaise = "raise" +) + // Request is one judged action waiting for a person's answer. type Request struct { ID uuid.UUID + Kind string RunID uuid.UUID // Key is the run's wait key, stored so an answer knows what to wake. Key string @@ -86,6 +94,7 @@ func (a Answer) Approval(d judgement.Decision) judgement.Approval { // View is a request as the API shows it. type View struct { ID uuid.UUID `json:"id"` + Kind string `json:"kind"` RunID uuid.UUID `json:"run_id"` Action string `json:"action"` Target string `json:"target"` @@ -104,7 +113,7 @@ type View struct { // View is r as the API shows it. func (r Request) View() View { return View{ - ID: r.ID, RunID: r.RunID, Action: r.Connector + " " + r.Action, + ID: r.ID, Kind: r.Kind, RunID: r.RunID, Action: r.Connector + " " + r.Action, Target: r.TargetKind + ":" + r.TargetID, Level: r.Level, Summary: r.Summary, State: r.State, Deadline: r.Deadline, DecisionID: r.DecisionID, RequestedAt: r.RequestedAt, @@ -124,20 +133,39 @@ type Delivery interface { Notify(ctx context.Context, n deliveries.Notification) error } +// Classes is where answers become autonomy: an approval counts toward raising +// an action class, a denial tightens it, and a raise a person approves +// loosens it. +type Classes interface { + Approved(ctx context.Context, decisionID uuid.UUID, by string, need int, deadline time.Time) (*judgement.Raise, error) + Denied(ctx context.Context, decisionID uuid.UUID) error + AnswerRaise(ctx context.Context, id uuid.UUID, by string, approve bool) (bool, error) + CancelRaise(ctx context.Context, id uuid.UUID) error +} + +// Policy is what the organisation decided about approvals. +type Policy interface { + ApprovalDeadline(ctx context.Context) (time.Duration, error) + RaiseAfter(ctx context.Context) (int, error) +} + // Module owns one organisation's approval requests. type Module struct { - orgID string - store *store.Store - tell Delivery - wake Signaller - log *slog.Logger - now func() time.Time + orgID string + store *store.Store + tell Delivery + wake Signaller + classes Classes + policy Policy + log *slog.Logger + now func() time.Time } // NewModule returns the approvals module for orgID. Answers are delivered by -// tell and wake the run through wake. -func NewModule(db *sqlx.DB, log *slog.Logger, orgID string, tell Delivery, wake Signaller) *Module { - return &Module{orgID: orgID, store: store.New(db), tell: tell, wake: wake, log: log, now: time.Now} +// tell and wake the run through wake, and are counted into classes under +// policy. +func NewModule(db *sqlx.DB, log *slog.Logger, orgID string, tell Delivery, wake Signaller, classes Classes, policy Policy) *Module { + return &Module{orgID: orgID, store: store.New(db), tell: tell, wake: wake, classes: classes, policy: policy, log: log, now: time.Now} } // Ask records a request for d and tells people about it. Asking again for the @@ -146,7 +174,7 @@ func NewModule(db *sqlx.DB, log *slog.Logger, orgID string, tell Delivery, wake func (m *Module) Ask(ctx context.Context, runID uuid.UUID, key string, d judgement.Decision, deadline time.Time) (Request, error) { row, err := m.store.Put(ctx, store.Request{ ID: uuid.New(), OrgID: m.orgID, RunID: runID, Key: key, - DecisionID: d.ID, Digest: d.Action.Digest, Level: d.Level.String(), + DecisionID: d.ID, Kind: KindAction, Digest: d.Action.Digest, Level: d.Level.String(), Connector: d.Action.Connector, Action: d.Action.Name, TargetKind: d.Action.Target.Kind, TargetID: d.Action.Target.ID, Summary: Summary(d), State: StatePending, Deadline: deadline.UTC(), @@ -188,12 +216,98 @@ func (m *Module) Answer(ctx context.Context, id uuid.UUID, by, via string, appro return Request{}, fmt.Errorf("%w: %s", ErrAnswered, row.State) } answer := Answer{RequestID: row.ID, Approved: approved, By: by, Via: via, At: now} + if row.Kind == KindRaise { + if err := m.answerRaise(ctx, row, answer); err != nil { + return Request{}, err + } + return requestOf(row, judgement.Decision{}), nil + } if err := m.wakeWith(ctx, row, answer); err != nil { return Request{}, err } + // The run has what it waited for; the answer's bearing on the class comes + // after, so a failure here is reported without holding the run. + if err := m.learn(ctx, row, answer); err != nil { + return Request{}, err + } return requestOf(row, judgement.Decision{}), nil } +// learn counts an answer to an action into its class. An approval that +// completes a run of them earns a raise, which is put to a person. +func (m *Module) learn(ctx context.Context, row store.Request, a Answer) error { + if !a.Approved { + return m.classes.Denied(ctx, row.DecisionID) + } + need, err := m.policy.RaiseAfter(ctx) + if err != nil { + return fmt.Errorf("read raise count: %w", err) + } + wait, err := m.policy.ApprovalDeadline(ctx) + if err != nil { + return fmt.Errorf("read approval deadline: %w", err) + } + raise, err := m.classes.Approved(ctx, row.DecisionID, a.By, need, a.At.Add(wait)) + if err != nil || raise == nil { + return err + } + return m.askRaise(ctx, raise) +} + +// askRaise puts a raise to a person on every channel. If it can't be asked the +// raise is withdrawn, so the class proposes it again at its next approval. +func (m *Module) askRaise(ctx context.Context, r *judgement.Raise) error { + class := r.Class + row, err := m.store.Put(ctx, store.Request{ + ID: uuid.New(), OrgID: m.orgID, Key: "raise:" + r.ID.String(), + DecisionID: r.ID, Kind: KindRaise, Level: r.From.String(), + Connector: class.Connector, Action: class.Action, TargetKind: class.TargetKind, TargetID: class.Environment, + Summary: raiseSummary(r), State: StatePending, Deadline: r.Deadline, + }) + if err == nil { + err = m.tell.Ask(ctx, deliveries.ApprovalRequest{ + RequestID: row.ID, Key: row.Key + ":ask", + Title: "Raise autonomy: " + class.Connector + " " + class.Action, + Body: row.Summary, ExpiresAt: row.Deadline, + }) + } + if err != nil { + if cerr := m.classes.CancelRaise(ctx, r.ID); cerr != nil { + err = errors.Join(err, cerr) + } + return fmt.Errorf("ask to raise a class: %w", err) + } + return nil +} + +// answerRaise applies a person's answer to a raise. No run waits on it. +func (m *Module) answerRaise(ctx context.Context, row store.Request, a Answer) error { + raised, err := m.classes.AnswerRaise(ctx, row.DecisionID, a.By, a.Approved) + if err != nil { + return fmt.Errorf("answer raise: %w", err) + } + text := answerText(a) + if a.Approved && !raised { + text += " The class had changed since, so its level stays." + } + return m.tell.Told(ctx, deliveries.ApprovalRequest{ + RequestID: row.ID, Key: row.Key + ":ask", Title: "Raise answered", + }, text) +} + +// raiseSummary is what a person is shown about a raise: the class, the change +// and the approvals that earned it. +func raiseSummary(r *judgement.Raise) string { + c := r.Class + var s strings.Builder + fmt.Fprintf(&s, "%s: %s on %s in %s. Raise from %s to %s.\nEarned by %d approvals in a row:", + c.Connector, c.Action, c.TargetKind, c.Environment, r.From, r.To, len(r.Evidence)) + for _, e := range r.Evidence { + fmt.Fprintf(&s, "\n- %s, %s", e.By, e.At.UTC().Format("2006-01-02 15:04 UTC")) + } + return s.String() +} + // Settle answers a request from an answer a channel delivered as an event. An // answer that can't settle it, because it was already answered, has expired // or names no request, reports false rather than an error: retrying the event @@ -439,7 +553,7 @@ func inputLine(input jsontext.Value) string { // requestOf is a stored row as the module's Request. func requestOf(row store.Request, d judgement.Decision) Request { r := Request{ - ID: row.ID, RunID: row.RunID, Key: row.Key, Decision: d, DecisionID: row.DecisionID, RequestedAt: row.CreatedAt, + ID: row.ID, Kind: row.Kind, RunID: row.RunID, Key: row.Key, Decision: d, DecisionID: row.DecisionID, RequestedAt: row.CreatedAt, Connector: row.Connector, Action: row.Action, TargetKind: row.TargetKind, TargetID: row.TargetID, Level: row.Level, Summary: row.Summary, State: row.State, Deadline: row.Deadline, } diff --git a/modules/approvals/internal/store/store.go b/modules/approvals/internal/store/store.go index 4d053f241..528cbd633 100644 --- a/modules/approvals/internal/store/store.go +++ b/modules/approvals/internal/store/store.go @@ -15,11 +15,14 @@ import ( // Request is one judged action waiting for a person's answer. type Request struct { - ID uuid.UUID `db:"id"` - OrgID string `db:"org_id"` - RunID uuid.UUID `db:"run_id"` - Key string `db:"key"` + ID uuid.UUID `db:"id"` + OrgID string `db:"org_id"` + RunID uuid.UUID `db:"run_id"` + Key string `db:"key"` + // DecisionID is the judged action the request is about, or for a raise + // request the raise. DecisionID uuid.UUID `db:"decision_id"` + Kind string `db:"kind"` Digest string `db:"digest"` // The action's own names, kept so a request reads back without its // decision. @@ -45,7 +48,7 @@ type Store struct { // New returns a store on db. func New(db *sqlx.DB) *Store { return &Store{db: db} } -const requestColumns = `id, org_id, run_id, key, decision_id, digest, connector, action, target_kind, +const requestColumns = `id, org_id, run_id, key, decision_id, kind, digest, connector, action, target_kind, target_id, level, summary, state, deadline, created_at, answered_at, answered_by, answered_via` // Put records r unless a request already exists for its run and key, and @@ -53,12 +56,12 @@ const requestColumns = `id, org_id, run_id, key, decision_id, digest, connector, func (s *Store) Put(ctx context.Context, r Request) (Request, error) { var out Request err := s.db.GetContext(ctx, &out, ` - INSERT INTO approvals.requests (id, org_id, run_id, key, decision_id, digest, connector, action, + INSERT INTO approvals.requests (id, org_id, run_id, key, decision_id, kind, digest, connector, action, target_kind, target_id, level, summary, state, deadline) - VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14) + VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15) ON CONFLICT (org_id, run_id, key) DO NOTHING RETURNING `+requestColumns, - r.ID, r.OrgID, r.RunID, r.Key, r.DecisionID, r.Digest, r.Connector, r.Action, r.TargetKind, + r.ID, r.OrgID, r.RunID, r.Key, r.DecisionID, r.Kind, r.Digest, r.Connector, r.Action, r.TargetKind, r.TargetID, r.Level, r.Summary, r.State, r.Deadline) if errors.Is(err, sql.ErrNoRows) { return s.Get(ctx, r.OrgID, r.RunID, r.Key) diff --git a/modules/governance/governance.go b/modules/governance/governance.go index 7558dca25..a73227739 100644 --- a/modules/governance/governance.go +++ b/modules/governance/governance.go @@ -31,6 +31,13 @@ const roleAgent = "agent" // when the organisation hasn't said. const DefaultApprovalDeadline = 24 * time.Hour +// DefaultRaiseAfter is how many approvals in a row earn a proposal to raise an +// action class when the organisation hasn't said. +const DefaultRaiseAfter = 3 + +// maxRaiseAfter bounds the count: past it a class could never earn a raise. +const maxRaiseAfter = 100 + // The bounds on an approval deadline. Below a minute nobody could answer; past // a month the request outlives the incident it was raised for. const ( @@ -43,6 +50,12 @@ type Settings struct { // ApprovalDeadline is how long an approval request waits for an answer // before the run gives up on it. ApprovalDeadline time.Duration + // RaiseAfter is how many approvals in a row, since an action class was last + // tightened, earn a proposal to raise it one level. + RaiseAfter int + // Frozen holds every action that changes something at propose and wait, + // without changing any class's level. + Frozen bool } // settingsRequest is the settings as the API shows and sets them. A duration @@ -50,6 +63,12 @@ type Settings struct { // in the config takes. type settingsRequest struct { ApprovalDeadline string `json:"approval_deadline"` + RaiseAfter int `json:"raise_after"` + Frozen bool `json:"frozen"` +} + +func (s Settings) request() settingsRequest { + return settingsRequest{ApprovalDeadline: s.ApprovalDeadline.String(), RaiseAfter: s.RaiseAfter, Frozen: s.Frozen} } // Model is the model chosen for a role. @@ -110,9 +129,31 @@ func (m *Module) Settings(ctx context.Context) (Settings, error) { return Settings{}, err } if !ok { - return Settings{ApprovalDeadline: DefaultApprovalDeadline}, nil + return Settings{ApprovalDeadline: DefaultApprovalDeadline, RaiseAfter: DefaultRaiseAfter}, nil } - return Settings{ApprovalDeadline: time.Duration(row.ApprovalDeadlineMS) * time.Millisecond}, nil + return Settings{ + ApprovalDeadline: time.Duration(row.ApprovalDeadlineMS) * time.Millisecond, + RaiseAfter: row.RaiseAfter, Frozen: row.Frozen, + }, nil +} + +// RaiseAfter is how many approvals in a row earn a proposal to raise an action +// class. +func (m *Module) RaiseAfter(ctx context.Context) (int, error) { + set, err := m.Settings(ctx) + if err != nil { + return 0, err + } + return set.RaiseAfter, nil +} + +// Frozen reports whether the organisation has frozen its actions. +func (m *Module) Frozen(ctx context.Context) (bool, error) { + set, err := m.Settings(ctx) + if err != nil { + return false, err + } + return set.Frozen, nil } // ApprovalDeadline is how long an approval request waits for an answer. @@ -139,7 +180,7 @@ func (m *Module) getSettings(w http.ResponseWriter, r *http.Request) { httpjson.Error(w, http.StatusInternalServerError, "couldn't read the settings") return } - httpjson.Write(w, http.StatusOK, settingsRequest{ApprovalDeadline: set.ApprovalDeadline.String()}) + httpjson.Write(w, http.StatusOK, set.request()) } func (m *Module) putSettings(w http.ResponseWriter, r *http.Request) { @@ -153,26 +194,31 @@ func (m *Module) putSettings(w http.ResponseWriter, r *http.Request) { httpjson.Error(w, http.StatusBadRequest, "approval deadline is a duration, such as 24h") return } - set := Settings{ApprovalDeadline: deadline} + set := Settings{ApprovalDeadline: deadline, RaiseAfter: req.RaiseAfter, Frozen: req.Frozen} if err := set.validate(); err != nil { httpjson.Error(w, http.StatusBadRequest, err.Error()) return } if err := m.store.PutSettings(r.Context(), store.Settings{ OrgID: m.orgID, ApprovalDeadlineMS: set.ApprovalDeadline.Milliseconds(), + RaiseAfter: set.RaiseAfter, Frozen: set.Frozen, }); err != nil { m.log.ErrorContext(r.Context(), "put settings", "error", err) httpjson.Error(w, http.StatusInternalServerError, "couldn't save the settings") return } - httpjson.Write(w, http.StatusOK, settingsRequest{ApprovalDeadline: set.ApprovalDeadline.String()}) + httpjson.Write(w, http.StatusOK, set.request()) } -// validate keeps a deadline inside the range an answer can be given in. +// validate keeps a deadline inside the range an answer can be given in, and +// the count of approvals a raise needs inside the range a class can earn. func (s Settings) validate() error { if s.ApprovalDeadline < minApprovalDeadline || s.ApprovalDeadline > maxApprovalDeadline { return fmt.Errorf("approval deadline must be between %s and %s", minApprovalDeadline, maxApprovalDeadline) } + if s.RaiseAfter < 1 || s.RaiseAfter > maxRaiseAfter { + return fmt.Errorf("raise after must be between 1 and %d approvals", maxRaiseAfter) + } return nil } diff --git a/modules/governance/internal/store/store.go b/modules/governance/internal/store/store.go index f7a1df6ab..4f37fb381 100644 --- a/modules/governance/internal/store/store.go +++ b/modules/governance/internal/store/store.go @@ -62,6 +62,11 @@ type Settings struct { OrgID string `db:"org_id"` // ApprovalDeadlineMS is how long an approval request waits for an answer. ApprovalDeadlineMS int64 `db:"approval_deadline_ms"` + // RaiseAfter is how many approvals in a row earn a proposal to raise an + // action class. + RaiseAfter int `db:"raise_after"` + // Frozen holds every action that changes something at propose and wait. + Frozen bool `db:"frozen"` } // Settings returns the organisation's settings; ok is false when none were @@ -69,7 +74,7 @@ type Settings struct { func (s *Store) Settings(ctx context.Context, orgID string) (Settings, bool, error) { var out Settings err := s.db.GetContext(ctx, &out, ` - SELECT org_id, approval_deadline_ms FROM governance.settings WHERE org_id = $1`, orgID) + SELECT org_id, approval_deadline_ms, raise_after, frozen FROM governance.settings WHERE org_id = $1`, orgID) if errors.Is(err, sql.ErrNoRows) { return Settings{}, false, nil } @@ -82,10 +87,11 @@ func (s *Store) Settings(ctx context.Context, orgID string) (Settings, bool, err // PutSettings records the organisation's settings. func (s *Store) PutSettings(ctx context.Context, set Settings) error { if _, err := s.db.NamedExecContext(ctx, ` - INSERT INTO governance.settings (org_id, approval_deadline_ms) - VALUES (:org_id, :approval_deadline_ms) + INSERT INTO governance.settings (org_id, approval_deadline_ms, raise_after, frozen) + VALUES (:org_id, :approval_deadline_ms, :raise_after, :frozen) ON CONFLICT (org_id) DO UPDATE - SET approval_deadline_ms = EXCLUDED.approval_deadline_ms, updated_at = now()`, set); err != nil { + SET approval_deadline_ms = EXCLUDED.approval_deadline_ms, raise_after = EXCLUDED.raise_after, + frozen = EXCLUDED.frozen, updated_at = now()`, set); err != nil { return fmt.Errorf("put settings: %w", err) } return nil diff --git a/modules/judgement/autonomy.go b/modules/judgement/autonomy.go new file mode 100644 index 000000000..ffde1ef23 --- /dev/null +++ b/modules/judgement/autonomy.go @@ -0,0 +1,295 @@ +package judgement + +import ( + "context" + json "encoding/json/v2" + "errors" + "fmt" + "time" + + "github.com/google/uuid" + + "github.com/samcharles93/archie-core/modules/judgement/internal/store" +) + +// event is something that happened to an action class that bears on how much +// autonomy it has. +type event int + +const ( + // approved: a person allowed one of the class's held actions. + approved event = iota + 1 + // denied: a person refused one of the class's held actions. + denied + // failed: an action of the class failed, or its outcome is unknown. + failed + // raiseApproved: a person approved the proposal to loosen the class. + raiseApproved + // raiseRefused: a person refused the proposal to loosen the class. + raiseRefused +) + +// standing is what a class has earned: its level, the approvals counted since +// it was last tightened or raised, and the level a raise waiting for an +// answer would take it to (zero when none waits). +type standing struct { + level Level + count int + raiseTo Level +} + +// after returns the standing the event leaves, and whether it earns a new +// proposal to raise the class by one level once need approvals in a row have +// counted. Autonomy is lost at once and earned only through a person: a +// denial or failure never loosens a class, and approvals never loosen it +// themselves. +func (s standing) after(e event, need int) (next standing, propose bool) { + next = s + switch e { + case approved: + next.count++ + if s.raiseTo == 0 && next.count >= need && s.level > ActQuietly && s.level < Never { + next.raiseTo = s.level - 1 + propose = true + } + case denied, failed: + next.level, next.count, next.raiseTo = max(s.level, ProposeAndWait), 0, 0 + case raiseApproved: + // A raise answers the level it was proposed from. A class that moved + // since stays where it is. + if s.raiseTo != 0 && s.level == s.raiseTo+1 { + next.level, next.count = s.raiseTo, 0 + } + next.raiseTo = 0 + case raiseRefused: + next.count, next.raiseTo = 0, 0 + } + return next, propose +} + +// freezeCeiling is the ceiling a freeze sets: a frozen organisation holds +// every action that changes something at propose and wait, and leaves reading +// alone. The class levels aren't touched, so lifting the freeze restores them. +func freezeCeiling(frozen, readOnly bool) Level { + if frozen && !readOnly { + return ProposeAndWait + } + return ActQuietly +} + +// Raise is Archie's proposal to loosen a class by one level, with the +// approvals that earned it. +type Raise struct { + ID uuid.UUID + Class Class + From, To Level + Evidence []RaiseEvidence + Deadline time.Time +} + +// RaiseEvidence is one approval counted toward a raise. +type RaiseEvidence struct { + DecisionID uuid.UUID `json:"decision_id"` + By string `json:"by"` + At time.Time `json:"at"` +} + +// Approved counts a person's approval of the held action decisionID, and +// returns the raise it earns, if it does: need approvals in a row since the +// class was last tightened. The raise waits until deadline for an answer. +func (c *Classes) Approved(ctx context.Context, decisionID uuid.UUID, by string, need int, deadline time.Time) (*Raise, error) { + row, err := c.store.ClassOfDecision(ctx, c.orgID, decisionID) + if errors.Is(err, store.ErrNoClass) { + return nil, nil + } + if err != nil { + return nil, err + } + var out *Raise + err = c.store.InClass(ctx, c.orgID, row.ID, c.now().UTC(), func(t *store.ClassTx) error { + if err := t.AddApproval(ctx, decisionID, by); err != nil { + return err + } + out, err = c.apply(ctx, t, approved, need, deadline, "") + return err + }) + return out, err +} + +// Denied tightens the class of the held action decisionID that a person +// refused. +func (c *Classes) Denied(ctx context.Context, decisionID uuid.UUID) error { + row, err := c.store.ClassOfDecision(ctx, c.orgID, decisionID) + if errors.Is(err, store.ErrNoClass) { + return nil + } + if err != nil { + return err + } + return c.tighten(ctx, row.ID, "denied") +} + +// Failed tightens the class of an action that failed or whose outcome is +// unknown. +func (c *Classes) Failed(ctx context.Context, class Class) error { + row, err := c.store.ClassByKey(ctx, store.Class{ + OrgID: c.orgID, Connector: class.Connector, Action: class.Action, + TargetKind: class.TargetKind, Environment: class.Environment, + }) + if errors.Is(err, store.ErrNoClass) { + return nil + } + if err != nil { + return err + } + return c.tighten(ctx, row.ID, "failed") +} + +func (c *Classes) tighten(ctx context.Context, id uuid.UUID, because string) error { + return c.store.InClass(ctx, c.orgID, id, c.now().UTC(), func(t *store.ClassTx) error { + _, err := c.apply(ctx, t, denied, 0, time.Time{}, because) + return err + }) +} + +// AnswerRaise settles raise id with a person's answer, and raises the class +// when it was approved and the class still stands where the proposal was made +// from. It reports whether the class was raised. An answer to a raise that is +// no longer waiting changes nothing. +func (c *Classes) AnswerRaise(ctx context.Context, id uuid.UUID, answeredBy string, approve bool) (bool, error) { + raise, err := c.store.RaiseByID(ctx, c.orgID, id) + if err != nil { + return false, err + } + var raised bool + err = c.store.InClass(ctx, c.orgID, raise.ClassID, c.now().UTC(), func(t *store.ClassTx) error { + _, pending, err := t.Count(ctx) + if err != nil || pending == nil || pending.ID != id { + return err + } + e := raiseRefused + if approve { + e = raiseApproved + } + before := t.Class.Level + if _, err := c.apply(ctx, t, e, 0, time.Time{}, answeredBy); err != nil { + return err + } + raised = approve && before == pending.FromLevel + return nil + }) + return raised, err +} + +// CancelRaise withdraws a raise whose request couldn't be asked, so the class +// proposes it again at its next approval. +func (c *Classes) CancelRaise(ctx context.Context, id uuid.UUID) error { + return c.store.CancelRaise(ctx, c.orgID, id) +} + +// apply moves the locked class through e and stores what changed. by is who +// answered a raise, or why the class was tightened. +func (c *Classes) apply(ctx context.Context, t *store.ClassTx, e event, need int, deadline time.Time, by string) (*Raise, error) { + cur, pending, err := standingOf(ctx, t) + if err != nil { + return nil, err + } + next, propose := cur.after(e, need) + if err := write(ctx, t, e, cur, next, pending, by); err != nil { + return nil, err + } + if !propose { + return nil, nil + } + return c.propose(ctx, t, cur.level, next.raiseTo, deadline) +} + +// standingOf reads the locked class's standing, and the raise waiting for an +// answer if one is. +func standingOf(ctx context.Context, t *store.ClassTx) (standing, *store.Raise, error) { + level, err := parseLevel(t.Class.Level) + if err != nil { + return standing{}, nil, err + } + count, pending, err := t.Count(ctx) + if err != nil { + return standing{}, nil, err + } + s := standing{level: level, count: count} + if pending != nil { + if s.raiseTo, err = parseLevel(pending.ToLevel); err != nil { + return standing{}, nil, err + } + } + return s, pending, nil +} + +// write stores the difference between two standings. +func write(ctx context.Context, t *store.ClassTx, e event, cur, next standing, pending *store.Raise, by string) error { + switch { + case e == denied || e == failed: + if err := t.Tighten(ctx, next.level.String(), by); err != nil { + return err + } + case next.level != cur.level: + if err := t.SetLevel(ctx, next.level.String()); err != nil { + return err + } + } + if next.count == 0 && cur.count > 0 { + if err := t.ClearCount(ctx); err != nil { + return err + } + } + if pending != nil && next.raiseTo == 0 { + return t.CloseRaise(ctx, closedRaiseState(e, next.level != cur.level), closedBy(e, by)) + } + return nil +} + +// closedRaiseState is how a raise ended. An approval that changed nothing, +// because the class had moved since, doesn't count as approved. +func closedRaiseState(e event, raised bool) string { + switch { + case e == raiseApproved && raised: + return "approved" + case e == raiseRefused: + return "denied" + } + return "superseded" +} + +func closedBy(e event, by string) string { + if e == raiseApproved || e == raiseRefused { + return by + } + return "" +} + +func (c *Classes) propose(ctx context.Context, t *store.ClassTx, from, to Level, deadline time.Time) (*Raise, error) { + evidence, err := t.Approvals(ctx) + if err != nil { + return nil, err + } + shown := make([]RaiseEvidence, len(evidence)) + for i, a := range evidence { + shown[i] = RaiseEvidence{DecisionID: a.DecisionID, By: a.By, At: a.At} + } + body, err := json.Marshal(shown) + if err != nil { + return nil, fmt.Errorf("encode evidence: %w", err) + } + r := &Raise{ + ID: uuid.New(), From: from, To: to, Evidence: shown, Deadline: deadline.UTC(), + Class: Class{ + Connector: t.Class.Connector, Action: t.Class.Action, + TargetKind: t.Class.TargetKind, Environment: t.Class.Environment, + }, + } + if err := t.InsertRaise(ctx, store.Raise{ + ID: r.ID, FromLevel: from.String(), ToLevel: to.String(), Evidence: body, Deadline: r.Deadline, + }); err != nil { + return nil, err + } + return r, nil +} diff --git a/modules/judgement/autonomy_test.go b/modules/judgement/autonomy_test.go new file mode 100644 index 000000000..972bd8e25 --- /dev/null +++ b/modules/judgement/autonomy_test.go @@ -0,0 +1,123 @@ +package judgement + +import "testing" + +// TestAutonomyIsEarnedSlowlyAndLostAtOnce guards the earned-autonomy seam: a +// class earns a proposal to loosen only after N approvals in a row since it was +// last tightened, loosens only when that proposal is approved, drops to propose +// and wait at once on a denial or a failure (and never loosens by doing so), +// and a freeze holds changing actions without touching the class level. +func TestAutonomyIsEarnedSlowlyAndLostAtOnce(t *testing.T) { + const need = 3 + tests := []struct { + name string + start standing + events []event + want standing + wantPropose int + frozen bool + readOnly bool + wantHeld Level + }{ + { + name: "fewer than N approvals propose nothing", start: standing{level: ProposeAndWait}, + events: []event{approved, approved}, want: standing{level: ProposeAndWait, count: 2}, + wantHeld: ProposeAndWait, + }, + { + name: "the Nth approval proposes one level up", start: standing{level: ProposeAndWait}, + events: []event{approved, approved, approved}, + want: standing{level: ProposeAndWait, count: 3, raiseTo: ActAndTell}, wantPropose: 1, + wantHeld: ProposeAndWait, + }, + { + name: "approvals while a proposal waits propose nothing more", start: standing{level: ProposeAndWait}, + events: []event{approved, approved, approved, approved, approved}, + want: standing{level: ProposeAndWait, count: 5, raiseTo: ActAndTell}, wantPropose: 1, + wantHeld: ProposeAndWait, + }, + { + name: "an approved proposal raises the class and restarts the count", start: standing{level: ProposeAndWait}, + events: []event{approved, approved, approved, raiseApproved}, + want: standing{level: ActAndTell}, wantPropose: 1, + wantHeld: ActAndTell, + }, + { + name: "a refused proposal leaves the level and restarts the count", start: standing{level: ProposeAndWait}, + events: []event{approved, approved, approved, raiseRefused}, + want: standing{level: ProposeAndWait}, wantPropose: 1, + wantHeld: ProposeAndWait, + }, + { + name: "a denial restarts the count", start: standing{level: ProposeAndWait}, + events: []event{approved, approved, denied, approved, approved}, + want: standing{level: ProposeAndWait, count: 2}, + wantHeld: ProposeAndWait, + }, + { + name: "a denial drops a raised class to propose and wait", start: standing{level: ActAndTell}, + events: []event{denied}, want: standing{level: ProposeAndWait}, + wantHeld: ProposeAndWait, + }, + { + name: "a failure drops a raised class and withdraws the proposal", start: standing{level: ActAndTell, count: 3, raiseTo: ActQuietly}, + events: []event{failed}, want: standing{level: ProposeAndWait}, + wantHeld: ProposeAndWait, + }, + { + name: "a failure never loosens a class that escalates", start: standing{level: Escalate}, + events: []event{failed}, want: standing{level: Escalate}, + wantHeld: Escalate, + }, + { + name: "a proposal answered after the class dropped changes nothing", start: standing{level: ProposeAndWait, count: 3, raiseTo: ActQuietly}, + events: []event{raiseApproved}, want: standing{level: ProposeAndWait, count: 3}, + wantHeld: ProposeAndWait, + }, + { + name: "a class that acts quietly proposes nothing", start: standing{level: ActQuietly}, + events: []event{approved, approved, approved}, want: standing{level: ActQuietly, count: 3}, + wantHeld: ActQuietly, + }, + { + name: "a class that never runs proposes nothing", start: standing{level: Never}, + events: []event{approved, approved, approved}, want: standing{level: Never, count: 3}, + wantHeld: Never, + }, + { + name: "a freeze holds a raised class and keeps its level", start: standing{level: ActAndTell}, + want: standing{level: ActAndTell}, frozen: true, + wantHeld: ProposeAndWait, + }, + { + name: "a freeze leaves reading alone", start: standing{level: ActQuietly}, + want: standing{level: ActQuietly}, frozen: true, readOnly: true, + wantHeld: ActQuietly, + }, + { + name: "a freeze never loosens a class that escalates", start: standing{level: Escalate}, + want: standing{level: Escalate}, frozen: true, + wantHeld: Escalate, + }, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + got, proposals := tt.start, 0 + for _, e := range tt.events { + var propose bool + if got, propose = got.after(e, need); propose { + proposals++ + } + } + if got != tt.want { + t.Fatalf("standing = %+v, want %+v", got, tt.want) + } + if proposals != tt.wantPropose { + t.Fatalf("proposals = %d, want %d", proposals, tt.wantPropose) + } + if held := lowest(got.level, freezeCeiling(tt.frozen, tt.readOnly)); held != tt.wantHeld { + t.Fatalf("held at %s, want %s", held, tt.wantHeld) + } + }) + } +} diff --git a/modules/judgement/classes.go b/modules/judgement/classes.go index defbb900f..26376e4e8 100644 --- a/modules/judgement/classes.go +++ b/modules/judgement/classes.go @@ -93,6 +93,13 @@ type ClassView struct { Decisions int `json:"decisions"` LastDecidedAt *time.Time `json:"last_decided_at,omitzero"` ResetAt *time.Time `json:"reset_at,omitzero"` + // Count is the approvals in a row since the class was last tightened or + // raised. + Count int `json:"count"` + // TightenedAt and TightenedBecause say when and why the class last lost + // autonomy. + TightenedAt *time.Time `json:"tightened_at,omitzero"` + TightenedBecause string `json:"tightened_because,omitzero"` } // HistoryEntry is one decision in a class's history, with what became of its @@ -118,11 +125,28 @@ type ResetView struct { At time.Time `json:"at"` } +// RaiseView is one proposal to loosen a class by one level. +type RaiseView struct { + ID uuid.UUID `json:"id"` + From Level `json:"from"` + To Level `json:"to"` + State string `json:"state"` + Deadline time.Time `json:"deadline"` + ProposedAt time.Time `json:"proposed_at"` + AnsweredBy string `json:"answered_by,omitzero"` + AnsweredAt *time.Time `json:"answered_at,omitzero"` + // Evidence is the approvals that earned the proposal. + Evidence []RaiseEvidence `json:"evidence"` +} + // ClassDetail is a class with its history, newest first. type ClassDetail struct { ClassView History []HistoryEntry `json:"history"` Resets []ResetView `json:"resets"` + // Raises are the proposals to loosen the class, newest first. One whose + // state is pending waits for an answer. + Raises []RaiseView `json:"raises"` } // List returns every class, most recently decided first. @@ -137,7 +161,7 @@ func (c *Classes) List(ctx context.Context) ([]ClassView, error) { if err != nil { return nil, err } - v.Decisions = r.Decisions + v.Decisions, v.Count = r.Decisions, r.Streak if r.LastAt.Valid { v.LastDecidedAt = &r.LastAt.Time } @@ -158,6 +182,9 @@ func viewOf(r store.Class) (ClassView, error) { if r.ResetAt.Valid { v.ResetAt = &r.ResetAt.Time } + if r.TightenedAt.Valid { + v.TightenedAt, v.TightenedBecause = &r.TightenedAt.Time, r.TightenedBecause.String + } return v, nil } @@ -180,6 +207,13 @@ func (c *Classes) Detail(ctx context.Context, id uuid.UUID, outcomes Outcomes) ( if err != nil { return ClassDetail{}, err } + if view.Count, err = c.store.ClassCount(ctx, id); err != nil { + return ClassDetail{}, err + } + raises, err := c.store.ClassRaises(ctx, id) + if err != nil { + return ClassDetail{}, err + } ids := make([]uuid.UUID, len(decisions)) for i, d := range decisions { ids[i] = d.ID @@ -188,34 +222,82 @@ func (c *Classes) Detail(ctx context.Context, id uuid.UUID, outcomes Outcomes) ( if err != nil { return ClassDetail{}, err } - detail := ClassDetail{ClassView: view, History: make([]HistoryEntry, 0, len(decisions)), Resets: make([]ResetView, 0, len(resets))} + detail := ClassDetail{ClassView: view, Raises: make([]RaiseView, 0, len(raises))} + if detail.History, err = historyOf(decisions, got); err != nil { + return ClassDetail{}, err + } + if detail.Resets, err = resetViews(resets); err != nil { + return ClassDetail{}, err + } + for _, r := range raises { + v, err := c.raiseView(r) + if err != nil { + return ClassDetail{}, err + } + detail.Raises = append(detail.Raises, v) + } + return detail, nil +} + +func historyOf(decisions []store.Decision, got map[uuid.UUID]Outcome) ([]HistoryEntry, error) { + out := make([]HistoryEntry, 0, len(decisions)) for _, d := range decisions { var body Decision if err := json.Unmarshal(d.Body, &body); err != nil { - return ClassDetail{}, fmt.Errorf("decision %s: %w", d.ID, err) + return nil, fmt.Errorf("decision %s: %w", d.ID, err) } level, err := parseLevel(d.Level) if err != nil { - return ClassDetail{}, fmt.Errorf("decision %s: %w", d.ID, err) + return nil, fmt.Errorf("decision %s: %w", d.ID, err) } o := got[d.ID] - detail.History = append(detail.History, HistoryEntry{ + out = append(out, HistoryEntry{ DecisionID: d.ID, RunID: d.RunID, Target: body.Action.Target.ID, Level: level, Refused: body.RefusedBy, Approval: o.State, AnsweredBy: o.By, At: d.CreatedAt, }) } + return out, nil +} + +func resetViews(resets []store.Reset) ([]ResetView, error) { + out := make([]ResetView, 0, len(resets)) for _, r := range resets { from, err := parseLevel(r.FromLevel) if err != nil { - return ClassDetail{}, err + return nil, err } to, err := parseLevel(r.ToLevel) if err != nil { - return ClassDetail{}, err + return nil, err } - detail.Resets = append(detail.Resets, ResetView{From: from, To: to, By: r.By, At: r.At}) + out = append(out, ResetView{From: from, To: to, By: r.By, At: r.At}) } - return detail, nil + return out, nil +} + +func (c *Classes) raiseView(r store.Raise) (RaiseView, error) { + from, err := parseLevel(r.FromLevel) + if err != nil { + return RaiseView{}, err + } + to, err := parseLevel(r.ToLevel) + if err != nil { + return RaiseView{}, err + } + v := RaiseView{ + ID: r.ID, From: from, To: to, State: r.State, Deadline: r.Deadline, ProposedAt: r.ProposedAt, + AnsweredBy: r.AnsweredBy.String, Evidence: []RaiseEvidence{}, + } + if v.State == "pending" && !c.now().Before(r.Deadline) { + v.State = "expired" + } + if r.AnsweredAt.Valid { + v.AnsweredAt = &r.AnsweredAt.Time + } + if err := json.Unmarshal(r.Evidence, &v.Evidence); err != nil { + return RaiseView{}, fmt.Errorf("raise %s: %w", r.ID, err) + } + return v, nil } // Reset returns a class to its default level. Its decisions and earlier resets diff --git a/modules/judgement/guards.go b/modules/judgement/guards.go index fd1bc21c3..9cef57551 100644 --- a/modules/judgement/guards.go +++ b/modules/judgement/guards.go @@ -60,3 +60,34 @@ func (p Precedent) Judge(ctx context.Context, a Action) (Verdict, error) { } return Verdict{Ceiling: level, Findings: []Finding{{Text: "this action class is at " + level.String()}}}, nil } + +// Freezes says whether the organisation has frozen its actions. +type Freezes interface { + Frozen(ctx context.Context) (bool, error) +} + +// Freeze holds every action that changes something at propose and wait while +// the organisation is frozen. It never changes a class's level, so lifting the +// freeze puts every class back where it stood. +type Freeze struct { + Freezes Freezes +} + +// Name is the guard's name in verdicts. +func (Freeze) Name() string { return "freeze" } + +// Advisory is false. +func (Freeze) Advisory() bool { return false } + +// Judge returns the freeze's ceiling. +func (f Freeze) Judge(ctx context.Context, a Action) (Verdict, error) { + frozen, err := f.Freezes.Frozen(ctx) + if err != nil { + return Verdict{}, fmt.Errorf("read freeze: %w", err) + } + v := Verdict{Ceiling: freezeCeiling(frozen, a.Effect.ReadOnly)} + if v.Ceiling != ActQuietly { + v.Findings = []Finding{{Text: "the organisation is frozen"}} + } + return v, nil +} diff --git a/modules/judgement/internal/store/autonomy.go b/modules/judgement/internal/store/autonomy.go new file mode 100644 index 000000000..423c73cd6 --- /dev/null +++ b/modules/judgement/internal/store/autonomy.go @@ -0,0 +1,247 @@ +package store + +import ( + "context" + "database/sql" + "errors" + "fmt" + "time" + + "github.com/google/uuid" + "github.com/jmoiron/sqlx" +) + +// ErrNoRaise means no raise has that id. +var ErrNoRaise = errors.New("no such raise") + +// Raise is a proposal to loosen a class by one level. +type Raise struct { + ID uuid.UUID `db:"id"` + OrgID string `db:"org_id"` + ClassID uuid.UUID `db:"class_id"` + FromLevel string `db:"from_level"` + ToLevel string `db:"to_level"` + Evidence []byte `db:"evidence"` + State string `db:"state"` + Deadline time.Time `db:"deadline"` + ProposedAt time.Time `db:"proposed_at"` + AnsweredBy sql.NullString `db:"answered_by"` + AnsweredAt sql.NullTime `db:"answered_at"` +} + +const raiseColumns = `id, org_id, class_id, from_level, to_level, evidence, state, deadline, proposed_at, answered_by, answered_at` + +// ClassOfDecision returns the class a decision belongs to. +func (s *Store) ClassOfDecision(ctx context.Context, orgID string, decisionID uuid.UUID) (Class, error) { + var out Class + err := s.db.GetContext(ctx, &out, ` + SELECT c.id, c.org_id, c.connector, c.action, c.target_kind, c.environment, c.read_only, c.level, + c.created_at, c.reset_at, c.tightened_at, c.tightened_because + FROM judgement.decisions d + JOIN judgement.classes c ON c.org_id = d.org_id AND c.connector = d.connector AND c.action = d.action + AND c.target_kind = d.target_kind AND c.environment = d.environment + WHERE d.org_id = $1 AND d.id = $2`, orgID, decisionID) + if errors.Is(err, sql.ErrNoRows) { + return Class{}, ErrNoClass + } + if err != nil { + return Class{}, fmt.Errorf("read class of decision: %w", err) + } + return out, nil +} + +// ClassByKey returns the class named by its four names. +func (s *Store) ClassByKey(ctx context.Context, c Class) (Class, error) { + var out Class + err := s.db.GetContext(ctx, &out, ` + SELECT `+classColumns+` FROM judgement.classes + WHERE org_id = $1 AND connector = $2 AND action = $3 AND target_kind = $4 AND environment = $5`, + c.OrgID, c.Connector, c.Action, c.TargetKind, c.Environment) + if errors.Is(err, sql.ErrNoRows) { + return Class{}, ErrNoClass + } + if err != nil { + return Class{}, fmt.Errorf("read class: %w", err) + } + return out, nil +} + +// RaiseByID returns one raise. +func (s *Store) RaiseByID(ctx context.Context, orgID string, id uuid.UUID) (Raise, error) { + var out Raise + err := s.db.GetContext(ctx, &out, `SELECT `+raiseColumns+` FROM judgement.class_raises WHERE org_id = $1 AND id = $2`, orgID, id) + if errors.Is(err, sql.ErrNoRows) { + return Raise{}, ErrNoRaise + } + if err != nil { + return Raise{}, fmt.Errorf("read raise: %w", err) + } + return out, nil +} + +// ClassRaises returns a class's raises, newest first. +func (s *Store) ClassRaises(ctx context.Context, id uuid.UUID) ([]Raise, error) { + var out []Raise + if err := s.db.SelectContext(ctx, &out, ` + SELECT `+raiseColumns+` FROM judgement.class_raises WHERE class_id = $1 ORDER BY proposed_at DESC, id`, id); err != nil { + return nil, fmt.Errorf("list class raises: %w", err) + } + return out, nil +} + +// ClassCount returns how many approvals a class has counted, for the class +// view. +func (s *Store) ClassCount(ctx context.Context, id uuid.UUID) (int, error) { + var n int + if err := s.db.GetContext(ctx, &n, `SELECT count(*) FROM judgement.class_approvals WHERE class_id = $1 AND counted`, id); err != nil { + return 0, fmt.Errorf("count approvals: %w", err) + } + return n, nil +} + +// ClassTx is one class held for update. Everything done through it commits +// together, so two answers arriving at once see each other's count. +type ClassTx struct { + tx *sqlx.Tx + now time.Time + Class Class +} + +// InClass runs fn with the class locked. A raise nobody answered by its +// deadline is expired first, and its count restarts, so a class that wasn't +// raised is asked again only after earning it again. +func (s *Store) InClass(ctx context.Context, orgID string, id uuid.UUID, now time.Time, fn func(*ClassTx) error) error { + tx, err := s.db.BeginTxx(ctx, nil) + if err != nil { + return fmt.Errorf("class: %w", err) + } + defer func() { _ = tx.Rollback() }() + t := &ClassTx{tx: tx, now: now} + err = tx.GetContext(ctx, &t.Class, `SELECT `+classColumns+` FROM judgement.classes WHERE org_id = $1 AND id = $2 FOR UPDATE`, orgID, id) + if errors.Is(err, sql.ErrNoRows) { + return ErrNoClass + } + if err != nil { + return fmt.Errorf("lock class: %w", err) + } + res, err := tx.ExecContext(ctx, ` + UPDATE judgement.class_raises SET state = 'expired', answered_at = $2 + WHERE class_id = $1 AND state = 'pending' AND deadline <= $2`, id, now) + if err != nil { + return fmt.Errorf("expire raise: %w", err) + } + if n, _ := res.RowsAffected(); n > 0 { + if err := t.ClearCount(ctx); err != nil { + return err + } + } + if err := fn(t); err != nil { + return err + } + if err := tx.Commit(); err != nil { + return fmt.Errorf("class: %w", err) + } + return nil +} + +// Count returns how many approvals count toward a raise, and the raise waiting +// for an answer, if one is. +func (t *ClassTx) Count(ctx context.Context) (int, *Raise, error) { + var n int + if err := t.tx.GetContext(ctx, &n, `SELECT count(*) FROM judgement.class_approvals WHERE class_id = $1 AND counted`, t.Class.ID); err != nil { + return 0, nil, fmt.Errorf("count approvals: %w", err) + } + var r Raise + err := t.tx.GetContext(ctx, &r, `SELECT `+raiseColumns+` FROM judgement.class_raises WHERE class_id = $1 AND state = 'pending'`, t.Class.ID) + if errors.Is(err, sql.ErrNoRows) { + return n, nil, nil + } + if err != nil { + return 0, nil, fmt.Errorf("read pending raise: %w", err) + } + return n, &r, nil +} + +// AddApproval counts one approved decision. A decision counts once. +func (t *ClassTx) AddApproval(ctx context.Context, decisionID uuid.UUID, by string) error { + if _, err := t.tx.ExecContext(ctx, ` + INSERT INTO judgement.class_approvals (id, org_id, class_id, decision_id, by, at) + VALUES ($1, $2, $3, $4, $5, $6) ON CONFLICT (decision_id) DO NOTHING`, + uuid.New(), t.Class.OrgID, t.Class.ID, decisionID, by, t.now); err != nil { + return fmt.Errorf("record approval: %w", err) + } + return nil +} + +// Approval is one counted approval, the evidence for a raise. +type Approval struct { + DecisionID uuid.UUID `db:"decision_id" json:"decision_id"` + By string `db:"by" json:"by"` + At time.Time `db:"at" json:"at"` +} + +// Approvals returns the approvals that count, oldest first. +func (t *ClassTx) Approvals(ctx context.Context) ([]Approval, error) { + var out []Approval + if err := t.tx.SelectContext(ctx, &out, ` + SELECT decision_id, by, at FROM judgement.class_approvals WHERE class_id = $1 AND counted ORDER BY at, id`, t.Class.ID); err != nil { + return nil, fmt.Errorf("list approvals: %w", err) + } + return out, nil +} + +// ClearCount stops every approval counting. +func (t *ClassTx) ClearCount(ctx context.Context) error { + if _, err := t.tx.ExecContext(ctx, `UPDATE judgement.class_approvals SET counted = false WHERE class_id = $1 AND counted`, t.Class.ID); err != nil { + return fmt.Errorf("clear approvals: %w", err) + } + return nil +} + +// SetLevel sets the class's level. +func (t *ClassTx) SetLevel(ctx context.Context, level string) error { + if _, err := t.tx.ExecContext(ctx, `UPDATE judgement.classes SET level = $2 WHERE id = $1`, t.Class.ID, level); err != nil { + return fmt.Errorf("set level: %w", err) + } + return nil +} + +// Tighten records that the class lost autonomy, and why. +func (t *ClassTx) Tighten(ctx context.Context, level, because string) error { + if _, err := t.tx.ExecContext(ctx, ` + UPDATE judgement.classes SET level = $2, tightened_at = $3, tightened_because = $4 WHERE id = $1`, + t.Class.ID, level, t.now, because); err != nil { + return fmt.Errorf("tighten class: %w", err) + } + return nil +} + +// CloseRaise settles the class's pending raise. +func (t *ClassTx) CloseRaise(ctx context.Context, state, by string) error { + if _, err := t.tx.ExecContext(ctx, ` + UPDATE judgement.class_raises SET state = $2, answered_by = nullif($3, ''), answered_at = $4 + WHERE class_id = $1 AND state = 'pending'`, t.Class.ID, state, by, t.now); err != nil { + return fmt.Errorf("close raise: %w", err) + } + return nil +} + +// InsertRaise records a proposal. +func (t *ClassTx) InsertRaise(ctx context.Context, r Raise) error { + if _, err := t.tx.ExecContext(ctx, ` + INSERT INTO judgement.class_raises (id, org_id, class_id, from_level, to_level, evidence, state, deadline, proposed_at) + VALUES ($1, $2, $3, $4, $5, $6, 'pending', $7, $8)`, + r.ID, t.Class.OrgID, t.Class.ID, r.FromLevel, r.ToLevel, r.Evidence, r.Deadline, t.now); err != nil { + return fmt.Errorf("record raise: %w", err) + } + return nil +} + +// CancelRaise withdraws a pending raise whose request couldn't be asked. +func (s *Store) CancelRaise(ctx context.Context, orgID string, id uuid.UUID) error { + if _, err := s.db.ExecContext(ctx, ` + UPDATE judgement.class_raises SET state = 'superseded' WHERE org_id = $1 AND id = $2 AND state = 'pending'`, orgID, id); err != nil { + return fmt.Errorf("cancel raise: %w", err) + } + return nil +} diff --git a/modules/judgement/internal/store/classes.go b/modules/judgement/internal/store/classes.go index 289e8e9bc..c04771b9a 100644 --- a/modules/judgement/internal/store/classes.go +++ b/modules/judgement/internal/store/classes.go @@ -25,6 +25,10 @@ type Class struct { Level string `db:"level"` CreatedAt time.Time `db:"created_at"` ResetAt sql.NullTime `db:"reset_at"` + // TightenedAt and TightenedBecause say when and why the class last lost + // autonomy; the count of approvals restarts there. + TightenedAt sql.NullTime `db:"tightened_at"` + TightenedBecause sql.NullString `db:"tightened_because"` } // ClassSummary is a class with how many decisions it holds. @@ -32,6 +36,7 @@ type ClassSummary struct { Class Decisions int `db:"decisions"` LastAt sql.NullTime `db:"last_at"` + Streak int `db:"streak"` } // Reset is one return of a class to its default. @@ -43,7 +48,7 @@ type Reset struct { At time.Time `db:"at"` } -const classColumns = `id, org_id, connector, action, target_kind, environment, read_only, level, created_at, reset_at` +const classColumns = `id, org_id, connector, action, target_kind, environment, read_only, level, created_at, reset_at, tightened_at, tightened_because` // EnsureClass returns the class c names, creating it at c.Level when it is // new. An existing class keeps its level. @@ -67,7 +72,9 @@ func (s *Store) Classes(ctx context.Context, orgID string) ([]ClassSummary, erro var out []ClassSummary err := s.db.SelectContext(ctx, &out, ` SELECT c.id, c.org_id, c.connector, c.action, c.target_kind, c.environment, c.read_only, c.level, - c.created_at, c.reset_at, count(d.id) AS decisions, max(d.created_at) AS last_at + c.created_at, c.reset_at, c.tightened_at, c.tightened_because, + count(d.id) AS decisions, max(d.created_at) AS last_at, + (SELECT count(*) FROM judgement.class_approvals a WHERE a.class_id = c.id AND a.counted) AS streak FROM judgement.classes c LEFT JOIN judgement.decisions d ON d.org_id = c.org_id AND d.connector = c.connector AND d.action = c.action AND d.target_kind = c.target_kind AND d.environment = c.environment @@ -140,6 +147,13 @@ func (s *Store) ResetClass(ctx context.Context, orgID string, id uuid.UUID, leve UPDATE judgement.classes SET level = $2, reset_at = $3 WHERE id = $1 RETURNING `+classColumns, id, level, at); err != nil { return Class{}, fmt.Errorf("reset class: %w", err) } + // A reset starts the count again and withdraws a raise that was waiting. + if _, err := tx.ExecContext(ctx, `UPDATE judgement.class_approvals SET counted = false WHERE class_id = $1 AND counted`, id); err != nil { + return Class{}, fmt.Errorf("reset class: %w", err) + } + if _, err := tx.ExecContext(ctx, `UPDATE judgement.class_raises SET state = 'superseded' WHERE class_id = $1 AND state = 'pending'`, id); err != nil { + return Class{}, fmt.Errorf("reset class: %w", err) + } if _, err := tx.ExecContext(ctx, ` INSERT INTO judgement.class_resets (id, org_id, class_id, from_level, to_level, by, at) VALUES ($1, $2, $3, $4, $5, $6, $7)`, uuid.New(), orgID, id, before.Level, level, by, at); err != nil { diff --git a/modules/judgement/judgement.go b/modules/judgement/judgement.go index f3c7e0c69..f4866958b 100644 --- a/modules/judgement/judgement.go +++ b/modules/judgement/judgement.go @@ -125,6 +125,12 @@ type Tools interface { Tool(name string) (connectors.Tool, bool) } +// FailureRecorder is told when an action of a class failed, so the class loses +// the autonomy it had. +type FailureRecorder interface { + Failed(ctx context.Context, c Class) error +} + type recorder interface { Record(ctx context.Context, d store.Decision) (store.Decision, error) ForRun(ctx context.Context, orgID string, runID uuid.UUID) ([]store.Decision, error) @@ -137,14 +143,15 @@ type Module struct { rules []HardRule guards []Guard store recorder + failed FailureRecorder log *slog.Logger now func() time.Time } // NewModule returns the judgement module for orgID, with its hard rules and -// guards. -func NewModule(db *sqlx.DB, log *slog.Logger, orgID string, tools Tools, rules []HardRule, guards []Guard) *Module { - return &Module{orgID: orgID, tools: tools, rules: rules, guards: guards, store: store.New(db), log: log, now: time.Now} +// guards. An action of a class that fails is reported to failed. +func NewModule(db *sqlx.DB, log *slog.Logger, orgID string, tools Tools, rules []HardRule, guards []Guard, failed FailureRecorder) *Module { + return &Module{orgID: orgID, tools: tools, rules: rules, guards: guards, store: store.New(db), failed: failed, log: log, now: time.Now} } // Assess judges one action and records the decision. Judging the same key @@ -229,11 +236,24 @@ func (m *Module) Execute(ctx context.Context, d Decision, input jsontext.Value, case connectors.Digest(d.Action.Name, input) != d.Action.Digest: return "", ErrAltered } + return m.invoke(ctx, d, input, key) +} + +// invoke runs the judged action. A failure, or an outcome nobody can confirm, +// drops the action's class to propose and wait at once, whatever level it ran at. +func (m *Module) invoke(ctx context.Context, d Decision, input jsontext.Value, key string) (string, error) { tool, ok := m.tools.Tool(d.Action.Connector) if !ok { return "", fmt.Errorf("%q isn't running", d.Action.Connector) } - return tool.Invoke(ctx, connectors.Invocation{Action: d.Action.Name, Input: input, IdempotencyKey: key}) + out, err := tool.Invoke(ctx, connectors.Invocation{Action: d.Action.Name, Input: input, IdempotencyKey: key}) + // A shutdown cancels the call without the action having gone wrong. + if err != nil && m.failed != nil && !errors.Is(err, context.Canceled) { + if ferr := m.failed.Failed(ctx, d.Action.Class()); ferr != nil { + return out, errors.Join(err, fmt.Errorf("tighten class: %w", ferr)) + } + } + return out, err } // Approval is a person's permission to run one decision's exact action. It @@ -263,11 +283,7 @@ func (m *Module) ExecuteApproved(ctx context.Context, d Decision, a Approval, in case connectors.Digest(d.Action.Name, input) != d.Action.Digest: return "", ErrAltered } - tool, ok := m.tools.Tool(d.Action.Connector) - if !ok { - return "", fmt.Errorf("%q isn't running", d.Action.Connector) - } - return tool.Invoke(ctx, connectors.Invocation{Action: d.Action.Name, Input: input, IdempotencyKey: key}) + return m.invoke(ctx, d, input, key) } // ForRun returns a run's decisions in the order they were made. diff --git a/ui/src/archie/ClassView.vue b/ui/src/archie/ClassView.vue index be388b023..e90d4acbd 100644 --- a/ui/src/archie/ClassView.vue +++ b/ui/src/archie/ClassView.vue @@ -1,5 +1,5 @@