bundle

type BuildInput struct {
	// Snapshot is a complete composition. Its recorded object bytes, never a
	// new checkout render, are packaged verbatim and checked against the layer.
	Snapshot *release.Snapshot
	// Project and Env name the bundle. Both required: a bundle is one
	// env's render, and a reader that could not tell which env it
	// described would have an artifact it could not place.
	Project string
	Env     string
	// Release is the version pinned, or "" for an unreleased bundle (dev,
	// or a Preview deploy) pinned to the build's own digests.
	Release string
	// Pins is the pin set the render resolved: images by artifact key,
	// and source pins for source-built components.
	Pins release.BundlePins
	// Provenance is where the render came from. Captured by the caller
	// (release.CaptureProvenance), never by this package: provenance is a
	// property of a checkout and this package never sees one.
	Provenance release.Provenance
	// Reader is what the backend this bundle is recorded in decodes. The
	// document leaves out every optional part it does not name
	// (release.BundleReader.Limit): a control plane strict-decodes the
	// document, so a field it predates fails the whole record. Nil writes
	// every part — the machine ledger is read by this same forge.
	Reader *release.BundleReader
	// Shape is the declaration half of the projection, exactly as
	// [ProjectShape] takes it. Build runs the projection ITSELF, from the
	// same parse it packages, rather than accepting a finished shape —
	// which is what makes "the shape describes these manifests" true by
	// construction instead of by a caller's discipline.
	Shape ShapeInput
	// CreatedAt is the bundle's creation time. Required, and the caller's:
	// see the determinism note at the top of this file.
	CreatedAt time.Time
	// Reconciled says a reconciler (Flux) may apply this bundle, so it must be
	// safe to apply repeatedly: a Job with a TTL or without a spec hash is then
	// REFUSED rather than built. False for an env forge applies itself (a
	// local or ephemeral lifecycle, or a declared applier of forge): a
	// one-shot apply neither re-runs a TTL'd Job on a timer nor re-reconciles
	// an unhashed one, and refusing there would break builds that work today.
	// The fixes that change nothing at runtime are made either way.
	Reconciled bool
	// ReconciledUnits narrows the refusal to the delivery units a reconciler
	// applies, for an env that moves onto Flux one unit at a time: an object in
	// a unit forge still applies directly is not refused, so the first unit to
	// move is not held up by a Job in one that has not. Consulted only when
	// Reconciled is false; Reconciled true is every unit. The fixes that change
	// nothing at runtime are made for every unit regardless.
	ReconciledUnits []string
	// Units declares the delivery units' order (see release.DeliveryUnit).
	// An object's unit is its forge.dev/delivery-unit label; a unit nobody
	// declares waits for the default unit. Every real cluster is split into
	// trees by it; see release.PlanTrees.
	Units []release.DeliveryUnit
	// Placements is the complete logical dependency declaration for mixed bundles.
	// Nil is unknown, not an assertion of independence.
	Placements []PlacementDeclaration
	// Observability is the dashboards and the metrics schema the bundle
	// carries beside its manifests (see [release.BundleObservabilityPrefix]).
	// Nothing applies them, so they neither enter the shape nor the config
	// digest; they do enter the layer, and so the bundle's digest.
	Observability []ObservabilityFile
}

type Bundle struct {
	// Digest is the OCI manifest digest: the bundle's identity.
	Digest string
	// Doc is the config blob, decoded. [Bundle.ConfigBlob] is the bytes.
	Doc release.BundleDoc
	// Manifest is the OCI image manifest, as raw JSON — the bytes Digest
	// is over, so a consumer verifies against exactly what was hashed
	// rather than against a re-marshalling of the struct.
	Manifest []byte
	// GuardedObjects is how many of the layer's objects were stamped
	// prune-exempt (prune_guard.go): the ones a reconciler must never
	// delete as a side effect of a render that came out short.
	//
	// Carried so the build can SAY so. A guard nobody sees is one nobody
	// notices has stopped working, and the day it matters is the day a
	// PersistentVolumeClaim is already gone.
	GuardedObjects int
	// contains filtered or unexported fields
}

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

type Cached struct {
	// Digest is the bundle's identity.
	Digest string
	// Doc is the bundle document.
	Doc release.BundleDoc
	// Dir is the directory the manifest layer was unpacked into:
	// `manifests/<cluster>/…`.
	Dir string
	// ManifestFiles are the manifest-layer paths relative to Dir, in APPLY
	// ORDER (the render order the filenames encode).
	ManifestFiles []string
}

type Fetched struct {
	// Digest is the OCI manifest digest the reference resolved to, and the
	// digest the received bytes were verified against.
	Digest string
	// Doc is the config blob, strictly decoded.
	Doc release.BundleDoc
	// Manifests is the manifest layer, still packed. Unpack it with
	// [Unpack] — which is where the hostile-input discipline lives, and
	// the reason this is not handed back as a directory.
	Manifests []byte
}

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

type ObservabilityFile struct {
	// Path is slash-separated and under [release.BundleObservabilityPrefix].
	Path string
	Data []byte
}

type PlacementDeclaration struct {
	Workload     string
	Runtime      string
	Actuator     string
	Dependencies []string
	Unit         string
}

type Pusher interface {
	Push(ctx context.Context, expected ocispec.Descriptor, content io.Reader) error
}

type RenderedObject struct {
	// Clusters are the clusters the deploy layer routes the document to, from
	// the stream's `# cluster:` header. Empty: attributed to none, so nothing
	// applies it.
	Clusters   []string
	APIVersion string
	Kind       string
	Namespace  string
	Name       string
	// Body is the decoded document. It is nil for a Secret: a Secret never
	// rides a bundle and its values are nobody's business here, so the body is
	// not retained.
	Body map[string]any
}

type Resolver interface {
	// Resolve maps a reference (tag or digest) to its descriptor. This is
	// the HEAD — it must not transfer the content.
	Resolve(ctx context.Context, reference string) (ocispec.Descriptor, error)
	// Fetch reads the content a descriptor names.
	Fetch(ctx context.Context, target ocispec.Descriptor) (io.ReadCloser, error)
}

type SecretDocument struct {
	Clusters  []string
	Namespace string
	Name      string
	Body      map[string]any
}

type ShapeInput struct {
	// Kind is the env kind the render implies (forge's hostedEnvKindOf
	// predicate, in pkg/release vocabulary). Required.
	Kind release.EnvKind
	// Workloads, Secrets, Domains and Clusters are the declaration's own
	// projection, already in shape vocabulary. Secrets carry NAMES.
	Workloads []release.ShapeWorkload
	Secrets   []release.ShapeSecret
	Domains   []string
	Clusters  []string

	// Manifests is the env's rendered manifest stream, exactly as
	// `forge env render <env>` prints it: `---`-separated documents, each
	// optionally preceded by the `# cluster: <a>, <b>` comment naming the
	// cluster(s) a deploy routes it to. A document with no such comment,
	// or one naming none, is attributed to no cluster rather than to a
	// guessed one.
	Manifests string

	// SyncedSecrets names Secrets the env needs that forge syncs from its
	// secret store and that therefore never appear in Manifests (a
	// secret_ref projection, a declared rendered Secret). Names only. They
	// are recorded in the bundle beside the render's own Secret documents.
	SyncedSecrets []release.BundleSecretRef

	// Images maps each release artifact key to the digest this render
	// pinned it to. It is what makes [release.ShapeObject.Images] and
	// ConfigHash possible: an object's images are the pins that appear in
	// it, and its ConfigHash is its hash with those pins normalized away.
	Images map[string]string

	// StatefulWorkloads names the workloads whose objects hold data beyond
	// their own spec — in practice the env's declared ManagedDatabases,
	// whose records expand into a Postgres cluster, its Services and its
	// volumes. The well-known stateful kinds (PVC, StatefulSet, Secret, …)
	// are recognised by pkg/release without being listed here; this is for
	// the objects whose kind alone does not say so.
	StatefulWorkloads []string

	// ControlPlaneSecrets are the Secrets the env's control plane supplies and
	// renews (forge.ControlPlaneSecret), already in shape vocabulary. Names and
	// destinations; a value never reaches forge.
	ControlPlaneSecrets []release.ShapeControlPlaneSecret

	// Store is the env's store-backed secrets and the components that serve
	// them (release.ProjectStoreSecrets over the render), already in shape
	// vocabulary. The zero value records nothing.
	Store release.StoreProjection

	// Alerts and AlertRoutes are the env's resolved alert rules and routes,
	// already in shape vocabulary (see release.ShapeAlert).
	Alerts      []release.ShapeAlert
	AlertRoutes []release.ShapeAlertRoute
	// ObservabilityPolicy is the env's observability opt-out, or nil when it
	// opts out of nothing.
	ObservabilityPolicy *release.ShapeObservabilityPolicy
	// FrontendTelemetry is what each frontend declares about its browser
	// telemetry, or nil.
	FrontendTelemetry []release.ShapeFrontendTelemetry
	// DeliveryPolicy is the env's delivery policy, or nil for the defaults.
	DeliveryPolicy *release.ShapeDeliveryPolicy
	// DataAccess is the env's declared data access, or nil for the default.
	DataAccess *release.ShapeDataAccess
	// ReleaseHealth is the env's release-health policy, or nil for the
	// defaults.
	ReleaseHealth *release.ShapeReleaseHealth
	// UptimeChecks are the env's uptime checks, or nil when it has none.
	UptimeChecks []release.ShapeUptimeCheck
	// Identity is the env's managed identity declaration, or nil when it
	// declares none.
	Identity *release.ShapeIdentity
	// Databases is what the env declares about its managed databases beyond
	// their workload entries (live dashboards), or nil when it declares none.
	Databases []release.ShapeDatabase

	// Applier is the env's declared applier (release.ApplierForge or
	// release.ApplierFlux), or "".
	Applier string
	// Units is who applies each delivery unit, when the env declares a split.
	Units []release.ShapeUnit
}

type Stats struct {
	// Resolved is true when the reference was resolved (the HEAD). Always
	// true on success.
	Resolved bool
	// Pulled is true when content was transferred. FALSE ON A CACHE HIT —
	// that is the property worth asserting.
	Pulled bool
	// Digest is the resolved manifest digest.
	Digest string
}