httk.workflow.executors

Define runner-executor contracts used by the workflow manager.

Classes

AttemptLaunch

Paths and context needed to construct an attempt command.

OutcomeCommit

Describe a published outcome being committed by the authoritative manager.

RunnerExecutor

Execution behavior selected by runner.executor in job.json.

PathRunnerExecutor

Execute the runner path directly from the payload or shared store.

Module Contents

class httk.workflow.executors.AttemptLaunch

Paths and context needed to construct an attempt command.

runner is the executable the manager resolved for this attempt. A payload runner is the file inside payload; a shared file runner is the verified /dev/fd/N alias and a shared tree runner is its verified entry at the original source path.

Parameters:

  • job – Immutable job definition being attempted.

  • marker – Authoritative marker for the attempt.

  • payload – Immutable job payload directory.

  • workdir – Directory in which the runner executes.

  • control – Attempt-control directory.

  • context – Runner context members.

  • runner – Resolved executable, or no value to use the payload runner.

  • workflow_prelude – Shell text run in a login shell before the runner, or empty for none.

job: httk.workflow.models.JobDefinition
marker: httk.workflow.models.Marker
payload: pathlib.Path
workdir: pathlib.Path
control: pathlib.Path
context: collections.abc.Mapping[str, Any]
runner: pathlib.Path | None = None
workflow_prelude: str = ''
property runner_command: pathlib.Path

Return the executable to run, defaulting to the payload runner.

class httk.workflow.executors.OutcomeCommit

Describe a published outcome being committed by the authoritative manager.

Parameters:

  • job – Immutable job definition producing the outcome.

  • marker – Authoritative marker being committed.

  • payload – Immutable job payload directory.

  • outcome_path – Path of the published outcome.

  • outcome – Outcome members.

job: httk.workflow.models.JobDefinition
marker: httk.workflow.models.Marker
payload: pathlib.Path
outcome_path: pathlib.Path
outcome: collections.abc.Mapping[str, Any]
class httk.workflow.executors.RunnerExecutor

Bases: Protocol

Execution behavior selected by runner.executor in job.json.

name: str
validate(job, payload)

Validate executor-specific immutable payload requirements.

abstractmethod command(launch)

Return the command argument vector for one attempt.

commit_outcome(commit)

Complete executor-specific idempotent work before the marker advances.

reconcile(workspace)

Repair executor-specific derived views; never alter authoritative state.

marker_changed(workspace, marker)

Refresh derived views after an authoritative marker transition.

class httk.workflow.executors.PathRunnerExecutor

Execute the runner path directly from the payload or shared store.

name = 'path'
validate(job, payload)

Validate the payload runner when the job runs one.

Parameters:

  • job (httk.workflow.models.JobDefinition) – Job definition whose runner is checked.

  • payload (pathlib.Path) – Immutable job payload directory.

Returns:

None.

Raises:

httk.workflow.errors.FormatError – If a payload runner is missing or not a file.

Return type:

None

command(launch)

Build the command for one path-runner attempt.

When the launch carries a workflow prelude, the runner is wrapped in a login shell that runs the prelude (under set -e) then execs the runner, so a failing prelude line aborts before the runner starts and the runner inherits the initialized environment.

Parameters:

launch (AttemptLaunch) – Attempt paths and runner context.

Returns:

Argument vector for the runner process.

Return type:

collections.abc.Sequence[str]

commit_outcome(commit)

Complete path-executor outcome work before the marker advances.

Parameters:

commit (OutcomeCommit) – Published outcome and its job context.

Returns:

None.

Return type:

None

reconcile(workspace)

Reconcile path-executor derived state.

Parameters:

workspace (httk.workflow.workspace.Workspace) – Workspace whose derived state is reconciled.

Returns:

None.

Return type:

None

marker_changed(workspace, marker)

Refresh path-executor state after a marker transition.

Parameters:

  • workspace (httk.workflow.workspace.Workspace) – Workspace containing the changed marker.

  • marker (httk.workflow.models.Marker) – Newly authoritative marker.

Returns:

None.

Return type:

None