labcode 0.1.3__tar.gz → 0.1.5__tar.gz

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

@@ -31,7 +31,9 @@ jobs:
           python-version: "3.12"
           cache: pip
       - run: pip install -e ".[dev]"
-      - run: ruff check labcode tests
+      # The whole tree, so `examples/` is linted too (ruff's own defaults skip
+      # build/venv dirs and honour .gitignore).
+      - run: ruff check .
 
   typecheck:
     runs-on: ubuntu-latest
@@ -43,3 +45,17 @@ jobs:
           cache: pip
       - run: pip install -e ".[dev]"
       - run: mypy
+
+  # `uv sync --extra sila2` is how a development environment gets built here, and
+  # uv.lock records what it produces. This asserts the lock still agrees with
+  # pyproject.toml, so a raised dependency floor or a new extra cannot leave the
+  # environment pinned to versions the project no longer accepts. It deliberately
+  # does not ask whether newer releases exist -- that is `uv lock --upgrade`, run
+  # when someone means to move. The jobs above stay on pip so they keep testing
+  # against the latest released siblings.
+  lock:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v7
+      - run: uv lock --check

labcode-0.1.5/MANIFEST.in

@@ -0,0 +1,6 @@
+# setuptools-scm hands the sdist every file git tracks, and uv.lock is tracked so
+# that the versions a developer actually gets stay reviewable. That lock describes
+# the development environment only -- an installer resolves the wheel's dependency
+# metadata and never reads it -- so it has no business in the distribution, where
+# it would roughly double the sdist. Excluded here; still in the repository.
+exclude uv.lock

{labcode-0.1.3 → labcode-0.1.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: labcode
-Version: 0.1.3
+Version: 0.1.5
 Summary: labcode -- a dialect wrapper over the Object-Flow Programming Language toolchain
 Author-email: Kazunari Kaizu <kwaizu@gmail.com>
 License-Expression: MIT

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

@@ -49,6 +49,10 @@ still validates and schedules as plain v0. Only labcode interprets it.
     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.
+  - `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.
 
 **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;
@@ -160,6 +164,15 @@ a script uses it.
 - a transport script with `flavor: sila2` requires that route's `transporter` to declare
   one.
 
+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`:
+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
+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.
 
@@ -258,8 +271,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 **device id** (`transporter id` for a transport), in `devices[]` order, holding **only** the machines that declared a `connection` |
-| `sila2_client` | the first of them — the one name a single-machine operation needs |
+| `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 |
 
 ```yaml
 x-labcode:
@@ -275,13 +288,92 @@ x-labcode:
   parameters, so an input port of the same name would be silently overwritten by a client;
   a process that declares one is rejected at the front door (as a `_id` view field is,
   §4.1).
-- **One connection per operation**, opened before the code runs and closed after it — on
+- **A transport may be handed all three of the machines it holds** — `endpoints: true`. A
+  transport activity occupies the source device, the destination device *and* the transporter
+  for its whole body (`ofplang-schedule` SPECIFICATIONS §4.5), so all three are its to
+  command: that is what lets the move that needs a lid open be the move that opens it, and
+  nothing else can be using either instrument meanwhile, because the scheduler has given them
+  both to this move.
+
+  It is **off unless asked for**, per route. A move that drives nothing but its transporter
+  should pay for one connection rather than three, and should not begin to fail because an
+  instrument it merely hands a plate to is switched off — while needing to open a lid is a
+  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.
+
+  ```yaml
+  transports:
+    - transporter: arm
+      from: plateloc.stage
+      to: thermal_cycler.block
+      duration: 8
+      x-labcode:
+        script:
+          language: python
+          flavor: sila2
+          endpoints: true        # ...so the lid can be opened before the plate arrives
+          code: |
+            from labcode.sila2_commands import settle
+
+            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")
+  ```
+- **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
   failing after an earlier one opened. There is no pooling and no reconnection: reaching an
   instrument is assumed, and failing to is an ordinary operation failure naming the machine.
+  A machine that declares a `connection` is connected to whether or not the script uses it,
+  so the cost of an operation follows the machines it **holds**, not the ones it commands.
+- **A machine held without a client explains itself.** An operation may hold a machine it
+  cannot reach — a plain holding device declares no `connection` — and that machine is
+  absent from `sila2_clients` (`in`, `.get()` and iteration all say so). *Indexing* it is
+  different: it yields a stand-in that is **falsy**, so `if sila2_clients[id]:` reads as "is
+  there a client for it", and that fails the operation with **why** there is none
+  (`sila2_not_connected`, or `sila2_endpoints_not_requested` for an end of a route that did
+  not ask for it) if the script commands it anyway. Indexing an id the operation does not
+  hold at all raises instead, naming what it does hold: that is a typo, and a falsy stand-in
+  would let it survive until something stranger happened later.
 - **Everything else is still the script's own.** The flavor supplies connections, nothing
   more: waiting for an observable command to finish (the standard `sila2` polling pattern)
   belongs in the code, as it does in a `raw` script.
+
+#### 1.6.1 `labcode.sila2_commands` — the polling loop, written once
+
+Waiting for an observable command is the same loop in every script that issues one, so
+labcode ships it. It is an **ordinary module**, reached by an ordinary import — nothing is
+injected, and a script that does not import it does not have it:
+
+```yaml
+code: |
+  from labcode.sila2_commands import settle
+
+  feature = sila2_client.PlateLocController
+  settle(feature.StartCycle(), "StartCycle")
+  return {"cycle_count": int(feature.CycleCount.get())}
+```
+
+`settle(instance, label, *, timeout=3600.0, poll=1.0)` polls `instance` until it reports
+`done` and returns its `get_responses()`.
+
+This is deliberately *not* part of the calling convention above. A name that appears out of
+nowhere is worth spending only on what a script cannot obtain for itself — a live connection
+is that, an import is not — and keeping it an import means the helper reserves no name, is
+equally available to a `raw` script, and stays visible in the code that depends on it.
+
+- **A timeout is not a cancel.** SiLA2 offers no way to stop a command already issued, so a
+  `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.
+- **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.
+- **Passing an unobservable command's response is an error** (`sila2_not_observable`): such
+  a command has already finished when its call returns, and there is nothing to settle.
 - 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`.
 

labcode-0.1.5/examples/README.md

@@ -0,0 +1,396 @@
+# labcode examples
+
+## `plate_line` — an Object-bearing line, driven by environment scripts
+
+A `Plate` flows down a four-station line, a `Tube` is dispensed into it, and a
+measurement is read off it:
+
+```
+         (in) tube ──────────────┐
+                                  ▼
+load ──[move]──> dispense ──[move]──> read ──[move]──> store
+                     │                   │
+                (out) tube           (out) od
+```
+
+- [`plate_line.workflow.yaml`](plate_line.workflow.yaml) is **portable ofplang v0** — it
+  says only *what* happens. The whole workflow takes one `Tube` in and passes the *same*
+  Tube back out, alongside the Pure Data measurement `od`. `dispense` and `read` are
+  **Object-bearing**: their Objects go in and the *same* Objects come out (`objects.map` —
+  identity preserved). The Plate is created inside the workflow by `load`; the Tube enters
+  at the run boundary.
+- [`plate_line.boundary.yaml`](plate_line.boundary.yaml) is the **run boundary** (dev-notes
+  D28). It supplies the `Tube` input — an Object, so it names a `spot`: a standalone tube
+  `rack` slot bound to no process, where the Tube starts and returns (`Tube` has no view
+  fields, so no `view`). The arm carries it to the dispenser and back. It also names the
+  outputs `od` and `tube`, whose produced values are echoed in the result boundary.
+- [`plate_line.env.yaml`](plate_line.env.yaml) is the **labcode environment** — it says
+  *how* each step is carried out, as an `x-labcode.script` (see [`../SPECIFICATIONS.md`](../SPECIFICATIONS.md)).
+  **Every process mode and every transport route carries a script**: `load` makes the
+  Plate, `dispense` dispenses the Tube into the Plate (both Objects are carried through by
+  `objects.map`, so its script returns nothing), `read` measures `od` (the Plate is
+  carried, so the script returns only what it computes — labcode's *partial outputs*, see
+  the spec), `store` takes it; the transport scripts perform the move and may read the
+  moved Plate's `view` (its barcode).
+
+labcode runs each script **out-of-process** on a wall clock, discovering completion by
+polling — so a real, slow device operation never blocks the runner.
+
+### Run it
+
+```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
+```
+
+`--seconds-per-tick` sets the real seconds per environment time tick; it defaults to a
+coarse value suited to real hardware, so a small value here keeps the demo quick. The run
+completes with every activity `completed`; the produced measurement (`od = 0.42`) can be
+written out with `--boundary-out result.yaml`.
+
+### Produce the outputs
+
+[`render_plate_line.py`](render_plate_line.py) drives the same run on the labcode backend
+and writes its artifacts under [`outputs/`](outputs/):
+
+```sh
+python examples/render_plate_line.py
+```
+
+- [`outputs/plate_line.plan.yaml`](outputs/plate_line.plan.yaml) — the **final execution
+  schedule** (the §6/§7 status document: every activity, `completed`).
+- [`outputs/plate_line.observation.yaml`](outputs/plate_line.observation.yaml) — the
+  **observation document** (D38): each completed activity's I/O views, as `lc run
+  --observation-out` would stream it.
+- [`outputs/plate_line.svg`](outputs/plate_line.svg) — a **Gantt chart** of that schedule
+  (device view), drawn by the scheduler's visualizer. (The ofplang toolchain renders
+  SVG/HTML; open it in a browser, or convert to PNG with any SVG rasterizer.)
+- [`outputs/plate_line.boundary.yaml`](outputs/plate_line.boundary.yaml) — the **result
+  boundary**, echoing the produced `od` and the returned `tube` (as `--boundary-out`
+  writes it).
+
+Because the labcode backend runs each op out-of-process on a wall clock, the exact times
+(and makespan) may vary slightly between runs; the sequence and produced values do not.
+
+Every Object's view carries a reserved **`_id`** — labcode's implicit, value-layer Object
+identity (see [`../SPECIFICATIONS.md`](../SPECIFICATIONS.md) §4). In the observation you can
+follow the *same* Plate (one `_id`) from `load` through `dispense`/`read` to `store`, and
+the Tube's `_id` round-trips from the input boundary to the output. The ids are
+reproducible (a seeded, provenance-keyed generator), so these outputs are stable to
+re-generate.
+
+> The scripts here are mocks (they just return values / reference their locals). Replace a
+> script's body with real device calls — e.g. `robot.move(from_spot, to_spot)` in a
+> transport, or an instrument read in `read` — to drive real hardware; the code may
+> `import` anything the host Python can.
+
+## `sila2_seal` — the same idea, driven by real SiLA2 servers
+
+Where `plate_line`'s scripts are mocks that only return values, this example's scripts open
+SiLA2 connections and issue real commands. It is the integration check for labcode's SiLA2
+story: labcode schedules, dispatches out-of-process, a script talks SiLA2, an instrument acts,
+and the produced value comes back through labcode's partial outputs.
+
+```
+   (in) plate ──[move]──▶ seal ──[move]──▶ (out) plate
+                            │
+                    (out) cycle_count
+```
+
+- [`sila2_seal.workflow.yaml`](sila2_seal.workflow.yaml) is portable ofplang v0: one Plate in,
+  the *same* Plate out (`objects.map`), plus the Pure Data reading `cycle_count`.
+- [`sila2_seal.wrapped.env.yaml`](sila2_seal.wrapped.env.yaml) drives a plate sealer over SiLA2
+  and a transport arm's `Pick`/`Place`, written the **recommended** way — `flavor: sila2`.
+  `cycle_count` is **a real reading**: the script asks the instrument how many cycles it has
+  performed, and the number goes up because this run performed one.
+- [`sila2_seal.boundary.yaml`](sila2_seal.boundary.yaml) puts the Plate in and takes it out at
+  the *same* spot, so the run is a **round trip** and can be repeated without anyone putting
+  the world back.
+
+Each machine's address is declared **once**, on the device (or the transporter) that has it:
+
+```yaml
+devices:
+  - id: plateloc
+    spots: [stage]
+    x-labcode:
+      connection: { kind: sila2, host: 127.0.0.1, port: 50053, insecure: true }
+```
+
+…and each script is the **commands alone**. labcode opens `sila2_client` before the code runs
+and closes it afterwards — on a `return`, on an exception, and on a later connection failing
+after an earlier one opened:
+
+```yaml
+x-labcode:
+  script:
+    flavor: sila2
+    language: python
+    code: |
+      from labcode.sila2_commands import settle
+
+      feature = sila2_client.PlateLocController
+      settle(feature.StartCycle(), "StartCycle")   # the wait is still the script's own
+      return {"cycle_count": int(feature.CycleCount.get())}
+```
+
+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
+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.
+
+Note what `settle` is *not*. Its timeout is in real seconds, unrelated to the mode's `duration`
+(an estimate, for scheduling) and unscaled by `--seconds-per-tick`; and it cancels nothing — a
+SiLA2 command cannot be stopped from here, so a timeout fails the operation while the
+instrument carries on, leaving the lab for the operator to restore.
+
+Spot names still have to be the ones the lab declares — a name it does not know fails the move
+at the moment of use. See [`../SPECIFICATIONS.md`](../SPECIFICATIONS.md) §1.4 and §1.6.
+
+### 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
+transporter) that declares a `connection`:
+
+```yaml
+    x-labcode:
+      connection: { kind: sila2, host: 127.0.0.1, port: 50053, insecure: true }
+      probe: { enabled: true, interval: 60 }
+```
+
+…makes `lc run` report the machine when its reachability changes and plan without it while
+it is down. These two examples leave it out on purpose: each has exactly one sealer and one
+arm, so there is nothing to route around, and what a stopped lab should produce here is the
+instrument command failing where it was issued. `lc run --no-probe` turns probing off for a
+run without editing the environment.
+
+### Prerequisites
+
+**Verified against [ofplang-sila2-backend](https://github.com/kaizu/sila2-demo) v0.3.0 (commit
+`0c3c4c8`)** — a virtual lab of mock SiLA2 instrument servers. That lab is a *reference, not a
+requirement*: the scripts speak plain SiLA2, so pointing them at real instruments is a matter
+of changing the host and port in the environment. The version is recorded so a run without
+hardware has something known to reproduce against; it is deliberately not asserted on, since
+checking a server's name would be the one thing that stopped this working against hardware.
+
+```sh
+# in the reference lab
+docker compose up -d
+
+# here: the client library has to be importable by the interpreter that runs the scripts
+uv sync --extra sila2
+```
+
+The world must be at t=0 — one plate on `station.slot1`. The round trip puts it back, so
+repeated runs need no intervention; a run that failed part way may not have, and restoring the
+world is the **operator's** job, not the workflow's:
+
+```sh
+curl -X POST http://localhost:8001/reseed
+```
+
+### Run it
+
+```sh
+python examples/run_sila2_seal.py
+```
+
+Exit code 0 means every check passed, so this is a check rather than a demo. It asserts only on
+what a real client can see — the schedule, the produced boundary, the observation — and **never
+contacts the lab's world-state service**: that service stands in for the physical world, which
+exposes no such interface, so a client that read it could not be pointed at hardware.
+
+Pass `--artifacts DIR` to keep the run's status, observation and result boundary (they are
+otherwise written to a temporary directory, since their timings vary between runs).
+
+### The same run, with each script connecting for itself
+
+[`sila2_seal.env.yaml`](sila2_seal.env.yaml) drives the *same* workflow through the same
+motions with `raw` scripts: no `connection` on the devices, each script opening its own
+`SilaClient` (so the address appears in every script that talks to a machine, and closing it is
+the author's `with`), and its `settle` written out by hand rather than imported — not because a
+`raw` script may not import it, but because this file is the low-level reference and the loop
+is worth being able to read. It is what to write when the connection is not a plain SiLA2 one,
+or when the script needs to do something the flavor does not cover:
+
+```sh
+python examples/run_sila2_seal.py --env examples/sila2_seal.env.yaml
+```
+
+The two environments are interchangeable today but are **not promised to stay equivalent**; the
+`flavor: sila2` one is the example that follows the dialect.
+
+> **A device id cannot contain a hyphen.** v0 identifiers are `[A-Za-z_][A-Za-z0-9_]*`, which
+> rules out the reference lab's `seal-remover`, `thermal-cycler` and `trolley-arm`. This
+> example sidesteps it by using `plateloc`; [`sila2_plate_cycle`](#sila2_plate_cycle--the-whole-circuit-four-instruments-and-one-plate)
+> below cannot, and translates the names in its transport scripts instead. (The arm is fine
+> either way: labcode names the transporter `arm` and never names the arm's own spot.)
+
+## `sila2_plate_cycle` — the whole circuit: four instruments and one plate
+
+Where `sila2_seal` drives one instrument, this drives a line. One `Plate` is unsealed,
+resealed, thermal-cycled and spun down, carried between the four instruments by the arm, and
+returned to the spot it started from:
+
+```
+   (in) plate ──▶ peel ──▶ seal ──▶ thermal_cycle ──▶ rotate ──▶ (out) plate
+                    │        │            │
+           (out) tape_left   │     (out) elapsed_time
+                     (out) cycle_count
+```
+
+- [`sila2_plate_cycle.workflow.yaml`](sila2_plate_cycle.workflow.yaml) is portable ofplang v0:
+  one Plate in, the *same* Plate out, carried through all four steps by `objects.map`. Three
+  steps also report a reading; `rotate` reports nothing, because the centrifuge exposes no
+  counter — it is the example of a step that only carries its Object.
+- [`sila2_plate_cycle.wrapped.env.yaml`](sila2_plate_cycle.wrapped.env.yaml) drives the four
+  instruments and the arm with `flavor: sila2`. The command arguments are taken from the
+  delivery scripts in `ScriptsForIntegrationTest` (`snip_xpeel.py`, `snip_plateloc.py`,
+  `snip_atc.py`, `snip_microplate_centrifuge.py`), so what each instrument is asked to do here
+  is what those ask of the real hardware.
+- [`sila2_plate_cycle.boundary.yaml`](sila2_plate_cycle.boundary.yaml) puts the Plate in and
+  takes it out at `station.slot1`, so the circuit is a **round trip** like `sila2_seal`'s.
+
+Every reading is a real one: the seal remover's remaining supply-spool tape, the sealer's cycle
+count, and the thermal cycler's `hh:mm:ss` elapsed time — read after the run, so it is non-zero
+exactly because a run happened. And because the Plate's `_id` survives four handovers, the
+check can assert something a single-step run cannot: that all four instruments handled the
+*same* plate.
+
+This is the labcode counterpart of the reference lab's own `samples/run_roundabout.py`, with
+one difference that is the point of it: there, a script drives the circuit directly; here,
+labcode schedules it and dispatches each step, and each script only says what one step does.
+
+### Two things worth reading the environment for
+
+**Hyphens.** The lab's locations are `seal-remover.stage` and `thermal-cycler.block`, which no
+v0 identifier can spell. The environment names those devices `seal_remover` and
+`thermal_cycler`, and each transport script writes the lab's names out literally rather than
+passing `from_spot` / `to_spot` through:
+
+```yaml
+code: |
+  # labcode's plateloc.stage -> thermal_cycler.block.
+  arm = sila2_client.TrolleyArmProvider
+  arm.Pick(LocationSpecifier="plateloc.stage")
+  arm.Place(LocationSpecifier="thermal-cycler.block")
+```
+
+A route is one fixed pair of spots, so there is nothing to compute, and the name the lab
+actually receives is the name written in the file. Deriving it instead — `_` → `-` — would
+read as a rule, and it is not one: it is a coincidence of this lab's naming, and a real lab may
+have a device legitimately called `foo_bar`. The cost is that the route and the strings can
+drift apart if one is edited without the other; the lab is what catches that, since a name it
+does not know fails the move with `unknown_location`.
+
+Only transport scripts face this, because only they name spots. The lab is *not* renamed to
+suit labcode: the 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
+because the scheduler has already given the move both instruments for its whole duration —
+nothing else can be using them meanwhile.
+
+The convention the environment follows is that **an instrument is closed at rest**: a transport
+opens what it must to pick and to place and closes the source it emptied, and a process closes
+the instrument to work and leaves it closed. Delivering the plate to the thermal cycler
+therefore reads as: the transport opens the lid and places the plate; `thermal_cycle` closes it,
+runs, and leaves it closed; the next transport opens it, takes the plate out, and closes it
+again.
+
+```yaml
+x-labcode:
+  script:
+    flavor: sila2
+    endpoints: true
+    code: |
+      from labcode.sila2_commands import settle
+
+      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")
+```
+
+Closed-at-rest is what a real instrument does, and it is what makes this example *check*
+something rather than merely work. The lab starts with everything open, so the first run's
+`OpenLid` is a no-op — but every run after it starts with the cycler and the centrifuge closed
+and gets nowhere unless the transports really can open them. (`OpenLid` / `CloseLid` set the
+world's accessibility outright rather than toggling it, so calling one that is already true
+costs nothing.) The thing to know is that the plate is inside a closed instrument for part of
+the circuit, so a run that dies there leaves it there — an operator's job to retrieve, or a
+reseed, as for any run that fails half way.
+
+### Run it
+
+```sh
+python examples/run_sila2_plate_cycle.py
+```
+
+Same prerequisites as `sila2_seal` (the lab up, `sila2` importable, one plate on
+`station.slot1`), and the same conventions: exit code 0 means every check passed, and
+`--artifacts DIR` keeps the run's status, observation and result boundary. It needs no
+particular lid or door state to start from: the transports open what they need.
+
+Verified against both of the reference lab's timing profiles at `--seconds-per-tick 1.0`.
+Against `command_durations.realistic.yaml` — the profile the environment's durations are
+measured on — the circuit takes a makespan of about 110, and each step lands within its
+declared duration; against the default profile (which waits for nothing) every op finishes
+early and the run still completes.
+
+Those durations are the **measured operation times, not the instrument's**. An op also costs
+labcode a child process (~2 s), a SiLA2 client per machine it connects to (~1 s each, since
+building one fetches every Feature definition), and one poll interval per `settle` that
+finishes mid-interval. Both variable parts show: `thermal_cycle` turns 10 s of instrument time
+into 17 because all five of its commands are short, and the cycler → centrifuge move costs 17
+for 11 s of instrument time, opening two instruments and closing one across three clients.
+Declaring the instrument's time alone would under-run every op, and the scheduler would keep
+trying to dispatch a successor onto a device still finishing.
+
+### Produce the outputs
+
+[`render_sila2_plate_cycle.py`](render_sila2_plate_cycle.py) drives the same circuit and keeps
+its documents under [`outputs/`](outputs/), so the schedule can be read — and its Gantt chart
+looked at — without a lab to hand:
+
+```sh
+python examples/render_sila2_plate_cycle.py
+```
+
+- [`outputs/sila2_plate_cycle.plan.yaml`](outputs/sila2_plate_cycle.plan.yaml) — the **final
+  execution schedule** (the §6/§7 status document): nine activities, five transports and four
+  instrument steps, every one `completed`.
+- [`outputs/sila2_plate_cycle.observation.yaml`](outputs/sila2_plate_cycle.observation.yaml) —
+  the **observation document** (D38). Follow one `_id` through `peel` → `seal` →
+  `thermal_cycle` → `rotate` and back to the output boundary: that is the plate surviving four
+  handovers.
+- [`outputs/sila2_plate_cycle.svg`](outputs/sila2_plate_cycle.svg) — a **Gantt chart** of that
+  schedule (device view), drawn by the scheduler's visualizer. Six rows — the four instruments,
+  the station and the arm — and the makespan marker.
+- [`outputs/sila2_plate_cycle.boundary.yaml`](outputs/sila2_plate_cycle.boundary.yaml) — the
+  **result boundary**: the three readings and the returned plate.
+
+It is a producer, not a check: it asserts nothing, and `run_sila2_plate_cycle.py` is what says
+whether the example still works. Unlike `render_plate_line.py` it needs the lab, since its
+scripts issue real commands. The committed copies were produced on the realistic profile
+(makespan 110); every op runs out-of-process on a wall clock against real servers, so the exact
+times vary between runs while the sequence, the identities and the produced values do not.
+
+### Run every SiLA2 example
+
+```sh
+python examples/run_all_sila2_examples.py
+```
+
+Runs each environment above in turn — both `sila2_seal` environments and `sila2_plate_cycle`
+(they are round trips that put the plate back where it started, and each opens whatever it
+needs open, so they follow one another without intervention) — prints a pass/fail summary, and
+exits non-zero if any failed. Only the examples
+that need the lab are included; `render_plate_line.py` needs nothing but Python.

labcode-0.1.5/examples/outputs/sila2_plate_cycle.boundary.yaml

@@ -0,0 +1,17 @@
+boundary:
+  inputs:
+    plate:
+      spot: station.slot1
+      view:
+        _id: 2fbeb516-ba67-4198-9ba6-7cd664e799c8
+  outputs:
+    tape_left:
+      view: 1186
+    cycle_count:
+      view: 22
+    elapsed_time:
+      view: 00:00:10
+    plate:
+      spot: station.slot1
+      view:
+        _id: 2fbeb516-ba67-4198-9ba6-7cd664e799c8