deploytarget

type BuildOnlyFrontend struct {
	// Name is the forge frontend name (logging).
	Name string

	// Path is the frontend source dir relative to the project root —
	// where install / `npm run build` run.
	Path string

	// DevRunner is "npm" (default) | "pnpm" | "yarn"; selects the
	// install command.
	DevRunner string

	// BuildEnv is the build-time env injected into the build process
	// (NEXT_PUBLIC_* / VITE_*). Layered over NODE_ENV=production.
	BuildEnv map[string]string

	// PublicDir is the build-output dir the build emits (relative to
	// Path), e.g. "out" for a Next.js static export. Used for dry-run
	// reporting of the emitted directory.
	PublicDir string
}

type BundleDirSpec struct {
	Src  string
	Dest string
}

type CacheRuleSpec struct {
	Pattern      string
	CacheControl string
}

type CapacityDemand struct {
	CPUMillicores int64
	MemoryBytes   int64
	StorageGiB    int64
	Workloads     int // services and jobs: anything that runs a pod
	Databases     int
	Builds        int
	StaticSites   int
}

type CapacityRefusedError struct {
	Env     string
	Verdict CapacityVerdict
	Demand  CapacityDemand
}

type CapacityVerdict struct {
	Allowed        bool
	Code           string
	Reason         string
	Fix            string
	HasComputePlan bool
	CeilingCPU     int64
	CeilingMemory  int64
	CeilingStorage int64
	// Unchecked is true when the control plane does not serve the procedure
	// (an older server): nothing was decided, and the server still enforces at
	// RecordBundle / Promote.
	Unchecked bool
	// Holds is set when Allowed is false but the control plane would ACCEPT
	// the deploy and QUEUE it on a human action (billing) rather than refuse
	// it. A deploy then proceeds — build, record, promote — and is reported
	// queued. An older control plane never sends it, so it keeps refusing.
	Holds []HostedHold
}

type ClusterBinding struct {
	// Cluster is the rendered cluster / kube-context name, as it appears in
	// the bundle's ClusterPaths. forge's key.
	Cluster string
	// ClusterID is the connected cluster's id, from ConnectCluster.
	ClusterID string
}

type ComposeProvider struct {
	// ProjectDir is the project root used for state-file paths. Empty
	// means "current working directory".
	ProjectDir string

	// Runner is the os/exec indirection used to invoke docker compose.
	// Nil falls back to the package default.
	Runner commandRunner
}

type ComposeSpec struct {
	ComposeFile string
	Service     string
	EnvFile     string

	// Env is the KCL-declared map forge puts in the `docker compose`
	// PROCESS environment — which is what the compose file's own `${VAR}`
	// references interpolate from. EnvFile is a different channel: it only
	// forwards values into CONTAINERS, and passing --env-file also
	// REPLACES compose's default `.env`.
	//
	// It is what lets a value be declared once in an env's KCL and reach
	// the container (the dev IdP's port is the motivating case — see
	// Compose.env in kcl/schema.k). These entries WIN over the inherited
	// shell environment, deliberately: a shell override would move the
	// container while every KCL reference to the same value stayed put.
	Env map[string]string

	// Wait selects readiness-gated deploys: `docker compose up -d
	// --wait` blocks until the service's declared healthcheck passes
	// instead of returning the moment the container is created.
	//
	// It is a pointer because the useful default is TRUE and a bool's
	// zero value is false: a nil Wait means "not specified", which
	// composeWait resolves to true. That keeps a ComposeSpec built by
	// any path — KCL, a test literal, a future caller — readiness-gated
	// unless someone opts OUT on purpose.
	Wait *bool

	// WaitTimeoutSeconds is a CEILING on the wait, not the mechanism:
	// readiness is decided by the healthcheck, and this only bounds how
	// long forge tolerates a container that never gets there, so a
	// wedged service fails loudly instead of hanging a dev loop or a CI
	// job forever. Zero means "no explicit ceiling" and lets the
	// healthcheck's own retries x interval bound it.
	WaitTimeoutSeconds int

	// ProjectDirectory is the directory compose runs the stack FROM: it
	// resolves ComposeFile and EnvFile, it is what every relative bind
	// mount in the file resolves against, and it is the
	// `com.docker.compose.project.working_dir` compose stamps on the
	// containers. Empty means the process working directory — a stack the
	// current checkout owns.
	//
	// The dispatcher sets it to the repo's PRIMARY checkout for a
	// `shared = True` stack (OnCompose.shared), so every worktree drives
	// the SAME containers with the SAME resolved config and an `up` from
	// any of them is a no-op once the stack is running.
	ProjectDirectory string

	// Shared records that the stack is machine infrastructure every
	// worktree uses (OnCompose.shared). It changes how a FOREIGN owner is
	// treated — see checkComposeOwnership.
	Shared bool
}

type DeployState struct {
	Image      string `json:"image"`
	Tag        string `json:"tag"`
	DeployedAt string `json:"deployed_at"` // RFC3339, wall-clock
}

type DistSourcemaps struct {
	// Dir is the built output, with its bundles and their maps.
	Dir string
	// Project, Frontend and BuildID identify the build, as for a staged one.
	Project, Frontend, BuildID string
	// BasePath is where the output is mounted in the served site ("" for the
	// root); it becomes the leading part of every path in the manifest.
	BasePath string
}

type FirebaseFrontend struct {
	// Name is the forge frontend name (logging + target fallbacks).
	Name string

	// Path is the frontend source dir relative to the project root —
	// where `npm install` / `npm run build` run.
	Path string

	// DevRunner is "npm" (default) | "pnpm" | "yarn"; selects the
	// install command. The build command is always `<runner> run build`.
	DevRunner string

	// BuildEnv is the build-time env injected into the build process
	// (NEXT_PUBLIC_* / VITE_*). Layered on top of os.Environ().
	BuildEnv map[string]string

	// Project is the forge project name (recorded in the source map manifest).
	Project string

	// VersionEnvVar is the variable the bundle reads service.version from
	// (NEXT_PUBLIC_APP_VERSION / VITE_APP_VERSION); forge injects the build id
	// into it unless BuildEnv sets it. Empty injects nothing.
	VersionEnvVar string

	// Sourcemaps is "publish" (default), "public" or "off". See the
	// Sourcemaps* constants.
	Sourcemaps string

	// RuntimeConfigJS is this ENVIRONMENT's rendered runtime config
	// document — the `window.__FORGE_CONFIG__ = {...}` script the browser
	// loads before any bundle code runs, produced from the environment's
	// KCL (frontend_config_gen.k's runtime projection).
	//
	// It is written into the assembled tree AFTER the built bundle is
	// copied, which is what makes promotion real: the bundle is
	// environment-agnostic and this one file is the only part that
	// differs, so the same bytes ship to dev and prod carrying different
	// configuration. Empty means the frontend declares no typed config —
	// nothing is written and the assembled layout is unchanged.
	RuntimeConfigJS string

	// SourcemapPublisher files the source maps the build extracts (F1) so
	// errors can be symbolicated: pushed to the platform registry when the
	// env's observability is hosted, kept on disk otherwise. nil files nothing
	// (the maps are still extracted, and never served).
	SourcemapPublisher SourcemapPublisher

	// Spec is the FirebaseHosting deploy config.
	Spec FirebaseHostingSpec
}

type FirebaseHostingSpec struct {
	Project   string
	Site      string
	Target    string
	PublicDir string
	BasePath  string
	Bundle    []BundleDirSpec
	Rewrites  []map[string]any

	// SPAFallback is the entry document ("/index.html") served for a
	// client-side route — a missing path inside its directory whose last
	// segment is not a static file. Empty means no SPA fallback. Rendered
	// AFTER Rewrites, so an explicit rewrite always wins.
	SPAFallback string

	// AssetDir is the build's content-hashed asset directory relative to
	// the frontend's mount ("assets" for Vite, "_next/static" for a
	// Next.js export). Empty means the build declares none: no immutable
	// cache rule and no asset retention.
	AssetDir string

	// KeepAssetReleases is how many releases' hashed assets the live site
	// serves, the new one included. Zero means the default (10); the floor
	// is 2. See firebase_assets.go.
	KeepAssetReleases int

	// CacheControl is the frontend's declared Cache-Control rules
	// (first match wins). Empty means forge's default: the asset dir
	// immutable, everything else no-cache. See firebaseHeaders.
	CacheControl []CacheRuleSpec
}

type FirebaseProvider struct {
	// ProjectDir is the project root. Frontend paths and Bundle.Src
	// resolve against it. Empty means the current working directory.
	ProjectDir string

	// Runner is the os/exec indirection (npm / firebase). Nil falls
	// back to the package default. Tests inject a fake runner.
	Runner commandRunner

	// StagingRoot overrides where the assembled hosting tree is written.
	// Empty means a temp dir under os.TempDir(). Tests set it so they
	// can inspect the assembled layout.
	StagingRoot string

	// HTTPClient reads the live release (its asset manifest and the
	// assets retention carries forward). Nil means an *http.Client with
	// a two-minute timeout.
	HTTPClient HTTPDoer

	// SiteURL maps a Firebase Hosting site id to the origin its live
	// release is read from. Nil means https://<site>.web.app, the origin
	// every site answers on. Tests point it at an httptest server.
	SiteURL func(site string) string

	// Sleep waits between attempts to read the live release, returning
	// early with ctx's error. Nil means a real, context-aware sleep.
	Sleep func(ctx context.Context, d time.Duration) error
}

type HTTPDoer interface {
	Do(*http.Request) (*http.Response, error)
}

type Health int

type HeldError struct {
	Env         string
	PromotionID string
	Release     string
	Holds       []HostedHold
}

type HostInfraProvider struct {
	// ProjectDir is the project root. Data directories declared relative
	// (the default) resolve against it. Empty means the working directory.
	ProjectDir string
}

type HostInfraSpec struct {
	Engine   string
	Port     int
	Database string
	User     string
	Password string
	DataDir  string
	Version  string

	// engine = "zitadel" only — the dev IdP's backing database and its
	// declarative bootstrap. See the HostInfra schema in kcl/schema.k.
	IDPDatabase     string
	IDPDatabasePort int
	IDPMasterKey    string
	IDPStepsFile    string
	IDPPATPath      string

	// engine = "nats" only.
	NATSMonitorPort int
	// engine = "temporal" only.
	TemporalNamespaces []string
	TemporalUIPort     int
}

type HostedCaller interface {
	Call(ctx context.Context, procedure string, req, out any) error
}

type HostedCustomDomain struct {
	Domain string `json:"domain"`
	// State is the lower-case vocabulary: pending_dns | verifying |
	// issuing | live | failed | conflict | unknown.
	State string `json:"state"`
	// RequiredRecords are the DNS records still to be set. The platform
	// reports them for as long as they matter, so a domain stuck in
	// pending_dns always carries the reason it is stuck.
	RequiredRecords []HostedDNSRecord `json:"required_records,omitempty"`
	LastError       string            `json:"last_error,omitempty"`
	// LiveSince is RFC3339 for when the domain started serving, empty
	// until it does.
	LiveSince string `json:"live_since,omitempty"`
	// ServingPath is where the domain's DNS sends its traffic, as the
	// control plane resolves it: edge | ingress | elsewhere. Empty when the
	// control plane did not say (the name does not resolve yet, or an older
	// control plane). See ServingPathName.
	ServingPath string `json:"serving_path,omitempty"`
}

type HostedDNSRecord struct {
	// Type is A | CNAME | TXT.
	Type string `json:"type,omitempty"`
	// Name is the record name, as the registrar wants it.
	Name string `json:"name,omitempty"`
	// Value is the record's value — an address, a target, or a token.
	Value string `json:"value,omitempty"`
}

type HostedEnvKind string

type HostedEnvRef struct {
	// Project is the forge project name (forge.yaml `name`).
	Project string
	Name    string
	Kind    HostedEnvKind

	// Shape is the env's rendered shape, recorded as the DECLARATION:
	// what runs, where, which secrets it needs, one hash per object. It is
	// what lets a reader answer "what kind, which secrets, which provider"
	// with no checkout and no daemon, which is the whole point of
	// recording it.
	//
	// NIL MEANS "I DID NOT RENDER", NOT "THE ENV DECLARES NOTHING". An
	// absent shape leaves the stored one untouched server-side, so the
	// ensures that run without a render — `forge secret set`, a promote —
	// cannot erase a declaration that a build recorded. Only a path that
	// actually rendered the env may set it.
	Shape *release.Shape
	// DeclaredBy is the provenance of the render Shape came from: which
	// commit, which checkout, which forge. It is a CLAIM, recorded as
	// one — identity is the caller's token, never this (O-11).
	DeclaredBy *release.Provenance

	// ClusterBindings maps each cluster the bundle renders for to the
	// CONNECTED cluster it deploys to — the control plane's record of where
	// this environment lands.
	//
	// A REPEATED FIELD BECAUSE ONE ENV CAN HAVE SEVERAL TARGETS. A forge
	// bundle renders a subtree per cluster (release.BundleClusterPath), so
	// an env that spans two clusters has two bindings, which a single
	// cluster id could not express.
	//
	// Nil means "no bindings to record", which leaves the stored ones
	// untouched server-side — the same rule Shape follows, and for the same
	// reason: an ensure that did not render (a secret set, a promote) must
	// not erase what a build recorded.
	ClusterBindings []ClusterBinding

	// HubConverged is WHO APPLIES the env's bound clusters, as decided from
	// the same render as Shape: true ONLY when the control plane's hub
	// converges EVERY delivery unit and forge applies none of them, false when
	// forge applies any part of the env from the author's machine. It is the
	// env-level summary of HubConvergedUnits, kept because a control plane that
	// predates per-unit convergence reads only this: sending true for an env
	// that has moved some units would make an old control plane converge the
	// units forge still applies, so the summary is deliberately the
	// conservative one. A bound cluster says WHERE the env lands, not who puts
	// it there.
	//
	// A SHAPE FIELD, sent only beside a Shape, because it is a projection of
	// that render. Nil means "this ensure did not render" and leaves the
	// stored value untouched, like Shape and ClusterBindings. An env never
	// declared is treated as forge-applied server-side, so an older forge
	// can never make the hub a second applier over a cluster it applies.
	HubConverged *bool
	// HubConvergedUnits are the delivery units the control plane's hub
	// converges, by name: the per-unit declaration an env uses to move onto
	// Flux one unit at a time (Bundle.hub_converges). Every other unit of the
	// env is applied by forge. Nil means this ensure did not render, like
	// HubConverged; a non-nil empty slice says "the hub converges none".
	//
	// A control plane that predates the field ignores it (connect's JSON codec
	// discards unknown fields) and obeys HubConverged, which is false until
	// every unit has moved: so an old control plane never converges a
	// partially moved env.
	HubConvergedUnits *[]string
}

type HostedEnvStatus struct {
	EnvironmentID string
	// Verdict is the environment-level verdict, lower-case.
	Verdict         string
	ReconcilePolicy string
	Workloads       []HostedWorkloadStatus
}

type HostedHold struct {
	// Kind is the DeployHoldKind value name (DEPLOY_HOLD_KIND_BILLING).
	Kind        string `json:"kind,omitempty"`
	PromotionID string `json:"promotionId,omitempty"`
	// Reason states the real quantity: "this runs compute (1 workload, 1
	// database) and the organization has no active compute plan".
	Reason string `json:"reason,omitempty"`
	// Fix is the literal next step, written by the control plane.
	Fix string `json:"fix,omitempty"`
	// ActionURL is where a human resolves it: the environment's page in
	// the Reliant web app. Empty when the control plane has none to give.
	ActionURL        string     `json:"actionUrl,omitempty"`
	CallerCanResolve bool       `json:"callerCanResolve,omitempty"`
	HeldSince        *time.Time `json:"heldSince,omitempty"`
}

type HostedPreflightItem struct {
	Name     string
	Tier     HostedTier
	Workload *v1alpha1.WorkloadSpec
	Database *v1alpha1.ManagedDatabaseSpec
	Static   *v1alpha1.StaticSiteSpec
}

type HostedProvider struct {
	Client HostedCaller
	// Rollout bounds and shapes the readiness wait: mode skip waits for
	// nothing, warn reports without failing, wait (the default) fails on a
	// workload that never becomes ready. Timeout is the WHOLE wait.
	Rollout cluster.RolloutPolicy
	// PollInterval is the GetStatus cadence. Zero means 3s.
	PollInterval time.Duration
	// OnRollout, when set, receives one outcome per published workload.
	OnRollout func(cluster.RolloutObservation)
	// OnEnvironment, when set, receives the control plane's environment id
	// as soon as it is known, so a report can carry it even if a later step
	// fails.
	OnEnvironment func(id string)
	// RecordBundle builds, pushes and records the env's bundle once the
	// environment exists. The provider cannot do it itself: building needs
	// the project render, which only the CLI can drive.
	// It returns the recorded bundle's digest, which the readiness wait
	// uses to confirm the platform applied THIS bundle before judging
	// workloads ("" skips that confirmation).
	RecordBundle func(ctx context.Context, environmentID string) (bundleDigest string, err error)
}

type HostedRecord struct {
	Kind string
	Name string
	// YAML is the serialized CR.
	YAML []byte
}

type HostedTarget struct {
	// Endpoint is the control plane's normalized base URL. Display only —
	// the Caller already addresses it.
	Endpoint string
	// Project is the forge project name the environment is addressed under
	// on the control plane (identity is (org, project, env name)).
	Project string
	// Release is the version the env is promoted to. Empty means unbound,
	// which a deploy refuses: a hosted deploy ships only promoted digests.
	Release string
	// PromotionID is the promotion whose frozen pins this deploy is
	// publishing — the one forge read Digests from. Recorded server-side
	// as Deployment.applied_promotion_id, which is what lets the
	// converger tell "a promotion is waiting to be applied" from "this
	// row has drifted": the two need opposite answers under the OBSERVE
	// policy, and comparing digests cannot distinguish them because both
	// read as "the row does not match the pin".
	//
	// Empty when the env is unbound, or when a control plane that
	// predates the ledger's promotion ids returned none. An omitted
	// promotion leaves the stored one untouched server-side, which is the
	// correct reading of a hand-run deploy: that is drift, not a
	// promotion.
	PromotionID string
	// Digests is the bound release's artifact → digest map (the ledger's
	// Resolved set).
	Digests map[string]string
	// Registries is the bound release's artifact → registry map: where each
	// image was pushed (the release artifact's URI). It locates the bytes of
	// a workload whose image THIS project builds, which is declared
	// registry-less (`image = "api"`): forge composed the address from the
	// env's declared push base, and recorded it here by
	// `forge env build <env> --push`.
	Registries map[string]string
	// PushBase is the registry subtree this env's hosted artifacts live
	// under, composed by forge from the env's declaration
	// (`<registry_host>/<org>/<project>`) and carried here so the
	// pre-publish check judges a pinned image against the same base the
	// build pushed to.
	//
	// It is the CLIENT's composition, deliberately: the server does not
	// advertise a base, it ENFORCES one — at publish (ociregistry.Admit) and
	// at the registry realm, which refuses a token outside its own org's
	// subtree. So a mis-declared org is caught by the thing that knows,
	// rather than by forge believing an answer it was handed.
	PushBase string
	// Shape and DeclaredBy are the env's rendered DECLARATION, recorded by
	// the EnsureEnvironment this deploy already performs rather than by a
	// write of their own.
	//
	// That placement is the contract, not a convenience. The order in this
	// file's header exists so nothing is written until everything is known
	// to be admissible — every workload validated, the hosted set rendered
	// as the platform will — and a deploy that forge is about to refuse
	// (unbound, off shape band, image outside the push base) must leave the
	// control plane untouched. A declaration sent ahead of the plan would
	// be the one write that escaped that rule.
	//
	// Nil means "no render to record", which leaves the stored shape
	// untouched server-side.
	Shape      *release.Shape
	DeclaredBy *release.Provenance
	// Kind is the env's control-plane kind as the CLI derived it from the
	// whole render (hostedEnvKindOf). "" means "not derived", which the
	// provider reads as PERSISTENT. It is the legacy wire field the control
	// plane is retiring; placement itself is per workload.
	Kind HostedEnvKind
}

type HostedTier string

type HostedWorkload struct {
	Tier HostedTier
	// Artifact is the release-ledger artifact name this workload's digest is
	// bound under. Empty means HostedArtifactName(Workload.Image) for a
	// workload and the workload's own name for a static site (the frontend
	// name `forge build` records its site release under).
	Artifact string
	// Workload is the spec published as a forge.dev Workload CR (named by
	// the ResolvedService name). Its Image is the declared image — a
	// registry-less artifact name this project builds, or a pinned
	// third-party reference — and the plan pins it to the release digest.
	Workload *v1alpha1.WorkloadSpec
	Database *v1alpha1.ManagedDatabaseSpec
	// Static is the deployed half of a StaticSite: everything but the
	// digest, which planHosted pins from the bound release as liveDigest.
	Static *v1alpha1.StaticSiteSpec
}

type HostedWorkloadStatus struct {
	Name string `json:"name"`
	// Tier is workload | database | static.
	Tier string `json:"tier,omitempty"`
	// URL is the platform-allocated public URL, once one exists.
	URL string `json:"url,omitempty"`
	// Hostname is URL's host, for a badge that has no room for a scheme.
	Hostname string `json:"hostname,omitempty"`
	// ServingPath is where Hostname's DNS sends its traffic, as the control
	// plane resolves it: edge | ingress | elsewhere, or empty when it did
	// not say (ServingPathName).
	ServingPath string `json:"serving_path,omitempty"`
	// Verdict is the control plane's lower-case deploystate verdict:
	// unknown | converging | converged | diverged | degraded.
	Verdict       string `json:"verdict"`
	VerdictReason string `json:"verdict_reason,omitempty"`
	// ObservedState is the observation vocabulary: pending | progressing |
	// ready | degraded | suspended | deleted | unknown.
	ObservedState  string `json:"observed_state"`
	ObservedDigest string `json:"observed_digest,omitempty"`
	DesiredDigest  string `json:"desired_digest,omitempty"`
	Drifted        bool   `json:"drifted,omitempty"`
	LastError      string `json:"last_error,omitempty"`
	// Domains is the per-domain state of every custom hostname this
	// deployment declares — what it is doing, and what DNS the author
	// still owes. Empty for a deployment that declares none.
	Domains []HostedCustomDomain `json:"domains,omitempty"`
}

type K8sClusterProvider struct {
	// ApplyOptsBuilder lets callers customize cluster.ApplyOpts before
	// the provider invokes cluster.Apply. The forge CLI uses this to
	// plumb through MainK, EnvConfigKV, Prune
	// from the rendered KCL — fields the provider itself doesn't know
	// about. A nil builder means "use the group's namespace+image tag
	// and let cluster.Apply default everything else", which is enough
	// for tests but not for the real forge env deploy path.
	ApplyOptsBuilder func(group ServiceGroup) cluster.ApplyOpts

	// Runner is the os/exec indirection used by OBSERVE ONLY, to shell
	// `kubectl get deployment -o json`. Nil falls back to the package
	// default.
	//
	// Deploy deliberately does NOT route through it: it delegates to
	// cluster.Apply, which owns its own execution, the KCL render and the
	// rollout wait. Threading this field into it would change deploy
	// behaviour, which is not what adding a read verb is for.
	Runner commandRunner
}

type K8sClusterSpec struct {
	Replicas int
	Platform string
	Ports    []int

	// OwnedClaims names the PersistentVolumeClaims forge ITSELF emits
	// for this workload, so an observation can be accountable for them.
	//
	// The distinction is ownership, not usage. A forge.Volume of type
	// "pvc" REFERENCES a claim by name and leaves its existence to
	// whoever provisioned it — forge has no standing to report on a
	// claim it did not create. A workload's `storageGiB` is the one
	// case where forge emits the PVC (pkg/deploy.RenderWorkloads, named by PVCName), and a thing forge creates is a thing forge must be
	// able to read back.
	//
	// It matters because an unbound claim is invisible in the half of
	// the state this observation otherwise reads. A Deployment whose PVC
	// never binds reports "0/1 ready" — true, and it names the symptom
	// while the cause (no default StorageClass on this cluster, or a
	// storage_gib change the class refused) sits one object away.
	//
	// Empty for an ordinary cluster service, which is why this is a
	// nil-able slice rather than a bool plus a naming convention: the
	// observer asks the group what forge owns instead of re-deriving
	// "<name>-data" and hoping the render still agrees.
	OwnedClaims []string
}

type LocalSourcemaps struct {
	// ProjectDir is the project root the .forge directory lives under, and Env
	// the deploy env the maps are kept for.
	ProjectDir, Env string
}

type ObservationUnsupportedError struct {
	// Provider is the declining provider's Name().
	Provider string
	// Reason states what makes the target unreadable, in the user's
	// terms. Required — an unsupported with no reason tells a user
	// nothing they can act on.
	Reason string
}

type Observed struct {
	// ProviderID is the Name() of the provider that produced this, so a
	// merged multi-group report stays attributable.
	ProviderID string `json:"provider"`

	// ObservedAt is when the read happened, wall-clock UTC. A reconciler
	// comparing declared against observed needs to know how stale the
	// observation is; without it, a cached or retried observation is
	// indistinguishable from a fresh one.
	ObservedAt time.Time `json:"observed_at"`

	// Items is the per-service / per-frontend detail.
	Items []ObservedItem `json:"items"`
}

type ObservedItem struct {
	// Name is the service or frontend name, matching
	// ResolvedService.Name / StaticSiteFrontend.Name so a caller can join
	// an observation back to what was declared.
	Name string `json:"name"`

	// Digest is the content-addressed identity of what is RUNNING: an
	// image digest for a container tier, the live release digest for a
	// static site. Empty means the provider could not determine it —
	// which includes the common, legitimate case of an image pinned by
	// mutable tag rather than by digest.
	Digest string `json:"digest,omitempty"`

	// Replicas is the scale observation, or nil when the tier has no
	// replica concept. Nil and &ReplicaCounts{} mean different things:
	// "not applicable" versus "nothing is running".
	Replicas *ReplicaCounts `json:"replicas,omitempty"`

	// Health is the provider's verdict. Zero value is HealthUnknown.
	Health Health `json:"health"`

	// Detail is one line of human-readable context, and it is REQUIRED
	// whenever Health is not HealthHealthy. An "unknown" with no reason
	// is indistinguishable from a provider that silently failed, which is
	// the exact confusion this whole verb exists to remove.
	Detail string `json:"detail,omitempty"`
}

type Provider interface {
	// Name returns the provider's stable identifier — used in log
	// output and error messages so users can tell which provider
	// produced a given line.
	Name() string

	// Deploy ships every service in the group. The provider owns the
	// in-pipeline ordering (e.g. K8sClusterProvider does one
	// kubectl-apply for all services at once because they share a
	// cluster/namespace).
	Deploy(ctx context.Context, group ServiceGroup) error

	// Observe reports what this provider currently sees deployed, so a
	// caller can compare it against what was declared.
	//
	// A READ with no side effects: it may run against a target forge has
	// never deployed to, and it must never mutate one. Deploy describes
	// a transition; this is the only verb that answers
	// "what is actually running right now", which is what a reconciler
	// is built around.
	//
	// A provider that cannot read its target back returns
	// ErrObservationUnsupported (via the unsupported helper) — never a
	// green Observed. See observe.go for why unknown is the zero value
	// on every field that could otherwise default to "fine".
	Observe(ctx context.Context, group ServiceGroup) (Observed, error)
}

type RawK8sCluster struct {
	Cluster   string
	Namespace string
	Registry  string
	Domain    string
	Spec      *K8sClusterSpec
}

type RawService struct {
	Name string

	// K8sCluster carries both the env-wide fields (used for grouping)
	// and the per-service spec (carried through to the provider).
	K8sCluster *RawK8sCluster

	Compose   *ComposeSpec
	HostInfra *HostInfraSpec

	// Secrets carries resolved secret values to inline into the runtime
	// env for Compose services. Carried verbatim onto the
	// ResolvedService. nil for K8sCluster services (those get rendered
	// Secret objects, not inlined values) and for external/none
	// providers.
	Secrets map[string]string
}

type Registry struct {
	// contains filtered or unexported fields
}

type RegistrySourcemaps struct {
	// ProjectDir and Env say where the record is written
	// (.forge/state/sourcemaps-<env>-<frontend>.json). ProjectDir empty means ".".
	ProjectDir, Env string
	// Base resolves the project's push base (`<host>/<org>/<project>`). It is
	// called at the first publish, not at construction, so a deploy that
	// extracted no map never needs the credential that resolving it takes.
	Base func(ctx context.Context) (string, error)
	// Push stores the packed artifact. nil is the real registry
	// (PushSourcemapsArtifact); tests state the registry's answer.
	Push func(ctx context.Context, repository, tag string, b SourcemapBuild, layer []byte) (digest string, err error)
}

type ReplicaCounts struct {
	// Desired is what the target was asked for (Deployment.spec.replicas).
	Desired int `json:"desired"`
	// Ready is how many are passing their readiness probe.
	Ready int `json:"ready"`
	// Updated is how many are running the CURRENT pod template — the
	// count that distinguishes "rolled out" from "rolling out", which a
	// ready count alone cannot.
	Updated int `json:"updated"`
	// Available is how many have stayed ready past minReadySeconds.
	Available int `json:"available"`
}

type ResolvedService struct {
	Name string

	// Exactly one of the following is non-nil. Discriminated by the
	// owning ServiceGroup.ProviderID, but kept as separate pointers
	// so each provider's Deploy method can type-assert against its
	// own concrete shape without a runtime switch.
	K8sCluster *K8sClusterSpec
	Compose    *ComposeSpec
	HostInfra  *HostInfraSpec
	Hosted     *HostedWorkload

	// Secrets carries resolved secret values to inject into the runtime
	// env (compose). Populated by the deploy dispatch from a
	// dotenv secret_provider's All() map; nil for external/none providers
	// (those resolve secrets out-of-band) and always nil for K8sCluster
	// services (those get rendered Secret objects + secretKeyRef, not
	// inlined env values). Merged UNDER the env_file overlay so an
	// explicit env_file entry wins on key conflict.
	Secrets map[string]string
}

type ServiceGroup struct {
	// Env is the environment name (matches the deploy/kcl/<env>/
	// directory name and the `forge env deploy <env>` CLI arg).
	Env string

	// ProviderID identifies the provider type — "k8s-cluster",
	// "hosted", "compose". Used by the dispatcher to look the
	// provider up and by log output to tag lines per-group.
	ProviderID string

	// Services is the per-service list. Each entry's Deploy field is
	// the dispatched view of the rendered KCL — see ResolvedService.
	Services []ResolvedService

	// Frontends carries the frontends the "firebase" provider ships.
	// It's the frontend analogue of Services — empty for the
	// service-shaped providers (k8s-cluster / compose / host-infra), which
	// read Services instead. The Firebase provider reads Frontends +
	// DryRun off the group so it dispatches through the registry like
	// every other provider.
	Frontends []FirebaseFrontend

	// StaticSites carries the frontends the "static-site" provider
	// ships. A separate field rather than a shared one because the two
	// frontend providers consume genuinely different specs (a hosting
	// site id vs. a bucket + CDN + retention policy), and a group only
	// ever routes to ONE provider — so a union type here would buy a
	// type assertion in both providers and nothing else.
	StaticSites []StaticSiteFrontend

	// Hosted is the env-level half of a "hosted" group: the control plane's
	// endpoint and the bound release's digests. Nil for every other
	// provider. Services carry the per-workload tier specs.
	Hosted *HostedTarget

	// HostedPlan is the plan a hosted group is admitted under: the
	// standard (billed) plan, judged by the shape band, or the anonymous
	// claimable plan, judged by its caps (deploy.CheckHostedResources). A
	// field rather than a property of the credential, so a preview with no
	// credential (`forge env shape --claimable`, `--claimable --plan-only`)
	// is judged exactly as the deploy will be.
	HostedPlan deploy.HostedPlan
	// ClaimableLimits are the claimable plan's caps HostedPlanClaimable is
	// judged by: the control plane's published answer, or forge's
	// compiled-in copy when it could not be asked. Zero (an unset field)
	// means the compiled-in copy.
	ClaimableLimits deploy.ClaimableLimits

	// ImageTag is the tag forge built (or is about to build) for
	// these services. Passed through to the provider so it can stamp
	// the image references correctly.
	ImageTag string

	// Common K8sCluster fields. Pulled from the first service in the
	// group (KCL refs guarantee they're identical across the group).
	// Empty for non-cluster providers.
	Cluster   string
	Namespace string
	Registry  string
	Domain    string

	// DryRun, when true, instructs the provider to print the exact
	// commands it would exec instead of running them, and skip any
	// state-file writes. Providers honor this independently of the
	// cluster.ApplyOpts.DryRun knob (K8sCluster's provider plumbs it
	// through ApplyOpts; Compose checks this field
	// directly because they don't go through cluster.Apply).
	DryRun bool
}

type SourcemapBuild struct {
	// Project and Frontend name the build in the artifact's annotations.
	Project, Frontend string
	// BuildID is the bundle's service.version and the key the maps are filed
	// under.
	BuildID string
	// Dir is the sidecar directory (SourcemapsDir of the staging tree).
	Dir string
	// Maps is how many maps the sidecar holds.
	Maps int
}

type SourcemapFile struct {
	Path   string `json:"path"`
	Map    string `json:"map"`
	SHA256 string `json:"sha256"`
}

type SourcemapManifest struct {
	Schema   string          `json:"schema"`
	Project  string          `json:"project"`
	Frontend string          `json:"frontend"`
	BuildID  string          `json:"build_id"`
	BasePath string          `json:"base_path"`
	Files    []SourcemapFile `json:"files"`
}

type SourcemapPublisher interface {
	PublishSourcemaps(ctx context.Context, b SourcemapBuild) (SourcemapsRecord, error)
}

type SourcemapsRecord struct {
	BuildID    string `json:"build_id"`
	Frontend   string `json:"frontend"`
	Maps       int    `json:"maps"`
	Repository string `json:"repository,omitempty"`
	Tag        string `json:"tag,omitempty"`
	Digest     string `json:"digest,omitempty"`
	Dir        string `json:"dir,omitempty"`
	FiledAt    string `json:"filed_at"`
}

type StageInput struct {
	// Name is the forge frontend name (logging, error prefixes, and the
	// default staging directory name).
	Name string

	// Path is the frontend source dir — where install and build run.
	// Relative paths resolve against ProjectDir.
	Path string

	// DevRunner is "npm" (default) | "pnpm" | "yarn"; selects the
	// install command. The build command is always `npm run build`.
	DevRunner string

	// BuildEnv is the build-time env injected into the build process
	// (NEXT_PUBLIC_* / VITE_*), layered over NODE_ENV=production.
	BuildEnv map[string]string

	// PublicDir is the build output directory, relative to Path.
	PublicDir string

	// BasePath is the sub-path under the site root to mount PublicDir
	// under ("/admin"). Empty means the site root.
	BasePath string

	// Bundle is the extra pre-built static dirs to assemble into the
	// same tree. Src resolves against ProjectDir.
	Bundle []BundleDirSpec

	// RuntimeConfigJS is this ENVIRONMENT's rendered runtime config
	// document. Written into the assembled tree AFTER every copy, which
	// is what makes promotion real: the built bundle is
	// environment-agnostic and this one file is the only part of the
	// artifact that differs between environments. Empty means the
	// frontend declares no typed config and nothing is written.
	RuntimeConfigJS string

	// StripRuntimeConfig deletes <basePath>/config.js from the assembled
	// tree instead of writing one: the environment-agnostic artifact a
	// hosted release ships. See StaticSiteFrontend.StripRuntimeConfig.
	StripRuntimeConfig bool

	// ProjectDir is the project root that Path and Bundle[].Src resolve
	// against. Empty means the current working directory.
	ProjectDir string

	// StagingRoot overrides where the assembled tree is written. Empty
	// means a temp dir under os.TempDir().
	StagingRoot string

	// Project is the forge project name, recorded in the source map manifest.
	Project string

	// VersionEnvVar is the framework-scoped variable the bundle reads its
	// service.version from (NEXT_PUBLIC_APP_VERSION / VITE_APP_VERSION).
	// forge sets it to the build id unless BuildEnv already sets it. Empty
	// means the frontend has no such variable and no id is injected.
	VersionEnvVar string

	// Sourcemaps is "publish" (default: maps leave the served tree for a
	// sidecar), "public" (maps are served) or "off" (maps are dropped).
	Sourcemaps string
}

type StagePlan struct {
	Name        string
	FrontendDir string // absolute frontend source dir
	InstallCmd  []string
	BuildCmd    []string
	BuildEnv    map[string]string
	StagingDir  string // absolute assembled public root

	// Copies is the ordered list of (absoluteSrc → relativeDestUnderStaging)
	// the assembler performs. The first entry is always the frontend's own
	// public_dir (mounted under base_path); the rest are bundle dirs.
	Copies []stageCopy

	// RuntimeConfigJS is the environment's runtime config document, and
	// RuntimeConfigRel is where it lands relative to the staging root —
	// inside the base-path subtree, because that is where the document
	// head's <script src="<basePath>/config.js"> resolves it. Empty
	// RuntimeConfigJS means no document is written.
	RuntimeConfigJS  string
	RuntimeConfigRel string
	// StripRuntimeConfig removes RuntimeConfigRel from the tree after the
	// copies rather than writing it.
	StripRuntimeConfig bool

	// Project, VersionEnvVar, Sourcemaps and BasePath are the StageInput
	// fields the build-identity and source map steps need. Sourcemaps is
	// already resolved (never empty).
	Project       string
	VersionEnvVar string
	Sourcemaps    string
	BasePath      string

	// BuildID is the build's identity, set by runStagePlan before the build
	// runs. Empty in a plan that has not run (a dry-run) or has no
	// VersionEnvVar.
	BuildID string
}

type StageResult struct {
	// BuildID is injected into the bundle as service.version and keys the
	// source maps. Empty when the frontend has no version variable.
	BuildID string
	// SourcemapsDir is the sidecar holding the extracted maps and
	// manifest.json; empty when none were extracted.
	SourcemapsDir string
	// Sourcemaps is how many maps were extracted.
	Sourcemaps int
}

type StaticSiteCDNSpec struct {
	URLMap               string
	Invalidate           string // "entrypoints" (default) | "none" | "all"
	ExtraInvalidatePaths []string
}

type StaticSiteFrontend struct {
	// Name is the forge frontend name (logging + the staging dir name).
	Name string

	// Path is the frontend source dir relative to the project root —
	// where install / `npm run build` run.
	Path string

	// DevRunner is "npm" (default) | "pnpm" | "yarn"; selects the
	// install command.
	DevRunner string

	// BuildEnv is the build-time env injected into the build process
	// (NEXT_PUBLIC_* / VITE_*).
	BuildEnv map[string]string

	// Project is the forge project name (recorded in the source map manifest).
	Project string

	// VersionEnvVar is the variable the bundle reads service.version from
	// (NEXT_PUBLIC_APP_VERSION / VITE_APP_VERSION); forge injects the build id
	// into it unless BuildEnv sets it. Empty injects nothing.
	VersionEnvVar string

	// Sourcemaps is "publish" (default), "public" or "off". See the
	// Sourcemaps* constants.
	Sourcemaps string

	// RuntimeConfigJS is this ENVIRONMENT's rendered runtime config
	// document, written into the assembled tree after every copy. See
	// FirebaseFrontend.RuntimeConfigJS — identical semantics, and the
	// reason a promoted bundle can carry different configuration
	// without rebuilding.
	RuntimeConfigJS string

	// StripRuntimeConfig removes any runtime config document that
	// travelled inside the built bundle (the dev copy under the frontend's
	// public/) instead of writing one. Set for a HOSTED release, whose
	// artifact must be environment-agnostic: its document is spec, written
	// by the control plane after each sync. Mutually exclusive with a
	// non-empty RuntimeConfigJS.
	StripRuntimeConfig bool

	// SourcemapPublisher files the source maps the build extracts (F1) so
	// errors can be symbolicated: pushed to the platform registry when the
	// env's observability is hosted, kept on disk otherwise. nil files nothing
	// (the maps are still extracted, and never served).
	SourcemapPublisher SourcemapPublisher

	// Spec is the StaticSite deploy config.
	Spec StaticSiteSpec
}

type StaticSiteProvider struct {
	// ProjectDir is the project root. Frontend paths and Bundle.Src
	// resolve against it. Empty means the current working directory.
	ProjectDir string

	// Runner is the os/exec indirection (npm / gcloud). Nil falls back
	// to the package default. Tests inject a fake runner.
	Runner commandRunner
}

type StaticSiteSpec struct {
	Bucket    string
	PublicDir string
	BasePath  string
	Bundle    []BundleDirSpec

	// AssetDir is the build's content-hashed asset directory relative to
	// the frontend's mount ("assets", "_next/static"); empty when the
	// build declares none. It is what the default cache policy marks
	// immutable (see cacheRules).
	AssetDir string

	// CacheControl is the frontend's declared Cache-Control rules (first
	// match wins). Empty means forge's default, the same one OnFirebase
	// and hosted static hosting serve: AssetDir immutable, everything
	// else no-cache.
	CacheControl []CacheRuleSpec

	CDN          *StaticSiteCDNSpec
	KeepReleases int
}