Module refine_plan 

SRD-77 refine plan — pre-computed skip set + next-execution id, derived from a session’s prior phase_outcomes rows. The runner builds one when nmbrs refine re-attaches to an existing session; the executor’s phase-walk gate checks it before dispatching each phase’s per-cycle work. SRD-77 refine: the per-execution skip plan.

When nmbrs refine re-attaches to an existing session, it reads the session’s phase_outcomes table and builds a [RefinePlan] — the set of (phase_name, phase_labels) pairs that have already completed across any prior execution, plus the next execution id to record outcomes under.

The plan rides on the executor context (ExecCtx::refine_plan) and the phase-walk gate checks each phase against [is_completed] before dispatching run_phase. Skipped phases still get their scene-tree node pushed (so the TUI / progress display shows them with a “skipped — prior outcome” status) but no cycles run and no new outcome row is written.

Scope (MVP): --scope=missing only — skip phases whose exact identity already has a completed outcome row. --scope=changed (hash compare) and --scope=all are follow-up pushes. --on-removed= policies likewise deferred.

Structs

PriorCompletion

The chronologically-latest completed outcome’s provenance for one phase identity (SRD-77 base hash + SRD-107 consumed-params JSON).

RefinePlan

Pre-computed skip set + next-execution id for one refine invocation.

Enums

ExecutionQualifier

SRD-77 — Every read-side path that touches session data is execution-qualified: it accepts an ExecutionQualifier at the call boundary, and the storage layer applies a matching exec_id filter to its queries. The “aggregate across every execution” intent is the explicit ExecutionQualifier::All variant, not an unqualified default — callers can never accidentally read across multiple executions when they meant the latest.

RefineScope

SRD-77 --scope= modes.

SkipBlocker

Why a phase may NOT skip under the refine hash gate (SRD-107 Push 3) — surfaced in diagnostics so an operator sees “re-running load_train: param ‘dataset’ changed” instead of a bare hash mismatch.

Constants

LATEST_LITERAL

SRD-77 — the reserved CLI-side virtual qualifier that means “the most recent execution recorded in the session store”. Resolvers translate this to a concrete exec_id at query-construction time. Must never appear in stored data — the metric_instance reserved-word guard refuses any write carrying session="latest" or exec_id="latest".

Functions

latest_exec_id_for_session

Read the maximum exec_id recorded in the session’s phase_outcomes table — i.e. “which execution_id is the most recent one in this session’s history”. Used by ExecutionQualifier::latest to resolve the latest- execution intent into a concrete id.

warn_multi_execution_default

SRD-77 — emit a per-command banner when the active session has more than one execution in its history. Tells the operator which execution the implicit latest default resolved to and lists the latest three in temporal order (newest first), with <-- latest marking the one their query is currently bound to.