applicationlifecycle

package
v0.50.1 Latest Latest
Warning

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

 Go to latest Published: Oct 1, 2026 License: Apache-2.0 Imports: 17 Imported by: 0

Documentation

Overview

Package applicationlifecycle persists the resumable state of every selected Application Kit. The state is bound to the exact ResolvedPlan and lifecycle contract; StackSpec and caller-supplied package identities are never read.

Index

Constants

View Source 
const (
	AxisVerified    = "verified"
	AxisUnverified  = "unverified"
	AxisRequired    = "required"
	AxisBlocked     = "blocked"
	AxisAbsent      = "absent"
	AxisNotRequired = "not-required"

	FreshnessLive       = "live"
	FreshnessHistorical = "historical"
	FreshnessNone       = "none"
)
View Source 
const (
	SetupResultAPIVersion = "stackkit.application-setup-result/v1"

	// VaultOwnerInviteActionRef is the sole action allowed to persist the
	// preparation facts below. They describe server-side invitation metadata;
	// neither fact proves personal login or client-side decryption.
	VaultOwnerInviteActionRef = "vault-owner-invite"
	// ImmichAddOnAPIKeyActionRef issues an add-on API key through the verified
	// Immich administrator; its result records the issued key, not an account.
	ImmichAddOnAPIKeyActionRef   = "immich-add-on-api-key"
	ImmichAddOnAPIKeyPreparation = "immich-api-key-issued"
	// ComfyUIModelDownloadActionRef installs a reviewed model preset. ComfyUI
	// has no accounts, so no administrator login is verified; the result
	// records the preset (Preparation "model-preset-<id>").
	ComfyUIModelDownloadActionRef = "comfyui-model-download"
	ComfyUIModelPresetPreparation = "model-preset-"
	// KombifyAIConnectorEnabledPreparation and KombifyAIConnectorDisabled-
	// Preparation report `stackkit setup ai-connect`. It changes the owner's
	// intent (connector token custody and the kombify-connector setting) ahead
	// of the next apply, so it observes no application and seals no setup
	// receipt; the next apply records the connector like any component.
	KombifyAIConnectorEnabledPreparation  = "kombify-ai-connector-enabled"
	KombifyAIConnectorDisabledPreparation = "kombify-ai-connector-disabled"
	VaultOwnerPreparationInvited          = "owner-invited"
	VaultOwnerPreparationRegistered       = "owner-registered"
	OwnerEmailVerificationPending         = "pending"
	OwnerEmailVerificationVerified        = "verified"
)
View Source 
const (
	APIVersion = "stackkit.application-lifecycle-state/v1"

	StatusRunning          = "running"
	StatusSucceeded        = "succeeded"
	StatusFailed           = "failed"
	StatusRecoveryRequired = "recovery-required"
	StatusRecovered        = "recovered"
)
View Source 
const AdoptionProfile = "home-assistant-container-in-place/v1"
View Source 
const AdoptionSchemaVersion = "stackkit.application-adoption/v1"
View Source 
const ExperienceSchemaVersion = "stackkit.application-experience/v1"

ExperienceSchemaVersion identifies the derived, read-only application experience projection. It is deliberately separate from the durable lifecycle state: the projection may be recomputed from the current Plan and the owner-custodied evidence at any time.

Variables

This section is empty.

Functions

func AdoptionIntentDigest added in v0.49.8 

func AdoptionIntentDigest(verb, action string, result AdoptionResult) (string, error)

func NewOperationID 

func NewOperationID(operationRef string) (string, error)

NewOperationID returns a collision-resistant local operation identity. The operationRef prefix keeps persisted state readable without making wall-clock time or a caller-provided identifier authoritative.

Types

type AdoptionContract added in v0.49.8 

type AdoptionContract struct {
	ProfileRef      string   `json:"profileRef"`
	Mode            string   `json:"mode"`
	SourceRuntime   string   `json:"sourceRuntime"`
	ImageRef        string   `json:"imageRef"`
	ImageDigest     string   `json:"imageDigest"`
	Version         string   `json:"version"`
	OwnedFields     []string `json:"ownedFields"`
	PreservedFields []string `json:"preservedFields"`
	Operations      []string `json:"operations"`
}

type AdoptionPlan added in v0.49.8 

type AdoptionPlan struct {
	SchemaVersion      string         `json:"schemaVersion"`
	APIVersion         string         `json:"apiVersion"`
	Authority          Authority      `json:"authority"`
	WorkloadRef        string         `json:"workloadRef"`
	ProfileRef         string         `json:"profileRef"`
	Mode               string         `json:"mode"`
	Source             AdoptionSource `json:"source"`
	OwnedFields        []string       `json:"ownedFields"`
	PreservedFields    []string       `json:"preservedFields"`
	AdmittedOperations []string       `json:"admittedOperations"`
	VerifiedOwnerRef   string         `json:"verifiedOwnerRef"`
	PlanDigest         string         `json:"planDigest,omitempty"`
}

func NewAdoptionPlan added in v0.49.8 

func NewAdoptionPlan(contract Contract, source AdoptionSource, ownerRef string) (AdoptionPlan, error)

type AdoptionReceipt added in v0.49.8 

type AdoptionReceipt struct {
	SchemaVersion string                                        `json:"schemaVersion"`
	Result        AdoptionResult                                `json:"result"`
	Signature     localevidence.OwnerLifecycleMutationSignature `json:"signature"`
	Evidence      Evidence                                      `json:"evidence"`
}

type AdoptionResult added in v0.49.8 

type AdoptionResult struct {
	APIVersion         string         `json:"apiVersion"`
	Authority          Authority      `json:"authority"`
	WorkloadRef        string         `json:"workloadRef"`
	OperationID        string         `json:"operationId"`
	ProfileRef         string         `json:"profileRef"`
	Mode               string         `json:"mode"`
	PlanDigest         string         `json:"planDigest"`
	Source             AdoptionSource `json:"source"`
	OwnedFields        []string       `json:"ownedFields"`
	PreservedFields    []string       `json:"preservedFields"`
	AdmittedOperations []string       `json:"admittedOperations"`
	VerifiedOwnerRef   string         `json:"verifiedOwnerRef"`
	Status             string         `json:"status"`
	Action             string         `json:"action,omitempty"`
	PowerState         string         `json:"powerState,omitempty"`
	VerifiedAt         time.Time      `json:"verifiedAt"`
}

type AdoptionSource added in v0.49.8 

type AdoptionSource struct {
	ContainerID         string `json:"containerId"`
	ImageID             string `json:"imageId"`
	ImageDigest         string `json:"imageDigest"`
	Revision            string `json:"revision"`
	ConfigMount         string `json:"configMount"`
	ConfigurationDigest string `json:"configurationDigest"`
	AccountsDigest      string `json:"accountsDigest"`
}

AdoptionSource contains hashes of inspected configuration, never environment values or account material. Revision excludes changing runtime power state.

type ApplicationExperience 

type ApplicationExperience struct {
	SchemaVersion string `json:"schemaVersion"`
	WorkloadRef   string `json:"workloadRef"`
	PackageRef    string `json:"packageRef"`
	// LifecycleVersion identifies the version of the lifecycle contract used
	// for this projection. It is deliberately named so consumers do not read
	// it as the version of the deployed application artifact.
	LifecycleVersion string `json:"lifecycleVersion"`
	ServiceRef       string `json:"serviceRef,omitempty"`
	URL              string `json:"url,omitempty"`

	Installed   ExperienceAxis `json:"installed"`
	Reachable   ExperienceAxis `json:"reachable"`
	Setup       ExperienceAxis `json:"setup"`
	Usable      ExperienceAxis `json:"usable"`
	Recoverable ExperienceAxis `json:"recoverable"`

	NextActions []string                `json:"nextActions,omitempty"`
	SetupAction *ApplicationSetupAction `json:"setupAction,omitempty"`
}

ApplicationExperience is a derived user-facing view of one selected Application workload. It is not a second lifecycle state machine.

func ProjectExperience 

func ProjectExperience(input ExperienceInput) (ApplicationExperience, error)

ProjectExperience deterministically derives the five independent experience axes for one workload. It is intentionally conservative: healthy health evidence can establish the health of the bound probe target, but it cannot establish client-view route reachability, installation, runtime, setup completion, or usability. A staged restore result likewise never establishes application recovery until a typed activation receipt is validated by a caller.

type ApplicationSetupAction 

type ApplicationSetupAction struct {
	OperationRef                 string   `json:"operationRef"`
	WorkloadRef                  string   `json:"workloadRef"`
	Title                        string   `json:"title"`
	CredentialFields             []string `json:"credentialFields"`
	CredentialsFile              string   `json:"credentialsFile"`
	GuideURL                     string   `json:"guideUrl"`
	SupportsOnboardingCompletion bool     `json:"supportsOnboardingCompletion"`
}

ApplicationSetupAction points to the shared operation catalog. The CLI still re-admits the current Plan and exact runtime before any mutation.

type Authority 

type Authority struct {
	PlanHash              string `json:"planHash"`
	LifecycleContractHash string `json:"lifecycleContractHash"`
	LifecycleVersion      string `json:"lifecycleVersion"`
	PackageRef            string `json:"packageRef"`
}

type BeginRequest 

type BeginRequest struct {
	IntentDigest string
	ID           string
	Stage        string
	OperationRef string
	Now          time.Time
}

type Contract 

type Contract struct {
	WorkloadRef              string
	PackageRef               string
	Version                  string
	ContractHash             string
	PlanHash                 string
	Delivery                 DeliveryContract
	Stages                   map[string]StageContract
	Adoption                 *AdoptionContract
	AdoptionBaselinePlanHash string
}

func ContractFromResolvedPlan 

func ContractFromResolvedPlan(plan resolvedplan.ResolvedPlan, workloadRef string) (Contract, error)

ContractFromResolvedPlan returns the only lifecycle contract runtimes may consume. The selected application and package are read from the compiled, authority-bound projection.

func ContractsFromResolvedPlan 

func ContractsFromResolvedPlan(plan resolvedplan.ResolvedPlan) ([]Contract, error)

ContractsFromResolvedPlan returns the complete, deterministically ordered application lifecycle projection from one verified canonical ResolvedPlan.

type DeliveryCapabilities 

type DeliveryCapabilities struct {
	Deployment     bool
	RouteTLS       bool
	StatusEvidence bool
	BackupRestore  bool
}

DeliveryCapabilities is the compiler-bound support row for the exact runtime adapter selected by one Application workload. It is catalog authority, not live evidence. Backup/restore remains false until that adapter owns a complete executable lifecycle.

type DeliveryContract 

type DeliveryContract struct {
	Kind         string
	AdapterRef   string
	Capabilities *DeliveryCapabilities
}

type Evidence 

type Evidence struct {
	Kind   string `json:"kind"`
	Ref    string `json:"ref"`
	Digest string `json:"digest"`
}

Evidence is an immutable content-addressed proof produced by the operation named in the ResolvedPlan lifecycle contract. Ref is a local owner-custody path or another stable identifier; Digest always identifies its exact bytes.

type ExperienceAxis 

type ExperienceAxis struct {
	ActivationStatus string               `json:"activationStatus,omitempty"`
	Status           string               `json:"status"`
	Reason           string               `json:"reason,omitempty"`
	Freshness        string               `json:"freshness"`
	ObservedAt       time.Time            `json:"observedAt,omitempty"`
	Evidence         []ExperienceEvidence `json:"evidence,omitempty"`
}

ExperienceAxis is one independently evaluated application state axis. Status is intentionally explicit: missing or stale evidence is unverified, never silently promoted to ready.

type ExperienceEvidence 

type ExperienceEvidence struct {
	Kind   string `json:"kind"`
	Ref    string `json:"ref"`
	Digest string `json:"digest,omitempty"`
}

ExperienceEvidence is a secret-free pointer to the proof used for one axis. A reference without a digest remains explanatory evidence only and cannot turn an axis into a verified state by itself.

type ExperienceInput 

type ExperienceInput struct {
	RestoreActivation *RestoreActivationInput
	Contract          Contract
	State             State
	ServiceRef        string
	RouteRef          string
	URL               string
	HealthRef         string
	RuntimeTargets    []RuntimeTarget
	Setup             SetupInput
	Observations      []runtimeobservation.Observation
}

ExperienceInput contains only current-plan bindings and read-only evidence already accepted by the CLI. No function here performs runtime, network, or backup operations.

type Operation 

type Operation struct {
	ID             string     `json:"id"`
	Stage          string     `json:"stage"`
	OperationRef   string     `json:"operationRef"`
	Status         string     `json:"status"`
	Attempt        uint64     `json:"attempt"`
	StartedAt      time.Time  `json:"startedAt"`
	UpdatedAt      time.Time  `json:"updatedAt"`
	CompletedAt    time.Time  `json:"completedAt,omitempty"`
	Authority      Authority  `json:"authority"`
	Evidence       []Evidence `json:"evidence"`
	LastError      string     `json:"lastError,omitempty"`
	RecoveryRef    string     `json:"recoveryRef,omitempty"`
	PreviousDigest string     `json:"previousDigest,omitempty"`
	Digest         string     `json:"digest"`
	IntentDigest   string     `json:"intentDigest,omitempty"`
	Dispatched     bool       `json:"dispatched,omitempty"`
}

type RestoreActivationInput 

type RestoreActivationInput struct {
	OperationID string
	PlanHash    string
	Status      string
	Evidence    Evidence
	VerifiedAt  time.Time
}

RestoreActivationInput is a signed result already authenticated by the caller. It records runtime activation only; it cannot prove application-data readback.

type RuntimeTarget 

type RuntimeTarget struct {
	RequirementID string
	InstanceRef   string
}

RuntimeTarget binds a runtime observation requirement to the selected workload. Requirement and instance identities come from the verified Plan.

type SetupInput 

type SetupInput struct {
	PlanHash    string
	WorkloadRef string
	Policy      string
	ActionRefs  []string
	Runs        []SetupRun
}

SetupInput carries plan-declared setup actions and the currently observed setup records. The caller is responsible for selecting records by the exact workload identity from the current Plan.

type SetupResult 

type SetupResult struct {
	APIVersion         string    `json:"apiVersion"`
	Authority          Authority `json:"authority"`
	WorkloadRef        string    `json:"workloadRef"`
	OperationID        string    `json:"operationId"`
	ActionRef          string    `json:"actionRef"`
	ApplyResultHash    string    `json:"applyResultHash"`
	ArtifactDigest     string    `json:"artifactDigest"`
	InstanceRef        string    `json:"instanceRef"`
	ApplicationVersion string    `json:"applicationVersion"`
	AccountRef         string    `json:"accountRef"`
	Initialized        bool      `json:"initialized"`
	AdminLoginVerified bool      `json:"adminLoginVerified"`
	OnboardingComplete bool      `json:"onboardingComplete"`
	Preparation        string    `json:"preparation,omitempty"`
	EmailVerification  string    `json:"emailVerification,omitempty"`
	VerifiedAt         time.Time `json:"verifiedAt"`
}

SetupResult is a secret-free observation of the application API. It is evidence for the existing application lifecycle, not a second setup state.

type SetupRun 

type SetupRun struct {
	// Set by SetupRuns for current-authority operations, even before a terminal
	// setup receipt exists. Completion still requires authenticated evidence.
	PlanHash string

	WorkloadRef   string
	AppName       string
	DropName      string
	RunID         string
	Policy        string
	Status        string
	Phase         string
	Message       string
	Error         string
	Evidence      []ExperienceEvidence
	LastRequested time.Time
	LastStarted   time.Time
	LastFinished  time.Time
	// contains filtered or unexported fields
}

SetupRun is the secret-free setup state consumed by the derived projection. PlanHash is populated only for an operation whose lifecycle Authority exactly matches the current Plan. Legacy and prior-Plan records leave it empty and cannot affect the current setup axis.

type StageContract 

type StageContract struct {
	Name          string
	Operations    []string
	Phases        []string
	Evidence      []string
	Mutation      bool
	Destructive   bool
	OwnerApproval bool
}

type State 

type State struct {
	APIVersion       string      `json:"apiVersion"`
	WorkloadRef      string      `json:"workloadRef"`
	Authority        Authority   `json:"authority"`
	CurrentOperation string      `json:"currentOperation,omitempty"`
	Operations       []Operation `json:"operations"`
	UpdatedAt        time.Time   `json:"updatedAt"`
	StateDigest      string      `json:"stateDigest"`
}

type Store 

type Store struct {
	Workspace string
}

func (Store) AdoptionBinding added in v0.49.8 

func (store Store) AdoptionBinding(workload string) (AdoptionReceipt, bool, error)

AdoptionBinding derives membership from the existing lifecycle journal and verifies the Owner signature using local trusted custody. It also reads old authority receipts so changing the Plan cannot evade a preservation guard.

func (Store) Begin 

func (store Store) Begin(contract Contract, request BeginRequest) (State, error)

func (Store) Load 

func (store Store) Load(contract Contract) (State, error)

func (Store) MarkAdoptionDispatch added in v0.49.8 

func (store Store) MarkAdoptionDispatch(contract Contract, id, intent string) error

MarkAdoptionDispatch persists uncertainty before the only source side effect. A retry reconciles read-only; it may never send the action a second time.

func (Store) RequireNoAdoption added in v0.49.8 

func (store Store) RequireNoAdoption() error

func (Store) SaveAdoptionResult added in v0.49.8 

func (store Store) SaveAdoptionResult(contract Contract, result AdoptionResult) (AdoptionReceipt, error)

SaveAdoptionResult seals evidence before terminal journal publication. A membership consumer must accept this receipt, never a successful exit alone.

func (Store) SaveSetupResult 

func (store Store) SaveSetupResult(contract Contract, result SetupResult) (Evidence, error)

SaveSetupResult seals one result before the existing lifecycle operation becomes terminal. A crash may leave an unreferenced immutable receipt; a retry re-observes the app and can safely finalize the same operation.

func (Store) SetupRuns 

func (store Store) SetupRuns(contract Contract, applyResultHash, actionRef string) ([]SetupRun, error)

SetupRuns projects the existing journal. Only operations with the exact current lifecycle Authority enter the current setup axis. An operation may be current and failed/running without a terminal receipt; only a matching signed Apply-bound receipt gains a verified setup result.

func (Store) Transition 

func (store Store) Transition(contract Contract, request TransitionRequest) (State, error)

type TransitionRequest 

type TransitionRequest struct {
	ID          string
	Status      string
	Evidence    []Evidence
	LastError   string
	RecoveryRef string
	Now         time.Time
}

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.