labcode 0.2.0__tar.gz → 0.3.1__tar.gz

{labcode-0.2.0 → labcode-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: labcode
-Version: 0.2.0
+Version: 0.3.1
 Summary: labcode -- a dialect wrapper over the Object-Flow Programming Language toolchain
 Author-email: Kazunari Kaizu <kwaizu@gmail.com>
 License-Expression: MIT
@@ -20,9 +20,9 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: ofplang-validate>=0.1.3
-Requires-Dist: ofplang-schedule>=0.2.3
-Requires-Dist: ofplang-run>=0.3.0
+Requires-Dist: ofplang-validate<0.3,>=0.2
+Requires-Dist: ofplang-schedule<0.6,>=0.5
+Requires-Dist: ofplang-run<0.7,>=0.6
 Provides-Extra: test
 Requires-Dist: pytest>=7.0; extra == "test"
 Requires-Dist: opentelemetry-sdk>=1.20; extra == "test"
@@ -98,19 +98,23 @@ repository, and what labcode adds to it in [`SPECIFICATIONS.md`](SPECIFICATIONS.
 
 What `lc run` brings of its own, beyond dispatching:
 
-- **the labcode backend** — each device operation's `x-labcode.script` runs
-  out-of-process on a wall clock (§1.2, §1.3), so a real operation that takes minutes
-  does not block the replan loop, and an operation that never returns is stopped by
-  **`op_timeout`** (§1.8; `--op-timeout` / `--no-op-timeout`).
+- **the labcode backend** — each operation's `x-labcode.script` runs out-of-process on a
+  wall clock (§1.2–§1.4), so a real operation that takes minutes does not block the
+  replan loop, and an operation that never returns is stopped by **`op_timeout`**
+  (§1.9; `--op-timeout` / `--no-op-timeout`).
+- **refilling a stock** — where the environment says a replenisher can reach a device, a
+  stock that would run out is topped up rather than ending the run: the refill's own
+  script runs like any other, holding both machines while it works (§1.4). See
+  *Refilling a stock* below.
 - **the dialect front door** — the environment's `x-labcode` extension is validated
   before anything runs, on top of the portable-v0 check `lc validate` performs (§1, §2).
 - **availability probing** — each machine is checked as often as its `probe` policy says,
   and one that cannot be reached is taken out of the environment the scheduler plans
-  against, so the run routes around it (§1.5; `--no-probe`).
+  against, so the run routes around it (§1.6; `--no-probe`).
 - **object identity** — the reserved `_id` view key is declared on Object types and minted
   per object, so a physical thing can be followed through a run (§4).
 - **`flavor: sila2`** — a script that speaks SiLA2 gets its clients opened around it
-  (§1.6). The client library itself is the `sila2` extra: `pip install labcode[sila2]`,
+  (§1.7). The client library itself is the `sila2` extra: `pip install labcode[sila2]`,
   installed into whichever interpreter runs the scripts.
 - **recording a run** — with `--trace`, what the run did is recorded as OpenTelemetry
   traces: one trace per run, a span per operation, and — measured inside the process that
@@ -168,10 +172,10 @@ lc run <workflow> --env <env>
   completed reads as discrete, observable steps; a demo against a fast mock wants a small
   value.
 - `--op-timeout S` / `--no-op-timeout` — how long one operation may run before it is
-  stopped and failed (§1.8). The default is the environment root's `x-labcode.op_timeout`,
+  stopped and failed (§1.9). The default is the environment root's `x-labcode.op_timeout`,
   else 7200 real seconds. The two forms exclude each other.
 - `--no-probe` — ignore the environment's `x-labcode.probe` policies and treat every
-  machine as reachable (§1.5). The documents are still validated.
+  machine as reachable (§1.6). The documents are still validated.
 - `--ignore-resources` — switch the consumable model off. The environment's resource
   declarations are still checked for shape but none is applied, so a bench whose devices
   declare stocks nobody is tracking runs without the boundary saying what they held.

{labcode-0.2.0 → labcode-0.3.1}/README.md

@@ -54,19 +54,23 @@ repository, and what labcode adds to it in [`SPECIFICATIONS.md`](SPECIFICATIONS.
 
 What `lc run` brings of its own, beyond dispatching:
 
-- **the labcode backend** — each device operation's `x-labcode.script` runs
-  out-of-process on a wall clock (§1.2, §1.3), so a real operation that takes minutes
-  does not block the replan loop, and an operation that never returns is stopped by
-  **`op_timeout`** (§1.8; `--op-timeout` / `--no-op-timeout`).
+- **the labcode backend** — each operation's `x-labcode.script` runs out-of-process on a
+  wall clock (§1.2–§1.4), so a real operation that takes minutes does not block the
+  replan loop, and an operation that never returns is stopped by **`op_timeout`**
+  (§1.9; `--op-timeout` / `--no-op-timeout`).
+- **refilling a stock** — where the environment says a replenisher can reach a device, a
+  stock that would run out is topped up rather than ending the run: the refill's own
+  script runs like any other, holding both machines while it works (§1.4). See
+  *Refilling a stock* below.
 - **the dialect front door** — the environment's `x-labcode` extension is validated
   before anything runs, on top of the portable-v0 check `lc validate` performs (§1, §2).
 - **availability probing** — each machine is checked as often as its `probe` policy says,
   and one that cannot be reached is taken out of the environment the scheduler plans
-  against, so the run routes around it (§1.5; `--no-probe`).
+  against, so the run routes around it (§1.6; `--no-probe`).
 - **object identity** — the reserved `_id` view key is declared on Object types and minted
   per object, so a physical thing can be followed through a run (§4).
 - **`flavor: sila2`** — a script that speaks SiLA2 gets its clients opened around it
-  (§1.6). The client library itself is the `sila2` extra: `pip install labcode[sila2]`,
+  (§1.7). The client library itself is the `sila2` extra: `pip install labcode[sila2]`,
   installed into whichever interpreter runs the scripts.
 - **recording a run** — with `--trace`, what the run did is recorded as OpenTelemetry
   traces: one trace per run, a span per operation, and — measured inside the process that
@@ -124,10 +128,10 @@ lc run <workflow> --env <env>
   completed reads as discrete, observable steps; a demo against a fast mock wants a small
   value.
 - `--op-timeout S` / `--no-op-timeout` — how long one operation may run before it is
-  stopped and failed (§1.8). The default is the environment root's `x-labcode.op_timeout`,
+  stopped and failed (§1.9). The default is the environment root's `x-labcode.op_timeout`,
   else 7200 real seconds. The two forms exclude each other.
 - `--no-probe` — ignore the environment's `x-labcode.probe` policies and treat every
-  machine as reachable (§1.5). The documents are still validated.
+  machine as reachable (§1.6). The documents are still validated.
 - `--ignore-resources` — switch the consumable model off. The environment's resource
   declarations are still checked for shape but none is applied, so a bench whose devices
   declare stocks nobody is tracking runs without the boundary saying what they held.

{labcode-0.2.0 → labcode-0.3.1}/SPECIFICATIONS.md

@@ -12,10 +12,12 @@ conformance validator, run at the `lc run` front door.
 
 ## 1. `x-labcode` in an environment (P5)
 
-The extension appears in four places, each answering a different question: on a **process
-mode** and on a **transport route** it says *what to run* (a `script`, §1.1–§1.3); on a
-**device** and on a **transporter** it says *how to reach the machine* (a `connection`,
-§1.4), which is what lets a script be the commands alone (§1.6). Nowhere else — see §1.7.
+The extension answers two different questions, in two kinds of place. On a **process
+mode**, a **transport route** and a **replenishment route** it says *what to run* (a
+`script`, §1.1–§1.4); on a **device**, a **transporter** and a **replenisher** it says
+*how to reach the machine* (a `connection`, §1.5), which is what lets a script be the
+commands alone (§1.7). The division is the same each time: the machine has an address,
+and the thing it does to something else has a procedure. Nowhere else — see §1.8.
 
 An environment process mode (§5) may carry an `x-labcode` mapping holding a `script`: the
 Python that carries out that `(process, mode)`.
@@ -39,20 +41,23 @@ still validates and schedules as plain v0. Only labcode interprets it.
 
 ### 1.1 Shape
 
-- `x-labcode` MUST be a mapping. On a process mode or a transport route its only key is
-  `script`.
+- `x-labcode` MUST be a mapping. On a process mode, a transport route or a replenishment
+  route its only key is `script`.
 - `x-labcode.script`, if present, MUST be a mapping with:
   - `language`: MUST be `python`.
   - `code`: MUST be a string (an implementation-provided Python function body).
   - `flavor` (optional, default `raw`): MUST be `raw` or `sila2` — how `code` is meant to
-    be run (§1.6). `sila2` is the **recommended** way to drive a SiLA2 lab: the code is the
+    be run (§1.7). `sila2` is the **recommended** way to drive a SiLA2 lab: the code is the
     commands alone and labcode supplies the clients. `raw` is the whole function body,
     written by its author — the general escape hatch, and what a script that connects for
-    itself (or speaks something other than SiLA2) uses.
+    itself (or speaks something other than SiLA2) uses. On a **replenishment route**
+    `sila2` is an error in this version (§1.4).
   - `endpoints` (**transport routes only**, optional, default `false`): MUST be a boolean —
     whether this move is also given clients for the devices at either **end** of its route,
-    not only its `transporter` (§1.6). A process mode may not declare it: a mode's machines
-    are the ones it lists.
+    not only its `transporter` (§1.7). A process mode may not declare it: a mode's machines
+    are the ones it lists. A `sila2` script on a route with **no transporter** (§1.3) MUST
+    declare it `true`: the ends are then the only machines there are, and a script is never
+    given a machine it did not ask for.
 
 **Unknown keys are an error** — in `x-labcode` at every position, and in the mappings it
 holds. A key this version does not know is either a typo or a feature it does not have;
@@ -121,12 +126,76 @@ output is verified. Success is "it ran without raising"; an exception is a grace
 A route with no `x-labcode.script` runs as a plain timed move — the runner's material
 bookkeeping only, with no device command (a warned no-op for a real move, from != to).
 
-### 1.4 `x-labcode` on a device or a transporter
+**A route with no transporter.** An environment may declare a route that needs no
+transporter at all, by writing `transporter: null` (ofplang-schedule §4.6 / §5.4) — a
+device shifting material between its own spots, a chute. The plan then reports the move
+with `transporter: null` too, and this dialect matches it like any other: routes are keyed
+by `(transporter, from, to)`, so a null one matches a null one, and the script's
+`transporter` local is `None`.
 
-An environment `devices[]` or `transporters[]` entry may carry an `x-labcode` with two
-keys: `connection` — **where that machine is**, written once per physical machine rather
-than repeated in every script that drives it — and `probe` (§1.5) — whether to check that
-it still answers.
+Such a move is performed by the **devices at either end of the route** — for a move within
+one device, that device. So a `flavor: sila2` script on such a route must declare
+**`endpoints: true`** (§1.6), and at least one of those devices must declare a
+`connection`; either missing is a front-door error. The `endpoints` request is *required*
+rather than inferred: it is the author's statement of which machines the script drives, and
+reading it for them would decide that on exactly the routes where it matters most. A `raw`
+script, or no script at all, is unaffected — neither is handed clients.
+
+`sila2_client` is then the first machine connected to, which is the **source device**: the
+one performing the move, exactly as it is the transporter on a carried route (§1.7).
+
+### 1.4 `x-labcode` on a replenishment route
+
+An environment `replenishments[]` route may carry an `x-labcode` with a `script`: the
+Python that physically refills that device from that replenisher (e.g. commanding a
+dispenser). Same shape as §1.1 (`language: python`, string `code`).
+
+The procedure lives on the **route**, not on the machine — the same division transports
+and transporters have. A dispenser's address is a property of the dispenser (§1.5); how it
+fills *this* device is a property of the pair.
+
+```yaml
+replenishments:
+  - replenisher: dispenser
+    device: reader
+    duration: 4                    # ticks: the scheduler's estimate of the visit
+    x-labcode:
+      script:
+        language: python
+        code: |
+          import time
+          time.sleep(80)           # real seconds: what the visit actually takes
+```
+
+**Calling convention (replenishment).** The script runs as a function body with these
+locals: `replenisher`, `device` (the two machines the visit holds) and `amounts` — the
+`{resource: amount}` the scheduler derived, which a planned refill fills to the device's
+capacity. It is **not** given the duration: a real refill takes as long as it takes, and
+the ticks the plan reserved are the scheduler's estimate rather than an instruction, so a
+stand-in states its own time (which is why the two numbers above are written separately).
+
+A replenishment script is **side-effect only**, as a transport's is: its return value is
+ignored and no output is verified. An exception is a graceful failure — the refill ends
+`failed` and the run stops, like any activity failure.
+
+`flavor: sila2` is **an error** on a replenishment route in this version. A `sila2` script
+is handed clients (§1.7), and which machine's clients a refill should receive — the
+replenisher's, or both ends' as a transport route may ask for — is not settled. Refusing
+says so; running the script without the clients it asked for would not. Use `raw` (the
+default), which may of course connect for itself.
+
+A route with no `x-labcode.script` runs as a plain timed visit: both machines are held for
+the declared duration and nothing is commanded. That is a legitimate environment to write
+— an operator tops the stock up while the schedule waits for them — and an easy one to
+write by accident, so it is **warned** about, as a scriptless real move is.
+
+### 1.5 `x-labcode` on a device, a transporter or a replenisher
+
+An environment `devices[]`, `transporters[]` or `replenishers[]` entry may carry an
+`x-labcode` with two keys: `connection` — **where that machine is**, written once per
+physical machine rather than repeated in every script that drives it — and `probe` (§1.6)
+— whether to check that it still answers. The three kinds are treated alike because they
+are alike: each is a machine with an address that a run may find unreachable.
 
 ```yaml
 devices:
@@ -162,21 +231,25 @@ a script uses it.
 - a mode script with `flavor: sila2` requires **at least one** of that mode's `devices[]`
   to declare a `connection`;
 - a transport script with `flavor: sila2` requires that route's `transporter` to declare
-  one.
+  one — or, on a route with **no transporter** (§1.3), requires `endpoints: true` and at
+  least one of the devices at its ends to declare one, those being the machines that
+  perform such a move.
 
 A transport that declares `endpoints: true` is also handed the clients of the devices at
-either **end** of its route (§1.6), but those are *not* required to declare a `connection`:
+either **end** of its route (§1.7), but those are *not* required to declare a `connection`:
 a route through a plain holding location is ordinary, and the end without an address is
 simply not connected to (a **warning** when *neither* end has one, since then the request
-does nothing). The transporter is the one that must be reachable, because it is the machine
-that does the moving — and the one `sila2_client` names. Asking a `raw` script for endpoint
+does nothing — an **error** on a route with no transporter, which has nothing else to
+drive). The transporter is the one that must be reachable, because it is the machine that
+does the moving — and the one `sila2_client` names; where there is none, that is the source
+device, for the same reason. Asking a `raw` script for endpoint
 clients is an **error**: a raw script is handed no clients at all, so the request cannot be
 honoured.
 
 Declaring a `connection` on a device no script connects to is allowed — it is how an
 environment is prepared before the scripts that use it are written.
 
-### 1.5 Availability — `probe`
+### 1.6 Availability — `probe`
 
 A machine that stops answering should not keep receiving work. A `probe` policy asks labcode
 to check the machines it knows how to reach, and to tell the scheduler about the ones it
@@ -263,7 +336,7 @@ belongs — as the operation that tried to command it failing.
   document is still validated, so an environment that is wrong about probing stays wrong).
   Each machine whose reachability changes is reported on stderr.
 
-### 1.6 Calling convention (`flavor: sila2`)
+### 1.7 Calling convention (`flavor: sila2`)
 
 A `sila2` script is the **commands alone**: labcode opens a client to each of the
 operation's machines, runs the code with them in scope, and closes them afterwards. On top
@@ -271,8 +344,8 @@ of the input ports of §1.2 (or the transport locals of §1.3), the code sees:
 
 | name | meaning |
 |---|---|
-| `sila2_clients` | the clients by **machine id**, in the order the operation holds its machines: a mode's `devices[]` order, or — for a transport — its `transporter`, followed by the devices at either **end of the route** when it declares `endpoints: true` |
-| `sila2_client` | the first of them — for a transport always its `transporter`; the one name a single-machine operation needs |
+| `sila2_clients` | the clients by **machine id**, in the order the operation names its machines: a mode's `devices[]` order, or — for a transport — its `transporter` (absent on a route that has none, §1.3), followed by the devices at either **end of the route** when it declares `endpoints: true`. Named, not held: a mode declaring `device_access: false` (ofplang-schedule §4.4.2) rests on its devices rather than occupying them, and its script is still handed their clients |
+| `sila2_client` | the first of them — for a transport its `transporter`, or the **source device** on a route with none (§1.3); the one name a single-machine operation needs |
 
 ```yaml
 x-labcode:
@@ -301,6 +374,12 @@ x-labcode:
   property of the move, not of the lab. A route that does not ask still *holds* both ends, so
   reaching for one is answered with what to add rather than with silence.
 
+  On a route with **no transporter** (§1.3) a `sila2` script must ask: the ends are the only
+  machines there are, so not asking leaves nothing to open, and the front door says so rather
+  than letting the move fail when it runs. It is still asked for, not assumed — which
+  machines a script drives is the author's to state, and nowhere more so than where the
+  machine doing the moving is also the one holding the material.
+
   ```yaml
   transports:
     - transporter: arm
@@ -371,7 +450,7 @@ equally available to a `raw` script, and stays visible in the code that depends
   is to turn a hang into a diagnosable failure.
 - **It is the inner of two limits.** This one is per command, chosen by the script that
   knows what it is waiting for, and its failure can name the command that hung. The outer
-  one (§1.8) is per operation and lab-wide, and catches the hangs no script is watching
+  one (§1.9) is per operation and lab-wide, and catches the hangs no script is watching
   for. The outer default is looser than this one, so where both apply this is what fires.
 - **Its timeout is in real seconds**, and is unrelated to the mode's `duration` — which is
   an *estimate*, in environment time, for scheduling. A schedule's estimate is not a
@@ -381,11 +460,11 @@ equally available to a `raw` script, and stays visible in the code that depends
 - A `sila2` script is only interpreted where the dialect is — in an environment
   `x-labcode`. A workflow's own `script` (v0 §22) has no `flavor`.
 
-### 1.7 Where an `x-labcode` may appear
+### 1.8 Where an `x-labcode` may appear
 
 The positions of §1 are the only ones: the environment **root** (`probe` defaults and
-`op_timeout`), `processes.<p>.modes[]`, `transports[]`, `devices[]` and
-`transporters[]`. An `x-labcode`
+`op_timeout`), `processes.<p>.modes[]`, `transports[]`, `replenishments[]`, `devices[]`,
+`transporters[]` and `replenishers[]`. An `x-labcode`
 anywhere else in the environment — on a process, beside `time` — is an **error**, as is a
 key at a position that does not define it (a `connection` at the root, a `probe` on a mode).
 Nothing would read it, and `ofplang-schedule` tolerates an `x-` key at *every* position
@@ -395,7 +474,7 @@ This rule covers the environment only. An `x-labcode` in the **workflow** is not
 that document is portable v0, read by other implementations, and what extension keys it
 carries is not labcode's business.
 
-### 1.8 Operation timeout — `op_timeout`
+### 1.9 Operation timeout — `op_timeout`
 
 How long **one operation** may run before labcode stops waiting for it, in **real
 seconds**. It lives at the environment root and nowhere else:
@@ -410,7 +489,7 @@ x-labcode:
   way to say "no limit" and is an error; a machine may not declare one (a per-machine key
   is an unknown key, §1.1).
 - **One value for the whole lab.** The fine-grained waits belong to the scripts, which know
-  what they are waiting for (`settle`, §1.6.1); this value only has to clear the longest
+  what they are waiting for (`settle`, §1.7.1); this value only has to clear the longest
   operation the lab legitimately runs. Its default (7200 s) is twice the `settle` default,
   so where both apply the inner one — which can name the command — fires first.
 - **The clock is real seconds**, from the moment the operation starts, covering everything
@@ -422,13 +501,13 @@ x-labcode:
   failure — the run stops, the status document is written, the reason is reported, the exit
   code is 1 — which is the point: without a limit, an instrument that stops answering
   leaves a run polling with *no* status document and no reason at all.
-- **A timeout is not a cancel**, exactly as in §1.6.1: nothing here can stop a command the
+- **A timeout is not a cancel**, exactly as in §1.7.1: nothing here can stop a command the
   instrument has already accepted. It keeps running, and the state that leaves behind —
   including material a transport was part way through moving — is the operator's to
   restore. The run stops there, so labcode's own picture of the lab is not relied on
   afterwards.
 - The machine that hung is **not** treated as unavailable: `op_timeout` does not add it to
-  the down machines (§1.5), because "not answering" is not "not there", and re-routing work
+  the down machines (§1.6), because "not answering" is not "not there", and re-routing work
   onto other machines while this one is still physically running its command would make the
   lab less consistent, not more.
 - `lc run` overrides it for one run: `--op-timeout SECONDS`, or `--no-op-timeout` for no
@@ -450,6 +529,11 @@ For a dispatched `(process, mode)`, labcode resolves the code to run in this ord
 will run as a typed-default no-op. This is allowed — convenient while mocking a device —
 but `lc run` warns about it, so an unimplemented device is not silently a no-op.
 
+**Transport and replenishment routes have no such chain.** There is nothing for them to
+fall back to: a workflow describes neither a physical move nor a refill, so the route's
+own `x-labcode.script` is the only source. A route without one runs as a plain timed
+activity (§1.3, §1.4), warned about for the same reason as above.
+
 ## 3. Execution model
 
 Each dispatched operation runs in its own child process (real, wall-clock-paced); the
@@ -457,7 +541,7 @@ runner discovers completion by polling, so a multi-minute computation never bloc
 The advisory `duration` is the scheduler's estimate; the real duration is the script's.
 A script error (an exception, a wrong/ missing output name, a non-conformant value) is a
 graceful runtime failure (§22.2): the operation ends `failed` and the run stops. An
-operation that never finishes at all ends the same way once it passes `op_timeout` (§1.8) —
+operation that never finishes at all ends the same way once it passes `op_timeout` (§1.9) —
 polling for completion is not the same as waiting forever for it.
 
 Cadence: the nominal poll period is `poll_interval × seconds_per_tick`. labcode defaults
@@ -503,7 +587,7 @@ statement that the cycle was cheap.
 
 So: keep the budget comfortably larger than the cycle cost. What the cycle costs is not
 fixed — replanning grows with the workflow, and a dialect step such as availability probing
-(§1.5) can add seconds — so the margin wants to be generous rather than exact. A run whose
+(§1.6) can add seconds — so the margin wants to be generous rather than exact. A run whose
 recorded times matter (a checked-in example, a comparison against the plan's estimates)
 needs this to hold; a run that only has to *complete* does not.
 
@@ -562,9 +646,13 @@ ids per physical Object swaps in `RealUuid4Generator` (via
 
 ## 5. Not yet in this version (roadmap)
 
+- **`flavor: sila2` on a replenishment route** — refused today (§1.4). What has to be
+  settled first is which machine's clients a refill script receives: the replenisher's
+  alone, or both ends' as a transport route may ask for with `endpoints`. Until then a
+  refill that must speak SiLA2 uses a `raw` script and connects for itself.
 - **A deeper probe** — asking a machine something (a SiLA2 property read) rather than only
   opening a connection to it, so "answering" can be checked and not just "listening"
-  (§1.5). It would be an opt-in depth, since it costs a real exchange per check.
+  (§1.6). It would be an opt-in depth, since it costs a real exchange per check.
 - **Probing in parallel** — checking machines concurrently, so a lab with many unreachable
-  machines does not pay for them one timeout at a time (§1.5).
-- **TLS** — the fields a secure connection needs, lifting the restriction in §1.4.
+  machines does not pay for them one timeout at a time (§1.6).
+- **TLS** — the fields a secure connection needs, lifting the restriction in §1.5.

{labcode-0.2.0 → labcode-0.3.1}/examples/README.md

@@ -136,7 +136,7 @@ x-labcode:
 
 What the flavor supplies is connections, nothing more. Waiting for an *observable* command to
 finish stays in the script — but the loop itself does not have to be rewritten each time:
-labcode ships `settle` in **`labcode.sila2_commands`** (§1.6.1), reached by the ordinary import
+labcode ships `settle` in **`labcode.sila2_commands`** (§1.7.1), reached by the ordinary import
 above. Nothing is injected, so a script that does not import it does not have it, and a `raw`
 script has exactly the same access as this one. A live connection is worth a name that appears
 out of nowhere; an import is not.
@@ -149,14 +149,14 @@ instrument carries on, leaving the lab for the operator to restore.
 The names a script hands a machine still have to be the ones that machine knows — for the arm
 those are its **station** names (`Base1`, `Base4`, …), not labcode's `device.spot`, and one it
 does not know fails with `InvalidStation` at the moment of use. See
-[`../SPECIFICATIONS.md`](../SPECIFICATIONS.md) §1.4 and §1.6, and the plate-cycle section below
+[`../SPECIFICATIONS.md`](../SPECIFICATIONS.md) §1.5 and §1.7, and the plate-cycle section below
 for why the two vocabularies do not meet anywhere but in a transport script.
 
 ### If a machine stops answering
 
 Neither environment here asks for it, but labcode can **check that a machine is reachable**
 and schedule around the ones that are not — see
-[`../SPECIFICATIONS.md`](../SPECIFICATIONS.md) §1.5. Adding this to a device (or a
+[`../SPECIFICATIONS.md`](../SPECIFICATIONS.md) §1.6. Adding this to a device (or a
 transporter) that declares a `connection`:
 
 ```yaml
@@ -175,7 +175,7 @@ run without editing the environment.
 
 Probing catches a machine that is not there; it does not catch one that accepted a command
 and never came back. That is what the **operation timeout** is for
-([`../SPECIFICATIONS.md`](../SPECIFICATIONS.md) §1.8): every operation has a real-seconds
+([`../SPECIFICATIONS.md`](../SPECIFICATIONS.md) §1.9): every operation has a real-seconds
 deadline (7200 s by default, declared lab-wide at the environment root as
 `x-labcode.op_timeout`), and one that passes it is stopped and failed with the reason
 `op_timeout` — a run that ends with a status document and a reason instead of one that
@@ -324,7 +324,7 @@ dependency runs one way, and the lab's world model is not labcode's to edit.
 **Lids and doors.** In the lab's world model a closed lid or door makes that spot inaccessible,
 and an item cannot be moved into or out of an inaccessible spot. So the transport that delivers
 the plate is what opens the instrument: three of the five routes declare `endpoints: true` and
-are handed clients for the devices at either end as well as for the arm (§1.6). That is sound
+are handed clients for the devices at either end as well as for the arm (§1.7). That is sound
 because the scheduler has already given the move both instruments for its whole duration —
 nothing else can be using them meanwhile.
 

{labcode-0.2.0 → labcode-0.3.1}/examples/run_sila2_plate_cycle.py

@@ -325,6 +325,18 @@ def main(argv: list[str] | None = None) -> int:
         print(f"makespan        : {status.get('now')}")
         print(f"result boundary : {result.result_boundary}")
 
+        # Why the run stopped, when it did. `RunResult.failure` (D36) is a machine-readable
+        # `kind` and a human-readable `detail` -- the reason the failing operation gave, which
+        # `lc run` prints and this script was discarding. The status document names the
+        # activities that did not complete but never says why any of them failed, so without
+        # this the operator is left to guess between an instrument that refused the command,
+        # one that stopped answering, and a station name the arm does not have.
+        if result.failed and result.failure is not None:
+            print(
+                f"run failure     : {result.failure.kind}: {result.failure.detail}",
+                file=sys.stderr,
+            )
+
         try:
             check_outcome(status, result.result_boundary, observation)
         except CheckFailed as error:

{labcode-0.2.0 → labcode-0.3.1}/examples/run_sila2_seal.py

@@ -281,6 +281,22 @@ def main(argv: list[str] | None = None) -> int:
         print(f"makespan        : {status.get('now')}")
         print(f"result boundary : {result.result_boundary}")
 
+        # Why the run stopped, when it did. `RunResult.failure` (D36) is a machine-readable
+        # `kind` and a human-readable `detail` -- the reason the failing operation gave, which
+        # `lc run` prints and this script was discarding. The status document names the
+        # activities that did not complete but never says why any of them failed, so without
+        # this the operator is left to guess between an instrument that refused the command,
+        # one that stopped answering, and a station name the arm does not have.
+        #
+        # It matters most here. This example is also the one that walks through what a run does
+        # when a machine stops answering -- before an operation and in the middle of one -- so
+        # the failure it exists to demonstrate was the failure it was declining to name.
+        if result.failed and result.failure is not None:
+            print(
+                f"run failure     : {result.failure.kind}: {result.failure.detail}",
+                file=sys.stderr,
+            )
+
         try:
             check_outcome(status, result.result_boundary, observation)
         except CheckFailed as error:

{labcode-0.2.0 → labcode-0.3.1}/labcode/backend.py

@@ -57,6 +57,7 @@ from labcode.extension import (
     script_endpoints,
     script_flavor,
     spot_device,
+    transport_label,
     transporter_connections,
 )
 from labcode.idgen import DEFAULT_ID_GENERATOR, IdGenerator
@@ -245,8 +246,7 @@ def make_transport_resolver(environment: dict) -> Callable:
             code = _flavored(
                 code, script,
                 _transport_machines(transport, transporters, devices, script),
-                f"transport {transporter!r} "
-                f"{transport.get('from')} -> {transport.get('to')}",
+                transport_label(transport),
             )
         routes[key] = code