labcode 0.9.0__tar.gz → 0.10.0__tar.gz

{labcode-0.9.0 → labcode-0.10.0}/CHANGELOG.md

@@ -6,6 +6,50 @@ specification the section numbers refer to is [`docs/SPECIFICATIONS.md`](docs/SP
 Releases before 0.9.0 are described in the messages of their `Release vX.Y.Z` commits
 (`git log --grep '^Release v'`).
 
+## 0.10.0 — 2026-10-05
+
+labcode runs a protocol repeated over every plate (`map` / `fold`), and stops making up
+a value a script did not compute.
+
+### Added
+
+- **`map` and `fold`** run, as ofplang-schedule 0.13 expands them and ofplang-run 0.13
+  executes the expansion. An **Array of Objects** at the run boundary is one Object per
+  element: its `view` is a list of views, one per spot, and each element gets its own
+  `_id`, keyed by the element (`plates[1]`, §4.3). An invocation's node path carries its
+  iteration index, and so do the keys of what it creates.
+- **What a run made up, it says** (`lc run` prints each as `lc run: warning: ...`):
+  - `entry_input_defaulted` — a boundary view written in part, or not at all: the
+    declared fields it left out run on their type's default (§4.2). Once per Object.
+  - `output_view_defaulted` — a script that did not return an Object it created: the
+    view runs on its type's default (§1.2). Once per process and port.
+  - `_id` is never reported; minting it is labcode's identity, not a default.
+
+### Changed — may need your attention
+
+- **A script must return every Pure Data output it declares** (§1.2). Until now one left
+  out took its type's default — `return {}` from a `read` gave `od: 0.0`, a reading
+  nothing took. It now fails the operation (`script_output_names`), as v0 §22.2 does. An
+  Object output may still be left out: a mapped one is carried, a created one gets its
+  default view (reported).
+- **A process with no script anywhere that declares a Pure Data output is refused** by
+  `lc run` before anything runs (§2): a no-op can compute nothing, so every run of it
+  would fail. One with only Object outputs still runs as a no-op, with the warning it
+  always had. A process with a script on some modes only fails if a mode without one is
+  chosen.
+- **A boundary view that is not a mapping** (or, for an Array, not a list of them) is
+  refused. It used to be replaced by an empty view without a word.
+- **An Object mapped from an input with no `_id`** fails the operation
+  (`missing_object_id`). No run can reach this; it is there to catch a broken invariant
+  early.
+- A v0 §22 workflow script in a language other than Python fails the operation
+  (`script_language`) instead of running as a no-op.
+- Requires ofplang-validate 0.3, ofplang-schedule 0.13 and ofplang-run 0.13
+  (specification revision 0.4).
+
+`lc export` is unchanged; drawing a run that has `map` / `fold` invocations in it is not
+yet supported there.
+
 ## 0.9.0 — 2026-09-28
 
 labcode can now drive a lab over **LADS OPC UA** as well as SiLA2, and gains `lc export`.

{labcode-0.9.0 → labcode-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: labcode
-Version: 0.9.0
+Version: 0.10.0
 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.3,>=0.2
-Requires-Dist: ofplang-schedule<0.13,>=0.9
-Requires-Dist: ofplang-run<0.13,>=0.11
+Requires-Dist: ofplang-validate<0.4,>=0.3
+Requires-Dist: ofplang-schedule<0.14,>=0.13
+Requires-Dist: ofplang-run<0.14,>=0.13
 Provides-Extra: test
 Requires-Dist: pytest>=7.0; extra == "test"
 Requires-Dist: opentelemetry-sdk>=1.20; extra == "test"

{labcode-0.9.0 → labcode-0.10.0}/docs/SPECIFICATIONS.md

@@ -74,26 +74,29 @@ port names**, each bound to that port's view value (Pure Data or an Object's vie
 — as in a v0 §22 `python_script_processes` script. External `import` is allowed; there is
 no sandbox.
 
-**Partial outputs.** Unlike v0 §22.2 (which requires the script to return *every* output
-exactly), a labcode process script `return`s only the outputs it **computes** — a subset.
-The backend fills the rest:
+**Object outputs need not be returned.** As in v0 §22.2, a labcode process script
+returns its outputs as a mapping, and **every Pure Data output it declares must be in
+it**: a measurement nothing computed has no value to give, and a default would be a
+made-up reading. One left out fails the operation (`script_output_names`), as does a
+returned name that is not a declared output (this catches a typo'd name). Each returned
+value must conform to its port's type.
+
+An **Object** output may be left out, because labcode can supply it without making a
+value up:
 
 - an Object output declared in `objects.map` is **carried from its input** (the same
   Object, its view unchanged) — so a pass-through need not restate it;
-- any other unset output gets a **typed default** for its type.
-
-The script's returned values override these. Each returned value must conform to its port's
-type, and **returning a name that is not a declared output is an error** (this catches a
-typo'd output name). A §22.2-strict script — one that returns every output explicitly —
-works unchanged.
+- an Object output declared in `objects.create` gets its type's **default view** (and a
+  freshly minted `_id`, §4.2). That view is a value labcode made up, so the run reports it
+  (`output_view_defaulted`, once per process and port); returning the view says what it
+  is, and the warning goes away. `_id` is never part of what is reported (§4.2).
 
-So for `read` (input `plate`, outputs `plate` via `objects.map` + `od`), all three are
-equivalent to returning `{"plate": plate, "od": 0.42}`… except the defaulted forms:
+So for `read` (input `plate`, outputs `plate` via `objects.map` + `od`):
 
 ```python
 return {"plate": plate, "od": 0.42}   # explicit
 return {"od": 0.42}                    # plate carried by objects.map
-return {}                              # plate carried; od defaults to 0.0
+return {}                              # fails: od is not returned
 ```
 
 ### 1.3 `x-labcode` on a transport route
@@ -645,15 +648,20 @@ For a dispatched `(process, mode)`, labcode resolves the code to run in this ord
 
 1. the mode's `x-labcode.script.code` (2 — the labcode device script), else
 2. the workflow process's own `script.code` (1 — a v0 §22 script process), else
-3. none — the operation runs as a **typed-default no-op** (its outputs are typed
-   defaults; a device not yet scripted).
+3. none — the operation runs as a **no-op** (a device not yet scripted): its Object
+   outputs are supplied as above (§1.2), and a Pure Data output, which only a script
+   could compute, fails the operation (`script_output_names`).
 
 **Exclusivity (error).** A process MUST NOT carry both a workflow `script` (1) and an env
 `x-labcode.script` (2) on any of its modes; that is ambiguous and is rejected.
 
-**Typed-default reachability (warning).** A process with neither (1) nor (2) on any mode
-will run as a typed-default no-op. This is allowed — convenient while mocking a device —
-but `lc run` warns about it, so an unimplemented device is not silently a no-op.
+**No-op reachability (warning, or error).** A process with neither (1) nor (2) on any
+mode will run as a no-op. This is allowed — convenient while mocking a device — but `lc
+run` warns about it, so an unimplemented device is not silently a no-op. A process that
+also declares a **Pure Data output** is refused instead: every run of it would fail, so
+it fails before anything runs. A process with a script on some modes and not others is
+not refused — which mode runs is the scheduler's choice — and fails only if a mode
+without one is chosen.
 
 **Transport and replenishment routes have no such chain.** There is nothing for them to
 fall back to: a workflow describes neither a physical move nor a refill, so the route's
@@ -744,13 +752,17 @@ An Object's `_id` is set at its two points of origin, then **carried** everywher
 `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).
+  produces it. A device script need not know about `_id`: it returns the view (or leaves
+  the Object out, §1.2), and labcode supplies `_id`.
 - **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.
+  mints its `_id`, **unless the boundary already carries one** — so a result boundary fed
+  back in round-trips its ids. An **Array of Objects** is one Object per element: its
+  `view`, if given, is a list of views, one per spot, and each element gets its own `_id`.
+  A view may be written in part: a declared field it leaves out takes its type's default,
+  and the run reports which (`entry_input_defaulted`, once per element). A view that is
+  not a mapping is refused, not replaced.
+- **What is reported.** `_id` is never in a warning: minting it is this feature, not a
+  default. Only a declared view field labcode had to fill is.
 - **`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.
 
@@ -759,16 +771,16 @@ An Object's `_id` is set at its two points of origin, then **carried** everywher
 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
+boundary input (`plates[1]` for an element of an Array) — **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.
+> The provenance key is the runner's node-instance identity + port. An invocation of an
+> expanded `map` / `fold` has its iteration index in its node path (`Load/2`), so each
+> invocation's creates key apart and stay reproducible. Dynamic control flow
+> (`do_while`) is not run.
 
 ## 5. Not yet in this version (roadmap)
 

{labcode-0.9.0 → labcode-0.10.0}/examples/README.md

@@ -29,8 +29,8 @@ load ──[move]──> dispense ──[move]──> read ──[move]──> s
   **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
+  carried, so the script returns only the reading — an Object output need not be
+  returned, 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
@@ -189,7 +189,7 @@ result boundary does not, carrying none.
 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.
+and the produced value comes back as the script's return, the plate carried by labcode.
 
 ```
    (in) plate ──[move]──▶ seal ──[move]──▶ (out) plate

{labcode-0.9.0 → labcode-0.10.0}/labcode/_child.py

@@ -1,12 +1,11 @@
-"""labcode's out-of-process child harness (the partial-output dialect).
+"""labcode's out-of-process child harness.
 
-Like ``ofplang.run.simulator._child``, but labcode process scripts follow the labcode
-dialect's **partial** output convention (SPECIFICATIONS.md §1.2): a script returns only the
-outputs it computes, and the backend fills the rest -- carrying an Object output through
-``objects.map`` (identity preserved) and defaulting the others. So this child does **no**
-output verification; it just returns the script's raw result mapping. The merge, the
-conformance check, and the rejection of any *extra* (undeclared) output name all happen in
-`labcode.backend.LabcodeBackend`.
+Like ``ofplang.run.simulator._child``, but a labcode process script may leave out an
+Object output (SPECIFICATIONS.md §1.2), which the backend supplies -- carried through
+``objects.map``, or a created Object's default view. So this child does **no** output
+verification; it just returns the script's raw result mapping. The check that every Pure
+Data output is there, the rejection of any *extra* (undeclared) output name, the Object
+fill and the conformance check all happen in `labcode.backend.LabcodeBackend`.
 
 A transport or refill script is side-effect only (its return is ignored). Protocol (JSON on
 stdin, outcome to ``result_path``) is identical to the upstream child; only the process
@@ -61,7 +60,7 @@ def _execute(job: dict, result_path: str) -> int:
                            f"{type(raw).__name__}, not a mapping",
             }}
         else:
-            # A partial mapping is allowed: the backend merges and verifies it (§1.2).
+            # Object outputs may be missing: the backend supplies and verifies (§1.2).
             payload = {"outputs": raw}
     except DeviceComputationError as exc:
         payload = {"error": {"code": exc.code, "message": str(exc)}}

{labcode-0.9.0 → labcode-0.10.0}/labcode/backend.py

@@ -66,7 +66,7 @@ from labcode.extension import (
     transporter_connections,
 )
 from labcode.idgen import DEFAULT_ID_GENERATOR, IdGenerator
-from labcode.objectid import RESERVED_ID, stamp_object_ids
+from labcode.objectid import RESERVED_ID, object_output_ports, stamp_object_ids
 from labcode.probe import (
     Availability,
     CadenceReporter,
@@ -289,8 +289,8 @@ def _labcode_child_spawn(job: dict, env: Mapping[str, str] | None = None):
 
 
 class LabcodeBackend(SubprocessBackend):
-    """A `SubprocessBackend` for the labcode dialect: partial process outputs + transport
-    execution.
+    """A `SubprocessBackend` for the labcode dialect: Object outputs filled for a script +
+    transport execution.
 
     Two dialect behaviours on top of the base backend:
 
@@ -299,11 +299,12 @@ class LabcodeBackend(SubprocessBackend):
       moved Object's view bound as locals (``from_spot`` / ``to_spot`` / ``transporter`` /
       ``view``). It reuses the upstream machinery -- `_start_child_op` launches it and the
       settle loop completes / fails it (ofplang-run >= 0.1.6) -- so only dispatch is added.
-    * **Partial process outputs** (SPECIFICATIONS.md §1.2). A process script returns only
-      the outputs it computes; `_resolve_model` fills the rest from `default_device_model`
-      (carrying an Object output via ``objects.map``, defaulting the others) and merges the
-      script's values on top. A returned name that is not a declared output is an error.
-      This needs the partial-tolerant `labcode._child` (the default `spawn`), since the
+    * **Object outputs need not be returned** (SPECIFICATIONS.md §1.2). A process script
+      returns every Pure Data output it declares, and may leave out an Object output:
+      `_resolve_model` carries a mapped one (``objects.map``) and gives a created one a
+      default view, reported in `warnings`. A Pure Data output left out, or a returned
+      name that is not a declared output, is an error -- nothing makes a measurement up.
+      This needs the Object-tolerant `labcode._child` (the default `spawn`), since the
       upstream child verifies outputs exactly."""
 
     def __init__(
@@ -343,6 +344,11 @@ class LabcodeBackend(SubprocessBackend):
         # with the run boundary's minting so a run's ids are consistent; default is the
         # reproducible seeded generator.
         self._id_gen = id_generator or DEFAULT_ID_GENERATOR
+        # Values this backend made up and said so (`ofplang.run` `RunWarning`): the view
+        # of a created Object its script did not return. One per (job, process, port),
+        # however many operations of it there were.
+        self.warnings: list = []
+        self._warned: set = set()
 
     # -- recording what the run did (`labcode.record`) -------------------------------
 
@@ -422,46 +428,89 @@ class LabcodeBackend(SubprocessBackend):
 
     def _resolve_model(self, process, mode, inputs, output_schema, definition,
                        node=None, job=None):
-        """The value model `_complete` calls at completion: merge the script's *partial*
-        outputs onto the defaults (§1.2), then stamp Object identities (`_id`).
-
-        `default_device_model` supplies the base (``objects.map`` Object carry + typed
-        defaults); the script's returned values override it. A returned name outside
-        `output_schema` is a runtime failure. `stamp_object_ids` then mints ``_id`` for a
-        created Object and carries it for a mapped one (keyed by `node`, the workflow
-        provenance, **and by `job`** -- two jobs of one workflow render the same node
-        path, so the node alone would mint one identity for two plates). A timed op (no
-        child) or a child error is handled as in the base backend.
+        """The value model `_complete` calls at completion: the script's outputs, with any
+        Object output it left out filled (§1.2), then Object identities (`_id`) stamped.
+
+        Every Pure Data output must come from the script: one it leaves out -- or a
+        process with no script at all that declares one (§2) -- is a runtime failure
+        (`script_output_names`), since nothing else could compute it and a default would
+        be a made-up measurement. An Object output may be left out: `default_device_model`
+        carries a mapped one, and gives a created one a default view, which is reported
+        (`warnings`). A returned name outside `output_schema` is a runtime failure.
+        `stamp_object_ids` then mints ``_id`` for a created Object and carries it for a
+        mapped one (keyed by `node`, the workflow provenance, **and by `job`** -- two jobs
+        of one workflow render the same node path, so the node alone would mint one
+        identity for two plates). A child error is handled as in the base backend.
 
         🔴 Both halves arrive here rather than at dispatch because this is where an
         identity is *made*: the runner offers provenance to a model that declares it
         (`ofplang-run` >= 0.11), and the simulator carries it on the operation from the
         dispatch that started it."""
         pending = self._pending
+        created, mapped = object_output_ports(definition)
+        object_ports = set(created) | set(mapped)
         if not isinstance(pending, dict):  # the _TIMED sentinel: no child ran
-            outputs = default_device_model(process, mode, inputs, output_schema, definition)
-            return stamp_object_ids(
-                outputs, definition, inputs or {}, node, self._id_gen, output_schema,
-                job=job,
-            )
-        if "error" in pending:
-            err = pending["error"]
-            raise DeviceComputationError(
-                err.get("message", "child failed"), code=err.get("code", "child_error")
-            )
-        raw = pending.get("outputs") or {}
-        extra = set(raw) - set(output_schema or {})
-        if extra:
-            raise DeviceComputationError(
-                f"script process {process!r} returned undeclared output names {sorted(extra)}",
-                code="script_output_names",
-            )
+            # A workflow script in a language no child runs is a failure, as in the base
+            # backend -- not a process without a script.
+            script = (definition or {}).get("script")
+            if script is not None and python_code(script) is None:
+                language = script.get("language") if isinstance(script, dict) else None
+                raise DeviceComputationError(
+                    f"script process {process!r} declares unsupported script language "
+                    f"{language!r}",
+                    code="script_language",
+                )
+            raw: dict = {}
+            what = f"process {process!r} mode {mode!r} has no script, and nothing computes"
+        else:
+            if "error" in pending:
+                err = pending["error"]
+                raise DeviceComputationError(
+                    err.get("message", "child failed"), code=err.get("code", "child_error")
+                )
+            raw = pending.get("outputs") or {}
+            extra = set(raw) - set(output_schema or {})
+            if extra:
+                raise DeviceComputationError(
+                    f"script process {process!r} returned undeclared output names "
+                    f"{sorted(extra)}",
+                    code="script_output_names",
+                )
+            what = f"script process {process!r} did not return"
+        # Every Pure Data output has to be computed: there is no default for one (D59).
+        missing = sorted(set(output_schema or {}) - object_ports - set(raw))
+        if missing:
+            raise DeviceComputationError(f"{what} output(s) {missing}", code="script_output_names")
         base = default_device_model(process, mode, inputs, output_schema, definition)
+        # A created Object the script did not return starts with a default view: say so.
+        for port in created:
+            if port not in raw:
+                self._warn_defaulted_view(process, port, node, job, output_schema)
         return stamp_object_ids(
             {**base, **raw}, definition, inputs or {}, node, self._id_gen, output_schema,
             job=job,
         )
 
+    def _warn_defaulted_view(self, process, port, node, job, output_schema) -> None:
+        """Report a created Object whose view runs on its type's defaults, once per job,
+        process and port. ``_id`` is not a default -- it is minted -- so a type with no
+        other view field gives nothing to report."""
+        from ofplang.run.runner.job import RunWarning
+
+        fields = (output_schema or {}).get(port, {}).get("fields") or {}
+        defaulted = [field for field in fields if field != RESERVED_ID]
+        key = (job or "", process, port)
+        if not defaulted or key in self._warned:
+            return
+        self._warned.add(key)
+        where = "/".join(str(step) for step in node) if node else "?"
+        self.warnings.append(RunWarning(
+            "output_view_defaulted",
+            f"process {process!r} did not return its created Object {port!r} (first at "
+            f"{where}), so view field(s) {defaulted} run on their type's default",
+            job or "",
+        ))
+
     def advance(self, until: int) -> int:
         """Pace the wall clock as the base backend does, and say so once if this run
         cannot keep the cadence it was asked for.

{labcode-0.9.0 → labcode-0.10.0}/labcode/dialect.py

@@ -70,7 +70,7 @@ from labcode.extension import (
     transport_label,
     unknown_key_messages,
 )
-from labcode.objectid import RESERVED_ID, reserved_collisions
+from labcode.objectid import RESERVED_ID, object_output_ports, reserved_collisions
 
 
 @dataclass
@@ -375,12 +375,24 @@ def _validate_processes(
                 f"process {name!r} has both a workflow script (1) and an env "
                 f"x-labcode.script (2); they are mutually exclusive"
             )
-        # typed-default reachability -- a warning, not an error.
+        # A process with no script anywhere runs as a no-op. That is allowed -- a device not
+        # scripted yet, while the rest is mocked -- and warned about. But a no-op computes
+        # nothing, so a Pure Data output it declares could only be made up: such a process
+        # is certain to fail every time it runs, and is refused here, before it does (D59).
         if not wf_has_script and not modes_with_script:
-            warnings.append(
-                f"process {name!r} has no script (workflow or x-labcode); its operations "
-                f"will run as a typed-default no-op"
-            )
+            created, mapped = object_output_ports(wf_procs.get(name))
+            declared = (wf_procs.get(name) or {}).get("outputs") or {}
+            computed = sorted(set(declared) - set(created) - set(mapped))
+            if computed:
+                errors.append(
+                    f"process {name!r} has no script (workflow or x-labcode) but declares "
+                    f"output(s) {computed}, which only a script can compute"
+                )
+            else:
+                warnings.append(
+                    f"process {name!r} has no script (workflow or x-labcode); its operations "
+                    f"will run as a no-op"
+                )
 
 
 def _check_reserved_locals(wf_process: Any, label: str, errors: list, flavor: str) -> None: