labcode 0.1.0__tar.gz → 0.1.2__tar.gz

{labcode-0.1.0 → labcode-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: labcode
-Version: 0.1.0
+Version: 0.1.2
 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.0
-Requires-Dist: ofplang-schedule>=0.1.2
-Requires-Dist: ofplang-run>=0.1.6
+Requires-Dist: ofplang-validate>=0.1.3
+Requires-Dist: ofplang-schedule>=0.1.3
+Requires-Dist: ofplang-run>=0.1.10
 Provides-Extra: test
 Requires-Dist: pytest>=7.0; extra == "test"
 Provides-Extra: dev

{labcode-0.1.0 → labcode-0.1.2}/SPECIFICATIONS.md

@@ -128,7 +128,60 @@ Cadence: the effective poll period is `poll_interval × seconds_per_tick`. labco
 sub-second, which would flood the replan loop); `lc run --seconds-per-tick/--speed/
 --poll-interval/--margin` override it.
 
-## 4. Not yet in this version (roadmap)
+## 4. Object identity — the reserved `_id` view key
+
+labcode gives every Object a stable, value-layer identity so it can be traced across
+steps and in the observation document. The identity lives in the Object's **view** under
+the reserved key **`_id`** (a `String`). This is a dialect feature layered on portable
+v0: the workflow the user writes carries no `_id`; `lc run` injects and mints it.
+
+### 4.1 Type rewrite
+
+Before running, `lc run` rewrites the workflow in memory: it adds `_id: { type: String }`
+to the `view` of **every `domain: object` type** (creating `view` if the type had none).
+`_id` is an ordinary legal v0 view field (a leading-underscore identifier, not reserved
+in core, and a primitive `String`), so the rewritten document validates and schedules
+unchanged, and the runner's closed-shape view conformance treats `_id` as a normal
+declared field. labcode runs this rewritten document directly (no temp file:
+`ofplang.run.run_workflow` accepts an in-memory document).
+
+**Reserved (error).** A user type that itself declares a `_id` view field is rejected at
+the dialect front door — labcode owns `_id`, and silently clobbering the field would be
+worse than a clear error.
+
+### 4.2 Where an id comes from
+
+An Object's `_id` is set at its two points of origin, then **carried** everywhere else —
+`objects.map` and transport copy the whole view, so `_id` propagates for free:
+
+- **`objects.create`** — a newly created Object's `_id` is minted when the operation
+  produces it (in the backend's output fill). A device script need not know about `_id`:
+  it returns only what it computes, and the fill supplies `_id` (like any other unset
+  output, §1.2).
+- **run boundary** — a whole-workflow Object *input* enters at the boundary; `lc run`
+  mints its `_id` (filling any other declared view field with a typed default so the
+  seeded value conforms), **unless the boundary already carries one** — so a result
+  boundary fed back in round-trips its ids.
+- **`objects.map`** — a mapped Object output carries its input's `_id` unchanged
+  (identity preserved), even if a §22.2-strict script returned the port explicitly.
+
+### 4.3 Reproducibility
+
+Ids come from a swappable generator (`labcode.idgen.IdGenerator`). The default
+(`SeededUuid4Generator`) mints **reproducible** uuid4-shaped ids from a seed and a
+*provenance key* — the node instance + output port for a create, the port name for a
+boundary input — **not** draw order. So the same workflow yields the same ids on every
+run, and the wall-clock backend's jittering completion order cannot change them (which is
+what keeps checked-in example observations stable). A real run wanting globally-unique
+ids per physical Object swaps in `RealUuid4Generator` (via
+`labcode_backend_factory(id_generator=...)`).
+
+> The provenance key is the runner's node-instance identity + port. Today each create
+> node runs once, so node-path + port is unique; when dynamic control flow (e.g.
+> `do_while`) is added, that node-instance identity must include the iteration index so
+> ids stay unique and reproducible.
+
+## 5. Not yet in this version (roadmap)
 
 - **Device / transporter `x-labcode`** — connection and availability information
   (e.g. SiLA2 address) consolidated on `devices[]` / `transporters[]`, used for a

labcode-0.1.2/examples/README.md

@@ -0,0 +1,85 @@
+# 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.

labcode-0.1.2/examples/outputs/plate_line.boundary.yaml

@@ -0,0 +1,13 @@
+boundary:
+  inputs:
+    tube:
+      spot: rack.slot
+      view:
+        _id: 60dfcfab-2234-4c90-b7aa-c8d984cbd3c5
+  outputs:
+    od:
+      view: 0.42
+    tube:
+      spot: rack.slot
+      view:
+        _id: 60dfcfab-2234-4c90-b7aa-c8d984cbd3c5

labcode-0.1.2/examples/outputs/plate_line.observation.yaml

@@ -0,0 +1,202 @@
+schema: ofplang-observation/v0
+time:
+  unit: second
+interface:
+  inputs:
+    tube: rack.slot
+  outputs:
+    tube: rack.slot
+---
+kind: transport
+from_spot: rack.slot
+to_spot: dispenser.tube
+transporter: arm
+arc:
+  from:
+    node: []
+    port: tube
+  to:
+    node:
+    - Dispense
+    port: tube
+start: 0
+end: 1
+moved:
+  view:
+    _id: 60dfcfab-2234-4c90-b7aa-c8d984cbd3c5
+---
+kind: processing
+process: load
+mode: m0
+node:
+- Load
+devices:
+- loader
+output_spots:
+  plate: loader.stage
+start: 0
+end: 1
+inputs: {}
+outputs:
+  plate:
+    view:
+      barcode: P001
+      _id: 7e50cfbd-8065-490c-a9ed-f4a50451bac1
+---
+kind: transport
+from_spot: loader.stage
+to_spot: dispenser.deck
+transporter: arm
+arc:
+  from:
+    node:
+    - Load
+    port: plate
+  to:
+    node:
+    - Dispense
+    port: plate
+start: 1
+end: 3
+moved:
+  view:
+    barcode: P001
+    _id: 7e50cfbd-8065-490c-a9ed-f4a50451bac1
+---
+kind: processing
+process: dispense
+mode: m0
+node:
+- Dispense
+devices:
+- dispenser
+input_spots:
+  plate: dispenser.deck
+  tube: dispenser.tube
+output_spots:
+  plate: dispenser.deck
+  tube: dispenser.tube
+start: 3
+end: 5
+inputs:
+  plate:
+    view:
+      barcode: P001
+      _id: 7e50cfbd-8065-490c-a9ed-f4a50451bac1
+  tube:
+    view:
+      _id: 60dfcfab-2234-4c90-b7aa-c8d984cbd3c5
+outputs:
+  plate:
+    view:
+      barcode: P001
+      _id: 7e50cfbd-8065-490c-a9ed-f4a50451bac1
+  tube:
+    view:
+      _id: 60dfcfab-2234-4c90-b7aa-c8d984cbd3c5
+---
+kind: transport
+from_spot: dispenser.deck
+to_spot: reader.stage
+transporter: arm
+arc:
+  from:
+    node:
+    - Dispense
+    port: plate
+  to:
+    node:
+    - Read
+    port: plate
+start: 5
+end: 7
+moved:
+  view:
+    barcode: P001
+    _id: 7e50cfbd-8065-490c-a9ed-f4a50451bac1
+---
+kind: transport
+from_spot: dispenser.tube
+to_spot: rack.slot
+transporter: arm
+arc:
+  from:
+    node:
+    - Dispense
+    port: tube
+  to:
+    node: []
+    port: tube
+start: 7
+end: 9
+moved:
+  view:
+    _id: 60dfcfab-2234-4c90-b7aa-c8d984cbd3c5
+---
+kind: processing
+process: read
+mode: m0
+node:
+- Read
+devices:
+- reader
+input_spots:
+  plate: reader.stage
+output_spots:
+  plate: reader.stage
+start: 7
+end: 10
+inputs:
+  plate:
+    view:
+      barcode: P001
+      _id: 7e50cfbd-8065-490c-a9ed-f4a50451bac1
+outputs:
+  plate:
+    view:
+      barcode: P001
+      _id: 7e50cfbd-8065-490c-a9ed-f4a50451bac1
+  od:
+    view: 0.42
+---
+kind: transport
+from_spot: reader.stage
+to_spot: sealer.stage
+transporter: arm
+arc:
+  from:
+    node:
+    - Read
+    port: plate
+  to:
+    node:
+    - Store
+    port: plate
+start: 10
+end: 12
+moved:
+  view:
+    barcode: P001
+    _id: 7e50cfbd-8065-490c-a9ed-f4a50451bac1
+---
+kind: processing
+process: store
+mode: m0
+node:
+- Store
+devices:
+- sealer
+input_spots:
+  plate: sealer.stage
+start: 12
+end: 14
+inputs:
+  plate:
+    view:
+      barcode: P001
+      _id: 7e50cfbd-8065-490c-a9ed-f4a50451bac1
+outputs: {}
+---
+final: true
+now: 14
+outcome: completed

labcode-0.1.2/examples/outputs/plate_line.plan.yaml

@@ -0,0 +1,144 @@
+time:
+  unit: second
+now: 14
+interface:
+  inputs:
+    tube: rack.slot
+  outputs:
+    tube: rack.slot
+activities:
+- kind: transport
+  start: 0
+  end: 1
+  from_spot: rack.slot
+  to_spot: dispenser.tube
+  transporter: arm
+  arc:
+    from:
+      node: []
+      port: tube
+    to:
+      node:
+      - Dispense
+      port: tube
+  status: completed
+- kind: processing
+  start: 0
+  end: 1
+  process: load
+  mode: m0
+  node:
+  - Load
+  devices:
+  - loader
+  output_spots:
+    plate: loader.stage
+  status: completed
+- kind: transport
+  start: 1
+  end: 3
+  from_spot: loader.stage
+  to_spot: dispenser.deck
+  transporter: arm
+  arc:
+    from:
+      node:
+      - Load
+      port: plate
+    to:
+      node:
+      - Dispense
+      port: plate
+  status: completed
+- kind: processing
+  start: 3
+  end: 5
+  process: dispense
+  mode: m0
+  node:
+  - Dispense
+  devices:
+  - dispenser
+  input_spots:
+    plate: dispenser.deck
+    tube: dispenser.tube
+  output_spots:
+    plate: dispenser.deck
+    tube: dispenser.tube
+  status: completed
+- kind: transport
+  start: 5
+  end: 7
+  from_spot: dispenser.deck
+  to_spot: reader.stage
+  transporter: arm
+  arc:
+    from:
+      node:
+      - Dispense
+      port: plate
+    to:
+      node:
+      - Read
+      port: plate
+  status: completed
+- kind: transport
+  start: 7
+  end: 9
+  from_spot: dispenser.tube
+  to_spot: rack.slot
+  transporter: arm
+  arc:
+    from:
+      node:
+      - Dispense
+      port: tube
+    to:
+      node: []
+      port: tube
+  status: completed
+- kind: processing
+  start: 7
+  end: 10
+  process: read
+  mode: m0
+  node:
+  - Read
+  devices:
+  - reader
+  input_spots:
+    plate: reader.stage
+  output_spots:
+    plate: reader.stage
+  status: completed
+- kind: transport
+  start: 10
+  end: 12
+  from_spot: reader.stage
+  to_spot: sealer.stage
+  transporter: arm
+  arc:
+    from:
+      node:
+      - Read
+      port: plate
+    to:
+      node:
+      - Store
+      port: plate
+  status: completed
+- kind: processing
+  start: 12
+  end: 14
+  process: store
+  mode: m0
+  node:
+  - Store
+  devices:
+  - sealer
+  input_spots:
+    plate: sealer.stage
+  status: completed
+objective:
+  kind: makespan
+  value: 14

labcode-0.1.2/examples/outputs/plate_line.svg

@@ -0,0 +1,2 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 784 296" width="784" height="296" font-family="system-ui, sans-serif" font-size="12"><text fill="#1a1a1a" font-size="15" font-weight="600" x="16" y="24">Schedule &#8212; device view</text><text fill="#666666" x="16" y="40">makespan 14 second</text><defs><marker id="ah" markerWidth="8" markerHeight="8" refX="7" refY="3" orient="auto"><path d="M0,0 L7,3 L0,6 Z" fill="#9333ea"/></marker></defs><g transform="translate(0,48)"><line stroke="#b3b3b3" stroke-width="1" x1="200.0" y1="34.0" x2="200.0" y2="220.0"/><text fill="#666666" x="200.0" y="28.0" text-anchor="middle">0</text><line stroke="#b3b3b3" stroke-width="1" x1="280.0" y1="34.0" x2="280.0" y2="220.0"/><text fill="#666666" x="280.0" y="28.0" text-anchor="middle">2</text><line stroke="#b3b3b3" stroke-width="1" x1="360.0" y1="34.0" x2="360.0" y2="220.0"/><text fill="#666666" x="360.0" y="28.0" text-anchor="middle">4</text><line stroke="#b3b3b3" stroke-width="1" x1="440.0" y1="34.0" x2="440.0" y2="220.0"/><text fill="#666666" x="440.0" y="28.0" text-anchor="middle">6</text><line stroke="#b3b3b3" stroke-width="1" x1="520.0" y1="34.0" x2="520.0" y2="220.0"/><text fill="#666666" x="520.0" y="28.0" text-anchor="middle">8</text><line stroke="#b3b3b3" stroke-width="1" x1="600.0" y1="34.0" x2="600.0" y2="220.0"/><text fill="#666666" x="600.0" y="28.0" text-anchor="middle">10</text><line stroke="#b3b3b3" stroke-width="1" x1="680.0" y1="34.0" x2="680.0" y2="220.0"/><text fill="#666666" x="680.0" y="28.0" text-anchor="middle">12</text><line stroke="#b3b3b3" stroke-width="1" x1="760.0" y1="34.0" x2="760.0" y2="220.0"/><text fill="#666666" x="760.0" y="28.0" text-anchor="middle">14</text><text fill="#666666" x="200.0" y="240.0">time (second)</text><line stroke="#d9d9d9" stroke-width="1" x1="0" y1="70.0" x2="784.0" y2="70.0"/><text fill="#1a1a1a" x="190.0" y="59.0" text-anchor="end">dispenser</text><line stroke="#d9d9d9" stroke-width="1" x1="0" y1="100.0" x2="784.0" y2="100.0"/><text fill="#1a1a1a" x="190.0" y="89.0" text-anchor="end">loader</text><line stroke="#d9d9d9" stroke-width="1" x1="0" y1="130.0" x2="784.0" y2="130.0"/><text fill="#1a1a1a" x="190.0" y="119.0" text-anchor="end">rack</text><line stroke="#d9d9d9" stroke-width="1" x1="0" y1="160.0" x2="784.0" y2="160.0"/><text fill="#1a1a1a" x="190.0" y="149.0" text-anchor="end">reader</text><line stroke="#d9d9d9" stroke-width="1" x1="0" y1="190.0" x2="784.0" y2="190.0"/><text fill="#1a1a1a" x="190.0" y="179.0" text-anchor="end">sealer</text><line stroke="#d9d9d9" stroke-width="1" x1="0" y1="220.0" x2="784.0" y2="220.0"/><text fill="#1a1a1a" x="190.0" y="209.0" text-anchor="end">arm (transporter)</text><line stroke="#dc2626" stroke-width="1.5" stroke-dasharray="4 3" x1="760.0" y1="34.0" x2="760.0" y2="220.0"/><text fill="#dc2626" x="763.0" y="28.0">now=14</text><rect fill="#f59e0b" x="200.0" y="195.0" width="40.0" height="20" rx="3"/><text fill="#3a2a00" x="204.0" y="209.0">&gt; D…</text><rect fill="#f59e0b" fill-opacity="0.2" x="200.0" y="105.0" width="40.0" height="20" rx="3"/><rect fill="#f59e0b" fill-opacity="0.2" x="200.0" y="45.0" width="40.0" height="20" rx="3"/><rect fill="#3b82f6" x="200.0" y="75.0" width="40.0" height="20" rx="3"/><text fill="#ffffff" x="204.0" y="89.0">Load</text><rect fill="#f59e0b" x="240.0" y="195.0" width="80.0" height="20" rx="3"/><text fill="#3a2a00" x="244.0" y="209.0">&gt; Dispense</text><rect fill="#f59e0b" fill-opacity="0.2" x="240.0" y="75.0" width="80.0" height="20" rx="3"/><rect fill="#f59e0b" fill-opacity="0.2" x="240.0" y="45.0" width="80.0" height="20" rx="3"/><rect fill="#3b82f6" x="320.0" y="45.0" width="80.0" height="20" rx="3"/><text fill="#ffffff" x="324.0" y="59.0">Dispense</text><rect fill="#f59e0b" x="400.0" y="195.0" width="80.0" height="20" rx="3"/><text fill="#3a2a00" x="404.0" y="209.0">&gt; Read</text><rect fill="#f59e0b" fill-opacity="0.2" x="400.0" y="45.0" width="80.0" height="20" rx="3"/><rect fill="#f59e0b" fill-opacity="0.2" x="400.0" y="135.0" width="80.0" height="20" rx="3"/><rect fill="#f59e0b" x="480.0" y="195.0" width="80.0" height="20" rx="3"/><text fill="#3a2a00" x="484.0" y="209.0">&gt; transport</text><rect fill="#f59e0b" fill-opacity="0.2" x="480.0" y="45.0" width="80.0" height="20" rx="3"/><rect fill="#f59e0b" fill-opacity="0.2" x="480.0" y="105.0" width="80.0" height="20" rx="3"/><rect fill="#3b82f6" x="480.0" y="135.0" width="120.0" height="20" rx="3"/><text fill="#ffffff" x="484.0" y="149.0">Read</text><rect fill="#f59e0b" x="600.0" y="195.0" width="80.0" height="20" rx="3"/><text fill="#3a2a00" x="604.0" y="209.0">&gt; Store</text><rect fill="#f59e0b" fill-opacity="0.2" x="600.0" y="135.0" width="80.0" height="20" rx="3"/><rect fill="#f59e0b" fill-opacity="0.2" x="600.0" y="165.0" width="80.0" height="20" rx="3"/><rect fill="#3b82f6" x="680.0" y="165.0" width="80.0" height="20" rx="3"/><text fill="#ffffff" x="684.0" y="179.0">Store</text></g></svg>

labcode-0.1.2/examples/plate_line.boundary.yaml

@@ -0,0 +1,18 @@
+# Run boundary (dev-notes D28) for plate_line.workflow.yaml.
+#
+# The whole workflow takes one `Tube` in and passes the same Tube out (plus the Pure
+# Data measurement `od`). A boundary port has two halves: `spot` (where an Object sits)
+# and `view` (its observable value).
+#
+#  - `tube` is Object-bearing, so it MUST name a spot: it starts in the standalone tube
+#    rack (`rack.slot`, bound to no process). The arm carries it to the dispenser for the
+#    dispense and back. `Tube` has no view fields, so no `view` is supplied.
+#  - `od` is Pure Data (no spot); its produced view is filled in at run end.
+#  - the `tube` output is pinned back to its rack slot, so it round-trips (its view is
+#    filled in at run end).
+boundary:
+  inputs:
+    tube: { spot: rack.slot }
+  outputs:
+    od: {}
+    tube: { spot: rack.slot }

{labcode-0.1.0 → labcode-0.1.2}/examples/plate_line.env.yaml

@@ -3,16 +3,27 @@
 # The workflow stays portable v0 (`ofplang-schedule` just tolerates the x- keys).
 #
 # Every process mode AND every transport route carries a script here. The process
-# scripts are Object-bearing: `load` returns the new Plate's view; `read` returns the
-# *same* plate it was given plus the measured `od`; `store` takes it (side-effect only).
+# scripts are Object-bearing: `load` returns the new Plate's view; `dispense` takes the
+# Plate and the Tube and passes *both* through (objects.map), so its script returns
+# nothing; `read` returns the measured `od` (the Plate is carried); `store` takes it.
 # The transport scripts move the plate and may read its view (the barcode).
+#
+# Physical layout: the Plate is loaded on `loader`, dispensed into on the `dispenser`
+# deck, read on `reader`, sealed on `sealer`; the `arm` moves it along. The source Tube
+# starts in a standalone `rack` slot -- a plain holding location bound to no process --
+# enters and leaves the run there (see plate_line.boundary.yaml), and the `arm` carries
+# it to the dispenser's `tube` holder for the dispense and back to the rack afterwards.
 time:
   unit: second
 
 devices:
-  - { id: loader, spots: [stage] }
-  - { id: reader, spots: [stage] }
-  - { id: sealer, spots: [stage] }
+  - { id: loader,    spots: [stage] }
+  - { id: dispenser, spots: [deck, tube] }
+  - { id: reader,    spots: [stage] }
+  - { id: sealer,    spots: [stage] }
+  # A tube rack: a plain holding location, used by no process. The source Tube lives
+  # here at the run boundary; the arm ferries it to/from the dispenser.
+  - { id: rack,      spots: [slot] }
 
 transporters:
   - { id: arm }
@@ -20,7 +31,7 @@ transporters:
 transports:
   - transporter: arm
     from: loader.stage
-    to: reader.stage
+    to: dispenser.deck
     duration: 2
     x-labcode:
       script:
@@ -31,6 +42,16 @@ transports:
           barcode = (view or {}).get("barcode")
           # a real arm would move the plate here; e.g. robot.move(from_spot, to_spot)
 
+  - transporter: arm
+    from: dispenser.deck
+    to: reader.stage
+    duration: 2
+    x-labcode:
+      script:
+        language: python
+        code: |
+          barcode = (view or {}).get("barcode")
+
   - transporter: arm
     from: reader.stage
     to: sealer.stage
@@ -41,6 +62,30 @@ transports:
         code: |
           barcode = (view or {}).get("barcode")
 
+  # The source Tube's round trip: rack -> dispenser for the dispense, then back.
+  - transporter: arm
+    from: rack.slot
+    to: dispenser.tube
+    duration: 2
+    x-labcode:
+      script:
+        language: python
+        code: |
+          # Move the source tube to the dispenser. `view` is the Tube's view; it has no
+          # fields here. A real arm would grip and move the tube; e.g. robot.move(...).
+          pass
+
+  - transporter: arm
+    from: dispenser.tube
+    to: rack.slot
+    duration: 2
+    x-labcode:
+      script:
+        language: python
+        code: |
+          # Return the tube to its rack slot.
+          pass
+
 processes:
 
   load:
@@ -55,6 +100,21 @@ processes:
               # Create the Plate's view (its observable data). Returns the one output port.
               return {"plate": {"barcode": "P001"}}
 
+  dispense:
+    modes:
+      - devices: [dispenser]
+        duration: 3
+        input_spots:  { plate: dispenser.deck, tube: dispenser.tube }
+        output_spots: { plate: dispenser.deck, tube: dispenser.tube }   # both stay in place
+        x-labcode:
+          script:
+            language: python
+            code: |
+              # `plate` and `tube` are the incoming Objects' views. A real dispenser would
+              # aspirate from the tube and dispense into the plate here. Both Objects are
+              # carried through by objects.map, so the script returns nothing.
+              return {}
+
   read:
     modes:
       - devices: [reader]