Documentation
¶
Overview ¶
Package execution composes bounded, process-local admission with the existing shared inference runner. Providers, broker credentials and optional telemetry are explicit dependencies; this package discovers no environment settings and never retries generation or selects another provider.
Index ¶
Constants ¶
const MaxSpecBytes = 1 << 20
Variables ¶
var ( ErrConfiguration = errors.New("execution_configuration_invalid") ErrClosed = errors.New("execution_coordinator_closed") ErrHostedDisabled = errors.New("execution_hosted_provider_disabled") )
var ErrInvalidSpec = errors.New("execution_spec_invalid")
ErrInvalidSpec deliberately omits reader errors, field names and task content.
Functions ¶
func LoadSpec ¶
LoadSpec reads one approved task snapshot, bounded by MaxSpecBytes. Field names are exact JSON names; unknown or duplicate keys, null values, trailing data, malformed UTF-8 and nesting beyond 32 levels are rejected. All errors are controlled and contain no task content. Loading performs no network call.
Types ¶
type Config ¶
type Config struct {
Runner inference.Runner
Admission admission.Config
Source admission.Source
Exporter observability.Exporter
// ExportTimeout is additional to the runner's task deadline, so cancelled
// generation can still export its outcome. Zero => 2s; explicit 1ms..5s.
ExportTimeout time.Duration
// AllowHosted is false by default. When false, both the spec and the provider's
// optional inference.SelfHostedProvider assertion must declare self-hosting.
// Assertions are trusted caller configuration, not proof of a zero invoice.
AllowHosted bool
}
Config holds one process's coordinator. A zero Admission uses the existing admission defaults, including one inference worker. Source defaults to the native system probe. Custom providers/sources/exporters must be concurrency safe and honor contexts. Per-lane reservations remain estimates, not OS limits.
type Coordinator ¶
type Coordinator struct {
// contains filtered or unexported fields
}
Coordinator owns one bounded queue and no completed-result cache. Durable claims/results belong to Runner.Broker. Separate coordinators and hosts do not share resource reservations, even when their broker scope is the same.
func New ¶
func New(lifecycle context.Context, cfg Config) (*Coordinator, error)
New starts the sampler under lifecycle. It performs no model call or broker access. Admission initially pauses until fresh recovery samples establish headroom; Run returns admission.ErrPaused during warm-up or pressure. It does not hold unbounded requests outside the queue while waiting for recovery.
func (*Coordinator) Close ¶
func (c *Coordinator) Close(ctx context.Context) error
Close stops admission, cancels queued and active calls, and waits for the sampler and admitted calls. A deadline returns while a noncooperating callback remains counted; it never opens a replacement slot. Repeated Close is safe.
func (*Coordinator) Run ¶
Run freezes the approved spec, admits the whole runner call once and awaits its outcome. Even result lookups use this process's inference lane. There is no automatic wait/retry after admission rejection or ErrInFlight. The caller must not mutate a spec concurrently while Run copies it.
Cancellation removes queued work or cancels an active provider. Active capacity remains held until the executor returns; custom dependencies must honor contexts. The returned error and partial result preserve Runner semantics.
func (*Coordinator) Status ¶
func (c *Coordinator) Status() admission.Status
Status reports the existing process-local admission state without task data.
type Result ¶
type Result struct {
inference.Result
Telemetry TelemetryResult `json:"telemetry"`
}
Result preserves the runner's result, including a nondurable partial answer on error. Complete and Durable are protocol evidence, not quality checks or human acceptance. Inspect Run's error before using any returned answer.
type TelemetryResult ¶
type TelemetryResult struct {
Status string `json:"status"` // disabled, not_attempted, acknowledged, unconfirmed, invalid_metadata
Receipt *observability.Receipt `json:"receipt,omitempty"`
Error error `json:"-"`
}
TelemetryResult is independent of task success. Error is never serialized; status and span IDs can be recorded without including backend error text. Export failure never changes Run's error or authorizes another generation.
Source Files