Run outcome model (developer notes)

Authority: All execution-truth rules (statuses, precedence, loaders, group projection) live in docs/run_outcome_contract.md. This guide collects implementation pointers for contributors; it does not define contract rules.

Where to look in code

Concern

Module / symbol

Status projection

run_outcome_truth.py

Typed loaders

load_run_results, load_run_outcome_context

Schema gate (schema_version >= 2)

assert_run_results_schema_supported in module_outcomes

Group rollups

project_group_outcomes(...)

Group phase metadata

load_group_phase_metadata(...) (file: aggregation_warnings.json today)

Incomplete run dirs (Diagnostics)

incomplete_runs.list_incomplete_run_dirs — read-only inventory of run directories missing run_results.json. Does not consult processing_state.json and does not delete anything.

Operator-only heuristics

Reporting or discovery code may infer hints from file presence when run_results.json is missing. Those heuristics are not canonical execution truth — they assist operators only. Canonical status always comes from typed loaders over run_results.json (see the contract).

Diagnostics → Incomplete analysis runs lists those directories so an operator can re-run or inspect a folder after a crash or refresh. Presence on that list is not a run status.

Decision log anchors

When semantics are ambiguous during implementation, log explicit decisions for:

  • blocked vs skipped precedence

  • cache-hit interpretation

  • partial run_results with manifest present

  • group/member status rollups

Resolve ambiguities by updating docs/run_outcome_contract.md first, then adjust code and this guide.