ofplang-run 0.1.0__tar.gz

ofplang_run-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,56 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      # `ofplang-schedule` and `ofplang-validate` are sibling repos, not on PyPI.
+      # Install them from git so the runner's schedule-dependent tests and the CLI
+      # front door resolve. validate first: schedule itself depends on it.
+      - run: pip install "ofplang-validate @ git+https://github.com/ofplang/validate.git@main"
+      - run: pip install "ofplang-schedule @ git+https://github.com/ofplang/schedule.git@main"
+      - run: pip install -e ".[test]"
+      - run: pytest
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      # ruff is a static analyzer: it needs neither the project installed nor the
+      # (PyPI-absent) ofplang-schedule dependency resolved, so install ruff alone.
+      - run: pip install "ruff>=0.16"
+      - run: ruff check ofplang tests
+
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      # mypy resolves `ofplang.schedule` and `ofplang.validate`, so install both
+      # sibling repos from git too (validate first: schedule depends on it).
+      - run: pip install "ofplang-validate @ git+https://github.com/ofplang/validate.git@main"
+      - run: pip install "ofplang-schedule @ git+https://github.com/ofplang/schedule.git@main"
+      - run: pip install -e ".[dev]"
+      - run: mypy

ofplang_run-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,96 @@
+name: Publish
+
+# Tag-driven release via PyPI Trusted Publishing (OIDC) — no API tokens.
+#
+# Version comes from the pushed git tag via setuptools-scm (`v0.1.0` -> 0.1.0).
+# Routing:
+#   - a pre-release tag containing `rc` (e.g. v0.1.0rc1) -> TestPyPI (rehearsal)
+#   - any other `v*` tag (e.g. v0.1.0)                    -> PyPI (production)
+#   - manual workflow_dispatch -> choose the target explicitly (run it from a
+#     tagged commit, else setuptools-scm yields a dev+local version PyPI rejects)
+#
+# PyPI-side setup (done once, by the project owner): register a Trusted Publisher
+# for owner=ofplang, repo=run, workflow=publish.yml, environment=pypi
+# (and environment=testpypi on TestPyPI). First release: register as "pending".
+#
+# Publish order across the org: validate -> schedule -> run. Do not publish this
+# before ofplang-validate and ofplang-schedule are available on the same index.
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+    inputs:
+      target:
+        description: "Publish target"
+        type: choice
+        options: [testpypi, pypi]
+        default: testpypi
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # setuptools-scm derives the version from tags + history.
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install --upgrade build twine
+      - run: python -m build
+      - run: twine check dist/*
+      # Guard against ambiguous tags: the built version (from setuptools-scm) must
+      # equal the pushed tag — e.g. tag v0.1.0 must build 0.1.0. Catches a commit
+      # carrying two tags (an rc and a release) where git describe can resolve to
+      # the wrong one and publish the wrong artifact.
+      - name: Verify built version matches tag
+        if: startsWith(github.ref, 'refs/tags/')
+        shell: bash
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          built="$(ls dist/*.tar.gz | sed -E 's#.*/[^/]*-([0-9][^-]*)\.tar\.gz#\1#')"
+          echo "tag=$tag built=$built"
+          if [ "$tag" != "$built" ]; then
+            echo "::error::built version $built != tag $tag (ambiguous or misplaced tag?)"
+            exit 1
+          fi
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-testpypi:
+    needs: build
+    if: >-
+      github.event_name == 'workflow_dispatch' && inputs.target == 'testpypi'
+      || (github.event_name == 'push' && contains(github.ref_name, 'rc'))
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  publish-pypi:
+    needs: build
+    if: >-
+      github.event_name == 'workflow_dispatch' && inputs.target == 'pypi'
+      || (github.event_name == 'push' && !contains(github.ref_name, 'rc'))
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

ofplang_run-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+*.egg-info/
+build/
+dist/
+.venv/
+venv/
+
+# Local working notes, not part of the published project (until explicitly committed).
+CLAUDE.md
+dev-notes/

ofplang_run-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kazunari Kaizu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ofplang_run-0.1.0/PKG-INFO

@@ -0,0 +1,189 @@
+Metadata-Version: 2.4
+Name: ofplang-run
+Version: 0.1.0
+Summary: Object-flow programming language v0 runner
+Author-email: Kazunari Kaizu <kwaizu@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ofplang/run
+Project-URL: Repository, https://github.com/ofplang/run
+Keywords: ofplang,dataflow,workflow,runner,rolling-horizon
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: ofplang-schedule
+Requires-Dist: ofplang-validate
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; 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: types-PyYAML; extra == "dev"
+Dynamic: license-file
+
+# ofplang run
+
+[![CI](https://github.com/ofplang/run/actions/workflows/ci.yml/badge.svg)](https://github.com/ofplang/run/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/ofplang-run.svg)](https://pypi.org/project/ofplang-run/)
+
+A runner for **Object-flow Programming Language v0** — a YAML-based dataflow
+workflow IR with linear Object tracking. The language is defined in the
+[ofplang/spec](https://github.com/ofplang/spec) repository.
+
+The runner drives an ofplang v0 workflow to completion against an execution
+backend, emitting an execution status document (spec §6/§7) as it progresses and
+routing typed **view values** through the workflow. It runs on a **simulator** — a
+simulated physical backend — so a full workflow can be exercised end to end
+without real hardware; the same dispatch contract targets real hardware later.
+
+> **Status:** the simulator, the runner, and a typed (dummy) value layer are
+> implemented.
+>
+> - **Simulator** (`ofplang.run.simulator`) — a physical backend: devices, spots,
+>   transporters, and timed operations advanced on a virtual clock. It validates
+>   every dispatch (an inconsistent plan is rejected), models timed device up/down
+>   and injected operation failure, and at completion produces each operation's
+>   output view values via a **device model** (the built-in `default_device_model`
+>   fills type defaults and carries Object outputs through from their `objects.map`
+>   inputs; a custom / real model computes them).
+> - **Runner** (`ofplang.run.runner`) — two ways to drive a backend:
+>   - **`replay`** runs a given execution plan (spec §6) on the backend verbatim.
+>   - **`run`** is a rolling-horizon loop: it calls
+>     [`ofplang.schedule`](https://github.com/ofplang/schedule) each tick,
+>     dispatches the work that can start now, advances the clock, and polls —
+>     replanning from the committed history as it goes. It re-routes around a
+>     downed device, polls at a fixed interval with completion-time estimation,
+>     absorbs duration variance (an operation running longer or shorter than
+>     planned), and stops the whole run if any activity fails (marking the abandoned
+>     work cancelled). Device up/down, operation failure, and duration variance are
+>     scenario concerns injected from Python (not CLI flags).
+> - **Value layer** — the runner resolves each port's type and view schema (§7),
+>   routes typed view values along the workflow's arcs (producer output → consumer
+>   input, across nested composites), contract-checks them, and assembles the
+>   whole-workflow outputs. A caller supplies the whole-workflow I/O as a single
+>   **run boundary** (`--boundary`): one document with a per-port `{spot, view}`
+>   descriptor — `spot` places a boundary Object (§6.8), `view` supplies an input
+>   value — for the workflow's entry inputs and final outputs. Unsupplied entry
+>   views default. A workflow-embedded static literal (`bind: {port: {value: …}}`,
+>   §11) is seeded as that consumer input's value in place of a default. At run end
+>   the produced output views are echoed back into a result boundary of the same
+>   schema (`--boundary-out`). Non-script values are typed but still dummy — a real
+>   device backend plugs into the same seam later.
+> - **Python script processes** (spec §22, `python_script_processes`) — an atomic
+>   Pure-Data process may carry a `script: {language: python, code: …}` section.
+>   The built-in device model runs it: the input port values are bound as locals,
+>   the code returns a mapping of the declared outputs, and those become the
+>   operation's computed output values — the first genuine (non-dummy) computation
+>   in the value layer. A script that raises, returns the wrong output names, or
+>   returns a non-conformant value fails runtime verification (§22.2) and stops the
+>   run gracefully like any other activity failure (the failed activity is marked
+>   `failed`, its unstarted successors `cancelled`, exit 1). The script runs inline
+>   in real time but advances no simulation time; its outputs appear when the
+>   operation completes at its `end`, and the environment mode's `duration` is the
+>   scheduler's estimate of the compute cost. Scripts run with full Python builtins
+>   and no import restriction (§22.3 permits an implementation to restrict these;
+>   this one does not).
+> - **Contracts** (spec §9) — an atomic process may declare `contracts` with
+>   `requires` (preconditions over `inputs.*.view`) and `ensures` (postconditions
+>   over `inputs.*.view` and `outputs.*.view`). The runner evaluates them at
+>   runtime against the actual view values: `requires` before the operation runs
+>   (a violation stops it before dispatch), `ensures` after it completes. An atomic
+>   `requires` that references only run/graph-phase inputs (§5.6) is knowable at run
+>   start, so it is checked there as a *preflight* — before any work is dispatched —
+>   rather than waiting for that (possibly late) operation. A
+>   violation — or a runtime evaluation error — stops the run gracefully like any
+>   activity failure (`failed` + downstream `cancelled`, exit 1). Static /
+>   graph-time contract checking (a fully-constant contract that is statically
+>   false, type errors, bad references) is `ofplang-validate`'s job and is not
+>   repeated here. Contracts are checked on atomic processes and on the top-level
+>   entry composite (`main`): the entry composite's `requires` is evaluated at run
+>   start over the whole-workflow inputs (a violation stops the run before any work
+>   runs) and its `ensures` at run end over the whole-workflow inputs and outputs (a
+>   violation marks the completed run failed). Nested composite contracts are checked
+>   too, at each composite invocation's value boundary: its `requires` once its inputs
+>   are available (for an input fed by an upstream process this is mid-run, before the
+>   composite's body runs) and its `ensures` once its outputs are, a violation
+>   stopping the run gracefully at the composite boundary (its not-yet-run body
+>   cancelled). Because non-script process outputs are still typed defaults, `ensures`
+>   bites mainly on script processes and boundary-supplied inputs until a real device
+>   backend computes physical outputs.
+> - **Failure observability** — when a run stops (an injected activity failure, a
+>   script error, or a contract violation), the reason is exposed as a structured
+>   `RollingRunner.failure` (a machine-readable `kind` code, e.g. `contract_requires`
+>   / `script_error`, plus a human-readable `detail`, the `subject`, and the time),
+>   and the CLI prints it to stderr. The status document itself stays a valid §6
+>   document (the reason is out of band). An optional `contract_observer` callback is
+>   invoked for every contract check (held or violated) — a trace hook for debugging.
+> - **Static view values** (spec §7.4) — a type whose view field declares a `value:`
+>   fixes that field to a constant for every value of the type. The runner projects it
+>   onto every view record it routes, so a Python script reading the field and a
+>   contract referencing it both see the static value (not a runtime default). A value
+>   that carries a conflicting one is forced to the static value.
+
+## Install
+
+```sh
+pip install ofplang-run
+```
+
+Requires Python 3.10+. Runtime dependencies (pulled in automatically) are PyYAML,
+the sibling [`ofplang-schedule`](https://pypi.org/project/ofplang-schedule/) that
+`run` (rolling-horizon) calls each tick, and
+[`ofplang-validate`](https://pypi.org/project/ofplang-validate/) used by the CLI
+front door. The runner *library* never imports validate (and the per-tick replans
+never re-validate), so it stays a one-shot CLI front door.
+
+For development, install editable with the test extra from a clone:
+
+```sh
+pip install -e ".[test]"
+```
+
+## Command line
+
+```sh
+ofp-run run <workflow> --env <env>
+    [--boundary DOC] [--boundary-out FILE]
+    [--poll-interval D] [--margin M] [--seed N] [-o OUT]
+ofp-run replay <plan> --env <env> [-o OUT]
+```
+
+`run` drives a v0 workflow to completion by replanning as it goes: each tick it
+renders the committed history as a status, calls the scheduler, and dispatches the
+newly-runnable work. `--boundary` supplies the whole-workflow I/O as one document —
+a `boundary:` mapping with a `{spot, view}` descriptor per entry input / final
+output port. `spot` places a boundary Object on an environment spot (spec §6.8;
+Object ports only); `view` supplies an input's view value (unsupplied entry views
+default). The runner projects it into the scheduler's interface (spots only, so the
+scheduler stays value-independent) and the seeded input values. `--boundary-out`
+writes the result boundary — the same schema with each produced output's `view`
+filled in — a run-local artifact, separate from the value-free status document. On
+completion each pinned Object output is checked to have reached its declared spot.
+`--poll-interval` sets the fixed polling interval (default 1). `replay` runs a plan
+produced by `ofp-schedule` verbatim on the simulator (no value layer). Both write
+the final execution status as YAML (`-o`, else stdout). Exit codes: `0` success,
+`1` execution failed (an activity failed, or a replan is infeasible), `2`
+usage/input error.
+
+This tool is also intended to be exposed as the `run` subcommand of the umbrella
+`ofp` CLI (a separate repository in the `ofplang` organization).
+
+The package lives under the `ofplang` PEP 420 namespace (`ofplang.run`), shared
+across the organization's tools.
+
+## Tests
+
+```sh
+pytest
+```

ofplang_run-0.1.0/README.md

@@ -0,0 +1,155 @@
+# ofplang run
+
+[![CI](https://github.com/ofplang/run/actions/workflows/ci.yml/badge.svg)](https://github.com/ofplang/run/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/ofplang-run.svg)](https://pypi.org/project/ofplang-run/)
+
+A runner for **Object-flow Programming Language v0** — a YAML-based dataflow
+workflow IR with linear Object tracking. The language is defined in the
+[ofplang/spec](https://github.com/ofplang/spec) repository.
+
+The runner drives an ofplang v0 workflow to completion against an execution
+backend, emitting an execution status document (spec §6/§7) as it progresses and
+routing typed **view values** through the workflow. It runs on a **simulator** — a
+simulated physical backend — so a full workflow can be exercised end to end
+without real hardware; the same dispatch contract targets real hardware later.
+
+> **Status:** the simulator, the runner, and a typed (dummy) value layer are
+> implemented.
+>
+> - **Simulator** (`ofplang.run.simulator`) — a physical backend: devices, spots,
+>   transporters, and timed operations advanced on a virtual clock. It validates
+>   every dispatch (an inconsistent plan is rejected), models timed device up/down
+>   and injected operation failure, and at completion produces each operation's
+>   output view values via a **device model** (the built-in `default_device_model`
+>   fills type defaults and carries Object outputs through from their `objects.map`
+>   inputs; a custom / real model computes them).
+> - **Runner** (`ofplang.run.runner`) — two ways to drive a backend:
+>   - **`replay`** runs a given execution plan (spec §6) on the backend verbatim.
+>   - **`run`** is a rolling-horizon loop: it calls
+>     [`ofplang.schedule`](https://github.com/ofplang/schedule) each tick,
+>     dispatches the work that can start now, advances the clock, and polls —
+>     replanning from the committed history as it goes. It re-routes around a
+>     downed device, polls at a fixed interval with completion-time estimation,
+>     absorbs duration variance (an operation running longer or shorter than
+>     planned), and stops the whole run if any activity fails (marking the abandoned
+>     work cancelled). Device up/down, operation failure, and duration variance are
+>     scenario concerns injected from Python (not CLI flags).
+> - **Value layer** — the runner resolves each port's type and view schema (§7),
+>   routes typed view values along the workflow's arcs (producer output → consumer
+>   input, across nested composites), contract-checks them, and assembles the
+>   whole-workflow outputs. A caller supplies the whole-workflow I/O as a single
+>   **run boundary** (`--boundary`): one document with a per-port `{spot, view}`
+>   descriptor — `spot` places a boundary Object (§6.8), `view` supplies an input
+>   value — for the workflow's entry inputs and final outputs. Unsupplied entry
+>   views default. A workflow-embedded static literal (`bind: {port: {value: …}}`,
+>   §11) is seeded as that consumer input's value in place of a default. At run end
+>   the produced output views are echoed back into a result boundary of the same
+>   schema (`--boundary-out`). Non-script values are typed but still dummy — a real
+>   device backend plugs into the same seam later.
+> - **Python script processes** (spec §22, `python_script_processes`) — an atomic
+>   Pure-Data process may carry a `script: {language: python, code: …}` section.
+>   The built-in device model runs it: the input port values are bound as locals,
+>   the code returns a mapping of the declared outputs, and those become the
+>   operation's computed output values — the first genuine (non-dummy) computation
+>   in the value layer. A script that raises, returns the wrong output names, or
+>   returns a non-conformant value fails runtime verification (§22.2) and stops the
+>   run gracefully like any other activity failure (the failed activity is marked
+>   `failed`, its unstarted successors `cancelled`, exit 1). The script runs inline
+>   in real time but advances no simulation time; its outputs appear when the
+>   operation completes at its `end`, and the environment mode's `duration` is the
+>   scheduler's estimate of the compute cost. Scripts run with full Python builtins
+>   and no import restriction (§22.3 permits an implementation to restrict these;
+>   this one does not).
+> - **Contracts** (spec §9) — an atomic process may declare `contracts` with
+>   `requires` (preconditions over `inputs.*.view`) and `ensures` (postconditions
+>   over `inputs.*.view` and `outputs.*.view`). The runner evaluates them at
+>   runtime against the actual view values: `requires` before the operation runs
+>   (a violation stops it before dispatch), `ensures` after it completes. An atomic
+>   `requires` that references only run/graph-phase inputs (§5.6) is knowable at run
+>   start, so it is checked there as a *preflight* — before any work is dispatched —
+>   rather than waiting for that (possibly late) operation. A
+>   violation — or a runtime evaluation error — stops the run gracefully like any
+>   activity failure (`failed` + downstream `cancelled`, exit 1). Static /
+>   graph-time contract checking (a fully-constant contract that is statically
+>   false, type errors, bad references) is `ofplang-validate`'s job and is not
+>   repeated here. Contracts are checked on atomic processes and on the top-level
+>   entry composite (`main`): the entry composite's `requires` is evaluated at run
+>   start over the whole-workflow inputs (a violation stops the run before any work
+>   runs) and its `ensures` at run end over the whole-workflow inputs and outputs (a
+>   violation marks the completed run failed). Nested composite contracts are checked
+>   too, at each composite invocation's value boundary: its `requires` once its inputs
+>   are available (for an input fed by an upstream process this is mid-run, before the
+>   composite's body runs) and its `ensures` once its outputs are, a violation
+>   stopping the run gracefully at the composite boundary (its not-yet-run body
+>   cancelled). Because non-script process outputs are still typed defaults, `ensures`
+>   bites mainly on script processes and boundary-supplied inputs until a real device
+>   backend computes physical outputs.
+> - **Failure observability** — when a run stops (an injected activity failure, a
+>   script error, or a contract violation), the reason is exposed as a structured
+>   `RollingRunner.failure` (a machine-readable `kind` code, e.g. `contract_requires`
+>   / `script_error`, plus a human-readable `detail`, the `subject`, and the time),
+>   and the CLI prints it to stderr. The status document itself stays a valid §6
+>   document (the reason is out of band). An optional `contract_observer` callback is
+>   invoked for every contract check (held or violated) — a trace hook for debugging.
+> - **Static view values** (spec §7.4) — a type whose view field declares a `value:`
+>   fixes that field to a constant for every value of the type. The runner projects it
+>   onto every view record it routes, so a Python script reading the field and a
+>   contract referencing it both see the static value (not a runtime default). A value
+>   that carries a conflicting one is forced to the static value.
+
+## Install
+
+```sh
+pip install ofplang-run
+```
+
+Requires Python 3.10+. Runtime dependencies (pulled in automatically) are PyYAML,
+the sibling [`ofplang-schedule`](https://pypi.org/project/ofplang-schedule/) that
+`run` (rolling-horizon) calls each tick, and
+[`ofplang-validate`](https://pypi.org/project/ofplang-validate/) used by the CLI
+front door. The runner *library* never imports validate (and the per-tick replans
+never re-validate), so it stays a one-shot CLI front door.
+
+For development, install editable with the test extra from a clone:
+
+```sh
+pip install -e ".[test]"
+```
+
+## Command line
+
+```sh
+ofp-run run <workflow> --env <env>
+    [--boundary DOC] [--boundary-out FILE]
+    [--poll-interval D] [--margin M] [--seed N] [-o OUT]
+ofp-run replay <plan> --env <env> [-o OUT]
+```
+
+`run` drives a v0 workflow to completion by replanning as it goes: each tick it
+renders the committed history as a status, calls the scheduler, and dispatches the
+newly-runnable work. `--boundary` supplies the whole-workflow I/O as one document —
+a `boundary:` mapping with a `{spot, view}` descriptor per entry input / final
+output port. `spot` places a boundary Object on an environment spot (spec §6.8;
+Object ports only); `view` supplies an input's view value (unsupplied entry views
+default). The runner projects it into the scheduler's interface (spots only, so the
+scheduler stays value-independent) and the seeded input values. `--boundary-out`
+writes the result boundary — the same schema with each produced output's `view`
+filled in — a run-local artifact, separate from the value-free status document. On
+completion each pinned Object output is checked to have reached its declared spot.
+`--poll-interval` sets the fixed polling interval (default 1). `replay` runs a plan
+produced by `ofp-schedule` verbatim on the simulator (no value layer). Both write
+the final execution status as YAML (`-o`, else stdout). Exit codes: `0` success,
+`1` execution failed (an activity failed, or a replan is infeasible), `2`
+usage/input error.
+
+This tool is also intended to be exposed as the `run` subcommand of the umbrella
+`ofp` CLI (a separate repository in the `ofplang` organization).
+
+The package lives under the `ofplang` PEP 420 namespace (`ofplang.run`), shared
+across the organization's tools.
+
+## Tests
+
+```sh
+pytest
+```

ofplang_run-0.1.0/examples/count_chain.env.yaml

@@ -0,0 +1,20 @@
+# Environment for count_chain.workflow.yaml: `inc` is a device-less Pure-Data-only
+# process (no devices, no spots). The workflow uses no physical resources, but the
+# scheduler requires at least one device to exist, so a single unused rack is
+# declared (the pure-data ops never touch it).
+time:
+  unit: second
+
+devices:
+  - { id: rack, spots: [slot] }
+transporters:
+  - { id: arm }
+transports: []
+
+processes:
+  inc:
+    modes:
+      - { id: v0, duration: 1 }
+
+objective:
+  kind: makespan

ofplang_run-0.1.0/examples/count_chain.workflow.yaml

@@ -0,0 +1,42 @@
+# Pure-Data chain for the job / device-model example (see examples/render_job_run.py):
+# a `Count` value (view {value: Int}) flows from the supplied job, through two
+# device-less `inc` steps, to the returned output. With a device model that adds one
+# each step, the entry value is computed through to the final output -- demonstrating
+# a supplied input propagating through the backend. No object flow, so no interface
+# is needed; it pairs with count_chain.env.yaml.
+spec_version: "0.0"
+
+types:
+  Count:
+    domain: data
+    view:
+      value: { type: Int }
+
+processes:
+  inc:
+    kind: atomic
+    inputs:
+      x: { type: Count, phase: data }
+    outputs:
+      y: { type: Count, phase: data }
+
+  main:
+    kind: composite
+    inputs:
+      start: { type: Count, phase: data }
+    outputs:
+      result: { type: Count, phase: data }
+    body:
+      nodes:
+        - id: S1
+          process: inc
+          bind:
+            x: { from: inputs.start }
+        - id: S2
+          process: inc
+          bind:
+            x: { from: S1.y }
+      returns:
+        result: { from: S2.y }
+
+entry: main

ofplang_run-0.1.0/examples/data_flow.env.yaml

@@ -0,0 +1,44 @@
+# Execution environment for pure_data.workflow.yaml (§5). The plate is loaded on
+# `loader`, measured on `reader`, and finished on `printer`; `arm` moves it along
+# the line. `analyze` is a device-less Pure-Data-only mode with a duration of 0
+# (allowed for a device-less mode, §5.5) -- it holds nothing and takes no time.
+time:
+  unit: second
+
+devices:
+  - id: loader
+    spots: [stage]
+  - id: reader
+    spots: [stage]
+  - id: printer
+    spots: [stage]
+
+transporters:
+  - id: arm
+
+transports:
+  - { transporter: arm, from: loader.stage, to: reader.stage,  duration: 2 }
+  - { transporter: arm, from: reader.stage, to: printer.stage, duration: 2 }
+
+processes:
+
+  measure:
+    modes:
+      - devices: [reader]
+        duration: 4
+        input_spots:  { plate: reader.stage }
+        output_spots: { plate_out: reader.stage }   # in-place transform
+
+  # Device-less Pure-Data-only mode: no devices, no spots, zero duration.
+  analyze:
+    modes:
+      - { id: mean_v1, duration: 0 }
+
+  finish:
+    modes:
+      - devices: [printer]
+        duration: 3
+        input_spots: { plate_in: printer.stage }
+
+objective:
+  kind: makespan