declarations

type Change struct {
	Class   Class
	Subject string // "policy", or "tool <name>"
	What    string
	// Covered says the digest covers the declaration (the policy, and a tool's Untrusted, Exempt and Caps).
	// A difference in a tool's Effect or its own gate is reported but changes no digest.
	Covered bool
}

type Class int

type Document struct {
	Format string `json:"format"`
	// Digest is the taint_policy_digest a run started by this agent records, "" for an agent with no taint
	// policy (no run it starts is under taint).
	Digest string `json:"digest"`
	// TracksIdempotent is set by a version that writes each tool's Idempotent member. A document without it
	// predates the member, so a tool's absent idempotent is unknown, not false (see Diff).
	TracksIdempotent bool `json:"tracks_idempotent,omitempty"`
	// Policy is the agent's taint policy, nil for none.
	Policy *Policy `json:"policy,omitempty"`
	// Tools is every tool the agent registers, by name.
	Tools []Tool `json:"tools"`
}

type Finding struct {
	Subject string
	Message string
}

type FlowBlock struct {
	Name string
	// Merge is set for a fan-in merge, a namespace of its own: a name may be both a block and a merge.
	Merge bool
	// Effect: the block can have a side effect (its safety is not readonly). Idempotent: it is retry-safe.
	Effect, Idempotent bool
	OwnGate            *Gate
	// Untrusted are the declared sources, sorted.
	Untrusted []string
	Trusted   string
	Exempt    string
}

type FlowDocument struct {
	// TaintKnown says the description carried the taint declarations (RegistryDescription.TaintDeclared). When
	// it is false nothing below says anything about taint, and an absent declaration is not read as none.
	TaintKnown bool
	// Policy is the taint policy the description was given, nil when none was given.
	Policy *Policy
	// Blocks are the Step, Tool, Model and Join blocks, sorted by name within each namespace (blocks, then merges).
	Blocks []FlowBlock
}

type Gate struct {
	Single           bool     `json:"single,omitempty"`
	Need             int      `json:"need,omitempty"`
	Approvers        []string `json:"approvers,omitempty"`
	ExcludePrincipal bool     `json:"exclude_principal,omitempty"`
	TimeoutMS        int64    `json:"timeout_ms,omitempty"`
}

type Policy struct {
	Gate   *Gate `json:"gate,omitempty"`
	Refuse bool  `json:"refuse,omitempty"`
	// RequireProvenance: every tool declares a provenance and every run states its input's.
	RequireProvenance bool `json:"require_provenance,omitempty"`
	// SeparateApprovers: the escalation gate excludes the approvers a call's own gate counted.
	SeparateApprovers bool `json:"separate_approvers,omitempty"`
}

type Tool struct {
	Name      string `json:"name"`
	Effect    bool   `json:"effect,omitempty"`
	OwnGate   *Gate  `json:"own_gate,omitempty"`
	Untrusted string `json:"untrusted,omitempty"`
	// Trusted is the reason the tool's results are the host's own (a positive provenance declaration).
	Trusted string   `json:"trusted,omitempty"`
	Exempt  string   `json:"exempt,omitempty"`
	Caps    []string `json:"caps,omitempty"`
	// Idempotent is set for a tool that can have a side effect and is retry-safe (Safety.Idempotent without
	// ReadOnly). It is for the diff only; the digest does not cover it.
	Idempotent bool `json:"idempotent,omitempty"`
	// RaisesSafety is the reason a wrapper declares a safer Safety than a tool inside it (agent.RaisesSafety).
	RaisesSafety string `json:"raises_safety,omitempty"`
}