runview

type ApprovalCheck struct {
	OK   bool   `json:"ok"`
	Text string `json:"text"`

	// What the approver cards show; not in the JSON view. Counted and Denied are the approvers
	// whose decision counted in the recount, Ignored the reason each other decision did not, Keys
	// each approver's key fingerprint (from the approver keys given), and Times the two times of
	// each counted approver's decision, with their sanity flags (audit.ApprovalVerdict.Times).
	Counted, Denied []string                      `json:"-"`
	Ignored         map[string]string             `json:"-"`
	Keys            map[string]string             `json:"-"`
	Times           map[string]audit.DecisionTime `json:"-"`
}

type Approvals struct {
	Keys     agent.ApproverVerifierFor
	Expected *agent.ApprovalPolicy
}

type ApproverCard struct {
	Name     string
	Initials string
	// State is approved, denied or pending.
	State string
	// Verify says what is known of the signature, in words: "signature verified", "signature NOT
	// verified", "in the signed log, signature not checked" or "signature not checked". VerifyOK
	// reports the first. Empty for a pending approver.
	Verify   string
	VerifyOK bool
	Why      string // why the decision did not count, when it did not
	// Fingerprint is the approver's key as "ed25519:3b6a27bc" (the first 8 hex digits of the
	// SHA-256 of its public key), when -approver-keys gave it.
	Fingerprint string
	// DecidedAt is when the approver says they decided, by their clock, inside the signature;
	// RecordedAt is when the decision was journaled, by the submitter's clock (not signed). Both are display text
	// in UTC ("2026-10-13 12:14:03.123"), empty when the record holds none. Gap is the difference
	// between them in words, shown without judgment, and Flags the sanity notes on them
	// (audit.FlagDecisionTimes, under audit.DefaultDecisionTimeTolerance), which never change
	// the gate's outcome. Empty for a pending approver.
	DecidedAt, RecordedAt string
	Gap                   string
	Flags                 []string
	// TimesNote says why no times are shown when the approver has several signed decisions with
	// the card's outcome and their signatures were not checked: which one counted, and so which
	// decided_at is signed, is not known.
	TimesNote string
}

type Change struct {
	Change string `json:"change"` // added, removed or changed
	What   string `json:"what"`   // node, edge, entry or flow
	Node   string `json:"node,omitempty"`
	From   string `json:"from,omitempty"`
	To     string `json:"to,omitempty"`
	// Details say what changed, one item each ("block charge -> refund", "approval 1 of 3 -> 2 of
	// 3"); for an added or removed node, what it was.
	Details []string `json:"details,omitempty"`
	// Gate is how the node's approval gate changed: weakened (a set of decisions the new gate
	// accepts would not have passed the old one: the gate was removed, its need lowered, or an
	// approver added without raising the need to match), strengthened (the reverse, and not
	// weakened), or reordered (the same approvers and need in another policy order). Empty when the
	// gate did not change. A removed node's gate counts as removed.
	Gate string `json:"gate,omitempty"`
}

type Config struct {
	Name     string
	Data     []byte
	Registry *plan.Registry
	// Strict makes Check fail on a warning as well as on an error (bide view -check -strict).
	Strict bool
}

type ConfigView struct {
	Name       string               `json:"name"`
	Flow       string               `json:"flow"`
	Typed      bool                 `json:"typed"`
	Digest     string               `json:"digest,omitempty"`
	Errors     int                  `json:"errors"`
	Warnings   int                  `json:"warnings"`
	Problems   []plan.ConfigProblem `json:"problems,omitempty"`
	Graph      *Graph               `json:"graph,omitempty"`
	Approvals  []string             `json:"approvals,omitempty"`
	CheckLabel string               `json:"check"`
	// Risk counts the nodes by crash behavior and gate, for the summary card.
	Risk RiskSummary `json:"risk"`
	// Assertions are the verdicts on the config's assert lines, in order.
	Assertions []plan.AssertionResult `json:"assertions,omitempty"`
	// Verdict is the answer the page opens with (see configVerdict); it is not in the JSON view.
	Verdict Verdict `json:"-"`
}

type Conformance struct {
	OK     bool     `json:"ok"`
	Method string   `json:"method"` // "plan.Conform", or "structural" (see structural)
	Source string   `json:"source"` // where the topology came from
	Diffs  []string `json:"diffs,omitempty"`
	Digest string   `json:"digest"` // "match", "mismatch", or "not compared"
}

type Counts struct {
	NodesAdded   int `json:"nodes_added"`
	NodesRemoved int `json:"nodes_removed"`
	NodesChanged int `json:"nodes_changed"`
	EdgesAdded   int `json:"edges_added"`
	EdgesRemoved int `json:"edges_removed"`
	EdgesChanged int `json:"edges_changed"`
}

type Decision struct {
	Approver   string `json:"approver,omitempty"` // empty for a one-decision gate's Approve
	Approved   bool   `json:"approved"`
	Signed     bool   `json:"signed"`
	DecidedAt  string `json:"decided_at,omitempty"`
	RecordedAt string `json:"recorded_at,omitempty"`
}

type Diff struct {
	Old, New Config
}

type DiffView struct {
	Name    string `json:"name"`
	OldName string `json:"old_name"`
	Flow    string `json:"flow"`
	// Typed reports both sides were checked against a plan.Registry, so their digests are known
	// (unless a side has errors).
	Typed     bool     `json:"typed"`
	OldDigest string   `json:"old_digest,omitempty"`
	NewDigest string   `json:"new_digest,omitempty"`
	Changes   []Change `json:"changes"`
	// Weakened and Strengthened name each node whose approval gate changed that way, with how:
	// "charge: approval 2 of 3 -> 1 of 3".
	Weakened     []string `json:"weakened,omitempty"`
	Strengthened []string `json:"strengthened,omitempty"`
	Counts       Counts   `json:"counts"`
	// OldErrors and NewErrors count each side's config errors (bide check lists them): a side
	// with errors is compared as far as it reads.
	OldErrors int    `json:"old_errors"`
	NewErrors int    `json:"new_errors"`
	Graph     *Graph `json:"graph,omitempty"`
	// Verdict is the answer the page opens with (see diffVerdict); it is not in the JSON view.
	Verdict Verdict `json:"-"`
}

type Event struct {
	Seq    int      `json:"seq"`   // 1-based position in the journal
	Name   string   `json:"name"`  // the record's journal name
	Kind   string   `json:"kind"`  // agent.StepKind
	Class  string   `json:"class"` // the row's style: model, tool, attempt, approval, halt, end, value
	Title  string   `json:"title"`
	Detail string   `json:"detail,omitempty"`
	Badges []string `json:"badges,omitempty"`

	// What the page adds to the row; none of it is in the JSON view.
	At      time.Time `json:"-"` // when the journal says the record happened (a start or an attempt marker), else zero
	Payload string    `json:"-"` // the record as indented JSON, cut to a readable size (see prettyJSON)
	Rel     string    `json:"-"` // At as an offset from the run's start ("+3.2s")
	Abs     string    `json:"-"` // At in UTC, for the hover
	Bar     *TimeBar  `json:"-"` // the span from At to the next timestamped record
}

type Exports map[string][]agent.Record

type Flow struct {
	Topology plan.Topology
	// Digest is flow.Digest(), compared with the digest the run journaled. Empty: not compared.
	Digest string
	// Conform is flow.Conform. Nil: the viewer runs only its structural check (see Conformance).
	// Source says where the topology came from, as the page shows it.
	Conform func(ctx context.Context, j *agent.Journal, runID string) (bool, []string, error)
	Source  string
}

type Follower interface {
	// Grew reports whether runID has a record after the store sequence after (agent.Entry.Seq).
	// It is the read live mode polls, so it is cheap: one Load from after, stopped at its first entry.
	Grew(ctx context.Context, runID string, after int64) (bool, error)
	// HistorySeq is History with each record's store sequence, both read in one pass.
	HistorySeq(ctx context.Context, runID string) ([]agent.Record, []int64, error)
}

type Gate struct {
	ToolUseID  string     `json:"tool_use_id"`
	ToolName   string     `json:"tool_name,omitempty"`
	Single     bool       `json:"single,omitempty"` // a one-decision gate (agent.Approve)
	Need       int        `json:"need,omitempty"`
	Approvers  []string   `json:"approvers,omitempty"`
	ApprovedBy []string   `json:"approved_by,omitempty"`
	DeniedBy   []string   `json:"denied_by,omitempty"`
	Pending    []string   `json:"pending,omitempty"`
	Decisions  []Decision `json:"decisions,omitempty"`
	Tallied    bool       `json:"tallied"` // the gate journaled its terminal tally
	// AskedAt is when the run asked for approval, by the run's clock: a flow node's request time
	// (agent.ApprovalRequest.RecordedAt), else the pause's (agent.ApprovalWait.RecordedAt); empty
	// when the journal does not say.
	AskedAt string `json:"asked_at,omitempty"`
	// Waiting: the run paused at this gate (its approval-pending record, agent.ApprovalWait) and
	// the call has no result, no terminal tally, and (for a one-decision gate) no decision yet.
	Waiting bool `json:"waiting"`
	// Signatures is whether the gate's approver signatures were verified (audit.VerifyApprovals,
	// with -approver-keys), or why they were not checked; SignaturesOK reports a verified gate.
	Signatures   string `json:"signatures"`
	SignaturesOK bool   `json:"signatures_ok"`
	Status       string `json:"status"`
	// Reapproval: the gate's recorded tally passed on decisions that predate the signed decision
	// format (agent.DecisionFormat) and the call has not run, so the gate asks again when the run
	// resumes (agent.PendingReapproval); only decisions with a signed time count.
	Reapproval bool `json:"reapproval,omitempty"`
	// Cards is each approver as the page shows them (see ApproverCard); not in the JSON view.
	Cards []ApproverCard `json:"-"`
}

type Graph struct {
	Nodes   []GraphNode `json:"nodes"`
	Edges   []GraphEdge `json:"edges"`
	SVG     string      `json:"-"`
	Mermaid string      `json:"mermaid"`
	Width   int         `json:"-"`
	Height  int         `json:"-"`
	// contains filtered or unexported fields
}

type GraphEdge struct {
	From    string `json:"from"`
	To      string `json:"to"`
	Label   string `json:"label,omitempty"`
	Taken   bool   `json:"taken"`
	Back    bool   `json:"back,omitempty"`
	Problem string `json:"problem,omitempty"` // a config problem at this edge or arm
	Cex     bool   `json:"cex,omitempty"`     // on a violated assertion's counterexample path
	// Change is how a flow diff changed this edge or arm (added, removed or changed), which
	// styles it; empty outside a diff.
	Change string `json:"change,omitempty"`
	// contains filtered or unexported fields
}

type GraphNode struct {
	Name   string `json:"name"`
	Kind   string `json:"kind"`
	Status string `json:"status"` // done, halted, attempted, waiting (at its approval gate), not-reached
	// Gate is the node's declared approval gate ("2 of 3", "one decision"), empty for none, and
	// GateStatus where its latest evaluation stands (see Gate.Status).
	Gate       string `json:"gate,omitempty"`
	GateStatus string `json:"gate_status,omitempty"`
	// GateLine and SigLine are what the node's box says about its gate, short enough to read in
	// a screenshot: "approved 2 of 3" or "waiting, 1 of 2 approvals", and "signatures verified" (or
	// not, and why in short). GateClass styles them: good, wait or bad.
	GateLine  string `json:"gate_line,omitempty"`
	SigLine   string `json:"sig_line,omitempty"`
	GateClass string `json:"gate_class,omitempty"`
	Iters     int    `json:"iters,omitempty"`
	Last      bool   `json:"last,omitempty"`
	Note      string `json:"note,omitempty"`  // a line under the box
	Title     string `json:"title,omitempty"` // the tooltip, when not "name: status"
	// Risk is a config node's safety class ("side effect", "read-only", "idempotent", "safety
	// unknown") and Crash its crash behavior in a few words; empty on a run's graph. Cex marks a
	// node on a violated assertion's counterexample path.
	Risk  string `json:"risk,omitempty"`
	Crash string `json:"crash,omitempty"`
	Cex   bool   `json:"cex,omitempty"`
	// contains filtered or unexported fields
}

type Halt struct {
	Op          string    `json:"op"` // "tool" or "step"
	ID          string    `json:"id"` // the tool-use ID, or the step name ("node:<name>" for a plan node)
	ToolName    string    `json:"tool_name,omitempty"`
	Marker      string    `json:"marker"`
	AttemptedAt time.Time `json:"attempted_at,omitzero"`
	Ref         string    `json:"ref"` // the agent.HaltRef to resolve it with, as Go
}

type Head struct {
	Title string
	Icon  template.URL
}

type JournalSource struct{ J *agent.Journal }

type KindOption struct {
	Value, Label string
	On           bool
}

type ListFilter struct {
	State string `json:"state,omitempty"`
	Kind  string `json:"kind,omitempty"`
	Q     string `json:"q,omitempty"`
	Limit int    `json:"limit"`
}

type LiveUpdate struct {
	Changed bool `json:"changed"`
	// Live: the run has no end marker yet, so the page polls again; false once it has one.
	Live bool `json:"live"`
	// Cursor is the store sequence of the run's last record: the after of the next poll.
	Cursor    int64   `json:"cursor"`
	State     string  `json:"state,omitempty"`
	StateText string  `json:"state_text,omitempty"`
	Events    []Event `json:"events,omitempty"` // the rows of the records after the cursor given, only
}

type MerklePath struct {
	Seq   int    // the record's 1-based position in the journal
	Name  string // its journal name
	Size  int    // the journal length the signed root commits to
	Leaf  string // the record's leaf hash, hex
	Steps []MerkleStep
	Root  string // the signed root, hex
	// Climbed reports that hashing the path from the leaf gave Root, which the page checks again
	// here for the intermediate hashes it shows; the proof itself was verified by audit.
	Climbed  bool
	Alg      string
	SignedAt time.Time
}

type MerkleStep struct {
	Sibling string
	Left    bool // the sibling is the left child
	Node    string
}

type Options struct {
	Source Source
	// Flows are the declared flows runs are drawn against, by flow name.
	Flows map[string]*Flow
	// Provers check runs against audit artifacts; the first to return a verdict for a run wins.
	Provers []Prover
	// Config, when set, makes the handler show this flow definition instead of runs: the page at /
	// and its view as JSON at /config.json. Source is then not read.
	Config *Config
	// Diff, when set, makes the handler show a flow definition compared with an earlier one
	// instead of runs: the page at / and its view as JSON at /diff.json (see BuildDiff).
	Diff *Diff
}

type Proof struct {
	Source   string   `json:"source"` // "signed tree head" or "evidence package"
	OK       bool     `json:"ok"`
	Summary  string   `json:"summary"`
	Covers   int      `json:"covers"` // journal records the signed head commits to
	Problems []string `json:"problems,omitempty"`
	Items    []string `json:"items,omitempty"`
	// Approvals is the signature verdict on each m-of-n gate that journaled its tally, by
	// tool-use ID: audit.VerifyApprovals over the gate's evidence, with the approver keys given.
	// Nil without approver keys.
	Approvals map[string]ApprovalCheck `json:"approvals,omitempty"`

	// What the page draws from the proof; none of it is in the JSON view.
	Merkle   *MerklePath `json:"-"` // the proven record's path to the signed root
	SignedAt time.Time   `json:"-"` // when the signed head was signed
}

type Prover func(ctx context.Context, runID string, recs []agent.Record) *Proof

type RiskSummary struct {
	SideEffects int `json:"side_effects"`
	Gated       int `json:"gated"`
	Ungated     int `json:"ungated"`
	ReadOnly    int `json:"read_only"`
	Idempotent  int `json:"idempotent"`
	Unknown     int `json:"unknown"`
	// Line is the headline, as "3 side-effect steps, 2 gated, 1 ungated" ("steps known" when a
	// class is unknown).
	Line string `json:"line"`
	// UnknownLine says why some classes are unknown, empty when none is.
	UnknownLine string `json:"unknown_line,omitempty"`
}

type RunList struct {
	Filter ListFilter `json:"filter"`
	Rows   []RunRow   `json:"runs"`
	// Matched is how many runs the filter admits; Rows holds the first Filter.Limit of them.
	Matched int `json:"matched"`
	// Summarized is how many runs were read; Listed how many the source lists. They differ when
	// more than maxSummarized runs match the ID filter.
	Summarized int      `json:"summarized"`
	Listed     int      `json:"listed"`
	Kinds      []string `json:"kinds"` // the kinds of the runs read, for the kind filter
	// Counts are the runs of each state group the ID and kind filters admit, and All their sum:
	// the state filter's counts.
	Counts map[string]int `json:"counts"`
	All    int            `json:"all"`
	More   string         `json:"more,omitempty"` // the page with listPage more rows, when there are more
	Notes  []string       `json:"notes,omitempty"`
	Err    string         `json:"error,omitempty"`
}

type RunRow struct {
	ID        string `json:"run_id"`
	Kind      string `json:"kind"`  // agent.RunKind, or "" when the run has no run:start
	State     string `json:"state"` // the View state (see Build)
	StateText string `json:"state_text"`
	Group     string `json:"group"` // the state filter group
	Flow      string `json:"flow,omitempty"`
	Records   int    `json:"records"`
	// Started is when the run's first drive started, as its run:start records it
	// (agent.RunStart.Started). Zero for a run journaled by a version that recorded none.
	Started time.Time `json:"started,omitzero"`
}

type Source interface {
	Runs(ctx context.Context) ([]string, error)
	History(ctx context.Context, runID string) ([]agent.Record, error)
}

type Stat struct {
	Value, Label string
	Sub          string // one line under the label
	Class        string // good, bad, warn or empty
}

type StateOption struct {
	Value, Label string
	Count        int
	Link         string // the list with this option chosen, the other filters kept
	On           bool   // the option is the filter's
}

type Stores struct {
	SQLite   func(path string) (agent.Store, io.Closer, error)
	Postgres func(dsn string) (agent.Store, io.Closer, error)
	// YAML converts a YAML flow config to the JSON plan reads; nil means this build reads JSON
	// configs only.
	YAML func(data []byte) ([]byte, error)
}

type TimeBar struct {
	X, W  float64
	Label string
}

type Verdict struct {
	// Class styles the banner: good, bad, warn, wait or info.
	Class string
	// Word is the state in capitals ("VERIFIED"), Icon its glyph (a name of icons) and Line one
	// sentence of why.
	Word, Icon, Line string
	// Details are further lines the state calls out (a weakened gate's policy).
	Details []string
	Stats   []Stat
}

type View struct {
	RunID  string `json:"run_id"`
	Kind   string `json:"kind"` // agent.RunKind, or "" when the run has no run:start
	Input  string `json:"input,omitempty"`
	Flow   string `json:"flow,omitempty"`   // the flow name run:start records
	Digest string `json:"digest,omitempty"` // the topology digest flow:digest records
	// State is the agent.RunState, except "halted" for a started run with a live attempt marker
	// and no result (see Halts): a resume returns *agent.OutcomeUnknown, so it is not in progress.
	State     string `json:"state"`
	StateText string `json:"state_text"` // State as the page shows it ("halted: outcome unknown")
	Terminal  string `json:"terminal,omitempty"`
	Records   int    `json:"records"`

	Events    []Event      `json:"events"`
	Halts     []Halt       `json:"halts,omitempty"`
	Gates     []Gate       `json:"gates,omitempty"`
	Graph     *Graph       `json:"graph,omitempty"`
	Conform   *Conformance `json:"conformance,omitempty"`
	Proof     *Proof       `json:"proof,omitempty"`
	Notes     []string     `json:"notes,omitempty"` // what the page cannot show for this run, and why
	LastNode  string       `json:"last_node,omitempty"`
	FinalText string       `json:"final_text,omitempty"`

	// Live: the page follows the run (live mode): it was read from a store, not an export, and has
	// no end marker. Cursor is the store sequence (agent.Entry.Seq) of its last record.
	Live   bool  `json:"live,omitempty"`
	Cursor int64 `json:"cursor,omitempty"`

	// Verdict is the answer the page opens with (see runVerdict); it is not in the JSON view.
	Verdict Verdict `json:"-"`
}