Workspace · Execution evidence
996102e0
Execution Ledger & Recovery Center
Use this center after the specification space and common endpoint are declared and before failed or incomplete execution gets simplified into a results table.
run_specs() returns successful result rows containing the specification plus estimate. If the processor or endpoint raises, the exception propagates. It does not create technical_failure, not_run, or repair-history rows for you.
The center has two purposes:
- explain the governed execution-state vocabulary used across the documentation;
- generate one documentation-side attempt record at a time so failure/recovery history can remain reconstructable.
Governed execution states
Showing all 6 execution states/events.
invalid_before_execution
Invalid before execution
A declared combination is rejected by a scientific validity rule fixed before processor or endpoint execution.
Preserve
Preserve the full factor combination, the pre-execution rule, its rationale, and declaration timing.
Next step
Keep the branch in the declared-space record but outside the valid execution denominator.
Boundary
Do not use this state retrospectively for a branch that failed technically or produced an inconvenient endpoint.
Reporting wording
[I] of [D] declared combinations were invalid before execution under the predeclared validity rule; [V] combinations remained valid.
successful
Successful execution
A valid branch completes the declared processing and endpoint contract and yields an estimate accepted by the surrounding audited workflow.
Preserve
Preserve branch identity, attempt identity, factor levels, endpoint reference, estimate, source/software identity, and timing.
Next step
Include the represented estimate in the appropriate robustness summaries while retaining the complete valid denominator.
Boundary
Success establishes execution under the declared contract; it does not establish scientific validity, preferred-model status, or robustness by itself.
Reporting wording
[S] of [V] valid specifications successfully produced the declared endpoint.
technical_failure
Technical failure
A valid branch is attempted but the processor or endpoint raises before a normal endpoint result can be retained.
Preserve
Preserve branch and attempt identity, exception type/message, failing layer, input/software identity, and whether outcomes were already inspected.
Next step
Diagnose the causal technical defect; if repaired, rerun the same scientific branch and retain both attempts.
Boundary
Core run_specs() propagates the exception; technical_failure is audit/recovery vocabulary, not a run_specs() enum.
Reporting wording
[F] valid specification(s) failed technically and remained in the valid denominator; the original failure record was retained.
non_finite_endpoint
Non-finite endpoint
A valid attempted branch returns NaN or infinity under the endpoint calculation.
Preserve
Preserve the exact non-finite value, branch/attempt identity, endpoint inputs relevant to diagnosis, and the declared non-finite policy.
Next step
Diagnose empty groups, missing contrasts, zero denominators, upstream non-finite values, or another endpoint-contract problem without converting the value to zero.
Boundary
float(...) accepts NaN and infinity, so core run_specs() does not automatically classify this state for you.
Reporting wording
[N] valid specification(s) returned a non-finite endpoint and were not interpreted as null effects.
not_run
Not run
A branch that belongs to the declared record was not attempted for an explicit external or workflow reason.
Preserve
Preserve whether the branch was scientifically valid, the reason it was not attempted, timing, and the intended rerun or closure decision.
Next step
Do not relabel a valid not-run branch as invalid or successful; resolve it or report the incomplete valid denominator.
Boundary
Not-run is audit vocabulary, not a package runtime status and not evidence of a null or failed effect.
Reporting wording
[R] valid specification(s) were not run; the reason and resulting incompleteness remained explicit.
repair_rerun_success
Successful repair rerun
The same scientifically valid branch is rerun after a causal technical repair and now produces an accepted endpoint.
Preserve
Preserve the new attempt ID, prior failed attempt ID, repair record, unchanged scientific branch identity, estimate, and before/after software or representation identity where relevant.
Next step
Use the reconciled current branch result for downstream summaries while retaining the historical failure event in the audit trail.
Boundary
A successful rerun does not erase the original failure and must not conceal any scientific change introduced during the repair.
Reporting wording
After a technical repair that did not change the scientific branch, the same specification was rerun successfully; the original failure event remained in the execution history.
No execution state matches these filters
Clear the filters or use site search with Ctrl/Cmd + K.
Build one attempt record
Use this form to preserve one branch attempt or recovery event. It does not execute code, inspect participant data, or decide whether a branch is scientifically valid.
No attempt record generated yet.
Documentation-side attempt JSON
This record is provenance. It is not a package runtime object and does not certify the scientific validity of the branch or repair.
{
"schema": "gazeaudit-execution-attempt-v1"
}Attempt-state compatibility rules
The builder enforces only a few structural consistency rules.
Invalid before execution
Must use:
- validity =
invalid_before_execution; - state =
invalid_before_execution; - no estimate;
- no execution error.
It is a declaration/validity record, not an attempted branch.
Successful
Must use:
- validity =
valid; - a finite numeric estimate.
Technical failure
Must use:
- validity =
valid; - an error type or message;
- no scientific estimate.
Non-finite endpoint
Must use:
- validity =
valid; - estimate text equal to
NaN,Infinity, or-Infinity.
Not run
Requires:
- an explicit reason;
- no estimate.
If the branch was scientifically valid, it remains unresolved in the valid denominator.
Successful repair rerun
Requires:
- validity =
valid; - a finite estimate;
- prior attempt ID;
- repair record reference.
The earlier failure remains in history.
Current state and historical events are different
Attempt rows are not the specification denominator. A branch can have more than one attempt.
Example:
S06 / attempt-01 / technical_failure
S06 / attempt-02 / repair_rerun_success
The current scientific result may use the successful rerun, while the provenance record still preserves the initial failure.
Do not overwrite attempt 1 with attempt 2.
Reconciliation rule
For a declared space:
declared = invalid-before-execution + valid
For the current execution state of valid branches:
valid = successful + unresolved technical failure + unresolved non-finite + valid not-run
Historical repair events can add extra attempt rows without increasing the number of scientific branches.
That distinction prevents an attempt ledger from being mistaken for a specification denominator.
Reporting examples
Methods
Every declared branch was assigned a stable branch identity. Pre-execution scientific validity was recorded separately from execution attempts. Valid technical failures, non-finite endpoints, and not-run branches remained in the valid denominator. Technical repairs created new attempt records linked to the original failed attempt rather than overwriting history.
Results
[S] of [V] valid specifications currently yielded accepted finite endpoints; [F] remained technical failures, [N] remained non-finite, and [R] were not run. [K] repaired branches had historical failure events retained in the attempt ledger.
Limitation
The execution ledger establishes branch and attempt accountability. It does not determine whether the declared factor space, endpoint, validity rule, repair, or scientific interpretation is substantively correct.
API links
run_specs()PipelineSpace- Specification Space Declaration Center
- Endpoint Definition & Handoff Center
- Evidence and denominator vocabulary
- Machine-readable execution-state reference
Continue from here
- Execution ledger and recovery — design, lineage, reconciliation, repair, and reporting guidance.
- Failure → repair → reconciliation — a fully synthetic multi-attempt ledger with one invalid branch, one non-finite endpoint, one technical failure, and one repaired rerun.
- Failed-audit recovery — detailed causal repair workflow.
- Results Interpretation & Reporting Center — convert reconciled evidence into bounded claims.