policy

type ActiveFreeze struct {
	Name   string `json:"name"`
	Reason string `json:"reason"`
	// Until is the end of this occurrence; zero = until a human lifts it
	// (incident freeze) or never (a window that does not parse: fail closed).
	Until    time.Time `json:"until,omitzero"`
	Incident bool      `json:"incident,omitempty"`
	By       string    `json:"by,omitempty"`
}

type Actor struct {
	// Agent is the agents.actors name the credential was minted for.
	Agent string `json:"agent"`
	// Harness and Session say where the agent runs (claude-code, codex, ...;
	// the harness session id). Informational: recorded for audit, never routed on.
	Harness string `json:"harness,omitempty"`
	Session string `json:"session,omitempty"`
}

type AgentActor struct {
	Name string `yaml:"name" json:"name"`
	// Harnesses it may run in (claude-code, codex, ...); empty = any.
	Harnesses []string `yaml:"harnesses,omitempty" json:"harnesses,omitempty"`
	// Groups: the root principal must hold one of them; empty = any root.
	Groups []string `yaml:"groups,omitempty" json:"groups,omitempty"`
	// Models narrows agents.allowedModels for this agent; empty = no narrowing.
	Models []string `yaml:"models,omitempty" json:"models,omitempty"`
}

type AgentLimits struct {
	// MaxDepth lowers agents.maxDepth for the profile's members; 0 = the org's.
	MaxDepth int `yaml:"maxDepth,omitempty" json:"maxDepth,omitempty"`
	// Remote names the agents.remote entries members may call; empty = every
	// entry whose rings or units admit them.
	Remote []string `yaml:"remote,omitempty" json:"remote,omitempty"`
}

type AgentScope struct {
	Ring, Unit string
	// MaxDepth is the effective maximum chain length for this root.
	MaxDepth int
	// Remote names the agents.remote entries the root's agents may call.
	Remote []string
}

type Agents struct {
	// MaxDepth bounds the delegation chain (default 2, at most 5).
	MaxDepth int `yaml:"maxDepth,omitempty" json:"maxDepth,omitempty"`
	// MaxTTLSeconds caps a delegated credential (default 900, at most 3600). It
	// never outlives its parent either.
	MaxTTLSeconds int `yaml:"maxTTLSeconds,omitempty" json:"maxTTLSeconds,omitempty"`
	// Experiments enrolls delegated callers in experiments with their root.
	// Default false: agent traffic gets control routing and no shadow.
	Experiments bool `yaml:"experiments,omitempty" json:"experiments,omitempty"`
	// AllowedModels are the gateway model aliases any delegated actor may call;
	// empty = every alias the root may call.
	AllowedModels []string `yaml:"allowedModels,omitempty" json:"allowedModels,omitempty"`
	// DeniedTools are tools a delegated actor's model call may not declare:
	// function names (matched ignoring case) and hosted tool identifiers such
	// as web_search, code_execution or mcp:<server> (matched as a prefix,
	// ignoring case and underscores; see DeniesTool). With any set, the
	// gateway refuses an agent call whose tools it cannot read.
	DeniedTools []string `yaml:"deniedTools,omitempty" json:"deniedTools,omitempty"`
	// Actors are the agents that may act. A name not listed is refused.
	Actors []AgentActor `yaml:"actors" json:"actors"`
	// Remote is the allowlist of A2A agents members may call.
	Remote []RemoteAgent `yaml:"remote,omitempty" json:"remote,omitempty"`
}

type AllowFinding struct {
	Digest string `yaml:"digest" json:"digest"`
	Rule   string `yaml:"rule" json:"rule"`
	Path   string `yaml:"path,omitempty" json:"path,omitempty"`
	Reason string `yaml:"reason" json:"reason"`
}

type Approval struct {
	By string `json:"by"`
	// Groups are the approver's groups when they approved (IdP or SCIM).
	Groups []string  `json:"groups,omitempty"`
	At     time.Time `json:"at"`
	Ticket string    `json:"ticket,omitempty"`
	// Scopes are the scopes of the approver's scoped approve bindings when
	// they approved (ADR-0037). nil means a global approver: every approval
	// recorded before ADR-0037 was global. A scoped approval counts only for
	// a change one of them covers (QuorumFor).
	Scopes []RoleScope `json:"scopes,omitempty"`
	// ScopedGroups replaces Groups on a scoped approval (ScopedApproval): a
	// binary from before ADR-0037 ignores Scopes, so it must see no groups
	// and count the approval for no rule, rather than count it as global.
	ScopedGroups []string `json:"scopedGroups,omitempty"`
}

type ApprovalRule struct {
	Name   string      `yaml:"name" json:"name"`
	Scope  ChangeScope `yaml:"scope,omitempty" json:"scope,omitzero"`
	Quorum int         `yaml:"quorum" json:"quorum"`
	// Groups are the IdP (or SCIM) groups an approver must hold one of.
	Groups []string `yaml:"groups" json:"groups"`
	// DistinctGroups: each counted approval must come from a different group.
	DistinctGroups bool `yaml:"distinctGroups,omitempty" json:"distinctGroups,omitempty"`
	// Ticket, when set, is a regular expression (matched whole) a change
	// ticket reference must match, e.g. ^(CHG|INC)[0-9]{7}$ or ^OPS-[0-9]+$.
	Ticket string `yaml:"ticket,omitempty" json:"ticket,omitempty"`
}

type Artifact struct {
	Name string `yaml:"name" json:"name"`
	Kind string `yaml:"kind" json:"kind"`
	// Path is a file or directory in the policy repo, relative to its root.
	Path string `yaml:"path,omitempty" json:"path,omitempty"`
	// Git is a repository pinned to a full commit id.
	Git *GitSource `yaml:"git,omitempty" json:"git,omitempty"`
	// OCI is a digest-pinned reference, host/repo@sha256:<hex>; each layer is
	// one file named by its org.opencontainers.image.title annotation.
	OCI string `yaml:"oci,omitempty" json:"oci,omitempty"`
	// Digest is the artifact digest (supplychain.DigestOf). Required for git
	// and oci; for a path it is computed and, when set, checked.
	Digest    string             `yaml:"digest,omitempty" json:"digest,omitempty"`
	Signature *ArtifactSignature `yaml:"signature,omitempty" json:"signature,omitempty"`
}

type ArtifactContent struct {
	Files  supplychain.Tree
	Err    string // why it could not be read
	Signer string // trusted identity whose signature verified, if any
}

type ArtifactSignature struct {
	Identity string `yaml:"identity" json:"identity"`
	File     string `yaml:"file" json:"file"`
}

type Axis string

type Budget struct {
	Name string `yaml:"name" json:"name"`
	// Scope picks the counter: user (one per verified subject), group (one per
	// listed group), ring (one per ring) or org (one shared counter).
	Scope string `yaml:"scope" json:"scope"`
	// Groups: for scope group, the groups that each get a counter (required);
	// for other scopes, only callers in one of them are counted. Empty = everyone.
	Groups []string `yaml:"groups,omitempty" json:"groups,omitempty"`
	// Rings limits the budget to callers routed to these rings. Empty = every ring.
	Rings []string `yaml:"rings,omitempty" json:"rings,omitempty"`
	// Window: day | week (Monday) | month, calendar windows in UTC, or rolling
	// over Period.
	Window string `yaml:"window" json:"window"`
	// Period is the rolling window length as a Go duration (e.g. 24h); rolling only.
	Period string `yaml:"period,omitempty" json:"period,omitempty"`
	// LimitUSD and LimitTokens (input + output + cache) cap the window; set at
	// least one. Either one reached exhausts the budget.
	LimitUSD    float64 `yaml:"limitUSD,omitempty" json:"limitUSD,omitempty"`
	LimitTokens int64   `yaml:"limitTokens,omitempty" json:"limitTokens,omitempty"`
	// Action when exhausted: warn (header + metric, the request passes) or
	// enforce (HTTP 429 until the window resets). Empty means warn.
	Action string `yaml:"action,omitempty" json:"action,omitempty"`
	// AlertAt are soft thresholds as fractions of the limit (default [0.8]).
	AlertAt []float64 `yaml:"alertAt,omitempty" json:"alertAt,omitempty"`
}

type ChangeScope struct {
	Rings []string `yaml:"rings,omitempty" json:"rings,omitempty"`
	Units []string `yaml:"units,omitempty" json:"units,omitempty"`
}

type ChangeTarget struct {
	Rings []string `json:"rings,omitempty"`
	Units []string `json:"units,omitempty"`
}

type CloudAgent struct {
	// Enabled false renders nothing that runs the agent and makes every
	// observed task a violation; it never deletes a vendor setting.
	Enabled bool `yaml:"enabled" json:"enabled"`
	// Repos the agent may work in: owner/repo or owner/* (every repo of owner).
	Repos []string `yaml:"repos,omitempty" json:"repos,omitempty"`
	// Models the agent may use (vendor model ids). The first is rendered as
	// the default where the vendor takes a model in config.
	Models []string `yaml:"models,omitempty" json:"models,omitempty"`
	// MaxConcurrent caps running tasks.
	MaxConcurrent CloudConcurrency `yaml:"maxConcurrent,omitempty" json:"maxConcurrent,omitempty"`
	// Budgets cap vendor-reported task spend (ADR-0017 budget fields).
	Budgets []Budget `yaml:"budgets,omitempty" json:"budgets,omitempty"`
	// Network is the egress the agent's sandbox gets, where the vendor has one.
	Network *CloudNetwork `yaml:"network,omitempty" json:"network,omitempty"`
	// Identity "workload" makes rendered workflows call the model through the
	// Halos gateway with a short-lived workload credential (ADR-0023) instead
	// of a long-lived vendor key. Empty uses the vendor's repository secret.
	Identity string `yaml:"identity,omitempty" json:"identity,omitempty"`
	// OnOverLimit is alert (default: report only) or pause (also pause the
	// agent where the vendor API can, reversibly; never auto-resumed).
	OnOverLimit string `yaml:"onOverLimit,omitempty" json:"onOverLimit,omitempty"`
	// Version pins the agent CLI where the vendor takes one (gemini).
	Version string `yaml:"version,omitempty" json:"version,omitempty"`
	// TimeoutMinutes caps one rendered workflow job (copilot at most 59).
	TimeoutMinutes int `yaml:"timeoutMinutes,omitempty" json:"timeoutMinutes,omitempty"`
}

type CloudAgents struct {
	// Identities map vendor logins to Halos users, so a cloud task is
	// attributed, ring-resolved and killed like its human.
	Identities []CloudIdentity `yaml:"identities,omitempty" json:"identities,omitempty"`
	// Server is the halo-server base URL rendered workflows exchange their
	// OIDC token at (identity: workload).
	Server string `yaml:"server,omitempty" json:"server,omitempty"`
	// HaloVersion is the halo release tag rendered workflows install to do
	// that exchange (identity: workload).
	HaloVersion string `yaml:"haloVersion,omitempty" json:"haloVersion,omitempty"`

	Claude  *CloudAgent `yaml:"claude,omitempty" json:"claude,omitempty"`
	Codex   *CloudAgent `yaml:"codex,omitempty" json:"codex,omitempty"`
	Copilot *CloudAgent `yaml:"copilot,omitempty" json:"copilot,omitempty"`
	Cursor  *CloudAgent `yaml:"cursor,omitempty" json:"cursor,omitempty"`
	Gemini  *CloudAgent `yaml:"gemini,omitempty" json:"gemini,omitempty"`
}

type CloudConcurrency struct {
	PerUser  int `yaml:"perUser,omitempty" json:"perUser,omitempty"`
	PerGroup int `yaml:"perGroup,omitempty" json:"perGroup,omitempty"`
	// Groups that each get a PerGroup counter (required with perGroup).
	Groups []string `yaml:"groups,omitempty" json:"groups,omitempty"`
}

type CloudIdentity struct {
	// User is the Halos user id (what rings, experiments and budgets key on).
	User string `yaml:"user" json:"user"`
	// GitHub is the GitHub login that triggers GitHub-hosted agents
	// (Claude and Gemini actions, Copilot cloud agent).
	GitHub string `yaml:"github,omitempty" json:"github,omitempty"`
}

type CloudNetwork struct {
	// Mode: none (no egress), allowlist (only Allow, plus the vendor's
	// package-registry list when Recommended) or full (any host; warned).
	Mode string `yaml:"mode" json:"mode"`
	// Allow are extra domains (a leading "*." matches subdomains).
	Allow []string `yaml:"allow,omitempty" json:"allow,omitempty"`
	// Recommended keeps the vendor's own dependency allowlist (allowlist only).
	Recommended bool `yaml:"recommended,omitempty" json:"recommended,omitempty"`
}

type Credential struct {
	Env    string `yaml:"env,omitempty" json:"env,omitempty"`
	File   string `yaml:"file,omitempty" json:"file,omitempty"`
	Scheme string `yaml:"scheme,omitempty" json:"scheme,omitempty"`
}

type CredentialRef struct {
	// IDs is the credential's jti, then its ancestors' (parent first).
	IDs []string
	// IssuedAt is the credential's iat (unix seconds).
	IssuedAt int64
}

type DLP struct {
	// Secrets: outbound secret detection on request content.
	Secrets DLPSecrets `yaml:"secrets,omitempty" json:"secrets,omitzero"`
	// Injection: prompt-injection signals on tool results entering the model.
	Injection DLPInjection `yaml:"injection,omitempty" json:"injection,omitzero"`
	// Rules override the actions per ring and org unit; the first rule whose
	// rings and units both match the caller wins.
	Rules []DLPRule `yaml:"rules,omitempty" json:"rules,omitempty"`
	// MaxScanBytes bounds how much of one request body is scanned (default
	// 4 MiB). A larger body is scanned up to the cap and counted as truncated.
	MaxScanBytes int64 `yaml:"maxScanBytes,omitempty" json:"maxScanBytes,omitempty"`
	// ScanResponses scans streamed and plain responses for echoed secrets
	// (monitor only, halo-proxy). Default true.
	ScanResponses *bool `yaml:"scanResponses,omitempty" json:"scanResponses,omitempty"`
}

type DLPInjection struct {
	// Action: monitor (count and audit) or block (refuse at or above
	// Threshold). Default monitor. Model content is never modified.
	Action string `yaml:"action,omitempty" json:"action,omitempty"`
	// Threshold is the score at which a tool result counts as an injection
	// (default 4).
	Threshold int `yaml:"threshold,omitempty" json:"threshold,omitempty"`
}

type DLPPattern struct {
	ID    string `yaml:"id" json:"id"`
	Regex string `yaml:"regex" json:"regex"`
}

type DLPRule struct {
	Rings     []string `yaml:"rings,omitempty" json:"rings,omitempty"`
	Units     []string `yaml:"units,omitempty" json:"units,omitempty"`
	Secrets   string   `yaml:"secrets,omitempty" json:"secrets,omitempty"`
	Injection string   `yaml:"injection,omitempty" json:"injection,omitempty"`
}

type DLPSecrets struct {
	// Action: monitor (count and audit), redact (replace each secret with
	// [REDACTED:<detector>:<hash8>]) or block (refuse the request). Default monitor.
	Action string `yaml:"action,omitempty" json:"action,omitempty"`
	// Disable turns built-in detectors off by id.
	Disable []string `yaml:"disable,omitempty" json:"disable,omitempty"`
	// Patterns are org detectors (RE2). The whole match is the secret unless
	// the regex has a capture group, then the first group is.
	Patterns []DLPPattern `yaml:"patterns,omitempty" json:"patterns,omitempty"`
}

type Delegation struct {
	// AllowHooks lets units add hooks.items. Default false: a hook is a shell
	// command every member's harness runs, so a unit owner could otherwise run
	// code on any member's machine.
	AllowHooks bool `yaml:"allowHooks,omitempty" json:"allowHooks,omitempty"`
	// EnvKeys are the env names units may add (exact). Provider, base-URL,
	// proxy and runtime-injection names (see UnitForbiddenEnv) are refused
	// even when listed.
	EnvKeys []string `yaml:"envKeys,omitempty" json:"envKeys,omitempty"`
}

type DelegationChain struct {
	// Actors is the chain: the root's own delegate first, the current actor last.
	Actors []Actor
	// Models narrows the model aliases the credential may call; nil = not
	// narrowed by the credential (policy still applies).
	Models []string
	// ID is the delegated credential's jti (audit correlation).
	ID string
	// AuthTime is when the root authenticated (unix seconds, the signed
	// auth_time claim): a human root's session revocation after it kills the chain.
	AuthTime int64
}

type Egress struct {
	// AllowedDomains is the allowlist: exact hosts or *.domain (subdomains only).
	AllowedDomains []string `yaml:"allowedDomains,omitempty" json:"allowedDomains,omitempty"`
	// Default is allow | deny for hosts no rule matches. Unset: deny when
	// anything is allowed (allowedDomains or presets), allow otherwise.
	Default string `yaml:"default,omitempty" json:"default,omitempty"`
	// DeniedDomains always lose: a deny rule wins over any allow rule. Unions
	// down an extends chain and across units.
	DeniedDomains []string `yaml:"deniedDomains,omitempty" json:"deniedDomains,omitempty"`
	// Presets are named domain sets added to the allowlist (EgressPresets):
	// package-registries | vcs | model-providers.
	Presets []string `yaml:"presets,omitempty" json:"presets,omitempty"`
}

type EgressRules struct {
	Default string   `json:"default"` // allow | deny
	Allow   []string `json:"allow,omitempty"`
	Deny    []string `json:"deny,omitempty"`
}

type Experiment struct {
	Meta   `yaml:",inline"`
	Type   ExperimentType `yaml:"type" json:"type"`
	Axis   Axis           `yaml:"axis" json:"axis"`
	Status string         `yaml:"status,omitempty" json:"status,omitempty"` // draft | running | paused | concluded
	// Rings the experiment draws users from.
	Rings    []string  `yaml:"rings" json:"rings"`
	Variants []Variant `yaml:"variants" json:"variants"`
	// Shadow only: fraction of eligible requests mirrored (0-1).
	SampleRate float64 `yaml:"sampleRate,omitempty" json:"sampleRate,omitempty"`
	// Shadow only: which turns of a sampled session are mirrored. "first"
	// (default) mirrors the opening request; "all" mirrors every step of the
	// session, each replayed on the real prefix (ADR-0014).
	Turns    string   `yaml:"turns,omitempty" json:"turns,omitempty"`
	Metrics  Metrics  `yaml:"metrics" json:"metrics"`
	Stopping Stopping `yaml:"stopping" json:"stopping"`
	// Salt keeps assignment independent across experiments; defaults to Name.
	Salt string `yaml:"salt,omitempty" json:"salt,omitempty"`
}

type ExperimentType string

type ExtensionSet struct {
	// Deny names that must not load. Unions down an extends chain.
	Deny []string `yaml:"deny,omitempty" json:"deny,omitempty"`
	// PluginOnly allows only extensions that arrive via plugins or managed
	// settings (the allowlist is then the allowed marketplaces); user and
	// project sources are blocked.
	PluginOnly bool `yaml:"pluginOnly,omitempty" json:"pluginOnly,omitempty"`
}

type Extensions struct {
	// Marketplaces is the allowlist of plugin marketplace sources; empty = any.
	Marketplaces []Marketplace `yaml:"marketplaces,omitempty" json:"marketplaces,omitempty"`
	// BlockedMarketplaces are sources users may never use. Unions down an extends chain.
	BlockedMarketplaces []Marketplace `yaml:"blockedMarketplaces,omitempty" json:"blockedMarketplaces,omitempty"`
	Plugins             Plugins       `yaml:"plugins,omitempty" json:"plugins,omitempty"`
	Skills              ExtensionSet  `yaml:"skills,omitempty" json:"skills,omitempty"`
	Subagents           ExtensionSet  `yaml:"subagents,omitempty" json:"subagents,omitempty"`
	// OutputStyle selects the harness's output style by name.
	OutputStyle string `yaml:"outputStyle,omitempty" json:"outputStyle,omitempty"`
	// StatusLine runs a managed command to render the status line.
	StatusLine StatusLine `yaml:"statusLine,omitempty" json:"statusLine,omitempty"`
	// Artifacts names halos.yaml supplyChain.artifacts this profile delivers
	// (ADR-0028). Unions down an extends chain.
	Artifacts []string `yaml:"artifacts,omitempty" json:"artifacts,omitempty"`
}

type FieldSource struct {
	Path   string `json:"path"`
	Value  string `json:"value"`
	Source string `json:"source"`
}

type FreezeStatus struct {
	Frozen bool           `json:"frozen"`
	Active []ActiveFreeze `json:"active,omitempty"`
	// NextOpen is the first instant no window covers the change. Zero while
	// an incident freeze holds, or when windows chain for over a year.
	NextOpen time.Time `json:"nextOpen,omitzero"`
}

type FreezeWindow struct {
	Name   string      `yaml:"name" json:"name"`
	Reason string      `yaml:"reason" json:"reason"`
	Scope  ChangeScope `yaml:"scope,omitempty" json:"scope,omitzero"`
	// Timezone is an IANA zone (America/New_York); default UTC. Start, End and
	// Weekly are wall-clock times there, so DST moves the instant, not the time.
	Timezone string `yaml:"timezone,omitempty" json:"timezone,omitempty"`
	// Start and End bound a one-off window [start, end): "2026-12-20T18:00",
	// "2026-12-20" (midnight) or RFC 3339 with an offset.
	Start string `yaml:"start,omitempty" json:"start,omitempty"`
	End   string `yaml:"end,omitempty" json:"end,omitempty"`
	// Weekly repeats every week from From to To.
	Weekly *WeeklyWindow `yaml:"weekly,omitempty" json:"weekly,omitempty"`
}

type Gateway struct {
	Meta `yaml:",inline"`
	// BaseURL is what clients are pointed at (Kong's public listener).
	BaseURL string `yaml:"baseURL" json:"baseURL"`
	// Protocol per harness: anthropic-messages | bedrock-invoke | openai-responses | gemini.
	Protocols map[string]string `yaml:"protocols,omitempty" json:"protocols,omitempty"`
	// Auth: how clients obtain a credential for the auth gateway.
	Auth GatewayAuth `yaml:"auth" json:"auth"`
	// Models maps a stable alias (what clients request) to upstream targets.
	Models map[string]ModelRoute `yaml:"models" json:"models"`
	// Upstreams are named backends (e.g. the orchestrator, direct Anthropic).
	Upstreams map[string]Upstream `yaml:"upstreams" json:"upstreams"`
	// Engine is the data plane that enforces this policy: halo-proxy (default),
	// kong, or external (a gateway Halos does not run, e.g. a company's own API
	// gateway: clients are rendered with each alias's provider model id, since
	// nothing translates aliases). Multi-target routes (weights, failover) are
	// halo-proxy-only; Kong uses each route's first target.
	Engine string `yaml:"engine,omitempty" json:"engine,omitempty"`
	// Pricing is USD per million tokens keyed by provider model id (the model a
	// route target names). It costs gateway usage for Budgets.
	Pricing map[string]ModelPrice `yaml:"pricing,omitempty" json:"pricing,omitempty"`
	// Budgets cap spend per user, group, ring or org (ADR-0017). halo-proxy
	// enforces them; halo-server holds the counters.
	Budgets []Budget `yaml:"budgets,omitempty" json:"budgets,omitempty"`
	// DLP is data-loss prevention and prompt-injection defense on model calls (ADR-0033).
	DLP *DLP `yaml:"dlp,omitempty" json:"dlp,omitempty"`
}

type GatewayAuth struct {
	// HelperCommand prints a short-lived token (used as Claude apiKeyHelper, Codex env_key source, ...).
	HelperCommand string `yaml:"helperCommand,omitempty" json:"helperCommand,omitempty"`
	TTLSeconds    int    `yaml:"ttlSeconds,omitempty" json:"ttlSeconds,omitempty"`
	// IdentityHeader is the header the auth gateway sets with the verified user id.
	IdentityHeader string `yaml:"identityHeader,omitempty" json:"identityHeader,omitempty"`
}

type GitSource struct {
	URL    string `yaml:"url" json:"url"`
	Commit string `yaml:"commit" json:"commit"`
	// Path within the repository ("" = its root).
	Path string `yaml:"path,omitempty" json:"path,omitempty"`
}

type Governance struct {
	// Freezes are change-freeze windows. While one covers a change, the rollout
	// controller does not advance, and promotion and advance proposals are
	// refused. Rollbacks, pauses and the kill switch are always allowed.
	Freezes []FreezeWindow `yaml:"freezes,omitempty" json:"freezes,omitempty"`
	// Approvals are approver quorums. Every rule whose scope covers a change
	// must be met before it goes out.
	Approvals []ApprovalRule `yaml:"approvals,omitempty" json:"approvals,omitempty"`
}

type Grant struct {
	Role   string    `json:"role"`
	Scope  RoleScope `json:"scope"`
	Source string    `json:"source"`
}

type Guardrail func(*Org) []Issue

type HarnessSpec struct {
	// Version is an exact CLI version pin (e.g. "2.1.280"). Required for rings.
	Version string `yaml:"version" json:"version"`
	// Model is this harness's default model alias, replacing models.default
	// for it (e.g. codex-default, so codex does not ask for a Claude alias).
	// Must be a gateway.models alias, and in models.allowed when enforced.
	Model string `yaml:"model,omitempty" json:"model,omitempty"`
	// Overrides are raw, harness-native keys merged last. Escape hatch; the Go guardrails still check them (ADR-0007).
	Overrides map[string]any `yaml:"overrides,omitempty" json:"overrides,omitempty"`
}

type Hook struct {
	// Event: PreToolUse | PostToolUse | SessionStart | Stop | UserPromptSubmit
	Event   string `yaml:"event" json:"event"`
	Matcher string `yaml:"matcher,omitempty" json:"matcher,omitempty"`
	Command string `yaml:"command" json:"command"`
}

type Hooks struct {
	ManagedOnly bool   `yaml:"managedOnly,omitempty" json:"managedOnly,omitempty"`
	Hooks       []Hook `yaml:"items,omitempty" json:"items,omitempty"`
}

type Identity struct {
	Issuer   string `yaml:"issuer,omitempty" json:"issuer,omitempty"`
	ClientID string `yaml:"clientID,omitempty" json:"clientID,omitempty"`
	// Audience expected in gateway bearer tokens; defaults to ClientID.
	Audience string `yaml:"audience,omitempty" json:"audience,omitempty"`
	// UserClaim / GroupsClaim name the JWT claims for subject id and groups.
	UserClaim   string `yaml:"userClaim,omitempty" json:"userClaim,omitempty"`     // default "email"
	GroupsClaim string `yaml:"groupsClaim,omitempty" json:"groupsClaim,omitempty"` // default "groups"
	// AdminGroups hold halo-server's admin role; same as Roles.Admin (kept for
	// existing policy repos).
	AdminGroups []string `yaml:"adminGroups,omitempty" json:"adminGroups,omitempty"`
	// Roles maps halo-server roles to IdP groups (ADR-0015). omitzero keeps
	// the JSON form, and so existing snapshot digests, unchanged when unset.
	Roles RoleGroups `yaml:"roles,omitempty" json:"roles,omitzero"`
	// RoleBindings grant a role over a scope of rings and units to groups
	// and users (ADR-0037); identity.roles and adminGroups stay global.
	// Omitted when empty, so existing snapshot digests are unchanged.
	RoleBindings []RoleBinding `yaml:"roleBindings,omitempty" json:"roleBindings,omitempty"`
	// GroupsOverage is what halo-server's console login does when the ID
	// token says the user's groups did not fit in it (Entra ID past 200
	// groups: _claim_names / hasgroups): deny (default) refuses the login with
	// a clear error; graph reads them from Microsoft Graph with the login's
	// access token (ADR-0036). Never a login with no groups.
	GroupsOverage string `yaml:"groupsOverage,omitempty" json:"groupsOverage,omitempty"`
	// RequireAcr: the console login's ID token acr must be one of these.
	// RequireAmr: its amr must contain at least one of these (e.g. [mfa]).
	// halo-server console login only; gateways do not check them (ADR-0036).
	RequireAcr []string `yaml:"requireAcr,omitempty" json:"requireAcr,omitempty"`
	RequireAmr []string `yaml:"requireAmr,omitempty" json:"requireAmr,omitempty"`
}

type ImportOptions struct {
	ID     string // registry id; default derived from the server.json name
	Remote bool   // pin the remote (streamable HTTP) endpoint, not a package
	SHA256 string // image digest, required for an oci package
}

type Issue struct {
	Severity Severity
	Path     string
	Message  string
}

type Kind string

type Loosening struct {
	Field   string // e.g. "permissions.sandbox"
	Message string
}

type MCP struct {
	// ManagedOnly blocks every server not listed here.
	ManagedOnly bool        `yaml:"managedOnly,omitempty" json:"managedOnly,omitempty"`
	Servers     []MCPServer `yaml:"servers,omitempty" json:"servers,omitempty"`
	Denied      []string    `yaml:"denied,omitempty" json:"denied,omitempty"`
}

type MCPAuth struct {
	// Mode: none (default) | oauth | enterprise | halos.
	Mode string `yaml:"mode,omitempty" json:"mode,omitempty"`
	// Issuer is the server's authorization server issuer (oauth, enterprise).
	Issuer string `yaml:"issuer,omitempty" json:"issuer,omitempty"`
	// ClientID is a pre-registered OAuth client id (oauth: at the server's
	// authorization server; enterprise: at the org IdP).
	ClientID string `yaml:"clientID,omitempty" json:"clientID,omitempty"`
	// ClientIDMetadataURL is the https URL of a Client ID Metadata Document
	// the org hosts (oauth): the URL is the client id.
	ClientIDMetadataURL string   `yaml:"clientIDMetadataURL,omitempty" json:"clientIDMetadataURL,omitempty"`
	Scopes              []string `yaml:"scopes,omitempty" json:"scopes,omitempty"`
}

type MCPFinding struct {
	Harness string `json:"harness"`
	File    string `json:"file"`
	Server  string `json:"server"`
	// Kind: unapproved | version-drift.
	Kind string `json:"kind"`
	// Transport: stdio | http.
	Transport string `json:"transport,omitempty"`
	// Host of an http server's URL (no userinfo, path or query).
	Host string `json:"host,omitempty"`
	// DefinitionSHA256 is the hex sha256 of the full user definition (URL, or
	// command and arguments), to tell definitions apart without showing them.
	DefinitionSHA256 string `json:"definitionSha256,omitempty"`
	Detail           string `json:"detail"`
	Fix              string `json:"fix"`
}

type MCPPackage struct {
	// Type: npm | pypi | oci | binary.
	Type string `yaml:"type" json:"type"`
	// Identifier is the package name (npm, pypi) or image reference without
	// tag or digest (oci). Unused for binary.
	Identifier string `yaml:"identifier,omitempty" json:"identifier,omitempty"`
	// Version is the exact version (npm, pypi; no ranges, no "latest"), or the
	// image tag for information (oci).
	Version string `yaml:"version,omitempty" json:"version,omitempty"`
	// SHA256 is "sha256:<hex>": the image digest (oci, required) or the
	// executable's digest (binary, required; halod checks it).
	SHA256 string `yaml:"sha256,omitempty" json:"sha256,omitempty"`
	// Args are appended to the derived command line.
	Args []string `yaml:"args,omitempty" json:"args,omitempty"`
}

type MCPPin struct {
	ID      string      `json:"id"`
	URL     string      `json:"url,omitempty"`
	Command []string    `json:"command,omitempty"`
	Package *MCPPackage `json:"package,omitempty"`
	// Units, when set, are the only units (and units below them) that get it;
	// empty = every member of the ring.
	Units []string `json:"units,omitempty"`
}

type MCPRegistry struct {
	// Mode: allowlist (default) | warn.
	Mode    string           `yaml:"mode,omitempty" json:"mode,omitempty"`
	Servers []RegistryServer `yaml:"servers" json:"servers"`
}

type MCPServer struct {
	Name    string            `yaml:"name" json:"name"`
	URL     string            `yaml:"url,omitempty" json:"url,omitempty"`
	Command []string          `yaml:"command,omitempty" json:"command,omitempty"`
	Headers map[string]string `yaml:"headers,omitempty" json:"headers,omitempty"`
	// Tools and Auth (ADR-0029) are usually filled from the halos.yaml mcp
	// registry; omitzero keeps existing snapshot digests unchanged when unset.
	Tools MCPTools `yaml:"tools,omitempty" json:"tools,omitzero"`
	Auth  MCPAuth  `yaml:"auth,omitempty" json:"auth,omitzero"`
}

type MCPTokenDecision struct {
	Allow  bool
	Server string
	Ring   string
	Unit   string
	Reason string
}

type MCPTools struct {
	Allow []string `yaml:"allow,omitempty" json:"allow,omitempty"`
	Deny  []string `yaml:"deny,omitempty" json:"deny,omitempty"`
}

type Marketplace struct {
	// Source: github | git | url | hostPattern
	Source      string `yaml:"source" json:"source"`
	Repo        string `yaml:"repo,omitempty" json:"repo,omitempty"`
	URL         string `yaml:"url,omitempty" json:"url,omitempty"`
	Ref         string `yaml:"ref,omitempty" json:"ref,omitempty"`
	HostPattern string `yaml:"hostPattern,omitempty" json:"hostPattern,omitempty"`
}

type Membership struct {
	// Users are explicit user ids always in this ring (checked before Groups).
	Users []string `yaml:"users,omitempty" json:"users,omitempty"`
	// Groups are IdP groups always in this ring.
	Groups []string `yaml:"groups,omitempty" json:"groups,omitempty"`
	// Percent of remaining users hashed into this ring (0-100, basis points precision).
	Percent float64 `yaml:"percent,omitempty" json:"percent,omitempty"`
	// Default marks the catch-all ring (GA).
	Default bool `yaml:"default,omitempty" json:"default,omitempty"`
	// OptIn lets developers join this ring themselves from the portal
	// (recorded as a group membership request; admins may auto-approve).
	OptIn bool `yaml:"optIn,omitempty" json:"optIn,omitempty"`
}

type Meta struct {
	APIVersion string            `yaml:"apiVersion" json:"apiVersion"`
	Kind       Kind              `yaml:"kind" json:"kind"`
	Name       string            `yaml:"name" json:"name"`
	Labels     map[string]string `yaml:"labels,omitempty" json:"labels,omitempty"`
}

type MetricDef struct {
	Name        string
	Unit        string // unit of the value, e.g. ratio, ms, usd
	Description string
	Sources     map[string]string
	// Source lists where values come from. When a metric has both online
	// sources, internal/promote prefers the gateway for an experiment that has
	// gateway data (exact cohort attribution), else the CLI events.
	Source []SignalSource
	// PerUnit defines one analysis sample: experiments compare the per-unit
	// values of the two arms. CLI unit = user.id (Codex: user.account_id, else
	// conversation.id; Gemini: installation.id); gateway unit = salted hash
	// of the session id (else of the verified subject).
	PerUnit string
	// Better is the direction of improvement ("increase" | "decrease"); when
	// set, goals on this metric must use it. Empty = not enforced.
	Better string
}

type MetricGoal struct {
	// Metric is a normalised halo.* metric name, e.g. halo.task.success, halo.cost.usd_per_session.
	Metric string `yaml:"metric" json:"metric"`
	// Direction: increase | decrease
	Direction string `yaml:"direction" json:"direction"`
	// MaxRegression (guardrails): relative worsening that aborts, e.g. 0.05 = 5%.
	MaxRegression float64 `yaml:"maxRegression,omitempty" json:"maxRegression,omitempty"`
}

type Metrics struct {
	Primary    MetricGoal   `yaml:"primary" json:"primary"`
	Guardrails []MetricGoal `yaml:"guardrails,omitempty" json:"guardrails,omitempty"`
}

type ModelChoice []string

type ModelPrice struct {
	InputPerMTok      float64 `yaml:"inputPerMTok" json:"inputPerMTok"`
	OutputPerMTok     float64 `yaml:"outputPerMTok" json:"outputPerMTok"`
	CacheReadPerMTok  float64 `yaml:"cacheReadPerMTok,omitempty" json:"cacheReadPerMTok,omitempty"`
	CacheWritePerMTok float64 `yaml:"cacheWritePerMTok,omitempty" json:"cacheWritePerMTok,omitempty"`
}

type ModelRoute struct {
	Upstream string `yaml:"upstream,omitempty" json:"upstream,omitempty"`
	// Model is the provider model id / Bedrock inference profile ARN.
	Model   string        `yaml:"model,omitempty" json:"model,omitempty"`
	Targets []RouteTarget `yaml:"targets,omitempty" json:"targets,omitempty"`
}

type Models struct {
	Default string   `yaml:"default" json:"default"`
	Allowed []string `yaml:"allowed,omitempty" json:"allowed,omitempty"`
	// Enforce rejects models outside Allowed rather than just hiding them.
	Enforce bool `yaml:"enforce,omitempty" json:"enforce,omitempty"`
}

type Org struct {
	Name        string
	Identity    Identity
	SelfService SelfService
	Gateway     *Gateway
	Profiles    map[string]*Profile
	Rings       []*Ring // ordered, earliest ring first
	Experiments []*Experiment
	Toggles     []*Toggle `json:",omitempty"` // omitted when empty: existing snapshots keep their digest

	// Rollouts are omitted when empty, like Toggles.
	Rollouts []*Rollout `json:",omitempty"`

	// Units are the org hierarchy (ADR-0018), omitted when empty like Toggles.
	Units []*Unit `json:",omitempty"`

	// Delegation is what units may add beyond the baseline (ADR-0018); omitted
	// when unset, like Toggles.
	Delegation *Delegation `json:",omitempty"`

	// Sources records which repo-relative file declared each document, so
	// Validate can keep unit directories (delegated by CODEOWNERS) to Unit
	// documents. Not part of the snapshot.
	Sources []Source `json:"-"`

	// Workloads federates CI / cloud workload identities (ADR-0023); omitted
	// when unset, like Toggles.
	Workloads *Workloads `json:",omitempty"`

	// Agents governs delegated and remote agents (ADR-0024); omitted when
	// unset, like Toggles.
	Agents *Agents `json:",omitempty"`

	// VendorAdmin drives the vendors' cloud admin consoles (ADR-0025); omitted
	// when unset, like Toggles.
	VendorAdmin *VendorAdmin `json:",omitempty"`

	// CloudAgents governs vendor-hosted background agents (ADR-0034); omitted
	// when unset, like Toggles.
	CloudAgents *CloudAgents `json:",omitempty"`

	// Governance holds change-freeze windows and approval quorums (ADR-0030);
	// omitted when unset, like Toggles.
	Governance *Governance `json:",omitempty"`

	// SupplyChain declares the extension artifacts releases deliver
	// (ADR-0028); omitted when unset, like Toggles.
	SupplyChain *SupplyChain `json:",omitempty"`

	// ArtifactContent is each artifact's resolved content, keyed by name:
	// path sources read by Load, remote sources fetched by the release
	// build. Not part of the snapshot.
	ArtifactContent map[string]*ArtifactContent `json:"-"`

	// MCP is the approved MCP server registry (ADR-0029); omitted when unset,
	// like Toggles.
	MCP *MCPRegistry `json:",omitempty"`

	// Deprecations are load-time warnings (one per file still on a deprecated
	// apiVersion) that Validate reports. Not part of the snapshot.
	Deprecations []Issue `json:"-"`
}

type Overlay struct {
	Models       Models            `yaml:"models,omitempty" json:"models,omitempty"`
	Permissions  Permissions       `yaml:"permissions,omitempty" json:"permissions,omitempty"`
	MCP          MCP               `yaml:"mcp,omitempty" json:"mcp,omitempty"`
	Hooks        Hooks             `yaml:"hooks,omitempty" json:"hooks,omitempty"`
	Telemetry    Telemetry         `yaml:"telemetry,omitempty" json:"telemetry,omitempty"`
	Egress       Egress            `yaml:"egress,omitempty" json:"egress,omitempty"`
	Sandbox      Sandbox           `yaml:"sandbox,omitempty" json:"sandbox,omitzero"`
	Instructions string            `yaml:"instructions,omitempty" json:"instructions,omitempty"`
	Env          map[string]string `yaml:"env,omitempty" json:"env,omitempty"`
	// Agents may only lower maxDepth and narrow remote (ADR-0024).
	Agents AgentLimits `yaml:"agents,omitempty" json:"agents,omitzero"`
}

type Permissions struct {
	// Mode: default | acceptEdits | plan | auto
	Mode          string   `yaml:"mode,omitempty" json:"mode,omitempty"`
	Allow         []string `yaml:"allow,omitempty" json:"allow,omitempty"`
	Deny          []string `yaml:"deny,omitempty" json:"deny,omitempty"`
	Ask           []string `yaml:"ask,omitempty" json:"ask,omitempty"`
	DisableBypass bool     `yaml:"disableBypass,omitempty" json:"disableBypass,omitempty"`
	// Sandbox: harness sandbox policy — off | workspace-write | read-only
	Sandbox string `yaml:"sandbox,omitempty" json:"sandbox,omitempty"`
	// SandboxRequired fails closed: the harness must refuse to run (Claude:
	// sandbox.failIfUnavailable) rather than fall back to unsandboxed
	// execution when its sandbox dependencies are missing.
	SandboxRequired bool `yaml:"sandboxRequired,omitempty" json:"sandboxRequired,omitempty"`
}

type Plugins struct {
	// Enabled plugins are required on.
	Enabled []string `yaml:"enabled,omitempty" json:"enabled,omitempty"`
	// Blocked plugins are required off. Unions down an extends chain.
	Blocked []string `yaml:"blocked,omitempty" json:"blocked,omitempty"`
}

type Profile struct {
	Meta    `yaml:",inline"`
	Extends string `yaml:"extends,omitempty" json:"extends,omitempty"`

	// Harnesses enabled by this profile, keyed by adapter name.
	Harnesses map[string]HarnessSpec `yaml:"harnesses" json:"harnesses"`

	Models      Models      `yaml:"models" json:"models"`
	Permissions Permissions `yaml:"permissions" json:"permissions"`
	MCP         MCP         `yaml:"mcp" json:"mcp"`
	Hooks       Hooks       `yaml:"hooks" json:"hooks"`
	Telemetry   Telemetry   `yaml:"telemetry" json:"telemetry"`
	Egress      Egress      `yaml:"egress" json:"egress"`
	// Sandbox is the agent sandbox: mode, writable roots, protected paths (ADR-0032).
	Sandbox Sandbox `yaml:"sandbox,omitempty" json:"sandbox,omitzero"`
	// Extensions governs agent-extension surfaces: plugins and their marketplaces,
	// skills, subagents, output style and status line.
	Extensions Extensions `yaml:"extensions,omitempty" json:"extensions,omitempty"`
	// Agents lowers the delegation depth and narrows the remote agents for
	// this profile's members (ADR-0024). Gateway and halo-server enforced.
	Agents AgentLimits `yaml:"agents,omitempty" json:"agents,omitzero"`
	// Login restricts how users authenticate: subscription (claude.ai / ChatGPT /
	// Google login) | api (API key or gateway credential). Empty = unrestricted.
	Login string `yaml:"login,omitempty" json:"login,omitempty"`
	// Instructions is org-wide memory (managed CLAUDE.md / AGENTS.md / GEMINI.md).
	Instructions string `yaml:"instructions,omitempty" json:"instructions,omitempty"`
	// Env is extra environment applied to every harness.
	Env map[string]string `yaml:"env,omitempty" json:"env,omitempty"`

	// Resolved is filled by Org.ResolveProfile from Extensions.Artifacts:
	// the artifacts this profile delivers, with content (ADR-0028).
	Resolved []ResolvedArtifact `yaml:"-" json:"-"`
}

type Provider struct {
	Name    string `yaml:"name" json:"name"`
	Region  string `yaml:"region,omitempty" json:"region,omitempty"`
	Project string `yaml:"project,omitempty" json:"project,omitempty"`
	URL     string `yaml:"url,omitempty" json:"url,omitempty"`
}

type QuorumResult struct {
	Rules []RuleResult `json:"rules"`
	Met   bool         `json:"met"`
	// Ticket is the change's ticket reference ("" = none).
	Ticket string `json:"ticket,omitempty"`
	// Ignored explains approvals that did not count.
	Ignored []string `json:"ignored,omitempty"`
}

type RegistryServer struct {
	// ID is the server name rendered into every harness (and the <server> of
	// its tools' names, e.g. mcp__<id>__<tool>): lowercase letters, digits, '-'.
	ID string `yaml:"id" json:"id"`
	// RegistryName and Version are the official MCP Registry's server.json name
	// and version this entry was imported from (`halo mcp registry import`).
	RegistryName string `yaml:"registryName,omitempty" json:"registryName,omitempty"`
	Version      string `yaml:"version,omitempty" json:"version,omitempty"`
	// Exactly one transport: URL (remote, https), Package (stdio; npm, pypi and
	// oci derive the command line) or Command (stdio; required with a binary package).
	URL     string            `yaml:"url,omitempty" json:"url,omitempty"`
	Command []string          `yaml:"command,omitempty" json:"command,omitempty"`
	Package *MCPPackage       `yaml:"package,omitempty" json:"package,omitempty"`
	Headers map[string]string `yaml:"headers,omitempty" json:"headers,omitempty"`
	Tools   MCPTools          `yaml:"tools,omitempty" json:"tools,omitzero"`
	Auth    MCPAuth           `yaml:"auth,omitempty" json:"auth,omitzero"`
	// Rings and Units it is rendered for: a member of a listed ring, or of a
	// listed unit or one below it. Both empty = rendered for nobody (approved
	// only: a toggle naming it may deliver it).
	Rings []string `yaml:"rings,omitempty" json:"rings,omitempty"`
	Units []string `yaml:"units,omitempty" json:"units,omitempty"`
}

type RemoteAgent struct {
	Name string `yaml:"name" json:"name"`
	// CardURL is the AgentCard, usually https://host/.well-known/agent-card.json.
	CardURL string `yaml:"cardURL" json:"cardURL"`
	// Digest pins the card: "sha256:<hex>" over its RFC 8785 canonical JSON, as
	// `halo agents verify` prints it. A changed card is a policy change.
	Digest string `yaml:"digest" json:"digest"`
	// PublicKey (PEM) or JWKSURL verifies the card's JWS signatures. With
	// either set, an unsigned card or a bad signature fails verification.
	PublicKey string `yaml:"publicKey,omitempty" json:"publicKey,omitempty"`
	JWKSURL   string `yaml:"jwksURL,omitempty" json:"jwksURL,omitempty"`
	// Skills are the card's skill ids members may invoke; empty = any.
	Skills []string `yaml:"skills,omitempty" json:"skills,omitempty"`
	// Rings and Units that may call it: a caller in a listed ring, or in a
	// listed unit or one below it, may. Both empty = nobody.
	Rings []string `yaml:"rings,omitempty" json:"rings,omitempty"`
	Units []string `yaml:"units,omitempty" json:"units,omitempty"`
}

type RemoteDecision struct {
	Allow  bool   `json:"allow"`
	Agent  string `json:"agent,omitempty"`
	Digest string `json:"digest,omitempty"`
	Reason string `json:"reason"`
	Ring   string `json:"ring,omitempty"`
	Unit   string `json:"unit,omitempty"`
}

type ResolvedArtifact struct {
	Name, Kind, Source, Digest, Signer string
	Files                              supplychain.Tree
}

type Resource struct {
	// Rings it affects; AllRings: members of every ring, and of none (an
	// org-wide toggle, a profile shared by several rings, a change whose
	// reach is unknown).
	Rings    []string `json:"rings,omitempty"`
	AllRings bool     `json:"allRings,omitempty"`
	// Units is the unit chain (root first) of the one member it concerns
	// (a device, an access request). AllUnits: members of every unit and of
	// none: rings, experiments, rollouts and toggles draw from the whole org
	// (ADR-0018), so no unit owns them.
	Units    []string `json:"units,omitempty"`
	AllUnits bool     `json:"allUnits,omitempty"`
}

type Ring struct {
	Meta    `yaml:",inline"`
	Order   int    `yaml:"order" json:"order"`
	Profile string `yaml:"profile" json:"profile"`
	// Release pins the ring to an immutable published release digest; empty = build from Profile.
	Release    string     `yaml:"release,omitempty" json:"release,omitempty"`
	Membership Membership `yaml:"membership" json:"membership"`
	// Posture gates gateway access on the device posture halod reports to
	// halo-server (fresh, drift-free, on this ring's release): off | warn | enforce.
	// Empty means warn. Takes effect only on gateways wired to halo-server.
	Posture string `yaml:"posture,omitempty" json:"posture,omitempty"`
	// VersionGate checks the CLI version in the User-Agent against the ring's
	// pinned harness version: off | warn | enforce. Empty means warn.
	VersionGate string `yaml:"versionGate,omitempty" json:"versionGate,omitempty"`
}

type RoleBinding struct {
	Role   string    `yaml:"role" json:"role"`
	Groups []string  `yaml:"groups,omitempty" json:"groups,omitempty"`
	Users  []string  `yaml:"users,omitempty" json:"users,omitempty"`
	Scope  RoleScope `yaml:"scope,omitempty" json:"scope,omitzero"`
}

type RoleGroups struct {
	Viewer   []string `yaml:"viewer,omitempty" json:"viewer,omitempty"`     // read fleet, releases, rollouts, experiments, toggles, policy
	Operator []string `yaml:"operator,omitempty" json:"operator,omitempty"` // viewer + kill switch, experiment status
	Approver []string `yaml:"approver,omitempty" json:"approver,omitempty"` // viewer + decide access requests
	Auditor  []string `yaml:"auditor,omitempty" json:"auditor,omitempty"`   // audit log only
	Admin    []string `yaml:"admin,omitempty" json:"admin,omitempty"`       // everything, incl. devices, sessions, toggle config
}

type RoleScope struct {
	Rings []string `yaml:"rings,omitempty" json:"rings,omitempty"`
	Units []string `yaml:"units,omitempty" json:"units,omitempty"`
}

type Rollout struct {
	Meta `yaml:",inline"`
	Axis Axis `yaml:"axis" json:"axis"`
	// Status: draft | active | paused | aborted | completed ("" = draft).
	Status string `yaml:"status,omitempty" json:"status,omitempty"`
	// Step is the live step's name, set by merged advance PRs ("" = not started).
	Step string `yaml:"step,omitempty" json:"step,omitempty"`
	// Experiment is the backing two-arm experiment: exposure, evidence, kill
	// switch. Optional when every step is progressive or blue-green.
	Experiment string          `yaml:"experiment,omitempty" json:"experiment,omitempty"`
	Change     RolloutChange   `yaml:"change" json:"change"`
	Baseline   RolloutBaseline `yaml:"baseline,omitempty" json:"baseline,omitempty"`
	Steps      []RolloutStep   `yaml:"steps" json:"steps"`
}

type RolloutBaseline struct {
	// Release is the client-axis switch-back target (required with ring-wide steps).
	Release string `yaml:"release,omitempty" json:"release,omitempty"`
}

type RolloutChange struct {
	// Client axis: the release digest ring pointers move to, and its label.
	Release string `yaml:"release,omitempty" json:"release,omitempty"`
	Version string `yaml:"version,omitempty" json:"version,omitempty"`
	// Traffic axis: the gateway model alias whose route becomes the treatment
	// variant's route for it when the rollout completes.
	Alias string `yaml:"alias,omitempty" json:"alias,omitempty"`
}

type RolloutGates struct {
	// Guardrails compare the backing experiment's arms (internal/stats
	// sequential test). A breach triggers OnFailure at any time.
	Guardrails []MetricGoal `yaml:"guardrails,omitempty" json:"guardrails,omitempty"`
	// Scorecard reads a `halo eval run --output json` scorecard.
	Scorecard *ScorecardGate `yaml:"scorecard,omitempty" json:"scorecard,omitempty"`
	// Approval holds the step until a human advances it (`halo rollout advance`).
	Approval bool `yaml:"approval,omitempty" json:"approval,omitempty"`
}

type RolloutPreset struct {
	Name  string
	Rings []Ring
	// Canary is the treatment ramp on the backing experiment, in order.
	Canary []RolloutStep
	// TeamBake is the bake on ring0; RingBake on each later ring before GA.
	TeamBake, RingBake string
}

type RolloutStep struct {
	Name     string          `yaml:"name" json:"name"`
	Strategy RolloutStrategy `yaml:"strategy" json:"strategy"`
	// Ring is required for progressive/blue-green. Percent steps expose the
	// backing experiment's rings; Ring, if set, must be one of them.
	Ring string `yaml:"ring,omitempty" json:"ring,omitempty"`
	// Percent: canary = treatment share; holdout = share kept on control;
	// dark-launch = share of requests mirrored; progressive/blue-green = 100.
	Percent float64 `yaml:"percent,omitempty" json:"percent,omitempty"`
	// Bake is the minimum time at this step: Go duration or N"d" (e.g. "14d").
	Bake       string       `yaml:"bake,omitempty" json:"bake,omitempty"`
	MinSamples int          `yaml:"minSamples,omitempty" json:"minSamples,omitempty"`
	Gates      RolloutGates `yaml:"gates,omitempty" json:"gates,omitempty"`
	// OnFailure: rollback | pause (default rollback).
	OnFailure string `yaml:"onFailure,omitempty" json:"onFailure,omitempty"`
}

type RolloutStrategy string

type Root struct {
	APIVersion string `yaml:"apiVersion,omitempty" json:"apiVersion,omitempty"`
	Kind       string `yaml:"kind,omitempty" json:"kind,omitempty"`
	Org        string `yaml:"org" json:"org"`
	// Identity configures OIDC for the portal, halo-proxy and enrollment (any IdP).
	Identity Identity `yaml:"identity,omitempty" json:"identity,omitempty"`
	// SelfService configures the developer portal (kiosk).
	SelfService SelfService `yaml:"selfService,omitempty" json:"selfService,omitempty"`
	// Workloads federates CI / cloud agents' OIDC tokens (ADR-0023).
	Workloads *Workloads `yaml:"workloads,omitempty" json:"workloads,omitempty"`
	// Agents governs delegated and remote (A2A) agents (ADR-0024).
	Agents *Agents `yaml:"agents,omitempty" json:"agents,omitempty"`
	// VendorAdmin drives the vendors' cloud admin consoles (ADR-0025).
	VendorAdmin *VendorAdmin `yaml:"vendorAdmin,omitempty" json:"vendorAdmin,omitempty"`
	// CloudAgents governs vendor-hosted background agents (ADR-0034).
	CloudAgents *CloudAgents `yaml:"cloudAgents,omitempty" json:"cloudAgents,omitempty"`
	// SupplyChain pins, scans and signs extension artifacts (ADR-0028).
	SupplyChain *SupplyChain `yaml:"supplyChain,omitempty" json:"supplyChain,omitempty"`
	// MCP is the approved MCP server registry (ADR-0029).
	MCP *MCPRegistry `yaml:"mcp,omitempty" json:"mcp,omitempty"`
	// Delegation is what units may add beyond the baseline (ADR-0018).
	Delegation *Delegation `yaml:"delegation,omitempty" json:"delegation,omitempty"`
	// Governance holds change-freeze windows and approval quorums (ADR-0030).
	Governance *Governance `yaml:"governance,omitempty" json:"governance,omitempty"`
	// Simple mode fields (tools, provider, models, ...): see simple.go.
	Simple `yaml:",inline"`
}

type RouteTarget struct {
	Upstream string  `yaml:"upstream" json:"upstream"`
	Model    string  `yaml:"model" json:"model"`
	Weight   float64 `yaml:"weight,omitempty" json:"weight,omitempty"`
	Priority int     `yaml:"priority,omitempty" json:"priority,omitempty"`
	// TimeoutSeconds bounds connect + wait for response headers (default: the
	// proxy's upstreamHeaderTimeout). Streams are not time-limited afterwards.
	TimeoutSeconds int `yaml:"timeoutSeconds,omitempty" json:"timeoutSeconds,omitempty"`
}

type RuleResult struct {
	Rule           string   `json:"rule"`
	Need           int      `json:"need"`
	Have           int      `json:"have"`
	Groups         []string `json:"groups"`
	DistinctGroups bool     `json:"distinctGroups,omitempty"`
	Approvers      []string `json:"approvers"`
	Ticket         string   `json:"ticket,omitempty"` // the pattern the change's ticket must match
	TicketOK       bool     `json:"ticketOK"`
	Met            bool     `json:"met"`
}

type Sandbox struct {
	// Mode: off | workspace-write | read-only. Same field as permissions.sandbox
	// (either may be set; ResolveProfile keeps the two equal).
	Mode string `yaml:"mode,omitempty" json:"mode,omitempty"`
	// WritableRoots are absolute (or ~/) directories writable beyond the
	// workspace, e.g. a build cache. A child list replaces its parent's, like
	// allowedDomains; a unit adding one is a loosening.
	WritableRoots []string `yaml:"writableRoots,omitempty" json:"writableRoots,omitempty"`
	// ProtectedPaths may never be read or written by the agent: credentials
	// (~/.ssh, ~/.aws) and secrets files (.env*). Absolute, ~/ or a
	// workspace-relative glob. Unions down an extends chain and across units.
	ProtectedPaths []string `yaml:"protectedPaths,omitempty" json:"protectedPaths,omitempty"`
}

type ScorecardGate struct {
	// File is the scorecard JSON, relative to the policy dir.
	File    string `yaml:"file" json:"file"`
	Variant string `yaml:"variant" json:"variant"`
	// MinPass1 is the absolute pass@1 floor (0 = none).
	MinPass1 float64 `yaml:"minPass1,omitempty" json:"minPass1,omitempty"`
	// MaxRegression is the largest allowed pass-rate drop vs the scorecard's
	// control (0.02 = 2pp); a significantly worse comparison always fails.
	MaxRegression float64 `yaml:"maxRegression,omitempty" json:"maxRegression,omitempty"`
}

type SelfService struct {
	Enabled bool `yaml:"enabled,omitempty" json:"enabled,omitempty"`
	// Launchers offered to developers: devcontainer | codespaces | coder | laptop.
	Launchers []string `yaml:"launchers,omitempty" json:"launchers,omitempty"`
	// Requestable items: kinds of access developers may request (approval opens a policy PR).
	Requestable []string `yaml:"requestable,omitempty" json:"requestable,omitempty"` // mcp-server | model | ring-opt-in | harness
	// Catalog lists MCP servers developers may request that aren't in their profile yet.
	Catalog []MCPServer `yaml:"catalog,omitempty" json:"catalog,omitempty"`
	// EnrollmentTTLSeconds bounds one-time laptop bootstrap tokens (default 900).
	EnrollmentTTLSeconds int `yaml:"enrollmentTTLSeconds,omitempty" json:"enrollmentTTLSeconds,omitempty"`
}

type ServerJSON struct {
	Name     string `json:"name"`
	Version  string `json:"version"`
	Packages []struct {
		RegistryType string `json:"registryType"`
		Identifier   string `json:"identifier"`
		Version      string `json:"version"`
		Transport    struct {
			Type string `json:"type"`
		} `json:"transport"`
		PackageArguments     []serverJSONArg `json:"packageArguments"`
		RuntimeArguments     []serverJSONArg `json:"runtimeArguments"`
		EnvironmentVariables []struct {
			Name       string `json:"name"`
			IsRequired bool   `json:"isRequired"`
		} `json:"environmentVariables"`
	} `json:"packages"`
	Remotes []struct {
		Type    string `json:"type"`
		URL     string `json:"url"`
		Headers []struct {
			Name string `json:"name"`
		} `json:"headers"`
	} `json:"remotes"`
}

type Severity string

type SignalSource string

type Simple struct {
	// Tools enables harnesses, each pinned to an exact CLI version: a bare
	// version, or {version, model} where model is one of the Models aliases
	// that tool starts on instead of "default" (e.g. codex on an OpenAI model).
	Tools map[string]ToolSpec `yaml:"tools,omitempty" json:"tools,omitempty"`
	// Provider is where models run: a name (anthropic | bedrock | vertex |
	// openai | gemini | multi) or {name, region, project, url}.
	Provider *Provider `yaml:"provider,omitempty" json:"provider,omitempty"`
	// Models maps an alias (what clients ask for; "default" is required) to a
	// provider model id, or to a list of ids tried in failover order. An id may
	// be prefixed "<provider>/" to pick another provider (required with multi).
	Models map[string]ModelChoice `yaml:"models,omitempty" json:"models,omitempty"`
	// Gateway is the base URL clients are pointed at (halo-proxy).
	Gateway string `yaml:"gateway,omitempty" json:"gateway,omitempty"`
	// GatewayEngine is what serves Gateway: halo-proxy (default), kong, or
	// external (your own API gateway; clients are sent provider model ids).
	GatewayEngine string `yaml:"gatewayEngine,omitempty" json:"gatewayEngine,omitempty"`
	// Telemetry is the OTLP/HTTP endpoint (telemetry is always on).
	Telemetry string `yaml:"telemetry,omitempty" json:"telemetry,omitempty"`
	// Team is ring0: IdP groups, or user ids containing "@". Default:
	// identity.adminGroups, else "<org>-ai-platform".
	Team []string `yaml:"team,omitempty" json:"team,omitempty"`
	// Safety preset: strict | standard (default) | relaxed. None bypasses permissions.
	Safety string `yaml:"safety,omitempty" json:"safety,omitempty"`
	// Rollout preset: fast | standard (default) | careful. Sets the rings and
	// the step template `halo upgrade start` and `halo model switch --canary` use.
	Rollout string `yaml:"rollout,omitempty" json:"rollout,omitempty"`
}

type Source struct {
	Path string
	Kind Kind
}

type StatusLine struct {
	Command string `yaml:"command,omitempty" json:"command,omitempty"`
	Padding int    `yaml:"padding,omitempty" json:"padding,omitempty"`
}

type Stopping struct {
	// Method: msprt | fixed
	Method      string  `yaml:"method" json:"method"`
	Alpha       float64 `yaml:"alpha,omitempty" json:"alpha,omitempty"`
	MinSamples  int     `yaml:"minSamples,omitempty" json:"minSamples,omitempty"`
	MaxDays     int     `yaml:"maxDays,omitempty" json:"maxDays,omitempty"`
	MaxSpendUSD float64 `yaml:"maxSpendUSD,omitempty" json:"maxSpendUSD,omitempty"`
}

type Subject struct {
	ID     string
	Groups []string
	// Kind is "" for a human and SubjectWorkload for a CI / cloud workload.
	Kind string
	// Delegation is set when an agent acts for this subject (ADR-0024); ID,
	// Groups and Kind are then the root principal's.
	Delegation *DelegationChain
	// Credential is set when the subject was verified from a credential
	// halo-server signed (workload or delegated agent): what revocation
	// (ADR-0026) is checked against.
	Credential *CredentialRef
}

type SupplyChain struct {
	// Scan: off | warn (default) | enforce. enforce turns scan findings into
	// errors (as does `--strict`).
	Scan string `yaml:"scan,omitempty" json:"scan,omitempty"`
	// RequireSignatures refuses an artifact from outside the policy repo
	// (git or oci) unless it carries a signature by a trusted identity.
	RequireSignatures bool              `yaml:"requireSignatures,omitempty" json:"requireSignatures,omitempty"`
	Artifacts         []Artifact        `yaml:"artifacts,omitempty" json:"artifacts,omitempty"`
	TrustedIdentities []TrustedIdentity `yaml:"trustedIdentities,omitempty" json:"trustedIdentities,omitempty"`
	AllowFindings     []AllowFinding    `yaml:"allowFindings,omitempty" json:"allowFindings,omitempty"`
}

type Telemetry struct {
	Enabled      bool              `yaml:"enabled" json:"enabled"`
	OTLPEndpoint string            `yaml:"otlpEndpoint,omitempty" json:"otlpEndpoint,omitempty"`
	Protocol     string            `yaml:"protocol,omitempty" json:"protocol,omitempty"` // grpc | http/protobuf
	LogPrompts   bool              `yaml:"logPrompts,omitempty" json:"logPrompts,omitempty"`
	Attributes   map[string]string `yaml:"attributes,omitempty" json:"attributes,omitempty"`
}

type Toggle struct {
	Meta        `yaml:",inline"`
	Description string `yaml:"description,omitempty" json:"description,omitempty"`
	// Owner is the team or person who answers for this toggle (required).
	Owner string `yaml:"owner" json:"owner"`
	// Expires (YYYY-MM-DD) is when the toggle should be removed; past it, validate warns.
	Expires string `yaml:"expires,omitempty" json:"expires,omitempty"`
	// Default is the state when no rule matches.
	Default bool `yaml:"default" json:"default"`
	// Axis: client = a settings fragment delivered in the signed release;
	// traffic = a model route switch applied by the gateway.
	Axis Axis `yaml:"axis" json:"axis"`
	// Rules are evaluated in order; the first rule that matches decides.
	Rules []ToggleRule `yaml:"rules,omitempty" json:"rules,omitempty"`
	// Client is the payload of a client-axis toggle.
	Client *ToggleClient `yaml:"client,omitempty" json:"client,omitempty"`
	// Traffic is the payload of a traffic-axis toggle.
	Traffic *ToggleTraffic `yaml:"traffic,omitempty" json:"traffic,omitempty"`
}

type ToggleClient struct {
	Harnesses map[string]TogglePatch `yaml:"harnesses" json:"harnesses"`
}

type TogglePatch struct {
	MCPServers []MCPServer       `yaml:"mcpServers,omitempty" json:"mcpServers,omitempty"`
	Hooks      []Hook            `yaml:"hooks,omitempty" json:"hooks,omitempty"`
	Env        map[string]string `yaml:"env,omitempty" json:"env,omitempty"`
	// Overrides are harness-native keys, restricted to the same allowlist as profile overrides.
	Overrides map[string]any `yaml:"overrides,omitempty" json:"overrides,omitempty"`
}

type ToggleRule struct {
	Name   string   `yaml:"name,omitempty" json:"name,omitempty"`
	Rings  []string `yaml:"rings,omitempty" json:"rings,omitempty"`
	Groups []string `yaml:"groups,omitempty" json:"groups,omitempty"`
	Users  []string `yaml:"users,omitempty" json:"users,omitempty"`
	// Percent (0-100) of the matching subjects, hashed with the toggle's own
	// salt. Omitted = no percent condition; an explicit 0 matches nobody.
	Percent *float64 `yaml:"percent,omitempty" json:"percent,omitempty"`
	// Effect is the state when the rule matches: "on" (default) or "off".
	Effect string `yaml:"effect,omitempty" json:"effect,omitempty"`
}

type ToggleTraffic struct {
	Routes map[string]ModelRoute `yaml:"routes" json:"routes"`
}

type ToolSpec struct {
	Version string `yaml:"version" json:"version"`
	Model   string `yaml:"model,omitempty" json:"model,omitempty"`
}

type TrustedIdentity struct {
	Name      string `yaml:"name" json:"name"`
	PublicKey string `yaml:"publicKey,omitempty" json:"publicKey,omitempty"`
	CosignKey string `yaml:"cosignKey,omitempty" json:"cosignKey,omitempty"`
}

type Unit struct {
	Meta        `yaml:",inline"`
	Description string `yaml:"description,omitempty" json:"description,omitempty"`
	// Parent is the enclosing unit; empty for a top-level unit.
	Parent string `yaml:"parent,omitempty" json:"parent,omitempty"`
	// Owners approve changes to the unit's directory in the policy repo:
	// CODEOWNERS entries such as @acme/payments-platform, @alice or an email.
	Owners []string `yaml:"owners" json:"owners"`
	// Members selects the unit's users from its parent's (or, at the top, the org's).
	Members UnitMembers `yaml:"members" json:"members"`
	// Overlay is what the unit changes on top of the baseline.
	Overlay Overlay `yaml:"overlay,omitempty" json:"overlay,omitempty"`

	// Dir is the repo-relative directory of the file that declares the unit
	// (set by Load). The unit's owners own that directory.
	Dir string `yaml:"-" json:"-"`
	// File is the repo-relative file that declares the unit (set by Load). A
	// top-level unit's file stays with the root owners: its members selector
	// draws from the whole org.
	File string `yaml:"-" json:"-"`
}

type UnitMembers struct {
	Groups []string `yaml:"groups,omitempty" json:"groups,omitempty"`
	Users  []string `yaml:"users,omitempty" json:"users,omitempty"`
}

type Upstream struct {
	// URL is the base URL. Optional for kind vertex (derived from region).
	URL string `yaml:"url,omitempty" json:"url,omitempty"`
	// Kind: orchestrator | anthropic | bedrock | vertex | openai | azure-openai | gemini
	Kind string `yaml:"kind" json:"kind"`
	// Project is the Google Cloud project id for kind vertex.
	Project string `yaml:"project,omitempty" json:"project,omitempty"`
	// APIVersion is the api-version query for kind azure-openai; empty uses the
	// versionless /openai/v1 surface.
	APIVersion string `yaml:"apiVersion,omitempty" json:"apiVersion,omitempty"`
	// Credential names where halo-proxy reads the provider key (kinds openai,
	// azure-openai, gemini). Policy never holds the secret itself.
	Credential *Credential `yaml:"credential,omitempty" json:"credential,omitempty"`
	// Region is the AWS SigV4 region for kind bedrock. halo-proxy signs a
	// bedrock upstream only if its host ends in an AWS suffix (.amazonaws.com,
	// .amazonaws.com.cn, .api.aws) or is listed in the proxy's signHosts; it
	// never signs for other hosts. The region is this value when set, else
	// parsed from the host (e.g. bedrock-runtime.<region>.amazonaws.com).
	Region string `yaml:"region,omitempty" json:"region,omitempty"`
	// Serves lists the client wires an orchestrator upstream answers
	// (anthropic-messages | bedrock-invoke | openai-responses | gemini). An
	// orchestrator may translate, so validate only trusts what is declared here;
	// other kinds' wires are known.
	Serves []string `yaml:"serves,omitempty" json:"serves,omitempty"`
}

type Variant struct {
	Name string `yaml:"name" json:"name"`
	// Weight is the share of the experiment's users (weights are normalised).
	Weight float64 `yaml:"weight" json:"weight"`
	// Traffic axis: model alias -> route override.
	Routes map[string]ModelRoute `yaml:"routes,omitempty" json:"routes,omitempty"`
	// Client axis: profile to apply.
	Profile string `yaml:"profile,omitempty" json:"profile,omitempty"`
	Control bool   `yaml:"control,omitempty" json:"control,omitempty"`
}

type VendorAdmin struct {
	// Ring whose profile the consoles get. Console settings are org-wide, so
	// exactly one ring's profile can win; empty means the last ring (GA).
	Ring    string        `yaml:"ring,omitempty" json:"ring,omitempty"`
	Claude  *VendorTarget `yaml:"claude,omitempty" json:"claude,omitempty"`
	Codex   *VendorTarget `yaml:"codex,omitempty" json:"codex,omitempty"`
	Gemini  *VendorTarget `yaml:"gemini,omitempty" json:"gemini,omitempty"`
	Copilot *VendorTarget `yaml:"copilot,omitempty" json:"copilot,omitempty"`
	Cursor  *VendorTarget `yaml:"cursor,omitempty" json:"cursor,omitempty"`
}

type VendorTarget struct {
	// Org is the tenant: the GitHub organization login (copilot, required),
	// or the Claude organization / ChatGPT workspace / Cursor team id recorded
	// in exported artifacts.
	Org string `yaml:"org,omitempty" json:"org,omitempty"`
	// Project is the Google Cloud project holding the Gemini Code Assist
	// settings (gemini, required).
	Project string `yaml:"project,omitempty" json:"project,omitempty"`
	// Location of the Gemini settings resources (gemini; default global).
	Location string `yaml:"location,omitempty" json:"location,omitempty"`
	// ReleaseChannel pins Gemini Code Assist's release channel (gemini):
	// stable | experimental. Empty leaves the channel unmanaged.
	ReleaseChannel string `yaml:"releaseChannel,omitempty" json:"releaseChannel,omitempty"`
}

type WeeklyWindow struct {
	From string `yaml:"from" json:"from"`
	To   string `yaml:"to" json:"to"`
}

type WireFitness int

type WorkloadIssuer struct {
	Name string `yaml:"name" json:"name"`
	// URL is the exact iss claim; discovery is <url>/.well-known/openid-configuration.
	URL      string `yaml:"url" json:"url"`
	Audience string `yaml:"audience,omitempty" json:"audience,omitempty"`
	// TenantClaim names the claim that identifies the tenant (org, group,
	// account) a token was minted for; every rule of this issuer must match it
	// exactly. Required for an issuer Halos does not know (see TenantClaims);
	// for a known one it may only narrow the choice to one of its claims.
	TenantClaim string `yaml:"tenantClaim,omitempty" json:"tenantClaim,omitempty"`
}

type WorkloadRule struct {
	Name   string `yaml:"name" json:"name"`
	Issuer string `yaml:"issuer" json:"issuer"` // WorkloadIssuer.Name
	// Match: claim name -> exact value or path.Match glob ("*" never crosses "/").
	// Every entry must hold; a missing claim never matches.
	Match map[string]string `yaml:"match" json:"match"`
	// Subject is the workload id; must start with "workload:". {claim}
	// expands to that (matched) claim's value, e.g. workload:gh:{repository}.
	Subject string   `yaml:"subject" json:"subject"`
	Groups  []string `yaml:"groups,omitempty" json:"groups,omitempty"`
	// MaxTTLSeconds bounds the minted credential (default 900, at most 3600).
	MaxTTLSeconds int `yaml:"maxTTLSeconds,omitempty" json:"maxTTLSeconds,omitempty"`
	// contains filtered or unexported fields
}

type Workloads struct {
	// Audience CI tokens must carry (each issuer may override). Required.
	Audience string           `yaml:"audience" json:"audience"`
	Issuers  []WorkloadIssuer `yaml:"issuers" json:"issuers"`
	// Rules are tried in order; the first whose every match entry holds wins.
	Rules []WorkloadRule `yaml:"rules" json:"rules"`
	// Experiments enrolls workloads in experiments like humans. Default false:
	// workload traffic gets control routing and no shadow, so CI runs never
	// skew experiment evidence.
	Experiments bool `yaml:"experiments,omitempty" json:"experiments,omitempty"`
}