README
¶
runtimeexecutor
runtimeexecutor/v1beta1 is the provider-neutral execution SPI for an already
authorized StackKits Architecture v2 Apply grant.
The control plane owns authorization, executor registration, retries, durable state, and product policy. This package only seals and validates the immutable grant projection, transports content-addressed artifact bytes without workspace paths, invokes one selected adapter safely, checks exact runtime and health outcomes, and derives a canonical result digest.
Runtime targets retain their exact site, node, workload, paired image ref and
immutable image digest, daemon, and
artifact references. Provider-owned runtimes additionally retain the exact
versioned owner adapter identity; module runtimes cannot carry that authority.
Workload targets using selected-paas must also retain one exact runtime
adapter binding: adapter ID, provider/module versions and contract hashes,
separate companion-agent module identities, and only the content-addressed
contract-handoff artifacts owned by those exact modules. Executable workload
artifacts and adapter handoffs are different execution classes and cannot be
substituted for one another. This proves the upstream Coolify/Komodo-style
selection without carrying an endpoint, credential, provider resource,
transport configuration, host permission, lease, or lifecycle operation.
Health targets retain both their materialized requirement ID and their logical
source contract ref, so a control plane never reconstructs one from the other.
Executable route Health additionally binds one exact runtime requirement, route,
backend pool, Site/node placement, and a closed address-free HTTP or TCP probe.
The probe can carry only protocol, port, bounded timeout, and the protocol's
fixed method/path/status policy; URL, host, redirect, credential, TLS identity,
and trust material are not representable. This lets the authenticated runtime
owner resolve and observe its own internal target without turning StackKits into
endpoint or network authority.
Optional Home access bindings retain only the exact StackKits requirement,
Site/capability/target-node scope, contract hashes, opaque external binding and
fabric refs, and a finite maximum-24-hour validity window. Every binding names
and is referenced by exactly one runtime requirement, carries a canonical
projection hash, participates in the sealed request digest, and is checked
against the actual invocation clock immediately before the adapter call. The
control plane must capture one UTC instant for authorization and call
InvokeAt with that same instant; the serialized authorization timestamp is
only a digest-bound consistency value and is never accepted as freshness proof
on its own. The
contract has no transport, endpoint, address, credential, provider
resource/account/region, discovery, lease, generation, or lifecycle field.
Optional Cloud backup-target bindings follow the same fail-closed envelope
without reusing Home access authority. They bind one exact runtime requirement,
Site, node set, offsite-object-backup capability and contract hash to opaque
target and custody-attestation refs. The shared projection has its own
content hash and maximum-24-hour validity window, is included in the sealed
request digest, and is rechecked against the actual InvokeAt instant before
the adapter runs. Buckets, endpoints, credentials, accounts, regions, provider
resources, leases, transports, backup-target lifecycle, and provider selection
are not representable.
Render-instance artifacts bind their exact provider,
module, unit, instance, logical output, site, and node identity and are
referenced exactly once. Plan-owned artifacts bind both owner reference and
owner contract hash to the exact plan digest and are never runtime-referenced.
Neither carries a workspace path. A daemon's
canonical absolute runtime socket is the only path-shaped contract value. The
verified result additionally binds the complete sealed request digest.
ExecutionChannelRequest and its factory/admission interfaces bind one opaque
channel to an exact single-Site/single-node Runtime+Health closure. A remote
admission can return its authenticated transport executor without constructing
local Operations; the shared contract still carries no endpoint, credential,
provider resource, lease, generation, discovery, or retry policy.
It intentionally contains no provider SDK/configuration, credentials, database, network transport, StackSpec type, workspace path, discovery, or policy.
Documentation
¶
Overview ¶
Package runtimeexecutor defines the provider-neutral v1beta1 contract for executing already-authorized governed runtime targets.
The package has no provider adapters, credentials, database, network, workspace paths, StackSpec types, or product policy. A control plane retains authorization and adapter-selection authority; this package validates the immutable execution envelope and the exact adapter outcome set.
Index ¶
- Constants
- func ComputeAccessBindingProjectionHash(input AccessBinding) (string, error)
- func ComputeArtifactSetHash(input []Artifact) (string, error)
- func ComputeBackupTargetBindingProjectionHash(input BackupTargetBinding) (string, error)
- type AccessBinding
- type AccessCapability
- type Artifact
- type BackupTargetBinding
- type DaemonTarget
- type Error
- type ErrorCode
- type ExecutionChannelAdmission
- type ExecutionChannelFactory
- type ExecutionChannelLocalExecutor
- type ExecutionChannelRequest
- type ExecutionOutcome
- type ExecutionRequest
- type ExecutionResult
- type Executor
- type ExecutorIdentity
- type HealthOutcome
- type HealthProbe
- type HealthStatus
- type HealthTarget
- type RuntimeAdapterAgentBinding
- type RuntimeAdapterBinding
- type RuntimeOutcome
- type RuntimeStatus
- type RuntimeTarget
Constants ¶
const ( MaxRuntimeTargets = 256 MaxHealthTargets = 256 MaxAccessBindings = 256 MaxBackupTargetBindings = 256 MaxArtifacts = 512 MaxArtifactBytes = 4 << 20 MaxTotalArtifactBytes = 32 << 20 MaxNodeRefsPerTarget = 128 MaxSiteRefsPerTarget = 128 MaxAdapterAgents = 128 )
Bounded envelope limits keep validation and hashing predictable.
const ( ArtifactExecutionClassExecutable = "executable" ArtifactExecutionClassContractHandoff = "contract-handoff" ArtifactExecutionClassPlan = "plan" )
Artifact execution classes separate executable runtime material from workload-scoped adapter handoffs and immutable plan metadata.
const APIVersion = "runtimeexecutor/v1beta1"
APIVersion is the closed runtime executor contract version.
const MaxAccessBindingValidity = 24 * time.Hour
MaxAccessBindingValidity bounds one externally issued admission receipt. It does not bound the lifetime of the externally managed access fabric; a fresh binding must be issued when a later Apply is authorized.
const MaxBackupTargetBindingValidity = 24 * time.Hour
MaxBackupTargetBindingValidity bounds one externally issued backup-target custody receipt. The backing target may outlive this receipt, but every execution must carry a fresh authorization envelope.
Variables ¶
This section is empty.
Functions ¶
func ComputeAccessBindingProjectionHash ¶
func ComputeAccessBindingProjectionHash(input AccessBinding) (string, error)
ComputeAccessBindingProjectionHash returns the canonical content address of the complete shared projection. BindingHash remains the upstream StackKits authority hash; ProjectionHash additionally binds the runtime owner and target-node projection used at this adapter boundary.
func ComputeArtifactSetHash ¶
ComputeArtifactSetHash validates artifacts and returns the canonical digest of their ordered metadata. Content is bound through each artifact digest.
func ComputeBackupTargetBindingProjectionHash ¶
func ComputeBackupTargetBindingProjectionHash(input BackupTargetBinding) (string, error)
ComputeBackupTargetBindingProjectionHash returns the canonical content address of the complete shared projection. BindingHash remains the upstream StackKits authority hash.
Types ¶
type AccessBinding ¶
type AccessBinding struct {
ID string `json:"id"`
Kind string `json:"kind"`
RuntimeRequirementID string `json:"runtime_requirement_id"`
StackID string `json:"stack_id"`
SiteRef string `json:"site_ref"`
CapabilityRef string `json:"capability_ref"`
ContractOwnerRef string `json:"contract_owner_ref"`
CapabilityContractHash string `json:"capability_contract_hash"`
TargetNodeRefs []string `json:"target_node_refs"`
RequirementsHash string `json:"requirements_hash"`
BindingRef string `json:"binding_ref"`
BindingHash string `json:"binding_hash"`
AccessFabricRef string `json:"access_fabric_ref"`
StackKitsVersion string `json:"stackkits_version"`
CandidateDigest string `json:"candidate_digest"`
SpecHash string `json:"spec_hash"`
IssuedAt string `json:"issued_at"`
ValidUntil string `json:"valid_until"`
ProjectionHash string `json:"projection_hash"`
}
AccessBinding is one exact, already-authorized Home access dependency for a governed runtime target. The shared contract carries only StackKits-owned requirement identity and opaque external binding identity. It deliberately has no transport, endpoint, address, credential, provider resource, account, region, discovery, lease, generation, or lifecycle field. Freshness is checked by Invoke immediately before the adapter call; no caller-supplied timestamp is accepted as proof of current validity.
type AccessCapability ¶
AccessCapability is the exact capability authority exposed by one runtime target for matching AccessBindings. It is separate from provider/module contracts because capability contracts are independently hash-bound by the StackKits catalog.
type Artifact ¶
type Artifact struct {
ID string `json:"id"`
Kind string `json:"kind"`
Format string `json:"format"`
Mode string `json:"mode"`
ExecutionClass string `json:"execution_class"`
OwnerKind string `json:"owner_kind"`
OwnerRef string `json:"owner_ref"`
OwnerContractHash string `json:"owner_contract_hash"`
ProviderRef string `json:"provider_ref,omitempty"`
ProviderContractHash string `json:"provider_contract_hash,omitempty"`
ModuleRef string `json:"module_ref,omitempty"`
ModuleContractHash string `json:"module_contract_hash,omitempty"`
UnitRef string `json:"unit_ref,omitempty"`
UnitContractHash string `json:"unit_contract_hash,omitempty"`
InstanceRef string `json:"instance_ref,omitempty"`
OutputRef string `json:"output_ref,omitempty"`
SiteRefs []string `json:"site_refs"`
NodeRefs []string `json:"node_refs"`
Digest string `json:"digest"`
Content []byte `json:"content"`
}
Artifact is an immutable content-addressed artifact snapshot. It deliberately contains no workspace or host path. Digest must match Content exactly.
type BackupTargetBinding ¶
type BackupTargetBinding struct {
ID string `json:"id"`
Kind string `json:"kind"`
RuntimeRequirementID string `json:"runtime_requirement_id"`
StackID string `json:"stack_id"`
SiteRef string `json:"site_ref"`
CapabilityRef string `json:"capability_ref"`
ContractOwnerRef string `json:"contract_owner_ref"`
CapabilityContractHash string `json:"capability_contract_hash"`
TargetNodeRefs []string `json:"target_node_refs"`
RequirementsHash string `json:"requirements_hash"`
BindingRef string `json:"binding_ref"`
BindingHash string `json:"binding_hash"`
BackupTargetRef string `json:"backup_target_ref"`
CustodyAttestationRef string `json:"custody_attestation_ref"`
StackKitsVersion string `json:"stackkits_version"`
CandidateDigest string `json:"candidate_digest"`
SpecHash string `json:"spec_hash"`
IssuedAt string `json:"issued_at"`
ValidUntil string `json:"valid_until"`
ProjectionHash string `json:"projection_hash"`
}
BackupTargetBinding is one exact, already-authorized Cloud backup-target dependency for a governed runtime target. It carries only StackKits-owned requirement identity plus opaque target and custody-attestation references. Provider, bucket, endpoint, credential, region, resource, lease, transport, generation, and lifecycle details are deliberately absent.
type DaemonTarget ¶
type DaemonTarget struct {
Ref string `json:"ref"`
InstanceRef string `json:"instance_ref"`
Engine string `json:"engine"`
SocketPath string `json:"socket_path"`
}
DaemonTarget is an exact plan-owned runtime daemon binding. SocketPath is the sole path-shaped value in this package; it names a runtime API socket, never a workspace artifact or credential file.
type ErrorCode ¶
type ErrorCode string
ErrorCode is a stable machine-readable runtimeexecutor failure class.
const ( ErrorInvalidRequest ErrorCode = "invalid_request" ErrorInvalidResult ErrorCode = "invalid_result" ErrorIdentityMismatch ErrorCode = "identity_mismatch" ErrorSetMismatch ErrorCode = "set_mismatch" ErrorCancelled ErrorCode = "cancelled" //nolint:misspell // Published error-code wire value. ErrorExecutorFailed ErrorCode = "executor_failed" ErrorExecutorPanic ErrorCode = "executor_panic" )
type ExecutionChannelAdmission ¶
type ExecutionChannelAdmission interface {
PrepareExecutionChannel(ExecutionChannelLocalExecutor) (Executor, error)
}
ExecutionChannelAdmission binds one already admitted scope to an executor. The implementation owns transport and authentication policy outside this DTO; it may return a remote executor without invoking local.
type ExecutionChannelFactory ¶
type ExecutionChannelFactory interface {
AdmitExecutionChannel(ExecutionChannelRequest) (ExecutionChannelAdmission, error)
}
ExecutionChannelFactory admits one exact Site/node/channel scope from service-owned configuration before any runtime owner is prepared.
type ExecutionChannelLocalExecutor ¶
ExecutionChannelLocalExecutor lazily constructs an in-process executor for the exact channel scope. A remote admission never needs to call it or possess the local Operations dependencies behind it.
type ExecutionChannelRequest ¶
type ExecutionChannelRequest struct {
ChannelRef string `json:"channel_ref"`
SiteRef string `json:"site_ref"`
NodeRef string `json:"node_ref"`
RuntimeTargets []RuntimeTarget `json:"runtime_targets"`
HealthTargets []HealthTarget `json:"health_targets"`
}
ExecutionChannelRequest is one exact provider-neutral routing scope already selected by the owning control plane. ChannelRef is opaque: it is not an endpoint, address, provider handle, credential, lease, or discovery grant.
func CloneExecutionChannelRequest ¶
func CloneExecutionChannelRequest(input ExecutionChannelRequest) ExecutionChannelRequest
CloneExecutionChannelRequest returns a defensive deep copy safe to cross a service-owned channel factory boundary.
func (ExecutionChannelRequest) Validate ¶
func (request ExecutionChannelRequest) Validate() error
Validate rejects a channel whose Runtime or Health closure escapes its exact Site, node, or opaque channel, or whose Health ownership is ambiguous.
type ExecutionOutcome ¶
type ExecutionOutcome struct {
Runtime []RuntimeOutcome `json:"runtime"`
Health []HealthOutcome `json:"health"`
}
ExecutionOutcome is the untrusted adapter return value. It contains no authority hashes or result digest; Invoke supplies and verifies those.
func CloneExecutionOutcome ¶
func CloneExecutionOutcome(input ExecutionOutcome) ExecutionOutcome
CloneExecutionOutcome returns a deep copy of an adapter outcome.
type ExecutionRequest ¶
type ExecutionRequest struct {
APIVersion string `json:"api_version"`
Executor ExecutorIdentity `json:"executor"`
PlanHash string `json:"plan_hash"`
ManifestHash string `json:"manifest_hash"`
GenerationReceiptHash string `json:"generation_receipt_hash"`
RequirementsHash string `json:"requirements_hash"`
EvidenceBundleHash string `json:"evidence_bundle_hash"`
AuthorizationTime string `json:"authorization_time,omitempty"`
ArtifactSetHash string `json:"artifact_set_hash"`
RuntimeTargets []RuntimeTarget `json:"runtime_targets"`
HealthTargets []HealthTarget `json:"health_targets"`
AccessBindings []AccessBinding `json:"access_bindings,omitempty"`
BackupTargetBindings []BackupTargetBinding `json:"backup_target_bindings,omitempty"`
Artifacts []Artifact `json:"artifacts"`
RequestDigest string `json:"request_digest"`
}
ExecutionRequest is the sealed, canonical input to an Executor. Its hashes bind the upstream plan, generated output, generation receipt, complete Apply requirements, authenticated evidence, and exact artifact set.
func CloneExecutionRequest ¶
func CloneExecutionRequest(input ExecutionRequest) ExecutionRequest
CloneExecutionRequest returns a deep copy safe to pass across an adapter boundary.
func SealRequest ¶
func SealRequest(input ExecutionRequest) (ExecutionRequest, error)
SealRequest returns a canonical defensive copy with derived artifact-set and request digests. The input is never mutated.
func (ExecutionRequest) Validate ¶
func (request ExecutionRequest) Validate() error
Validate rejects noncanonical, incomplete, substituted, or secret-bearing execution requests.
type ExecutionResult ¶
type ExecutionResult struct {
APIVersion string `json:"api_version"`
Executor ExecutorIdentity `json:"executor"`
PlanHash string `json:"plan_hash"`
ManifestHash string `json:"manifest_hash"`
GenerationReceiptHash string `json:"generation_receipt_hash"`
RequirementsHash string `json:"requirements_hash"`
EvidenceBundleHash string `json:"evidence_bundle_hash"`
ArtifactSetHash string `json:"artifact_set_hash"`
RequestDigest string `json:"request_digest"`
Runtime []RuntimeOutcome `json:"runtime"`
Health []HealthOutcome `json:"health"`
ResultDigest string `json:"result_digest"`
}
ExecutionResult is the immutable verified result projection returned by Invoke. ResultDigest binds every upstream hash, executor identity, artifact set, and exact outcome.
func CloneExecutionResult ¶
func CloneExecutionResult(input ExecutionResult) ExecutionResult
CloneExecutionResult returns a deep copy of a verified result.
func Invoke ¶
func Invoke(ctx context.Context, executor Executor, request ExecutionRequest) (ExecutionResult, error)
Invoke validates a sealed request, revalidates the selected executor identity, calls it with a defensive request copy, rejects cancellation and panics fail-closed, verifies the exact result set, and returns a digest-bound result. It performs no retry, persistence, provider selection, or I/O itself.
func InvokeAt ¶
func InvokeAt(ctx context.Context, executor Executor, request ExecutionRequest, at time.Time) (ExecutionResult, error)
InvokeAt is the deterministic clock-injected form of Invoke. Production callers use Invoke; tests and replay verification may supply an exact UTC instant. Freshness is checked immediately before the adapter call.
func (ExecutionResult) Validate ¶
func (result ExecutionResult) Validate() error
Validate checks a result's canonical digest and closed outcome vocabulary. Exact target-set matching is performed by Invoke against its request.
type Executor ¶
type Executor interface {
Identity() ExecutorIdentity
Execute(context.Context, ExecutionRequest) (ExecutionOutcome, error)
}
Executor is transport-neutral. The owning control plane selects an implementation and retains authorization, retries, and durable state.
type ExecutorIdentity ¶
type ExecutorIdentity struct {
ID string `json:"id"`
Version string `json:"version"`
Digest string `json:"digest"`
}
ExecutorIdentity is the immutable identity selected by the owning control plane. Digest is a canonical SHA-256 digest of the executable or adapter release, not a provider credential.
type HealthOutcome ¶
type HealthOutcome struct {
RequirementID string `json:"requirement_id"`
TargetRef string `json:"target_ref"`
Status HealthStatus `json:"status"`
ObservationRef string `json:"observation_ref"`
ObservationDigest string `json:"observation_digest"`
}
HealthOutcome is an opaque, digest-bound observation for one health target.
type HealthProbe ¶
type HealthProbe struct {
Protocol string `json:"protocol"`
Port int `json:"port"`
TimeoutSeconds int `json:"timeout_seconds"`
Method string `json:"method,omitempty"`
FollowRedirects bool `json:"follow_redirects,omitempty"`
Path string `json:"path,omitempty"`
ExpectedStatuses []int `json:"expected_statuses,omitempty"`
}
HealthProbe is a closed, address-free probe descriptor. The authenticated runtime owner resolves the target inside its exact execution channel; callers cannot provide a URL, host, credential, trust root, or redirect policy.
type HealthStatus ¶
type HealthStatus string
HealthStatus is the closed successful health outcome vocabulary.
const HealthStatusHealthy HealthStatus = "healthy"
HealthStatusHealthy means the exact health requirement passed.
type HealthTarget ¶
type HealthTarget struct {
RequirementID string `json:"requirement_id"`
RuntimeRequirementID string `json:"runtime_requirement_id,omitempty"`
SourceRef string `json:"source_ref"`
ContractHash string `json:"contract_hash"`
Phase string `json:"phase"`
Kind string `json:"kind"`
TargetKind string `json:"target_kind"`
TargetRef string `json:"target_ref"`
RouteRef string `json:"route_ref,omitempty"`
BackendPoolRef string `json:"backend_pool_ref,omitempty"`
Probe *HealthProbe `json:"probe,omitempty"`
SiteRefs []string `json:"site_refs"`
NodeRefs []string `json:"node_refs"`
}
HealthTarget is one exact post-execution health requirement.
type RuntimeAdapterAgentBinding ¶
type RuntimeAdapterAgentBinding struct {
ID string `json:"id"`
ModuleRef string `json:"module_ref"`
ModuleVersion string `json:"module_version"`
ModuleContractHash string `json:"module_contract_hash"`
ArtifactRefs []string `json:"artifact_refs"`
}
RuntimeAdapterAgentBinding binds one adapter-owned companion agent module and its exact contract-handoff artifacts. It carries authority identity only; endpoints, credentials, host access, provider lifecycle, and transport configuration remain in the selected executor's custody.
type RuntimeAdapterBinding ¶
type RuntimeAdapterBinding struct {
ID string `json:"id"`
ProviderRef string `json:"provider_ref"`
ProviderVersion string `json:"provider_version"`
ProviderContractHash string `json:"provider_contract_hash"`
ModuleRef string `json:"module_ref"`
ModuleVersion string `json:"module_version"`
ModuleContractHash string `json:"module_contract_hash"`
ArtifactRefs []string `json:"artifact_refs"`
Agents []RuntimeAdapterAgentBinding `json:"agents,omitempty"`
}
RuntimeAdapterBinding is the exact workload-scoped adapter authority chosen by the upstream plan. Provider/module versions and hashes bind that choice; ArtifactRefs bind only provider-neutral, content-addressed handoff material. Agents are separately named so a control-plane adapter cannot silently widen itself into node-agent authority.
type RuntimeOutcome ¶
type RuntimeOutcome struct {
RequirementID string `json:"requirement_id"`
InstanceRef string `json:"instance_ref"`
Status RuntimeStatus `json:"status"`
ObservationRef string `json:"observation_ref"`
ObservationDigest string `json:"observation_digest"`
}
RuntimeOutcome is an opaque, digest-bound observation for one runtime target.
type RuntimeStatus ¶
type RuntimeStatus string
RuntimeStatus is the closed successful runtime outcome vocabulary.
const RuntimeStatusApplied RuntimeStatus = "applied"
RuntimeStatusApplied means the exact governed instance was applied.
type RuntimeTarget ¶
type RuntimeTarget struct {
RequirementID string `json:"requirement_id"`
OwnerKind string `json:"owner_kind"`
OwnerRef string `json:"owner_ref"`
OwnerVersion string `json:"owner_version,omitempty"`
OwnerContractHash string `json:"owner_contract_hash"`
ProviderRef string `json:"provider_ref"`
ProviderContractHash string `json:"provider_contract_hash"`
ModuleRef string `json:"module_ref,omitempty"`
ModuleContractHash string `json:"module_contract_hash,omitempty"`
UnitRef string `json:"unit_ref,omitempty"`
UnitContractHash string `json:"unit_contract_hash,omitempty"`
RuntimeKind string `json:"runtime_kind"`
RuntimeDelivery string `json:"runtime_delivery"`
RuntimeEngine string `json:"runtime_engine,omitempty"`
InstanceRef string `json:"instance_ref"`
ExecutionChannelRef string `json:"execution_channel_ref,omitempty"`
SiteRefs []string `json:"site_refs"`
NodeRefs []string `json:"node_refs"`
WorkloadRef string `json:"workload_ref,omitempty"`
ImageRef string `json:"image_ref,omitempty"`
ImageDigest string `json:"image_digest,omitempty"`
DaemonBindings []DaemonTarget `json:"daemon_bindings"`
ArtifactRefs []string `json:"artifact_refs"`
RuntimeAdapter *RuntimeAdapterBinding `json:"runtime_adapter,omitempty"`
AccessCapabilities []AccessCapability `json:"access_capabilities,omitempty"`
AccessBindingRefs []string `json:"access_binding_refs,omitempty"`
BackupTargetCapabilities []AccessCapability `json:"backup_target_capabilities,omitempty"`
BackupTargetBindingRefs []string `json:"backup_target_binding_refs,omitempty"`
}
RuntimeTarget is one exact governed runtime instance. Contract hashes bind every authority level involved in selecting it. Module and unit pairs may be absent only when the corresponding authority level is not used. ExecutionChannelRef is an opaque, already-authorized routing identity. It is never an endpoint, address, provider reference, credential, or permission to discover a target.
Source Files