README
¶
Portable execution model
Demand is the versioned full requirement snapshot used in submission metadata
and the client-owned c2j.execution payload namespace. Inspect selects the
latest yielded snapshot over the submission hint and labels unresolved,
specified, unspecified, malformed, and unsupported state. Snapshot changes are
published only with a JobDB yield; there is no live read-projection service.
LastAllocation describes the publishing handoff, not a currently running lease.
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. The compiler and
executionruntime wire this model to JobDB's
independent client payload and explicit workflow yield. 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 ¶
func ParsePackage ¶ added in v0.0.64
ParsePackage validates only local syntax. Resolution is deferred until use.
func PayloadWithDemand ¶ added in v0.0.52
func PayloadWithDemand(raw json.RawMessage, d Demand) (json.RawMessage, error)
PayloadWithDemand replaces just the execution snapshot, preserving all other client JSON. The caller publishes it with an observed-revision checked reset.
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 Demand ¶ added in v0.0.52
type Demand struct {
SchemaVersion int `json:"schema_version"`
RecipeResolution string `json:"recipe_resolution"`
RecipeDigest string `json:"recipe_digest,omitempty"`
RecipeBase *Requirements `json:"recipe_base,omitempty"`
// NodeRequirements is the lexical overlay at the last scheduling boundary.
// Non-nil (even empty) enables task-frontier checks instead of root preflight.
NodeRequirements *Requirements `json:"node_requirements,omitempty"`
JobRequirements Requirements `json:"job_requirements"`
Effective Requirements `json:"effective"`
Revision uint64 `json:"revision"`
Checkpoints map[string]string `json:"checkpoints,omitempty"`
LastAllocation *Allocation `json:"last_handoff_allocation,omitempty"`
}
Demand is a complete snapshot. Only a yield publishes a runtime change.
func DecodeDemand ¶ added in v0.0.52
func DecodeDemand(raw json.RawMessage) (*Demand, error)
func Initial ¶ added in v0.0.52
func Initial(base *Requirements, digest string, overrides Requirements) (Demand, error)
func PayloadDemand ¶ added in v0.0.52
func PayloadDemand(raw json.RawMessage) (*Demand, error)
PayloadDemand interprets only the reserved client-owned namespace. Other namespaces remain opaque, including JSON numbers not representable as floats.
type Filter ¶ added in v0.0.52
type Filter struct {
Allocation Allocation `json:"allocation"`
IncludeUnresolved bool `json:"include_unresolved"`
}
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 {
Packages []string `json:"packages,omitempty" yaml:"packages,omitempty"`
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) MarshalYAML ¶ added in v0.0.52
func (r Requirements) MarshalYAML() (any, error)
MarshalYAML makes programmatically constructed and parsed declarations share the same representation, including when hashing a pinned recipe.
func (Requirements) Normalize ¶
func (r Requirements) Normalize() (Requirements, error)
Normalize validates all supplied fields and returns canonical values.
func (*Requirements) UnmarshalYAML ¶ added in v0.0.52
func (r *Requirements) UnmarshalYAML(node *yaml.Node) error
type UnsupportedVersionError ¶ added in v0.0.52
type UnsupportedVersionError struct{ Version int }
func (*UnsupportedVersionError) Error ¶ added in v0.0.52
func (e *UnsupportedVersionError) Error() string
type View ¶ added in v0.0.52
type View struct {
Status string `json:"status"`
Source string `json:"source"`
Published bool `json:"published"`
Demand *Demand `json:"demand,omitempty"`
Initial *Demand `json:"initial,omitempty"`
Diagnostic string `json:"diagnostic,omitempty"`
}
func Inspect ¶ added in v0.0.52
func Inspect(metadata, payload json.RawMessage) View
Inspect never resolves recipes or reads history. Missing metadata remains unknown, even if a compatible executor has since resolved the recipe.
Source Files