worker

type ActionIntent struct {
	ID      string          `json:"id"`
	Intent  json.RawMessage `json:"intent"`
	Receipt *ActionReceipt  `json:"receipt,omitempty"`
}

type ActionReceipt struct {
	ActionID  string `json:"action_id"`
	ReceiptID string `json:"receipt_id"`
	Status    string `json:"status,omitempty"`
}

type AdapterResult struct {
	RunID          string         `json:"run_id"`
	Status         ResultStatus   `json:"status"`
	Summary        string         `json:"summary,omitempty"`
	WakeAt         *time.Time     `json:"wake_at,omitempty"`
	EventID        string         `json:"event_id,omitempty"`
	DecisionPrompt string         `json:"decision_prompt,omitempty"`
	ReceiptID      string         `json:"receipt_id,omitempty"`
	ActionReceipt  *ActionReceipt `json:"action_receipt,omitempty"`
	ActionStatus   string         `json:"action_status,omitempty"`
	ReviewNote     string         `json:"review_note,omitempty"`
}

type CheckReport struct {
	Report
	Tasks []StatusItem `json:"tasks"`
}

type Client interface {
	GetBoard(context.Context, string, bool) (json.RawMessage, error)
	GetCard(context.Context, string) (json.RawMessage, error)
	GetCardMarkdown(context.Context, string) (string, error)
	GetCardMetadata(context.Context, string) (api.CardMetadata, error)
	UpdateCardMetadata(context.Context, string, api.MetadataPatch) (json.RawMessage, error)
	CreateCard(context.Context, string, string, string, string) (json.RawMessage, error)
	AddCommentOnce(context.Context, string, string) (json.RawMessage, error)
}

type Clock interface{ Now() time.Time }

type Config struct {
	BoardID       string
	WorkerID      string
	PollInterval  time.Duration
	LeaseDuration time.Duration
	RunTimeout    time.Duration
	MaxConcurrent int
	ArtifactDir   string
	OutputLimit   int
	PacketLimit   int
	NoticeTimeout time.Duration
	Runner        Runner
	Notifier      Notifier
	// Observer is optional and is run only by Serve's shared board-wide pass.
	// Its proposals remain non-delegated and are never passed to Runner.
	Observer               Observer
	ObserverRegistryCardID string
	ObserverListID         string
	ObserverTimeout        time.Duration
}

type Decision struct {
	Prompt string          `json:"prompt,omitempty"`
	ID     string          `json:"id,omitempty"`
	Value  json.RawMessage `json:"value,omitempty"`
}

type Delegation struct {
	Delegated     bool            `json:"delegated"`
	Authorization json.RawMessage `json:"authorization,omitempty"`
}

type Enrollment struct {
	Goal               string
	CompletionCriteria string
	Authorization      json.RawMessage
	Sources            []SourceRef
	Action             *ActionIntent
}

type IngestReport struct {
	Received   int      `json:"received"`
	Created    []string `json:"created"`
	Duplicates int      `json:"duplicates"`
}

type Journal struct {
	ID        string `json:"id"`
	State     string `json:"state"`
	CommentID string `json:"comment_id,omitempty"`
}

type LeaseTicker interface {
	C() <-chan time.Time
	Stop()
}

type Notice struct {
	ID    string `json:"id"`
	State string `json:"state"`
	// QueueReceiptID proves only that a relay accepted the notice for later
	// display. It is intentionally distinct from a user-delivery receipt.
	QueueReceiptID string `json:"queue_receipt_id,omitempty"`
	ReceiptID      string `json:"receipt_id,omitempty"`
}

type NoticePacket struct {
	Version  int    `json:"version"`
	NoticeID string `json:"notice_id"`
	CardID   string `json:"card_id"`
	RunID    string `json:"run_id"`
	// DecisionID is sent only with a waiting-user outcome, allowing a host
	// relay to route the displayed question and answer exactly.
	DecisionID string `json:"decision_id,omitempty"`
	Message    string `json:"message"`
}

type NoticeReceipt struct {
	NoticeID  string `json:"notice_id"`
	ReceiptID string `json:"receipt_id"`
	// An omitted state retains synchronous-adapter compatibility as delivered.
	// queued means the adapter accepted transport, not that a user saw it.
	DeliveryState string `json:"delivery_state,omitempty"`
}

type Notifier interface {
	Deliver(context.Context, NoticePacket) (NoticeReceipt, error)
}

type Observer interface {
	Observe(context.Context) ([]Suggestion, error)
}

type Outcome struct {
	RunID      string `json:"run_id"`
	Kind       string `json:"kind"`
	Summary    string `json:"summary,omitempty"`
	ReceiptID  string `json:"receipt_id,omitempty"`
	ReviewNote string `json:"review_note,omitempty"`
}

type Packet struct {
	Version            int             `json:"version"`
	CardID             string          `json:"card_id"`
	BoardID            string          `json:"board_id"`
	RunID              string          `json:"run_id"`
	Goal               string          `json:"goal"`
	CompletionCriteria string          `json:"completion_criteria"`
	Authorization      json.RawMessage `json:"authorization"`
	CardMarkdown       string          `json:"card_markdown"`
	Sources            []SourceRef     `json:"sources,omitempty"`
	EventReceipts      []string        `json:"event_receipts,omitempty"`
	Decision           *Decision       `json:"decision,omitempty"`
	Action             *ActionIntent   `json:"action,omitempty"`
	AllowedResults     []string        `json:"allowed_results"`
}

type Record struct {
	Version            int           `json:"version"`
	Goal               string        `json:"goal"`
	CompletionCriteria string        `json:"completion_criteria"`
	Delegation         Delegation    `json:"delegation"`
	State              State         `json:"state"`
	WakeAt             *time.Time    `json:"wake_at,omitempty"`
	Sources            []SourceRef   `json:"sources,omitempty"`
	Action             *ActionIntent `json:"action,omitempty"`
	Run                *Run          `json:"run,omitempty"`
	Outcome            *Outcome      `json:"outcome,omitempty"`
	Decision           *Decision     `json:"decision,omitempty"`
	EventID            string        `json:"event_id,omitempty"`
	Journal            *Journal      `json:"journal,omitempty"`
	Notice             *Notice       `json:"notice,omitempty"`
	// Unresolved outbox entries are retained when a later task step creates a
	// new current journal/notice. They are evidence for operator reconciliation
	// and are never replayed automatically.
	UnresolvedJournals []Journal                  `json:"unresolved_journals,omitempty"`
	UnresolvedNotices  []Notice                   `json:"unresolved_notices,omitempty"`
	EventReceipts      []string                   `json:"event_receipts,omitempty"`
	DecisionReceipts   []string                   `json:"decision_receipts,omitempty"`
	SuggestionRegistry bool                       `json:"suggestion_registry,omitempty"`
	SuggestionClaims   map[string]SuggestionClaim `json:"suggestion_claims,omitempty"`
}

type Report struct {
	Scanned     int `json:"scanned"`
	Recognized  int `json:"recognized"`
	Due         int `json:"due"`
	Claimed     int `json:"claimed"`
	Processed   int `json:"processed"`
	NeedsReview int `json:"needs_review"`
	Ignored     int `json:"ignored"`
}

type ResultStatus string

type Run struct {
	ID         string `json:"id"`
	OwnerToken string `json:"owner_token"`
	// Fence binds a claim to the authorization and outward-action intent that
	// the operator approved. A metadata edit cannot retain an old claim while
	// changing either permission boundary.
	Fence        string    `json:"fence"`
	StartedAt    time.Time `json:"started_at"`
	HeartbeatAt  time.Time `json:"heartbeat_at"`
	LeaseExpires time.Time `json:"lease_expires_at"`
}

type Runner interface {
	Run(context.Context, Packet) (AdapterResult, error)
}

type Service struct {
	Store  Store
	Config Config
	Clock  Clock
	// NewLeaseTicker is injectable so fencing/cancellation tests do not need
	// wall-clock sleeps. Production leaves it nil and uses time.NewTicker.
	NewLeaseTicker func(time.Duration) LeaseTicker
}

type Snapshot struct {
	Card      cardView
	Metadata  api.CardMetadata
	Record    Record
	HasRecord bool
	ParseErr  error
}

type SourceRef struct {
	ID        string `json:"id"`
	Reference string `json:"reference,omitempty"`
}

type State string

type StatusItem struct {
	CardID string     `json:"card_id"`
	State  State      `json:"state"`
	WakeAt *time.Time `json:"wake_at,omitempty"`
}

type Store struct {
	Client Client
}

type SubprocessNotifier struct {
	Argv        []string
	OutputLimit int
	Env         []string
}

type SubprocessObserver struct {
	Argv        []string
	OutputLimit int
	MaxEvents   int
	Env         []string
}

type SubprocessRunner struct {
	Argv        []string
	ArtifactDir string
	OutputLimit int
	PacketLimit int
	// Env is deliberately explicit. Ambient process credentials are never
	// inherited by adapters; trusted bridge configuration belongs in files or
	// a socket owned by that bridge, not this worker's environment.
	Env []string
}

type Suggestion struct {
	SourceID  string `json:"source_id"`
	Reference string `json:"reference,omitempty"`
	Title     string `json:"title"`
	Proposal  string `json:"proposal"`
}

type SuggestionClaim struct {
	State  string `json:"state"`
	CardID string `json:"card_id,omitempty"`
}