board

type CopyResult struct {
	Text           string
	Picked         []Item
	Matched, Total int
	Worker         string
}

type ErrNoMessages struct{ Worker string }

type Event struct {
	Kind EventKind

	// Board is the board this message was DELIVERED TO, read from the subject
	// (design 028). It is never read from the payload: a post carries no board
	// id, which is what keeps founder gate 4 closed. A consumer holding several
	// boards routes on this field.
	Board string

	Post     *msg.MsgBoardPost
	Register *msg.MsgBoardRegister
}

type EventKind int

type Flow struct {
	Board  string      `json:"board"`
	Nodes  []FlowNode  `json:"nodes"`
	Edges  []FlowEdge  `json:"edges"`
	Events []FlowEvent `json:"events"`
	Stats  FlowStats   `json:"stats"`
}

type FlowDepCycle struct {
	Members []string // labels, in edge order: each is blocked by the next
	// Waiting is how many agents outside the ring wait on it.
	Waiting int
}

type FlowDepNode struct {
	ID       string
	Label    string
	Work     string
	Activity string
	Health   string
	// Waiting is how many distinct agents wait on this one, directly or
	// transitively.
	Waiting int
	// Also are this agent's OTHER blockers — it is drawn once under each, and
	// a reader must know that unblocking one parent is not enough.
	Also []string
	// Repeat marks a node already drawn higher in the same root's tree (a
	// diamond): its subtree is not drawn twice.
	Repeat   bool
	Children []FlowDepNode
}

type FlowDeps struct {
	// Roots are the blockers nobody blocks, most-waited-on first.
	Roots []FlowDepNode
	// Cycles are deadlocks: agents blocked on each other in a ring. No root
	// reaches them, so they are listed apart.
	Cycles []FlowDepCycle
	// Blocked is how many agents are blocked at all.
	Blocked int
}

type FlowEdge struct {
	Type        string `json:"type"`
	From        string `json:"from"`
	To          string `json:"to"`
	Count       int    `json:"count"`
	Answered    *int   `json:"answered,omitempty"`
	Undelivered *int   `json:"undelivered,omitempty"`
	Open        *int   `json:"open,omitempty"`
	LatencyMS   *int64 `json:"latency_ms,omitempty"`
	LastTS      int64  `json:"last_ts,omitempty"`
}

type FlowEvent struct {
	TS      int64  `json:"ts"`
	Type    string `json:"type"`
	From    string `json:"from"`
	To      string `json:"to"`
	Kind    string `json:"kind"`
	Thread  string `json:"thread"`
	CmdID   string `json:"cmd_id,omitempty"`
	Summary string `json:"summary"`
}

type FlowNode struct {
	ID     string `json:"id"`
	Kind   string `json:"kind"`
	Label  string `json:"label"`
	Role   string `json:"role,omitempty"`
	Parent string `json:"parent,omitempty"`
	Comm   string `json:"comm,omitempty"`
	Posts  int    `json:"posts"`

	// The fleet status ledger (design 054), from pane meta; omitted for a
	// pane in no watched fleet. Work is declared, Activity observed, Health
	// derived; BlockedBy are pane ids (or "human" / "ext:<what>").
	Work      string   `json:"work,omitempty"`
	Task      string   `json:"task,omitempty"`
	Activity  string   `json:"activity,omitempty"`
	Health    string   `json:"health,omitempty"`
	BlockedBy []string `json:"blocked_by,omitempty"`

	// The goal executor's verdict (design 055), from pane meta: the primary
	// condition (progressing, blocker, stressed, strayed, …), declared
	// progress and ETA (unix millis). Omitted with no executor, so a board
	// without one renders byte-identically to before.
	GoalState string `json:"goal_state,omitempty"`
	GoalPct   *int   `json:"goal_pct,omitempty"`
	GoalEta   int64  `json:"goal_eta,omitempty"`
}

type FlowPane struct {
	ID   string            `json:"id"`
	Name string            `json:"name"`
	Meta map[string]string `json:"meta"`
}

type FlowStats struct {
	Panes       int `json:"panes"`
	Prompts     int `json:"prompts"`
	Answered    int `json:"answered"`
	Undelivered int `json:"undelivered"`
	Open        int `json:"open"`
	Status      int `json:"status"`
	// Blocked is how many pane nodes declare blocked (design 054).
	Blocked int `json:"blocked,omitempty"`
}

type HTMLPage struct {
	Board   string
	Worker  string
	N       int    // the count asked for; 0 = all
	Picked  []Item // oldest first
	Matched int    // the worker's items before N
	Total   int    // every item on the board window
	Now     time.Time
	Loc     *time.Location // nil = time.Local
}

type InboxItem struct {
	CmdID      string `json:"cmd_id"`
	ThreadID   string `json:"thread_id"`
	From       string `json:"from"`         // sender persona, display only
	FromPaneID string `json:"from_pane_id"` // sender identity
	TS         int64  `json:"ts"`
	Text       string `json:"text"`
	File       string `json:"file,omitempty"`

	// Answered is true once the reader acked the command or posted anything
	// on its thread. A reply is an answer: design 050 §5.4 makes
	// `fleetctl report` the ack, and a report is a post on that thread.
	Answered bool  `json:"answered"`
	AckTS    int64 `json:"ack_ts,omitempty"` // the first answer's time
}

type Item struct {
	Post      *msg.MsgBoardPost // a sanitised copy; never the store's own pointer
	ThreadKey string
	Reply     bool
}

type ItemArgs struct {
	Worker string
	N      int
	Format string // output only: html | pdf
	Board  string // --board / --fleet; "" = the caller's own board
	Out    string // output only: --out <dir>
	NoOpen bool   // output only: --no-open
}

type KV interface {
	Put(key string, value []byte) (uint64, error)
	Get(key string) (nats.KeyValueEntry, error)
	Keys(opts ...nats.WatchOpt) ([]string, error)
}

type LivePanesFunc func() (map[string]bool, error)

type OutputRequest struct {
	Page   HTMLPage
	Format string // html | pdf
	Dir    string // "" = DefaultOutputDir()
	Open   bool
}

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

type PersistenceFor func(board string) *Persistence

type Query struct {
	// Since keeps only threads with activity at or after this unix-millis
	// instant. It is compared against the poster's clock (MsgBoardPost.TS), so
	// it inherits that field's honest limit: arrival order, not causal order.
	Since int64 `json:"since,omitempty"`

	// Limit bounds how many THREADS come back, keeping the most recent — this
	// is `tail`, so the end of the board is what you want. Zero means unbounded.
	//
	// Threads, not posts, because the store's own eviction is by whole thread
	// (store.go evictLocked): splitting a thread to hit a post count would
	// manufacture exactly the orphan pile both bounds exist to avoid.
	Limit int `json:"limit,omitempty"`
}

type QueryReply struct {
	Threads []Thread      `json:"threads"`
	Roster  []RosterEntry `json:"roster"`
	Stats   Stats         `json:"stats"`

	// Filtered counts threads dropped by Since; Withheld counts threads dropped
	// by Limit. Both are here so a truncated answer can say so out loud.
	Filtered int `json:"filtered"`
	Withheld int `json:"withheld"`

	// RosterReconciled reports whether Roster was checked against the panes
	// that actually exist, or is being served as recorded.
	//
	// False is not an error and does not invalidate the answer — it means the
	// recorder could not confirm who is alive, so the roster may still contain
	// panes that have closed (F-26). It is here because the alternative to
	// disclosing it is a caller that cannot tell an authoritative roster from a
	// best-effort one, which is the same shape of defect as the ghost itself:
	// something that looks certain and is not.
	RosterReconciled bool `json:"roster_reconciled"`

	// Err carries a refusal from the recorder. A recorder that cannot answer
	// says so; it never answers with an empty board, for the reason at the top
	// of this file. Ask turns a non-empty Err into an error.
	Err string `json:"err,omitempty"`
}

type RosterEntry struct {
	PaneID  string `json:"pane_id"`
	Persona string `json:"persona"`
	TS      int64  `json:"ts"`
}

type Stats struct {
	Threads     int    `json:"threads"`     // total threads, provisional included
	Provisional int    `json:"provisional"` // threads still missing their root
	Posts       int    `json:"posts"`       // roots + replies currently held
	Duplicates  uint64 `json:"duplicates"`
	Evicted     uint64 `json:"evicted"`
	// UnknownVersion counts posts whose V is not BoardSchemaVersion. They are
	// KEPT, not dropped — a board that discards a message because it was
	// written by a newer agent is worse than one that renders it plainly.
	UnknownVersion uint64 `json:"unknown_version"`
}

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

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

type TeamRow struct {
	ID        string
	Label     string
	Role      string
	Work      string
	Activity  string
	Health    string
	Task      string
	BlockedBy []string // labels, not ids
	LastPost  int64    // unix millis of the member's newest post; 0 = none

	// The goal executor's verdict (design 055); empty with no executor.
	GoalState string
	GoalPct   *int
	GoalEta   int64
}

type Thread struct {
	// Key addresses the thread. For a normal thread it is the poster-minted
	// "<pane-uuid>/<n>" that replies carry. For a standalone post (one that
	// arrived with no ThreadID and can therefore never be replied to) it is an
	// internal key that no agent can mint — see standaloneKey.
	Key string `json:"key"`

	// Root is nil while the thread is Provisional.
	Root    *msg.MsgBoardPost   `json:"root"`
	Replies []*msg.MsgBoardPost `json:"replies"`

	// Provisional marks a thread whose replies arrived before their root.
	// This is expected, not an error: thread ids are minted agent-side with no
	// round trip (design 025 §4.3), so ordering between two panes is not
	// guaranteed. The view renders a provisional thread as a root; when the
	// real root lands the thread stops being provisional and re-positions
	// itself to where the ROOT's arrival puts it.
	Provisional bool `json:"provisional"`
}

type View string