Documentation
¶
Overview ¶
Package engine is the rolling-admission correctness core (DESIGN §3.3, D6, D13): a pure, stateless derivation of every node's state and the admissible set from live inputs (pins, observed refs, readiness). No clock, no I/O, no Kubernetes. Restart-safe by construction (DESIGN D9) — every evaluation is a full recalculation.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Admission ¶
type Admission struct {
Node adapter.NodeRef
Source types.NamespacedName
From string // previous pin ("" for initial pin)
To string // the observed SHA being admitted
ObservedRef string
Initial bool // true = initial-pin-on-discovery (§3.5.4), not ancestor-gated
PendingSince time.Time
}
Admission is a pin advance the controller should perform.
type Blocked ¶
type Blocked struct {
// Ancestor is the nearest unsettled transitive ancestor, or the blocking
// sibling for SharedSourceBlocked (zero for SelfHeld/GraphCycle).
Ancestor adapter.NodeRef
Reason BlockedReason
}
Blocked attributes a pending node's non-admission.
type BlockedReason ¶
type BlockedReason string
BlockedReason attributes why a pending node was not admitted (DESIGN §6).
const ( ReasonAncestorUnhealthy BlockedReason = "AncestorUnhealthy" ReasonAncestorPending BlockedReason = "AncestorPending" // pending or converging ReasonAncestorHeld BlockedReason = "AncestorHeld" // held or suspended ReasonAncestorUnobserved BlockedReason = "AncestorUnobserved" // no ref observation yet ReasonSelfHeld BlockedReason = "SelfHeld" ReasonGraphCycle BlockedReason = "GraphCycle" // shares its GitRepository with a sibling node that is not: a shared // source's pin is one commit, so pending-ness is a property of the // source, not of any one referencing node, and it advances only when // every referencing node is admissible (gateSharedSources). ReasonSharedSourceBlocked BlockedReason = "SharedSourceBlocked" )
type Evaluation ¶
type Evaluation struct {
Nodes map[adapter.NodeRef]NodeResult
Admissions []Admission // ancestor-gated pin advances, deterministic order
Initial []Admission // initial pins (not ancestor-gated)
}
Evaluation is one complete derivation over the graph.
func Evaluate ¶
Evaluate derives all node states and the admissible set. Pure: same inputs, same outputs; restart-safe by construction (DESIGN D9).
Only nodes present in inputs are evaluated; a graph member without an input is never assigned a NodeResult, and — being unproven — counts as unsettled wherever it appears as an ancestor.
At most one admission (gated or initial) is ever emitted per Source: two or more selected nodes sharing one GitRepository (a standard Flux monorepo topology) advance it in lockstep, gated on every referencing node being admissible, not on the least-blocked one alone (gateSharedSources).
type NodeInput ¶
type NodeInput struct {
Ref adapter.NodeRef
Role Role
Ready bool // adapter.Readiness.Ready
Failing bool // adapter.Readiness.Failing
AppliedSHA string
Source *SourceState // nil iff Role == RoleGate
}
NodeInput is one graph member's evaluation input.
type NodeResult ¶
type NodeResult struct {
State State
Held bool
Blocked *Blocked // set when Pending but not Admissible
PendingSince time.Time // zero unless pending
}
NodeResult is the derived state of one node.
type SourceState ¶
type SourceState struct {
Source types.NamespacedName
TrackingRef string // full ref name being tracked, e.g. "refs/heads/main"
Pin string // spec.ref.commit ("" = unpinned)
Held bool // commit owned by a foreign field manager
HeldBy string
Suspended bool // spec.suspend (human incident action)
ArtifactSHA string // parsed from status.artifact.revision ("" if no artifact)
FetchFailing bool // sourcev1 FetchFailed condition True (metrics only)
ObservedSHA string // latest advertised SHA of TrackingRef ("" = not observed)
FirstObserved time.Time // when ObservedSHA was first seen (admission_wait, pin lag)
}
SourceState is the controller's read of one managed GitRepository, combined with the poller's observation of its tracking ref.
Source Files