Module run_task 

Single-task lifecycle: cache lookup, hit-path restoration, or miss-path spawn-and-capture with success-only store.

run_task is the async entry point. It does no scheduling, no cap accounting, no mutex acquisition, no cancellation, and emits no presentation-layer bytes itself: captured streams flow to the caller through the RunObserver trait. Concrete observer implementations distinguish the two EXEC-016 modes: live (per-line [project:task] -tag-prefixed writes to a shared parent sink) and buffered (one contiguous block per stream on task completion).

The function composes the cache-key derivation (crate::cache_key::build_cache_key) with the crate::process::ProcessSpawner trait into the executor’s smallest end-to-end unit. A scheduler layer combines many run_task calls with the workspace’s concurrency caps and mutex hold-set (EXEC-004..007).

Spec coverage

• EXEC-007 step 1 – key derivation and lookup precede every other concern. Mutex acquisition is not implemented by this function; that responsibility belongs to a scheduler layer.
• EXEC-007 step 2 – cache-hit restoration runs mutex-free.
• EXEC-009 – terminal classification: zero exit is RunState::Succeeded; non-zero or signalled is RunState::Failed. A cache hit is RunState::Succeeded. The cancelled state of EXEC-009’s third option is not reachable from this function: cancellation is not implemented here.
• EXEC-016 – the full stdout and stderr byte streams of every fresh run are captured (the cache stores them per CACHE-012) and surfaced through RunObserver.
• EXEC-017 – on a cache hit, the recorded stdout and stderr flow through RunObserver with the same mode-agnostic signal as a fresh run.
• CACHE-008 (runtime) – the spawned process sees only the effective env: allow-listed host values plus task-level overrides, override wins on collision. The spawn-plan builder assembles that env vector; the std backend’s env_clear() ensures the child sees this set and nothing else.
• CACHE-014..016 – haz_cache::Cache::lookup folds every failure into a clean miss, so no RunTaskError variant covers it.
• CACHE-017..018 – the cache store fires only when the fresh run’s exit status was zero. The store call itself surfaces as RunTaskError::StoreFailed.
• CACHE-019 – restoration uses haz_cache::Cache::restore, surfacing haz_cache::RestoredStreams through the observer.

Out of scope for this function

• Concurrency caps (EXEC-004..006) and the canonical-order tie-breaking of EXEC-003: scheduler-level concerns.
• Mutex acquisition (EXEC-007 step 3) and EXEC-006 condition 3: scheduler-level concerns.
• Failure cascade and the skipped state (EXEC-009..011): scheduler-level concerns.
• Cancellation (EXEC-012..015): not implemented in this function.
• Live-mode per-line tag prefixing and atomic sink writes (EXEC-016 presentation): implemented inside concrete RunObserver types.
• Runtime cycle (EXEC-019) and output-overlap (EXEC-020) detection: scheduler-level concerns.

Structs

CompletedRecord

Run-record fields produced by one run_task invocation: the observation of a task that the scheduler admitted into the lookup-then-spawn pipeline and that reached a run classification (EXEC-009).

RunContext

Borrowed bundle of long-lived state that every run_task invocation in a given haz run shares.

SkipRecord

Record of a task that the scheduler cascade-skipped because an upstream task failed (EXEC-010 / EXEC-011).

TaskLookup

Run one task per its workspace declaration, cache-aware.

Enums

CancelledRecord

Record of a task that ended in the executor-initiated cancelled state per EXEC-009 / EXEC-013.

CapturedStream

Which of the two captured byte streams a RunTaskError::CapturedStreamReadFailed refers to.

RunOutcome

Terminal state of one task in a crate::run_graph invocation.

RunSource

Where a CompletedRecord’s success came from.

RunState

Terminal classification of a single-task run per EXEC-009.

RunTaskError

Failure modes of run_task.

SkipCause

Reason a task was cascade-skipped per EXEC-011.

Traits

RunObserver

Observation surface for one run_task invocation.

Functions

cache_lookup_phase

EXEC-007 step 1 of the single-task lifecycle: resolve the bearing project + task, derive the cache key, and consult the cache. No mutex hold is taken; no observer event fires.

restore_from_hit

Cache-hit branch: restore the manifest’s outputs, emit the recorded streams to the observer, and build the matching CompletedRecord (EXEC-007 step 2, EXEC-017, CACHE-019).

run_fresh

Cache-miss branch (EXEC-007 step 3, compatible mutex path): spawn the task’s command, capture both streams, classify per EXEC-009, and on success persist the run to the cache.

run_task

Single-task lifecycle entry point: composes cache_lookup_phase, restore_from_hit, and run_fresh without any mutex orchestration.