labcode 0.1.5__tar.gz → 0.1.7__tar.gz

{labcode-0.1.5 → labcode-0.1.7}/.github/workflows/ci.yml

@@ -14,8 +14,8 @@ jobs:
       matrix:
         python-version: ["3.10", "3.11", "3.12", "3.13"]
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
         with:
           python-version: ${{ matrix.python-version }}
           cache: pip
@@ -25,8 +25,8 @@ jobs:
   lint:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
         with:
           python-version: "3.12"
           cache: pip
@@ -38,8 +38,8 @@ jobs:
   typecheck:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
         with:
           python-version: "3.12"
           cache: pip
@@ -56,6 +56,6 @@ jobs:
   lock:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
       - uses: astral-sh/setup-uv@v7
       - run: uv lock --check

{labcode-0.1.5 → labcode-0.1.7}/.github/workflows/publish.yml

@@ -29,11 +29,11 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
         with:
           # setuptools-scm derives the version from tags + history.
           fetch-depth: 0
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v7
         with:
           python-version: "3.12"
       - run: python -m pip install --upgrade build twine
@@ -54,7 +54,7 @@ jobs:
             echo "::error::built version $built != tag $tag (ambiguous or misplaced tag?)"
             exit 1
           fi
-      - uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@v7
         with:
           name: dist
           path: dist/
@@ -69,7 +69,7 @@ jobs:
     permissions:
       id-token: write
     steps:
-      - uses: actions/download-artifact@v4
+      - uses: actions/download-artifact@v8
         with:
           name: dist
           path: dist/
@@ -87,7 +87,7 @@ jobs:
     permissions:
       id-token: write
     steps:
-      - uses: actions/download-artifact@v4
+      - uses: actions/download-artifact@v8
         with:
           name: dist
           path: dist/

labcode-0.1.7/PKG-INFO

@@ -0,0 +1,242 @@
+Metadata-Version: 2.4
+Name: labcode
+Version: 0.1.7
+Summary: labcode -- a dialect wrapper over the Object-Flow Programming Language toolchain
+Author-email: Kazunari Kaizu <kwaizu@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ofplang/labcode
+Project-URL: Repository, https://github.com/ofplang/labcode
+Keywords: ofplang,labcode,dataflow,workflow,cli
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Compilers
+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.1.3
+Requires-Dist: ofplang-run>=0.1.13
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+Requires-Dist: opentelemetry-sdk>=1.20; extra == "test"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: ruff>=0.16; extra == "dev"
+Requires-Dist: mypy>=1.11; extra == "dev"
+Requires-Dist: opentelemetry-sdk>=1.20; extra == "dev"
+Provides-Extra: sila2
+Requires-Dist: sila2>=0.14; extra == "sila2"
+Provides-Extra: otel
+Requires-Dist: opentelemetry-api>=1.20; extra == "otel"
+Requires-Dist: opentelemetry-sdk>=1.20; extra == "otel"
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.20; extra == "otel"
+Dynamic: license-file
+
+# labcode
+
+[![CI](https://github.com/ofplang/labcode/actions/workflows/ci.yml/badge.svg)](https://github.com/ofplang/labcode/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/labcode.svg)](https://pypi.org/project/labcode/)
+
+The **`lc`** command-line interface for the **labcode** dialect of the
+**Object-flow Programming Language**. Installing this one package pulls in the
+ofplang toolchain and exposes it under a single command:
+
+```sh
+lc validate ...   # check a workflow is well-formed portable v0
+lc schedule ...   # compute a schedule for a workflow
+lc run ...        # execute a workflow on the labcode backend
+```
+
+labcode is where a site-specific dialect and a custom runner (real lab hardware)
+are developed on top of the ofplang toolchain. `lc validate` and `lc schedule`
+forward to the ofplang siblings unchanged; **`lc run` is the labcode dialect's own
+runner**: it drives the workflow on the labcode backend, running each device
+operation's script — supplied in the environment as an `x-labcode.script` extension
+on a process mode — out-of-process on a wall clock, so a long-running real operation
+never blocks the replan loop. See [`SPECIFICATIONS.md`](SPECIFICATIONS.md) for the
+`x-labcode` extension.
+
+```yaml
+# in the execution environment: how a (process, mode) is carried out
+processes:
+  measure_od:
+    modes:
+      - id: v0
+        duration: 45
+        x-labcode:
+          script:
+            language: python
+            code: |
+              return {"od": read_plate(plate)}
+```
+
+## Install
+
+```sh
+pip install labcode
+```
+
+Requires Python 3.10+. `lc validate` and `lc schedule` are dispatched to the ofplang
+sibling packages unchanged; `lc run` is this package's own runner, built on them:
+
+- [`ofplang-validate`](https://github.com/ofplang/validate) — the validator
+- [`ofplang-schedule`](https://github.com/ofplang/schedule) — the scheduler
+- [`ofplang-run`](https://github.com/ofplang/run) — the runner / simulator
+
+The language is defined in the [ofplang/spec](https://github.com/ofplang/spec)
+repository, and what labcode adds to it in [`SPECIFICATIONS.md`](SPECIFICATIONS.md).
+
+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 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`).
+- **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]`,
+  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 a span per SiLA2 connection and
+  command measured inside the process that issued it. Off by default; the extra is
+  `pip install labcode[otel]`.
+
+## Usage
+
+Each subcommand keeps its own options, exit codes, and `--help`:
+
+```sh
+lc --help            # top-level help
+lc <command> --help  # command-specific options
+lc --version
+```
+
+`lc` can also be run as a module: `python -m labcode <command> ...`.
+
+`lc validate` and `lc schedule` are the ofplang siblings' own CLIs unchanged, so their
+options are documented in those repositories. `lc run` is this package's own, and is
+described below.
+
+### `lc run`
+
+```sh
+lc run <workflow> --env <env>
+    [--boundary DOC] [-o OUT] [--boundary-out FILE] [--observation-out FILE]
+    [--seconds-per-tick S] [--op-timeout S | --no-op-timeout] [--no-probe]
+    [--trace] [--mission-id ID] [--object-ids seeded|real]
+```
+
+- `<workflow>` — the portable v0 workflow: *what* happens.
+- `--env` (required) — the labcode environment: the execution environment (spec §5) plus
+  the `x-labcode` extension saying *how* each operation is carried out.
+- `--boundary DOC` — the whole-workflow I/O as one document: a `boundary:` mapping with a
+  `{spot, view}` descriptor per entry input / final output port. `spot` says where a
+  boundary Object sits; `view` supplies an input's value. A workflow with Object-bearing
+  entry inputs needs one, since each must be placed on a spot and only the operator knows
+  where the labware is.
+- `-o OUT` — write the final execution status (spec §6/§7) here; the default is stdout.
+- `--boundary-out FILE` — write the result boundary: the same schema as `--boundary`, with
+  each produced output's `view` filled in, including the `_id` its Object was minted with
+  (§4) — which is how one checks that the plate that came back is the plate that went in.
+- `--observation-out FILE` — stream the observation document: each *completed* activity's
+  concrete input / output view values, appended as it finishes. What the instruments
+  reported, as against the status document's timings.
+- `--seconds-per-tick S` — real seconds per environment time tick (default 20). Durations
+  in the environment are counted in ticks, and this is what maps them onto the wall clock.
+  The default is deliberately coarse, so that a real operation's dispatch → running →
+  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`,
+  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.
+- `--trace` — record what the run did (see below). Off by default.
+- `--mission-id ID` — the campaign this run belongs to. Recorded with the run and given no
+  meaning by labcode: several runs may share one, and nothing here reads it back.
+- `--object-ids seeded|real` — how Object `_id`s are minted: `seeded` is reproducible (the
+  same workflow yields the same ids every run, which is what keeps the examples' recorded
+  output stable), `real` is unique per run. Unset, it follows `--trace`.
+
+Exit codes: `0` the run completed, `1` it failed (an activity failed, a contract was
+violated, an operation timed out, or a replan became infeasible), `2` a usage or input
+error — including a workflow or an `x-labcode` extension the front doors reject.
+
+A complete invocation, against this repository's `examples/` (`--seconds-per-tick` small
+because that example's scripts return instantly):
+
+```sh
+lc run examples/plate_line.workflow.yaml --env examples/plate_line.env.yaml \
+  --boundary examples/plate_line.boundary.yaml --seconds-per-tick 0.2
+```
+
+The remaining options tune the replan loop rather than describe the run —
+`--poll-interval`, `--margin`, `--seed`, `--speed`, `--max-ticks`, `--no-validate` — and
+are covered by `lc run --help`.
+
+### Recording a run
+
+`--trace` records what the run did as OpenTelemetry traces. It needs the extra, in the
+interpreter that drives the run — which is also the one that runs the scripts, since
+labcode launches each with `sys.executable`:
+
+```sh
+pip install 'labcode[otel]'
+lc run <workflow> --env <env> --trace --mission-id M-2026-001
+```
+
+One run is one trace, and the id it can be found by is printed to stderr as the run starts:
+
+```text
+run                                  mission.id, and the failure if it stopped on one
+├─ process Seal                      which node, process and mode; the plan's interval;
+│  │                                 which Objects it handled
+│  ├─ sila2.connect                  the address, measured in the process that connected
+│  └─ sila2 SealerControl.Seal       the command, from its start to its real completion
+└─ transport                         the route and the transporter
+```
+
+An operation's span is opened when it is dispatched and closed when a poll finds it
+finished, so its end is late by up to one poll period; what an instrument actually spent is
+in the command spans, which are measured where the commands are issued. `ofp.object.id`
+lists the `_id`s an operation handled, including one it created — which is what makes
+"everything that happened to this plate" a single query.
+
+Where the record goes is configured by the **standard `OTEL_*` environment variables**
+(`OTEL_EXPORTER_OTLP_ENDPOINT`, `OTEL_RESOURCE_ATTRIBUTES`, `OTEL_SERVICE_NAME`, …), so
+labcode adds no settings of its own; `service.name` falls back to `labcode` if nothing sets
+it. `LC_TRACE_FILE=path` additionally writes the spans to a file as JSON lines, one file per
+process (the name gets the process id), which is how a record can be read without standing
+up a collector.
+
+Two things to know before pointing a run at a collector. **`--trace` makes Object `_id`s
+real rather than reproducible** unless `--object-ids` says otherwise, since a reproducible id
+is the same on every run and would collapse several runs' plates into one. And **a collector
+that is configured but does not answer delays each operation**, by as long as
+OpenTelemetry's own export timeout allows: labcode sets no timeout of its own, so
+`OTEL_EXPORTER_OTLP_TIMEOUT` is the knob, and it belongs to whoever pointed the run there.
+
+## Examples
+
+[`examples/`](examples/README.md) holds three worked runs: `plate_line`, an
+Object-bearing line driven entirely by environment scripts and runnable with no
+hardware, and `sila2_seal` and `sila2_plate_cycle`, which drive the reference lab's
+SiLA2 servers for real. `sila2_seal` also walks through what a run does when a
+machine stops answering — before an operation, and in the middle of one.
+
+## License
+
+MIT

labcode-0.1.7/README.md

@@ -0,0 +1,201 @@
+# labcode
+
+[![CI](https://github.com/ofplang/labcode/actions/workflows/ci.yml/badge.svg)](https://github.com/ofplang/labcode/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/labcode.svg)](https://pypi.org/project/labcode/)
+
+The **`lc`** command-line interface for the **labcode** dialect of the
+**Object-flow Programming Language**. Installing this one package pulls in the
+ofplang toolchain and exposes it under a single command:
+
+```sh
+lc validate ...   # check a workflow is well-formed portable v0
+lc schedule ...   # compute a schedule for a workflow
+lc run ...        # execute a workflow on the labcode backend
+```
+
+labcode is where a site-specific dialect and a custom runner (real lab hardware)
+are developed on top of the ofplang toolchain. `lc validate` and `lc schedule`
+forward to the ofplang siblings unchanged; **`lc run` is the labcode dialect's own
+runner**: it drives the workflow on the labcode backend, running each device
+operation's script — supplied in the environment as an `x-labcode.script` extension
+on a process mode — out-of-process on a wall clock, so a long-running real operation
+never blocks the replan loop. See [`SPECIFICATIONS.md`](SPECIFICATIONS.md) for the
+`x-labcode` extension.
+
+```yaml
+# in the execution environment: how a (process, mode) is carried out
+processes:
+  measure_od:
+    modes:
+      - id: v0
+        duration: 45
+        x-labcode:
+          script:
+            language: python
+            code: |
+              return {"od": read_plate(plate)}
+```
+
+## Install
+
+```sh
+pip install labcode
+```
+
+Requires Python 3.10+. `lc validate` and `lc schedule` are dispatched to the ofplang
+sibling packages unchanged; `lc run` is this package's own runner, built on them:
+
+- [`ofplang-validate`](https://github.com/ofplang/validate) — the validator
+- [`ofplang-schedule`](https://github.com/ofplang/schedule) — the scheduler
+- [`ofplang-run`](https://github.com/ofplang/run) — the runner / simulator
+
+The language is defined in the [ofplang/spec](https://github.com/ofplang/spec)
+repository, and what labcode adds to it in [`SPECIFICATIONS.md`](SPECIFICATIONS.md).
+
+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 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`).
+- **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]`,
+  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 a span per SiLA2 connection and
+  command measured inside the process that issued it. Off by default; the extra is
+  `pip install labcode[otel]`.
+
+## Usage
+
+Each subcommand keeps its own options, exit codes, and `--help`:
+
+```sh
+lc --help            # top-level help
+lc <command> --help  # command-specific options
+lc --version
+```
+
+`lc` can also be run as a module: `python -m labcode <command> ...`.
+
+`lc validate` and `lc schedule` are the ofplang siblings' own CLIs unchanged, so their
+options are documented in those repositories. `lc run` is this package's own, and is
+described below.
+
+### `lc run`
+
+```sh
+lc run <workflow> --env <env>
+    [--boundary DOC] [-o OUT] [--boundary-out FILE] [--observation-out FILE]
+    [--seconds-per-tick S] [--op-timeout S | --no-op-timeout] [--no-probe]
+    [--trace] [--mission-id ID] [--object-ids seeded|real]
+```
+
+- `<workflow>` — the portable v0 workflow: *what* happens.
+- `--env` (required) — the labcode environment: the execution environment (spec §5) plus
+  the `x-labcode` extension saying *how* each operation is carried out.
+- `--boundary DOC` — the whole-workflow I/O as one document: a `boundary:` mapping with a
+  `{spot, view}` descriptor per entry input / final output port. `spot` says where a
+  boundary Object sits; `view` supplies an input's value. A workflow with Object-bearing
+  entry inputs needs one, since each must be placed on a spot and only the operator knows
+  where the labware is.
+- `-o OUT` — write the final execution status (spec §6/§7) here; the default is stdout.
+- `--boundary-out FILE` — write the result boundary: the same schema as `--boundary`, with
+  each produced output's `view` filled in, including the `_id` its Object was minted with
+  (§4) — which is how one checks that the plate that came back is the plate that went in.
+- `--observation-out FILE` — stream the observation document: each *completed* activity's
+  concrete input / output view values, appended as it finishes. What the instruments
+  reported, as against the status document's timings.
+- `--seconds-per-tick S` — real seconds per environment time tick (default 20). Durations
+  in the environment are counted in ticks, and this is what maps them onto the wall clock.
+  The default is deliberately coarse, so that a real operation's dispatch → running →
+  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`,
+  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.
+- `--trace` — record what the run did (see below). Off by default.
+- `--mission-id ID` — the campaign this run belongs to. Recorded with the run and given no
+  meaning by labcode: several runs may share one, and nothing here reads it back.
+- `--object-ids seeded|real` — how Object `_id`s are minted: `seeded` is reproducible (the
+  same workflow yields the same ids every run, which is what keeps the examples' recorded
+  output stable), `real` is unique per run. Unset, it follows `--trace`.
+
+Exit codes: `0` the run completed, `1` it failed (an activity failed, a contract was
+violated, an operation timed out, or a replan became infeasible), `2` a usage or input
+error — including a workflow or an `x-labcode` extension the front doors reject.
+
+A complete invocation, against this repository's `examples/` (`--seconds-per-tick` small
+because that example's scripts return instantly):
+
+```sh
+lc run examples/plate_line.workflow.yaml --env examples/plate_line.env.yaml \
+  --boundary examples/plate_line.boundary.yaml --seconds-per-tick 0.2
+```
+
+The remaining options tune the replan loop rather than describe the run —
+`--poll-interval`, `--margin`, `--seed`, `--speed`, `--max-ticks`, `--no-validate` — and
+are covered by `lc run --help`.
+
+### Recording a run
+
+`--trace` records what the run did as OpenTelemetry traces. It needs the extra, in the
+interpreter that drives the run — which is also the one that runs the scripts, since
+labcode launches each with `sys.executable`:
+
+```sh
+pip install 'labcode[otel]'
+lc run <workflow> --env <env> --trace --mission-id M-2026-001
+```
+
+One run is one trace, and the id it can be found by is printed to stderr as the run starts:
+
+```text
+run                                  mission.id, and the failure if it stopped on one
+├─ process Seal                      which node, process and mode; the plan's interval;
+│  │                                 which Objects it handled
+│  ├─ sila2.connect                  the address, measured in the process that connected
+│  └─ sila2 SealerControl.Seal       the command, from its start to its real completion
+└─ transport                         the route and the transporter
+```
+
+An operation's span is opened when it is dispatched and closed when a poll finds it
+finished, so its end is late by up to one poll period; what an instrument actually spent is
+in the command spans, which are measured where the commands are issued. `ofp.object.id`
+lists the `_id`s an operation handled, including one it created — which is what makes
+"everything that happened to this plate" a single query.
+
+Where the record goes is configured by the **standard `OTEL_*` environment variables**
+(`OTEL_EXPORTER_OTLP_ENDPOINT`, `OTEL_RESOURCE_ATTRIBUTES`, `OTEL_SERVICE_NAME`, …), so
+labcode adds no settings of its own; `service.name` falls back to `labcode` if nothing sets
+it. `LC_TRACE_FILE=path` additionally writes the spans to a file as JSON lines, one file per
+process (the name gets the process id), which is how a record can be read without standing
+up a collector.
+
+Two things to know before pointing a run at a collector. **`--trace` makes Object `_id`s
+real rather than reproducible** unless `--object-ids` says otherwise, since a reproducible id
+is the same on every run and would collapse several runs' plates into one. And **a collector
+that is configured but does not answer delays each operation**, by as long as
+OpenTelemetry's own export timeout allows: labcode sets no timeout of its own, so
+`OTEL_EXPORTER_OTLP_TIMEOUT` is the knob, and it belongs to whoever pointed the run there.
+
+## Examples
+
+[`examples/`](examples/README.md) holds three worked runs: `plate_line`, an
+Object-bearing line driven entirely by environment scripts and runnable with no
+hardware, and `sila2_seal` and `sila2_plate_cycle`, which drive the reference lab's
+SiLA2 servers for real. `sila2_seal` also walks through what a run does when a
+machine stops answering — before an operation, and in the middle of one.
+
+## License
+
+MIT

{labcode-0.1.5 → labcode-0.1.7}/SPECIFICATIONS.md

@@ -306,7 +306,7 @@ x-labcode:
     - transporter: arm
       from: plateloc.stage
       to: thermal_cycler.block
-      duration: 8
+      duration: 43
       x-labcode:
         script:
           language: python
@@ -317,9 +317,10 @@ x-labcode:
 
             cycler = sila2_clients["thermal_cycler"].AutomatedThermalCyclerController
             settle(cycler.OpenLid(), "OpenLid")
-            arm = sila2_client.TrolleyArmProvider   # the transporter: still the first client
-            arm.Pick(LocationSpecifier="plateloc.stage")
-            arm.Place(LocationSpecifier="thermal-cycler.block")
+            # The transporter is still the first client. Its own names for the places it
+            # serves are stations, not `device.spot`, so a route writes them out.
+            labware = sila2_client.LabwareService
+            settle(labware.Transfer(SourceStation="Base4", DestinationStation="Base6"), "Transfer")
   ```
 - **Connections last one operation**, opened before the code runs and closed after it — on
   any exit, including a `return` or an exception, and including a *later* connection
@@ -367,8 +368,11 @@ equally available to a `raw` script, and stays visible in the code that depends
   `settle` that times out fails the *operation* while the instrument carries on. Whatever
   state that leaves the lab in is the operator's to restore, as for any operation that
   failed part way. The default timeout is therefore generous rather than tight: its purpose
-  is to turn a hang into a diagnosable failure, since nothing else in the stack bounds an
-  operation's running time.
+  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
+  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
   deadline, and `--seconds-per-tick` does not rescale the timeout.
@@ -379,8 +383,9 @@ equally available to a `raw` script, and stays visible in the code that depends
 
 ### 1.7 Where an `x-labcode` may appear
 
-The positions of §1 are the only ones: the environment **root** (`probe` defaults only),
-`processes.<p>.modes[]`, `transports[]`, `devices[]` and `transporters[]`. An `x-labcode`
+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`
 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
@@ -390,6 +395,45 @@ 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`
+
+How long **one operation** may run before labcode stops waiting for it, in **real
+seconds**. It lives at the environment root and nowhere else:
+
+```yaml
+x-labcode:
+  op_timeout: 7200      # a positive number of real seconds (the default)
+  # op_timeout: null    # or: wait as long as it takes
+```
+
+- `op_timeout` MUST be a positive, finite number, or `null` for **no limit**. `0` is not a
+  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
+  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
+  it does: connecting, every command it issues, and its own waiting. It is unrelated to the
+  mode's `duration` (an *estimate*, in environment time, for scheduling) and is not
+  rescaled by `--seconds-per-tick`.
+- **What happens when it expires**: the operation's child process is stopped and the
+  operation **fails** with the reason code `op_timeout`. That is an ordinary graceful
+  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
+  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
+  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
+  limit at all. The order is flag, then document, then default.
+
 ## 2. Code source resolution and exclusivity
 
 For a dispatched `(process, mode)`, labcode resolves the code to run in this order:
@@ -412,7 +456,9 @@ Each dispatched operation runs in its own child process (real, wall-clock-paced)
 runner discovers completion by polling, so a multi-minute computation never blocks it.
 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.
+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) —
+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
 `seconds_per_tick` to ~20 s (so a real op is polled at an observable cadence, not