resolvedplan

package
v0.40.0 Latest Latest
Warning

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

 Go to latest Published: Sep 24, 2026 License: Apache-2.0 Imports: 27 Imported by: 0

Documentation

Overview

Package resolvedplan compiles the Architecture v2 intent, immutable kit definition, observed inventory, and a governed contract catalog into the one deterministic plan consumed by later generators and runtimes.

CUE remains the schema authority. The document types deliberately retain a JSON-shaped boundary instead of duplicating the full CUE type system in Go. Compile performs the cross-document and catalog resolution that CUE alone cannot perform, and MarshalCanonical emits a CUE-compatible JSON document.

Index

Constants

View Source 
const (
	// ResolvedPlanAPIVersion is the only plan contract emitted by the
	// Architecture v2 compiler. A StackSpec v1 document is never accepted as a
	// ResolvedPlan through the integrity helpers below.
	ResolvedPlanAPIVersion = "stackkit.resolved-plan/v1"
	ResolvedPlanKind       = "ResolvedPlan"
)

Variables

This section is empty.

Functions

func CanonicalJSON 

func CanonicalJSON(value any) ([]byte, error)

CanonicalJSON exposes the compiler's canonical JSON implementation for versioned downstream contracts such as generation manifests. Callers must not introduce a second JSON-normalization or object-hashing algorithm.

func CanonicalPlanHash 

func CanonicalPlanHash(plan ResolvedPlan) (string, error)

CanonicalPlanHash returns the compiler-compatible hash of a plan with its declared planHash omitted. It preserves the established secret-redaction semantics and never mutates the supplied map.

func CanonicalSHA256 

func CanonicalSHA256(value any) (string, error)

CanonicalSHA256 returns the compiler canonical hash without applying secret redaction. ResolvedPlan integrity must instead use VerifyPlanHash, which applies the exact compiler rules and rejects unsafe secret material first.

func ComputeBackupTargetRequirementHash 

func ComputeBackupTargetRequirementHash(requirement BackupTargetRequirement) (string, error)

func ComputeExternalBackupTargetBindingHash 

func ComputeExternalBackupTargetBindingHash(binding ExternalBackupTargetBinding) (string, error)

func ComputeExternalFederationLinkBindingHash 

func ComputeExternalFederationLinkBindingHash(binding ExternalFederationLinkBinding) (string, error)

func ComputeExternalHomeAccessBindingHash 

func ComputeExternalHomeAccessBindingHash(binding ExternalHomeAccessBinding) (string, error)

ComputeExternalHomeAccessBindingHash binds the opaque external realization envelope. No provider, endpoint, address, transport, or credential is part of this authority.

func ComputeExternalHomeBackupTargetBindingHash 

func ComputeExternalHomeBackupTargetBindingHash(binding ExternalHomeBackupTargetBinding) (string, error)

func ComputeExternalHostBindingHash 

func ComputeExternalHostBindingHash(binding ExternalHostBinding) (string, error)

ComputeExternalHostBindingHash returns the canonical digest of a normalized ExternalHostBinding with bindingHash omitted. It performs no provider action.

func ComputeExternalHostRequirementsHash 

func ComputeExternalHostRequirementsHash(plan ResolvedPlan, nodeRef string) (string, error)

ComputeExternalHostRequirementsHash returns the exact provider-free host requirements digest for one node in a canonical plan. Binding issuers use this value without learning or transferring any server-provider identity.

func ComputeFederationLinkRequirementHash 

func ComputeFederationLinkRequirementHash(requirement FederationLinkRequirement) (string, error)

func ComputeHomeAccessRequirementHash 

func ComputeHomeAccessRequirementHash(requirement HomeAccessRequirement) (string, error)

ComputeHomeAccessRequirementHash binds the complete provider-neutral requirement body while avoiding a self-referential digest.

func ComputeHomeBackupTargetRequirementHash 

func ComputeHomeBackupTargetRequirementHash(requirement HomeBackupTargetRequirement) (string, error)

func ComputeHostConformanceReceiptDigest 

func ComputeHostConformanceReceiptDigest(receipt HostConformanceReceipt) (string, error)

ComputeHostConformanceReceiptDigest returns the canonical digest of a normalized HostConformanceReceipt with receiptDigest omitted.

func DecodeDocument 

func DecodeDocument[T ~map[string]any](data []byte) (T, error)

DecodeDocument decodes a CUE-exported JSON object into a typed document map. It rejects trailing JSON values and preserves numbers as json.Number so canonical hashes do not depend on float conversion.

func ProjectRecoveryObjectives 

func ProjectRecoveryObjectives(data map[string]any, applications []localbackuppolicy.ApplicationVolume) ([]localbackuppolicy.RecoveryObjective, error)

ProjectRecoveryObjectives projects only objectives represented by the target-local application volumes. The complete binding/source coverage is checked by validateRecoveryObjectives before rendering the policy.

func ValidateExternalBackupTargetBindingsFreshness 

func ValidateExternalBackupTargetBindingsFreshness(plan ResolvedPlan, at time.Time) error

func ValidateExternalFederationLinkBinding 

func ValidateExternalFederationLinkBinding(binding ExternalFederationLinkBinding, requirement FederationLinkRequirement) error

ValidateExternalFederationLinkBinding verifies the complete closed external custody receipt against its exact compiler-owned requirement, including opaque reference shapes, semantic version, canonical hashes, UTC timestamps, and the normative maximum validity window.

func ValidateExternalFederationLinkBindingsFreshness 

func ValidateExternalFederationLinkBindingsFreshness(plan ResolvedPlan, at time.Time) error

func ValidateExternalHomeAccessBindingsFreshness 

func ValidateExternalHomeAccessBindingsFreshness(plan ResolvedPlan, at time.Time) error

ValidateExternalHomeAccessBindingsFreshness revalidates exact requirement parity and the externally issued validity window at execution time.

func ValidateExternalHomeBackupTargetBindingsFreshness 

func ValidateExternalHomeBackupTargetBindingsFreshness(plan ResolvedPlan, at time.Time) error

func ValidateExternalHostBindingForReceipt 

func ValidateExternalHostBindingForReceipt(binding ExternalHostBinding, at time.Time) error

ValidateExternalHostBindingForReceipt validates the closed, provider-free handoff envelope before an on-host receipt producer trusts it. Intent and inventory equality are revalidated later by the final plan compiler.

func ValidateExternalHostBindingFreshness 

func ValidateExternalHostBindingFreshness(binding ExternalHostBinding, at time.Time) error

ValidateExternalHostBindingFreshness is the deterministic apply-time staleness check. The compiler deliberately does not read wall-clock time; the caller supplies the execution instant that will be recorded in evidence.

func ValidateExternalHostBindingsFreshness 

func ValidateExternalHostBindingsFreshness(plan ResolvedPlan, at time.Time) error

ValidateExternalHostBindingsFreshness applies the execution-time validity decision to every provider-free host handoff in an already verified plan. Empty bindings are valid for plans that execute entirely on the current host. The caller owns the execution instant so the same value can be written to apply evidence; the compiler remains deterministic and clock-free.

func ValidateHostConformanceReceiptsForApply 

func ValidateHostConformanceReceiptsForApply(plan ResolvedPlan, at time.Time) error

ValidateHostConformanceReceiptsForApply admits external hosts only when each binding has one fresh, identity-bound and conformant StackKits receipt. Plans without external host bindings remain valid for local execution.

func VerifyPlanHash 

func VerifyPlanHash(plan ResolvedPlan) (string, error)

VerifyPlanHash verifies the self-declared hash against the canonical plan with planHash removed. It also rejects plaintext secret material, the wrong contract kind/version, malformed hashes, and never mutates the caller's map.

func VersionAtLeast 

func VersionAtLeast(actual, minimum string) (bool, error)

VersionAtLeast applies the compiler's semantic-version ordering for downstream compatibility gates. Keeping this comparison here prevents generation/apply adapters from drifting onto a second version algorithm.

Types

type AddOnContract 

type AddOnContract map[string]any

AddOnContract is a JSON-decoded foundation.#AddOnContract document.

type ApplicationLifecycleContract 

type ApplicationLifecycleContract map[string]any

ApplicationLifecycleContract is a JSON-decoded foundation.#ApplicationLifecycleContractV1 document. It binds a selected application workload to the reusable lifecycle and its Application Kit package without exposing either choice as StackSpec input.

type BackupTargetRequirement 

type BackupTargetRequirement map[string]any

BackupTargetRequirement is StackKits-owned provider-free intent for one Cloud offsite backup destination.

type CUEContractValidator 

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

CUEContractValidator is the non-substitutable schema authority used by Compiler. Its state can only be initialized by NewCUEContractValidator, so a caller cannot inject a no-op implementation and bypass #KitSpecBinding or #ResolvedPlan validation.

func NewCUEContractValidator 

func NewCUEContractValidator(moduleRoot string) (*CUEContractValidator, error)

NewCUEContractValidator binds validation to a concrete StackKits CUE module. moduleRoot must contain cue.mod/module.cue, the authority profile projection, foundation/architecture_v2.cue, and the semantic Definition binding.

func NewCUEContractValidatorForAuthority 

func NewCUEContractValidatorForAuthority(moduleRoot string, authority PlanAuthority) (*CUEContractValidator, error)

NewCUEContractValidatorForAuthority binds filesystem-backed validation to one exact plan authority class.

func NewCUEContractValidatorFromSources 

func NewCUEContractValidatorFromSources(virtualModuleRoot string, sources map[string][]byte) (*CUEContractValidator, error)

NewCUEContractValidatorFromSources binds validation to an immutable, in-memory CUE module. virtualModuleRoot is an absolute namespace only; the constructor and subsequent validation never trust or materialize authority from that host path. Source keys are module-relative slash paths such as cue.mod/module.cue.

func NewCUEContractValidatorFromSourcesForAuthority 

func NewCUEContractValidatorFromSourcesForAuthority(virtualModuleRoot string, sources map[string][]byte, authority PlanAuthority) (*CUEContractValidator, error)

NewCUEContractValidatorFromSourcesForAuthority additionally binds every verified plan to one exact product or contract-fixture authority class.

func (*CUEContractValidator) NormalizeStackSpecBinding 

func (v *CUEContractValidator) NormalizeStackSpecBinding(definition KitDefinition, spec StackSpecV2) (StackSpecV2, error)

NormalizeStackSpecBinding validates desired intent against the canonical StackSpec contract and the selected Kit Definition without inventing host inventory or compiling a target-specific ResolvedPlan.

func (*CUEContractValidator) ValidateCanonicalPlan 

func (v *CUEContractValidator) ValidateCanonicalPlan(plan ResolvedPlan) error

ValidateCanonicalPlan re-runs the governed CUE #ResolvedPlan contract and requires the supplied plan to already equal the fully normalized result. This is deliberately a method on the non-substitutable concrete validator: downstream apply/generation gates cannot claim semantic verification from a self-consistent planHash alone or inject a no-op schema validator.

func (*CUEContractValidator) ValidateFederationRemoteActionEnvelope 

func (v *CUEContractValidator) ValidateFederationRemoteActionEnvelope(raw []byte) error

ValidateFederationRemoteActionEnvelope applies the closed catalog-owned wire shape. Signatures, present-time TTL and replay decisions remain runtime checks.

type CapabilityContract 

type CapabilityContract map[string]any

CapabilityContract is a JSON-decoded foundation.#CapabilityContract document.

type CapabilityProvider 

type CapabilityProvider map[string]any

CapabilityProvider is a JSON-decoded foundation.#CapabilityProvider document.

type Catalog 

type Catalog struct {
	Capabilities                 []CapabilityContract
	Providers                    []CapabilityProvider
	AddOns                       []AddOnContract
	Modules                      []ModuleContract
	Workloads                    []WorkloadContract
	ApplicationLifecycles        []ApplicationLifecycleContract
	PrivilegedInterfaceApprovals []PrivilegedInterfaceApproval
	RILActionExecutors           []RILActionExecutorContract
	RILActionPrimitives          []RILActionPrimitiveContract
	PlanArtifacts                []PlanArtifactContract
}

Catalog is the governed set of contracts the compiler may resolve. Unknown IDs and capabilities without exactly one selected realization fail closed.

type CompileError 

type CompileError struct {
	Code    ErrorCode
	Path    string
	Message string
}

CompileError identifies a fail-closed compiler decision.

func (*CompileError) Error 

func (e *CompileError) Error() string

type Compiler 

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

Compiler owns an immutable governed catalog and produces ResolvedPlan v1. It is safe for concurrent use after construction.

func NewCompiler 

func NewCompiler(catalog Catalog, options Options) (*Compiler, error)

NewCompiler validates and freezes the governed contract catalog.

func (*Compiler) Compile 

func (c *Compiler) Compile(input Input) (ResolvedPlan, error)

Compile resolves one profile-bound desired spec and its observed inventory. The returned plan contains no plaintext secret values and its planHash covers the complete plan except the planHash field itself.

func (*Compiler) ComputeExternalHostInventoryHash 

func (c *Compiler) ComputeExternalHostInventoryHash(inventory InventoryFacts) (string, error)

ComputeExternalHostInventoryHash returns the canonical provider-free digest an ExternalHostBinding must carry. It first applies the same CUE inventory normalization as Compile, then excludes the self-referential binding and conformance envelopes exactly as plan compilation does.

type ErrorCode 

type ErrorCode string

ErrorCode is stable enough for CLI/API adapters to map without parsing text. 

const (
	ErrInvalidInput               ErrorCode = "invalid_input"
	ErrContractValidation         ErrorCode = "contract_validation"
	ErrProfileMismatch            ErrorCode = "profile_spec_mismatch"
	ErrUnknownCapability          ErrorCode = "unknown_capability"
	ErrForbiddenCapability        ErrorCode = "forbidden_capability"
	ErrUnrealizedCapability       ErrorCode = "unrealized_capability"
	ErrAmbiguousProvider          ErrorCode = "ambiguous_provider"
	ErrUnknownProvider            ErrorCode = "unknown_provider"
	ErrUnknownAddOn               ErrorCode = "unknown_addon"
	ErrUnsupportedAddOn           ErrorCode = "unsupported_addon"
	ErrUnknownModule              ErrorCode = "unknown_module"
	ErrUnrealizedModule           ErrorCode = "unrealized_module"
	ErrUndeclaredComputeProfile   ErrorCode = "undeclared_compute_profile"
	ErrUnknownWorkload            ErrorCode = "unknown_workload"
	ErrForbiddenWorkload          ErrorCode = "forbidden_workload"
	ErrUnknownWorkloadAlternative ErrorCode = "unknown_workload_alternative"
	ErrContractConflict           ErrorCode = "contract_conflict"
	ErrUnresolvedPlacement        ErrorCode = "unresolved_placement"
	ErrUnsafeSecretReference      ErrorCode = "unsafe_secret_reference"
	ErrPlanHashMismatch           ErrorCode = "plan_hash_mismatch"
	ErrNonCanonicalPlan           ErrorCode = "non_canonical_plan"
)
const (
	ErrExternalHostBindingStale                ErrorCode = "external_host_binding_stale"
	ErrHostConformanceReceiptMissing           ErrorCode = "host_conformance_receipt_missing"
	ErrHostConformanceReceiptStale             ErrorCode = "host_conformance_receipt_stale"
	ErrHostConformanceReceiptRejected          ErrorCode = "host_conformance_receipt_rejected"
	ErrExternalHomeAccessBindingStale          ErrorCode = "external_home_access_binding_stale"
	ErrExternalHomeAccessBindingMismatch       ErrorCode = "external_home_access_binding_mismatch"
	ErrExternalBackupTargetBindingStale        ErrorCode = "external_backup_target_binding_stale"
	ErrExternalBackupTargetBindingMismatch     ErrorCode = "external_backup_target_binding_mismatch"
	ErrExternalHomeBackupTargetBindingStale    ErrorCode = "external_home_backup_target_binding_stale"
	ErrExternalHomeBackupTargetBindingMismatch ErrorCode = "external_home_backup_target_binding_mismatch"
	ErrExternalFederationLinkBindingStale      ErrorCode = "external_federation_link_binding_stale"
	ErrExternalFederationLinkBindingMismatch   ErrorCode = "external_federation_link_binding_mismatch"
)

type ExternalBackupTargetBinding 

type ExternalBackupTargetBinding map[string]any

ExternalBackupTargetBinding is the opaque, time-bound custody attestation supplied by the external backup-target authority.

func IssueExternalBackupTargetBinding 

func IssueExternalBackupTargetBinding(requirement BackupTargetRequirement, targetRef, custodyRef, version, candidateDigest string, at time.Time) (ExternalBackupTargetBinding, error)

IssueExternalBackupTargetBinding projects a local owner's opaque custody commitments onto the existing provider-neutral external target contract.

type ExternalFederationLinkBinding 

type ExternalFederationLinkBinding map[string]any

ExternalFederationLinkBinding is the opaque, time-bound attestation for one exact FederationLinkRequirement.

type ExternalHomeAccessBinding 

type ExternalHomeAccessBinding map[string]any

ExternalHomeAccessBinding is an opaque external realization binding. It carries no transport, endpoint, credential, or provider lifecycle data.

type ExternalHomeBackupTargetBinding 

type ExternalHomeBackupTargetBinding map[string]any

ExternalHomeBackupTargetBinding is the opaque, time-bound custody attestation supplied by the external Home backup-target authority.

type ExternalHostBinding 

type ExternalHostBinding map[string]any

ExternalHostBinding is the provider-free handoff for a host that has already been selected and supplied by the platform control plane.

type FederationLinkRequirement 

type FederationLinkRequirement map[string]any

FederationLinkRequirement is the compiler-owned, provider-free Modern Home-to-Cloud fabric requirement.

type HomeAccessRequirement 

type HomeAccessRequirement map[string]any

HomeAccessRequirement is the StackKits-owned, provider-neutral Shadow-Plan contract for one Home access capability.

type HomeBackupTargetRequirement 

type HomeBackupTargetRequirement map[string]any

HomeBackupTargetRequirement is StackKits-owned provider-free intent for one encrypted Home offsite backup destination.

type HostConformanceReceipt 

type HostConformanceReceipt map[string]any

HostConformanceReceipt is StackKits-owned OS/host diagnostic evidence for one exact ExternalHostBinding. It is never server-provider compatibility.

type Input 

type Input struct {
	Definition KitDefinition
	Spec       StackSpecV2
	Inventory  InventoryFacts
}

Input contains the only deployment-specific compiler inputs. Catalog data is immutable compiler configuration and is therefore supplied to NewCompiler.

type InventoryFacts 

type InventoryFacts map[string]any

InventoryFacts is a JSON-decoded foundation.#InventoryFacts document.

func AttachExternalBackupTargetBinding 

func AttachExternalBackupTargetBinding(inventory InventoryFacts, requirement BackupTargetRequirement, binding ExternalBackupTargetBinding, previousHash string) (InventoryFacts, error)

AttachExternalBackupTargetBinding preserves all other Inventory authority. Renewal requires the exact previous hash; a caller cannot replace a raced target.

type KitDefinition 

type KitDefinition map[string]any

KitDefinition is a JSON-decoded foundation.#KitDefinition document.

type ModuleContract 

type ModuleContract map[string]any

ModuleContract is a JSON-decoded foundation.#ModuleContractV2 document.

type Options 

type Options struct {
	CompilerVersion   string
	ContractValidator *CUEContractValidator
	PlanAuthority     PlanAuthority
	// AuthorityDefinitions is the complete CUE-exported Definition set owned
	// by the service constructing this compiler. When present, persisted-plan
	// verification is bound to those exact normalized definition hashes.
	AuthorityDefinitions    []KitDefinition
	MinimumCLIVersion       string
	MinimumRuntimeVersion   string
	MinimumGeneratorVersion string
	RendererID              string
	RendererVersion         string
}

Options records compiler identity in every plan. CompilerVersion must be a stable release/build identifier and must not contain timestamps.

type PlanArtifactContract 

type PlanArtifactContract map[string]any

PlanArtifactContract is a JSON-decoded foundation.#CatalogPlanArtifactV2 document. It is CUE catalog authority, not caller-supplied compiler configuration.

type PlanAuthority 

type PlanAuthority struct {
	Class                string `json:"class"`
	Document             string `json:"document"`
	GraduationEligible   bool   `json:"graduationEligible"`
	Issuer               string `json:"issuer"`
	AuthorityFingerprint string `json:"authorityFingerprint,omitempty"`
	CatalogHash          string `json:"catalogHash,omitempty"`
}

PlanAuthority is plan-bound provenance, not sidecar fixture metadata. The exact class/document/eligibility tuple is CUE constrained and carried into generation manifests and receipts so evidence consumers cannot graduate a contract fixture as a product kit.

func ContractFixturePlanAuthority 

func ContractFixturePlanAuthority() PlanAuthority

func DevelopmentPlanAuthority 

func DevelopmentPlanAuthority() PlanAuthority

DevelopmentPlanAuthority is the non-graduating default for filesystem and caller-supplied CUE sources. Product eligibility is reserved for the embedded authority bundle shipped inside the binary.

func ProductPlanAuthority 

func ProductPlanAuthority() PlanAuthority

type PrivilegedInterfaceApproval 

type PrivilegedInterfaceApproval map[string]any

PrivilegedInterfaceApproval is centrally owned catalog authority for one narrowly scoped direct runtime-interface exception.

type RILActionExecutorContract 

type RILActionExecutorContract map[string]any

RILActionExecutorContract is the CUE-governed, provider-free identity and operation-class boundary for one authenticated in-process action owner.

type RILActionPrimitiveContract 

type RILActionPrimitiveContract map[string]any

RILActionPrimitiveContract is a CUE-governed approved-action catalog entry. Presence in the catalog is not execution support; the contract's support field remains contract-only until an authenticated runtime owner is bound.

type ResolvedPlan 

type ResolvedPlan map[string]any

ResolvedPlan is a JSON-decoded foundation.#ResolvedPlan document. It must only be constructed through Compiler.Compile so its source and plan hashes agree.

func DecodeCanonicalPlan 

func DecodeCanonicalPlan(data []byte) (ResolvedPlan, error)

DecodeCanonicalPlan accepts only byte-for-byte canonical JSON. Requiring the canonical representation rejects duplicate object keys and representation ambiguity before a persisted plan reaches a renderer or apply gate.

func (ResolvedPlan) MarshalCanonical 

func (p ResolvedPlan) MarshalCanonical() ([]byte, error)

MarshalCanonical emits stable JSON suitable for persisting or handing to CUE. It never applies secret redaction; plans are already sanitized before they are constructed.

type StackSpecV2 

type StackSpecV2 map[string]any

StackSpecV2 is a JSON-decoded foundation.#StackSpecV2 document.

type WorkloadComputeTierFit 

type WorkloadComputeTierFit struct {
	Declared      bool
	Included      bool
	AlternativeID string
	Reason        string
}

WorkloadComputeTierFit is the catalog binding of one workload to one install.computeTier graph. Undeclared fits admit the default alternative.

func CatalogWorkloadComputeTierFit 

func CatalogWorkloadComputeTierFit(contract map[string]any, tier string) WorkloadComputeTierFit

CatalogWorkloadComputeTierFit reads #WorkloadContractV2.computeTiers. Missing computeTiers or a missing tier admits the caller to use defaultAlternative.

type WorkloadContract 

type WorkloadContract map[string]any

WorkloadContract is a JSON-decoded foundation.#WorkloadContractV2 document. It owns logical workload and alternative selection; StackSpec never supplies the referenced provider or module implementation IDs.

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.