Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.firstresonance.io/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Every run in ION lives in one of four states. The state machine is small and intentional — most of the operational complexity lives inside In Progress, where steps are being executed. 
   ┌──────┐    start    ┌─────────────┐    complete    ┌──────────┐
   │ Todo │ ──────────▶ │ In Progress │ ─────────────▶ │ Complete │
   └──────┘             └─────┬───────┘                └──────────┘
                              │
                              │ fail
                              ▼
                        ┌──────────┐
                        │  Failed  │
                        └──────────┘
StateMeaning
TodoThe run has been created from a procedure but no operator has started executing steps yet. The run is staged on a part inventory and ready to pick up.
In ProgressAt least one step has been started or completed. Operators are actively executing.
FailedThe run was terminated due to a failure that can’t be reconciled — typically a part scrap, a process abort, or an unrecoverable quality event. The part inventory is typically scrapped or quarantined.
CompleteEvery required step has been completed and signed off. The part inventory’s state reflects the build outcome.
A run never moves backward through completed states without explicit intervention. Once Complete, reopening requires a deliberate admin action and leaves an audit trail.

​
Transitions

​
Todo → In Progress

Triggered automatically when an operator starts the first step of the run. Doesn’t require an explicit “start run” action — beginning the first step is the start signal. The run’s startedAt timestamp is recorded on this transition. Use that field for floor-time analytics; it’s the moment work actually began, not when the run was created.

​
In Progress → Complete

When the last required step is signed off, the run moves to Complete. ION:
  • Sets completedAt.
  • Updates the target partInventory’s state (typically to available for the produced unit).
  • Closes any open run-level approval gates.
  • Stops further step edits unless the run is reopened.
If the run has any open issues at completion, ION may block the transition until issues are dispositioned — depending on org settings.

​
In Progress → Failed

Triggered explicitly via the Fail run action on the run page. Use cases:
  • A part inventory is scrapped mid-build.
  • A process step uncovers an unrecoverable nonconformance.
  • The build target is abandoned for a non-quality reason (planning error, customer cancellation).
Failed runs preserve every step’s history — operators can still see what was done, what was measured, and what was attached. The data isn’t lost; the run is just terminated.

​
Reopening a complete run

Reopening a Complete run requires admin permission. It’s recorded in the run’s transaction history with the user, timestamp, and reason. Use it sparingly — it’s typically reserved for finding-and-fixing data issues rather than continuing work.

​
Run states vs step states

A step’s status is independent of (but constrained by) the run’s status.
Run statusAllowed step transitions
TodoSteps stay todo; first step transition is what flips the run to In Progress
In ProgressSteps can move freely between todo, in_progress, failed, complete (subject to step-level approval gates)
FailedSteps freeze in their current state — no further transitions
CompleteSteps are locked to complete (or the failed-but-resolved equivalent) — no further transitions
A run’s status reflects the rolled-up state of its steps plus explicit transitions. If every step is complete, the run is Complete. If any step is failed and the run hasn’t been explicitly failed, the run remains In Progress (because the operator might address the failure and continue).

​
What gets timestamped on a run

FieldSet when
_createdRun record was created
startedAtFirst step transitioned out of todo
completedAtLast required step transitioned to complete
_updatedAny field on the run was last modified
Use startedAt → completedAt for cycle-time analytics; _created → completedAt if you want to include staging time before the first step.

​
Tips

  • Don’t fail runs out of habit. Failing a run is operationally significant. If a step fails but the build can be reworked, mark the step failed and continue — the run stays In Progress until you actually need to terminate the build.
  • Watch for stuck Todo runs. A run that sits in Todo for days usually means a planning or staging issue, not an operator problem. Surface them in a dashboard.
  • Use Issues, not run-fail, for quality events. Quality issues attach to runs and steps without ending the run; failing the run loses operational continuity.