labcode 0.1.5__tar.gz → 0.1.6__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: labcode
-Version: 0.1.5
+Version: 0.1.6
 Summary: labcode -- a dialect wrapper over the Object-Flow Programming Language toolchain
 Author-email: Kazunari Kaizu <kwaizu@gmail.com>
 License-Expression: MIT
@@ -22,7 +22,7 @@ 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.11
+Requires-Dist: ofplang-run>=0.1.12
 Provides-Extra: test
 Requires-Dist: pytest>=7.0; extra == "test"
 Provides-Extra: dev

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

@@ -367,8 +367,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 +382,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 +394,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 +455,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

{labcode-0.1.5 → labcode-0.1.6}/examples/README.md

@@ -168,6 +168,18 @@ arm, so there is nothing to route around, and what a stopped lab should produce
 instrument command failing where it was issued. `lc run --no-probe` turns probing off for a
 run without editing the environment.
 
+### If a machine stops answering *mid-operation*
+
+Probing catches a machine that is not there; it does not catch one that accepted a command
+and never came back. That is what the **operation timeout** is for
+([`../SPECIFICATIONS.md`](../SPECIFICATIONS.md) §1.8): every operation has a real-seconds
+deadline (7200 s by default, declared lab-wide at the environment root as
+`x-labcode.op_timeout`), and one that passes it is stopped and failed with the reason
+`op_timeout` — a run that ends with a status document and a reason instead of one that
+polls forever. A script that knows its own commands should still bound them itself with
+`settle(..., timeout=...)`: it fires first and can say *which command* hung. `lc run
+--op-timeout SECONDS` / `--no-op-timeout` change the outer limit for a single run.
+
 ### Prerequisites
 
 **Verified against [ofplang-sila2-backend](https://github.com/kaizu/sila2-demo) v0.3.0 (commit

{labcode-0.1.5 → labcode-0.1.6}/labcode/backend.py

@@ -33,6 +33,7 @@ import subprocess
 import sys
 import time
 from collections.abc import Callable
+from typing import Literal
 
 from ofplang.run.simulator import (
     DeviceComputationError,
@@ -41,7 +42,9 @@ from ofplang.run.simulator import (
 )
 
 from labcode.extension import (
+    DEFAULT_OP_TIMEOUT,
     FLAVOR_SILA2,
+    declared_op_timeout,
     device_connections,
     python_code,
     script_endpoints,
@@ -65,6 +68,11 @@ from labcode.sila2 import failing_code, plan_clients, wrap
 # reads as discrete, observable steps rather than a burst of sub-second replans.
 DEFAULT_SECONDS_PER_TICK = 20.0
 
+#: `op_timeout="environment"` -- take the operation timeout from the environment document
+#: (or the default). It is a distinct value from `None`, which says the opposite: run with
+#: no deadline at all, whatever the document declares.
+FROM_ENVIRONMENT: Literal["environment"] = "environment"
+
 
 def _flavored(code: str, script, machines, label: str) -> str:
     """`code` as its flavor asks for it: a `sila2` script wrapped so its clients are open
@@ -333,6 +341,21 @@ class LabcodeBackend(SubprocessBackend):
         return uuid
 
 
+def _effective_op_timeout(
+    environment: dict, requested: float | None | Literal["environment"]
+) -> float | None:
+    """How long an operation may run in this environment, in real seconds (None = no
+    limit): what the caller asked for, else what the document declares, else the default.
+
+    The three layers are `lc run --op-timeout` / `--no-op-timeout`, the environment root's
+    ``x-labcode.op_timeout``, and `DEFAULT_OP_TIMEOUT` -- a lab that says nothing still
+    gets a limit, because a hang that nobody bounded is the thing this is here to stop."""
+    if isinstance(requested, str):  # the sentinel: the document decides
+        declared, value = declared_op_timeout(environment)
+        return value if declared else DEFAULT_OP_TIMEOUT
+    return requested
+
+
 def labcode_backend_factory(
     *,
     seconds_per_tick: float = DEFAULT_SECONDS_PER_TICK,
@@ -345,6 +368,7 @@ def labcode_backend_factory(
     prober: Prober | None = None,
     on_availability_change: ChangeReporter | None = None,
     on_cadence_slip: CadenceReporter | None = None,
+    op_timeout: float | None | Literal["environment"] = FROM_ENVIRONMENT,
 ) -> Callable[[dict], SubprocessBackend]:
     """Build a ``backend_factory(environment) -> SubprocessBackend`` for the runner,
     wired with the labcode env-script resolver (`make_code_resolver`).
@@ -361,7 +385,12 @@ def labcode_backend_factory(
     ``lc run --no-probe`` does). `prober` decides how a machine is checked (default: a TCP
     connection), and `on_availability_change(id, reachable)` is told when one changes, so a
     caller can report it. `on_cadence_slip(skipped, budget, spent)` is told once if a poll
-    cycle outgrows its poll period (see `LabcodeBackend.advance`)."""
+    cycle outgrows its poll period (see `LabcodeBackend.advance`).
+
+    `op_timeout` bounds how long one operation may run, in **real seconds**: by default the
+    environment's ``x-labcode.op_timeout`` (or `DEFAULT_OP_TIMEOUT` if it declares none),
+    which a caller overrides with a number of its own or `None` for no limit at all -- what
+    ``lc run --op-timeout`` / ``--no-op-timeout`` pass."""
 
     def factory(environment: dict) -> LabcodeBackend:
         kwargs: dict = {
@@ -373,6 +402,7 @@ def labcode_backend_factory(
             "monotonic": monotonic,
             "sleep": sleep,
             "on_cadence_slip": on_cadence_slip,
+            "op_timeout": _effective_op_timeout(environment, op_timeout),
         }
         if probe:
             kwargs["availability"] = build_availability(

{labcode-0.1.5 → labcode-0.1.6}/labcode/dialect.py

@@ -57,6 +57,7 @@ from labcode.extension import (
     is_supported_position,
     merge_probe,
     parse_connection,
+    parse_op_timeout,
     parse_probe,
     script_flavor,
     spot_device,
@@ -143,8 +144,8 @@ def _validate_positions(environment: dict, errors: list) -> None:
 
 
 def _validate_root(environment: dict, errors: list) -> dict:
-    """Shape-check the environment root's ``x-labcode`` -- document-wide probing defaults,
-    and nothing else (an address belongs to the machine that has it). Returns the probe
+    """Shape-check the environment root's ``x-labcode`` -- document-wide defaults, and
+    nothing else (an address belongs to the machine that has it). Returns the probe
     fields it declares, for the effective policies below."""
     extension = environment.get(EXTENSION_KEY)
     if extension is None:
@@ -156,6 +157,11 @@ def _validate_root(environment: dict, errors: list) -> dict:
         f"environment root: {message}"
         for message in unknown_key_messages(extension, "x-labcode", ROOT_KEYS)
     )
+    # The operation timeout is one value for the whole lab, so it lives here and nowhere
+    # else -- a mode that needs a different wait says so inside its own script.
+    if "op_timeout" in extension:
+        _value, messages = parse_op_timeout(extension["op_timeout"])
+        errors.extend(f"environment root: x-labcode.{message}" for message in messages)
     raw = extension.get("probe")
     if raw is None:
         return {}

{labcode-0.1.5 → labcode-0.1.6}/labcode/extension.py

@@ -43,7 +43,7 @@ SCRIPT_SITE_KEYS: tuple[str, ...] = ("script",)
 #: `x-labcode` on a device or a transporter -- how to reach it, and whether to check.
 NODE_KEYS: tuple[str, ...] = ("connection", "probe")
 #: `x-labcode` at the environment root -- document-wide defaults, and nothing else.
-ROOT_KEYS: tuple[str, ...] = ("probe",)
+ROOT_KEYS: tuple[str, ...] = ("probe", "op_timeout")
 CONNECTION_KEYS: tuple[str, ...] = ("kind", "host", "port", "insecure")
 PROBE_KEYS: tuple[str, ...] = ("enabled", "timeout", "interval")
 
@@ -168,6 +168,64 @@ def parse_connection(raw: Any) -> tuple[Connection | None, list[str]]:
     return connection, []
 
 
+# -- operation timeout ----------------------------------------------------------
+
+#: How long one operation may run before labcode gives up on it, in **real seconds**.
+#:
+#: Deliberately generous, and deliberately finite. Its job is not to notice a slow
+#: instrument -- a script that knows what it is waiting for should say so with its own
+#: `labcode.sila2_commands.settle(timeout=...)`, which can name the command that hung.
+#: This is the outer net: it catches the hangs no script is watching for (a `raw` script,
+#: a forgotten `settle`, a stall while connecting), and it exists at all because without
+#: it a silent instrument stops a run with no status document and no reason written.
+#:
+#: It is **one value for the whole lab**, not a per-machine one: the fine-grained waits
+#: belong to the scripts, so the value here only has to clear the longest operation the
+#: lab legitimately runs. It is twice the `settle` default so that when both apply, the
+#: inner wait -- which can say *which command* did not answer -- is the one that fires.
+DEFAULT_OP_TIMEOUT = 7200.0
+
+
+def parse_op_timeout(raw: Any) -> tuple[float | None, list[str]]:
+    """Parse a **declared** ``x-labcode.op_timeout``: seconds, or None for `null` (wait
+    forever). Returns ``(value, errors)``.
+
+    Only call this when the key is present: a declared `null` and no declaration at all
+    mean different things (wait forever / use the default), and a mapping cannot tell
+    them apart once the value is out."""
+    if raw is None:
+        return None, []
+    if (
+        isinstance(raw, bool)
+        or not isinstance(raw, (int, float))
+        or raw <= 0
+        or raw in (float("inf"), float("-inf"))
+        or raw != raw  # NaN
+    ):
+        return None, [
+            "op_timeout must be a positive, finite number of seconds, or null (no limit)"
+        ]
+    return float(raw), []
+
+
+def declared_op_timeout(environment: Any) -> tuple[bool, float | None]:
+    """The operation timeout the environment root declares: ``(declared?, seconds)``,
+    where `seconds` is None for "wait forever".
+
+    Best-effort, like the other readers here: a malformed value reads as *not declared*
+    (the dialect validator is what reports it), so execution falls back to the default
+    rather than silently to no limit at all."""
+    if not isinstance(environment, dict):
+        return False, None
+    extension = environment.get(EXTENSION_KEY)
+    if not isinstance(extension, dict) or "op_timeout" not in extension:
+        return False, None
+    value, errors = parse_op_timeout(extension["op_timeout"])
+    if errors:
+        return False, None
+    return True, value
+
+
 # -- probe ---------------------------------------------------------------------
 
 #: Probing is **off unless asked for**: writing a policy says *how* to probe, never

{labcode-0.1.5 → labcode-0.1.6}/labcode/run_cli.py

@@ -31,8 +31,9 @@ from ofplang.run import FrontDoorResult, front_door_check
 from ofplang.run.runner import ContractSyntaxError, RunnerError, load_document, serialize_document
 from ofplang.run.simulator import SimulatorError
 
-from labcode.backend import DEFAULT_SECONDS_PER_TICK
+from labcode.backend import DEFAULT_SECONDS_PER_TICK, FROM_ENVIRONMENT
 from labcode.dialect import validate_dialect
+from labcode.extension import DEFAULT_OP_TIMEOUT
 from labcode.runner import run_labcode
 
 EXIT_OK = 0
@@ -84,6 +85,19 @@ def _build_parser() -> argparse.ArgumentParser:
         help="ignore the environment's x-labcode.probe policies and treat every machine as"
              " reachable (the document is still validated)",
     )
+    # One operation timeout for the whole lab, in real seconds. The two forms exclude each
+    # other: asking for a limit and for no limit in the same breath is a mistake, not a
+    # precedence puzzle to resolve quietly.
+    timeout = p.add_mutually_exclusive_group()
+    timeout.add_argument(
+        "--op-timeout", type=float, default=None, metavar="S",
+        help="stop and fail an operation that has run for S real seconds (default: the"
+             f" environment's x-labcode.op_timeout, else {DEFAULT_OP_TIMEOUT:g})",
+    )
+    timeout.add_argument(
+        "--no-op-timeout", action="store_true",
+        help="let an operation run for as long as it takes, whatever the environment says",
+    )
     return p
 
 
@@ -131,6 +145,16 @@ def main(argv: Sequence[str] | None = None) -> int:
             print(f"lc run: {label} not found: {path!r}", file=sys.stderr)
             return EXIT_USAGE
 
+    # A limit of zero (or less) is not "no limit" -- that is what --no-op-timeout says --
+    # so it is a usage error rather than something to interpret.
+    if args.op_timeout is not None and not args.op_timeout > 0:
+        print(
+            f"lc run: --op-timeout must be a positive number of seconds "
+            f"(got {args.op_timeout:g}); use --no-op-timeout for no limit",
+            file=sys.stderr,
+        )
+        return EXIT_USAGE
+
     # Shared workflow front door (ofplang-validate + capability gate; validate skippable).
     fd = front_door_check(args.workflow, validate=not args.no_validate)
     if not fd.ok:
@@ -193,6 +217,16 @@ def main(argv: Sequence[str] | None = None) -> int:
             else ""
         )
 
+    def timeout_note(kind: str) -> str:
+        # The upstream failure says what happened and that nothing cancelled the
+        # instrument; what it cannot say is how *this* CLI's user changes the limit.
+        if kind != "op_timeout":
+            return ""
+        return (
+            " (raise the limit with --op-timeout SECONDS or the environment root's"
+            " x-labcode.op_timeout, or drop it entirely with --no-op-timeout)"
+        )
+
     try:
         # Validation already ran at the front doors above, so run trusting. `run_labcode`
         # owns the labcode Object-identity setup (rewrite the workflow's Object types to
@@ -214,6 +248,13 @@ def main(argv: Sequence[str] | None = None) -> int:
             probe=not args.no_probe,
             on_availability_change=report_availability,
             on_cadence_slip=report_cadence_slip,
+            # Three layers, outermost first: this flag, the environment, the default.
+            # `FROM_ENVIRONMENT` is "the flag says nothing"; None is "no limit at all".
+            op_timeout=(
+                None if args.no_op_timeout
+                else FROM_ENVIRONMENT if args.op_timeout is None
+                else args.op_timeout
+            ),
         )
     except (yaml.YAMLError, ContractSyntaxError) as exc:
         print(f"lc run: invalid input: {exc}", file=sys.stderr)
@@ -232,7 +273,8 @@ def main(argv: Sequence[str] | None = None) -> int:
         failure = result.failure
         if failure is not None:
             print(
-                f"lc run: execution failed: {failure.kind}: {failure.detail}{probe_note()}",
+                f"lc run: execution failed: {failure.kind}: {failure.detail}"
+                f"{probe_note()}{timeout_note(failure.kind)}",
                 file=sys.stderr,
             )
         else:

{labcode-0.1.5 → labcode-0.1.6}/labcode/runner.py

@@ -18,11 +18,16 @@ from __future__ import annotations
 
 import time
 from collections.abc import Callable
+from typing import Literal
 
 from ofplang.run.app import RunResult
 from ofplang.run.runner import RollingRunner, RunnerError, load_document
 
-from labcode.backend import DEFAULT_SECONDS_PER_TICK, labcode_backend_factory
+from labcode.backend import (
+    DEFAULT_SECONDS_PER_TICK,
+    FROM_ENVIRONMENT,
+    labcode_backend_factory,
+)
 from labcode.idgen import IdGenerator, SeededUuid4Generator
 from labcode.objectid import inject_boundary_ids, inject_id_field, reserved_collisions
 from labcode.probe import CadenceReporter, ChangeReporter, Prober
@@ -35,9 +40,11 @@ class LabcodeRunner(RollingRunner):
     runner reads it itself). Object types are rewritten to declare ``_id``, the boundary's
     Object inputs are minted, and the labcode backend is wired with a shared `IdGenerator`
     (default: reproducible, seeded). `seconds_per_tick` / `speed` / `spawn` / `monotonic` /
-    `sleep` configure the wall-clock backend and `probe` / `prober` /
-    `on_availability_change` its availability probing (`labcode.probe`); any other keyword
-    is forwarded to `RollingRunner` (e.g. `random_seed`, `down_scope`, `observation_out`).
+    `sleep` configure the wall-clock backend, `probe` / `prober` /
+    `on_availability_change` its availability probing (`labcode.probe`), and `op_timeout`
+    how long one operation may run before it is stopped and failed (default: whatever the
+    environment's ``x-labcode.op_timeout`` says); any other keyword is forwarded to
+    `RollingRunner` (e.g. `random_seed`, `down_scope`, `observation_out`).
 
     **`running_task_margin` defaults to the poll interval here**, not to the upstream 0.
     The margin is how far ahead of *now* a still-running operation is assumed to finish
@@ -64,6 +71,7 @@ class LabcodeRunner(RollingRunner):
         prober: Prober | None = None,
         on_availability_change: ChangeReporter | None = None,
         on_cadence_slip: CadenceReporter | None = None,
+        op_timeout: float | None | Literal["environment"] = FROM_ENVIRONMENT,
         poll_interval: int | None = 1,
         running_task_margin: int | None = None,
         **rolling_kwargs,
@@ -91,6 +99,7 @@ class LabcodeRunner(RollingRunner):
             prober=prober,
             on_availability_change=on_availability_change,
             on_cadence_slip=on_cadence_slip,
+            op_timeout=op_timeout,
         )
         # A margin of at least one tick, defaulting to the poll interval (see the class
         # docstring). An explicit value is honoured as given -- including 0, for a caller

{labcode-0.1.5 → labcode-0.1.6}/labcode.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: labcode
-Version: 0.1.5
+Version: 0.1.6
 Summary: labcode -- a dialect wrapper over the Object-Flow Programming Language toolchain
 Author-email: Kazunari Kaizu <kwaizu@gmail.com>
 License-Expression: MIT
@@ -22,7 +22,7 @@ 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.11
+Requires-Dist: ofplang-run>=0.1.12
 Provides-Extra: test
 Requires-Dist: pytest>=7.0; extra == "test"
 Provides-Extra: dev

{labcode-0.1.5 → labcode-0.1.6}/labcode.egg-info/requires.txt

@@ -1,6 +1,6 @@
 ofplang-validate>=0.1.3
 ofplang-schedule>=0.1.3
-ofplang-run>=0.1.11
+ofplang-run>=0.1.12
 
 [dev]
 pytest>=7.0

labcode-0.1.6/labcode.egg-info/scm_version.json

@@ -0,0 +1,8 @@
+{
+  "tag": "0.1.6",
+  "distance": 0,
+  "node": "g6ac79222ac2f8e4280981ac7b9c860b5862bdbfe",
+  "dirty": false,
+  "branch": "HEAD",
+  "node_date": "2026-08-15"
+}

{labcode-0.1.5 → labcode-0.1.6}/pyproject.toml

@@ -25,16 +25,17 @@ classifiers = [
     "Typing :: Typed",
 ]
 # labcode bundles the toolchain by depending on the ofplang sibling packages. `lc run`
-# is the labcode dialect backend, so the floors reflect what it needs: run must take a
-# *transporter* out of the plan when `down_devices` reports one, which is what availability
-# probing depends on for the machines that carry material (>=0.1.11); schedule's in-memory
-# workflow acceptance (>=0.1.3); validate's `$import` expansion API so the front door hands
-# the expanded document on (>=0.1.3). `validate` and `schedule` subcommands still forward
-# unchanged.
+# is the labcode dialect backend, so the floors reflect what it needs: run must bound how
+# long one operation may run (`SubprocessBackend(op_timeout=...)`), which is what the
+# lab-wide `x-labcode.op_timeout` is carried by (>=0.1.12, and which also takes a
+# *transporter* out of the plan when `down_devices` reports one, from 0.1.11); schedule's
+# in-memory workflow acceptance (>=0.1.3); validate's `$import` expansion API so the front
+# door hands the expanded document on (>=0.1.3). `validate` and `schedule` subcommands
+# still forward unchanged.
 dependencies = [
     "ofplang-validate>=0.1.3",
     "ofplang-schedule>=0.1.3",
-    "ofplang-run>=0.1.11",
+    "ofplang-run>=0.1.12",
 ]
 
 [project.urls]

{labcode-0.1.5 → labcode-0.1.6}/tests/test_backend.py

@@ -19,6 +19,7 @@ from labcode.backend import (
     make_code_resolver,
     make_transport_resolver,
 )
+from labcode.extension import DEFAULT_OP_TIMEOUT
 
 WF_DEF = {"script": {"language": "python", "code": "WF"}}
 
@@ -84,6 +85,57 @@ def test_factory_builds_labcode_backend():
     backend.close()
 
 
+# -- the operation timeout: three layers, outermost first ----------------------
+
+
+def _timeout_env(**extension) -> dict:
+    env = {
+        "time": {"unit": "second"},
+        "devices": [{"id": "rack", "spots": ["slot"]}],
+        "transporters": [{"id": "arm"}],
+        "transports": [],
+        "processes": {},
+        "objective": {"kind": "makespan"},
+    }
+    if extension:
+        env["x-labcode"] = extension
+    return env
+
+
+def _built(env: dict, **kw) -> float | None:
+    backend = labcode_backend_factory(seconds_per_tick=0.001, **kw)(env)
+    try:
+        return backend._op_timeout
+    finally:
+        backend.close()
+
+
+def test_a_lab_that_says_nothing_still_gets_a_limit():
+    # The point of the default: the hang that stops a run silently is exactly the one
+    # nobody thought to bound.
+    assert _built(_timeout_env()) == DEFAULT_OP_TIMEOUT
+
+
+def test_the_environment_sets_the_limit():
+    assert _built(_timeout_env(op_timeout=120)) == 120.0
+
+
+def test_the_environment_can_ask_to_wait_forever():
+    # A declared null is a decision on the record, unlike saying nothing.
+    assert _built(_timeout_env(op_timeout=None)) is None
+
+
+def test_the_caller_overrides_the_environment():
+    assert _built(_timeout_env(op_timeout=120), op_timeout=30.0) == 30.0
+    assert _built(_timeout_env(op_timeout=120), op_timeout=None) is None
+
+
+def test_a_malformed_limit_falls_back_to_the_default():
+    # The dialect front door rejects it; if one reaches execution anyway, falling back to
+    # the default is the safe reading -- silently meaning "no limit" is not.
+    assert _built(_timeout_env(op_timeout="soon")) == DEFAULT_OP_TIMEOUT
+
+
 # -- transport resolution / dispatch -------------------------------------------
 
 

{labcode-0.1.5 → labcode-0.1.6}/tests/test_dialect.py

@@ -145,6 +145,35 @@ def test_a_connection_at_the_environment_root_is_rejected():
     assert any("unknown key 'connection'" in e for e in result.errors)
 
 
+def test_the_root_holds_the_operation_timeout():
+    # One value for the whole lab: how long any operation may run before labcode stops
+    # waiting for it. A positive number of real seconds, or null for no limit at all.
+    for value in (7200, 0.5, None):
+        env = _device_env(_device())
+        env["x-labcode"] = {"op_timeout": value}
+        result = validate_dialect({}, env)
+        assert result.ok, result.errors
+
+
+def test_a_nonsensical_operation_timeout_is_rejected():
+    # Zero is not "no limit" (null is), and neither a string nor an infinity is a wait.
+    for value in (0, -1, "3600", True, float("inf"), float("nan")):
+        env = _device_env(_device())
+        env["x-labcode"] = {"op_timeout": value}
+        result = validate_dialect({}, env)
+        assert not result.ok, value
+        assert any("op_timeout" in e for e in result.errors)
+
+
+def test_an_operation_timeout_on_a_machine_is_rejected():
+    # Per-machine limits are deliberately not a thing: a script that knows what it waits
+    # for says so itself (`settle`), and the outer net is one number for the lab.
+    env = _device_env(_device(**{"x-labcode": {"op_timeout": 60}}))
+    result = validate_dialect({}, env)
+    assert not result.ok
+    assert any("unknown key 'op_timeout'" in e for e in result.errors)
+
+
 def test_x_labcode_on_a_process_is_rejected():
     env = _env({"id": "v0"})
     env["processes"]["m"]["x-labcode"] = {"connection": CONNECTION}

{labcode-0.1.5 → labcode-0.1.6}/tests/test_run_cli.py

@@ -275,6 +275,82 @@ def test_cli_no_probe_ignores_the_policy(tmp_path, capsys):
     assert "unreachable" not in capsys.readouterr().err
 
 
+# -- the operation timeout -----------------------------------------------------
+
+#: `device_script.env.yaml`, but the measurement never returns. This is what an
+#: instrument that has stopped answering looks like from labcode's side: the child is
+#: alive, so no poll will ever complete the op.
+HANGING_ENV = """\
+time: {unit: second}
+devices: [{id: rack, spots: [slot]}]
+transporters: [{id: arm}]
+transports: []
+processes:
+  measure:
+    modes:
+      - id: v0
+        duration: 3
+        x-labcode:
+          script:
+            language: python
+            code: |
+              import time
+              time.sleep(600)
+              return {"od": 0.42}
+objective: {kind: makespan}
+"""
+
+
+def test_cli_stops_a_hung_operation_and_says_how_to_change_the_limit(tmp_path, capsys):
+    # End to end with a real child process: the script hangs, the deadline stops it, and
+    # the run ends the way any failure does -- a status document, a reason, exit 1 --
+    # instead of polling for as long as anyone is willing to wait.
+    pytest.importorskip("ofplang.schedule", reason="ofplang-schedule not installed")
+    env = tmp_path / "hanging.env.yaml"
+    env.write_text(HANGING_ENV, encoding="utf-8")
+    status = tmp_path / "status.yaml"
+    code = run_cli.main([
+        WF, "--env", str(env), "--seconds-per-tick", "0.01",
+        "--op-timeout", "1", "-o", str(status),
+    ])
+    assert code == 1
+    err = capsys.readouterr().err
+    assert "op_timeout" in err
+    assert "did not finish within 1s" in err
+    assert "--no-op-timeout" in err  # the way out is in the message
+    assert status.exists()  # the failure is on the record, not just on stderr
+
+
+def test_cli_rejects_a_zero_timeout(tmp_path, capsys):
+    # Zero is not a way to say "no limit"; --no-op-timeout is.
+    code = run_cli.main([WF, "--env", ENV, "--op-timeout", "0"])
+    assert code == 2
+    assert "--no-op-timeout" in capsys.readouterr().err
+
+
+def test_cli_rejects_asking_for_both_a_limit_and_no_limit():
+    with pytest.raises(SystemExit) as excinfo:
+        run_cli.main([WF, "--env", ENV, "--op-timeout", "10", "--no-op-timeout"])
+    assert excinfo.value.code == 2
+
+
+def test_cli_no_op_timeout_asks_for_no_deadline(monkeypatch):
+    # The flag has to reach the backend, since nothing else can express "wait forever".
+    seen = {}
+
+    def fake_run(*args, **kwargs):
+        from ofplang.run.app import RunResult
+
+        seen["op_timeout"] = kwargs.get("op_timeout")
+        return RunResult(
+            status={"now": 0, "activities": []}, result_boundary={}, failed=False, failure=None
+        )
+
+    monkeypatch.setattr(run_cli, "run_labcode", fake_run)
+    assert run_cli.main([WF, "--env", ENV, "--no-op-timeout"]) == 0
+    assert seen["op_timeout"] is None
+
+
 def test_cli_warns_on_typed_default(tmp_path, capsys, monkeypatch):
     # A process with no script warns (typed-default no-op) but still runs. Stub the run so
     # the test does not spend real wall-clock time.

labcode-0.1.5/labcode.egg-info/scm_version.json

@@ -1,8 +0,0 @@
-{
-  "tag": "0.1.5",
-  "distance": 0,
-  "node": "gad4beebfe8287e650c5d40dfe4ce43a0e9f47139",
-  "dirty": false,
-  "branch": "HEAD",
-  "node_date": "2026-08-10"
-}