Documentation
¶
Overview ¶
Package store is the central, in-memory state container for the controller pipeline. It tracks three orthogonal kinds of information for each Kubernetes-style resource (keyed by manifest.NamedResource):
- The parsed manifest object itself.
- The processing status (Pending / Ready / Failed) with an optional error message.
- The artifact produced by a controller (e.g. a checked-out git working tree, a rendered manifest, a downloaded chart).
Three event types are dispatched as state evolves: ObjectAdded, StatusUpdated, ArtifactUpdated. Callers subscribe via AddListener (sync, returns an unsubscribe function).
Store is safe for concurrent use. Listeners run inline on the goroutine that triggered the event; they MUST NOT call back into the same Store with a blocking call.
Index ¶
- Constants
- type AcquisitionState
- type AdvisoryEvidence
- type Artifact
- type ArtifactInput
- type ArtifactRead
- type AssessmentKind
- type Child
- type ChildDocuments
- type Condition
- type Declaration
- type Emission
- type EventKind
- type Gate
- type Input
- type Listener
- type Observation
- type Outcome
- type ReadSet
- func (r *ReadSet) Accept(kind AssessmentKind)
- func (r *ReadSet) AddWarning(warning manifest.Warning)
- func (r *ReadSet) Admit(child Child, source, owner manifest.NamedResource)
- func (r *ReadSet) Admitted() bool
- func (r *ReadSet) BeginExecution(obj manifest.BaseManifest)
- func (r *ReadSet) Bind(emission *Emission)
- func (r *ReadSet) Capture(input *Input) manifest.BaseManifest
- func (r *ReadSet) CarryAdvisories(previous *ReadSet)
- func (r *ReadSet) CarryWarnings(previous RenderedOutput)
- func (r *ReadSet) Close()
- func (r *ReadSet) Gates() iter.Seq[Gate]
- func (r *ReadSet) Get[T manifest.BaseManifest](id manifest.NamedResource) (T, bool)
- func (r *ReadSet) GetAcquisition(id manifest.NamedResource) AcquisitionState
- func (r *ReadSet) GetArtifact(id manifest.NamedResource, read ArtifactRead) Artifact
- func (r *ReadSet) GetDeclaration(id manifest.NamedResource) manifest.BaseManifest
- func (r *ReadSet) GetEmission(id manifest.NamedResource) (manifest.BaseManifest, map[string]any, Emission)
- func (r *ReadSet) GetObject(id manifest.NamedResource) manifest.BaseManifest
- func (r *ReadSet) GetStatus(id manifest.NamedResource) (StatusInfo, bool)
- func (r *ReadSet) ID() manifest.NamedResource
- func (r *ReadSet) IncomingProductions(child Child, index *manifest.DiscoveryIndex) []manifest.Production
- func (r *ReadSet) Init(s *Store, id manifest.NamedResource, inputs []Input)
- func (r *ReadSet) Inputs() iter.Seq[manifest.NamedResource]
- func (r *ReadSet) ListObjects(group, kind string) []manifest.BaseManifest
- func (r *ReadSet) ListProductionCandidates(group, kind string, index *manifest.DiscoveryIndex, ...) []manifest.BaseManifest
- func (r *ReadSet) Lookup(id manifest.NamedResource) (manifest.BaseManifest, manifest.DeclarationPolicy)
- func (r *ReadSet) Matches(previous *ReadSet) bool
- func (r *ReadSet) MatchesContent(previous *ReadSet, id manifest.NamedResource) bool
- func (r *ReadSet) Materializer(id manifest.NamedResource, production manifest.Production) manifest.NamedResource
- func (r *ReadSet) OrdinaryDemand(id manifest.NamedResource) bool
- func (r *ReadSet) Policy(id manifest.NamedResource) manifest.DeclarationPolicy
- func (r *ReadSet) Preflight() string
- func (r *ReadSet) Productions(id manifest.NamedResource, index *manifest.DiscoveryIndex) []manifest.Production
- func (r *ReadSet) Promotions(id manifest.NamedResource, index *manifest.DiscoveryIndex) []manifest.Production
- func (r *ReadSet) QualificationSettled(id manifest.NamedResource) bool
- func (r *ReadSet) RecordSuppliedOverride(override SuppliedOverride)
- func (r *ReadSet) ReferenceFacts(id manifest.NamedResource, index *manifest.DiscoveryIndex, ...) ReferenceFacts
- func (r *ReadSet) ReleaseCapture()
- func (r *ReadSet) ReplacesInvalid() bool
- func (r *ReadSet) Require(ref manifest.DependencyRef)
- func (r *ReadSet) RequireData(id manifest.NamedResource)
- func (r *ReadSet) RequireMaterializer(id manifest.NamedResource)
- func (r *ReadSet) RequireQualification(id manifest.NamedResource)
- func (r *ReadSet) Required() iter.Seq2[manifest.NamedResource, bool]
- func (r *ReadSet) Retire()
- func (r *ReadSet) SetAcquisition(state AcquisitionState)
- func (r *ReadSet) SetWork(work *manifest.WorkRecorder)
- func (r *ReadSet) Snapshot(id manifest.NamedResource, conditions bool) (manifest.BaseManifest, Observation)
- func (r *ReadSet) SourceAdmission(id, source manifest.NamedResource) bool
- func (r *ReadSet) UnsettledProducers(id manifest.NamedResource) []manifest.NamedResource
- func (r *ReadSet) Valid() bool
- func (r *ReadSet) Work() *manifest.WorkRecorder
- func (r *ReadSet) WorkScope() manifest.WorkScope
- type ReferenceFacts
- type RenderedOutput
- type SourceArtifact
- type Status
- type StatusInfo
- func (i StatusInfo) BlockedBy() []manifest.NamedResource
- func (i StatusInfo) DependencyReason(subject manifest.DiagnosticIdentity) manifest.DiagnosticReason
- func (i StatusInfo) IsDependencyFailure() bool
- func (i StatusInfo) IsUnavailable() bool
- func (i StatusInfo) MarshalJSON() ([]byte, error)
- func (i StatusInfo) Outcome() Outcome
- func (i StatusInfo) String() string
- type StatusReason
- type Store
- func (s *Store) AddDeclaration(child Declaration)
- func (s *Store) AddListener(event EventKind, fn Listener, flush bool) Unsubscribe
- func (s *Store) AddObject(obj manifest.BaseManifest, docs ...map[string]any)
- func (s *Store) AddObjects(objs []manifest.BaseManifest)
- func (s *Store) AddWarning(w manifest.Warning)
- func (s *Store) AdvisoryEvidence() AdvisoryEvidence
- func (s *Store) ChildFootprint(parent manifest.NamedResource, children []Child, ...) iter.Seq2[manifest.NamedResource, manifest.DiscoveryRecord]
- func (s *Store) ChildSourcePaths(parent manifest.NamedResource, children []Child, ...) []manifest.SourceEvidence
- func (s *Store) DeleteObject(id manifest.NamedResource) bool
- func (s *Store) EmissionOwner(id manifest.NamedResource) manifest.NamedResource
- func (s *Store) FailedResources() map[manifest.NamedResource]StatusInfo
- func (s *Store) Get[T manifest.BaseManifest](id manifest.NamedResource) (T, bool)
- func (s *Store) GetArtifact(id manifest.NamedResource, _ ArtifactRead) Artifact
- func (s *Store) GetDeclaration(id manifest.NamedResource) manifest.BaseManifest
- func (s *Store) GetEmission(id manifest.NamedResource) (manifest.BaseManifest, map[string]any, Emission)
- func (s *Store) GetObject(id manifest.NamedResource) manifest.BaseManifest
- func (s *Store) GetStatus(id manifest.NamedResource) (StatusInfo, bool)
- func (s *Store) HasGeneratedObjects(id manifest.NamedResource) bool
- func (s *Store) HasInventory(id manifest.NamedResource) bool
- func (s *Store) IncomingProductions(child Child, index *manifest.DiscoveryIndex) []manifest.Production
- func (s *Store) ListAs[T manifest.BaseManifest](group, kind string) []T
- func (s *Store) ListObjects(group, kind string) []manifest.BaseManifest
- func (s *Store) ListProductionCandidates(group, kind string, index *manifest.DiscoveryIndex, ...) []manifest.BaseManifest
- func (s *Store) Lookup(id manifest.NamedResource) (manifest.BaseManifest, manifest.DeclarationPolicy)
- func (s *Store) Objects() []manifest.BaseManifest
- func (s *Store) Policy(id manifest.NamedResource) manifest.DeclarationPolicy
- func (s *Store) Productions(id manifest.NamedResource, index *manifest.DiscoveryIndex) []manifest.Production
- func (s *Store) RecordEmitted(id manifest.NamedResource, next *Emission, ...)
- func (s *Store) ReferenceFacts(id manifest.NamedResource, index *manifest.DiscoveryIndex, ...) ReferenceFacts
- func (s *Store) RenderedParent(id manifest.NamedResource, index *manifest.DiscoveryIndex) (manifest.NamedResource, bool)
- func (s *Store) ReportHidden(id manifest.NamedResource) bool
- func (s *Store) ReportProgress(id manifest.NamedResource, message string)
- func (s *Store) ReportStatus(id manifest.NamedResource) (StatusInfo, bool)
- func (s *Store) RequiredInputs(id manifest.NamedResource) iter.Seq2[manifest.NamedResource, bool]
- func (s *Store) Retire(reads *ReadSet)
- func (s *Store) SetArtifact(id manifest.NamedResource, artifact *SourceArtifact)
- func (s *Store) SetCondition(id manifest.NamedResource, cond Condition)
- func (s *Store) SetDiscoveryIndex(index *manifest.DiscoveryIndex)
- func (s *Store) SetIncluded(id manifest.NamedResource, included, ordinary bool)
- func (s *Store) SetPreflight(id manifest.NamedResource, message string)
- func (s *Store) SetWorkTree(tree manifest.TreeID, scope manifest.WorkScope)
- func (s *Store) Snapshot(id manifest.NamedResource, conditions bool) (manifest.BaseManifest, Observation)
- func (s *Store) SourceAdmission(id, source manifest.NamedResource) bool
- func (s *Store) Sweep() iter.Seq[manifest.NamedResource]
- func (s *Store) UpdateFailure(id manifest.NamedResource, err error)
- func (s *Store) UpdateStatus(id manifest.NamedResource, info StatusInfo)
- func (s *Store) Warnings() []manifest.Warning
- func (s *Store) WorkScope() manifest.WorkScope
- func (s *Store) WorkSnapshot() manifest.WorkSummary
- type SuppliedOverride
- type Unsubscribe
Constants ¶
const ( ConditionReady = "Ready" ConditionHealthy = "Healthy" )
Condition type identifiers used by flate. These mirror Flux's conventions so a future watch-mode could publish to a real cluster without translating.
const ( ReasonSucceeded = "Succeeded" ReasonFailed = "Failed" ReasonReconciling = "Reconciling" )
Condition reasons attached to the Ready condition.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type AcquisitionState ¶ added in v0.7.3
type AcquisitionState uint8
AcquisitionState grants no content authority without valid captured evidence.
const ( AcquisitionPending AcquisitionState = iota AcquisitionPrepared AcquisitionSkipped )
Acquisition results describe credential settlement separately from source readiness.
type AdvisoryEvidence ¶ added in v0.7.3
type AdvisoryEvidence struct {
Overrides []SuppliedOverride
}
AdvisoryEvidence retains accepted facts for cluster advisory publication.
type Artifact ¶
type Artifact interface {
// contains filtered or unexported methods
}
Artifact is a marker interface implemented by every artifact type. Controllers type-assert to the concrete type they expect.
type ArtifactInput ¶ added in v0.7.3
type ArtifactInput struct {
Present bool `json:"Present"`
Readable bool `json:"Readable"`
Kind string `json:"Kind"`
Key string `json:"Key"`
Content string `json:"Content"`
Digest string `json:"Digest"`
LocalRoot string `json:"LocalRoot"`
LocalPath string `json:"LocalPath"`
InputAlias bool `json:"InputAlias"`
Revision string `json:"Revision"`
Origin string `json:"Origin"`
OriginPresent bool `json:"OriginPresent"`
}
ArtifactInput is the comparable projection of selected source facts.
type ArtifactRead ¶ added in v0.7.3
type ArtifactRead uint8
ArtifactRead selects the source facts consumed by an execution.
const ( // ArtifactContent selects content availability, generation and source binding. ArtifactContent ArtifactRead = 1 << iota // ArtifactRevision selects the human-readable source revision. ArtifactRevision // ArtifactOrigin selects origin revision and its presence. ArtifactOrigin )
type AssessmentKind ¶ added in v0.7.3
type AssessmentKind uint8
AssessmentKind keeps entry bindings separate from reconciliation acceptance.
const ( AssessmentReconciled AssessmentKind = iota AssessmentReused AssessmentQualificationSettled AssessmentEntryBinding )
Assessment dispositions select one of the two independent acceptance slots.
type Child ¶ added in v0.7.3
type Child struct {
Entry *manifest.EntryApplication
SourceSupport manifest.NamedResource
Obj manifest.BaseManifest
Doc map[string]any
Generated bool
Origin manifest.DeclarationOrigin
Productions []manifest.Production
Warnings []manifest.Warning `json:"-"`
// contains filtered or unexported fields
}
Child retains an admitted object and its authoritative sanitized document.
func (Child) Policy ¶ added in v0.7.3
func (c Child) Policy(id manifest.NamedResource) manifest.DeclarationPolicy
Policy derives execution roles from an incoming or captured declaration envelope.
type ChildDocuments ¶ added in v0.7.3
type ChildDocuments struct {
Children []Child
Visible []manifest.DocOccurrence
Failures []manifest.DocOccurrence
}
ChildDocuments retains admission failures beside successfully parsed documents.
type Condition ¶
Condition is an alias for k8s metav1.Condition. flate stores per-resource conditions so SOPS-encrypted-secret detection, health-check rollups, and Flux's dependsOn ReadyExpr CEL evaluation can interoperate with the rest of the K8s ecosystem.
type Declaration ¶ added in v0.7.3
type Declaration struct {
Obj manifest.BaseManifest
Doc map[string]any
Origin manifest.DeclarationOrigin
InputPath string
Ordinal int
Warnings []manifest.Warning `json:"-"`
// contains filtered or unexported fields
}
Declaration associates an immutable input object with its origin and provenance.
type Emission ¶ added in v0.7.3
type Emission struct {
// Reads records the accepted assessment's consumed inputs.
Reads *ReadSet
// OutputReads retains provenance for attempted output or the last complete inventory.
OutputReads *ReadSet
Children []Child
Manifests []manifest.DocOccurrence
Failures []manifest.DocOccurrence
Fingerprint string
Unreadable []manifest.NamedResource
Complete bool
// Render retains immutable pre-admission renderer metadata and output.
Render *manifest.RenderReceipt
// contains filtered or unexported fields
}
Emission is an immutable assessed inventory. Maps and objects are borrowed read-only.
func (*Emission) Finish ¶ added in v0.7.3
func (e *Emission) Finish()
Finish retains completed renderer bytes across rejected admission without retaining its captures.
func (*Emission) Footprint ¶ added in v0.7.3
func (e *Emission) Footprint() iter.Seq2[manifest.NamedResource, manifest.DiscoveryRecord]
Footprint projects the exact complete inventory accepted by this invocation. A nil iterator denotes an unaccepted or incomplete attempt.
func (*Emission) Replay ¶ added in v0.7.3
func (e *Emission) Replay(fingerprint string) (RenderedOutput, bool)
Replay returns completed content matching the caller's canonical input key. Stale accepted inventory remains unavailable through GetEmission.
func (*Emission) Retains ¶ added in v0.7.3
Retains reports whether an accepted assessment or borrowed descriptor still owns reads.
func (*Emission) SourcePaths ¶ added in v0.7.3
func (e *Emission) SourcePaths() []manifest.SourceEvidence
SourcePaths projects the source paths of a complete accepted inventory.
type EventKind ¶
type EventKind int
EventKind enumerates the three observable changes the Store dispatches.
const ( // EventObjectAdded fires on publication, the first explicit inclusion of a // present manifest, or registration with flush=true to replay existing state. EventObjectAdded EventKind = iota + 1 // EventStatusUpdated reports condition transitions and transient reconciliation progress. EventStatusUpdated // EventArtifactUpdated fires when an artifact is stored. EventArtifactUpdated )
type Gate ¶ added in v0.7.3
type Gate struct {
manifest.DependencyRef
Materializer bool
}
Gate retains a readiness expression and its dependency purpose.
type Input ¶ added in v0.7.3
type Input struct {
Ref manifest.DependencyRef
// contains filtered or unexported fields
}
Input co-owns a captured dependency and its authority registrations. Its observations MUST remain immutable while retained for content comparison.
type Listener ¶
type Listener func(id manifest.NamedResource, payload any)
Listener receives store events. The payload type depends on EventKind:
- EventObjectAdded → manifest.BaseManifest
- EventStatusUpdated → StatusInfo
- EventArtifactUpdated → Artifact
Listeners run synchronously on the goroutine that triggered the event, so they MUST NOT call back into the same Store with a blocking call.
type Observation ¶ added in v0.7.3
type Observation struct {
StatusInfo
Conditions []Condition
Statusful bool
}
Observation holds the requested readiness facts from a coherent Snapshot.
type Outcome ¶ added in v0.7.3
type Outcome string
Outcome classifies a resource's readiness and failure provenance.
type ReadSet ¶ added in v0.7.3
type ReadSet struct {
// contains filtered or unexported fields
}
ReadSet retains the immutable inputs consumed by one execution. Its storage MUST remain owned until subscriptions and retained comparisons finish.
func (*ReadSet) Accept ¶ added in v0.7.3
func (r *ReadSet) Accept(kind AssessmentKind)
Accept publishes only against the predecessor captured by this execution.
func (*ReadSet) AddWarning ¶ added in v0.7.3
AddWarning retains a render advisory in this execution's accepted bundle.
func (*ReadSet) Admit ¶ added in v0.7.3
func (r *ReadSet) Admit(child Child, source, owner manifest.NamedResource)
Admit binds raw-file admission to the captured source that supplied its bytes.
func (*ReadSet) BeginExecution ¶ added in v0.7.3
func (r *ReadSet) BeginExecution(obj manifest.BaseManifest)
BeginExecution borrows optional run-owned counters for an execution.
func (*ReadSet) Bind ¶ added in v0.7.3
Bind attaches consumed provenance and retains prospective children before publication.
func (*ReadSet) Capture ¶ added in v0.7.3
func (r *ReadSet) Capture(input *Input) manifest.BaseManifest
Capture records a caller-owned named input without reconstructing its identity index.
func (*ReadSet) CarryAdvisories ¶ added in v0.7.3
CarryAdvisories copies precedence facts after the caller proves equal consumed inputs.
func (*ReadSet) CarryWarnings ¶ added in v0.7.3
func (r *ReadSet) CarryWarnings(previous RenderedOutput)
CarryWarnings reuses advisories after the caller verifies an equal consumed projection.
func (*ReadSet) Close ¶ added in v0.7.3
func (r *ReadSet) Close()
Close retires captured assessment cells and the origin's borrowed output. Callers MUST stop work for the origin before closing.
func (*ReadSet) Get ¶ added in v0.7.3
func (r *ReadSet) Get[T manifest.BaseManifest](id manifest.NamedResource) (T, bool)
Get returns the captured object asserted to T.
func (*ReadSet) GetAcquisition ¶ added in v0.7.3
func (r *ReadSet) GetAcquisition(id manifest.NamedResource) AcquisitionState
GetAcquisition freezes the accepted result for this capture.
func (*ReadSet) GetArtifact ¶ added in v0.7.3
func (r *ReadSet) GetArtifact(id manifest.NamedResource, read ArtifactRead) Artifact
GetArtifact captures fetched content or accepted output for a dependency.
func (*ReadSet) GetDeclaration ¶ added in v0.7.3
func (r *ReadSet) GetDeclaration(id manifest.NamedResource) manifest.BaseManifest
GetDeclaration captures the effective input authorized by static or accepted support.
func (*ReadSet) GetEmission ¶ added in v0.7.3
func (r *ReadSet) GetEmission(id manifest.NamedResource) (manifest.BaseManifest, map[string]any, Emission)
GetEmission binds candidate output to this execution's captured declaration and source.
func (*ReadSet) GetObject ¶ added in v0.7.3
func (r *ReadSet) GetObject(id manifest.NamedResource) manifest.BaseManifest
GetObject captures a named object, including its absence and supplying producer.
func (*ReadSet) GetStatus ¶ added in v0.7.3
func (r *ReadSet) GetStatus(id manifest.NamedResource) (StatusInfo, bool)
GetStatus captures the readiness condition used by an assessment.
func (*ReadSet) ID ¶ added in v0.7.3
func (r *ReadSet) ID() manifest.NamedResource
ID identifies the execution that owns these inputs.
func (*ReadSet) IncomingProductions ¶ added in v0.7.3
func (r *ReadSet) IncomingProductions(child Child, index *manifest.DiscoveryIndex) []manifest.Production
IncomingProductions captures prospective source and contributor evidence without reading the target.
func (*ReadSet) Init ¶ added in v0.7.3
func (r *ReadSet) Init(s *Store, id manifest.NamedResource, inputs []Input)
Init starts an execution using caller-owned dependency storage. Reused storage MUST have no live or detached registration or output borrower.
func (*ReadSet) Inputs ¶ added in v0.7.3
func (r *ReadSet) Inputs() iter.Seq[manifest.NamedResource]
Inputs yields the concrete identities captured by the completed execution. The owning output MUST keep the read set immutable throughout iteration.
func (*ReadSet) ListObjects ¶ added in v0.7.3
func (r *ReadSet) ListObjects(group, kind string) []manifest.BaseManifest
ListObjects captures the kind bucket and every candidate consulted by selection.
func (*ReadSet) ListProductionCandidates ¶ added in v0.7.3
func (r *ReadSet) ListProductionCandidates( group, kind string, index *manifest.DiscoveryIndex, prospective map[manifest.NamedResource]bool, ) []manifest.BaseManifest
ListProductionCandidates captures visible objects with indexed, prospective, or published ownership. A prospective key without a namespace includes every namespace.
func (*ReadSet) Lookup ¶ added in v0.7.3
func (r *ReadSet) Lookup(id manifest.NamedResource) (manifest.BaseManifest, manifest.DeclarationPolicy)
Lookup MUST return the object and policy from one captured authority.
func (*ReadSet) Matches ¶ added in v0.7.3
Matches recaptures a predecessor's consumed projections in a fresh execution.
func (*ReadSet) MatchesContent ¶ added in v0.7.3
func (r *ReadSet) MatchesContent(previous *ReadSet, id manifest.NamedResource) bool
MatchesContent compares captured content without granting current authority. Both captures MUST have finished recording and retain their observation payloads.
func (*ReadSet) Materializer ¶ added in v0.7.3
func (r *ReadSet) Materializer(id manifest.NamedResource, production manifest.Production) manifest.NamedResource
Materializer selects and captures the runnable declaration supplying a production.
func (*ReadSet) OrdinaryDemand ¶ added in v0.7.3
func (r *ReadSet) OrdinaryDemand(id manifest.NamedResource) bool
OrdinaryDemand captures purpose so later promotion invalidates qualification settlement.
func (*ReadSet) Policy ¶ added in v0.7.3
func (r *ReadSet) Policy(id manifest.NamedResource) manifest.DeclarationPolicy
Policy MUST retain the origin captured with the object.
func (*ReadSet) Preflight ¶ added in v0.7.3
Preflight returns the captured structural admission failure.
func (*ReadSet) Productions ¶ added in v0.7.3
func (r *ReadSet) Productions(id manifest.NamedResource, index *manifest.DiscoveryIndex) []manifest.Production
Productions captures all contributors and discovery evidence for a named input.
func (*ReadSet) Promotions ¶ added in v0.7.3
func (r *ReadSet) Promotions(id manifest.NamedResource, index *manifest.DiscoveryIndex) []manifest.Production
Promotions captures source-family evidence before conditional raw-file admission. The target itself is a mutation precondition until admission has completed.
func (*ReadSet) QualificationSettled ¶ added in v0.7.3
func (r *ReadSet) QualificationSettled(id manifest.NamedResource) bool
QualificationSettled MUST retain the original assessment's validity around capture matching.
func (*ReadSet) RecordSuppliedOverride ¶ added in v0.7.3
func (r *ReadSet) RecordSuppliedOverride(override SuppliedOverride)
RecordSuppliedOverride retains a copied precedence fact in this execution.
func (*ReadSet) ReferenceFacts ¶ added in v0.7.3
func (r *ReadSet) ReferenceFacts( id manifest.NamedResource, index *manifest.DiscoveryIndex, consumer manifest.NamedResource, ) ReferenceFacts
ReferenceFacts captures visible data and its accepted source-qualified authority.
func (*ReadSet) ReleaseCapture ¶ added in v0.7.3
func (r *ReadSet) ReleaseCapture()
ReleaseCapture MUST follow evaluation, replay and every output borrow.
func (*ReadSet) ReplacesInvalid ¶ added in v0.7.3
ReplacesInvalid reports whether this attempt supersedes a stale accepted assessment.
func (*ReadSet) Require ¶ added in v0.7.3
func (r *ReadSet) Require(ref manifest.DependencyRef)
Require retains each distinct readiness gate in the execution footprint.
func (*ReadSet) RequireData ¶ added in v0.7.3
func (r *ReadSet) RequireData(id manifest.NamedResource)
RequireData records a required semantic input without imposing readiness.
func (*ReadSet) RequireMaterializer ¶ added in v0.7.3
func (r *ReadSet) RequireMaterializer(id manifest.NamedResource)
RequireMaterializer retains a supplier's status-aware readiness assessment.
func (*ReadSet) RequireQualification ¶ added in v0.7.3
func (r *ReadSet) RequireQualification(id manifest.NamedResource)
RequireQualification retains demand without authorizing an ordinary producer body.
func (*ReadSet) Required ¶ added in v0.7.3
Required enumerates the required inputs of the accepted execution.
func (*ReadSet) Retire ¶ added in v0.7.3
func (r *ReadSet) Retire()
Retire releases only this execution's subscriptions at the next boundary.
func (*ReadSet) SetAcquisition ¶ added in v0.7.3
func (r *ReadSet) SetAcquisition(state AcquisitionState)
SetAcquisition stages settlement without changing the accepted result.
func (*ReadSet) SetWork ¶ added in v0.7.3
func (r *ReadSet) SetWork(work *manifest.WorkRecorder)
SetWork borrows invocation-owned recording storage for a temporary proof.
func (*ReadSet) Snapshot ¶ added in v0.7.3
func (r *ReadSet) Snapshot(id manifest.NamedResource, conditions bool) (manifest.BaseManifest, Observation)
Snapshot captures the declaration and requested readiness facts.
func (*ReadSet) SourceAdmission ¶ added in v0.7.3
func (r *ReadSet) SourceAdmission(id, source manifest.NamedResource) bool
SourceAdmission captures whether accepted output still permits initial source support.
func (*ReadSet) UnsettledProducers ¶ added in v0.7.3
func (r *ReadSet) UnsettledProducers(id manifest.NamedResource) []manifest.NamedResource
UnsettledProducers captures contributors needed to supply an unpublished declaration. Availability MUST NOT become a content projection for artifact reuse.
func (*ReadSet) Valid ¶ added in v0.7.3
Valid reports whether every consumed authority still has its original stamp.
func (*ReadSet) Work ¶ added in v0.7.3
func (r *ReadSet) Work() *manifest.WorkRecorder
Work returns this operation's accounting, including a borrowed proof's parent.
type ReferenceFacts ¶ added in v0.7.3
type ReferenceFacts struct {
Data manifest.Data
Materializers []manifest.NamedResource
Generated, Offline, Private bool
Accepted bool
Productions []manifest.Production
ReferenceData []manifest.ReferenceData
}
ReferenceFacts preserves visible data separately from accepted authority and relations.
func (*ReferenceFacts) AllowsAbsence ¶ added in v0.7.3
func (f *ReferenceFacts) AllowsAbsence() bool
AllowsAbsence MUST preserve omission policy for producer-owned inputs.
type RenderedOutput ¶ added in v0.7.3
type RenderedOutput struct {
// Render retains immutable pre-admission renderer metadata and output.
Render *manifest.RenderReceipt
Children []Child
Manifests []manifest.DocOccurrence
Fingerprint string
Unreadable []manifest.NamedResource
// contains filtered or unexported fields
}
RenderedOutput retains keyed render content without assessment registrations. Its objects, documents and warning details MUST remain immutable.
type SourceArtifact ¶
type SourceArtifact struct {
// Reads retains the declaration and material that produced this acquisition.
Reads *ReadSet
Kind string
URL string
LocalPath string
Revision string
// Content identifies the exact acquired filesystem generation and shaping.
Content string
Digest string
Size int64
Metadata map[string]string
// LocalRoot is the selected input's ownership origin, which may be synthetic.
// Only an admitted bootstrap uses its original checkout root for Git metadata.
LocalRoot string
// Key identifies an acquisition family; Content identifies its admitted generation.
// Empty Content with FS denotes mutable content requiring cache validation.
// Nonempty Key without FS requires acquisition before reading.
Key string
// InputAlias marks source shaping derived from the selected bootstrap input,
// rather than an authored committed source pin.
InputAlias bool
// FS supplies acquired content; LocalPath and LocalRoot are coordinates only.
// Nil FS is unavailable or existence-only, regardless of Key or LocalPath.
FS fs.FS
// Warnings is immutable acquisition evidence, excluded from content identity.
Warnings []manifest.Warning
// ContentFingerprint lazily identifies selected bytes at their source owner.
// Nil or an empty result supplies no equality evidence; acquisition identity stays separate.
ContentFingerprint func(context.Context, fs.FS) (string, error) `json:"-"`
// contains filtered or unexported fields
}
SourceArtifact retains content and metadata acquired by a source owner.
func (*SourceArtifact) HistoryIdentity ¶ added in v0.7.3
func (a *SourceArtifact) HistoryIdentity(source manifest.NamedResource) manifest.SourceIdentity
HistoryIdentity identifies a qualified source family across changed filesystem generations.
func (*SourceArtifact) Input ¶ added in v0.7.3
func (a *SourceArtifact) Input(read ArtifactRead) ArtifactInput
Input returns the selected facts without retaining filesystem handles or metadata maps.
func (*SourceArtifact) OriginPath ¶ added in v0.7.3
func (a *SourceArtifact) OriginPath(file string) string
OriginPath projects mutable inputs and aliases onto their physical input origin. file MUST be within the admitted artifact's LocalPath.
func (*SourceArtifact) WithReads ¶ added in v0.7.3
func (a *SourceArtifact) WithReads(reads *ReadSet) *SourceArtifact
WithReads retains the acquired material while replacing its execution registrations.
type Status ¶
type Status string
Status is the processing state of a resource as projected from its Ready condition. Kept as a high-level rollup for callers (depwait, `test` reporting) that don't need the full condition slice.
type StatusInfo ¶
type StatusInfo struct {
Status Status
Reason StatusReason
Message string
// contains filtered or unexported fields
}
StatusInfo projects readiness, reason, message and failure provenance from a Ready condition.
func ApplyingStatus ¶ added in v0.7.3
func ApplyingStatus(objects int) StatusInfo
ApplyingStatus records pending progress without formatting its object count.
func (StatusInfo) BlockedBy ¶ added in v0.7.3
func (i StatusInfo) BlockedBy() []manifest.NamedResource
BlockedBy returns a copy of the immediate failed dependencies in this snapshot.
func (StatusInfo) DependencyReason ¶ added in v0.7.3
func (i StatusInfo) DependencyReason(subject manifest.DiagnosticIdentity) manifest.DiagnosticReason
DependencyReason returns detached failure context for nested dependency propagation.
func (StatusInfo) IsDependencyFailure ¶ added in v0.7.3
func (i StatusInfo) IsDependencyFailure() bool
IsDependencyFailure reports whether the Failed status came from failed dependencies.
func (StatusInfo) IsUnavailable ¶ added in v0.7.3
func (i StatusInfo) IsUnavailable() bool
IsUnavailable reports whether a producer's output cannot be compared.
func (StatusInfo) MarshalJSON ¶ added in v0.7.3
func (i StatusInfo) MarshalJSON() ([]byte, error)
MarshalJSON encodes the visible status message with its readiness and reason.
func (StatusInfo) Outcome ¶ added in v0.7.3
func (i StatusInfo) Outcome() Outcome
Outcome returns the semantic outcome independently of diagnostic text.
func (StatusInfo) String ¶ added in v0.7.3
func (i StatusInfo) String() string
String returns the visible status message.
type StatusReason ¶ added in v0.7.3
type StatusReason string
StatusReason identifies a Ready condition's machine-readable reason.
const ( ReasonSkipped StatusReason = "Skipped" ReasonUnchanged StatusReason = "Unchanged" ReasonSuspended StatusReason = "Suspended" )
Special Ready condition reasons.
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store is the central in-memory state container.
Sharded layout ¶
The Store's hot state is sharded across shardCount shards keyed by the FNV-1a hash of id.Kind. Reads and writes on different Kinds no longer serialize on a single global lock — the profile evidence from `buroa/k8s-gitops` had `store.SetCondition` + `UpdateStatus` contributing ~17% of total mutex delay on a warm 1.1s run, almost all of it cross-Kind contention (KS writers blocking HR writers blocking source-controller readers).
Cross-shard operations (the ListObjects("", ""), FailedResources, AddListener(replay=true) iterate-everything paths) acquire every shard in ascending index order via lockAll/unlockAll. Holding all shards in canonical order is mandatory: any code path that locks two or more shards MUST do so via lockAll / rLockAll — taking them out-of-order or interleaving with shardFor's lock will deadlock.
Immutability contract ¶
Objects passed to AddObject (and returned by GetObject / ListObjects) are treated as IMMUTABLE after insertion. The store returns shared pointers rather than defensive copies for performance: rendering pipelines read millions of fields per reconcile, and cloning the full manifest tree on every read would dominate CPU.
Callers that need to "modify" a stored object must:
- Shallow-copy the struct (most manifest types are flat enough that *clone := *orig works).
- Mutate the copy's fields.
- Re-AddObject the modified copy. AddObject's content dedup avoids spurious events, and the second-pass dispatch reaches downstream controllers.
Mutating an object after AddObject is a bug — concurrent readers will see torn state and AddObject's dedup will compare against a moving target. The loader (pkg/loader/inherit.go) and orchestrator (pkg/orchestrator/orchestrator.go) follow the clone-then-AddObject pattern; any new mutation site should too.
func (*Store) AddDeclaration ¶ added in v0.7.3
func (s *Store) AddDeclaration(child Declaration)
AddDeclaration admits an immutable declaration under its origin's authority.
func (*Store) AddListener ¶
func (s *Store) AddListener(event EventKind, fn Listener, flush bool) Unsubscribe
AddListener registers a callback for the given event kind. When flush==true, the listener is immediately invoked with every matching object already in the store before the call returns. Replay order is unspecified (Go-map iteration); listeners that need a deterministic order must sort what they receive. Listener panics during replay are recovered, same as live dispatch. The returned Unsubscribe removes the listener.
Lock strategy (sharded):
- flush=false: holds every shard's RLock during set.add so a concurrent writer can't snapshot listeners (fireUnderLock) and dispatch before fn is registered. We need RLocks on ALL shards because a writer on any shard runs fireUnderLock under its own shard's write lock — without holding every shard's RLock here, a concurrent writer on shard X could snapshot listeners (not yet including fn), release shard X's lock, and dispatch while fn is being added. The cost (one rLockAll per AddListener) is paid once at controller wiring time, not on the dispatch hot path.
- flush=true: holds every shard's write lock across (register + snapshot) so the pair is atomic with respect to writers. Without the write locks, a concurrent AddObject on some shard could update its map, snapshot listeners (already including fn via set.add), and dispatch — while this goroutine replays the same object from the post-update map snapshot, double-firing fn. Exactly-one delivery is the invariant; the canonical-order lockAll prevents deadlock between two simultaneous flush=true calls.
func (*Store) AddObject ¶
func (s *Store) AddObject(obj manifest.BaseManifest, docs ...map[string]any)
AddObject inserts a manifest. Equal content with unchanged authority is a no-op.
func (*Store) AddObjects ¶
func (s *Store) AddObjects(objs []manifest.BaseManifest)
AddObjects admits every changed sibling before dispatching any event.
func (*Store) AddWarning ¶ added in v0.4.6
AddWarning retains each complete direct warning payload once, ignoring incoming Count.
func (*Store) AdvisoryEvidence ¶ added in v0.7.3
func (s *Store) AdvisoryEvidence() AdvisoryEvidence
AdvisoryEvidence returns defensive copies of current valid accepted facts.
func (*Store) ChildFootprint ¶ added in v0.7.3
func (s *Store) ChildFootprint( parent manifest.NamedResource, children []Child, index *manifest.DiscoveryIndex, ) iter.Seq2[manifest.NamedResource, manifest.DiscoveryRecord]
ChildFootprint projects a complete parsed batch using the supplied discovery evidence. Objects, documents and index records are borrowed and MUST remain immutable.
func (*Store) ChildSourcePaths ¶ added in v0.7.3
func (s *Store) ChildSourcePaths( parent manifest.NamedResource, children []Child, index *manifest.DiscoveryIndex, ) []manifest.SourceEvidence
ChildSourcePaths projects the source paths of a complete discovery batch.
func (*Store) DeleteObject ¶
func (s *Store) DeleteObject(id manifest.NamedResource) bool
DeleteObject removes static authority and its condition/artifact payloads.
func (*Store) EmissionOwner ¶ added in v0.7.3
func (s *Store) EmissionOwner(id manifest.NamedResource) manifest.NamedResource
EmissionOwner returns the generated producer supplying the representative for id. Static, hidden or absent representatives have an empty owner. This individual read does not form an atomic pair with a separate GetEmission call.
func (*Store) FailedResources ¶
func (s *Store) FailedResources() map[manifest.NamedResource]StatusInfo
FailedResources returns every (id, info) currently in Failed state for an object that is also present in the store. The "also present" gate filters phantom entries: DeleteObject wipes the conditions map, but a SetCondition that lands AFTER the delete (e.g. a slow reconcile goroutine writing back its terminal status) would otherwise resurrect a failure entry for an id that no longer exists. Conditioning on s.objects ensures FailedResources never reports a failure for a resource the orchestrator has explicitly removed.
Iterating conditions rather than objects is faster when most objects don't have conditions yet (common during bootstrap) — avoids the secondary map lookup for every un-reconciled object.
Cross-shard read: walks every shard's conditions/objects. Each shard is RLocked independently in canonical (ascending) order via rLockAll because conditions and objects for a single id always share the same shard, so per-shard reads suffice to detect the phantom — no global lock needed beyond the canonical-order ordering itself, which prevents lockAll-vs-rLockAll deadlocks.
func (*Store) Get ¶ added in v0.6.0
func (s *Store) Get[T manifest.BaseManifest](id manifest.NamedResource) (T, bool)
Get fetches the object at id and asserts it to T. Returns (zero, false) when absent, stored under another type, or s is nil.
func (*Store) GetArtifact ¶
func (s *Store) GetArtifact(id manifest.NamedResource, _ ArtifactRead) Artifact
GetArtifact returns the artifact for id, or nil if none was set.
func (*Store) GetDeclaration ¶ added in v0.7.3
func (s *Store) GetDeclaration(id manifest.NamedResource) manifest.BaseManifest
GetDeclaration returns the effective input authorized by static or accepted support.
func (*Store) GetEmission ¶ added in v0.7.3
func (s *Store) GetEmission(id manifest.NamedResource) (manifest.BaseManifest, map[string]any, Emission)
GetEmission borrows valid accepted inventory and binds an attempt to its current input. The captured document remains available while declaration authority is parked. Render identity is available through Emission.Replay. OutputReads preserves validity evidence for withdrawal without exposing invalid inventory. Returned slices and their contents MUST be copied before mutation.
func (*Store) GetObject ¶
func (s *Store) GetObject(id manifest.NamedResource) manifest.BaseManifest
GetObject returns the manifest for id, or nil if not present.
func (*Store) GetStatus ¶
func (s *Store) GetStatus(id manifest.NamedResource) (StatusInfo, bool)
GetStatus returns the Ready-derived StatusInfo for id and whether a Ready condition was present.
func (*Store) HasGeneratedObjects ¶ added in v0.7.3
func (s *Store) HasGeneratedObjects(id manifest.NamedResource) bool
HasGeneratedObjects reports whether retained inventory contains auxiliary declarations.
func (*Store) HasInventory ¶ added in v0.7.3
func (s *Store) HasInventory(id manifest.NamedResource) bool
HasInventory reports whether a producer has published an inventory, including hidden output.
func (*Store) IncomingProductions ¶ added in v0.7.3
func (s *Store) IncomingProductions(child Child, index *manifest.DiscoveryIndex) []manifest.Production
IncomingProductions projects prospective evidence without the stored target's state.
func (*Store) ListAs ¶ added in v0.6.0
func (s *Store) ListAs[T manifest.BaseManifest](group, kind string) []T
ListAs returns objects in the exact group/kind bucket that assert to T. Empty group and kind selects the complete inventory, as in ListObjects.
func (*Store) ListObjects ¶
func (s *Store) ListObjects(group, kind string) []manifest.BaseManifest
ListObjects returns objects in the exact group/kind bucket, sorted by NamedResource.Compare. Empty group and kind returns the complete inventory. Single-bucket reads use one kind shard; inventory reads MUST use rLockAll to capture a consistent snapshot across shards.
func (*Store) ListProductionCandidates ¶ added in v0.7.3
func (s *Store) ListProductionCandidates( group, kind string, index *manifest.DiscoveryIndex, prospective map[manifest.NamedResource]bool, ) []manifest.BaseManifest
ListProductionCandidates returns visible objects with indexed, prospective, or published ownership. A prospective key without a namespace includes every namespace.
func (*Store) Lookup ¶ added in v0.7.3
func (s *Store) Lookup(id manifest.NamedResource) (manifest.BaseManifest, manifest.DeclarationPolicy)
Lookup returns the coherent representative and its declaration roles.
func (*Store) Objects ¶ added in v0.7.3
func (s *Store) Objects() []manifest.BaseManifest
Objects snapshots visible objects in unspecified order without holding locks during use.
func (*Store) Policy ¶ added in v0.7.3
func (s *Store) Policy(id manifest.NamedResource) manifest.DeclarationPolicy
Policy projects the coherent representative's declaration roles.
func (*Store) Productions ¶ added in v0.7.3
func (s *Store) Productions(id manifest.NamedResource, index *manifest.DiscoveryIndex) []manifest.Production
Productions merges discovery evidence with accepted reverse memberships into a read-only snapshot.
func (*Store) RecordEmitted ¶ added in v0.7.3
func (s *Store) RecordEmitted( id manifest.NamedResource, next *Emission, payloads map[manifest.NamedResource]*SourceArtifact, )
RecordEmitted atomically accepts completed work, replacing complete inventories and merging incomplete progress. The greatest producer identity supplies shared content.
func (*Store) ReferenceFacts ¶ added in v0.7.3
func (s *Store) ReferenceFacts( id manifest.NamedResource, index *manifest.DiscoveryIndex, consumer manifest.NamedResource, ) ReferenceFacts
ReferenceFacts selects visible data and source-qualified production evidence.
func (*Store) RenderedParent ¶ added in v0.7.3
func (s *Store) RenderedParent( id manifest.NamedResource, index *manifest.DiscoveryIndex, ) (manifest.NamedResource, bool)
RenderedParent returns the smallest eligible accepted or discovered rendered owner. A nil index uses the installed discovery index.
func (*Store) ReportHidden ¶ added in v0.7.3
func (s *Store) ReportHidden(id manifest.NamedResource) bool
ReportHidden classifies the coherent representative's auxiliary provenance.
func (*Store) ReportProgress ¶ added in v0.7.3
func (s *Store) ReportProgress(id manifest.NamedResource, message string)
ReportProgress dispatches transient phase text without changing Ready conditions.
func (*Store) ReportStatus ¶ added in v0.7.3
func (s *Store) ReportStatus(id manifest.NamedResource) (StatusInfo, bool)
ReportStatus returns status and whether the representative is hidden from reports. A missing Ready condition has an empty status.
func (*Store) RequiredInputs ¶ added in v0.7.3
func (s *Store) RequiredInputs(id manifest.NamedResource) iter.Seq2[manifest.NamedResource, bool]
RequiredInputs enumerates a completed origin's accepted required footprint.
func (*Store) Retire ¶ added in v0.7.3
Retire releases registrations only when neither retained output borrows them.
func (*Store) SetArtifact ¶
func (s *Store) SetArtifact(id manifest.NamedResource, artifact *SourceArtifact)
SetArtifact stores acquired content and notifies readers of selected source facts.
func (*Store) SetCondition ¶
func (s *Store) SetCondition(id manifest.NamedResource, cond Condition)
SetCondition upserts cond into the resource's condition list keyed by cond.Type. Dispatches a StatusUpdated event with the StatusInfo rollup (derived from Ready) on every observable condition change, not just Ready transitions. Listeners that only care about Ready can filter on the StatusInfo payload; CEL-based ReadyExpr watchers need the broader notification so a Healthy condition flip (for example) wakes them.
An identical re-write of the same condition is a no-op (no event).
SetCondition does NOT require the object to be in the store — callers may legitimately establish initial state before AddObject lands (e.g. tests). The FailedResources rollup filters phantoms by intersecting against the object map at read time.
func (*Store) SetDiscoveryIndex ¶ added in v0.7.3
func (s *Store) SetDiscoveryIndex(index *manifest.DiscoveryIndex)
SetDiscoveryIndex installs frozen source-qualified evidence before reconciliation. Discovery is never rebuilt on the render path.
func (*Store) SetIncluded ¶ added in v0.7.3
func (s *Store) SetIncluded(id manifest.NamedResource, included, ordinary bool)
SetIncluded MUST never exclude an object after this Store invocation admits it.
func (*Store) SetPreflight ¶ added in v0.7.3
func (s *Store) SetPreflight(id manifest.NamedResource, message string)
SetPreflight publishes a changed structural admission decision.
func (*Store) SetWorkTree ¶ added in v0.7.3
SetWorkTree qualifies subsequent execution accounting before admission begins.
func (*Store) Snapshot ¶
func (s *Store) Snapshot(id manifest.NamedResource, conditions bool) (manifest.BaseManifest, Observation)
Snapshot reads an effective object and its requested readiness observation.
func (*Store) SourceAdmission ¶ added in v0.7.3
func (s *Store) SourceAdmission(id, source manifest.NamedResource) bool
SourceAdmission rejects initial source support after accepted ownership retires it.
func (*Store) Sweep ¶ added in v0.7.3
func (s *Store) Sweep() iter.Seq[manifest.NamedResource]
Sweep delivers changed inputs and reclaims retired registrations. Only the invocation's structural boundary may call Sweep.
func (*Store) UpdateFailure ¶ added in v0.7.3
func (s *Store) UpdateFailure(id manifest.NamedResource, err error)
UpdateFailure atomically records a terminal error and its immediate failed dependencies.
func (*Store) UpdateStatus ¶
func (s *Store) UpdateStatus(id manifest.NamedResource, info StatusInfo)
UpdateStatus records a Ready-condition transition and dispatches a StatusUpdated event when the StatusInfo rollup changes. Snapshot exposes the full condition state. An empty reason derives the normal reason from status.
func (*Store) Warnings ¶ added in v0.4.6
Warnings returns a copy of the collected advisories ordered by manifest.CompareWarning, or nil when none were recorded.
func (*Store) WorkScope ¶ added in v0.7.3
WorkScope returns the invocation's tree preparation attribution.
func (*Store) WorkSnapshot ¶ added in v0.7.3
func (s *Store) WorkSnapshot() manifest.WorkSummary
WorkSnapshot detaches this run's sorted admission and operation counters. All writers MUST join before the snapshot is constructed.
type SuppliedOverride ¶ added in v0.7.3
type SuppliedOverride struct {
Resource manifest.NamedResource
SupplyPath string
Keys []string
}
SuppliedOverride records repository keys that take precedence over supplied data.
type Unsubscribe ¶
type Unsubscribe func()
Unsubscribe removes a listener. It is safe to call from inside the listener.
Source Files
¶
- acquisition.go
- advisory.go
- artifact.go
- assessment.go
- capture.go
- capture_content.go
- capture_match.go
- capture_storage.go
- doc.go
- emission.go
- emission_prepare.go
- emission_read.go
- events.go
- history.go
- membership.go
- production_candidates.go
- publication.go
- publication_commit.go
- reference.go
- registration.go
- requirements.go
- status.go
- status_message.go
- store.go
- supply.go
- typed.go
- warning.go
- work.go