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:"-"`
	// Identity is what an audit found of each certificate-bound approver's decision on the gate (by
	// approver id), for the identity block: only a result here can mark a decision disputed, and only
	// a result for every one of them can make the block audited (the only green). Empty without one.
	Identity map[string]IdentityAudit `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
	// Identity is the identity of a certificate-bound approver's counted decision (see
	// IdentityCard), nil for a bare-key approver and for a decision no identity record shows.
	// Binding says which kind of approver this is on a gate with a certificate-bound approver:
	// "certificate-bound" or "bare key (no identity)", empty on a gate of bare keys. IdentityNote is
	// what to read instead of a signature line for a certificate-bound approver whose decision has no
	// identity card, and IdentityBad that it is a problem.
	Identity     *IdentityCard
	Binding      string
	IdentityNote string
	IdentityBad  bool
}

type AttentionGate struct {
	Single     bool     `json:"single,omitempty"` // a one-decision gate (agent.Approve)
	Need       int      `json:"need,omitempty"`
	Of         int      `json:"of,omitempty"`
	Approvers  []string `json:"approvers,omitempty"`
	ApprovedBy []string `json:"approved_by,omitempty"`
	DeniedBy   []string `json:"denied_by,omitempty"`
	Pending    []string `json:"pending,omitempty"`
	Reapproval bool     `json:"reapproval,omitempty"`
	Status     string   `json:"status"` // the run page's gate status
	// ExpiresAt is the gate's recorded deadline, empty for a gate with none. Due says where it stands
	// on the list's clock (Gate.Due), DueSoon that it falls within dueSoonWindow (or has passed), and
	// Overdue that it has passed with no expiry recorded: the gate refuses decisions, and the run
	// records the expiry when it is next driven.
	ExpiresAt string `json:"expires_at,omitempty"`
	Due       string `json:"due,omitempty"`
	DueSoon   bool   `json:"due_soon,omitempty"`
	Overdue   bool   `json:"overdue,omitempty"`
	// Identity is the gate's approver identity, for a gate with a certificate-bound approver: what it
	// is paused for (paused: identity status unknown, ...) and the identity of each counted decision.
	Identity *GateIdentity `json:"identity,omitempty"`
}

type AttentionItem struct {
	Kind     string `json:"kind"`
	KindText string `json:"kind_text"`
	RunID    string `json:"run_id"`
	// Call is the tool-use ID of the call (or the node key, or the operation's ID); Tool its name.
	Call string `json:"call,omitempty"`
	Tool string `json:"tool,omitempty"`
	// Since is when it began needing a person, by the journal's (or the trail's) clock: the gate's
	// ask time, the halted attempt's time, the abort's time, or when recovery began failing. Zero
	// when the journal does not say; such items come last.
	Since time.Time `json:"since,omitzero"`
	// Waiting is Since to the list's Now, as durText phrases it.
	Waiting string `json:"waiting,omitempty"`
	Summary string `json:"summary"`

	Gate *AttentionGate `json:"gate,omitempty"` // for an approval
	Halt *Halt          `json:"halt,omitempty"` // for a halt: its HaltRef is the ResolveHalt hint
	// Reason is why a run aborted, or the class of cause a recovery keeps failing with.
	Reason string `json:"reason,omitempty"`
	// Command is the bide approve command that records a decision on the call, when the viewer
	// knows how to write one (Options.ApproveCommand). Empty otherwise.
	Command string `json:"command,omitempty"`
	// NoCommand says why an approval has none although the viewer writes them: an id that cannot be
	// shown or pasted safely (approveline.ErrUnsafe).
	NoCommand string `json:"no_command,omitempty"`
	// CommandNote qualifies Command on a gate with certificate-bound approvers: the command signs a bare
	// key, so it is for the bare-key approvers only, and a bare-key decision does not count for the
	// certificate-bound ones. CertOnly: every pending approver is certificate-bound, so no command is shown.
	CommandNote string `json:"command_note,omitempty"`
	CertOnly    bool   `json:"cert_only,omitempty"`
	// CertCommand is the bide approve -cert command for a gate with a pending certificate-bound approver
	// (Options.ApproveCertCommand). When every pending approver is certificate-bound (CertOnly) it is the
	// only command (Command is empty): a bare-key decision does not count for them.
	CertCommand string `json:"cert_command,omitempty"`
	// Notify says whether the item was notified and acknowledged; nil without the notify trail.
	Notify *NotifyStatus `json:"notify,omitempty"`
}

type AttentionList struct {
	// Status is what the headline says, for a script: attention, clear or unknown (see Coverage).
	Status string          `json:"status"`
	Items  []AttentionItem `json:"items"`
	// Coverage says what was read; the headline is clear only when it is complete.
	Coverage
	// Live: the source is a store the runs are still written to, so the page refreshes itself.
	Live bool `json:"live,omitempty"`
	// Now is the time the waits are measured to.
	Now time.Time `json:"now"`
	// Runs is how many runs were read.
	Runs  int      `json:"runs"`
	Notes []string `json:"notes,omitempty"`
}

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). Removing or
	// lengthening a gate's timeout is a weakening (a run waits longer, and late decisions count), and
	// adding or shortening one a strengthening (the gate fails closed sooner). Empty when the
	// gate did not change. A removed node's gate counts as removed.
	Gate string `json:"gate,omitempty"`
	// Weakening says what a weakened change weakened: "gate" (an approval policy: the gate was
	// removed, loosened, or lost its exclusion of the requester or its deadline), "path" (a node
	// newly reachable without passing an approval gate: one every path reached through a gate
	// before, whatever its safety, or a new or newly wired-in effect), "safety" (a node's safety
	// lowered toward read-only), "block" (a block changed on an ungated effect node, without the
	// Registry), "condition" (a Switch condition changed beside an ungated effect) or "assertion"
	// (an assert line removed or loosened, or kept and no longer holding). Empty for a change that
	// weakened nothing.
	Weakening string `json:"weakening,omitempty"`
	// contains filtered or unexported fields
}

type Config struct {
	Name     string
	Data     []byte
	Registry *plan.Registry
	// Description is what the program registered, read from a file (bide check -blocks). It is only
	// as good as the file: the page and the text say so wherever they report a typed result.
	Description *plan.RegistryDescription
	// DescriptionSHA256 is the SHA-256 of the description file's bytes (ReadDescriptionFile), shown
	// where a result rests on the file, so a reviewer can tell which file was used.
	DescriptionSHA256 string
	// AllowUnusedBlocks makes a registered block the config does not use no problem
	// (plan.AllowUnusedBlocks). bide check -blocks sets it: a description is of the whole program, and
	// a flow config uses some of its blocks.
	AllowUnusedBlocks bool
	// 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"`
	// Source is what the typed result rests on (SourceRegistry, SourceDescription), empty when
	// structural.
	Source string `json:"source,omitempty"`
	// DescriptionSHA256 is the SHA-256 of the description file the typed result rests on, when it
	// rests on one read from a file.
	DescriptionSHA256 string               `json:"description_sha256,omitempty"`
	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 Coverage struct {
	// Listable: the source can enumerate its runs. A store without an agent.Lister cannot, and a page
	// over it knows nothing about its runs.
	Listable bool `json:"listable"`
	// Truncated is how many listed runs were not read because a load reads at most maxSummarized.
	Truncated int `json:"truncated,omitempty"`
	// Unread is how many runs could not be read (their listing or their journal failed); Err says
	// the class of the first failure, never the store's own text.
	Unread int    `json:"unread,omitempty"`
	Err    string `json:"error,omitempty"`
	// Empty is how many listed runs hold no records.
	Empty int `json:"empty,omitempty"`
	// Trail: the notification trail was given (Options.Events). TrailUnread is how many runs' trails
	// could not be read.
	Trail       bool `json:"notify_trail"`
	TrailUnread int  `json:"trail_unread,omitempty"`
	// Filtered: the page shows a filter's runs only, so its headline cannot speak for the store.
	Filtered bool `json:"filtered,omitempty"`
}

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"`
	// Note says why a recorded decision did not count, when the journal alone would make it look
	// as if it should have: agent.ReasonAfterExpiry for one written after the gate's expiry.
	Note string `json:"note,omitempty"`
	// contains filtered or unexported fields
}

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"`
	// Basis is what the typed result rests on: SourceRegistry when both sides were checked against
	// a Registry, SourceDescription when a side was checked against a description file only (what
	// that side's blocks declare is then as the file says, not checked against the program), empty
	// when structural.
	Basis string `json:"basis,omitempty"`
	// OldBasis and NewBasis say how each side was checked: SourceRegistry, SourceDescription, or
	// "structural".
	OldBasis string `json:"old_basis"`
	NewBasis string `json:"new_basis"`
	// OldFile and NewFile are the SHA-256 of the description file of each side, when it has one.
	OldFile string `json:"old_file,omitempty"`
	NewFile string `json:"new_file,omitempty"`
	// Fallback is set when a side checked against a Registry or a description had errors, so the typed
	// comparison had nothing sound to read: the diff was made structurally, as it is without them,
	// which never reads a gate as stronger than it can tell. It says so in words and the diff is not
	// certified: -fail-on-weaken fails on it, and the verdict is never good.
	Fallback  string   `json:"fallback,omitempty"`
	OldDigest string   `json:"old_digest,omitempty"`
	NewDigest string   `json:"new_digest,omitempty"`
	Changes   []Change `json:"changes"`
	// Cannot, when set, says the sides could not be compared and why (a file with errors has no digest
	// to compare); nothing is then claimed about them, and Changes is empty.
	Cannot string `json:"cannot,omitempty"`
	// DigestNote is set when the digests differ and no change explains it: the digest covers more than
	// the diff itemises (a type spelled with another package path).
	DigestNote string `json:"digest_note,omitempty"`
	// Weakened and Strengthened name each change that made the flow's approval checks weaker or
	// stronger, with how: "charge: approval 2 of 3 -> 1 of 3" for a gate, "receipt: reachable
	// without an approval gate (validate -> receipt), not before; its safety is side effect" for a
	// node newly reachable around a gate, "assertion removed: every path to charge passes approval >= 2 of 3" for an assert line.
	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:"-"`
	// contains filtered or unexported fields
}

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"`
	// RecordedAt is the record's own recorded_at, verbatim, on the records that carry one: the
	// claim of the process that wrote it, informational (see agent.Record.RecordedAt).
	RecordedAt string `json:"recorded_at,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, an attempt marker, or a record's recorded_at), 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"`
	// ReapprovalSoD: the re-ask is because the recorded tally passed without excluding the requester
	// and the gate's policy now excludes it (agent.PendingSoDReapproval); Reapproval is set too.
	ReapprovalSoD bool `json:"reapproval_sod,omitempty"`
	// Cards is each approver as the page shows them (see ApproverCard); not in the JSON view.
	Cards []ApproverCard `json:"-"`
	// Why says why the call needs this gate beyond its tool's own: for the escalation instance of a tainted
	// call, the untrusted content its turn had read; for a gate a cap rule holds, the rule and this call's
	// figures as of the ask. It is the engine's gate-reason record, the application's claim, and no gate reads it.
	Why []gatereason.Reason `json:"why,omitempty"`
	// ExcludePrincipal: the gate never counts the run's requester (agent.ApprovalPolicy.ExcludePrincipal);
	// Requesters are the requesters (the run's principal and those of the runs above it), and Excluded
	// the approvers who fill no seat (the tally's, or before
	// it, the approver ids equal to the requester ignoring case).
	ExcludePrincipal bool     `json:"exclude_principal,omitempty"`
	Requesters       []string `json:"requesters,omitempty"`
	Excluded         []string `json:"excluded,omitempty"`
	// ExpiresAt is the gate's recorded deadline (agent.ApprovalDeadline), in the journal's timestamp
	// form, and Timeout the timeout it was opened with ("24h"); both empty for a gate with none.
	ExpiresAt string `json:"expires_at,omitempty"`
	Timeout   string `json:"timeout,omitempty"`
	// Expired: the gate's recorded outcome is its expiry (agent.GateStanding.Expired): the call never
	// ran, and a decision is not counted.
	Expired bool `json:"expired,omitempty"`
	// Overdue: the gate still waits and the viewer's clock is past ExpiresAt. Only a drive of the run
	// records the expiry; until then the gate refuses decisions (agent.ErrApprovalExpired) and the
	// run is not finished.
	Overdue bool `json:"overdue,omitempty"`
	// Due says where the deadline stands on the viewer's clock ("due in 40m 00s (... UTC)"); empty
	// for a gate with no deadline.
	Due string `json:"due,omitempty"`
	// Identity is the gate's approver identity, for a gate with a certificate-bound approver; nil for
	// a gate of bare keys (see GateIdentity).
	Identity *GateIdentity `json:"identity,omitempty"`
	// Held: the call is counted but not run, held before execution by the identity status re-check
	// (agent.ExecHold); the run needs a person although the gate is no longer waiting for decisions.
	Held bool `json:"held,omitempty"`
}

type GateIdentity struct {
	Bound bool `json:"bound"`
	// Approvers are the approver ids that are certificate-bound, in policy order; the other approvers
	// of the gate are bare keys, whose decisions carry no identity.
	Approvers    []string `json:"approvers,omitempty"`
	PolicyDigest string   `json:"policy_digest,omitempty"`
	// Phase is the pause note's Pause (agent.Pause*), PhaseText the words for it ("paused: identity
	// status unknown"), empty when the gate is simply waiting for decisions, and Detail the note's
	// sentence.
	Phase     string `json:"phase,omitempty"`
	PhaseText string `json:"phase_text,omitempty"`
	Detail    string `json:"detail,omitempty"`
	// Unchecked are certificate-bound approvers who decided on a gate that has not counted yet: the
	// decision is recorded, and nothing here says it counts.
	Unchecked []string       `json:"unchecked,omitempty"`
	Cards     []IdentityCard `json:"cards,omitempty"`
	Hold      *IdentityHold  `json:"hold,omitempty"`
	// Paused: the newest phase note says exec-hold but the journal holds no hold record, which is the
	// gate waiting for current status before it runs the call (nothing authoritative is written; the same
	// approvals run once status is fresh), not a revoked or no-longer-verifying decision.
	Paused bool `json:"paused,omitempty"`

	// Generation is the gate's newest count (0 is the first); Reasked says a call was held before
	// execution and the gate asked again, so earlier counts are history.
	Generation int  `json:"generation,omitempty"`
	Reasked    bool `json:"reasked,omitempty"`
	// Problems are why the identity data cannot be relied on, in words.
	Problems []string `json:"problems,omitempty"`
	// Class is audited, final, prov, bad or wait (see the type's comment); Line is one line saying it.
	Class string `json:"class"`
	Line  string `json:"line"`
	// contains filtered or unexported fields
}

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
	// Refresh, when positive, makes the page reload itself after that many seconds (a live page
	// that needs no script).
	Refresh int
}

type HeldCounts struct {
	// Held runs are held by the stop for certain; May runs may be (an agent stop: the journal does not record
	// the agent identity that drives a run). Read is how many unfinished runs were read, Unread how many could
	// not be, and Truncated says more than maxHeldRead were listed and only the first were read.
	Held, May, Read, Unread int
	Truncated               bool
	// ListErr is set when the runs could not be listed, so nothing was counted. Incomplete is set when the count
	// was cut off (its context ended) after counting some: the counts are then lower bounds.
	ListErr    string
	Incomplete bool
}

type IdentityAudit struct {
	OK           bool
	Disputed     bool
	Detail       string
	TallyDigest  string
	PolicyDigest string
	CheckedAt    string
}

type IdentityCard struct {
	Approver   string `json:"approver"`
	Identifier string `json:"identifier"`
	// DisplayName is the certificate's subject common name, read from the decision record when its
	// leaf is the one the identity record names. It is the CA's label, not part of the identity.
	DisplayName string `json:"display_name,omitempty"`
	Tier        string `json:"tier"`
	// TierText names the tier in words; Class is audited, final, prov or bad.
	TierText  string `json:"tier_text"`
	Class     string `json:"class"`
	BasisKind string `json:"basis_kind,omitempty"`
	Basis     string `json:"basis,omitempty"`
	// Audited: an audit the viewer was given re-checked this decision and agrees (green only then);
	// StatusAge is S's age on the viewer's clock (MarkDeadlines).
	Audited   bool   `json:"audited,omitempty"`
	StatusAge string `json:"status_age,omitempty"`

	// StatusTime is S, the time of the revocation status the count rests on; AnchoredAt is when the
	// decision became provable and TimeSource what that time rests on; Window is W'. All are display
	// text in UTC.
	StatusTime string   `json:"status_time,omitempty"`
	AnchoredAt string   `json:"anchored_at,omitempty"`
	TimeSource string   `json:"time_source,omitempty"`
	Window     string   `json:"window,omitempty"`
	Leaf       string   `json:"leaf,omitempty"` // the first 16 hex digits of the leaf certificate's hash
	Warnings   []string `json:"warnings,omitempty"`
	// Disputed is set only from an audit result (ApprovalCheck.Identity), never from the journal: an audit found newer status showing a revocation (keyCompromise) effective at or
	// before the decision became provable, which voids the count back to the certificate's notBefore.
	Disputed bool `json:"disputed,omitempty"`
	// contains filtered or unexported fields
}

type IdentityHold struct {
	Reason     string   `json:"reason"`
	Detail     string   `json:"detail,omitempty"`
	Approvers  []string `json:"approvers,omitempty"`
	CheckedAt  string   `json:"checked_at,omitempty"`
	StatusTime string   `json:"status_time,omitempty"`
	Serial     string   `json:"serial,omitempty"`
}

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 Listable interface{ CanList() bool }

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 NotifyStatus struct {
	State string `json:"state"`
	Text  string `json:"text"`
	// Deadline is when the notification is overdue if unacknowledged; Overdue says it is.
	Deadline time.Time `json:"deadline,omitzero"`
	Overdue  bool      `json:"overdue,omitempty"`
}

type OpenedStore struct {
	Source  Source
	Journal *agent.Journal
	Store   agent.Store
	Closer  io.Closer
}

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
	// Events, when set, is the notification trail's store (the audit.EventStore beside the
	// journal): the Needs attention list then says for each item whether it was notified and
	// acknowledged, and lists a run whose recovery keeps failing.
	Events audit.EventStore
	// ApproveCommand, when set, writes the bide approve command line that records a decision on a
	// call of a run (single: a one-decision gate). The Needs attention list shows it with each
	// pending approval; without it the list says it has none.
	ApproveCommand func(runID, toolUseID string, single bool) (string, error)
	// ApproveCertCommand, when set, writes the bide approve -cert command line for a gate with a
	// certificate-bound approver: a bare-key decision does not count for that approver. The Needs
	// attention list shows it beside (a gate with bare-key approvers too) or instead of (all approvers
	// certificate-bound) ApproveCommand's line.
	ApproveCertCommand func(runID, toolUseID string) (string, error)
	// Stops, when set, is the kill switch's control run of the journal: every page then opens with a banner
	// while a stop is in force (or the control run cannot be judged, or holds rejected records), a run's page
	// and the run list say which runs a stop holds, and /stops.json serves the same state.
	Stops *StopFeed
	// Themes are custom themes (see the theme package) the pages offer beside the shipped light, dark
	// and high-contrast; DefaultTheme, when not empty, names the one a reader starts in. Handler
	// panics on a DefaultTheme that names no theme and on two themes with one name: they are a host
	// program's mistake, and bide view checks both before it calls Handler.
	Themes       []*theme.Theme
	DefaultTheme string
	// ThemeLock, when not empty, names the one theme the pages have: no switch, no remembered
	// choice (the system's request for more contrast or forced colors still wins). Handler panics
	// on a ThemeLock that names no theme or that differs from a DefaultTheme.
	ThemeLock string
	// Now is the clock the Needs attention list measures waits by; nil is time.Now.
	Now func() time.Time
	// contains filtered or unexported fields
}

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"`
	// Recovering is how many of the runs counted have an open recovery failure episode in the
	// notification trail and have not ended.
	Recovering int      `json:"recovering,omitempty"`
	More       string   `json:"more,omitempty"` // the page with listPage more rows, when there are more
	Notes      []string `json:"notes,omitempty"`
	// Status is what the headline says, for a script: attention, clear or unknown. Coverage says what
	// was read; the headline is ALL CLEAR only when it is complete (see Coverage.nothingFound).
	Status string `json:"status"`
	Coverage
}

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"`
	// Held are the active kill switch stops that hold, or may hold, the run (see heldBy).
	Held []StopHold `json:"held_by,omitempty"`
	// 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
	Link         string // where the number links to, if anywhere
	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 StopBanner struct {
	// Mode is the control's mode, basic or audited. Verified says whether signatures were checked.
	Mode     string `json:"mode"`
	Verified bool   `json:"signatures_verified"`
	// Active are the stops in force (the first maxBannerStops), MoreActive how many more there are.
	Active     []StopLine `json:"active"`
	MoreActive int        `json:"more_active,omitempty"`
	// Unknowable says why the stops cannot be judged (a basic viewer on a signed deployment, a policy chain it
	// cannot walk): the engine holds side-effect calls a stop could cover while that is so.
	Unknowable string `json:"unknowable,omitempty"`
	// Unverified counts signed records a viewer with no stop policy cannot check.
	Unverified int `json:"unverified,omitempty"`
	// Rejected are records in the control run that have no effect (a forged record, a signer the policy does
	// not enrol); RejectedTotal counts them all.
	Rejected      []string `json:"rejected,omitempty"`
	RejectedTotal int      `json:"rejected_total,omitempty"`
	// ReadErr says the control run could not be read, by class: the banner never claims "no stop" then.
	ReadErr string `json:"read_error,omitempty"`
	// PlainIgnored counts plain (unsigned) stops in force for basic processes that this audited view ignores:
	// a deployment that has not moved to audited mode, or a process still configured basic, is stopped while
	// the audited processes are not.
	PlainIgnored int `json:"plain_ignored,omitempty"`
	// ReadAt is when the control run was read (the banner is served again for a couple of seconds).
	ReadAt string `json:"read_at,omitempty"`
}

type StopFeed struct {
	Control *agent.StopControl
	// Plain, set with an audited Control, is a basic control over the same journal: the stops it sees that
	// are not signed are stops a basic process enforces and an audited one ignores, which the banner says
	// (a deployment that has not upgraded, read by a viewer given the stop policy).
	Plain *agent.StopControl
	// Verified is true when the control checks signatures: the viewer was given the deployment's stop policy.
	Verified bool
}

type StopHold struct {
	Stop  string `json:"stop"` // the stop's ID
	Scope string `json:"scope"`
	// May is true when the journal cannot say: an agent stop covers the runs of an agent identity, which the
	// journal does not record, so any unfinished run may be one of them.
	May bool `json:"may,omitempty"`
}

type StopLine struct {
	ID           string `json:"id"`
	Scope        string `json:"scope"`
	Reason       string `json:"reason"`
	By           string `json:"by"`
	Host         string `json:"host,omitempty"`
	At           string `json:"at"`
	Age          string `json:"age"`
	Signed       bool   `json:"signed"`
	Compensation string `json:"compensation"`
	LiftsHeld    int    `json:"lifts_held"`
	LiftsNeeded  int    `json:"lifts_needed"`
}

type StoreFlags struct {
	DB          string
	Postgres    string
	PostgresEnv string
	Journals    []string
}

type Stores struct {
	SQLite   func(path string) (agent.Store, io.Closer, error)
	Postgres func(dsn string) (agent.Store, io.Closer, error)
	// Events returns the notification trail's store beside a store the opener returned, or nil when
	// the store keeps none. A nil Events means the Needs attention list says nothing about
	// notification.
	Events func(agent.Store) audit.EventStore
	// 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 ThemeSet struct {
	Extra   []*theme.Theme
	Default string
	Lock    string
}

type TimeBar struct {
	X, W  float64
	Label string
}

type TooLargeError struct {
	// contains filtered or unexported fields
}

type TopologyDiff struct {
	// Old and New are the sides; Old is the run's.
	Old, New plan.ConfigReport
	// OldName and NewName label them.
	OldName, NewName string
	// Typed says both sides know their kinds, types and gates: the file was checked against a
	// plan.Registry (or a description of one). Without it the comparison is structural: flow name,
	// entry, node names and blocks, edges, Switch arms and their order. A journaled gate is the
	// resolved policy (a block's own Go gate, a one-decision gate), which a structural file cannot
	// show, so gates, and every verdict about them, are compared only when Typed.
	Typed bool
	// Basis is what the file's typed result rests on (SourceRegistry or SourceDescription), empty
	// when structural.
	Basis string
}

type UnfinishedLister interface {
	Unfinished(ctx context.Context) ([]string, error)
}

type Verdict struct {
	// Class styles the banner: good, bad, warn, wait or info.
	Class string
	// Status is what a script reads of the page (StatusAttention, StatusClear or StatusUnknown); the
	// JSON of the run list and the Needs attention list carry it.
	Status 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
	// Link, with LinkText, is a link the banner carries (the run list's to the Needs attention list).
	Link, LinkText string
}

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"`
	// EndedAt is when the run's first end marker was written, by the clock of the process that wrote
	// it (agent.RunStatus.EndedAt); empty when the run has not ended or the marker records no time.
	EndedAt string `json:"ended_at,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
	// Held are the active kill switch stops that hold, or may hold, the run at its next drive (see heldBy);
	// empty when no stop applies or the viewer reads no control run.
	Held      []StopHold `json:"held_by,omitempty"`
	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:"-"`
	// contains filtered or unexported fields
}