labcode 0.1.7__tar.gz → 0.2.0__tar.gz

{labcode-0.1.7 → labcode-0.2.0}/.gitignore

@@ -12,3 +12,6 @@ venv/
 # Local working notes, not part of the published project (until explicitly committed).
 CLAUDE.md
 dev-notes/
+
+# The bench-specific environments name real hosts and ports; this repository is public.
+*.remote.env.yaml

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: labcode
-Version: 0.1.7
+Version: 0.2.0
 Summary: labcode -- a dialect wrapper over the Object-Flow Programming Language toolchain
 Author-email: Kazunari Kaizu <kwaizu@gmail.com>
 License-Expression: MIT
@@ -21,22 +21,25 @@ 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
+Requires-Dist: ofplang-schedule>=0.2.3
+Requires-Dist: ofplang-run>=0.3.0
 Provides-Extra: test
 Requires-Dist: pytest>=7.0; extra == "test"
 Requires-Dist: opentelemetry-sdk>=1.20; extra == "test"
+Requires-Dist: opentelemetry-instrumentation-grpc[instruments]>=0.41b0; 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"
+Requires-Dist: opentelemetry-instrumentation-grpc[instruments]>=0.41b0; 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"
+Requires-Dist: opentelemetry-instrumentation-grpc>=0.41b0; extra == "otel"
 Dynamic: license-file
 
 # labcode
@@ -110,9 +113,9 @@ What `lc run` brings of its own, beyond dispatching:
   (§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]`.
+  traces: one trace per run, a span per operation, and — measured inside the process that
+  issued them — a span per SiLA2 connection, per command, and per gRPC call each of those
+  made. Off by default; the extra is `pip install labcode[otel]`.
 
 ## Usage
 
@@ -136,7 +139,7 @@ described below.
 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]
+    [--ignore-resources] [--trace] [--mission-id ID] [--object-ids seeded|real]
 ```
 
 - `<workflow>` — the portable v0 workflow: *what* happens.
@@ -146,7 +149,12 @@ lc run <workflow> --env <env>
   `{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.
+  where the labware is. Where a device declares a consumable and some mode draws on it,
+  an `inventories: {levels: ...}` section says what each stock holds **at the start of
+  the run** — the level later on is never stated, it is worked out from that and what the
+  run has done since. It is not echoed into `--boundary-out`, because that document is
+  written to be fed back and the next run would take this run's opening stock for its
+  own.
 - `-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
@@ -164,6 +172,9 @@ lc run <workflow> --env <env>
   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.
+- `--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.
 - `--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.
@@ -187,6 +198,49 @@ 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`.
 
+### Refilling a stock
+
+Where a device declares a consumable and the environment says a replenisher can reach it,
+a stock that would run out is **topped up instead of ending the run**. The procedure goes
+on the `replenishments[]` route — the pair is what has a procedure, while the machine has
+only an address, the same division `transporters` and `transports` have:
+
+```yaml
+replenishers:
+  - id: dispenser
+    x-labcode:
+      connection: { kind: sila2, host: 10.0.0.9, port: 50055, insecure: true }
+
+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
+```
+
+The script is handed `replenisher`, `device` and the `amounts` the scheduler derived, and
+is expected to put that in. It is **not** handed the duration: a real refill takes as long
+as it takes, so a stand-in says so in its own code — which is why the two numbers above
+are written separately. Like a transport script it returns nothing; it acts.
+
+A route with no script runs as a timed visit: both machines are held for the declared
+duration and nothing is commanded. That is a real thing 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.
+
+`flavor: sila2` is **refused on a refill route** for now: a sila2 script is handed clients,
+and which machine's clients a refill should receive — the replenisher's, or both ends' as a
+transport may ask for — is not settled. Use `python`.
+
+A refill holds the device it fills *and* the replenisher filling it, so it never overlaps
+the work it feeds. It is recorded (`--trace`) as a `replenishment` span naming both
+machines.
+
 ### Recording a run
 
 `--trace` records what the run did as OpenTelemetry traces. It needs the extra, in the
@@ -198,14 +252,17 @@ 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:
+One run is one trace, and the id it can be found by is printed to stderr as the run
+starts (`lc run: recording this run as trace …`). What it holds:
 
 ```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
+│  │  └─ /…/SiLAService/GetFeatureDefinition   one per feature, × however many
 │  └─ sila2 SealerControl.Seal       the command, from its start to its real completion
+│     └─ /…/SealerControl/Seal       the round trip that started it
 └─ transport                         the route and the transporter
 ```
 
@@ -215,6 +272,16 @@ in the command spans, which are measured where the commands are issued. `ofp.obj
 lists the `_id`s an operation handled, including one it created — which is what makes
 "everything that happened to this plate" a single query.
 
+The innermost layer is the gRPC calls themselves, each under the connection or the command
+that issued it — so what a connection spends is broken down into the feature definitions it
+had to fetch, and a command's span separates its round trip from the time the instrument
+then took. It needs `grpcio`, which arrives with the `sila2` extra; without it the record is
+the same minus that layer. Two things it does not do: an observable command's
+execution-info subscription is **not** recorded (it is read on a thread of `sila2`'s own,
+where it would land in a trace of its own, and its duration is the command's anyway), and
+each recorded call **sends the trace context to the instrument** in its gRPC metadata, which
+a SiLA2 server ignores as it does any key that is not SiLA Client Metadata.
+
 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

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

@@ -69,9 +69,9 @@ What `lc run` brings of its own, beyond dispatching:
   (§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]`.
+  traces: one trace per run, a span per operation, and — measured inside the process that
+  issued them — a span per SiLA2 connection, per command, and per gRPC call each of those
+  made. Off by default; the extra is `pip install labcode[otel]`.
 
 ## Usage
 
@@ -95,7 +95,7 @@ described below.
 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]
+    [--ignore-resources] [--trace] [--mission-id ID] [--object-ids seeded|real]
 ```
 
 - `<workflow>` — the portable v0 workflow: *what* happens.
@@ -105,7 +105,12 @@ lc run <workflow> --env <env>
   `{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.
+  where the labware is. Where a device declares a consumable and some mode draws on it,
+  an `inventories: {levels: ...}` section says what each stock holds **at the start of
+  the run** — the level later on is never stated, it is worked out from that and what the
+  run has done since. It is not echoed into `--boundary-out`, because that document is
+  written to be fed back and the next run would take this run's opening stock for its
+  own.
 - `-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
@@ -123,6 +128,9 @@ lc run <workflow> --env <env>
   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.
+- `--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.
 - `--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.
@@ -146,6 +154,49 @@ 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`.
 
+### Refilling a stock
+
+Where a device declares a consumable and the environment says a replenisher can reach it,
+a stock that would run out is **topped up instead of ending the run**. The procedure goes
+on the `replenishments[]` route — the pair is what has a procedure, while the machine has
+only an address, the same division `transporters` and `transports` have:
+
+```yaml
+replenishers:
+  - id: dispenser
+    x-labcode:
+      connection: { kind: sila2, host: 10.0.0.9, port: 50055, insecure: true }
+
+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
+```
+
+The script is handed `replenisher`, `device` and the `amounts` the scheduler derived, and
+is expected to put that in. It is **not** handed the duration: a real refill takes as long
+as it takes, so a stand-in says so in its own code — which is why the two numbers above
+are written separately. Like a transport script it returns nothing; it acts.
+
+A route with no script runs as a timed visit: both machines are held for the declared
+duration and nothing is commanded. That is a real thing 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.
+
+`flavor: sila2` is **refused on a refill route** for now: a sila2 script is handed clients,
+and which machine's clients a refill should receive — the replenisher's, or both ends' as a
+transport may ask for — is not settled. Use `python`.
+
+A refill holds the device it fills *and* the replenisher filling it, so it never overlaps
+the work it feeds. It is recorded (`--trace`) as a `replenishment` span naming both
+machines.
+
 ### Recording a run
 
 `--trace` records what the run did as OpenTelemetry traces. It needs the extra, in the
@@ -157,14 +208,17 @@ 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:
+One run is one trace, and the id it can be found by is printed to stderr as the run
+starts (`lc run: recording this run as trace …`). What it holds:
 
 ```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
+│  │  └─ /…/SiLAService/GetFeatureDefinition   one per feature, × however many
 │  └─ sila2 SealerControl.Seal       the command, from its start to its real completion
+│     └─ /…/SealerControl/Seal       the round trip that started it
 └─ transport                         the route and the transporter
 ```
 
@@ -174,6 +228,16 @@ in the command spans, which are measured where the commands are issued. `ofp.obj
 lists the `_id`s an operation handled, including one it created — which is what makes
 "everything that happened to this plate" a single query.
 
+The innermost layer is the gRPC calls themselves, each under the connection or the command
+that issued it — so what a connection spends is broken down into the feature definitions it
+had to fetch, and a command's span separates its round trip from the time the instrument
+then took. It needs `grpcio`, which arrives with the `sila2` extra; without it the record is
+the same minus that layer. Two things it does not do: an observable command's
+execution-info subscription is **not** recorded (it is read on a thread of `sila2`'s own,
+where it would land in a trace of its own, and its duration is the command's anyway), and
+each recorded call **sends the trace context to the instrument** in its gRPC metadata, which
+a SiLA2 server ignores as it does any key that is not SiLA Client Metadata.
+
 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

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

@@ -185,11 +185,11 @@ polls forever. A script that knows its own commands should still bound them itse
 
 ### Prerequisites
 
-**Verified against [ofplang-sila2-backend](https://github.com/kaizu/sila2-demo) branch `ardea`
-(commit `de3c4fd`)** — a virtual lab of mock SiLA2 instrument servers. That branch is where its
+**Verified against [ofplang-sila2-backend](https://github.com/ofplang/sila2-backend) at commit
+`de3c4fd`** — a virtual lab of mock SiLA2 instrument servers. That commit is where its
 transporter became a mock of **Ardea**, a machine that exists, serving the real one's nine
-Feature definitions unchanged; it is not merged, so a checkout of `main` will not run these
-examples. That lab is a *reference, not a
+Feature definitions unchanged; it reached `main` in the `ardea` merge, so a checkout of `main`
+runs these examples. 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
@@ -417,14 +417,122 @@ scripts issue real commands. The committed copies were produced on the realistic
 times vary between runs — by tens of seconds, now that five 30 s transfers dominate — while the
 sequence, the identities and the produced values do not.
 
+## `sila2_plate_cycle_no_atc` — the same circuit, on a bench with no thermal cycler
+
+The full circuit above needs an automated thermal cycler. When there is not one to use, the
+workflow that goes to the bench is this one — `sila2_plate_cycle` with that step removed and the
+rest in the order a bench with an **unsealed** plate can run them:
+
+```
+   (in) plate ──▶ seal ──▶ rotate ──▶ peel ──▶ (out) plate
+                    │                    │
+          (out) cycle_count        (out) tape_left
+```
+
+Seal, spin, peel — so the plate ends the circuit in the state it began it, and the run repeats
+without anyone reconditioning a plate in between. That is the same property the round trip has
+for the plate's *location*, applied to its condition; peeling first would need a sealed plate to
+start from and hand back a sealed one.
+
+- [`sila2_plate_cycle_no_atc.workflow.yaml`](sila2_plate_cycle_no_atc.workflow.yaml) is the
+  circuit minus one node, with the remaining three in the new order: the plate is sealed, spun
+  down and unsealed, and the *same* plate comes back to `station.slot1`.
+- [`sila2_plate_cycle_no_atc.wrapped.env.yaml`](sila2_plate_cycle_no_atc.wrapped.env.yaml)
+  drops the `thermal_cycler` device, its routes and the `thermal_cycle` mode, and joins four
+  different pairs of places: to the sealer, to the centrifuge, to the peeler, home. Only the
+  centrifuge has a door, so only the two routes at its ends open anything. Every instrument
+  script and every duration is the full circuit's, unchanged.
+- [`sila2_plate_cycle_no_atc.boundary.yaml`](sila2_plate_cycle_no_atc.boundary.yaml) is the
+  full circuit's boundary without `elapsed_time` — that reading was the cycler's.
+
+Nothing connects to the cycler, so the run does not care whether that server is up: the check
+asserts it was never scheduled, which is what makes a pass here evidence for the bench it was
+written for rather than for the full lab.
+
+```sh
+python examples/run_sila2_plate_cycle_no_atc.py
+```
+
+Same prerequisites and conventions as `sila2_plate_cycle` (the lab up, `sila2` importable, one
+plate on `station.slot1`, exit code 0 means every check passed, `--artifacts DIR` keeps the
+documents). It checks the same things minus the cycler's reading: every activity completed,
+four transports and three instrument steps, both readings real, the plate home at
+`station.slot1`, and all three instruments handling the plate with the same `_id`.
+
+Verified against the reference lab on both timing profiles at `--seconds-per-tick 1.0`. On
+`command_durations.realistic.yaml` the circuit is a makespan of about 190–220 (two ops fewer
+than the full one's 260–290); on the default profile every op finishes early and the run still
+completes. Running it twice in a row is the more interesting pass: the second run starts with
+the centrifuge closed by the first, so it only gets anywhere if the transport really can open
+the door.
+
+`--trace` records the run (`labcode.record`) and prints its trace id, so the SiLA2 commands, the
+client builds and the poll waits *inside* each operation are separable — which is what to look
+at when a duration turns out to be wrong. The exporter is configured by OpenTelemetry's own
+environment variables:
+
+```sh
+OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4318 \
+  python examples/run_sila2_plate_cycle_no_atc.py --trace --artifacts run1
+```
+
+One thing to get right first: **point the exporter at `127.0.0.1`, not `localhost`.** Where the
+collector binds IPv4 only, `localhost` can resolve to `::1` first, and the exporter's retry
+backoff then stalls whichever operation was exporting. Measured on the reference lab at
+`--seconds-per-tick 1.0`: makespan 216 untraced, **219** traced via `127.0.0.1` (so recording
+itself costs next to nothing), **279** traced via `localhost` — one 39 s move became 95 s, and
+the run reported a 54 s poll cycle. Both traced runs recorded the same 114 spans, so the trace
+was not the poorer for it; only the schedule was.
+
+Even so, take a duration from an *untraced* run and use the trace to explain it. Recording puts
+an exporter in every operation's child process, and an operation's measured time is exactly what
+these numbers are for.
+
 ### 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
+Runs each environment above in turn — both `sila2_seal` environments, `sila2_plate_cycle` and
+`sila2_plate_cycle_no_atc` (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.
+
+## Taking one of these to a bench
+
+The examples above point at the reference lab because it is what CI and a laptop can run. An
+environment that speaks plain SiLA2 goes to real instruments by **changing hosts and ports and
+nothing else** — so a bench environment is best written as a copy of the mock one with the
+addresses replaced, and nothing else touched. Then `diff` says what is bench-specific.
+
+`*.remote.env.yaml` is **git-ignored**: this repository is public, and a bench's host/port
+inventory is not something to publish by accident. Keep the copy local, or commit it
+deliberately.
+
+### Check the bench before commanding anything
+
+[`preflight_sila2_env.py`](preflight_sila2_env.py) takes any labcode environment and checks it
+against the machines it names, **issuing no SiLA2 command**:
+
+```sh
+python examples/preflight_sila2_env.py --env examples/<your>.remote.env.yaml
+```
+
+Everything it does is a read — building labcode's own client (which fetches every Feature
+definition, and is where TLS, a wrong port and a half-open server show up), the `SiLAService`
+properties every server serves, and the transporter's non-observable
+`CarriageService.StationNames`. Nothing moves, nothing opens, nothing starts. It reports
+
+- each machine's identity and the Features it serves;
+- whether every Feature the environment's **scripts** name is actually served — a script
+  reaching for a Feature the server does not implement otherwise fails mid-run, with a plate
+  somewhere;
+- whether every station name the transport scripts use is one the transporter **knows** — an
+  unknown one fails with `InvalidStation`.
+
+What it cannot check is the one thing the hardware will not catch either: whether a station
+name the machine *does* know is the place the workflow means. `Base4` that is the sealer on one
+bench and the cycler on another does not fail — it puts a plate somewhere else. That mapping
+has to be confirmed against the bench, and it is the thing to confirm before a first run.

{labcode-0.1.7 → labcode-0.2.0}/examples/plate_line.env.yaml

@@ -141,6 +141,3 @@ processes:
             code: |
               # `plate` is the incoming Plate's view; storing is side-effect only.
               return {}
-
-objective:
-  kind: makespan