selection

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: 17 Imported by: 0

Documentation

Overview

Package selection owns render membership. Physical acquisition and storage remain with their factual owners.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Declarations

func Declarations(documents []store.Child) iter.Seq[store.Child]

Declarations excludes executable raw siblings from dependency acquisition.

func Project

func Project(
	runs []Snapshot,
	runErr error,
	request Request,
) ([]*Result, ProjectionErrors)

Project projects one render, or two ordered orig/current renders, onto requested kinds with a common namespace and name. Labels filter output objects, while Counts and fatal scope retain the roots matched before labels. Incomplete inputs yield only warnings and their original errors. Unchanged catalog-only objects contain reporting facts, not complete specs; select them for render to obtain full specs. Borrowed objects, graphs and document batches MUST remain immutable in use. ProjectionErrors separates selected failures from non-resource diagnostics.

func ProjectIndex

func ProjectIndex(index *manifest.DiscoveryIndex, decision *Decision) *manifest.DiscoveryIndex

ProjectIndex prunes excluded reader edges without mutating the borrowed index.

func ReduceStatic

func ReduceStatic[S staticScope](scope S) iter.Seq[string]

ReduceStatic yields exact parent-directory reads to its caller. The caller MUST complete each read before resuming and exhaust the iterator before publication. No borrowed input or mutable result escapes this construction call.

Types

type Acquisition

type Acquisition struct {
	Demand    Demand
	Child     store.Child
	Root      string
	Available bool
	Reads     *store.ReadSet
}

Acquisition borrows an exact driver's result until its preparation consumes it.

type Admission

type Admission struct {
	Needed       []manifest.NamedResource
	Selected     []manifest.NamedResource
	Dirty        []manifest.NamedResource
	Ordinary     []manifest.NamedResource
	Objects      []store.Child
	Blocked      []string
	Revision     uint64
	Namespaces   []string
	EntryReceipt *manifest.EntryApplication

	Request PrepareRequest
	// contains filtered or unexported fields
}

Admission is a temporary proposal computed outside execution-membership locks.

func (*Admission) Demands

func (a *Admission) Demands() iter.Seq[Demand]

Demands MUST be copied before Commit or Retire ends the proposal lifetime.

func (*Admission) Retire

func (a *Admission) Retire()

Retire ends proposal payload access, preserving borrowed guards and identity results.

type CommitStage

type CommitStage uint8

CommitStage separates construction admission from execution membership.

const (
	// Construction admits dependencies without execution membership.
	Construction CommitStage = iota
	// Execution commits the settled invocation selection.
	Execution
)

type Decision

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

Decision MUST remain immutable after publication, including every borrowed bucket.

func (*Decision) Changed

func (d *Decision) Changed(id manifest.NamedResource) bool

Changed treats unrestricted execution as changed.

func (*Decision) Ordering

func (d *Decision) Ordering(id manifest.NamedResource, present, indexed bool) bool

Ordering preserves missing external dependency validation without admitting excluded inventory.

func (*Decision) OrdinaryDemand

func (d *Decision) OrdinaryDemand(id manifest.NamedResource) bool

OrdinaryDemand permits ordinary execution when the decision is nil.

func (*Decision) Output

func (d *Decision) Output(id manifest.NamedResource) bool

Output includes every identity when the decision is nil.

func (*Decision) Reconcile

func (d *Decision) Reconcile(id manifest.NamedResource) bool

Reconcile admits every identity when the decision is nil.

type Demand

type Demand struct {
	Identity   manifest.NamedResource
	Occurrence OccurrenceFacts
	Source     manifest.NamedResource
	Root       string
	Ordinary   bool
	History    bool
	Complete   bool
	Artifact   *store.SourceArtifact
	Reads      *store.ReadSet
	Witness    manifest.BaseManifest
}

Demand borrows its artifact and capture until the successor preparation consumes its acquisition.

type DocumentFact

type DocumentFact struct {
	Document map[string]any
	Identity manifest.NamedResource
}

DocumentFact MUST preserve the emitter's identity before document projection.

type EmissionFacts

type EmissionFacts struct {
	Emitter   manifest.BaseManifest
	Parent    manifest.BaseManifest
	Documents []DocumentFact
}

EmissionFacts MUST retain actual emitter and reporting parent separately.

type EntryFailure

type EntryFailure struct {
	File       string
	Coordinate string
	Evidence   RootEvidence
	Occurrence manifest.DocOccurrence
}

EntryFailure borrows a retained document failure and its physical root evidence.

type EntryIdentity

type EntryIdentity struct {
	Producer, Key manifest.NamedResource
}

EntryIdentity MUST retain both the physical producer and its comparison key.

type EntryRoute

type EntryRoute struct {
	Application *manifest.EntryApplication
	Previous    manifest.NamedResource
	Producer    manifest.NamedResource
	Root        manifest.NamedResource
	Reads       *store.ReadSet
	Bound       bool
}

EntryRoute borrows discovery's immutable matched support and its captured observations.

type FailuresError

type FailuresError struct{ Message string }

FailuresError retains the domain identity of resource reconciliation failures.

func (*FailuresError) Error

func (e *FailuresError) Error() string

func (*FailuresError) Unwrap

func (*FailuresError) Unwrap() error

type NativeRootFacts

type NativeRootFacts struct {
	Path       string
	Identities []manifest.NamedResource
	Owners     []manifest.NamedResource
	Claims     []manifest.KSClaim
	Entry      bool
	Built      bool
	Selected   bool
	Excluded   bool
	Component  bool
}

NativeRootFacts borrows one physical package's graph membership and construction state.

type OccurrenceFacts

type OccurrenceFacts struct {
	Declaration     OccurrenceID
	Identity        manifest.NamedResource
	Authored        manifest.NamedResource
	Object          manifest.BaseManifest
	Catalog         manifest.BaseManifest
	Source          manifest.NamedResource
	Path            string
	HasPath         bool
	Namespaced      bool
	Uncertain       bool
	RequiresBuild   bool
	Retained        bool
	Structural      *manifest.Kustomization
	NeedsCandidates bool
	Labels          map[string]string
	Labeled         bool
	Traversed       bool
	Mounted         *store.SourceArtifact
	Witness         any
	Located         bool
	CatalogKnown    bool
	Refs            []manifest.Reference
	Reverse         []manifest.NamedResource
	TemplateInputs  []manifest.TemplateInput
	TemplateObjects []manifest.BaseManifest
	Roots           []string
	Targets         []manifest.ProducerTarget
	AuthoredTargets []manifest.ProducerTarget
	Policy          *manifest.EmissionPolicy
}

OccurrenceFacts borrows immutable parsed data; its collections must not be mutated.

func (OccurrenceFacts) SourcePath

func (o OccurrenceFacts) SourcePath() (manifest.NamedResource, string, bool)

SourcePath resolves references in the occurrence's effective namespace.

type OccurrenceID

type OccurrenceID struct {
	Source   string
	File     string
	Document int
	Item     int
}

OccurrenceID preserves document and List-item coordinates within a source.

type Preparation

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

Preparation MUST remain with one logical admission owner until its final consumer.

func (*Preparation) Retire

func (p *Preparation) Retire()

Retire MUST follow every active proposal and preserve accepted store borrowers.

type PrepareRequest

type PrepareRequest struct {
	Preparation       **Preparation
	Changes           *change.Set
	HistoryOwners     map[manifest.NamedResource][]manifest.SourceEvidence
	Acquired          []Acquisition
	AllowMissingKinds []string
	// Generation MUST remain immutable until its preparation retires.
	Generation []store.Child
	Owner      manifest.NamedResource
	Reads      *store.ReadSet
	Invocation bool
	History    map[manifest.NamedResource]struct {
		Records  iter.Seq2[manifest.NamedResource, manifest.DiscoveryRecord]
		Complete bool
	}
}

PrepareRequest describes the evidence and selection intent for an admission proposal.

type ProducerFacts

type ProducerFacts struct {
	Declaration manifest.BaseManifest
	Derived     bool
	Occurrence  OccurrenceFacts
}

ProducerFacts preserves an immutable producer projection and its derivation witness.

type ProjectionErrors

type ProjectionErrors struct {
	Selected  error
	Remaining error
}

ProjectionErrors keeps selected failures separate from diagnostics outside the projection.

type Request

type Request struct {
	Roots   []manifest.NamedResource
	Changed bool
	Labels  map[string]string
}

Request containers MUST remain immutable for the invocation.

func (Request) Matches

func (s Request) Matches(id manifest.NamedResource) bool

Matches reports whether an identity is eligible under the requested roots. Namespace restrictions retain cluster-scoped output; complete render-kind requests include standalone output.

func (Request) MatchesScope

func (s Request) MatchesScope(id manifest.NamedResource) bool

MatchesScope reports whether a kind and namespace belong to the requested output scope.

type Result

type Result struct {
	// Subjects maps raw identities to captured display context.
	Subjects        map[manifest.NamedResource]manifest.DiagnosticIdentity
	Manifests       []manifest.DocumentBatch
	Failed          map[manifest.NamedResource]store.StatusInfo
	Blocked         map[manifest.NamedResource][]manifest.NamedResource
	Warnings        []manifest.Warning
	ClusterWarnings []manifest.Warning
	// Objects contains selected roots after metadata filtering, grouped by requested kind.
	// Unchanged catalog-only roots expose reporting facts, never complete specs or execution authority.
	Objects []manifest.BaseManifest
	// Counts records matched roots per requested kind before label filtering.
	Counts map[string]int
	// Statuses contains roster statuses and eligible diagnostic failures. Blocked
	// messages are prepared for test reports without changing dependency identity.
	Statuses map[manifest.NamedResource]store.StatusInfo
	// ChartVersions contains versions resolved from selected HR chartRef sources.
	ChartVersions map[manifest.NamedResource]string
	// Causes maps prepared failure roots to sorted distinct blocked victims.
	// Missing roots have no Failed entry; closed cycle roots carry prepared Failed messages.
	Causes map[manifest.NamedResource][]manifest.NamedResource
	// Unavailable contains canonical failure, soft-skip or suspension evidence for
	// paired producer output, independently of fatal namespace scope.
	Unavailable map[manifest.NamedResource]store.StatusInfo
	// ProducerKeys maps actual producers to their paired comparison identities.
	ProducerKeys map[manifest.NamedResource]manifest.NamedResource
	// Unrelated contains prepared advisories for failures outside named fatal scope.
	Unrelated []manifest.Warning
	// External contains paired external-source skip disclosures, honoring explicit namespace scope.
	External []manifest.Warning
}

Result contains the objects and diagnostics projected onto requested roots. Borrowed manifests and document batches MUST remain immutable in use.

func (*Result) BlockedCount

func (r *Result) BlockedCount() int

BlockedCount excludes dependency-cycle roots promoted to primary failures.

func (*Result) Diagnostic

Diagnostic returns prepared display context, including ordinary absent objects.

type RootCoveringOwner

type RootCoveringOwner struct {
	Identity     manifest.NamedResource
	Object       manifest.BaseManifest
	Productions  []manifest.Production
	Source       manifest.NamedResource
	Path         string
	Root         string
	Applications map[manifest.NamedResource]manifest.DiscoveryRecord
	Replaced     bool
	Output       *store.Emission
	Input        *store.SourceArtifact
}

RootCoveringOwner borrows producer ancestry and captured output authority.

type RootEligibility

type RootEligibility uint8

RootEligibility MUST preserve its order because propagation only raises eligibility.

const (
	RootUnknown RootEligibility = iota
	RootInactive
	RootEligible
	RootIndependent
)

Static reduction MUST start at RootUnknown for each construction generation.

type RootEvidence

type RootEvidence struct {
	Native            *NativeRootFacts
	Identity          manifest.NamedResource
	Record            RootRecord
	StaticRecord      *RootRecord
	Occurrence        OccurrenceFacts
	Scope             RootScopeFacts
	InitialScope      *RootScopeFacts
	InitialOccurrence *OccurrenceFacts
	Productions       []manifest.Production
	LiveProductions   []manifest.Production
	Declaration       manifest.BaseManifest
	Sources           [2]RootSourceSupport
	CoveringOwners    []RootCoveringOwner
	Supplied          bool
	Incoming          bool
	Needed            bool
	StaticOwner       bool
	DeclarationSource string
	Captured          bool
	Stale             bool
	PreparedRoot      string
	BuiltChild        store.Child
	BuiltCurrent      bool
}

RootEvidence combines immutable discovery facts with captured current support.

type RootOwnerFacts

type RootOwnerFacts struct {
	Identity manifest.NamedResource
	Path     string
	Indexed  bool
	Initial  bool
}

RootOwnerFacts borrows a scope owner's indexed path.

type RootRecord

type RootRecord struct {
	Builder      string
	Authored     manifest.NamedResource
	Path         string
	Parent       manifest.NamedResource
	BuilderOwner manifest.NamedResource
}

RootRecord retains only the coordinates used for root classification and support.

func RootRecordFrom

func RootRecordFrom(record *manifest.DiscoveryRecord) RootRecord

RootRecordFrom excludes declaration payloads from retained root evidence.

type RootResult

type RootResult struct {
	NeedsOwnerSupport  bool
	Construction       bool
	InitialAdmitted    bool
	InitialIndependent bool
	InitialEntry       bool
	Owner              manifest.NamedResource
	Occurrence         OccurrenceFacts
	Admitted           bool
	Independent        bool
	Entry              bool
	PackageRoot        bool
}

RootResult keeps physical availability, independent membership and entry qualification distinct.

func Root

func Root(facts RootEvidence) RootResult

Root decides membership and qualification from one immutable factual snapshot.

type RootScopeFacts

type RootScopeFacts struct {
	Path              string
	Eligibility       RootEligibility
	Owners            []RootOwnerFacts
	Peers             [][]manifest.NamedResource
	Records           map[manifest.NamedResource]manifest.DiscoveryRecord
	Claims            map[string][]manifest.NamedResource
	Claim             string
	ApplicationSource manifest.NamedResource
	ApplicationPath   string
	Loaded            bool
	Bootstrap         bool
	Initial           bool
	Terminal          bool
	NamespaceEligible bool
	NativeOperand     bool
	NativeEntry       bool
	EntryKustomize    bool
	Application       bool
	LocalApplication  bool
	SameEntryOrigin   bool
	Prepared          bool
	Candidate         bool
	Compact           bool
	PackageKnown      bool
	PackagePaths      []string
	PackageOwners     [][]int
	PackageIndex      int
	PackageRoot       bool
	PackageEligible   bool
	PackageRunnable   bool
	NativePackage     bool
}

RootScopeFacts borrows physical scope relationships without membership verdicts.

type RootSourceSupport

type RootSourceSupport struct {
	Source    manifest.NamedResource
	Allowed   bool
	Available bool
	Path      string
	Origin    string
}

RootSourceSupport captures authority from one source generation.

type Session

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

Session publishes immutable decisions from guarded admission proposals.

func New

func New(st *store.Store, facts census, request Request) (*Session, error)

New returns nil for unrestricted full execution.

func (*Session) Commit

func (s *Session) Commit(ctx context.Context, proposal *Admission, stage CommitStage) (*Admission, bool, error)

Commit publishes guarded membership before admitting any object.

func (*Session) DiscardConstruction

func (s *Session) DiscardConstruction()

DiscardConstruction ends an aborted invocation without changing accepted execution membership.

func (*Session) EntryFailure

func (s *Session) EntryFailure(ctx context.Context, failures iter.Seq[EntryFailure]) error

EntryFailure selects failures under the invocation's roots and qualified comparison.

func (*Session) Include

func (s *Session) Include(id manifest.NamedResource)

Include MUST precede an execution's capture of a newly arrived identity.

func (*Session) PendingRoots

func (s *Session) PendingRoots() *store.ReadSet

PendingRoots returns a captured acquisition frontier; the caller MUST retire it after admission.

func (*Session) Prepare

func (l *Session) Prepare(
	ctx context.Context,
	request PrepareRequest,
) (*Admission, error)

Prepare computes the local declaration and input closure without publishing membership or objects. History is invocation-local borrowed evidence; complete inventories replace only their owner's support.

func (*Session) PublishEntry

func (s *Session) PublishEntry(route *EntryRoute)

PublishEntry MUST receive a completed immutable route from the entry qualification owner.

func (*Session) RefreshHistory

func (s *Session) RefreshHistory(
	ctx context.Context,
	previous *Admission,
	request PrepareRequest,
) (*Admission, error)

RefreshHistory MUST retain the settled identities while capturing each receipt's current authority.

func (*Session) RefreshProducers

func (s *Session) RefreshProducers(
	ctx context.Context,
	previous *Admission,
	request PrepareRequest,
) (*Admission, error)

RefreshProducers MUST recheck the exact pending production after its native prerequisite changes. The caller retains its logical Preparation and retires the result after consuming its demands.

func (*Session) Snapshot

func (s *Session) Snapshot() *Decision

Snapshot permits nil sessions and returns an immutable decision.

type Snapshot

type Snapshot struct {
	Store            *store.Store
	Index            *manifest.DiscoveryIndex
	Facts            projectionFacts
	Decision         *Decision
	Entry            EntryIdentity
	Emissions        []EmissionFacts
	Manifests        []manifest.DocumentBatch
	Failed           map[manifest.NamedResource]store.StatusInfo
	Blocked          map[manifest.NamedResource][]manifest.NamedResource
	Warnings         []manifest.Warning
	ClusterWarnings  []manifest.Warning
	ChangeNamespaces []string
	Err              error
	ErrorIdentity    error
	Complete         bool
	HasResult        bool
	Absent           bool
}

Snapshot borrows completed storage. Its owners MUST remain immutable through projection.

func (*Snapshot) CollectEmissions

func (s *Snapshot) CollectEmissions()

CollectEmissions applies committed membership without mutating the captured emission facts.

func (*Snapshot) ReportCounts

func (s *Snapshot) ReportCounts(request Request) map[string]int

ReportCounts requires unchanged-parent evidence before counting unpublished declarations.

func (*Snapshot) UnchangedDeclarations

func (s *Snapshot) UnchangedDeclarations(request Request) iter.Seq[manifest.BaseManifest]

UnchangedDeclarations MUST retain current parent authority throughout iteration.

type SourceContext

type SourceContext struct {
	Root                       string
	Roots                      []NativeRootFacts
	InputReaders, InputObjects map[manifest.NamedResource][]manifest.NamedResource
	TemplateProjections        map[manifest.NamedResource]manifest.TemplateProjection
	EntryPath                  string
	NativeEntry                bool
	PlainEntry                 bool
	Frozen                     bool
	SideKnown                  bool
	Side                       manifest.TreeSide
}

SourceContext borrows construction facts shared by one preparation.

type SourceFacts

type SourceFacts struct {
	Comparison           *change.Set
	Context              SourceContext
	Source               manifest.NamedResource
	Changes, Delta       *change.Set
	Snapshots            [2]*store.SourceArtifact
	Declarations         [2]manifest.BaseManifest
	Declaration          manifest.BaseManifest
	Input, Initial       *store.SourceArtifact
	ConfiguredInput      *store.SourceArtifact
	Origin               string
	Path                 string
	ToIndex              string
	Files                []SourceFile
	Paired, InitialKnown bool
	Pinned, External     bool
	Derived              bool
}

SourceFacts borrows the source owner's immutable qualified comparison.

func (*SourceFacts) Coordinates

func (f *SourceFacts) Coordinates(root, path string) (string, string)

Coordinates projects an absolute path through the captured source origin.

type SourceFile

type SourceFile struct {
	Path    string
	Indexed string
}

SourceFile preserves both source-relative and census-relative coordinates.

type StaticContribution

type StaticContribution struct {
	Owner, Source            manifest.NamedResource
	Visits                   int
	Unshared, MembershipOnly bool
}

StaticContribution retains source identity even when owners share physical visits.

type StaticFile

type StaticFile struct {
	Eligibility  RootEligibility
	Loaded       bool
	ObjectsKnown bool
	HasObjects   bool
}

StaticFile borrows presence facts; it MUST NOT retain or expose parsed document objects.

type StaticTraversal

type StaticTraversal struct {
	Reached    RootEligibility
	Controlled bool
}

StaticTraversal contains only mutable reduction results, never physical visits.

type StaticVisit

type StaticVisit struct {
	File, LocalFile, Origin, Dir string
	Resource                     bool
}

StaticVisit coordinates MUST stay in the original source view.

Jump to

Keyboard shortcuts

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