release

type Artifact struct {
	URL       string       `json:"url"`
	SHA256    string       `json:"sha256,omitempty"`    // lowercase hex
	Integrity string       `json:"integrity,omitempty"` // SRI "sha512-<base64>" (npm dist.integrity)
	Size      int64        `json:"size,omitempty"`      // exact byte size when known
	Kind      ArtifactKind `json:"kind"`
	BinPath   string       `json:"binPath"`           // binary: installed file name; npm: bin command name
	Package   string       `json:"package,omitempty"` // npm package name
}

type ArtifactKind string

type ArtifactResolver struct {
	HTTP        *http.Client // default: 60s timeout
	ClaudeBase  string       // default https://downloads.claude.ai/claude-code-releases
	NPMRegistry string       // default https://registry.npmjs.org
}

type AttestOptions struct {
	HalosVersion string // version of the halo that built it
	BuilderID    string // default https://github.com/dshakes/halos/cmd/halo@<HalosVersion>
	PolicyRepo   string // policy repo URL, if known
	PolicyCommit string // policy repo commit (git rev-parse HEAD), if known
	PolicyDirty  bool   // the working tree had uncommitted changes
}

type Attestations struct {
	BOM        []byte
	Provenance []byte
}

type CloudAgentFile struct {
	Vendor string   `json:"vendor"`
	Path   string   `json:"path"` // relative to the repository root
	SHA256 string   `json:"sha256"`
	Repos  []string `json:"repos,omitempty"` // policy repo patterns it is for
}

type Experiment struct {
	Name     string              `json:"name"`
	Salt     string              `json:"salt"`
	Variants []ExperimentVariant `json:"variants"`
}

type ExperimentVariant struct {
	Name    string  `json:"name"`
	Weight  float64 `json:"weight"`
	Channel string  `json:"channel"`
}

type FileEntry struct {
	Path   string `json:"path"`
	Mode   uint32 `json:"mode"`
	SHA256 string `json:"sha256"`
	// Artifact/ArtifactPath tie the file to a Manifest.SupplyChain entry and
	// its path inside it; halod checks both before writing (ADR-0028).
	Artifact     string `json:"artifact,omitempty"`
	ArtifactPath string `json:"artifactPath,omitempty"`
}

type HarnessEntry struct {
	Version        string                 `json:"version"`
	InstallCommand map[string]string      `json:"installCommand,omitempty"`
	Files          map[string][]FileEntry `json:"files"`
	// Artifacts are verified install artifacts keyed by "<goos>-<goarch>"
	// (or "any"), filled by ResolveArtifacts; see artifacts.go.
	Artifacts map[string]Artifact `json:"artifacts,omitempty"`
}

type Manifest struct {
	SchemaVersion int                     `json:"schemaVersion"`
	Org           string                  `json:"org"`
	Version       string                  `json:"version"`
	Profile       string                  `json:"profile"`
	Ring          string                  `json:"ring"`
	CreatedAt     time.Time               `json:"createdAt"`
	Harnesses     map[string]HarnessEntry `json:"harnesses"`
	Warnings      []string                `json:"warnings,omitempty"`
	// Experiment/Variant are set on a client-axis variant release only: the
	// release served on channel policy.ChannelName(Ring, Experiment, Variant).
	Experiment string `json:"experiment,omitempty"`
	Variant    string `json:"variant,omitempty"`
	// Experiments (ring releases only) lists the running client-axis
	// experiments enrolling Ring. Signed with the release, it is what halod
	// uses to pick a device's variant channel.
	Experiments []Experiment `json:"experiments,omitempty"`
	// Toggles are the client-axis feature toggles: targeting rules plus the
	// per-harness fragments halod merges for the toggles that are on for it.
	Toggles []ToggleEntry `json:"toggles,omitempty"`
	// Units are the org units (ADR-0018): member selectors plus each unit's
	// rendered files, which halod applies in place of the release's own.
	Units []UnitEntry `json:"units,omitempty"`
	// RemoteAgents pins the A2A agents this ring's members (or some of its
	// units' members) may call, with each AgentCard's digest (ADR-0024):
	// signed with the release, so a changed card is a policy change.
	RemoteAgents []RemoteAgentEntry `json:"remoteAgents,omitempty"`
	// SupplyChain pins the extension artifacts this release delivers
	// (ADR-0028): each one's digest and file listing, signed with the release.
	SupplyChain []SupplyChainEntry `json:"supplyChain,omitempty"`
	// MCPMode and MCPServers carry the halos.yaml mcp registry (ADR-0029):
	// its mode and the servers ring's members (or some of its units' members)
	// get, pinned, so halod reports unapproved and version-drifted servers in
	// user configs. Empty when the policy has no registry.
	MCPMode    string          `json:"mcpMode,omitempty"`
	MCPServers []policy.MCPPin `json:"mcpServers,omitempty"`
	// CloudAgents are the repository files of the workflow-configured cloud
	// agents (ADR-0034), signed with the release for review and the PR that
	// adds them. halod never writes them: they belong in repositories.
	CloudAgents []CloudAgentFile `json:"cloudAgents,omitempty"`
}

type Options struct {
	Org       string          // defaults to the resolver's Org.Name when it is a *policy.Org
	Version   string          // release version label, e.g. "1.4.0"
	CreatedAt time.Time       // zero => Unix epoch, keeping builds reproducible
	OSes      []harness.OS    // defaults to darwin, linux, windows
	Gateway   *policy.Gateway // defaults to Org.Gateway when resolver is a *policy.Org
	// Experiment/Variant mark a client-axis variant release: stamped into the
	// manifest and into the harness config (telemetry resource attributes).
	Experiment, Variant string
	// Experiments is the ring release's client-axis experiment table (see BuildRing).
	Experiments []Experiment
}

type ProfileResolver interface {
	ResolveProfile(name string) (*policy.Profile, error)
}

type Release struct {
	Manifest Manifest
	Blobs    map[string][]byte // sha256 hex -> content
	Tar      []byte
	Digest   string // "sha256:<hex>" of Tar
	// Attestations (AI-BOM and provenance, see Attest) describe the release
	// by digest; they are not part of Tar. bundle.Publish stores them as a
	// signed OCI referrer when set.
	Attestations *Attestations
}

type RemoteAgentEntry struct {
	Name    string   `json:"name"`
	CardURL string   `json:"cardURL"`
	Digest  string   `json:"digest"`
	Skills  []string `json:"skills,omitempty"`
	// Units, when set, are the only units (and units below them) whose
	// members may call it; empty = every member of the ring.
	Units []string `json:"units,omitempty"`
}

type SupplyChainEntry struct {
	Name   string `json:"name"`
	Kind   string `json:"kind"`
	Source string `json:"source"`
	// Digest is supplychain.DigestOf(Files): the content pin.
	Digest string `json:"digest"`
	// Signer is the trusted identity whose signature over Digest verified at
	// build time, if the artifact is signed.
	Signer string `json:"signer,omitempty"`
	// Files is the listing the digest covers: path in the artifact -> sha256
	// hex. Empty when the content was not resolved (nothing is delivered).
	Files map[string]string `json:"files,omitempty"`
}

type ToggleEntry struct {
	Name    string              `json:"name"`
	Default bool                `json:"default"`
	Expires string              `json:"expires,omitempty"`
	Rules   []policy.ToggleRule `json:"rules,omitempty"`
	// Fragments is harness -> OS -> deltas, one per file the toggle changes
	// (FileEntry.Path is the managed file the delta applies to; the blob is
	// JSON, see toggle.Delta). The release's own files are the toggle-off state.
	Fragments map[string]map[string][]FileEntry `json:"fragments,omitempty"`
}

type UnitEntry struct {
	Name   string   `json:"name"`
	Parent string   `json:"parent,omitempty"`
	Groups []string `json:"groups,omitempty"`
	Users  []string `json:"users,omitempty"`
	// Files is harness -> OS -> the files the unit's effective profile renders
	// differently from the release's own: whole files (not deltas), so an
	// overlay can narrow a list. The release's own files are the no-unit state.
	Files map[string]map[string][]FileEntry `json:"files,omitempty"`
}