release

type Actor struct {
	User  string `json:"user,omitempty"`
	Actor string `json:"actor,omitempty"`
}

type AppliedManifest struct {
	// Release is the version label, for the refusal's wording.
	Release string
	// Manifest is what that release recorded.
	Manifest MigrationManifest
}

type Apply struct {
	ID       string `json:"id"`
	Env      string `json:"env"`
	BundleID string `json:"bundle_id"`
	// PromotionID is the binding this apply realizes; "" only for an
	// unreleased bundle (a dev-shaped "deploy my worktree").
	PromotionID string `json:"promotion_id,omitempty"`
	AppliedBy   string `json:"applied_by,omitempty"`
	Run         Run    `json:"run,omitempty"`
	// PlanDigest is the approved plan this apply realizes (O-13).
	PlanDigest string `json:"plan_digest,omitempty"`
	// AcknowledgedFindings are the stop-class finding codes the approver
	// accepted by name.
	AcknowledgedFindings []string `json:"acknowledged_findings,omitempty"`
	// SupersededInFlight records that this apply was started over one that
	// had not finished — a deliberate override.
	SupersededInFlight bool `json:"superseded_in_flight,omitempty"`
	// DeadlineAt is forge's wait budget. Past it with no outcome, the apply
	// reads as abandoned ([ApplyAbandoned]).
	DeadlineAt   time.Time `json:"deadline_at"`
	ImportedFrom string    `json:"imported_from,omitempty"`
	CreatedAt    time.Time `json:"created_at"`
}

type ApplyOutcome struct {
	ApplyID string      `json:"apply_id"`
	Status  ApplyStatus `json:"status"`
	Summary string      `json:"summary,omitempty"`
	// Workloads is the applier's per-resource rollout result: one entry per
	// resource it waited on.
	Workloads []ApplyWorkload `json:"workloads,omitempty"`
	// ReportedBy is set by the BACKEND from the credential, never by the
	// client.
	ReportedBy string    `json:"reported_by,omitempty"`
	FinishedAt time.Time `json:"finished_at"`
}

type ApplyState string

type ApplyStatus string

type ApplyWorkload struct {
	Name    string `json:"name"`
	Cluster string `json:"cluster,omitempty"`
	State   string `json:"state"`
	Detail  string `json:"detail,omitempty"`
}

type Artifact struct {
	Kind Kind `json:"kind"`
	Mode Mode `json:"mode"`
	// Digests maps a variant key → canonical digest. OCI only: for
	// [ModeShared] the only key is [SharedVariant].
	Digests map[string]string `json:"digests,omitempty"`
	// Platforms is the OS/arch set the image manifest advertises.
	// Informational, and NOT part of the artifact's identity.
	Platforms []string `json:"platforms,omitempty"`
	// Source is set exactly for [ModeSource].
	Source *Source `json:"source,omitempty"`
	// Version is how a consumer ASKS for a non-OCI artifact.
	Version string `json:"version,omitempty"`
	// Integrity is how a consumer KNOWS they got the right bytes, in the
	// ecosystem's native hash format. Stored verbatim.
	Integrity string `json:"integrity,omitempty"`
	// URI locates the artifact when name+version does not (a download URL,
	// a non-default registry, or the registry an image was pushed to).
	URI string `json:"uri,omitempty"`
	// BuiltFrom is the git checkout the artifact's build command ran in, when
	// that is a checkout forge can name — a ShellBuild's cwd. Informational
	// provenance like Platforms, and NOT part of the identity: the digest
	// names the bytes, this says where they were built.
	BuiltFrom *BuildSource `json:"built_from,omitempty"`
}

type ArtifactBuildEvent struct {
	Consumer ConsumerKey    `json:"consumer"`
	Artifact ArtifactID     `json:"artifact"`
	Origin   ArtifactOrigin `json:"origin"`
}

type ArtifactChange struct {
	Name   string             `json:"name"`
	Kind   Kind               `json:"kind"`
	Change ArtifactChangeKind `json:"change"`
	From   string             `json:"from,omitempty"`
	To     string             `json:"to,omitempty"`
}

type ArtifactChangeKind string

type ArtifactID string

type ArtifactOrigin struct {
	External *ExternalArtifact `json:"external,omitempty"`
	Release  string            `json:"release"`
	Source   *Source           `json:"source,omitempty"`
	Receipt  *BuildReceipt     `json:"receipt,omitempty"`
}

type Attest struct {
	Provider string `json:"provider"`
	Subject  string `json:"subject"`
	RunID    string `json:"run_id,omitempty"`
}

type BuildInputs struct {
	Recipe        string            `json:"recipe"`
	Sources       []Source          `json:"sources"`
	ContextDigest string            `json:"context_digest"`
	RecipeDigest  string            `json:"recipe_digest"`
	ConfigDigest  string            `json:"config_digest"`
	Tools         map[string]string `json:"tools"`
	Platforms     []string          `json:"platforms"`
	Args          map[string]string `json:"args,omitempty"`
	External      map[string]string `json:"external,omitempty"`
	Outputs       []string          `json:"outputs"`
	Cacheable     bool              `json:"cacheable"`
}

type BuildReceipt struct {
	Inputs           BuildInputs       `json:"inputs"`
	InputDigest      string            `json:"input_digest"`
	WorkingDirectory *BuildSource      `json:"working_directory,omitempty"`
	Outputs          map[string]string `json:"outputs"`
}

type BuildSource struct {
	// Repo is the canonical remote ("github.com/org/repo"); "" when the
	// checkout had none.
	Repo string `json:"repo,omitempty"`
	// Commit is HEAD, full hex.
	Commit string `json:"commit"`
	// Dirty: the checkout had uncommitted changes when the build started.
	Dirty bool `json:"dirty,omitempty"`
}

type BundleClusterTree struct {
	// Cluster is the kubectl context the documents are routed to, or ""
	// for the unclustered tree (objects nothing applies).
	Cluster string `json:"cluster,omitempty"`
	// Path is [BundleClusterPath]'s answer for Cluster: what a
	// Kustomization sets as spec.path.
	Path string `json:"path"`
	// Documents is how many documents the path holds. Carried so a reader
	// can tell an empty tree from an absent one without fetching the
	// layer, and so a Kustomization is never built over zero documents.
	Documents int `json:"documents"`
}

type BundleDoc struct {
	Schema         string    `json:"schema"`
	Snapshot       *Snapshot `json:"snapshot,omitempty"`
	SnapshotDigest string    `json:"snapshot_digest,omitempty"`
	Project        string    `json:"project"`
	Env            string    `json:"env"`
	// Release is the version the bundle pins, or "" for an unreleased
	// bundle (dev, or a Preview deploy) pinned to a build's own digests.
	Release string `json:"release"`
	// ConfigDigest is the digest of the render with every release-bound
	// image reference normalized to its artifact key: the shape of the
	// deploy independent of which release it pins. Two bundles with equal
	// ConfigDigests differ, at most, in images.
	ConfigDigest string     `json:"config_digest"`
	Pins         BundlePins `json:"pins"`
	Provenance   Provenance `json:"provenance"`
	Shape        Shape      `json:"shape"`
	// PlacementPrerequisites is sealed dependency evidence; absent is unknown.
	PlacementPrerequisites *PlacementPrerequisites `json:"placement_prerequisites,omitempty"`
	// Objects describes Shape.Objects for reading — a summary line and a
	// digest per section of each ([ObjectSummary]) — so two bundles can say
	// what changed between them without either's manifests. Beside the shape
	// rather than in it: the shape is bounded and read on every Live page,
	// these are read on a release page. Empty on a bundle built before it.
	Objects []ObjectSummary `json:"objects,omitempty"`
	// ClusterPaths is one entry per path the manifest layer actually
	// carries: the cluster, and the path under which its documents live.
	//
	// THE BUNDLE DESCRIBES ITS OWN LAYOUT so the reconciler's operator
	// builds one Kustomization per cluster without re-deriving anything.
	// It could compute the paths from Shape.Clusters and
	// [BundleClusterPath], and that is exactly the coupling this removes:
	// Shape.Clusters is the env's DECLARED cluster list, while these are
	// the paths the layer HOLDS, and the two differ whenever a declared
	// cluster ends up with no documents routed to it. A Kustomization
	// built for the declared-but-empty cluster points at a path that does
	// not exist, which reconciles green over an env that was never
	// applied.
	//
	// So it is written from the tar entries themselves, after they are
	// written, and a reader can trust it the way it trusts the digest.
	ClusterPaths []BundleClusterTree `json:"cluster_paths,omitempty"`
	// Trees is the v2 layout: one entry per cluster × delivery unit × phase,
	// for every cluster that is not [FlatCluster]. Each carries its
	// dependsOn, its per-attempt timeout and what its health is judged on,
	// so a reconciler builds one Kustomization per entry without deriving
	// anything. A cluster listed here has a [BundleClusterTree] too (its
	// Documents is the sum of its trees'); a flat cluster has no entry.
	// Sorted by Path.
	Trees []BundleTree `json:"trees,omitempty"`
	// Secrets names the Secret objects the env requires in each cluster.
	// NAMES ONLY: a Secret never rides the manifest layer, not even
	// redacted, so the reconciler neither writes nor prunes one. `forge env
	// deploy` syncs them to the cluster itself, before pointing the
	// reconciler at this bundle; a hub-reconciled env reads this list to
	// know what its clusters must already hold.
	Secrets   []BundleSecretRef `json:"secrets,omitempty"`
	CreatedAt time.Time         `json:"created_at"`
}

type BundleHealthCheck struct {
	Kind      string `json:"kind"`
	Namespace string `json:"namespace,omitempty"`
	Name      string `json:"name"`
}

type BundlePins struct {
	Images  map[string]string `json:"images,omitempty"`
	Sources map[string]Source `json:"sources,omitempty"`
}

type BundleReader struct {
	Features []string
}

type BundleRecord struct {
	Snapshot       *Snapshot `json:"snapshot,omitempty"`
	SnapshotDigest string    `json:"snapshot_digest,omitempty"`
	ID             string    `json:"id"`
	Env            string    `json:"env"`
	// Release is the version pinned, "" for an unreleased bundle.
	Release string `json:"release,omitempty"`
	// Digest is the OCI MANIFEST digest: the bundle's identity, and the
	// revision a reconciler reports.
	//
	// THIS IS THE VALUE THE CONTROL PLANE WRITES TO THE HUB OCIRepository'S
	// `spec.ref.digest`, and therefore the value a convergence read compares
	// `Kustomization.status.lastAppliedRevision` against. Measured
	// read-only on the dev hub, the chain is one unchanged string:
	//
	//	spec.ref.digest  ==  status.artifact.revision  ==  lastAppliedRevision
	//	sha256:<64 hex>      sha256:<64 hex>              sha256:<64 hex>
	//
	// and this field is produced in exactly that form ([ValidDigest]
	// enforces it). So the comparison is a plain string equality, which is
	// what control-plane's fluxobserve.judge performs — no normalization,
	// no tag prefix, nothing to strip on either side.
	//
	// It is the MANIFEST digest rather than the manifests LAYER's, and the
	// distinction is the one thing to get right when the hub moves from
	// per-deployment config artifacts to `bundle.v1/<env>`: a bundle's
	// identity, what a promotion names, and what Flux resolves `ref.digest`
	// to are all this one value, while the layer digest is an internal
	// detail of the artifact that nothing outside the bundle addresses.
	// Selecting a layer with `layerSelector` changes which bytes land in the
	// artifact, not which revision the source reports.
	//
	// That last sentence is reasoned from Flux's model (the revision is the
	// resolved manifest digest, fixed before layer extraction) and NOT
	// measured: no OCIRepository on the dev hub sets a layerSelector today,
	// and confirming it needs a cluster that does. It is worth one assertion
	// in the first integration test that points a Kustomization at a bundle
	// — if it were ever false, every env would read as permanently
	// progressing while being perfectly converged.
	Digest string `json:"digest"`
	// Reference is repo@digest, or an OCI-layout reference for a file
	// ledger.
	Reference    string `json:"reference"`
	ConfigDigest string `json:"config_digest"`
	Shape        Shape  `json:"shape"`
	// Objects is the document's [BundleDoc.Objects], kept with the record so
	// a release comparison reads it without fetching the bundle.
	Objects      []ObjectSummary `json:"objects,omitempty"`
	Provenance   Provenance      `json:"provenance"`
	Run          Run             `json:"run,omitempty"`
	CreatedBy    string          `json:"created_by,omitempty"`
	ImportedFrom string          `json:"imported_from,omitempty"`
	CreatedAt    time.Time       `json:"created_at"`
}

type BundleSecretRef struct {
	// Cluster is the kubectl context the Secret belongs in, or "" when the
	// render attributed it to no cluster.
	Cluster   string `json:"cluster,omitempty"`
	Namespace string `json:"namespace,omitempty"`
	Name      string `json:"name"`
}

type BundleTree struct {
	Cluster string `json:"cluster"`
	Unit    string `json:"unit"`
	Phase   Phase  `json:"phase"`
	// Path is [BundleTreePath]'s answer: Kustomization.spec.path, and the
	// tree's identity within the bundle.
	Path      string `json:"path"`
	Documents int    `json:"documents"`
	// DependsOn lists the Paths of the trees that must be Ready first, in
	// this bundle. Sorted.
	DependsOn []string `json:"depends_on,omitempty"`
	// TimeoutSeconds and RetryIntervalSeconds are the per-attempt Flux
	// settings ([TreeTimeoutSeconds], [TreeRetryIntervalSeconds]).
	TimeoutSeconds       int `json:"timeout_seconds"`
	RetryIntervalSeconds int `json:"retry_interval_seconds"`
	// Health is what the tree is ready on: the Jobs and awaited ExternalSecrets
	// of a pre or post tree, the Deployments and StatefulSets of a rollout tree.
	// A DaemonSet is not listed: a node-level rollout (an image prepull) is not
	// a gate, which is also what direct apply waits on. Sorted.
	Health []BundleHealthCheck `json:"health,omitempty"`
	// BudgetSeconds is how long the control plane lets this tree stay
	// "progressing" before it calls it failed. Flux's own wait is one short
	// attempt ([TreeTimeoutSeconds]); this is the whole-rollout allowance the
	// observer enforces instead (design §8.3), so a long rollout is never a
	// false alarm and a stuck one is never forgiven forever. It is derived
	// from the objects the tree is judged on ([TreeBudget]), recorded here so
	// the observer reads it rather than re-deriving it.
	BudgetSeconds int `json:"budget_seconds"`
}

type CaptureOptions struct {
	// ForgeVersion is the rendering binary's version.
	ForgeVersion string
	// WorktreeKey is forge's devstack key for the checkout ("" = primary).
	WorktreeKey string
	// Host names the machine (a daemon id, or HostID()). Never a raw
	// hostname.
	Host string
	// Attestation is the CI identity, when there is one.
	Attestation *Attest
	// contains filtered or unexported fields
}

type Changes struct {
	// Paths are the checkout's own uncommitted changes — tracked edits,
	// deletions, and untracked-unignored files — relative to the top of the
	// checkout, in git's order.
	Paths []string
	// Nested are untracked directories that are the root of ANOTHER git
	// checkout (a parked worktree, a cloned repo), with git's trailing slash.
	// They are not this checkout's content and are not in Paths.
	Nested []string
}

type ChartChange struct {
	// Chart is the forge.HelmChart name that owns the object.
	Chart string
	// Key names the object; Key.Cluster is the kubectl context it lives in.
	Key ObjectKey
	Op  ChartOp
	// Fields are the changed field paths of a ChartChanged object.
	Fields []string
	// Fingerprint is the hash of the desired document (for a removal, of the
	// chart and object). Digested, so an approval names this exact change.
	Fingerprint string
	// LoadBalancer marks a pruned Service holding a load balancer: its
	// external address goes with it.
	LoadBalancer bool
}

type ChartOp string

type ChartPlan struct {
	Changes   []ChartChange
	Unplanned []ChartUnplanned
	// Pruned are the env's own objects the deploy deletes after its rollout
	// (the owned-object prune), and Kept the ones it leaves and why. They ride
	// the chart plan because they, too, are effects of the apply that no bundle
	// diff can see: the bundle says an object left the render, not that the
	// deploy deletes it.
	Pruned []OwnedRemoval
	Kept   []OwnedKept
	// PruneUnplanned says why the prune set could not be read, when it could not.
	PruneUnplanned string
}

type ChartUnplanned struct {
	Chart  string
	Reason string
}

type ClosureError struct {
	Required []ConsumerKey
	Reasons  []string
}

type Commit struct {
	// SHA is the full object id.
	SHA string `json:"sha"`
	// Subject is the first line of the message, bounded at
	// [MaxCommitSubjectBytes].
	Subject string `json:"subject"`
	// Author is the author's name. Never an email: the ledger is shown to
	// every member of an org.
	Author string `json:"author,omitempty"`
	// Time is the committer date, UTC — the same clock as
	// [Provenance.CommitTime].
	Time time.Time `json:"time"`
}

type CommitComparison struct {
	State CommitComparisonState `json:"state"`
	// Reverts is true when To is the OLDER release. Commits are then the
	// ones From has and To does not: what moving From → To takes away.
	Reverts bool `json:"reverts,omitempty"`
	// Commits are newest first, at most MaxComparedCommits, never nil.
	Commits []Commit `json:"commits"`
	// Total is the number of commits between the two when every composed
	// range could count its own; 0 when one could not.
	Total int `json:"total,omitempty"`
	// Truncated says Commits is not every commit between the two.
	Truncated bool `json:"truncated,omitempty"`
	// Releases are the versions whose recorded ranges were composed, newest
	// first.
	Releases []string `json:"releases,omitempty"`
}

type CommitComparisonState string

type CommitRange struct {
	// BaseRelease is the earlier release this range starts after: the newest
	// release of the project, by cut time, whose clean commit is an ancestor
	// of this release's. BaseCommit is that release's commit. Both are empty
	// when the cutting checkout held no such release in its history — the
	// project's first release, or a shallow clone ([CommitRange.Truncated]).
	BaseRelease string `json:"base_release,omitempty"`
	BaseCommit  string `json:"base_commit,omitempty"`
	// Commits are reachable from the release's commit and not from
	// BaseCommit, newest first, at most [MaxRangeCommits]. Empty, never nil,
	// when the release re-cuts its base's commit.
	Commits []Commit `json:"commits"`
	// Total is how many commits the range holds. It equals len(Commits)
	// unless Truncated, and is 0 when Truncated and the count is unknown.
	Total int `json:"total,omitempty"`
	// Truncated says Commits is not the whole range. Either the range is
	// longer than [MaxRangeCommits] (Total says how long), or the checkout's
	// history ended before the base was reached — a shallow clone, which is
	// how CI checks out by default — so the rest, and the count, are
	// unknowable (Total is 0).
	Truncated bool `json:"truncated,omitempty"`
}

type CompatibilityEvidence struct {
	Consumer          ConsumerKey `json:"consumer"`
	Peer              ConsumerKey `json:"peer"`
	Contract          string      `json:"contract"`
	BaseConsumer      string      `json:"base_consumer"`
	CandidateConsumer string      `json:"candidate_consumer"`
	BasePeer          string      `json:"base_peer"`
	CandidatePeer     string      `json:"candidate_peer"`
	PolicyDigest      string      `json:"policy_digest"`
	Validator         string      `json:"validator"`
	ReportDigest      string      `json:"report_digest"`
}

type CompositionDecision struct {
	Consumer ConsumerKey `json:"consumer"`
	Action   string      `json:"action"` // build, reuse, carry
	Reason   string      `json:"reason"`
}

type CompositionInput struct {
	Base      *Snapshot
	Candidate Snapshot
	BaseRef   *SnapshotBase
	Selected  []ConsumerKey
}

type Consumer struct {
	// False is unknown compatibility, not independent release permission.
	DependenciesDeclared bool                 `json:"dependencies_declared"`
	Key                  ConsumerKey          `json:"key"`
	Slots                []string             `json:"slots"`
	DependsOn            []ConsumerDependency `json:"depends_on,omitempty"`
}

type ConsumerBinding struct {
	Consumer ConsumerKey `json:"consumer"`
	Slot     string      `json:"slot"`
	Artifact ArtifactID  `json:"artifact"`
	// Tag is the OCI tag the consumer DECLARED for an external image
	// (`repo:tag@sha256:X` keeps `tag`), and empty for a built image. It is
	// part of the rendered reference, never of the artifact's identity: the
	// bytes are Location@Content either way. Keeping it makes sealing a
	// declared, already-pinned reference byte-identical to what the workload
	// ran before, so sealing alone changes no pod template and rolls nothing.
	Tag string `json:"tag,omitempty"`
}

type ConsumerDependency struct {
	Consumer ConsumerKey `json:"consumer"`
	Contract string      `json:"contract"`
}

type ConsumerKey struct {
	Cluster  string `json:"cluster"`
	Workload string `json:"workload"`
}

type DBQueryPolicy string

type DeliveryMode string

type DeliveryUnit struct {
	Name string `json:"name"`
	// After names the units whose trees must be Ready before this unit's
	// first tree applies. nil means "not declared" (the default applies);
	// a non-nil empty slice means "waits for nothing".
	After []string `json:"after"`
}

type DriftObservation struct {
	Drifted []ObjectKey
}

type EnvKind string

type EnvRecord struct {
	Name          string      `json:"name"`
	Kind          EnvKind     `json:"kind"`
	DeclaredShape *Shape      `json:"declared_shape,omitempty"`
	DeclaredBy    *Provenance `json:"declared_by,omitempty"`
	DeclaredAt    *time.Time  `json:"declared_at,omitempty"`
}

type ExternalArtifact struct {
	Verifier         string `json:"verifier"`
	DescriptorDigest string `json:"descriptor_digest"`
}

type FindingClass string

type FluxFinding struct {
	Rule      string
	Kind      string
	Namespace string
	Name      string
	// Unit is the delivery unit the object is in ([DefaultDeliveryUnit] when it
	// declares none), so a caller that judges only the units a reconciler
	// applies can tell which findings are its own.
	Unit   string
	Reason string
	Fix    string
}

type Gate struct {
	// Name is the check: "lint", "test", "smoke", "rollout", "qa-signoff".
	Name string `json:"name"`
	// Status is the verdict, from the closed set.
	Status GateStatus `json:"status"`
	// RawStatus is the stored status when it was NOT in the closed set —
	// free text from a ledger written before the set closed. Empty on
	// every gate whose status is recognised, so a non-empty value is
	// exactly the signal "this entry predates the vocabulary".
	// Set only by the READ path; never sent.
	RawStatus string `json:"raw_status,omitempty"`
	// URL is where the full report lives (a CI run, an artifact).
	URL string `json:"url,omitempty"`
	// Summary is one line: "412 passed, 0 failed, 3 skipped".
	Summary string `json:"summary,omitempty"`
	// StartedAt and FinishedAt are the check's own window, not when it was
	// recorded. They are what makes a gate a run stage with a duration.
	StartedAt  *time.Time `json:"started_at,omitempty"`
	FinishedAt *time.Time `json:"finished_at,omitempty"`
	// RunID ties this check to one [Run]. Optional: a manual sign-off
	// belongs to a promotion and to no run.
	RunID string `json:"run_id,omitempty"`
	// Details is small, structured and optional — counts and verdicts, not
	// logs. A hosted backend caps it (8 KiB); the full report is behind
	// URL.
	Details map[string]any `json:"details,omitempty"`
	// RecordedBy and RecordedAt are SET BY THE BACKEND that recorded the
	// gate, from the authenticated principal — a user id, or
	// "token:<token-id>". Never accepted from a request, because evidence
	// whose author the author chose is not attributable. A file ledger
	// leaves them empty: it has no principal to attest to.
	RecordedBy string     `json:"recorded_by,omitempty"`
	RecordedAt *time.Time `json:"recorded_at,omitempty"`
}

type GateStatus string

type Git struct {
	Commit string `json:"commit,omitempty"`
	Tag    string `json:"tag,omitempty"`
	// Dirty means the release was cut from a tree with uncommitted changes:
	// its bytes correspond to no reviewable commit.
	Dirty bool `json:"dirty,omitempty"`
}

type ImageChange struct {
	Artifact string `json:"artifact"`
	From     string `json:"from,omitempty"`
	To       string `json:"to,omitempty"`
}

type Kind string

type LayerObject struct {
	Path       string
	Cluster    string
	Unit       string // "" in the v1 layout
	Phase      string // "" in the v1 layout
	APIVersion string
	Kind       string
	Namespace  string
	Name       string
}

type LayerViolation struct {
	// File is the archive entry's path as written, or "(archive)" for a
	// problem with the stream itself (not gzip, not tar, too large).
	File   string
	Reason string
}

type LocalSession struct {
	// ID is minted by forge and stable across heartbeats.
	ID         string     `json:"id"`
	Env        string     `json:"env"`
	Worktree   Worktree   `json:"worktree"`
	Provenance Provenance `json:"provenance"`
	// BundleDigest names the LOCAL bundle the stack runs; the blob never
	// leaves the machine.
	BundleDigest string     `json:"bundle_digest,omitempty"`
	StartedAt    time.Time  `json:"started_at"`
	LastSeenAt   time.Time  `json:"last_seen_at"`
	StoppedAt    *time.Time `json:"stopped_at,omitempty"`
}

type ManifestsLayerError struct {
	Violations []LayerViolation
	// Truncated is true when more violations existed than are listed.
	Truncated bool
}

type ManifestsLayerSummary struct {
	// Files counts every regular file: manifests plus data artifacts.
	Files int
	// Bytes is the sum of the files' bytes, uncompressed.
	Bytes int64
	// Objects is every manifest, sorted by Path.
	Objects []LayerObject
	// Artifacts is every non-manifest data file (observability JSON),
	// sorted. Nothing applies them.
	Artifacts []string
}

type MigrationManifest struct {
	// Sets is one entry per migrations directory, sorted by Source.
	Sets []MigrationSet `json:"sets"`
}

type MigrationSet struct {
	// Source identifies the directory across every machine and every
	// release: the canonical repository and the directory's path within it,
	// e.g. "github.com/reliant-labs/reliant/db/migrations". Two releases'
	// sets are compared only when their Sources are equal, because a
	// migration's version is meaningful only within its own directory —
	// two projects' databases have unrelated schema histories.
	Source string `json:"source"`
	// Commit is the commit the files were read at: the release's own commit
	// for the project's directory, the sibling checkout's for a sibling's.
	// Empty when the bytes were no commit's (a dirty checkout). A claim, for
	// the reader; the check never consults it.
	Commit string `json:"commit,omitempty"`
	// Files are the forward migrations' base names
	// ("20261024035148_hosted_http_action_tickets.up.sql"), sorted by
	// version then name. A name, not only a version, because what a database
	// recorded is one specific file: two branches can claim one version.
	Files []string `json:"files"`
}

type Mode string

type ObjectChange struct {
	Live      ShapeObject `json:"live"`
	Candidate ShapeObject `json:"candidate"`
	// ConfigChanged: the non-image half of the object changed. When either
	// side lacks a ConfigHash the split cannot be made, and ConfigChanged
	// is true whenever the hashes differ (the conservative reading).
	ConfigChanged bool `json:"config_changed"`
	// Images are the release-bound images whose pinned digest changed.
	Images []ImageChange `json:"images,omitempty"`
}

type ObjectChangeKind string

type ObjectComparison struct {
	Deltas    []ObjectDelta `json:"deltas"`
	Unchanged int           `json:"unchanged"`
	// SummariesMissing says at least one bundle carried no object
	// summaries (it was built before they existed), so added, removed and
	// modified objects are named without saying what they are or what in
	// them changed.
	SummariesMissing bool `json:"summaries_missing,omitempty"`
}

type ObjectDelta struct {
	Change   ObjectChangeKind `json:"change"`
	Key      ObjectKey        `json:"key"`
	Workload string           `json:"workload,omitempty"`
	// Summary is the one line: the object's own summary when it was added
	// or removed, and what changed ([DescribeObjectChange]) when modified.
	Summary string `json:"summary,omitempty"`
	// Images are the release-bound images whose digest moved in it.
	Images []ImageChange `json:"images,omitempty"`
	// Parts are the sections that moved, when both sides recorded them.
	Parts []PartChange `json:"parts,omitempty"`
}

type ObjectKey struct {
	Cluster   string `json:"cluster"`
	Kind      string `json:"kind"`
	Namespace string `json:"namespace,omitempty"`
	Name      string `json:"name"`
}

type ObjectMove struct {
	Key  ObjectKey `json:"key"`
	From string    `json:"from"`
	To   string    `json:"to"`
}

type ObjectSummary struct {
	Key ObjectKey `json:"key"`
	// Summary is one value-free line saying what the object declares; ""
	// when there is nothing worth saying beyond its kind and name.
	Summary string `json:"summary,omitempty"`
	// Parts maps a section name to a [PartDigestLen]-hex digest of that
	// section's canonical JSON. Images are excluded: [ShapeObject.Images]
	// already says which artifact digest an object runs.
	Parts map[string]string `json:"parts,omitempty"`
}

type OwnedKept struct {
	Key ObjectKey
	Why string
}

type OwnedRemoval struct {
	Key ObjectKey
	// Fingerprint is the hash of the object's identity and UID, so an approval
	// names this exact object and not a replacement of the same name.
	Fingerprint string
}

type PartChange struct {
	Part   string           `json:"part"`
	Change ObjectChangeKind `json:"change"`
}

type PassedMigration struct {
	// Source is the migrations directory (MigrationSet.Source).
	Source string `json:"source"`
	// File and Version are the migration that can never apply.
	File    string `json:"file"`
	Version uint64 `json:"version"`
	// Head is the highest version the environment's applied releases
	// carried from Source; HeadFile names it and HeadRelease the first
	// release in the applied list (newest first, as callers pass it) that
	// carried it.
	Head        uint64 `json:"head"`
	HeadFile    string `json:"head_file"`
	HeadRelease string `json:"head_release"`
}

type Phase string

type PlacementBinding struct {
	Item         PlacementKey    `json:"item"`
	Object       PlacementObject `json:"object"`
	ManifestHash string          `json:"manifest_hash"`
	JobContract  string          `json:"job_contract,omitempty"`
}

type PlacementEdge struct {
	Predecessor PlacementKey `json:"predecessor"`
	Dependent   PlacementKey `json:"dependent"`
}

type PlacementItem struct {
	Key      PlacementKey `json:"key"`
	Workload string       `json:"workload"`
}

type PlacementKey struct {
	Runtime   string `json:"runtime"`
	Actuator  string `json:"actuator"`
	Cluster   string `json:"cluster"`
	Namespace string `json:"namespace"`
	Kind      string `json:"kind"`
	Name      string `json:"name"`
}

type PlacementObject struct {
	Cluster    string `json:"cluster"`
	APIVersion string `json:"api_version"`
	Kind       string `json:"kind"`
	Namespace  string `json:"namespace"`
	Name       string `json:"name"`
}

type PlacementPrerequisites struct {
	Version  int                `json:"version"`
	Items    []PlacementItem    `json:"items"`
	Edges    []PlacementEdge    `json:"edges"`
	Bindings []PlacementBinding `json:"bindings"`
}

type Plan struct {
	Digest string `json:"digest"`
	// BaseDigest is the digest before chart findings were folded in by
	// [Plan.WithCharts]; empty when none were. Never serialized: it exists for
	// the write to a control plane that recomputes the plan without charts.
	BaseDigest     string        `json:"-"`
	EnvironmentID  string        `json:"environment_id"`
	BundleID       string        `json:"bundle_id"`
	ReleaseVersion string        `json:"release_version,omitempty"`
	LiveBasis      PlanBasis     `json:"live_basis"`
	Findings       []PlanFinding `json:"findings"`
	// ConfigIdentical: the bundle's config digest equals the live one, so
	// the deploy changes images at most. A no-op deploy says so instead of
	// manufacturing a diff to approve.
	ConfigIdentical bool      `json:"config_identical"`
	ComputedAt      time.Time `json:"computed_at"`
}

type PlanBasis struct {
	CurrentPromotionID  string `json:"current_promotion_id,omitempty"`
	AppliedBundleID     string `json:"applied_bundle_id,omitempty"`
	AppliedConfigDigest string `json:"applied_config_digest,omitempty"`
	DriftObserved       bool   `json:"drift_observed"`
}

type PlanFinding struct {
	Code    string       `json:"code"`
	Class   FindingClass `json:"class"`
	Section string       `json:"section"`
	// Subject is "<cluster>/<kind>/<ns>/<name>" for an object, else the
	// workload, artifact or secret name, or the section for an unknown.
	Subject string `json:"subject"`
	// Detail is human-readable and NEVER a secret value. Not digested.
	Detail string `json:"detail,omitempty"`
	// Fingerprint pins the CONTENT a finding is about when no bundle does:
	// the hash of a chart object's desired document. It is digested, so an
	// approval of a plan names the exact chart change and not just the
	// object's name. Empty for every bundle-backed finding, which keeps their
	// digests what they always were.
	Fingerprint string `json:"fingerprint,omitempty"`
}

type PlanInput struct {
	EnvironmentID  string
	BundleID       string
	ReleaseVersion string

	Candidate             Shape
	CandidateConfigDigest string

	// Live is the applied bundle's shape, else the env's declared shape;
	// nil when nothing is recorded (every object then reads as added, and
	// the plan carries an unknown finding).
	Live *Shape
	// Basis is the live state the plan is bound to. AppliedConfigDigest is
	// also what ConfigIdentical compares against.
	Basis PlanBasis

	// Drift is the live-cluster observation: nil when drift is not
	// observable for this env (an unknown finding), else the objects found
	// diverged from the applied bundle (possibly none).
	Drift *DriftObservation
	// SecretPresence maps a secret name to whether its value is set, for
	// the secrets whose presence the caller COULD read: a managed store, or
	// the target cluster's Secrets when the caller is the one applying to
	// it. A name the map does not contain is UNVERIFIABLE — a store or a
	// cluster that could not be read — never "missing": one env commonly
	// mixes providers, and reading every unread secret as missing would make
	// the warning meaningless. nil means nothing could be read.
	//
	// It is consulted for every declared secret: a newly declared one is a
	// finding either way (info when present), and a previously declared one
	// is a finding only when explicitly false — declared at the last apply,
	// missing now.
	SecretPresence map[string]bool

	// Charts is what the env's forge.HelmChart platform deps would change in
	// their clusters. A chart is applied on its own path and rides no bundle,
	// so the shapes above cannot see it; the caller observes it and BuildPlan
	// folds it into the same sections, under the same digest.
	Charts ChartPlan
}

type Promotion struct {
	// Frozen complete desired state; absent only on historical promotions.
	Snapshot       *Snapshot `json:"snapshot,omitempty"`
	SnapshotDigest string    `json:"snapshot_digest,omitempty"`
	BundleID       string    `json:"bundle_id,omitempty"`
	BundleDigest   string    `json:"bundle_digest,omitempty"`
	// ID is assigned by the backend that recorded the entry.
	ID string `json:"id,omitempty"`
	// Env is the environment name.
	Env string `json:"env"`
	// Release is the version label bound.
	Release string        `json:"release"`
	Kind    PromotionKind `json:"kind"`
	// FromEnv is the environment this release was promoted FROM, or empty
	// for a first deploy or a direct promote. Makes the promotion PATH auditable.
	FromEnv string `json:"from_env,omitempty"`
	// Resolved is the image → digest pin set FROZEN at promote time. A
	// deploy pins exactly these; nothing re-reads the release later.
	Resolved map[string]string `json:"resolved"`
	// Sources is the source-built half of the same snapshot.
	Sources map[string]Source `json:"sources,omitempty"`
	// Targets names the components a SCOPED deploy moved (`--target api`,
	// `--frontends-only`): workload, frontend or group names as the env
	// declares them, sorted. Empty means the whole release moved.
	//
	// It is what keeps "prod runs v2" honest after `forge env deploy prod v2
	// --target api`: the entry still binds prod to v2 — the release whose
	// pins the deploy shipped — and Targets says only api took them, so a
	// reader asking what a workload runs walks back to the newest entry that
	// [Promotion.Moved] it. Resolved and Sources stay the release's whole
	// pin set either way.
	Targets    []string `json:"targets,omitempty"`
	PromotedBy Actor    `json:"promoted_by,omitempty"`
	// Gates is the PRE-promote evidence, frozen into the entry: what had
	// already passed when the environment was bound.
	Gates []Gate `json:"gates,omitempty"`
	// RecordedGates is the POST-promote evidence — the wait, the smoke, a
	// manual sign-off — appended after the binding. It is a separate field
	// because the promotion entry is append-only: evidence that arrives
	// later cannot be written into Gates without rewriting history, and
	// the distinction is itself meaningful (what was known BEFORE the
	// environment moved, versus what was learned after).
	//
	// A file ledger leaves it empty: there is nowhere to append to a line
	// already written. A hosted backend fills it from its child table.
	RecordedGates []Gate `json:"recorded_gates,omitempty"`
	// Run is the pipeline attempt that made this promotion, or the zero
	// Run for a promotion that belongs to none.
	Run Run `json:"run,omitempty"`
	// FromPromotionID is the SOURCE promotion this one copied pins from —
	// the exact entry, not just the environment. FromEnv names where the
	// bytes came from; this names WHEN, which is what makes a promote
	// chain reconstructible after the source env has moved on.
	FromPromotionID string `json:"from_promotion_id,omitempty"`
	// SupersededInFlight records that this promotion replaced one whose
	// rollout had not finished — a deliberate override, not an accident.
	// Set by the backend that admitted the override; it is the audit trail
	// for "who decided to interrupt a rollout".
	SupersededInFlight bool `json:"superseded_in_flight,omitempty"`
	// Note is the free-form "why" — the most valuable field on a promote
	// that moves an environment backwards.
	Note string `json:"note,omitempty"`
	// PlanDigest is the approved deploy plan this promotion was written
	// under ([Plan.Digest]). Writing the promotion IS the deploy wherever a
	// converger applies it, so the review precedes the record, and this
	// names which review.
	PlanDigest string `json:"plan_digest,omitempty"`
	// ApprovedBy is who approved that plan. A backend sets it from the
	// credential; a client never supplies it as identity.
	ApprovedBy string `json:"approved_by,omitempty"`
	// AcknowledgedFindings are the stop-class finding codes the approver
	// accepted by name.
	AcknowledgedFindings []string `json:"acknowledged_findings,omitempty"`
	// PromotedAt is when the entry was written. It is PROMOTE time, not
	// deploy time: a promotion moves no bytes.
	PromotedAt time.Time `json:"promoted_at"`
}

type PromotionKind string

type Provenance struct {
	// Repo is the canonical remote, e.g. "github.com/reliant-labs/forge".
	// Empty when the checkout has no remote.
	Repo string `json:"repo"`
	// Commit is HEAD, full hex. Empty when the source is not a git tree.
	Commit string `json:"commit"`
	// CommitTime is when Commit was made: the committer date, UTC. It is the
	// start of a lead-time measurement (commit to production), so it is only
	// ever the time of the commit that was BUILT: nil when the checkout was
	// dirty (the bytes are no commit's) or the commit is unknown. It is a
	// claim like Branch, not authority.
	CommitTime *time.Time `json:"commit_time,omitempty"`
	// CommitSubject is Commit's subject line (the first line of its message)
	// and CommitAuthor its author's name, as git reported them, so a release
	// can be read as "abc1234 fix(gateway): …, by alice" without a repository
	// at hand. Set whenever Commit is, dirty or not: a dirty build's Commit is
	// the base it was built on, and Dirty says the bytes are more than that.
	// Claims like Branch. The subject is bounded at [MaxCommitSubjectBytes].
	CommitSubject string `json:"commit_subject,omitempty"`
	CommitAuthor  string `json:"commit_author,omitempty"`
	// Branch is the symbolic ref at build time; empty on a detached HEAD.
	Branch string `json:"branch,omitempty"`
	// Tag is an exact tag at HEAD, if any.
	Tag string `json:"tag,omitempty"`
	// Dirty: tracked OR untracked-unignored changes existed at build time.
	Dirty bool `json:"dirty"`
	// Tree is the git tree hash of the BUILT content, dirty changes
	// included, computed through a temporary index (the user's index is
	// never touched). Empty means it was not hashed — no git, or the
	// working tree was too large to hash within the capture budget, which
	// CaptureProvenance reports as [ErrUnhashed]. A clean checkout's Tree
	// equals HEAD^{tree}.
	Tree string `json:"tree"`
	// Worktree identifies the checkout on its machine.
	Worktree Worktree `json:"worktree"`
	// ForgeVersion is the binary that rendered. A render is a function of
	// (forge, KCL, config), so the same commit rendered by two forges is
	// two different artifacts.
	ForgeVersion string `json:"forge_version"`
	// Attestation is the CI identity that built it, or nil from a laptop.
	Attestation *Attest `json:"attestation,omitempty"`
}

type Release struct {
	// Version is the label ("v1.4.0"). Releases are ADDRESSED by it, in
	// every backend.
	Version string `json:"release"`
	// Project is the forge project (forge.yaml `name`) the version belongs
	// to. A version label is unique within a project, not across an org:
	// two projects may both cut v1.0.0. "" is a release recorded before
	// releases carried a project.
	Project string `json:"project,omitempty"`
	// Git is the legacy provenance view, kept filled from Provenance (see
	// SetProvenance) so readers that predate Provenance keep working.
	Git Git `json:"git"`
	// Provenance is where the release's images were built from. Nil on a
	// release recorded before it existed.
	Provenance *Provenance `json:"provenance,omitempty"`
	// Commits is the source history this release adds over the release it
	// was cut after ([CaptureCommitRange]). Nil when none was recorded: a
	// non-git tree, a forge that predates it, or a capture that failed. Like
	// Provenance it is evidence about the release and not part of its
	// identity — [Release.SameContent] ignores it.
	Commits *CommitRange `json:"commits,omitempty"`
	// Migrations is every migrations directory the release's artifacts
	// embed, as the files each held at the cut ([MigrationManifest]) — what
	// lets a cut and a deploy refuse a release an environment's schema has
	// already passed ([PassedMigrations]). Nil when none was recorded: a
	// release cut before it existed (until backfilled), or a project with no
	// migrations. Evidence like Commits: [Release.SameContent] ignores it.
	Migrations *MigrationManifest `json:"migrations,omitempty"`
	// CreatedAt is when the release was cut.
	CreatedAt time.Time `json:"created_at"`
	// CreatedBy is who cut it, when the backend knows (a hosted ledger
	// does; a file does not).
	CreatedBy string `json:"created_by,omitempty"`
	// Artifacts maps the bare artifact name (an image name, a package name,
	// a frontend name) → its identity.
	Artifacts map[string]Artifact `json:"artifacts"`
	// Catalog and SnapshotIntents freeze complete composition intent. Absent on
	// historical releases, which remain readable but are not snapshot candidates.
	Catalog         map[ArtifactID]SnapshotArtifact `json:"catalog,omitempty"`
	SnapshotIntents map[string]string               `json:"snapshot_intents,omitempty"`
	// Run is the pipeline attempt that cut the release, or the zero Run
	// when a human cut it. It is NOT part of the release's identity:
	// [Release.SameContent] ignores it, so a CI retry that re-cuts the
	// same bytes under a new run id is still an idempotent re-cut.
	Run Run `json:"run,omitempty"`
}

type RenderedExternalSecretsOperator struct {
	Cluster          string `json:"cluster"`
	ConnectedCluster string `json:"connected_cluster,omitempty"`
	Namespace        string `json:"namespace"`
	Version          string `json:"version"`
}

type RenderedGeneratedSecret struct {
	Kind       string `json:"kind"`
	Bytes      int    `json:"bytes,omitempty"`
	Encoding   string `json:"encoding,omitempty"`
	Prefix     string `json:"prefix,omitempty"`
	Length     int    `json:"length,omitempty"`
	Symbols    string `json:"symbols,omitempty"`
	Companion  string `json:"companion,omitempty"`
	CommonName string `json:"common_name,omitempty"`
	ValidDays  int    `json:"valid_days,omitempty"`
}

type RenderedOpenBao struct {
	Name             string `json:"name"`
	Namespace        string `json:"namespace"`
	Image            string `json:"image"`
	Cluster          string `json:"cluster"`
	ConnectedCluster string `json:"connected_cluster,omitempty"`
}

type RenderedStore struct {
	Type    string `json:"type"`
	Project string `json:"project,omitempty"`
}

type RenderedStoreSecret struct {
	Name      string               `json:"name"`
	Namespace string               `json:"namespace"`
	Source    *RenderedStoreSource `json:"source,omitempty"`
	// Clusters are the clusters the Secret is delivered to, resolved by the
	// caller. Not part of the render record.
	Clusters []StoreCluster `json:"-"`
}

type RenderedStoreSource struct {
	Store     RenderedStore                      `json:"store"`
	Data      map[string]string                  `json:"data,omitempty"`
	Generate  map[string]RenderedGeneratedSecret `json:"generate,omitempty"`
	Pin       map[string]int                     `json:"pin,omitempty"`
	Immutable []string                           `json:"immutable,omitempty"`
}

type ResourceKey struct {
	Cluster   string `json:"cluster"`
	Group     string `json:"group"`
	Kind      string `json:"kind"`
	Namespace string `json:"namespace"`
	Name      string `json:"name"`
}

type Run struct {
	// ID is opaque and CALLER-chosen, stable across retries of one
	// attempt: "github:acme/app/12345/1". Stable-across-retries is the
	// property that makes gate recording idempotent on
	// (promotion, name, run id) — a re-run of one CI step must not
	// double-record.
	ID string `json:"id"`
	// URL links to the run in whatever ran it.
	URL string `json:"url,omitempty"`
	// Provider is "github", "gitlab", "manual". DISPLAY ONLY — nothing
	// branches on it, and it is not part of the run's identity. A verb
	// that behaved differently per provider is the thing this field exists
	// to avoid needing.
	Provider string `json:"provider,omitempty"`
}

type RunTimeline struct {
	Run Run `json:"run"`
	// Release is the version label the run concerns, empty when unknown.
	Release string `json:"release,omitempty"`
	// Stages are ordered by StartedAt, oldest first.
	Stages []Stage `json:"stages"`
}

type RuntimeChange struct {
	Workload    string `json:"workload"`
	From        string `json:"from"`
	To          string `json:"to"`
	FromCluster string `json:"from_cluster,omitempty"`
	ToCluster   string `json:"to_cluster,omitempty"`
}

type SecretStage string

type Shape struct {
	Kind      EnvKind         `json:"kind"`
	Workloads []ShapeWorkload `json:"workloads"`
	Secrets   []ShapeSecret   `json:"secrets"`
	Domains   []string        `json:"domains"`
	Clusters  []string        `json:"clusters"`
	Objects   []ShapeObject   `json:"objects"`
	// ControlPlaneSecrets are the Secrets the env's declared control plane
	// supplies and renews (forge.ControlPlaneSecret): where each lands and what
	// to mint into it. It is how the control plane learns what to deliver, so
	// it is recorded on every ensure. Omitted when empty, so an env that
	// declares none encodes, and hashes, exactly as it did before the field.
	ControlPlaneSecrets []ShapeControlPlaneSecret `json:"control_plane_secrets,omitempty"`
	// StoreSecrets are the store names each namespace of each cluster reads
	// from a secret store (forge.ExternalSecret with a forge.StoreSource), with
	// their version pins: what a control plane builds a secretaccess.Request
	// from. GeneratedSecrets are the values to mint when the store has none,
	// OpenBao and ExternalSecretsOperators the components the env declares and
	// where. Names, versions and recipes; never a value. All omitted when the
	// env declares none, so every shape recorded before them encodes and hashes
	// exactly as it did; a control plane that predates them refuses the shape,
	// so they are a bundle-document feature ([BundleFeatureStoreSecrets]). See
	// store_secrets.go.
	StoreSecrets             []ShapeStoreSecret             `json:"store_secrets,omitempty"`
	GeneratedSecrets         []ShapeGeneratedSecret         `json:"generated_secrets,omitempty"`
	OpenBao                  *ShapeOpenBao                  `json:"openbao,omitempty"`
	ExternalSecretsOperators []ShapeExternalSecretsOperator `json:"external_secrets_operators,omitempty"`
	// Alerts are the env's resolved alert rules: its own (forge.AlertRule) plus
	// the generated defaults it did not disable, each tagged with its source.
	// The control plane evaluates them; a rollback restores the rules of the
	// release it returns to. Each entry serializes to pkg/alerting's RuleSpec.
	// Omitted when empty, like ControlPlaneSecrets.
	Alerts []ShapeAlert `json:"alerts,omitempty"`
	// AlertRoutes say which receiver an alert goes to, by label, first match
	// wins unless a route continues. Receivers are NAMES: their secrets live
	// in the control plane. Order is significant and is preserved.
	AlertRoutes []ShapeAlertRoute `json:"alert_routes,omitempty"`
	// ObservabilityPolicy is the env's resolved observability opt-out
	// (forge.Observability): what the author switched off. It is how the
	// platform learns what NOT to collect, enforced at the source (the node
	// agent, the operator's injection, the browser ingest). Omitted when the
	// env declares no observability or opts out of nothing, so every shape
	// recorded before the field encodes and hashes exactly as it did.
	ObservabilityPolicy *ShapeObservabilityPolicy `json:"observability_policy,omitempty"`
	// FrontendTelemetry is what each frontend declares about its browser
	// telemetry beyond the env's observability policy (forge.BrowserTelemetry):
	// the error filters the issue worker applies, the funnels, and what becomes
	// of the build's source maps. One entry per frontend that declares
	// something other than the defaults, sorted by frontend. Omitted when no
	// frontend does, so every shape recorded before the field encodes and
	// hashes exactly as it did. A control plane that predates it refuses the
	// whole shape, so it is a bundle-document feature
	// ([BundleFeatureFrontendTelemetry]).
	FrontendTelemetry []ShapeFrontendTelemetry `json:"frontend_telemetry,omitempty"`
	// DeliveryPolicy is what the env's releases must prove before they ship
	// (forge.DeliveryPolicy): one control per hardening control, each with a
	// mode and its parameters. It is how the control plane learns what to
	// enforce. Omitted when every value is the default, so every shape
	// recorded before the field encodes and hashes exactly as it did; a
	// reader treats absence as [DefaultDeliveryPolicy], never as "off".
	DeliveryPolicy *ShapeDeliveryPolicy `json:"delivery_policy,omitempty"`
	// DataAccess is how the env's data may be read (forge.DataAccess): today
	// whether `forge db query` is open, audited or denied. The control plane
	// enforces it from this recorded shape. Omitted when it is the default, so
	// every shape recorded before the field encodes and hashes exactly as it
	// did; a reader treats absence as [DefaultDataAccess], never as "open". A
	// control plane that predates it refuses the whole shape, so it is a
	// bundle-document feature ([BundleFeatureDataAccess]).
	DataAccess *ShapeDataAccess `json:"data_access,omitempty"`
	// ReleaseHealth is how the env's promotions are judged
	// (forge.ReleaseHealth): the before/after window, the thresholds, and the
	// findings that fail a release. Nil when every value is the default; a
	// reader treats absence as [DefaultReleaseHealth].
	ReleaseHealth *ShapeReleaseHealth `json:"release_health,omitempty"`
	// UptimeChecks are the env's outside-in HTTP checks (forge.UptimeCheck and
	// the ones forge derives for every public frontend and route), sorted by
	// name. The control plane's prober reads them from here. Omitted when the
	// env has none, so every shape recorded before the field encodes and
	// hashes exactly as it did; a control plane that predates it refuses the
	// whole shape, so it is a bundle-document feature
	// ([BundleFeatureUptimeChecks]).
	UptimeChecks []ShapeUptimeCheck `json:"uptime_checks,omitempty"`
	// Identity is the env's managed identity as declared
	// (forge.ManagedIdentity): the instance the control plane's identity
	// reconciler converges, and which workloads consume it. Names and
	// destinations only; every issued value is delivered, never recorded.
	// Omitted when the env declares none, so every shape recorded before the
	// field encodes and hashes exactly as it did.
	Identity *ShapeIdentity `json:"identity,omitempty"`
	// Databases is what the env declares about its managed databases beyond
	// their workload entries: today whether live dashboard panels may query
	// each one, and under which limits (ManagedDatabase.dashboards). One entry
	// per database that ENABLES something, sorted by name. Omitted when none
	// does, so every shape recorded before the field encodes and hashes exactly
	// as it did; a reader treats a database with no entry as dashboards
	// DISABLED, never open ([Shape.DashboardsFor]). A control plane that
	// predates it refuses the whole shape, so it is a bundle-document feature
	// ([BundleFeatureDatabaseDashboards]).
	Databases []ShapeDatabase `json:"databases,omitempty"`
	// Applier is who applies this env when it DECLARES one: "forge" for a real
	// environment none of whose delivery units has moved onto the hub yet (a
	// transitional state, see [ApplierForge]), or "flux" for one an in-cluster
	// Flux reconciles ([ApplierFlux]). Empty means undeclared, and
	// omitted, so every shape recorded before the field encodes and hashes as
	// it did.
	Applier string `json:"applier,omitempty"`
	// Units is who applies each delivery unit of the env: the split between the
	// units the hub converges and the units forge still applies directly. It is
	// recorded only when the env declares one (delivery units, or
	// hub_converges), and omitted otherwise, so every shape recorded before the
	// field encodes and hashes exactly as it did. Sorted by name.
	//
	// It is a DECLARATION about who applies, so it is not part of the config
	// digest: moving a unit onto the hub changes nobody's configuration.
	Units []ShapeUnit `json:"units,omitempty"`
}

type ShapeAlert struct {
	Alert string `json:"alert"`
	Expr  string `json:"expr"`
	// For and Interval are Go duration strings ("5m", "1h30m").
	For           string `json:"for,omitempty"`
	Interval      string `json:"interval,omitempty"`
	KeepFiringFor string `json:"keep_firing_for,omitempty"`
	// Labels always carry `severity`: critical | warning | info.
	Labels      map[string]string `json:"labels,omitempty"`
	Annotations map[string]string `json:"annotations,omitempty"`
	// Source is AlertSourceUser or AlertSourceDefault.
	Source string `json:"source"`
	// DefaultID names the generated default this rule came from.
	DefaultID string `json:"default_id,omitempty"`
}

type ShapeAlertRoute struct {
	Match    map[string]string `json:"match,omitempty"`
	Receiver string            `json:"receiver"`
	Continue bool              `json:"continue,omitempty"`
}

type ShapeApprovals struct {
	Mode      DeliveryMode `json:"mode"`
	Required  int          `json:"required"`
	Approvers []string     `json:"approvers"`
}

type ShapeBundleKinds struct {
	Mode  DeliveryMode `json:"mode"`
	Allow []string     `json:"allow"`
	Deny  []string     `json:"deny"`
}

type ShapeControl struct {
	Mode DeliveryMode `json:"mode"`
}

type ShapeControlPlaneSecret struct {
	Name      string `json:"name"`
	Namespace string `json:"namespace"`
	// Cluster is the kube context the Secret lands in, the same key the
	// shape's workloads and objects use.
	Cluster string `json:"cluster"`
	// ConnectedCluster is the name `forge cluster connect` registered: the
	// credential the control plane delivers with.
	ConnectedCluster string `json:"connected_cluster"`
	// Kind says what the control plane mints into it
	// (ControlPlaneSecretTelemetryToken).
	Kind string   `json:"kind"`
	Keys []string `json:"keys,omitempty"`
	// Delivery is ControlPlaneSecretDeliveryStore when the control plane
	// writes the value into the env's secret store and the External Secrets
	// Operator delivers it (a floating ExternalSecret); empty means the control
	// plane pushes the Secret into the cluster itself. The store the value goes
	// to is in Shape.StoreSecrets, under ControlPlaneSecretStoreName.
	Delivery string `json:"delivery,omitempty"`
	// Required says a workload reads the Secret without an optional marker,
	// so its pods wait for the first delivery instead of starting without it.
	// The control plane reports such an env as waiting on the delivery.
	// Omitted when false, so a shape recorded before the field is unchanged.
	Required bool `json:"required,omitempty"`
}

type ShapeDataAccess struct {
	DBQuery DBQueryPolicy `json:"db_query"`
}

type ShapeDatabase struct {
	Name string `json:"name"`
	// Dashboards is the database's live-dashboard declaration
	// (ManagedDatabase.dashboards in KCL). Nil means disabled.
	Dashboards *ShapeDatabaseDashboards `json:"dashboards,omitempty"`
}

type ShapeDatabaseDashboards struct {
	Enabled        bool `json:"enabled"`
	RowCap         int  `json:"row_cap,omitempty"`
	TimeoutMs      int  `json:"timeout_ms,omitempty"`
	MaxConcurrency int  `json:"max_concurrency,omitempty"`
}

type ShapeDeliveryPolicy struct {
	TrustedBuilder   ShapeTrustedBuilder `json:"trusted_builder"`
	Signing          ShapeSigning        `json:"signing"`
	ProvenanceSBOM   ShapeControl        `json:"provenance_sbom"`
	FluxVerify       ShapeControl        `json:"flux_verify"`
	AdmissionVerify  ShapeControl        `json:"admission_verify"`
	SignedPromotions ShapeControl        `json:"signed_promotions"`
	VulnGate         ShapeVulnGate       `json:"vuln_gate"`
	BundleKinds      ShapeBundleKinds    `json:"bundle_kinds"`
	Approvals        ShapeApprovals      `json:"approvals"`
	// HealthGate is the promotion health gate (forge.HealthGate). Nil is its
	// default — mode enforce, no environments named, so no gate — and is how
	// a policy that declares none encodes, so every shape recorded before
	// the field still hashes as it did. A reader that predates it never sees
	// it: it is the bundle feature [BundleFeatureHealthGate].
	HealthGate *ShapeHealthGate `json:"health_gate,omitempty"`
}

type ShapeDiff struct {
	// LiveUnknown: there was no live shape to compare against (nothing
	// recorded yet). Every candidate object then appears in Added, and a
	// reader must say "no recorded config" rather than present the diff as
	// a real comparison — empty and unknown must never render alike.
	LiveUnknown bool `json:"live_unknown,omitempty"`
	// KindChanged is never set.
	//
	// Deprecated: an env has no placement kind any more — placement is per
	// workload (docs/design/per-workload-placement.md), and a part that moves
	// between placements is reported in RuntimeChanges. Kept only so a reader
	// built against an older forge still decodes the document; removed with
	// Shape.Kind.
	KindChanged *KindChange `json:"kind_changed,omitempty"`

	Added   []ShapeObject  `json:"added,omitempty"`
	Removed []ShapeObject  `json:"removed,omitempty"`
	Changed []ObjectChange `json:"changed,omitempty"`
	// Moved are objects present on both sides, in the same cluster, whose
	// delivery tree differs. Independent of Changed: a move can leave the
	// object's bytes untouched.
	Moved []ObjectMove `json:"moved,omitempty"`

	WorkloadsAdded   []string        `json:"workloads_added,omitempty"`
	WorkloadsRemoved []string        `json:"workloads_removed,omitempty"`
	RuntimeChanges   []RuntimeChange `json:"runtime_changes,omitempty"`
	SecretsAdded     []ShapeSecret   `json:"secrets_added,omitempty"`
	SecretsRemoved   []ShapeSecret   `json:"secrets_removed,omitempty"`
	DomainsAdded     []string        `json:"domains_added,omitempty"`
	DomainsRemoved   []string        `json:"domains_removed,omitempty"`
	ClustersAdded    []string        `json:"clusters_added,omitempty"`
	ClustersRemoved  []string        `json:"clusters_removed,omitempty"`
}

type ShapeExternalSecretsOperator struct {
	Cluster          string `json:"cluster"`
	ConnectedCluster string `json:"connected_cluster,omitempty"`
	Namespace        string `json:"namespace"`
	// Version is the chart version.
	Version string `json:"version"`
}

type ShapeFrontendTelemetry struct {
	// Frontend is the forge frontend's name (the forge.frontend resource
	// attribute its telemetry carries).
	Frontend string `json:"frontend"`
	// Sourcemaps is what becomes of the build's source maps: "public" or
	// "off". Omitted for the default, [SourcemapsPublish].
	Sourcemaps string `json:"sourcemaps,omitempty"`
	// ErrorsIgnore are the declared error filters, in declaration order: a
	// plain entry matches an exception type exactly or a message substring, a
	// "re:" entry is a regular expression over the message. An issue that
	// matches is born ignored.
	ErrorsIgnore []string `json:"errors_ignore,omitempty"`
	// Funnels are the declared product funnels, sorted by id.
	Funnels []ShapeFunnel `json:"funnels,omitempty"`
}

type ShapeFunnel struct {
	ID    string `json:"id"`
	Title string `json:"title,omitempty"`
	// Steps are product event names, in order.
	Steps []string `json:"steps"`
	// Window and By are always set; the KCL schema defaults them.
	Window string `json:"window"`
	By     string `json:"by"`
}

type ShapeGeneratedSecret struct {
	// Store says who mints it: [StoreHosted] (the control plane, at promotion)
	// or [StoreOpenBao] (the component's converge Job, inside the cluster).
	Store string `json:"store"`
	// Kind is a secretgen.Kind.
	Kind string `json:"kind"`
	// Names are the store names written, in secretgen's order: the key first,
	// then its companion for the two-name kinds. Not sorted: the order is
	// meaningful.
	Names []string `json:"names"`

	// Parameters of the kinds that take them; the others carry zero values.
	// Canonical fills the defaults, so a shape that spells them out and one
	// that leaves them to the default are one shape.
	Bytes      int    `json:"bytes,omitempty"`
	Encoding   string `json:"encoding,omitempty"`
	Prefix     string `json:"prefix,omitempty"`
	Length     int    `json:"length,omitempty"`
	Symbols    string `json:"symbols,omitempty"`
	CommonName string `json:"common_name,omitempty"`
	ValidDays  int    `json:"valid_days,omitempty"`
}

type ShapeHealthGate struct {
	Mode  DeliveryMode `json:"mode"`
	After []string     `json:"after"`
}

type ShapeIdentity struct {
	// Name names the outputs (forge-identity-<name>) and the declaration.
	Name string `json:"name"`
	// Runtime is where the instance runs: [IdentityRuntimeHosted] or
	// [IdentityRuntimeHost].
	Runtime string `json:"runtime"`
	// ShareWith is the env of the SAME project that owns the instance this
	// env's applications live in. Empty when this env owns its instance.
	ShareWith string `json:"share_with,omitempty"`
	// ProjectName is the identity project's name. Empty means the env's
	// project; an adopted instance keeps its legacy name here.
	ProjectName string             `json:"project_name,omitempty"`
	Login       ShapeIdentityLogin `json:"login"`
	// Public is the declaration's own claim that the instance needs a public
	// route (hosted login, an explicit public = True). The control plane also
	// raises it for a consumer outside the platform network, which only it
	// can see.
	Public bool `json:"public,omitempty"`
	// Domain is a custom issuer domain (login.acme.com), instead of the
	// assigned <slug>.reliantidentity.com.
	Domain       string                     `json:"domain,omitempty"`
	Roles        []ShapeIdentityRole        `json:"roles,omitempty"`
	Applications []ShapeIdentityApplication `json:"applications,omitempty"`
	Consumers    []ShapeIdentityConsumer    `json:"consumers,omitempty"`
	MachineUsers []ShapeIdentityMachineUser `json:"machine_users,omitempty"`
	SMTP         *ShapeIdentitySMTP         `json:"smtp,omitempty"`
	SeedUsers    []ShapeIdentitySeedUser    `json:"seed_users,omitempty"`
	// Deliveries are the Secrets the control plane writes this identity's
	// outputs into on a connected cluster. Each is ALSO an entry of
	// Shape.ControlPlaneSecrets, which is how the existing delivery path sees
	// it; this list says which of those entries are the identity's.
	Deliveries []ShapeIdentityDelivery `json:"deliveries,omitempty"`
	// ManagedSecrets are the reserved managed-secret names the control plane
	// writes the outputs under for HOSTED consumers. They are not the env's
	// secrets: nobody sets them.
	ManagedSecrets []string `json:"managed_secrets,omitempty"`
}

type ShapeIdentityApplication struct {
	Name string `json:"name"`
	// Workload is the broker: the workload that runs the sign-in endpoint.
	Workload     string   `json:"workload"`
	Kind         string   `json:"kind"`
	RedirectURIs []string `json:"redirect_uris,omitempty"`
	LogoutURIs   []string `json:"logout_uris,omitempty"`
	// LoginURI is the declared literal override. Empty means the control plane
	// derives it from the env's frontend.
	LoginURI string `json:"login_uri,omitempty"`
}

type ShapeIdentityConsumer struct {
	Workload string `json:"workload"`
	// Application is the application this consumer brokers for. Empty for a
	// consumer that only validates tokens.
	Application string `json:"application,omitempty"`
	// Fields maps an output ([IdentityOutputs]) to the config field it fills
	// when that is not the standard one (the 20%: an app that validates two
	// issuers).
	Fields map[string]string `json:"fields,omitempty"`
	// DeliverOnly says the control plane delivers this consumer's Secrets but
	// forge projects nothing into the workload: it still reads its own config.
	DeliverOnly bool `json:"deliver_only,omitempty"`
	// Omit lists outputs ([IdentityOmittableOutputs]) forge does not project
	// into the workload, for an app whose config has no field for them. The
	// Secrets still carry them.
	Omit []string `json:"omit,omitempty"`
}

type ShapeIdentityDelivery struct {
	Kind             string `json:"kind"`
	Name             string `json:"name"`
	Namespace        string `json:"namespace"`
	Cluster          string `json:"cluster"`
	ConnectedCluster string `json:"connected_cluster"`
}

type ShapeIdentityKeySecret struct {
	Name             string `json:"name"`
	Namespace        string `json:"namespace"`
	Cluster          string `json:"cluster"`
	ConnectedCluster string `json:"connected_cluster"`
}

type ShapeIdentityLogin struct {
	Mode string `json:"mode"`
}

type ShapeIdentityMachineUser struct {
	Name  string   `json:"name"`
	Roles []string `json:"roles,omitempty"`
	// KeySecret is where its key is delivered. Required for a hosted
	// instance; a host-run one keeps the key in the env's secret store.
	KeySecret *ShapeIdentityKeySecret `json:"key_secret,omitempty"`
}

type ShapeIdentityRole struct {
	Key         string `json:"key"`
	DisplayName string `json:"display_name,omitempty"`
	Group       string `json:"group,omitempty"`
	// MembersFrom is [IdentityMembersConsole] or [IdentityMembersDeclared].
	MembersFrom string `json:"members_from"`
	// Members are the declared members' emails. Only with MembersFrom
	// declared.
	Members []string `json:"members,omitempty"`
}

type ShapeIdentitySMTP struct {
	Host           string `json:"host"`
	Port           int    `json:"port"`
	User           string `json:"user,omitempty"`
	Sender         string `json:"sender"`
	PasswordSecret string `json:"password_secret"`
}

type ShapeIdentitySeedUser struct {
	Email          string   `json:"email"`
	Roles          []string `json:"roles,omitempty"`
	PasswordSecret string   `json:"password_secret,omitempty"`
}

type ShapeObject struct {
	Cluster    string `json:"cluster"`
	APIVersion string `json:"api_version,omitempty"`
	Kind       string `json:"kind"`
	Namespace  string `json:"namespace,omitempty"`
	Name       string `json:"name"`
	// Workload is the forge workload the object belongs to
	// (forge.dev/workload), for grouping.
	Workload string `json:"workload,omitempty"`
	// Hash is the digest of the pinned document after secret redaction:
	// what drift detection compares the live object against.
	Hash string `json:"hash"`
	// ConfigHash is the digest of the same document with release-bound
	// image references normalized to their artifact keys. Equal ConfigHash
	// with a different Hash means only images changed.
	ConfigHash string `json:"config_hash,omitempty"`
	// Images maps the release artifact key → pinned digest for every
	// release-bound image the object runs.
	Images map[string]string `json:"images,omitempty"`
	// Stateful marks an object that holds data beyond its own spec — a
	// declared database's objects. The well-known stateful kinds
	// ([statefulKinds]) are recognised without it.
	Stateful bool `json:"stateful,omitempty"`
	// Tree is the object's place in a v2 bundle, "<unit>/<phase>", or ""
	// for an object on a flat cluster. An object whose Tree changes between
	// releases is MOVING between Kustomizations: the one it leaves prunes
	// it, the one it joins creates it. The plan stops on that
	// ([FindingTreeMoved]).
	Tree string `json:"tree,omitempty"`
	// Identity carries the attributes that give an object an EXTERNAL
	// identity, which a deploy can silently replace: a Service's type and
	// load balancer, an Ingress's static IP. Keys are closed
	// ([IdentityKeys]) so the map can never become a place a value hides.
	Identity map[string]string `json:"identity,omitempty"`
}

type ShapeObservabilityPolicy struct {
	Enabled  bool     `json:"enabled"`
	Disabled []string `json:"disabled,omitempty"`
	// OptIn lists the categories the env turned ON that default off (only
	// [ObsOptInReplay] today). Absent = none opted in.
	OptIn []string `json:"opt_in,omitempty"`
	// Retention is the browser-telemetry retention the env declared, present
	// only when it moves any of the defaults (see [ShapeRetention.IsDefault]).
	// A control plane that predates it refuses the shape, so it is part of
	// [BundleFeatureFrontendTelemetry].
	Retention *ShapeRetention `json:"retention,omitempty"`
}