Documentation
¶
Overview ¶
Package reconcile implements repository reconciliation — a class of mutation distinct from dependency updates.
StageFreight makes two fundamentally different kinds of change:
Intentful mutations: StageFreight selects among valid futures (a newer version is available — should we take it?). These flow through candidate generation and policy (max_update, holds, review). There is a search space and discretion.
Reconciliation mutations: StageFreight makes the repository internally consistent with intent it ALREADY encodes (one file declares a requirement another file violates). There is no search space, no policy, and no discretion — the answer is already written down; the engine derives it or, when it cannot be derived canonically, reports a configuration error.
The governing invariant: a reconciler may only mutate state that is functionally dependent on an authoritative source, and authority flows one direction only (e.g. go.mod's `go` directive is authoritative for the golang builder image, never the reverse). This keeps reconciliation from ever becoming "automatic updates" under another name.
The first reconciler (go-toolchain, gotoolchain.go) enforces that a golang builder image satisfies its module's `go` directive floor. Future reconcilers of the same species — Rust edition ↔ toolchain, Cargo MSRV, Node engine ↔ builder, Terraform version ↔ runner — add sibling files returning the same Result vocabulary.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ConfigError ¶
type ConfigError struct {
Reconciler string
File string // the dependent file that cannot be reconciled
Line int
Message string
}
ConfigError is an inconsistency detected against an authoritative source for which NO canonical satisfying representation could be derived. The repository is invalid and a human must resolve it — the reconciler never guesses, never substitutes a different representation, never overshoots.
type GoBuilderObservation ¶
type GoBuilderObservation struct {
File string // repo-relative Dockerfile path
Line int // 1-based FROM line
Image string // image reference minus tag, e.g. "golang" or "docker.io/library/golang"
CurrentTag string // the builder's current tag on disk, e.g. "1.24.13", "1.24-alpine3.18"
Floor string // the governing module's `go` directive, e.g. "1.25.0"
AvailableTags []string // published tags for the builder image (a pure registry fact)
FloorSource string // human label of the floor's origin, e.g. "go.mod: go 1.25.0"
}
GoBuilderObservation is one golang builder image FROM line paired with the `go` directive floor of the module that governs it and the registry's published golang tags. It is the PURE input to go-toolchain reconciliation: all IO — reading go.mod, reading the Dockerfile FROM line, listing registry tags — is performed by the adapter that assembles these. The reconciler only derives.
type Mutation ¶
type Mutation struct {
Reconciler string // which reconciler derived it, e.g. "go-toolchain"
File string // repo-relative path to edit
Line int // 1-based line to replace
From string // current token, e.g. "golang:1.24.13"
To string // canonical token, e.g. "golang:1.25.7"
Authority string // the authoritative source that mandates it, e.g. "go.mod: go 1.25.0"
}
Mutation is a derived, non-discretionary change that makes the repository internally consistent with an already-encoded authoritative constraint. It is NOT an update: no version was chosen among valid futures. It is the single canonical representation the repository already requires.
type Result ¶
type Result struct {
Mutations []Mutation
ConfigErrors []ConfigError
}
Result is the outcome of a reconciliation pass: the derived mutations and the inconsistencies that could not be reconciled. A pass never partially decides — it reports everything it found so the caller can apply all derivable work and then fail on the config errors.
func ReconcileGoToolchain ¶
func ReconcileGoToolchain(obs []GoBuilderObservation) Result
ReconcileGoToolchain derives, for each observation, whether the golang builder satisfies its module's `go` directive floor and — when it does not — the canonical tag that does, preserving the operator's variant and tag granularity. It never selects among valid futures: the floor's minor line and the operator's variant fully determine the target, or the configuration is unreconcilable.
Source Files