feat(judgement,approvals,governance,ui): a class earns a raise after N approvals and drops on denial or failure; a freeze holds changing actions (#2004)

This commit is contained in:
sam committed 2026-11-16 05:03:24 +11:00
1 parent ff58c8e39b
commit 22aee72679
17 files changed
+1185 -58

No files matched your search

+5 -5
View File
@@ -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.
@@ -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;
+126 -12
View File
@@ -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,
}
+11 -8
View File
@@ -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)
+52 -6
View File
@@ -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
}
+10 -4
View File
@@ -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
+295
View File
@@ -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
}
+123
View File
@@ -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)
}
})
}
}
+91 -9
View File
@@ -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
+31
View File
@@ -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
}
@@ -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
}
+16 -2
View File
@@ -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 {
+25 -9
View File
@@ -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.
+53 -2
View File
@@ -1,5 +1,5 @@
<script setup lang="ts">
import { onBeforeUnmount, ref, watch } from "vue";
import { computed, onBeforeUnmount, ref, watch } from "vue";
import { useRouter } from "vue-router";
import PageHeader from "@/base/PageHeader.vue";
@@ -16,6 +16,7 @@ import {
import { Badge } from "@/components/ui/badge";
import { Button } from "@/components/ui/button";
import { Empty, EmptyHeader, EmptyTitle } from "@/components/ui/empty";
import { MetadataList } from "@/components/ui/metadata-list";
import { ReadError } from "@/components/ui/read-error";
import { Section } from "@/components/ui/section";
import { Spinner } from "@/components/ui/spinner";
@@ -24,6 +25,22 @@ import { Timestamp } from "@/components/ui/timestamp";
import { type ClassDetail, classDetail, resetClass, Unauthorized } from "./api";
import { className, levelLabel } from "./state";
const autonomyRows = computed(() => {
const d = detail.value;
if (!d) return [];
const rows: { label: string; value?: string; at?: string }[] = [
{ label: "Approvals in a row", value: String(d.count) },
d.tightened_at
? { label: "Last tightened", value: d.tightened_because, at: d.tightened_at }
: { label: "Last tightened", value: "Never" },
];
const raise = d.raises.find((r) => r.state === "pending");
if (raise) {
rows.push({ label: "Raise waiting", value: `${levelLabel(raise.from)} to ${levelLabel(raise.to)}, answer by`, at: raise.deadline });
}
return rows;
});
/** One action class: its level, and every decision made in it. */
const props = defineProps<{ id: string }>();
const emit = defineEmits<{ unauthorized: [] }>();
@@ -87,7 +104,41 @@ onBeforeUnmount(() => controller.abort());
</Button>
</PageHeader>
<ReadError v-if="error" :message="error" retry-label="Retry" @retry="load" />
<Section title="History">
<Section title="Autonomy">
<MetadataList :rows="autonomyRows">
<template #value="{ row }">
<template v-if="row.at">
<Timestamp :at="row.at" /><template v-if="row.value">, {{ row.value }}</template>
</template>
<template v-else>{{ row.value }}</template>
</template>
</MetadataList>
</Section>
<Section v-if="detail.raises.length > 0" title="Raises" class="mt-4">
<Table>
<TableHeader>
<TableRow>
<TableHead>From</TableHead>
<TableHead>To</TableHead>
<TableHead>State</TableHead>
<TableHead>Answered by</TableHead>
<TableHead>Approvals</TableHead>
<TableHead>Proposed</TableHead>
</TableRow>
</TableHeader>
<TableBody>
<TableRow v-for="r in detail.raises" :key="r.id">
<TableCell>{{ levelLabel(r.from) }}</TableCell>
<TableCell>{{ levelLabel(r.to) }}</TableCell>
<TableCell>{{ r.state }}</TableCell>
<TableCell>{{ r.answered_by }}</TableCell>
<TableCell>{{ r.evidence.map((e) => e.by).join(", ") }}</TableCell>
<TableCell><Timestamp :at="r.proposed_at" /></TableCell>
</TableRow>
</TableBody>
</Table>
</Section>
<Section title="History" class="mt-4">
<Empty v-if="detail.history.length === 0">
<EmptyHeader><EmptyTitle>No decisions yet</EmptyTitle></EmptyHeader>
</Empty>
+2
View File
@@ -56,6 +56,7 @@ onBeforeUnmount(() => controller.abort());
<TableHead>Environment</TableHead>
<TableHead>Level</TableHead>
<TableHead>Decisions</TableHead>
<TableHead>Approvals in a row</TableHead>
<TableHead>Last</TableHead>
</TableRow>
</TableHeader>
@@ -66,6 +67,7 @@ onBeforeUnmount(() => controller.abort());
<TableCell>{{ c.environment }}</TableCell>
<TableCell><Badge variant="outline">{{ levelLabel(c.level) }}</Badge></TableCell>
<TableCell>{{ c.decisions }}</TableCell>
<TableCell>{{ c.count }}</TableCell>
<TableCell><Timestamp v-if="c.last_decided_at" :at="c.last_decided_at" /></TableCell>
</TableRow>
</TableBody>
+25 -1
View File
@@ -4,10 +4,12 @@ import { onBeforeUnmount, onMounted, ref } from "vue";
import PageHeader from "@/base/PageHeader.vue";
import { Button } from "@/components/ui/button";
import { DurationInput } from "@/components/ui/duration-input";
import { NumberField, NumberFieldContent, NumberFieldDecrement, NumberFieldIncrement, NumberFieldInput } from "@/components/ui/number-field";
import { ReadError } from "@/components/ui/read-error";
import { Section } from "@/components/ui/section";
import { SettingRow } from "@/components/ui/setting-row";
import { Spinner } from "@/components/ui/spinner";
import { Switch } from "@/components/ui/switch";
import { getSettings, saveSettings, Unauthorized } from "./api";
/**
@@ -17,6 +19,8 @@ import { getSettings, saveSettings, Unauthorized } from "./api";
const emit = defineEmits<{ unauthorized: [] }>();
const deadline = ref("24h");
const raiseAfter = ref(3);
const frozen = ref(false);
const saved = ref("");
const loading = ref(true);
const saving = ref(false);
@@ -29,6 +33,8 @@ async function load() {
try {
const set = await getSettings(controller.signal);
deadline.value = set.approval_deadline;
raiseAfter.value = set.raise_after;
frozen.value = set.frozen;
} catch (err) {
fail(err);
} finally {
@@ -41,7 +47,7 @@ async function save() {
error.value = "";
saved.value = "";
try {
await saveSettings({ approval_deadline: deadline.value });
await saveSettings({ approval_deadline: deadline.value, raise_after: raiseAfter.value, frozen: frozen.value });
saved.value = "Saved.";
} catch (err) {
fail(err);
@@ -72,6 +78,24 @@ onBeforeUnmount(() => controller.abort());
<p class="text-caption text-muted-foreground">
How long an approval request waits for an answer. Nothing runs when it expires.
</p>
<SettingRow label="Approvals to propose a raise" for="raise-after">
<NumberField v-model="raiseAfter" :min="1" :max="100" class="w-32">
<NumberFieldContent>
<NumberFieldDecrement />
<NumberFieldInput id="raise-after" class="font-mono" />
<NumberFieldIncrement />
</NumberFieldContent>
</NumberField>
</SettingRow>
<p class="text-caption text-muted-foreground">
Approvals in a row, since a class was last tightened, before Archie proposes raising it one level.
</p>
<SettingRow label="Freeze" for="frozen" tone="danger">
<Switch id="frozen" v-model="frozen" aria-label="Freeze" />
</SettingRow>
<p class="text-caption text-muted-foreground">
Every action that changes something waits for approval. Class levels stay as they are.
</p>
<div class="mt-3 flex items-center gap-3">
<Button :disabled="saving" @click="save">Save</Button>
<span v-if="saved" class="text-caption text-muted-foreground">{{ saved }}</span>
+21
View File
@@ -140,6 +140,10 @@ export interface Trail {
export interface Settings {
/** A Go duration, such as "24h". */
approval_deadline: string;
/** Approvals in a row, since a class was last tightened, that earn a proposal to raise it. */
raise_after: number;
/** Holds every action that changes something at propose and wait. */
frozen: boolean;
}
export const getSettings = (signal?: AbortSignal) => get<Settings>("/api/settings", signal);
@@ -187,6 +191,10 @@ export interface ActionClass {
decisions: number;
last_decided_at?: string;
reset_at?: string;
/** Approvals in a row since the class was last tightened or raised. */
count: number;
tightened_at?: string;
tightened_because?: "denied" | "failed";
}
export interface HistoryEntry {
@@ -200,7 +208,20 @@ export interface HistoryEntry {
at: string;
}
export interface Raise {
id: string;
from: Level;
to: Level;
state: "pending" | "approved" | "denied" | "expired" | "superseded";
deadline: string;
proposed_at: string;
answered_by?: string;
answered_at?: string;
evidence: { decision_id: string; by: string; at: string }[];
}
export interface ClassDetail extends ActionClass {
raises: Raise[];
history: HistoryEntry[];
resets: { from: Level; to: Level; by: string; at: string }[];
}