executionruntime

README

Execution-aware JobDB runtime

Wrap a persistent JobDB runtime with executionruntime.New(runtime, allocation, onHandoff). Pass the same normalized allocation and callback to compiler.RecipeJobWorkerOptions, with StageExecution: wrapped.Stage and WrapTaskWorker: wrapped.WrapTaskWorker, and build the engine using the wrapped runtime. Register schemas using the original runtime. The CLI performs this wiring for all execution entry points.

The adapter checks current published demand at lease admission, including task-only leases. An incompatible lease is rescheduled with the same route and task coordinates, without rewriting the snapshot. Recipe preflight separately resolves and checks the pinned base when no snapshot has been published.

For recipes using execution_needs, recipe leases replay first: an older published scope may belong to completed work. The compiler stages the inherited needs before each task call, and guarded task workers check them only after JobDB has decided the task is unfinished. Completed results bypass the worker and do not request historical environments. This also applies when recovery starts through a task route: its saved task may already have completed before the executor crashed. The next genuinely unfinished task is checked instead.

If building a workset manually, wrap every task worker with WrapTaskWorker and supply that same function in the recipe worker options. This is required for scoped needs; staging alone cannot enforce a live-task boundary.

Node scopes are ephemeral. Any subsequent ordinary reschedule publishes the staged scope if it differs from the saved snapshot, without mutating permanent job overrides. Explicit job requirements still override recipe and node declarations. No live scheduler updates or automatic downsizing are performed.

The compiler stages resolved demand so ordinary task/time reschedules can publish it if needed. An explicit requirement change is a full revision-checked snapshot on yield. The adapter preserves lease token/worker identity forwarding needed for chapter persistence; it does not add lease matching or provisioning.

Stop or redirect an incompatible worker after OnHandoff to avoid a tight reacquisition loop. The event is a handoff, not completion. Admission errors stop keepalive for rejected leases; ordinary lease-expiry recovery applies.

Use ops.SuspendExecution at a successful durable activity boundary to request a change. Read-only replay must use ReadOnlyReplay: true and must not publish. See the design and user guide for lifecycle and failure semantics.

Supplied leases

Runtime.RunWithLease(ctx, lease, request, listener) uses JobDB's supplied-lease runner and performs allocation admission after authoritative validation/renewal. It never calls acquisition APIs. Keep the same StageExecution, WrapTaskWorker, allocation, and callback wiring described above. The method returns after one lease lifecycle, including a normal reschedule or handoff.

Renewable lease wrappers retain shared invocation state across refreshed snapshots, so a heartbeat cannot drop staged requirements before rescheduling. They forward current token, owner, expiry, and schema metadata. See the run-with-lease guide for usage and deployment details.

Documentation

Overview

Package executionruntime fences actual executor compatibility at lease entry and carries resolved demand through ordinary workflow reschedules. It does not change JobDB's lease selection or add a separate persistence store.

Index

• type Runtime
  • func New(runtime jobdb.WorkflowRuntime, allocation execution.Allocation, ...) *Runtime
  • func (r *Runtime) GetJobLease(ctx context.Context, req jobdb.GetJobLeaseRequest) (jobdb.ExecutionLease, error)
  • func (r *Runtime) PollWork(ctx context.Context, req jobdb.PollWorkRequest) ([]jobdb.ExecutionLease, error)
  • func (r *Runtime) RunWithLease(ctx context.Context, supplied jobdb.ExecutionLease, ...) (jobworkflow.JobRunOutcome, error)
  • func (r *Runtime) Stage(key jobdb.JobKey, demand execution.Demand)
  • func (r *Runtime) WrapTaskWorker(worker jobworkflow.TaskWorker) jobworkflow.TaskWorker

Types

type Runtime

type Runtime struct {
	jobdb.WorkflowRuntime
	Allocation execution.Allocation
	OnHandoff  func(compiler.ExecutionHandoff)
	// contains filtered or unexported fields
}

func New

func New(runtime jobdb.WorkflowRuntime, allocation execution.Allocation, handoff func(compiler.ExecutionHandoff)) *Runtime

func (*Runtime) GetJobLease

func (r *Runtime) GetJobLease(ctx context.Context, req jobdb.GetJobLeaseRequest) (jobdb.ExecutionLease, error)

func (*Runtime) PollWork

func (r *Runtime) PollWork(ctx context.Context, req jobdb.PollWorkRequest) ([]jobdb.ExecutionLease, error)

func (*Runtime) RunWithLease

func (r *Runtime) RunWithLease(ctx context.Context, supplied jobdb.ExecutionLease, req jobworkflow.GetJobForRunRequest, listener jobworkflow.JobRunListener) (jobworkflow.JobRunOutcome, error)

RunWithLease executes exactly one supplied lease using JobDB's shared runner. It validates and renews before allocation admission or application work, and never acquires replacement work. Configure the recipe worker with this runtime's Stage and WrapTaskWorker, as for ordinary claim-and-run execution. BeforeRun, when provided, runs after successful allocation admission under the same renewing lease. WorkerID should normally be left empty to retain the supplied lease's owner.

func (*Runtime) Stage

func (r *Runtime) Stage(key jobdb.JobKey, demand execution.Demand)

func (*Runtime) WrapTaskWorker

func (r *Runtime) WrapTaskWorker(worker jobworkflow.TaskWorker) jobworkflow.TaskWorker

WrapTaskWorker checks needs only when JobDB actually invokes a task worker, after looking up completed results. Use it for every worker in the workset.