validationharness

package
v0.0.0-...-89d81dd Latest Latest
Warning

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

 Go to latest Published: Aug 11, 2026 License: Apache-2.0 Imports: 46 Imported by: 0

Documentation

Overview

Package validationharness executes repository-owned validation scenarios through a separately built Endstate engine.

Index

Constants

View Source 
const (
	LiveDefinitionSchemaVersion = 1
	LiveResultSchemaVersion     = 1
)
View Source 
const (
	CodeInvalidEngine      = "invalid_engine"
	CodeInvalidResultPath  = "invalid_result_path"
	CodeScenarioSelection  = "scenario_selection"
	CodeUnsupportedFixture = "unsupported_fixture"
	CodeAssertionContract  = "assertion_contract"
	CodeEnvelopeContract   = "envelope_contract"
	CodeEventContract      = "event_contract"
	CodeExecutionFailure   = "execution_failure"
	CodeArtifactContract   = "artifact_contract"
	CodeContentMismatch    = "content_mismatch"
	CodeRevertFailure      = "revert_failure"
	CodeIsolationFailure   = "isolation_failure"
	CodeGenerationContract = "generation_contract"
	CodeMigrationContract  = "migration_contract"
	ResultSchemaVersion    = 1
	ResultStatusPassed     = "passed"
	ResultStatusFailed     = "failed"
)

Variables

This section is empty.

Functions

func CanonicalLiveDefinitionSHA256 

func CanonicalLiveDefinitionSHA256(definition LiveDefinition) (string, error)

CanonicalLiveDefinitionSHA256 returns the deterministic digest that binds a result to all non-authorizing preparation inputs.

func NormalizeLiveVersion 

func NormalizeLiveVersion(value string) (string, error)

NormalizeLiveVersion permits the observer's explicitly narrow vendor format: numeric dotted components, one optional leading v, and insignificant zeroes.

func ParseLiveWingetTable 

func ParseLiveWingetTable(output []byte, ref string) (string, error)

ParseLiveWingetTable parses only the fixed-width layout declared by the separator row. Header labels are intentionally ignored because they localize.

func ValidateLiveRequest 

func ValidateLiveRequest(request LiveRequest) error

ValidateLiveRequest rejects malformed or authorizing work before a runner can observe it. Compilation returns a definition that already satisfies it.

func ValidateLiveResult 

func ValidateLiveResult(result LiveResult) error

ValidateLiveResult enforces the deliberately narrow result contract before a later runner serializes or persists it.

func ValidateLiveResultForDefinition 

func ValidateLiveResultForDefinition(result LiveResult, definition LiveDefinition) error

ValidateLiveResultForDefinition binds a result to the exact compiled definition and the package/comparator identities it authorizes for observation only.

Types

type CaptureContractPlan 

type CaptureContractPlan struct {
	ModuleID       string
	ModuleRevision string
	ScenarioID     string
	Inventory      validationmode.Inventory
	Targets        []CaptureContractTarget
	Verifiers      []modules.VerifyDef
	Restores       []modules.RestoreDef
	// contains filtered or unexported fields
}

CaptureContractPlan pins the exact reviewed production capture declaration. Runtime resolution and materialization happen only after validation mode has created its contained host roots.

func (*CaptureContractPlan) HasOptionalTargets 

func (plan *CaptureContractPlan) HasOptionalTargets() bool

func (*CaptureContractPlan) MaterializeCaptured 

func (plan *CaptureContractPlan) MaterializeCaptured() *Failure

func (*CaptureContractPlan) MaterializeOptionalAbsent 

func (plan *CaptureContractPlan) MaterializeOptionalAbsent() *Failure

type CaptureContractTarget 

type CaptureContractTarget struct {
	Coordinate     string
	AuthoredSource string
	Destination    string
	Optional       bool
	Content        []byte
	Resolved       string
}

type CatalogMatrixRequest 

type CatalogMatrixRequest struct {
	EnginePath string
	RepoRoot   string
	ResultPath string
}

CatalogMatrixRequest identifies one built engine and one immutable repository authority. The matrix deliberately only consumes the public catalog-plan CLI.

type CatalogMatrixResult 

type CatalogMatrixResult struct {
	SchemaVersion   int                           `json:"schemaVersion"`
	Status          string                        `json:"status"`
	ProofLevels     []validationmatrix.ProofLevel `json:"proofLevels"`
	CatalogCount    int                           `json:"catalogCount"`
	Attempted       int                           `json:"attempted"`
	Passed          int                           `json:"passed"`
	Failed          int                           `json:"failed"`
	MembershipCount int                           `json:"membershipCount"`
	UniqueModules   int                           `json:"uniqueModules"`
	Reuse           []CatalogReuse                `json:"reuse"`
	Rows            []CatalogMatrixRow            `json:"rows"`
	EngineHash      string                        `json:"engineHash,omitempty"`
	RepositoryHash  string                        `json:"repositoryHash,omitempty"`
	Failure         *Failure                      `json:"failure,omitempty"`
	PhaseTimings    map[string]time.Duration      `json:"phaseTimings"`
}

CatalogMatrixResult is distinct from a module scenario Result because a catalog proof binds a bundle set and two CLI executions per bundle.

func RunCatalogMatrix 

func RunCatalogMatrix(ctx context.Context, request CatalogMatrixRequest) (CatalogMatrixResult, error)

type CatalogMatrixRow 

type CatalogMatrixRow struct {
	SchemaVersion   int                           `json:"schemaVersion"`
	BundleID        string                        `json:"bundleId"`
	BundleHash      string                        `json:"bundleHash"`
	BundleVersion   int                           `json:"bundleVersion"`
	Status          string                        `json:"status"`
	ProofLevels     []validationmatrix.ProofLevel `json:"proofLevels"`
	MembershipCount int                           `json:"membershipCount"`
	Actions         []catalogplan.Action          `json:"actions"`
	PlanExecutions  int                           `json:"planExecutions"`
	AssertionCounts map[string]int                `json:"assertionCounts"`
	Failures        []catalogplan.Failure         `json:"failures,omitempty"`
	Failure         *Failure                      `json:"failure,omitempty"`
	PhaseTimings    map[string]time.Duration      `json:"phaseTimings"`
}

type CatalogReuse 

type CatalogReuse struct {
	ModuleID string   `json:"moduleId"`
	Bundles  []string `json:"bundles"`
}

type ComparatorMapping 

type ComparatorMapping struct {
	Identity        string `json:"identity"`
	CaptureTemplate string `json:"captureTemplate"`
	RestoreTemplate string `json:"restoreTemplate"`
	Optional        bool   `json:"optional"`
}

type ComparatorOutcome 

type ComparatorOutcome struct {
	Identity string `json:"identity"`
	Status   string `json:"status"`
}

type ExactBytesComparator 

type ExactBytesComparator struct {
	Mappings                []ComparatorMapping `json:"mappings"`
	MinimumExistingMappings int                 `json:"minimumExistingMappings"`
}

ExactBytesComparator describes the stable mappings a later runner may snapshot and compare. It deliberately contains templates, never resolved host paths or bytes.

type Failure 

type Failure struct {
	Code        string                        `json:"code"`
	Phase       string                        `json:"phase"`
	Coordinate  string                        `json:"coordinate,omitempty"`
	Detail      string                        `json:"detail,omitempty"`
	ProofLevels []validationmatrix.ProofLevel `json:"-"`
}

type FixtureExcluded 

type FixtureExcluded struct {
	Relative        string
	Path            string
	Captured        string
	Mutated         string
	CapturePatterns []string
	RestorePatterns []string
}

type FixturePlan 

type FixturePlan struct {
	Targets         []FixtureTarget
	RegistryTargets []RegistryFixtureTarget
	// contains filtered or unexported fields
}

func (*FixturePlan) CompareCaptureSeed 

func (plan *FixturePlan) CompareCaptureSeed() *Failure

func (*FixturePlan) CompareCaptured 

func (plan *FixturePlan) CompareCaptured() *Failure

func (*FixturePlan) CompareMutated 

func (plan *FixturePlan) CompareMutated() *Failure

func (*FixturePlan) CompareOptionalAbsent 

func (plan *FixturePlan) CompareOptionalAbsent() *Failure

func (*FixturePlan) CompareRestored 

func (plan *FixturePlan) CompareRestored() *Failure

func (*FixturePlan) HasOptionalTargets 

func (plan *FixturePlan) HasOptionalTargets() bool

func (*FixturePlan) MaterializeCaptured 

func (plan *FixturePlan) MaterializeCaptured() *Failure

func (*FixturePlan) MaterializeOptionalAbsent 

func (plan *FixturePlan) MaterializeOptionalAbsent() *Failure

func (*FixturePlan) MaterializeRestored 

func (plan *FixturePlan) MaterializeRestored() *Failure

func (*FixturePlan) Mutate 

func (plan *FixturePlan) Mutate() *Failure

func (*FixturePlan) OperationCount 

func (plan *FixturePlan) OperationCount() int

func (*FixturePlan) RestoreTargets 

func (plan *FixturePlan) RestoreTargets() []FixtureRestoreTarget

type FixtureRestoreTarget 

type FixtureRestoreTarget struct {
	Coordinate  string
	Authored    string
	Destination string
	Strategy    string
	Optional    bool
	Registry    bool
}

FixtureRestoreTarget is the shared, deterministic projection consumed by every production-backed roundtrip assertion. Registry payload text proves only its grammar and scope; typed fixture snapshots prove its content.

type FixtureTarget 

type FixtureTarget struct {
	Coordinate                  string
	Authored                    string
	Destination                 string
	Resolved                    string
	PayloadPath                 string
	Strategy                    string
	Captured                    string
	Mutated                     string
	Restored                    string
	Directory                   bool
	Optional                    bool
	CaptureExcluded             []FixtureExcluded
	RestoreExcluded             []FixtureExcluded
	OverlappingExcluded         []FixtureExcluded
	RetainedCaptureAncestorDirs []string
}

type InstallContractPlan 

type InstallContractPlan struct {
	ModuleID          string
	ModuleRevision    string
	ScenarioID        string
	Inventory         validationmode.Inventory
	Verifiers         []modules.VerifyDef
	CommandExecutable string
	ManifestPath      string
	// contains filtered or unexported fields
}

InstallContractPlan pins the package and verifier authority exercised by an install-contract scenario. It is compiled from the selected production module; the journey must not infer either authority from fixture data.

type LiveAttempt 

type LiveAttempt struct {
	Number          int                 `json:"number"`
	Phase           LivePhase           `json:"phase"`
	Status          LiveStatus          `json:"status"`
	Package         PackageObservation  `json:"package"`
	Comparator      []ComparatorOutcome `json:"comparator"`
	FailureCategory LiveFailureCategory `json:"failureCategory,omitempty"`
}

type LiveDefinition 

type LiveDefinition struct {
	SchemaVersion           int                         `json:"schemaVersion"`
	ModuleID                string                      `json:"moduleId"`
	ModuleRevision          string                      `json:"moduleRevision"`
	ValidationSourceSHA256  string                      `json:"validationSourceSha256"`
	Policy                  validationmatrix.LivePolicy `json:"policy"`
	WingetRef               string                      `json:"wingetRef"`
	Observer                LiveObserverDefinition      `json:"observer"`
	SeedRepositoryPath      string                      `json:"seedRepositoryPath"`
	SeedSHA256              string                      `json:"seedSha256"`
	RunnerLabel             string                      `json:"runnerLabel"`
	PRTimeoutMinutes        int                         `json:"prTimeoutMinutes"`
	ScheduledTimeoutMinutes int                         `json:"scheduledTimeoutMinutes"`
	Comparator              ExactBytesComparator        `json:"comparator"`
	NonAuthorizing          bool                        `json:"nonAuthorizing"`
	MutationAuthorized      bool                        `json:"mutationAuthorized"`
}

LiveDefinition is preparation data only. It cannot authorize package or configuration mutation.

func CompileLiveDefinition 

func CompileLiveDefinition(repoRoot, moduleID string) (LiveDefinition, error)

CompileLiveDefinition loads current repository authority and prepares one candidate policy for diagnosis only. It never authorizes mutation or proof.

type LiveExecutionClass 

type LiveExecutionClass string
const (
	LiveExecutionProbe     LiveExecutionClass = "probe"
	LiveExecutionEngine    LiveExecutionClass = "engine"
	LiveExecutionSeed      LiveExecutionClass = "seed"
	LiveExecutionWinget    LiveExecutionClass = "winget"
	LiveExecutionUninstall LiveExecutionClass = "uninstaller"
)

type LiveExecutionError 

type LiveExecutionError struct {
	Code LiveExecutionFailureCode
	// contains filtered or unexported fields
}

LiveExecutionError has stable failure categories. Its text deliberately omits commands, arguments, paths, environment values, and child output.

func (*LiveExecutionError) Error 

func (err *LiveExecutionError) Error() string

func (*LiveExecutionError) Unwrap 

func (err *LiveExecutionError) Unwrap() error

type LiveExecutionFailureCode 

type LiveExecutionFailureCode string
const (
	LiveExecutionInvalidRequest LiveExecutionFailureCode = "invalid-request"
	LiveExecutionMutationDenied LiveExecutionFailureCode = "mutation-denied"
	LiveExecutionUnsupported    LiveExecutionFailureCode = "unsupported"
	LiveExecutionStartFailed    LiveExecutionFailureCode = "start-failed"
	LiveExecutionContainment    LiveExecutionFailureCode = "containment-failed"
	LiveExecutionTimeout        LiveExecutionFailureCode = "timeout"
	LiveExecutionCanceled       LiveExecutionFailureCode = "canceled"
	LiveExecutionOutputLimit    LiveExecutionFailureCode = "output-limit"
	LiveExecutionProcessExit    LiveExecutionFailureCode = "process-exit"
)

type LiveFailureCategory 

type LiveFailureCategory string
const (
	LiveFailureNone        LiveFailureCategory = ""
	LiveFailureDefinition  LiveFailureCategory = "definition"
	LiveFailureSeed        LiveFailureCategory = "seed"
	LiveFailurePackage     LiveFailureCategory = "package"
	LiveFailureCapture     LiveFailureCategory = "capture"
	LiveFailureRestore     LiveFailureCategory = "restore"
	LiveFailureComparison  LiveFailureCategory = "comparison"
	LiveFailureEnvironment LiveFailureCategory = "environment"
)

type LiveFileInfo 

type LiveFileInfo struct {
	Regular      bool
	ReparsePoint bool
}

type LiveFiles 

type LiveFiles interface {
	Stat(string) (LiveFileInfo, error)
	FileVersion(string) (string, error)
}

type LiveObservation 

type LiveObservation struct {
	Status            LiveObservationStatus `json:"status"`
	WingetPresent     bool                  `json:"wingetPresent"`
	RegistryPresent   bool                  `json:"registryPresent"`
	ExecutablePresent bool                  `json:"executablePresent"`
	Ref               string                `json:"ref"`
	WingetVersion     string                `json:"wingetVersion,omitempty"`
	RegistryVersion   string                `json:"registryVersion,omitempty"`
	ExecutableVersion string                `json:"executableVersion,omitempty"`
}

LiveObservation contains only summary state. It intentionally excludes host paths, raw registry data, command output, environment values, and errors.

type LiveObservationStatus 

type LiveObservationStatus string
const (
	LiveObservationAbsent          LiveObservationStatus = "absent"
	LiveObservationPresent         LiveObservationStatus = "present"
	LiveObservationMixed           LiveObservationStatus = "mixed"
	LiveObservationAmbiguous       LiveObservationStatus = "ambiguous"
	LiveObservationVersionMismatch LiveObservationStatus = "version-mismatch"
	LiveObservationFailed          LiveObservationStatus = "failed"
)

type LiveObserver 

type LiveObserver struct {
	Process  LiveProcess
	Registry LiveRegistry
	Path     LivePath
	Files    LiveFiles
}

LiveObserver combines independent, injected read-only observations. It does not import the production winget driver, verifier, or snapshot parser.

func NewWindowsLiveObserver 

func NewWindowsLiveObserver(LiveVersionSource) (LiveObserver, error)

func (LiveObserver) Observe 

func (observer LiveObserver) Observe(ctx context.Context, definition LiveObserverDefinition) LiveObservation

type LiveObserverDefinition 

type LiveObserverDefinition struct {
	WingetRef            string   `json:"wingetRef"`
	UninstallDisplayName []string `json:"uninstallDisplayName"`
	ExecutableNames      []string `json:"executableNames"`
}

LiveObserverDefinition is derived by a later caller from a compiled module. It is deliberately narrower than a module and grants no command authority.

type LivePath 

type LivePath interface {
	MachineAndUserPath(context.Context) ([]string, error)
}

LivePath reconstructs the machine and user PATH from host authority. It must not return the current process PATH as a substitute.

type LivePhase 

type LivePhase string
const (
	LivePhasePreparation LivePhase = "preparation"
	LivePhasePackage     LivePhase = "package"
	LivePhaseSeed        LivePhase = "seed"
	LivePhaseCapture     LivePhase = "capture"
	LivePhaseRestore     LivePhase = "restore"
	LivePhaseCompare     LivePhase = "compare"
)

type LiveProcess 

type LiveProcess interface {
	Run(context.Context, string, ...string) (LiveProcessResult, error)
}

type LiveProcessClassification 

type LiveProcessClassification string
const (
	LiveProcessCompleted   LiveProcessClassification = "completed"
	LiveProcessNoInstalled LiveProcessClassification = "no-installed-package"
)

type LiveProcessRequest 

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

LiveProcessRequest is an internal execution request. It has no zero-value behavior: probes are created only by a reviewed typed builder, and mutations only by a permit-bearing typed builder.

type LiveProcessResult 

type LiveProcessResult struct {
	ExitCode       int
	Stdout         []byte
	Version        string
	Classification LiveProcessClassification
}

LiveProcessResult deliberately leaves non-zero exit result interpretation to a reviewed host contract; winget list's human output is not a stable API.

type LiveRegistry 

type LiveRegistry interface {
	UninstallRecords(context.Context) ([]LiveUninstallRecord, error)
}

type LiveRegistryView 

type LiveRegistryView string
const (
	LiveRegistryHKLM64 LiveRegistryView = "hklm-64"
	LiveRegistryHKLM32 LiveRegistryView = "hklm-32"
	LiveRegistryHKCU   LiveRegistryView = "hkcu"
)

type LiveRequest 

type LiveRequest struct {
	SchemaVersion int            `json:"schemaVersion"`
	Definition    LiveDefinition `json:"definition"`
	MaxAttempts   int            `json:"maxAttempts"`
}

LiveRequest contains only a compiled, non-authorizing diagnostic definition.

type LiveResult 

type LiveResult struct {
	SchemaVersion          int                           `json:"schemaVersion"`
	ModuleID               string                        `json:"moduleId"`
	ModuleRevision         string                        `json:"moduleRevision"`
	ValidationSourceSHA256 string                        `json:"validationSourceSha256"`
	DefinitionSHA256       string                        `json:"definitionSha256"`
	Status                 LiveStatus                    `json:"status"`
	PublicEvidenceEligible bool                          `json:"publicEvidenceEligible"`
	ProvenProofLevels      []validationmatrix.ProofLevel `json:"provenProofLevels"`
	Attempts               []LiveAttempt                 `json:"attempts"`
	FailureCategory        LiveFailureCategory           `json:"failureCategory,omitempty"`
}

LiveResult has no fields for config bytes, paths, environment state, command output, or secret-derived material. This slice never grants public evidence.

type LiveStatus 

type LiveStatus string
const (
	LiveStatusPending LiveStatus = "pending"
	LiveStatusPassed  LiveStatus = "passed"
	LiveStatusFailed  LiveStatus = "failed"
)

type LiveUninstallRecord 

type LiveUninstallRecord struct {
	View            LiveRegistryView
	KeyIdentity     string
	DisplayName     string
	DisplayVersion  string
	InstallLocation string
	DisplayIcon     string
	Publisher       string
	UninstallString string
}

type LiveVersionSource 

type LiveVersionSource interface {
	FileVersion(string) (string, error)
}

type OperationCounts 

type OperationCounts struct {
	Executed int
	Skipped  int
}

type PackageObservation 

type PackageObservation struct {
	Ref     string `json:"ref"`
	Version string `json:"version,omitempty"`
	Status  string `json:"status"`
}

type RegistryFixtureTarget 

type RegistryFixtureTarget struct {
	Coordinate  string
	Authored    string
	Destination string
	Source      string
	Target      string
	Strategy    string
	Optional    bool
	Captured    validationmode.RegistryState
	Mutated     validationmode.RegistryState
	Restored    validationmode.RegistryState
}

type Request 

type Request struct {
	EnginePath string
	RepoRoot   string
	ModuleID   string
	ScenarioID string
	ResultPath string
}

type RestoreContractPlan 

type RestoreContractPlan struct {
	ModuleID       string
	ModuleRevision string
	ScenarioID     string
	Inventory      validationmode.Inventory
	Restore        modules.RestoreDef
	Verifiers      []modules.VerifyDef
	Restored       []byte
	Original       []byte
	PayloadPath    string
	ManifestPath   string
	ArtifactPath   string
	// contains filtered or unexported fields
}

type Result 

type Result struct {
	SchemaVersion   int                           `json:"schemaVersion"`
	ModuleID        string                        `json:"moduleId"`
	ModuleRevision  string                        `json:"moduleRevision,omitempty"`
	ScenarioID      string                        `json:"scenarioId"`
	Kind            validationmatrix.ScenarioKind `json:"kind,omitempty"`
	Status          string                        `json:"status"`
	ProofLevels     []validationmatrix.ProofLevel `json:"proofLevels"`
	AssertionCounts map[string]int                `json:"assertionCounts"`
	Failure         *Failure                      `json:"failure,omitempty"`
	PhaseTimings    map[string]time.Duration      `json:"phaseTimings"`
}

func Run 

func Run(ctx context.Context, request Request) (Result, error)

Run validates one exact production module/scenario pair and executes its declared config roundtrip through the caller-built engine. Operational failures are returned in Result; errors are reserved for harness-owned I/O failures.

type V2ExcludedFixture 

type V2ExcludedFixture struct {
	Relative        string
	Path            string
	Captured        []byte
	Mutated         []byte
	CapturePatterns []string
	RestorePatterns []string
}

type V2FixtureFile 

type V2FixtureFile struct {
	Relative string
	Path     string
	Captured []byte
	Mutated  []byte
}

type V2FixturePlan 

type V2FixturePlan struct {
	Compiled             v2CompiledFixture
	Instance             modules.ConfigInstance
	TargetInstance       modules.ConfigInstance
	CaptureID            string
	CaptureTargets       []V2FixtureTarget
	Targets              []V2FixtureTarget
	CaptureValidations   int
	MigrationValidations int
	Validations          int
	// contains filtered or unexported fields
}

func (*V2FixturePlan) CompareCaptured 

func (plan *V2FixturePlan) CompareCaptured() *Failure

func (*V2FixturePlan) CompareMutated 

func (plan *V2FixturePlan) CompareMutated() *Failure

func (*V2FixturePlan) MaterializeCaptured 

func (plan *V2FixturePlan) MaterializeCaptured() *Failure

func (*V2FixturePlan) Mutate 

func (plan *V2FixturePlan) Mutate() *Failure

type V2FixtureTarget 

type V2FixtureTarget struct {
	Coordinate   string
	Authored     string
	Destination  string
	Resolved     string
	Directory    bool
	PreserveRoot bool
	Optional     bool
	Members      []V2FixtureFile
	Excluded     []V2ExcludedFixture
}

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.