// Code generated by seatgen from the seat definitions; DO NOT EDIT.

// Package nodeengine is the contract of the seat "node-engine", defined whole (seats/node-engine/seat.json): The node seat every node's engine holds (novox/hq ADR 0563, ADR 0618 §3, §4): its hand acts on the operator's warrant, its read-only judgements, its compositions and what it reads of a manifest. Each verb is answered on this node's subject, mesh.seat.node-engine.tool.<verb>.<node>, and each event is published on mesh.seat.node-engine.event.<event>.<node>, the node's name its last token.
package nodeengine

import (
	"bytes"
	"encoding/json"
	"errors"
	"strings"
	"time"
)

// Seat is the seat's name.
const Seat = "node-engine"

const (
	VerbHandOver         = "hand-over"
	VerbAccessAct        = "access-act"
	VerbJudgeDirectories = "judge-directories"
	VerbSetuidSearch     = "setuid-search"
	VerbRootFree         = "root-free"
	VerbActs             = "acts"
	VerbPackages         = "packages"
	VerbComposition      = "composition"
	VerbCompose          = "compose"
	VerbComposeCandidate = "compose-candidate"
	VerbManifestReads    = "manifest-reads"
	VerbSeatList         = "seat-list"
	VerbSeatListAgain    = "seat-list-again"
)

const (
	EventAsked                = "asked"
	EventDone                 = "done"
	EventRefused              = "refused"
	EventManifestReadsChanged = "manifest-reads-changed"
)

// Verbs is every verb the seat serves, in its definition's order: a new copy each call.
func Verbs() []string {
	return []string{VerbHandOver, VerbAccessAct, VerbJudgeDirectories, VerbSetuidSearch, VerbRootFree, VerbActs, VerbPackages, VerbComposition, VerbCompose, VerbComposeCandidate, VerbManifestReads, VerbSeatList, VerbSeatListAgain}
}

// Events is every event published on the seat's subject: a new copy each call.
func Events() []string {
	return []string{EventAsked, EventDone, EventRefused, EventManifestReadsChanged}
}

// Family is where the seat's events are kept: the shared events stream, filtered to the seat's subjects.
const (
	Family           = "node-engine.events"
	FamilyMaxAgeDays = 7
)

// SubjectAsked is where asked is published for one caller.
func SubjectAsked(caller string) string { return "mesh.seat.node-engine.event.asked." + caller }

// SubjectDone is where done is published for one caller.
func SubjectDone(caller string) string { return "mesh.seat.node-engine.event.done." + caller }

// SubjectRefused is where refused is published for one caller.
func SubjectRefused(caller string) string { return "mesh.seat.node-engine.event.refused." + caller }

// SubjectManifestReadsChanged is where manifest-reads-changed is published for one caller.
func SubjectManifestReadsChanged(caller string) string {
	return "mesh.seat.node-engine.event.manifest-reads-changed." + caller
}

const (
	StateHave     = "have"
	StateComposed = "composed"
	StateData     = "data"
	StatePackages = "packages"
	StateHealth   = "health"
	StateFindings = "findings"
)

// HaveByNodeModuleKey is the key of one value of the state have under the form "<node>.<module>".
func HaveByNodeModuleKey(node, module string) string { return node + "." + module }

// ParseHaveByNodeModuleKey reads the parts of a key of the form "<node>.<module>", in the order of the form; the last result is false for a key of another form.
func ParseHaveByNodeModuleKey(key string) (string, string, bool) {
	rest := key
	v0, after0, found0 := strings.Cut(rest, ".")
	if !found0 || v0 == "" {
		return "", "", false
	}
	rest = after0
	if rest == "" {
		return "", "", false
	}
	v2 := rest
	rest = ""
	if rest != "" {
		return "", "", false
	}
	return v0, v2, true
}

// DecodeHaveByNodeModuleValue reads one value of the state have under the form "<node>.<module>", refusing a field HaveByNodeModuleValue does not know and any text after the value.
func DecodeHaveByNodeModuleValue(raw []byte) (HaveByNodeModuleValue, error) {
	var v HaveByNodeModuleValue
	dec := json.NewDecoder(bytes.NewReader(raw))
	dec.DisallowUnknownFields()
	if err := dec.Decode(&v); err != nil {
		return v, err
	}
	if dec.More() {
		return v, errors.New("text after the value")
	}
	return v, nil
}

// HaveByNodeNodeKey is the key of one value of the state have under the form "<node>.node".
func HaveByNodeNodeKey(node string) string { return node + ".node" }

// ParseHaveByNodeNodeKey reads the parts of a key of the form "<node>.node", in the order of the form; the last result is false for a key of another form.
func ParseHaveByNodeNodeKey(key string) (string, bool) {
	rest := key
	v0, after0, found0 := strings.Cut(rest, ".node")
	if !found0 || v0 == "" {
		return "", false
	}
	rest = after0
	if rest != "" {
		return "", false
	}
	return v0, true
}

// DecodeHaveByNodeNodeValue reads one value of the state have under the form "<node>.node", refusing a field HaveByNodeNodeValue does not know and any text after the value.
func DecodeHaveByNodeNodeValue(raw []byte) (HaveByNodeNodeValue, error) {
	var v HaveByNodeNodeValue
	dec := json.NewDecoder(bytes.NewReader(raw))
	dec.DisallowUnknownFields()
	if err := dec.Decode(&v); err != nil {
		return v, err
	}
	if dec.More() {
		return v, errors.New("text after the value")
	}
	return v, nil
}

// ComposedByNodeModuleFingerprintKey is the key of one value of the state composed under the form "<node>.<module>.<fingerprint>".
func ComposedByNodeModuleFingerprintKey(node, module, fingerprint string) string {
	return node + "." + module + "." + fingerprint
}

// ParseComposedByNodeModuleFingerprintKey reads the parts of a key of the form "<node>.<module>.<fingerprint>", in the order of the form; the last result is false for a key of another form.
func ParseComposedByNodeModuleFingerprintKey(key string) (string, string, string, bool) {
	rest := key
	v0, after0, found0 := strings.Cut(rest, ".")
	if !found0 || v0 == "" {
		return "", "", "", false
	}
	rest = after0
	v2, after2, found2 := strings.Cut(rest, ".")
	if !found2 || v2 == "" {
		return "", "", "", false
	}
	rest = after2
	if rest == "" {
		return "", "", "", false
	}
	v4 := rest
	rest = ""
	if rest != "" {
		return "", "", "", false
	}
	return v0, v2, v4, true
}

// DecodeComposedByNodeModuleFingerprintValue reads one value of the state composed under the form "<node>.<module>.<fingerprint>", refusing a field ComposedByNodeModuleFingerprintValue does not know and any text after the value.
func DecodeComposedByNodeModuleFingerprintValue(raw []byte) (ComposedByNodeModuleFingerprintValue, error) {
	var v ComposedByNodeModuleFingerprintValue
	dec := json.NewDecoder(bytes.NewReader(raw))
	dec.DisallowUnknownFields()
	if err := dec.Decode(&v); err != nil {
		return v, err
	}
	if dec.More() {
		return v, errors.New("text after the value")
	}
	return v, nil
}

// ComposedByNodeNodeKey is the key of one value of the state composed under the form "<node>.node".
func ComposedByNodeNodeKey(node string) string { return node + ".node" }

// ParseComposedByNodeNodeKey reads the parts of a key of the form "<node>.node", in the order of the form; the last result is false for a key of another form.
func ParseComposedByNodeNodeKey(key string) (string, bool) {
	rest := key
	v0, after0, found0 := strings.Cut(rest, ".node")
	if !found0 || v0 == "" {
		return "", false
	}
	rest = after0
	if rest != "" {
		return "", false
	}
	return v0, true
}

// DecodeComposedByNodeNodeValue reads one value of the state composed under the form "<node>.node", refusing a field ComposedByNodeNodeValue does not know and any text after the value.
func DecodeComposedByNodeNodeValue(raw []byte) (ComposedByNodeNodeValue, error) {
	var v ComposedByNodeNodeValue
	dec := json.NewDecoder(bytes.NewReader(raw))
	dec.DisallowUnknownFields()
	if err := dec.Decode(&v); err != nil {
		return v, err
	}
	if dec.More() {
		return v, errors.New("text after the value")
	}
	return v, nil
}

// DataByNodeModuleKey is the key of one value of the state data under the form "<node>.<module>".
func DataByNodeModuleKey(node, module string) string { return node + "." + module }

// ParseDataByNodeModuleKey reads the parts of a key of the form "<node>.<module>", in the order of the form; the last result is false for a key of another form.
func ParseDataByNodeModuleKey(key string) (string, string, bool) {
	rest := key
	v0, after0, found0 := strings.Cut(rest, ".")
	if !found0 || v0 == "" {
		return "", "", false
	}
	rest = after0
	if rest == "" {
		return "", "", false
	}
	v2 := rest
	rest = ""
	if rest != "" {
		return "", "", false
	}
	return v0, v2, true
}

// DecodeDataByNodeModuleValue reads one value of the state data under the form "<node>.<module>", refusing a field DataByNodeModuleValue does not know and any text after the value.
func DecodeDataByNodeModuleValue(raw []byte) (DataByNodeModuleValue, error) {
	var v DataByNodeModuleValue
	dec := json.NewDecoder(bytes.NewReader(raw))
	dec.DisallowUnknownFields()
	if err := dec.Decode(&v); err != nil {
		return v, err
	}
	if dec.More() {
		return v, errors.New("text after the value")
	}
	return v, nil
}

// PackagesByNodeKey is the key of one value of the state packages under the form "<node>".
func PackagesByNodeKey(node string) string { return node }

// ParsePackagesByNodeKey reads the parts of a key of the form "<node>", in the order of the form; the last result is false for a key of another form.
func ParsePackagesByNodeKey(key string) (string, bool) {
	rest := key
	if rest == "" {
		return "", false
	}
	v0 := rest
	rest = ""
	if rest != "" {
		return "", false
	}
	return v0, true
}

// DecodePackagesByNodeValue reads one value of the state packages under the form "<node>", refusing a field PackagesByNodeValue does not know and any text after the value.
func DecodePackagesByNodeValue(raw []byte) (PackagesByNodeValue, error) {
	var v PackagesByNodeValue
	dec := json.NewDecoder(bytes.NewReader(raw))
	dec.DisallowUnknownFields()
	if err := dec.Decode(&v); err != nil {
		return v, err
	}
	if dec.More() {
		return v, errors.New("text after the value")
	}
	return v, nil
}

// HealthByNodeKey is the key of one value of the state health under the form "<node>".
func HealthByNodeKey(node string) string { return node }

// ParseHealthByNodeKey reads the parts of a key of the form "<node>", in the order of the form; the last result is false for a key of another form.
func ParseHealthByNodeKey(key string) (string, bool) {
	rest := key
	if rest == "" {
		return "", false
	}
	v0 := rest
	rest = ""
	if rest != "" {
		return "", false
	}
	return v0, true
}

// DecodeHealthByNodeValue reads one value of the state health under the form "<node>", refusing a field HealthByNodeValue does not know and any text after the value.
func DecodeHealthByNodeValue(raw []byte) (HealthByNodeValue, error) {
	var v HealthByNodeValue
	dec := json.NewDecoder(bytes.NewReader(raw))
	dec.DisallowUnknownFields()
	if err := dec.Decode(&v); err != nil {
		return v, err
	}
	if dec.More() {
		return v, errors.New("text after the value")
	}
	return v, nil
}

// FindingsByKeyKey is the key of one value of the state findings under the form "<key>".
func FindingsByKeyKey(key string) string { return key }

// ParseFindingsByKeyKey reads the parts of a key of the form "<key>", in the order of the form; the last result is false for a key of another form.
func ParseFindingsByKeyKey(key string) (string, bool) {
	rest := key
	if rest == "" {
		return "", false
	}
	v0 := rest
	rest = ""
	if rest != "" {
		return "", false
	}
	return v0, true
}

// DecodeFindingsByKeyValue reads one value of the state findings under the form "<key>", refusing a field FindingsByKeyValue does not know and any text after the value.
func DecodeFindingsByKeyValue(raw []byte) (FindingsByKeyValue, error) {
	var v FindingsByKeyValue
	dec := json.NewDecoder(bytes.NewReader(raw))
	dec.DisallowUnknownFields()
	if err := dec.Decode(&v); err != nil {
		return v, err
	}
	if dec.More() {
		return v, errors.New("text after the value")
	}
	return v, nil
}

// AccountsHanded is the hashes of the users of the list, sealed to the vault.
type AccountsHanded struct {
	// when
	At   time.Time `json:"at"`
	Box  SealedBox `json:"box"`
	From string    `json:"from"`
	// the fingerprint of the vault's key
	To    string `json:"to"`
	Users int64  `json:"users"`
}

// Act is one act asked through the seat, as acts reads it (ADR 0563 §9).
type Act struct {
	// the act: hand-over, access-act, judge-directories or setuid-search
	Act string `json:"act"`
	// the operator's ask of a hand-over or an access act
	Ask string `json:"ask,omitempty"`
	// when it was asked, RFC 3339
	At string `json:"at"`
	// the engine asked it itself, on finding a library's root holding data outside its group (ADR 0563 §4)
	Auto bool `json:"auto,omitempty"`
	// who answered, as the operator's warrant names them
	By string `json:"by,omitempty"`
	// the caller as the runtime proved it
	Caller string `json:"caller"`
	// what the engine read on disk when it judged
	Disk string `json:"disk,omitempty"`
	// when it ended, RFC 3339
	Ended string `json:"ended,omitempty"`
	// when the ask ends unanswered, RFC 3339
	Expires string `json:"expires,omitempty"`
	// the act's id
	ID string `json:"id"`
	// the directory the act changes
	Path string `json:"path,omitempty"`
	// the warrant's proofs
	Proofs []string `json:"proofs,omitempty"`
	// what the engine said of it: its outcome or why it was refused
	Said string `json:"said,omitempty"`
	// the owner, group and mode it sets, in words
	Sets string `json:"sets,omitempty"`
	// where it stands
	State string `json:"state"`
	// the path of a hand-over, or the access of an access act
	Subject string `json:"subject,omitempty"`
	// the channel the warrant came on
	Via string `json:"via,omitempty"`
	// why it was asked, in words
	Why string `json:"why,omitempty"`
}

// The values of Act's state.
const (
	ActStateAsked    = "asked"
	ActStateDone     = "done"
	ActStateRefused  = "refused"
	ActStateAnswered = "answered"
)

// ActSaid is what the seat says of an act: the act, the path or access, the caller as the runtime proved it and the ask (ADR 0563 §1).
type ActSaid struct {
	// the act
	Act string `json:"act"`
	// the operator's ask
	Ask string `json:"ask,omitempty"`
	// the caller as the runtime proved it
	Caller string `json:"caller"`
	// the node whose engine says it
	Node string `json:"node"`
	// what the engine said of it
	Said string `json:"said,omitempty"`
	// where the act stands
	State string `json:"state"`
	// the path or the access
	Subject string `json:"subject,omitempty"`
}

// The values of ActSaid's state.
const (
	ActSaidStateAsked   = "asked"
	ActSaidStateDone    = "done"
	ActSaidStateRefused = "refused"
)

// Acts is the acts kept.
type Acts struct {
	// the acts, newest first
	Acts []Act `json:"acts"`
	// the node
	Node string `json:"node"`
}

// Adoption is the node is adopted and which of its modules are taken.
type Adoption struct {
	// the modules taken
	Taken []string `json:"taken"`
	// by module, the resources left untaken
	Untaken map[string][]string `json:"untaken,omitempty"`
}

// Asked is the answer of an act the operator is asked.
type Asked struct {
	// the ask's id: acts shows where it stands
	Asked string `json:"asked"`
	// the node
	Node string `json:"node"`
	// what happens next, in words
	Says string `json:"says"`
}

// AttachedNetwork is a network attached to a link.
type AttachedNetwork struct {
	Link    string `json:"link"`
	Network string `json:"network"`
}

// CandidateAdded is a module the candidate adds.
type CandidateAdded struct {
	Composed string   `json:"composed,omitempty"`
	Module   string   `json:"module"`
	Unissued []string `json:"unissued,omitempty"`
}

// CandidateAnswer is the node's answer to one placement candidate naming it.
type CandidateAnswer struct {
	Added    []CandidateAdded   `json:"added,omitempty"`
	Differs  []CandidateDiffers `json:"differs,omitempty"`
	Held     []CandidateRefusal `json:"held,omitempty"`
	Note     string             `json:"note,omitempty"`
	Proposal string             `json:"proposal"`
	Refusals []CandidateRefusal `json:"refusals,omitempty"`
	// why the node cannot compose with the candidate at all
	Refused string `json:"refused,omitempty"`
	// modules the candidate removes
	Removed  []string `json:"removed,omitempty"`
	Returns  string   `json:"returns,omitempty"`
	Revision int64    `json:"revision"`
	// modules whose composition is the one running
	Same         []string `json:"same,omitempty"`
	ValuesDiffer int64    `json:"values_differ,omitempty"`
	// same, differs or refused
	Verdict string `json:"verdict"`
}

// The values of CandidateAnswer's verdict.
const (
	CandidateAnswerVerdictSame    = "same"
	CandidateAnswerVerdictDiffers = "differs"
	CandidateAnswerVerdictRefused = "refused"
)

// CandidateBodies is the bodies of one resource that differ.
type CandidateBodies struct {
	Composed string   `json:"composed,omitempty"`
	ID       string   `json:"id"`
	Paths    []string `json:"paths,omitempty"`
	Running  string   `json:"running,omitempty"`
	Why      string   `json:"why"`
}

// CandidateDiffers is a module whose composition with the candidate differs from the one running.
type CandidateDiffers struct {
	Bodies   []CandidateBodies `json:"bodies,omitempty"`
	Composed string            `json:"composed,omitempty"`
	Module   string            `json:"module"`
	Resource string            `json:"resource,omitempty"`
	Running  string            `json:"running,omitempty"`
	Why      string            `json:"why"`
}

// CandidateRefusal is a module refused or held with the candidate.
type CandidateRefusal struct {
	Module string `json:"module"`
	Today  string `json:"today,omitempty"`
	Why    string `json:"why"`
}

// DeclaredGroup is a group.
type DeclaredGroup struct {
	Gid  int64  `json:"gid"`
	Name string `json:"name"`
}

// DeclaredIdentity is the identity of a module assigned to the node.
type DeclaredIdentity struct {
	Gid    int64   `json:"gid"`
	Groups []int64 `json:"groups,omitempty"`
	Module string  `json:"module"`
	Name   string  `json:"name"`
	Runner string  `json:"runner,omitempty"`
	Uid    int64   `json:"uid"`
}

// DeclaredLibrary is a library the node is reached by.
type DeclaredLibrary struct {
	Gid     int64    `json:"gid"`
	Group   string   `json:"group"`
	Home    bool     `json:"home"`
	Library string   `json:"library"`
	Paths   []string `json:"paths,omitempty"`
	Root    string   `json:"root"`
	Runner  string   `json:"runner,omitempty"`
	Taken   bool     `json:"taken,omitempty"`
}

// FailedUnit is a unit that failed.
type FailedUnit struct {
	Load     string `json:"load,omitempty"`
	Resource string `json:"resource,omitempty"`
	Result   string `json:"result,omitempty"`
	Scope    string `json:"scope"`
	// since when
	Since time.Time `json:"since"`
	Unit  string    `json:"unit"`
}

// FindingAction is one answer the operator may give from a notification.
type FindingAction struct {
	Arguments map[string]string `json:"arguments,omitempty"`
	Label     string            `json:"label"`
	Level     string            `json:"level,omitempty"`
	Machine   string            `json:"machine,omitempty"`
	// the seat verb the operator channel calls
	Verb string `json:"verb"`
}

// The values of FindingAction's level.
const (
	FindingActionLevelAcknowledge = "acknowledge"
	FindingActionLevelApprove     = "approve"
)

// FindingEvidence is one observation, as it was said.
type FindingEvidence struct {
	At   time.Time `json:"at"`
	Said string    `json:"said"`
}

// FindingSubject is what the condition is about.
type FindingSubject struct {
	// the other machines it concerns
	Also []string `json:"also,omitempty"`
	// its id within the scope
	ID string `json:"id"`
	// the machine it concerns, when there is one
	Machine string `json:"machine,omitempty"`
	// machine, plan, call, build, merge, provider, seat, bus, core, probe, mesh, delivery or module
	Scope string `json:"scope"`
}

// LoginFallback is a login that fell back to another node.
type LoginFallback struct {
	// when
	At   time.Time `json:"at"`
	From string    `json:"from"`
	Node string    `json:"node"`
	Why  string    `json:"why"`
}

// ManifestReadsChanged is what a node-engine says when what it reads changed or its node returned (ADR 0618 §4).
type ManifestReadsChanged struct {
	// when it says it, RFC 3339
	At string `json:"at"`
	// what its engine states it reads now
	ManifestReads []string `json:"manifest-reads,omitempty"`
	// the node
	Node string `json:"node"`
	// the layout's version
	V int64 `json:"v"`
	// started: the engine started or what it states changed; returned: its node returned after being away
	Why string `json:"why"`
}

// The values of ManifestReadsChanged's why.
const (
	ManifestReadsChangedWhyStarted  = "started"
	ManifestReadsChangedWhyReturned = "returned"
)

// Module is one module's composition with the candidate.
type Module struct {
	// the candidate changes it from the one composed without it
	Changed bool `json:"changed,omitempty"`
	// the composition's digest when composed
	Digest string `json:"digest,omitempty"`
	// the fingerprint it was composed at
	Fp string `json:"fp,omitempty"`
	// the module, node for the node's own composition
	Module string `json:"module"`
	// composed (digest set), refused by the candidate, or held without it too (words set)
	State string `json:"state"`
	// why, for a refused or held one
	Words string `json:"words,omitempty"`
}

// The values of Module's state.
const (
	ModuleStateComposed = "composed"
	ModuleStateRefused  = "refused"
	ModuleStateHeld     = "held"
)

// NetworkHealth is the node's network.
type NetworkHealth struct {
	Parts []NetworkPart `json:"parts"`
	// since when
	Since time.Time `json:"since"`
	// running, degraded or unknown
	State string `json:"state"`
}

// NetworkPart is one part of the node's network.
type NetworkPart struct {
	Owner  string `json:"owner,omitempty"`
	Part   string `json:"part"`
	Reason string `json:"reason,omitempty"`
	Said   string `json:"said,omitempty"`
	// since when
	Since   time.Time `json:"since"`
	State   string    `json:"state"`
	Streak  int64     `json:"streak,omitempty"`
	Targets []string  `json:"targets,omitempty"`
	Toward  []string  `json:"toward,omitempty"`
	Writer  string    `json:"writer,omitempty"`
}

// NodeAccount is an account the node needs to log in again.
type NodeAccount struct {
	Account  string `json:"account"`
	Module   string `json:"module,omitempty"`
	Reason   string `json:"reason"`
	Resource string `json:"resource,omitempty"`
	// since when
	Since time.Time `json:"since"`
}

// NodeDirectory is a directory found where the node expected none.
type NodeDirectory struct {
	Module   string `json:"module"`
	Path     string `json:"path"`
	Reason   string `json:"reason"`
	Resource string `json:"resource"`
	// since when
	Since time.Time `json:"since"`
}

// NodeOwn is what a node's own composition carries beside its resources.
type NodeOwn struct {
	Adoption   *Adoption          `json:"adoption,omitempty"`
	Groups     []DeclaredGroup    `json:"groups,omitempty"`
	Identities []DeclaredIdentity `json:"identities,omitempty"`
	Libraries  []DeclaredLibrary  `json:"libraries,omitempty"`
	// the account the provisioner's client runs as on the node
	ProvisionerAccount string `json:"provisioner_account,omitempty"`
}

// NodeRecord is what the machine observes of itself, for every node and composing part to read.
type NodeRecord struct {
	Authority     string            `json:"authority,omitempty"`
	Capabilities  []string          `json:"capabilities,omitempty"`
	Certificate   string            `json:"certificate,omitempty"`
	Contract      int64             `json:"contract,omitempty"`
	ManifestReads []string          `json:"manifest-reads,omitempty"`
	Networks      []AttachedNetwork `json:"networks,omitempty"`
	NetworksSaid  bool              `json:"networks-said,omitempty"`
	Node          string            `json:"node"`
	OutwardLinks  []string          `json:"outward-links,omitempty"`
	SealingKey    string            `json:"sealing-key,omitempty"`
	ServingKey    string            `json:"serving-key,omitempty"`
	Trusts        []string          `json:"trusts,omitempty"`
	TunnelKey     string            `json:"tunnel-key,omitempty"`
	V             int64             `json:"v"`
}

// PeerSeen is a tunnel peer and whether it is seen.
type PeerSeen struct {
	Addresses []string `json:"addresses,omitempty"`
	Key       string   `json:"key"`
	Seen      bool     `json:"seen"`
}

// PlacedDataItem is one data item a module declares, as placed on a node.
type PlacedDataItem struct {
	Class string `json:"class"`
	// the path whose snapshot keeps it, empty when it is not backed up
	CoveredBy string `json:"covered_by,omitempty"`
	Item      string `json:"item"`
	// walk, dataset or shallow
	Measure string `json:"measure,omitempty"`
	Module  string `json:"module"`
	// the item's place on the node
	Path string `json:"path"`
	// backup, redundancy, both or none
	Protection string `json:"protection,omitempty"`
}

// PullWait is the pull from a store a failed apply waits on.
type PullWait struct {
	// when the pull began
	Began time.Time `json:"began"`
	// that seat's holder, whose settling the apply waits for
	Holder string `json:"holder"`
	Image  string `json:"image"`
	// what triggered the last try again, in words
	Retried string `json:"retried,omitempty"`
	// when the apply was last tried again
	RetriedAt *time.Time `json:"retried-at,omitempty"`
	// the seat the pull came through
	Seat string `json:"seat,omitempty"`
}

// Revision is one revision of a composition key.
type Revision struct {
	// its digest
	Digest string `json:"digest,omitempty"`
	// the composition's key
	Key string `json:"key"`
	// the latest revision
	Latest bool `json:"latest,omitempty"`
	// why it cannot be read or trusted
	Refused string `json:"refused,omitempty"`
	// how many resources it names
	Resources int64 `json:"resources,omitempty"`
	// its revision
	Revision int64 `json:"revision,omitempty"`
}

// RootAccountVerdict is the engine's verdict of whether an account's resource is root-free, as the node's health lists it.
type RootAccountVerdict struct {
	Account  string `json:"account"`
	Module   string `json:"module"`
	Reason   string `json:"reason,omitempty"`
	Resource string `json:"resource"`
	// since when
	Since time.Time `json:"since"`
	State string    `json:"state"`
}

// RootVerdict is the engine's root-free verdict (ADR 0563 §6).
type RootVerdict struct {
	// the machine is root-free
	Free bool `json:"free"`
	// when the engine judged it, RFC 3339
	Judged string `json:"judged"`
	// the machine
	Machine string `json:"machine"`
	// why, in words
	Why string `json:"why"`
}

// Said is the answer of a read-only judgement.
type Said struct {
	// the node
	Node string `json:"node"`
	// the engine's judgement or search, one line per directory or program
	Said string `json:"said"`
}

// SealedBox is a value sealed to a key.
type SealedBox struct {
	Ct  string `json:"ct"`
	Eph string `json:"eph"`
	Iv  string `json:"iv"`
	Tag string `json:"tag"`
	V   int64  `json:"v"`
}

// SeatListStatus is a type of the contract.
type SeatListStatus struct {
	// the seat mesh-catalog has answered
	Heard     bool           `json:"heard"`
	Held      []SeatListHeld `json:"held"`
	LastError string         `json:"last-error,omitempty"`
	// a trunk definition that does not parse, by seat: the one held stands
	Refused  map[string]string `json:"refused,omitempty"`
	Revision int64             `json:"revision,omitempty"`
	// the seats held from the bootstrap alone
	Waiting []string `json:"waiting,omitempty"`
}

// SeatList is what an engine holds of the seat list (novox/hq ADR 0636 §7).
type SeatList struct {
	// why the read failed, for seat-list-again
	Error string `json:"error,omitempty"`
	// the one line the engine says of it; empty when nothing waits
	Health string         `json:"health"`
	Status SeatListStatus `json:"status"`
}

// SeatListHeld is a type of the contract.
type SeatListHeld struct {
	// the digest of the definition held; empty for a bootstrapped one
	Digest string `json:"digest,omitempty"`
	Seat   string `json:"seat"`
	Source string `json:"source"`
}

// The values of SeatListHeld's source.
const (
	SeatListHeldSourceTrunk     = "trunk"
	SeatListHeldSourceBootstrap = "bootstrap"
)

// UnitsHealth is the node's units.
type UnitsHealth struct {
	Away   []string     `json:"away,omitempty"`
	Failed []FailedUnit `json:"failed"`
	State  string       `json:"state"`
	Unread []string     `json:"unread,omitempty"`
}

// UserListWritten is the bus's user list as the engine of the bus node wrote it to the bus module's file.
type UserListWritten struct {
	// when
	At time.Time `json:"at"`
	// the digest of the file on the machine after the write
	Digest string `json:"digest,omitempty"`
	// why a write failed
	Error string `json:"error,omitempty"`
	// which list the node follows now
	Follows string          `json:"follows,omitempty"`
	Handed  *AccountsHanded `json:"handed,omitempty"`
	// the bus node's sealing key, its public half
	Key      string `json:"key,omitempty"`
	Revision int64  `json:"revision"`
	// the key the list was taken from
	Source string `json:"source"`
	// why the bus node does not watch the grants part's key now
	Unwatched string `json:"unwatched,omitempty"`
	Users     int64  `json:"users"`
	// the digest of the list the source holds, sha256:<hex>
	Wanted string `json:"wanted"`
}

// HandOverInput is what hand-over takes.
type HandOverInput struct {
	// the directory's absolute path, as the engine states it
	Path string `json:"path"`
	// why it is asked, in words the operator reads
	Why string `json:"why,omitempty"`
}

// HandOverAnswer is what hand-over answers.
type HandOverAnswer = Asked

// AccessActInput is what access-act takes.
type AccessActInput struct {
	// the access, library:<name>
	Access string `json:"access"`
	// the act: take
	Act string `json:"act"`
	// why it is asked, in words the operator reads
	Why string `json:"why,omitempty"`
}

// AccessActAnswer is what access-act answers.
type AccessActAnswer = Asked

// JudgeDirectoriesInput is what judge-directories takes.
type JudgeDirectoriesInput struct {
}

// JudgeDirectoriesAnswer is what judge-directories answers.
type JudgeDirectoriesAnswer = Said

// SetuidSearchInput is what setuid-search takes.
type SetuidSearchInput struct {
	// why it is asked, in words
	Why string `json:"why,omitempty"`
}

// SetuidSearchAnswer is what setuid-search answers.
type SetuidSearchAnswer = Said

// RootFreeInput is what root-free takes.
type RootFreeInput struct {
}

// RootFreeAnswer is what root-free answers.
type RootFreeAnswer struct {
	// this machine's verdict
	Machines []RootVerdict `json:"machines"`
}

// ActsInput is what acts takes.
type ActsInput struct {
	// one act, by its id
	ID string `json:"id,omitempty"`
	// at most this many, newest
	Limit string `json:"limit,omitempty"`
}

// ActsAnswer is what acts answers.
type ActsAnswer = Acts

// PackagesInput is what packages takes.
type PackagesInput struct {
	// "true": write this machine's key again from what the engine composed
	Write string `json:"write,omitempty"`
}

// The values of PackagesInput's write.
const (
	PackagesInputWriteTrue  = "true"
	PackagesInputWriteFalse = "false"
)

// PackagesAnswerKeyPackagesItem is a type of the contract.
type PackagesAnswerKeyPackagesItem struct {
	// declared absent
	Absent bool `json:"absent"`
	// the modules that declare it
	Modules []string `json:"modules"`
	// the package
	Package string `json:"package"`
}

// PackagesAnswerKey is the node's key as the bus holds it; absent when the engine wrote none.
type PackagesAnswerKey struct {
	// the node
	Node string `json:"node"`
	// its packages sorted by name, absent after present
	Packages []PackagesAnswerKeyPackagesItem `json:"packages"`
}

// PackagesAnswer is what packages answers.
type PackagesAnswer struct {
	// the node's key as the bus holds it; absent when the engine wrote none
	Key *PackagesAnswerKey `json:"key,omitempty"`
	// why the key could not be read
	KeyError string `json:"key_error,omitempty"`
	// the node
	Node string `json:"node"`
	// a note, such as that no key is written yet
	Note string `json:"note,omitempty"`
	// where the key is read: the engine's state packages
	Source string `json:"source"`
	// with write: the key was written again (false: it already held what the engine composed)
	Wrote bool `json:"wrote,omitempty"`
}

// CompositionInput is what composition takes.
type CompositionInput struct {
	// "true": list the resources that differ from what runs
	Diff string `json:"diff,omitempty"`
	// a composition's digest (sha256:…), to read that revision rather than the latest
	Digest string `json:"digest,omitempty"`
	// the module, as placed on this machine; node for the node's own
	Module string `json:"module"`
}

// CompositionAnswerAttempt is the module's last apply that did not end running; absent when none.
type CompositionAnswerAttempt struct {
	// the want's revision the hold took
	AnsweredRevision int64 `json:"answered_revision,omitempty"`
	// the digest tried
	Composed string `json:"composed,omitempty"`
	// the composition's revision it was tried at
	CompositionRevision int64 `json:"composition_revision"`
	// the fingerprint tried
	Fp string `json:"fp"`
	// held for a failed backup
	Held bool `json:"held,omitempty"`
	// it failed because the bus did not answer for a moment
	Transient bool `json:"transient,omitempty"`
	// the want's revision it was tried at
	WantRevision int64 `json:"want_revision"`
}

// CompositionAnswerHave is what the module's have key says now; absent when it says nothing.
type CompositionAnswerHave struct {
	// digest
	Composed string `json:"composed,omitempty"`
	// detail
	Detail string `json:"detail,omitempty"`
	// fingerprint
	Fp string `json:"fp,omitempty"`
	// judgement
	Judgement string `json:"judgement,omitempty"`
	// running, failed, held or waiting-yes
	Phase string `json:"phase"`
	// the digest that waits for a yes
	Waits string `json:"waits,omitempty"`
}

// CompositionAnswerJudged is the move from what runs to the composition read.
type CompositionAnswerJudged struct {
	// the judgement
	Judgement string `json:"judgement"`
	// the agent would wait for a person's yes before applying it
	WaitsForYes bool `json:"waits_for_yes"`
	// its words
	Words string `json:"words"`
}

// CompositionAnswerOwn is of the node's own composition, its own fields beside what runs names.
type CompositionAnswerOwn struct {
	// the revision's adoption; absent for a converged node
	Adoption map[string]any `json:"adoption,omitempty"`
	// groups
	Groups int64 `json:"groups,omitempty"`
	// each module the node's composer held in its last pass, with why
	Held map[string]string `json:"held,omitempty"`
	// identities the revision names
	Identities int64 `json:"identities,omitempty"`
	// libraries
	Libraries int64 `json:"libraries,omitempty"`
	// the account the provisioner's client runs as, as the revision names it
	ProvisionerAccount string `json:"provisioner_account"`
	// as what runs names it
	RunsProvisionerAccount string `json:"runs_provisioner_account,omitempty"`
}

// CompositionAnswerRuns is what runs of the module; absent when nothing runs.
type CompositionAnswerRuns struct {
	// digest
	Composed string `json:"composed,omitempty"`
	// fingerprint
	Fp string `json:"fp,omitempty"`
	// applied, have or kept
	From string `json:"from"`
	// phase
	Phase string `json:"phase,omitempty"`
	// how many resources run
	Resources int64 `json:"resources"`
}

// CompositionAnswerWant is the module's want as the agent holds it; absent when it holds none.
type CompositionAnswerWant struct {
	// the operator's answer to a failed backup, again or skip
	Backup string `json:"backup,omitempty"`
	// the composition's digest it names
	Composed string `json:"composed,omitempty"`
	// its build's fingerprint
	Fp string `json:"fp"`
	// the module is removed
	Removed bool `json:"removed,omitempty"`
	// the revision of the want's key read last
	Revision int64 `json:"revision"`
	// the node composes the module itself (ADR 0547 §2)
	Self bool `json:"self,omitempty"`
	// its words
	Words string `json:"words,omitempty"`
	// the digest a person said yes to
	Yes string `json:"yes,omitempty"`
}

// CompositionAnswer is what composition answers.
type CompositionAnswer struct {
	// the module's last apply that did not end running; absent when none
	Attempt     *CompositionAnswerAttempt `json:"attempt,omitempty"`
	Composition Revision                  `json:"composition"`
	// every resource that differs from what runs, when asked
	Diff []map[string]any `json:"diff,omitempty"`
	// what the module's have key says now; absent when it says nothing
	Have *CompositionAnswerHave `json:"have,omitempty"`
	// the move from what runs to the composition read
	Judged CompositionAnswerJudged `json:"judged"`
	// the module
	Module string `json:"module"`
	// the node
	Node string `json:"node"`
	// of the node's own composition, its own fields beside what runs names
	Own *CompositionAnswerOwn `json:"own,omitempty"`
	// the revisions of its key the bucket keeps, oldest first
	Revisions []Revision `json:"revisions,omitempty"`
	// what runs of the module; absent when nothing runs
	Runs *CompositionAnswerRuns `json:"runs,omitempty"`
	// the agent has looked at the module once since it started
	Started bool `json:"started"`
	// the module's want as the agent holds it; absent when it holds none
	Want *CompositionAnswerWant `json:"want,omitempty"`
}

// ComposeInput is what compose takes.
type ComposeInput struct {
	// a module placed on this machine whose apply is also tried again (optional)
	Module string `json:"module,omitempty"`
}

// ComposeAnswerPass is how the pass went.
type ComposeAnswerPass struct {
	// when the node composes again on its own, RFC 3339
	Again string `json:"again,omitempty"`
	// when the pass ended, RFC 3339
	At string `json:"at"`
	// the answer is the last pass, made moments ago
	Earlier bool `json:"earlier,omitempty"`
	// how many compositions the pass handed the agent that differ from before
	Handed int64 `json:"handed"`
	// each module refused alone, with why
	Held map[string]string `json:"held,omitempty"`
	// why the node composed none of its modules
	Refused string `json:"refused,omitempty"`
}

// ComposeAnswer is what compose answers.
type ComposeAnswer struct {
	// how the pass went
	Pass ComposeAnswerPass `json:"pass"`
	// the module whose apply was tried again
	Retried string `json:"retried,omitempty"`
}

// ComposeCandidateInput is what compose-candidate takes.
type ComposeCandidateInput struct {
	// the key of the indexer's candidate, <group>.<heads hash>
	Candidate string `json:"candidate"`
	// also answer the composition input the candidate was composed from, for the sandbox path
	Input bool `json:"input,omitempty"`
}

// ComposeCandidateAnswer is what compose-candidate answers.
type ComposeCandidateAnswer struct {
	// the candidate's key
	Candidate string `json:"candidate"`
	// when asked: the composition input it composed from
	Input map[string]any `json:"input,omitempty"`
	// every module placed on the node, sorted by name
	Modules []Module `json:"modules"`
	// the node
	Node string `json:"node"`
	Own  Module `json:"own"`
	// why the node could not compose with the candidate at all
	Refused string `json:"refused,omitempty"`
	// how long the engine took, in milliseconds
	Took int64 `json:"took"`
	// the layout's version
	V int64 `json:"v"`
	// the node's verdict (ADR 0593 §7, §9)
	Verdict string `json:"verdict"`
}

// The values of ComposeCandidateAnswer's verdict.
const (
	ComposeCandidateAnswerVerdictComposed  = "composed"
	ComposeCandidateAnswerVerdictRefused   = "refused"
	ComposeCandidateAnswerVerdictUnready   = "unready"
	ComposeCandidateAnswerVerdictNotJudged = "not-judged"
)

// ManifestReadsInput is what manifest-reads takes.
type ManifestReadsInput struct {
}

// ManifestReadsAnswer is what manifest-reads answers.
type ManifestReadsAnswer struct {
	// the reader capabilities its engine states: the manifest words, forms and seat names it reads; empty for an engine built before it said them, read as the baseline
	ManifestReads []string `json:"manifest-reads,omitempty"`
	// the node
	Node string `json:"node"`
	// when the engine last stated them, RFC 3339
	StatedAt string `json:"stated-at"`
	// the layout's version
	V int64 `json:"v"`
}

// SeatListInput is what seat-list takes.
type SeatListInput struct {
}

// SeatListAnswer is what seat-list answers.
type SeatListAnswer = SeatList

// SeatListAgainInput is what seat-list-again takes.
type SeatListAgainInput struct {
}

// SeatListAgainAnswer is what seat-list-again answers.
type SeatListAgainAnswer = SeatList

// AskedEvent is the body of the event asked.
type AskedEvent = ActSaid

// DoneEvent is the body of the event done.
type DoneEvent = ActSaid

// RefusedEvent is the body of the event refused.
type RefusedEvent = ActSaid

// ManifestReadsChangedEvent is the body of the event manifest-reads-changed.
type ManifestReadsChangedEvent = ManifestReadsChanged

// HaveByNodeModuleValue is one value of the state have under the key <node>.<module>.
type HaveByNodeModuleValue struct {
	Build string `json:"build,omitempty"`
	// the move changes the build alone
	BuildAlone bool `json:"build-alone,omitempty"`
	// the digest of the composition the node runs
	Composed string `json:"composed,omitempty"`
	Detail   string `json:"detail,omitempty"`
	// the fingerprint held
	Fp     string          `json:"fp,omitempty"`
	Handed *AccountsHanded `json:"handed,omitempty"`
	// what the module's own check says
	Health string `json:"health"`
	// in phase waiting-yes, the judgement of the move
	Judgement string `json:"judgement,omitempty"`
	// what the node keeps of the module as it runs
	Kept []string `json:"kept,omitempty"`
	// how far it has come
	Phase    string    `json:"phase"`
	PullWait *PullWait `json:"pull-wait,omitempty"`
	// each value sealed to the node's key
	Sealed []string `json:"sealed,omitempty"`
	// the sealed values by slot
	SealedAt map[string]string `json:"sealed-at,omitempty"`
	UserList *UserListWritten  `json:"user-list,omitempty"`
	V        int64             `json:"v"`
	// in phase waiting-yes, the digest of the composition that waits
	Waits string `json:"waits,omitempty"`
}

// The values of HaveByNodeModuleValue's health.
const (
	HaveByNodeModuleValueHealthOk      = "ok"
	HaveByNodeModuleValueHealthFailed  = "failed"
	HaveByNodeModuleValueHealthWaits   = "waits"
	HaveByNodeModuleValueHealthUnknown = "unknown"
)

// The values of HaveByNodeModuleValue's judgement.
const (
	HaveByNodeModuleValueJudgementRecreates   = "recreates"
	HaveByNodeModuleValueJudgementMovesData   = "moves-data"
	HaveByNodeModuleValueJudgementCannotJudge = "cannot-judge"
)

// The values of HaveByNodeModuleValue's phase.
const (
	HaveByNodeModuleValuePhaseBackingUp  = "backing-up"
	HaveByNodeModuleValuePhaseApplying   = "applying"
	HaveByNodeModuleValuePhaseChecking   = "checking"
	HaveByNodeModuleValuePhaseRunning    = "running"
	HaveByNodeModuleValuePhaseFailed     = "failed"
	HaveByNodeModuleValuePhaseRemoved    = "removed"
	HaveByNodeModuleValuePhaseHeld       = "held"
	HaveByNodeModuleValuePhaseWaitingYes = "waiting-yes"
)

// HaveByNodeNodeValue is one value of the state have under the key <node>.node.
type HaveByNodeNodeValue struct {
	Busy []map[string]any `json:"busy,omitempty"`
	// the node's answer to each placement candidate naming it, by proposal id
	Candidates map[string]CandidateAnswer `json:"candidates,omitempty"`
	// the digest of the node's own composition it runs
	Composed string `json:"composed,omitempty"`
	// own, or none (empty)
	Composes    string            `json:"composes,omitempty"`
	ComposesWhy string            `json:"composes-why,omitempty"`
	Filters     []map[string]any  `json:"filters,omitempty"`
	Profile     map[string]any    `json:"profile,omitempty"`
	Record      *NodeRecord       `json:"record,omitempty"`
	Sealed      []string          `json:"sealed,omitempty"`
	SealedAt    map[string]string `json:"sealed-at,omitempty"`
	Strays      []map[string]any  `json:"strays,omitempty"`
	V           int64             `json:"v"`
	Windows     []map[string]any  `json:"windows,omitempty"`
}

// ComposedByNodeModuleFingerprintValue is one value of the state composed under the key <node>.<module>.<fingerprint>.
type ComposedByNodeModuleFingerprintValue struct {
	// the module declares data
	Data bool `json:"data,omitempty"`
	// the files the provisioner fills
	FilledFiles []string `json:"filled_files,omitempty"`
	Fp          string   `json:"fp"`
	Module      string   `json:"module"`
	Node        string   `json:"node"`
	// the module's whole provisioning plan, catalogue.Plan, kept whole: it is the manifest layer's type
	Plan map[string]any `json:"plan,omitempty"`
	// why the module cannot be composed at this fingerprint
	Refused string `json:"refused,omitempty"`
	// the declaration resources, each saying its module
	Resources []map[string]any `json:"resources"`
	V         int64            `json:"v"`
}

// ComposedByNodeNodeValue is one value of the state composed under the key <node>.node.
type ComposedByNodeNodeValue struct {
	// the module declares data
	Data bool `json:"data,omitempty"`
	// the files the provisioner fills
	FilledFiles []string `json:"filled_files,omitempty"`
	Node        string   `json:"node"`
	Own         *NodeOwn `json:"own,omitempty"`
	// the declaration resources, each saying its module
	Resources []map[string]any `json:"resources"`
	V         int64            `json:"v"`
}

// DataByNodeModuleValue is one value of the state data under the key <node>.<module>.
type DataByNodeModuleValue struct {
	Digest string           `json:"digest"`
	Items  []PlacedDataItem `json:"items"`
	Module string           `json:"module"`
	Node   string           `json:"node"`
	V      int64            `json:"v"`
}

// PackagesByNodeValuePackagesItem is a type of the contract.
type PackagesByNodeValuePackagesItem struct {
	Absent  bool     `json:"absent"`
	Modules []string `json:"modules"`
	Package string   `json:"package"`
}

// PackagesByNodeValue is one value of the state packages under the key <node>.
type PackagesByNodeValue struct {
	Node     string                            `json:"node"`
	Packages []PackagesByNodeValuePackagesItem `json:"packages"`
}

// HealthByNodeValue is one value of the state health under the key <node>.
type HealthByNodeValue struct {
	// when
	At       time.Time            `json:"at"`
	Contract int64                `json:"contract,omitempty"`
	Fallback *LoginFallback       `json:"fallback,omitempty"`
	Found    []NodeDirectory      `json:"found,omitempty"`
	Network  *NetworkHealth       `json:"network,omitempty"`
	Node     string               `json:"node"`
	Peers    []PeerSeen           `json:"peers,omitempty"`
	Relogin  []NodeAccount        `json:"relogin,omitempty"`
	Root     []RootAccountVerdict `json:"root,omitempty"`
	Units    *UnitsHealth         `json:"units,omitempty"`
	V        int64                `json:"v"`
}

// FindingsByKeyValue is one value of the state findings under the key <key>.
type FindingsByKeyValue struct {
	Actions []FindingAction `json:"actions,omitempty"`
	At      time.Time       `json:"at"`
	// newest first, at most 10
	Evidence    []FindingEvidence `json:"evidence,omitempty"`
	Explanation string            `json:"explanation,omitempty"`
	Headline    string            `json:"headline,omitempty"`
	// scope.id.token
	Key   string `json:"key"`
	Kind  string `json:"kind"`
	Needs string `json:"needs,omitempty"`
	// the module that wrote it
	Observer string `json:"observer"`
	// the key's last part when it is not the kind
	Ref      string `json:"ref,omitempty"`
	Resolved string `json:"resolved,omitempty"`
	// self, operator, agent or healer:<name>
	Resolver string `json:"resolver,omitempty"`
	// what of its own saw it last
	Run      string `json:"run,omitempty"`
	Severity string `json:"severity"`
	// the row, probe or event that saw it
	Source  string         `json:"source"`
	Subject FindingSubject `json:"subject"`
	// one line
	Summary string `json:"summary"`
	// layout version, 1
	V int64 `json:"v"`
}

// The values of FindingsByKeyValue's severity.
const (
	FindingsByKeyValueSeverityUrgent  = "urgent"
	FindingsByKeyValueSeverityWarning = "warning"
)