release

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

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 Attest struct {
	Provider string `json:"provider"`
	Subject  string `json:"subject"`
	RunID    string `json:"run_id,omitempty"`
}

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"`
	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"`
	// 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"`
	// 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 BundlePins struct {
	Images  map[string]string `json:"images,omitempty"`
	Sources map[string]Source `json:"sources,omitempty"`
}

type BundleRecord struct {
	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"`
	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 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
}

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 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 FindingClass 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 KindChange struct {
	Live      EnvKind `json:"live"`
	Candidate EnvKind `json:"candidate"`
}

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 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 ObjectKey struct {
	Cluster   string `json:"cluster"`
	Kind      string `json:"kind"`
	Namespace string `json:"namespace,omitempty"`
	Name      string `json:"name"`
}

type Plan struct {
	Digest         string        `json:"digest"`
	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"`
}

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
}

type Promotion struct {
	// 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"`
	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"`
	// 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. 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"`
	// 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"`
	// 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 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 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"`
	// 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"`
	// Applier is who applies this env when it DECLARES one: "forge" for a real
	// environment forge applies on purpose (the platform's own env, which its
	// own hub must not apply). Empty means undeclared, and omitted, so every
	// shape recorded before the field encodes and hashes as it did.
	Applier string `json:"applier,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 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"`
}

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 set when the two shapes disagree about the env's kind.
	// A kind is immutable, so this is always an error for a reader to
	// surface, never a change that can be deployed.
	KindChanged *KindChange `json:"kind_changed,omitempty"`

	Added   []ShapeObject  `json:"added,omitempty"`
	Removed []ShapeObject  `json:"removed,omitempty"`
	Changed []ObjectChange `json:"changed,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 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"`
	// 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"`
}

type ShapeSecret struct {
	Name string `json:"name"`
	// Provider is the env's secret provider for it: file | hosted |
	// external | … (forge's provider discriminator).
	Provider string `json:"provider"`
	// DeclaredBy are the workloads that read it.
	DeclaredBy []string `json:"declared_by,omitempty"`
}

type ShapeWorkload struct {
	Name string `json:"name"`
	// Runtime is forge's runtime discriminator: host | compose | cluster |
	// hosted (and the frontend runtimes for frontends).
	Runtime string `json:"runtime"`
	// Cluster is the kube context for a cluster workload.
	Cluster string `json:"cluster,omitempty"`
	// Artifact is the release artifact key its image comes from, if any.
	Artifact string `json:"artifact,omitempty"`
	Replicas *int   `json:"replicas,omitempty"`
}

type Source struct {
	// Repo is the repository the source is fetched from.
	Repo string `json:"repo"`
	// Ref is the tag/branch/sha as DECLARED (what a human edits).
	Ref string `json:"ref"`
	// Subdir is the path within the repo the component builds from.
	Subdir string `json:"subdir,omitempty"`
	// Commit is what Ref resolved to when the release was cut — the actual
	// content address.
	Commit string `json:"commit,omitempty"`
}

type Stage struct {
	Kind StageKind `json:"kind"`
	// Name is which one: a check's name, an environment name, an artifact.
	Name   string      `json:"name,omitempty"`
	Status StageStatus `json:"status"`
	// Env is the environment a promote or rollout stage concerns. Empty on
	// a build, a cut, or a check that is not env-specific.
	Env string `json:"env,omitempty"`
	// PromotionID ties a promote or rollout stage to its ledger entry.
	PromotionID string     `json:"promotion_id,omitempty"`
	StartedAt   *time.Time `json:"started_at,omitempty"`
	FinishedAt  *time.Time `json:"finished_at,omitempty"`
	URL         string     `json:"url,omitempty"`
	Summary     string     `json:"summary,omitempty"`
}

type StageKind string

type StageStatus string

type Worktree struct {
	// Key is forge's devstack key: "" for the primary checkout, the
	// sanitized linked-worktree name otherwise. It is the same key the
	// checkout's dev-stack port block is held under.
	Key string `json:"key"`
	// Label is what a human calls the checkout: the branch, else the
	// directory's base name. Never a path.
	Label string `json:"label,omitempty"`
	// Host names the machine: a daemon id, or a hash of the hostname.
	// Never a raw hostname or path.
	Host string `json:"host,omitempty"`
	// Path is the checkout's absolute path, for DISPLAY on the machine that
	// built it. It is stripped from anything sent to a hosted ledger
	// ([Provenance.ForHosted]): a path names a user's home directory.
	Path string `json:"path,omitempty"`
}