store

package
v0.7.3 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 9, 2026 License: AGPL-3.0 Imports: 19 Imported by: 0

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

View Source
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.

View Source
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

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

type Condition = metav1.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

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

func (e *Emission) Retains(reads *ReadSet) bool

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.

const (
	OutcomePending   Outcome = "Pending"
	OutcomePassed    Outcome = "Passed"
	OutcomeFailed    Outcome = "Failed"
	OutcomeBlocked   Outcome = "Blocked"
	OutcomeSkipped   Outcome = "Skipped"
	OutcomeUnchanged Outcome = "Unchanged"
	OutcomeSuspended Outcome = "Suspended"
)

Resource outcomes.

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

func (r *ReadSet) AddWarning(warning manifest.Warning)

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) Admitted added in v0.7.3

func (r *ReadSet) Admitted() bool

Admitted reports the captured changed-only disposition.

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

func (r *ReadSet) Bind(emission *Emission)

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

func (r *ReadSet) CarryAdvisories(previous *ReadSet)

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) Gates added in v0.7.3

func (r *ReadSet) Gates() iter.Seq[Gate]

Gates enumerates the retained readiness assessments.

func (*ReadSet) Get added in v0.7.3

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

GetEmission binds candidate output to this execution's captured declaration and source.

func (*ReadSet) GetObject added in v0.7.3

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

Lookup MUST return the object and policy from one captured authority.

func (*ReadSet) Matches added in v0.7.3

func (r *ReadSet) Matches(previous *ReadSet) bool

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

Policy MUST retain the origin captured with the object.

func (*ReadSet) Preflight added in v0.7.3

func (r *ReadSet) Preflight() string

Preflight returns the captured structural admission failure.

func (*ReadSet) Productions added in v0.7.3

Productions captures all contributors and discovery evidence for a named input.

func (*ReadSet) Promotions added in v0.7.3

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

func (r *ReadSet) ReplacesInvalid() bool

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

func (r *ReadSet) Required() iter.Seq2[manifest.NamedResource, bool]

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

func (r *ReadSet) Valid() bool

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.

func (*ReadSet) WorkScope added in v0.7.3

func (r *ReadSet) WorkScope() manifest.WorkScope

WorkScope returns the operation's attribution or its store's discovery scope.

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.

const (
	StatusPending Status = "Pending"
	StatusReady   Status = "Ready"
	StatusFailed  Status = "Failed"
)

Possible Status values.

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:

  1. Shallow-copy the struct (most manifest types are flat enough that *clone := *orig works).
  2. Mutate the copy's fields.
  3. 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 New

func New() *Store

New constructs an empty Store.

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

func (s *Store) AddWarning(w manifest.Warning)

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

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

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

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

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

func (s *Store) Retire(reads *ReadSet)

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

func (s *Store) SetWorkTree(tree manifest.TreeID, scope manifest.WorkScope)

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

func (s *Store) Warnings() []manifest.Warning

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

func (s *Store) WorkScope() manifest.WorkScope

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL