README
¶
Portable execution model
This package implements the shared value model for portable execution requirements. It does not provision environments, change JobDB lease matching, or enable recipe execution handoff by itself. JobDB now provides independent client payload and explicit workflow yield, and c2j's context wrappers support them; the execution-requirements feature itself remains unintegrated. See the upgrade notes for the current client-payload and typed-route contract, and the design for feature intent.
Requirements uses optional string pointers for image, platform, CPU, memory,
and ephemeral storage. Normalize validates and canonicalizes supplied values.
Overlay(base, patch) copies fields, with supplied patch fields replacing the
base, including lower resource minima. Normalize each input before overlaying:
empty, zero, and negative values are errors, not requests to clear a field.
CPU accepts cores or millicores at integral millicore precision. Memory/storage
accept SI (k, M, G, T, P, E) or IEC (Ki through Ei) units and must
resolve to integral bytes. Scalars must fit signed 64-bit integers. Kubernetes
quantity parsing is checked for rounding and overflow; quantities are never
silently rounded down or capped. Canonical byte values always retain a unit
(one byte is 0.001k). Platforms use os/architecture[/variant], normalized to
lowercase; a requirement without a variant accepts any variant of that same
OS/architecture.
Allocation version 1 describes actual simultaneous usable capacity, injected
by a trusted provisioner. It must not be inferred from recipe requests, host
capacity, or a previous attempt. Its image has three independent fields:
reference: normalized launch reference/tag.manifest_digest: actual resolved OCI manifest digest.image_id: diagnostic runtime/config identity; never used as a manifest digest.
Compare(requirements, allocation) validates both operands and returns
structured mismatches. Unknown allocation fields cannot satisfy explicit
requirements. Resources use minimum-capacity comparisons; image tags match
launch references, and pinned images require the actual manifest digest.
A pinned launch reference alone is not proof of the actual manifest. Empty
requirements are compatible with unknown allocation. Compatibility is not a
lease, resource reservation, or readiness guarantee.
Run package tests with go test ./pkg/execution.
Documentation
¶
Overview ¶
Package execution defines portable demands and actual executor allocations. It has no scheduler dependencies and never treats a request as an allocation.
Index ¶
Constants ¶
const SchemaVersion = 1
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Allocation ¶
type Allocation struct {
SchemaVersion int `json:"schema_version"`
Image Image `json:"image,omitempty"`
Platform *string `json:"platform,omitempty"`
Resources Resources `json:"resources,omitempty"`
}
Allocation contains simultaneous usable capacities reported by the trusted provisioner, not requested limits or capacities discovered from the host.
func (Allocation) HasCompatibilityFacts ¶
func (a Allocation) HasCompatibilityFacts() bool
HasCompatibilityFacts excludes image IDs, which are diagnostic only.
func (Allocation) Normalize ¶
func (a Allocation) Normalize() (Allocation, error)
type Mismatch ¶
type Mismatch struct {
Field string `json:"field"`
Required string `json:"required"`
Allocated string `json:"allocated,omitempty"`
Reason string `json:"reason"`
}
func Compare ¶
func Compare(required Requirements, allocated Allocation) ([]Mismatch, error)
Compare validates both operands. A nil error with no mismatches proves compatibility only with this supplied allocation, never lease readiness.
type Requirements ¶
type Requirements struct {
Image *string `json:"image,omitempty" yaml:"image,omitempty"`
Platform *string `json:"platform,omitempty" yaml:"platform,omitempty"`
Resources Resources `json:"resources,omitempty" yaml:"resources,omitempty"`
}
Requirements is also the partial override format: nil preserves the base property. Explicit empty values are invalid; version 1 does not support clear.
func Overlay ¶
func Overlay(base, override Requirements) Requirements
Overlay returns an independent copy; callers cannot mutate either input via the returned pointers. Validate patches before overlaying them.
func (Requirements) Empty ¶
func (r Requirements) Empty() bool
func (Requirements) Normalize ¶
func (r Requirements) Normalize() (Requirements, error)
Normalize validates all supplied fields and returns canonical values.
Source Files