productruntime

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

README

Product Runtime composition

pkg/productruntime is the public, provider-free construction and prepared- Apply boundary for authenticated StackKits Product Runtime integrations. It projects the StackKits-owned static owner catalog and selected-PaaS selector, then consumes the canonical kombify-go-common execution-channel, Apply-evidence Collector, Journal, and opaque recovery-custody contracts.

NewComposition fixes the exact remote-only owner allowlist, root identity, channel authority, Collector, Journal, and Recovery store before resolution. ApplyPrepared and ReconcilePrepared then accept only an authenticated authority scope, workspace, current StackSpec/Inventory, and (for recovery) an exact request digest. StackKits re-resolves through its embedded CUE authority, requires byte-identical persisted plan and generated artifacts, acquires the held output lock, collects evidence through the construction-owned Collector, and returns only a hash-bound provider-neutral result. Partial durable execution returns a public ReconcileRequiredError containing only the opaque request digest accepted by ReconcilePrepared; child operation state and provider-native receipts remain private to the owning service.

The API cannot accept caller evidence or an implicit local execution channel. It does not construct local Operations, select an endpoint, carry credentials, or own provider lifecycle, leases, generation, discovery, transport, retries, or persistence. Consumers implement those concerns behind the shared interfaces and must not import internal/architecturev2.

The static owner catalog includes all six CUE-owned HA owner IDs for Basement, Cloud, and Modern warm-standby/quorum. Authenticated services select those stable IDs as remote owners; they cannot reconstruct or substitute the provider/module selector. Member-local implementations receive only the sealed, provider-free HA policy through the internal Operations boundary.

Focused contract checks stay separate and bounded:

go test ./pkg/productruntime -count=1
cd pkg/productruntime/testdata/externalconsumer
GOWORK=off go test ./... -count=1

Documentation

Overview

Package productruntime exposes the provider-free StackKits Product Runtime construction contract and its high-level prepared-Apply composition. StackKits remains the authority for CUE-owned selectors, target intent, workspace custody, and authorization; this package contains no transport, credential, provider, lease, generation, discovery, or persistence implementation.

Index

Constants

View Source 
const (
	OwnerSecurityBaseline       = architecturev2.ProductRuntimeOwnerSecurityBaseline
	OwnerCoreHostBootstrap      = architecturev2.ProductRuntimeOwnerCoreHostBootstrap
	OwnerHomeBackupTarget       = architecturev2.ProductRuntimeOwnerHomeBackupTarget
	OwnerBasementCompose        = architecturev2.ProductRuntimeOwnerBasementCompose
	OwnerBasementIdentityTrust  = architecturev2.ProductRuntimeOwnerBasementIdentityTrust
	OwnerCloudIdentityTrust     = architecturev2.ProductRuntimeOwnerCloudIdentityTrust
	OwnerCloudHostSecurity      = architecturev2.ProductRuntimeOwnerCloudHostSecurity
	OwnerCloudPublicEdge        = architecturev2.ProductRuntimeOwnerCloudPublicEdge
	OwnerCloudOffsiteBackup     = architecturev2.ProductRuntimeOwnerCloudOffsiteBackup
	OwnerPublicTLS              = architecturev2.ProductRuntimeOwnerPublicTLS
	OwnerHomeDeviceAuthority    = architecturev2.ProductRuntimeOwnerHomeDeviceAuthority
	OwnerHomeAccess             = architecturev2.ProductRuntimeOwnerHomeAccess
	OwnerLocalAutonomy          = architecturev2.ProductRuntimeOwnerLocalAutonomy
	OwnerModernHomeIdentity     = architecturev2.ProductRuntimeOwnerModernHomeIdentity
	OwnerModernCloudIdentity    = architecturev2.ProductRuntimeOwnerModernCloudIdentity
	OwnerFederationLink         = architecturev2.ProductRuntimeOwnerFederationLink
	OwnerFederationControlAgent = architecturev2.ProductRuntimeOwnerFederationControlAgent
	OwnerBridgePublication      = architecturev2.ProductRuntimeOwnerBridgePublication
	OwnerBridgeOriginMTLS       = architecturev2.ProductRuntimeOwnerBridgeOriginMTLS
	OwnerHABasementWarm         = architecturev2.ProductRuntimeOwnerHABasementWarm
	OwnerHABasementQuorum       = architecturev2.ProductRuntimeOwnerHABasementQuorum
	OwnerHACloudWarm            = architecturev2.ProductRuntimeOwnerHACloudWarm
	OwnerHACloudQuorum          = architecturev2.ProductRuntimeOwnerHACloudQuorum
	OwnerHAModernWarm           = architecturev2.ProductRuntimeOwnerHAModernWarm
	OwnerHAModernQuorum         = architecturev2.ProductRuntimeOwnerHAModernQuorum
)

Variables

This section is empty.

Functions

This section is empty.

Types

type ApplyEvidenceCollectionRequest 

type ApplyEvidenceCollectionRequest = applyevidence.CollectionRequest

type ApplyEvidenceCollector 

type ApplyEvidenceCollector = applyevidence.Collector

ApplyEvidenceCollector and RecoveryStore are the shared custody SPIs used by a service-owned composition. Implementations retain observation/signing and persistence behavior; StackKits receives only exact requests and opaque canonical bytes.

type ApplyResult 

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

ApplyResult is the immutable public projection of a verified StackKits execution result. It contains no provider-native lifecycle receipt.

func (ApplyResult) Canonical 

func (r ApplyResult) Canonical() []byte

Canonical returns a defensive copy of the verified result envelope.

func (ApplyResult) ResultHash 

func (r ApplyResult) ResultHash() string

ResultHash returns the canonical content address of the verified result.

type ComponentVersions 

type ComponentVersions struct {
	CLI       string
	Generator string
	Runtime   string
}

ComponentVersions identifies the exact StackKits components participating in one prepared Apply. These identities are checked against the CUE-owned compatibility minima before an execution channel can be admitted.

type Composition 

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

Composition is an opaque, concurrency-safe Product Runtime authority. It owns no provider client, transport credential, lease, generation, endpoint, or service database. Those concerns stay behind the supplied shared SPIs.

func NewComposition 

func NewComposition(config CompositionConfig) (*Composition, error)

NewComposition constructs the external Product Runtime boundary. Every planned owner is remote-only at this boundary: an execution-channel admission must return the authenticated executor and the implicit local builder can never be selected.

func (*Composition) ApplyPrepared 

func (c *Composition) ApplyPrepared(ctx context.Context, request PreparedRequest) (ApplyResult, error)

ApplyPrepared resolves current intent through embedded CUE authority, opens and locks the governed workspace itself, collects evidence through the construction-owned collector, and executes only through an admitted shared channel. Generated artifacts must already exist and match this exact resolution; no caller-provided evidence or local fallback is accepted.

func (*Composition) ReconcilePrepared 

func (c *Composition) ReconcilePrepared(ctx context.Context, request ReconcileRequest) (ApplyResult, error)

ReconcilePrepared revalidates the same CUE plan and held generated bytes before resuming one exact recovery digest. Access-bound recovery remains fail-closed until its fresh-instant continuation contract is versioned.

type CompositionConfig 

type CompositionConfig struct {
	BuildVersion       string
	Versions           ComponentVersions
	StaticOwners       []OwnerID
	ImmichSelectedPaaS *SelectedPaaSOwner
	ExecutionChannels  ExecutionChannelFactory
	EvidenceCollector  ApplyEvidenceCollector
	Journal            Journal
	Recovery           RecoveryStore
}

CompositionConfig fixes the complete provider-free Product Runtime graph at construction. All collaborators are shared contracts; StackKits retains the CUE authority, target selection, workspace custody, and authorization logic.

type ExecutionChannelAdmission 

type ExecutionChannelAdmission = runtimeexecutor.ExecutionChannelAdmission

type ExecutionChannelFactory 

type ExecutionChannelFactory = runtimeexecutor.ExecutionChannelFactory

type ExecutionChannelLocalExecutor 

type ExecutionChannelLocalExecutor = runtimeexecutor.ExecutionChannelLocalExecutor

type ExecutionChannelRequest 

type ExecutionChannelRequest = runtimeexecutor.ExecutionChannelRequest

ExecutionChannelRequest and the related interfaces are aliases of the canonical go-common contract. They are repeated here only as the StackKits integration entry surface; their ownership remains in runtimeexecutor.

type Journal 

type Journal = runtimeapply.Journal

type OwnerDescriptor 

type OwnerDescriptor = architecturev2.ProductRuntimeOwnerDescriptor

OwnerDescriptor is a value-only projection of one governed owner selector.

func ImmichSelectedPaaSOwner 

func ImmichSelectedPaaSOwner(runtimeAdapterRef, runtimeAdapterModuleRef string) (OwnerDescriptor, error)

ImmichSelectedPaaSOwner returns the exact governed workload selector for one explicitly selected adapter identity. It grants no Operations or transport authority and does not register or execute the owner.

func StaticOwnerCatalog 

func StaticOwnerCatalog() []OwnerDescriptor

StaticOwnerCatalog returns a fresh projection of every stable static owner. Selected-PaaS owners are constructed separately because adapter identity is a required service-owned input.

type OwnerID 

type OwnerID = architecturev2.ProductRuntimeOwnerID

OwnerID is the stable StackKits-owned identity of one static Product Runtime owner. Consumers never reconstruct selector fields from this value.

type OwnerSelector 

type OwnerSelector = architecturev2.ProductRuntimeOwnerSelector

OwnerSelector is the exact provider-free CUE/catalog selector used to match one verified RuntimeTarget to its service-owned owner.

type PreparedRequest 

type PreparedRequest struct {
	AuthorityScope string
	WorkspaceRoot  string
	StackSpec      []byte
	Inventory      []byte
}

PreparedRequest identifies one already-generated StackKits workspace. The authority scope isolates otherwise equal Stack IDs between authenticated tenants without entering the ResolvedPlan or generated artifact contract.

type ReconcileRequest 

type ReconcileRequest struct {
	PreparedRequest
	RequestDigest string
}

ReconcileRequest resumes one exact request already held by the construction-owned Recovery store. Callers cannot supply recovery bytes or substitute evidence.

type ReconcileRequiredError 

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

ReconcileRequiredError is the public fail-closed handoff after a partially executed durable Apply. Its opaque digest is the only authority accepted by ReconcilePrepared; internal operation steps and provider state are not exposed.

func (*ReconcileRequiredError) Error 

func (e *ReconcileRequiredError) Error() string

func (*ReconcileRequiredError) RequestDigest 

func (e *ReconcileRequiredError) RequestDigest() string

RequestDigest returns the exact recovery-custody key for ReconcilePrepared.

func (*ReconcileRequiredError) Unwrap 

func (e *ReconcileRequiredError) Unwrap() error

Unwrap preserves typed lower-level diagnostics without exporting their internal StackKits representation as part of this package's API.

type RecoveryStore 

type RecoveryStore = runtimeapply.RecoveryStore

type SelectedPaaSOwner 

type SelectedPaaSOwner struct {
	RuntimeAdapterRef       string
	RuntimeAdapterModuleRef string
}

SelectedPaaSOwner binds the one workload-specific owner whose exact runtime adapter identity is intentionally not static. The refs are catalog identities only; endpoints, credentials, leases, generations, and provider resource handles remain outside StackKits.

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.