# Runs and comments

> The panel of a unit: staging a procedure and its metadata, Start and what it validates, Hold, Resume, Stop and Abort, the live cards, comments, the single commands, the run file, and the automation and agent paths.

A unit's **panel** (Process > Models > a model > Operate > the unit > a panel, and the
same panel on the View page when it is marked Show on View) is where a run is staged,
started, steered and watched. Which cards it draws, and in which order, is arranged once on
the model under Visualization > [Panels](process-panels); every unit of the model then
operates through the same surface. Watching needs only the tree. Every command on the panel
takes **Run procedures**; without it the panel opens with the notice "You can watch this
unit's run state here, but starting or steering it needs the 'Run procedures' permission."
and draws no lifecycle button at all.

A card the station gives nothing to show is left out rather than drawn empty: the Single
commands card needs a datalog or an instant recipe on the model, the Channels card a
readable channel, the Metadata card a staged procedure that prompts a field (or nothing
staged yet), and an embedded dashboard something placed on it. A panel that arranges no
card reads "This panel draws no card. Choose its cards on the model's Panels row, under
Visualization."

## The interlock banner {#the-interlock-banner}

When the model observes an external stop ([Automation](process-automation)), the unit's
interlock stands above every card and draws nothing while it is Normal. Otherwise it is a
banner titled **Interlock tripped** (loud), **Interlock awaiting reset** or **Interlock
unavailable**, with the reason, the source's name, its value and its quality. While it is
not Normal no new Start, Resume, snapshot, evaluation or recipe apply is admitted on the
unit. A trip ends the run in progress through the ordinary end path, as **Aborted** with
verdict **NOK** and the termination reason **Interlock**, and nobody is named as having
ended it. The latch survives a restart. **Rearm** appears only in Awaiting reset, needs Run
procedures, a source that reads good and safe and a unit no run owns; it clears the latch,
is journaled with the operator's name, and never restarts the aborted run.

## The Run card {#the-run-card}

The head of the card carries a lamp: **Recording** (green), **Preparing** (caution) or
**Not recording**.

| Field | What it is | Values / default | Effect |
| --- | --- | --- | --- |
| Procedure | The procedure staged for the next Start. | "(none)" plus every procedure of the model, alphabetically; nothing staged by default, and staging resets when the app starts. | Staging is station-wide: every screen of this unit, the `Next.Procedure` point and the Operate card show the same choice. Staging a procedure that pins an alias set applies that set to the unit at Start; a pin that cannot be applied leaves the previous staging in place and says why on the card. The picker is greyed without Run procedures and while the runtime is stopped. |

The lifecycle buttons, in the order drawn. Hold and Resume are left out when the staged
procedure is Controlled or Instant, because only a Temporal run has a window to freeze;
with nothing staged all five are drawn.

| Command | What it does | Greyed when (situation) | Not drawn when (role) |
| --- | --- | --- | --- |
| Start | Starts the staged procedure on this unit. | The unit is busy, no procedure is staged, the runtime is stopped, the interlock is not Normal, or the station is refusing writes. | Without Run procedures. |
| Hold | Freezes the temporal window at the last setpoint; the datalog keeps recording. | No run is Running, or the running procedure is not Temporal. | Without Run procedures; the staged procedure is Controlled or Instant. |
| Resume | Releases the hold and carries the window on. | No run is Held, or the interlock is not Normal. | Without Run procedures; the staged procedure is Controlled or Instant. |
| Stop | Ends the run cleanly and freezes it as history, from Running or from Held. | No run owns the unit. | Without Run procedures. |
| Abort | Ends the run as aborted; the finalization block still runs. | No run is Running or Held. | Without Run procedures. |

A refused command writes its reason on the card ("No procedure is staged. Pick one
first."), and two standing lines under the buttons say why the station or the unit is not
accepting commands: "Runtime stopped", and the interlock's reason.

## Start, and what it validates {#start-and-what-it-validates}

Start consumes the unit's staging and refuses everything before it takes any resource. In
order: the unit is reserved (a second Start on the same unit is refused); the staged
procedure must still exist ("The staged procedure no longer exists. Pick one again.") and
the staging must not have moved while Start waited for an engineering edit to finish ("The
staged procedure or metadata changed while Start was waiting. Review the prepared run and
retry."); the procedure must pass the gate its own page shows ("Nothing to run: this
procedure references neither a datalog nor a recipe.", "Temporal mode needs a duration.
Set one.", "Instant mode needs an instant recipe (or none). A temporal profile has no
single tick.", "The recipe profile (n ms) is longer than the temporal window (m ms).",
and the production-output checks); every armed occurrence must have a valid condition; at
least one datalog channel must resolve to a bound source on this unit ("No datalog channel
resolves to a bound source on unit 'X'."); the prompted metadata must be complete and typed
("Metadata field 'X' is required.", "Metadata field 'X' must be numeric.") and every
sequential field must be able to compose (a missing unit or procedure code refuses the
Start); the interlock must be Normal; and every source the recipe writes must be free (a
source held by another unit's run refuses the Start by channel and holding unit). Only
then are the sequential counters reserved, the run file created with the metadata already
written into it, and the engines launched; the Start labels and Start reports the
procedure emits go out as the run materializes ([Emitting labels and
reports](process-emission)).

## The Metadata card {#the-metadata-card}

The card is headed "What the next run of 'Procedure' is recorded under. A field marked *
is prompted by every procedure." and draws one entry per metadata field the staged
procedure prompts, in the procedure's order; with nothing staged it reads "Stage a
procedure and the fields it prompts appear here."

| Field kind | What the card draws | Effect |
| --- | --- | --- |
| Text | An entry box. | Written to the station-wide staging as you type; Start records it into the run file. A required field (marked *) refuses an empty Start. |
| Numeric | An entry box. | The same, and Start refuses a value that is not a number. |
| Sequential | A read-only preview of the identifier the counter would compose now, or "Reserved at start" when no counter state exists yet. | Nothing is reserved by looking: the definitive value is reserved at Start, so a counter shared by several units may move before then. |

Staging is consumed by Start, not cleared: the entries stay as defaults for the next run
of the same procedure. Entries typed for another procedure stay in the staging area but
are inert, since Start reads only the fields of the staged procedure. The boxes are greyed
without Run procedures and while the runtime is stopped.

## The Run state card {#the-run-state-card}

Three readouts: **State** (Running, Held, Saving, Completed, Aborted, Failed, or
"Preparing" while the unit is reserved and "Idle" when nothing owns it), **Cycle** ("2 /
10" for a cyclic run, "Not cycling" otherwise; left out entirely when the staged procedure
is Controlled or Instant) and **Verdict** (the evaluation's live verdict, kept readable
after the run ends until the next run starts; "None" when nothing has been judged).

## What each end does {#what-each-end-does}

| Ending | Recording | Recipe | Verdict and state |
| --- | --- | --- | --- |
| Stop | Sampling stops after the finalization block ran, so the safe-state transition is in the datalog. | The finalization setpoints are written. | The evaluation closes its open windows and folds: OK, NOK, Indeterminate, or None without an evaluation. Completed. |
| Abort | The same. | The finalization setpoints are written. | NOK whatever was judged. Aborted. |
| The window ends (Temporal) or the row is recorded (Instant) | The same. | The finalization setpoints are written. | As Stop. Completed; nobody is named as having ended it. |
| A recipe write fails with the failure policy Abort | The same. | Finalization still runs. | NOK. Aborted. |
| The interlock trips | The same. | Finalization still runs. | NOK. Aborted, termination reason Interlock. |
| The runtime stops | Every run not yet sealed is aborted. | Finalization still runs. | NOK. Aborted. |
| An unrecoverable error | Sampling stops; no finalization. | Nothing more is written. | None. Failed. |

Closing the application ends nothing: a Running or Held run resumes at the next launch, a
temporal profile held at its persisted segment and cycle, and the datalog carries on in the
same file.

## The Channels card {#the-channels-card}

The unit's readable channels on one live chart, each series labelled by the name in force
on this unit (an alias shows live) and drawn in the colour and band the model declares on
the channel, with the chart toolbar every chart carries ([Charts](view-charts)). It shows
the live values whether or not a run records; a line under the drawing says how much
history the chart retains.

## The Comments card {#the-comments-card}

The card is headed "Comments · Procedure · Unit" while a run is active and "Comments · no
active run" otherwise; an idle unit shows no timeline, and a finished run takes its notes
from [Histories](histories-notes). Each recorded line shows its time, its phase (Run or
Post-run) and its text, with two gestures: **Edit** rewrites it in place (Enter saves, Esc
cancels; a blank or unchanged text leaves the record alone, and a rewrite stamps the edit
instant), and **Delete** takes two presses, the first arming the line ("Delete this
comment? This cannot be undone.") and the second removing it. The box at the foot ("Add a
comment…") and **Add** record a new line stamped with the instant and the operator signed
in on this screen (the station when nobody is). All three gestures need Run procedures and
an active run. The same append is available to dashboards and agents through the unit's
`Commands.Comment` point ([The unit address space](process-addresses)).

## The Occurrences card {#the-occurrences-card}

The occurrence episodes of this unit, active ones first, each with its status, its two
clocks (active time and signal loss) and the message frozen with it; the head counts the
active episodes. What an episode is, and how its clocks are derived, is on
[Occurrences](process-occurrences).

## The Productivity card {#the-productivity-card}

The unit's production activity over **Today** or the rolling window (a segmented control
in the head): productivity, yield and typical elapsed time, the output ledger, the
completion outcomes and a per-procedure table. What counts and how it is computed is
[Productivity](process-productivity).

## The Single commands card {#the-single-commands-card}

One isolated command on the unit, outside any procedure. A row appears only where the
model declares what it fires from.

| Row | Controls | What it does | Greyed when |
| --- | --- | --- | --- |
| Snapshot | A datalog picker and **Capture** | Records one datalog row now as a finished Instant run in Histories, named "Snapshot · datalog". | The unit is busy, the interlock is not Normal, the runtime is stopped, a single command is still running, or without Run procedures. |
| Evaluate now | A datalog picker, an evaluation picker and **Evaluate** | Records one row and judges it against the evaluation now; the run is named "Evaluate · evaluation" and carries the moment's verdict. Drawn only when the model has both a datalog and an evaluation. | The same. |
| Apply recipe | A picker of the model's instant recipes and **Apply** | Writes the recipe's setpoints once through the write funnel under a short-lived lock; no run is recorded, the journal is the record. A source held by a live run refuses it. | The interlock is not Normal, the runtime is stopped, an apply is still running, or without Run procedures. It stays available while the unit records. |

Snapshots and evaluations prompt no metadata, reserve no counter and never count toward
production. Outcomes land in the action feed ("Snapshot recorded. See Histories.",
"Evaluated. The verdict is recorded in Histories.", "Recipe applied.").

## Dashboards as cards {#dashboards-as-cards}

A panel may embed any dashboard of the model as a card, at the height chosen on the panel.
The card runs the model's definition resolved for this unit, exactly as the unit's own
dashboard node does, and its command components need Run procedures only.

## The datalog {#the-datalog}

While a run records, the [datalog](process-datalogs) named by its procedure writes one
application-level snapshot per interval: every recorded channel, in declared column order,
each value paired with a Good or Unavailable flag. The row promises coherent application
observation, not simultaneous physical acquisition: source devices refresh at their own
rates. An unavailable source or an unconvertible value is stored as a gap; a correctly
received `NaN` or engineering sentinel stays Good. A shorter interval does not get there
through the screen: the datalog's Snapshot interval field refuses a value below 50 ms
("Enter a number of at least 50.") and puts the box back to the interval in force. An
interval that reaches a run by any other path is used as-is down to 50 ms, and anything
lower is treated as 50 ms.

## The run file {#the-run-file}

The run file is the complete record: stable model, unit and procedure identities and
names, the model revision, the frozen channel layout with each column's resolved chart
ink, the metadata values, the as-executed recipe writes, criterion results, occurrence
events, comments, chart annotations, production records, label artifacts and report
registrations. The frozen context is captured at Start and never mutated; the finalizer
only adds the outcome: verdict, terminal state, finish time, who ended the run and, where
an interlock ended it, the termination reason. Deleting the model, unit or procedure never
touches a recorded run. Browsing, exporting and regenerating documents from run files is
[Histories](histories).

## The automation path {#the-automation-path}

A unit whose [automation](process-automation) is enabled takes the same lifecycle from
the field: a rising edge on the Boolean source bound to Start, Hold, Resume, Stop or Abort
fires that command. Abort wins over Stop on the same poll, and any other pair of
simultaneous edges is refused as conflicting. An automated Start resolves its procedure
from the fixed choice or the numeric selector and its metadata from the configured sources
without touching the operator's staging, and is admitted only when the unit is ready for
Start. The result is written back to the return mapped as CommandResult: 0 Idle, 1
Accepted, 2 UnitNotReady, 3 InvalidSelection, 4 InvalidMetadata, 5 IncompatibleCommand, 6
ConflictingCommands, 7 InternalFailure. A run the automation admitted lists in Histories
with the **Automation** badge, records the automation as responsible, and names it as the
one who ended it after an automated Stop or Abort.

## Agents and dashboards {#agents-and-dashboards}

The embedded agent server drives the same lifecycle through its Process operate tools
(start, stop, hold, resume, abort, comment, snapshot, evaluate, recipe apply), journaled
as Agent and recorded as Agent in the run ([Agent access](agent)). A dashboard reaches it
through the unit's command points: a Button on `Commands.Start` disables itself while the
readiness reads false, an Input on `Next.<Field>` stages a value, and the Procedure picker
component stages a procedure ([The unit address space](process-addresses)).

## What this surface does not do {#what-this-surface-does-not-do}

It configures nothing: channels, bindings, metadata, the interlock and the automation are
edited under [Definition](process-definition); what a run applies, records and judges is
composed under [Setup](process-setup). It does not edit a finished run: post-run notes,
annotations, exports, reports and labels of a recorded run are [Histories](histories). And
it never draws a card the station cannot fill.