nodus-container 0.1.0__tar.gz

nodus_container-0.1.0/PKG-INFO

@@ -0,0 +1,100 @@
+Metadata-Version: 2.4
+Name: nodus-container
+Version: 0.1.0
+Summary: Container execution primitives for Nodus runtimes (Docker, Podman)
+Author: Shawn Knight
+License: MIT
+Project-URL: Homepage, https://github.com/Masterplanner25/Nodus/tree/main/packages/nodus-container
+Project-URL: Repository, https://github.com/Masterplanner25/Nodus
+Project-URL: Issues, https://github.com/Masterplanner25/Nodus/issues
+Keywords: nodus,container,docker,podman,workflow,orchestration
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Provides-Extra: test
+Requires-Dist: pytest>=9.0; extra == "test"
+
+# nodus-container
+
+Container execution for Nodus workflows — launch a container, capture its result,
+without dropping back to bash.
+
+```python
+from nodus_container import ContainerSpec, Mount, build_argv, run
+
+spec = ContainerSpec(
+    image="alpine:3",
+    command=("echo", "hello"),
+    mounts=(Mount(source="/data", target="/data"),),   # read-only by default
+)
+build_argv(spec)
+# ['docker', 'run', '--rm', '-v', '/data:/data:ro', 'alpine:3', 'echo', 'hello']
+```
+
+`run(spec, runner=...)` executes it through a runner you supply — from Nodus,
+that is `std:subprocess.run`. This package never imports a subprocess module.
+
+## Security: read this before granting it
+
+This is an adapter over `subprocess`, and it declares **no capability of its
+own**. A `container` capability would be unenforceable: anything holding
+`subprocess` can already run `docker` directly, so a control beside it would be
+bypassed by the permission the caller already has.
+
+**The enforceable boundary is `allowed_commands`:**
+
+```python
+NodusRuntime(allow_subprocess=True, allowed_commands=["docker"])
+```
+
+Withhold `docker` from that list and container execution is refused. Setting any
+allowlist also refuses `subprocess.shell`, so `sh -c "docker …"` cannot step
+around it.
+
+**What is still not bounded:** `-v /:/host` escapes `allowed_paths`, and
+`--privileged` exists. That is not a gap this package opens —
+[SECURITY_POSTURE.md §5](https://github.com/Masterplanner25/Nodus/blob/main/docs/governance/SECURITY_POSTURE.md)
+already records that a permitted subprocess's binary and arguments are
+unrestricted — but this package makes it a one-liner, which is worth knowing
+before you grant it. Mounts are read-only by default for that reason.
+
+To restrict *arguments*, use a `CapabilityPolicy`: it receives the call's
+arguments, and `build_argv` is pure so the argv a call would make can be
+inspected before it runs.
+
+### Under `nodus serve`, check which nodus-lang you are on
+
+The server's treatment of submitted code changed in
+[#754](https://github.com/Masterplanner25/Nodus/issues/754), and the two
+behaviours are opposites:
+
+- **Through nodus-lang 5.9.0**, code sent to `POST /execute` ran with subprocess,
+  network and environment access permitted, and **no flag could restrict it**. If
+  you are on one of those releases, anything that can reach the port can run
+  `docker` — put the server behind something that authenticates, and treat this
+  package's presence as incidental to that.
+- **After #754 ships**, submitted code is denied those by default and the
+  operator grants them:
+
+  ```bash
+  nodus serve --auth-token "$TOKEN" --allow-subprocess --allowed-commands docker
+  ```
+
+The allowlist is the part worth typing. `--allow-subprocess` alone permits every
+executable on the host.
+
+## Status
+
+Published from the [nodus-lang repository](https://github.com/Masterplanner25/Nodus/tree/main/packages/nodus-container),
+where it is developed alongside the runtime rather than in a repository of its own.
+
+Design and the capability argument in full:
+[NODUS_CONTAINER.md](https://github.com/Masterplanner25/Nodus/blob/main/docs/ecosystem/NODUS_CONTAINER.md).
+Issue: [#85](https://github.com/Masterplanner25/Nodus/issues/85).

nodus_container-0.1.0/README.md

@@ -0,0 +1,77 @@
+# nodus-container
+
+Container execution for Nodus workflows — launch a container, capture its result,
+without dropping back to bash.
+
+```python
+from nodus_container import ContainerSpec, Mount, build_argv, run
+
+spec = ContainerSpec(
+    image="alpine:3",
+    command=("echo", "hello"),
+    mounts=(Mount(source="/data", target="/data"),),   # read-only by default
+)
+build_argv(spec)
+# ['docker', 'run', '--rm', '-v', '/data:/data:ro', 'alpine:3', 'echo', 'hello']
+```
+
+`run(spec, runner=...)` executes it through a runner you supply — from Nodus,
+that is `std:subprocess.run`. This package never imports a subprocess module.
+
+## Security: read this before granting it
+
+This is an adapter over `subprocess`, and it declares **no capability of its
+own**. A `container` capability would be unenforceable: anything holding
+`subprocess` can already run `docker` directly, so a control beside it would be
+bypassed by the permission the caller already has.
+
+**The enforceable boundary is `allowed_commands`:**
+
+```python
+NodusRuntime(allow_subprocess=True, allowed_commands=["docker"])
+```
+
+Withhold `docker` from that list and container execution is refused. Setting any
+allowlist also refuses `subprocess.shell`, so `sh -c "docker …"` cannot step
+around it.
+
+**What is still not bounded:** `-v /:/host` escapes `allowed_paths`, and
+`--privileged` exists. That is not a gap this package opens —
+[SECURITY_POSTURE.md §5](https://github.com/Masterplanner25/Nodus/blob/main/docs/governance/SECURITY_POSTURE.md)
+already records that a permitted subprocess's binary and arguments are
+unrestricted — but this package makes it a one-liner, which is worth knowing
+before you grant it. Mounts are read-only by default for that reason.
+
+To restrict *arguments*, use a `CapabilityPolicy`: it receives the call's
+arguments, and `build_argv` is pure so the argv a call would make can be
+inspected before it runs.
+
+### Under `nodus serve`, check which nodus-lang you are on
+
+The server's treatment of submitted code changed in
+[#754](https://github.com/Masterplanner25/Nodus/issues/754), and the two
+behaviours are opposites:
+
+- **Through nodus-lang 5.9.0**, code sent to `POST /execute` ran with subprocess,
+  network and environment access permitted, and **no flag could restrict it**. If
+  you are on one of those releases, anything that can reach the port can run
+  `docker` — put the server behind something that authenticates, and treat this
+  package's presence as incidental to that.
+- **After #754 ships**, submitted code is denied those by default and the
+  operator grants them:
+
+  ```bash
+  nodus serve --auth-token "$TOKEN" --allow-subprocess --allowed-commands docker
+  ```
+
+The allowlist is the part worth typing. `--allow-subprocess` alone permits every
+executable on the host.
+
+## Status
+
+Published from the [nodus-lang repository](https://github.com/Masterplanner25/Nodus/tree/main/packages/nodus-container),
+where it is developed alongside the runtime rather than in a repository of its own.
+
+Design and the capability argument in full:
+[NODUS_CONTAINER.md](https://github.com/Masterplanner25/Nodus/blob/main/docs/ecosystem/NODUS_CONTAINER.md).
+Issue: [#85](https://github.com/Masterplanner25/Nodus/issues/85).

nodus_container-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["setuptools>=80", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "nodus-container"
+version = "0.1.0"
+description = "Container execution primitives for Nodus runtimes (Docker, Podman)"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "Shawn Knight" }]
+keywords = ["nodus", "container", "docker", "podman", "workflow", "orchestration"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: System :: Systems Administration",
+]
+
+# No runtime dependencies, and no `nodus-lang` floor: the engine is reached
+# through an injected runner, so nothing here imports a subprocess module or the
+# runtime. Companions do not cap nodus-lang (policy, 2026-08-17) -- see #445.
+dependencies = []
+
+[project.urls]
+# This package is developed inside the nodus-lang repository rather than in one
+# of its own, so both point there. `nodus-store-sql` was promoted out to a
+# separate repo before publishing; that has not been done here, and the URLs say
+# so honestly rather than naming a repository that does not exist.
+Homepage = "https://github.com/Masterplanner25/Nodus/tree/main/packages/nodus-container"
+Repository = "https://github.com/Masterplanner25/Nodus"
+Issues = "https://github.com/Masterplanner25/Nodus/issues"
+
+[project.optional-dependencies]
+test = ["pytest>=9.0"]
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+# The scaffold's own package must win over any same-named production install
+# (#312): `import nodus_container` here means *this* tree.
+pythonpath = ["src"]

nodus_container-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

nodus_container-0.1.0/src/nodus_container/__init__.py

@@ -0,0 +1,23 @@
+"""Container execution primitives for Nodus runtimes (#85).
+
+An adapter over `std:subprocess`, not a container runtime: it builds an argv,
+hands it to an injected runner, and shapes the result into what
+`subprocess.run` already returns.
+
+Read `docs/ecosystem/NODUS_CONTAINER.md` before extending it -- particularly the
+capability decision, which is the reason this package declares no capability of
+its own.
+"""
+
+from .models import SUPPORTED_ENGINES, ContainerResult, ContainerSpec, Mount
+from .runner import ContainerSpecError, build_argv, run
+
+__all__ = [
+    "SUPPORTED_ENGINES",
+    "ContainerResult",
+    "ContainerSpec",
+    "ContainerSpecError",
+    "Mount",
+    "build_argv",
+    "run",
+]

nodus_container-0.1.0/src/nodus_container/models.py

@@ -0,0 +1,69 @@
+"""Value types for a container invocation (#85).
+
+Pure data. Nothing here reaches an engine, imports a subprocess module, or knows
+what a Nodus runtime is -- which is what lets `build_argv` be tested without
+Docker installed, and lets a `CapabilityPolicy` inspect the argv a call *would*
+make rather than pattern-matching a shell string.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+#: Engines whose CLI takes the argv shape this builds. Named once; `build_argv`
+#: validates against it rather than accepting any string, so a typo is refused
+#: where it is written instead of surfacing as "docker: command not found".
+SUPPORTED_ENGINES = frozenset({"docker", "podman"})
+
+
+@dataclass(frozen=True)
+class Mount:
+    """A host path made visible inside the container.
+
+    `read_only` defaults to **True**, and that default is the one opinion this
+    package holds. A writable bind mount is the mechanism behind
+    `docker run -v /:/host` -- the escape from `allowed_paths` that
+    `SECURITY_POSTURE.md §5` describes -- so it is the thing a reader should have
+    to type rather than the thing they get by forgetting.
+    """
+
+    source: str
+    target: str
+    read_only: bool = True
+
+    def as_argument(self) -> str:
+        suffix = "ro" if self.read_only else "rw"
+        return f"{self.source}:{self.target}:{suffix}"
+
+
+@dataclass(frozen=True)
+class ContainerSpec:
+    """What to run, as data."""
+
+    image: str
+    command: tuple[str, ...] = ()
+    engine: str = "docker"
+    env: dict[str, str] = field(default_factory=dict)
+    mounts: tuple[Mount, ...] = ()
+    workdir: str | None = None
+    network: str | None = None
+    remove: bool = True
+
+
+@dataclass(frozen=True)
+class ContainerResult:
+    """The same shape `subprocess.run` returns, plus the argv that produced it.
+
+    Nothing new to learn for a reader who has used `std:subprocess`, and keeping
+    the argv means a refusal or a surprise can be read back afterwards -- which
+    matters most when the refusal came from a capability policy inspecting it.
+    """
+
+    exit_code: int
+    stdout: str = ""
+    stderr: str = ""
+    argv: tuple[str, ...] = ()
+
+    @property
+    def ok(self) -> bool:
+        return self.exit_code == 0

nodus_container-0.1.0/src/nodus_container/runner.py

@@ -0,0 +1,95 @@
+"""Turning a `ContainerSpec` into an argv, and running it through someone else's runner (#85).
+
+**`build_argv` is pure and `run` takes an injected runner**, and the split is the
+design rather than a convenience. Three things follow from it:
+
+- The argv can be tested without a container engine present.
+- A `CapabilityPolicy` can inspect the argv a call *would* make -- refusing
+  `--privileged`, or a writable mount of `/` -- instead of pattern-matching a
+  shell string. Argument-level restriction is a policy question, not a capability
+  one, and this is what makes it answerable.
+- Nothing here imports a subprocess module, so the package declares no capability
+  of its own. The Nodus side passes `std:subprocess.run` in, and **that** call is
+  what `allow_subprocess` and `allowed_commands` gate.
+
+On why there is no `container` capability: one would be unenforceable. Anything
+holding `subprocess` can already run `docker` directly, so a capability beside it
+would be bypassed by the capability the caller already has -- a control an
+operator believes they have and does not. `docs/ecosystem/NODUS_CONTAINER.md`
+carries the full argument and the measurements behind it.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+
+from .models import SUPPORTED_ENGINES, ContainerResult, ContainerSpec
+
+
+class ContainerSpecError(ValueError):
+    """A spec that cannot become an argv. Raised where it is written."""
+
+
+def build_argv(spec: ContainerSpec) -> list[str]:
+    """The argv *spec* becomes. Pure -- nothing is executed.
+
+    Deterministic, including environment ordering: an argv that varies run to run
+    cannot be compared in a test, diffed in a trace, or matched by a policy.
+    """
+    if spec.engine not in SUPPORTED_ENGINES:
+        raise ContainerSpecError(
+            f"unknown engine {spec.engine!r}; expected one of "
+            f"{', '.join(sorted(SUPPORTED_ENGINES))}"
+        )
+    if not spec.image or not spec.image.strip():
+        raise ContainerSpecError("a container spec needs an image")
+
+    argv: list[str] = [spec.engine, "run"]
+    if spec.remove:
+        argv.append("--rm")
+    for key in sorted(spec.env):
+        argv += ["-e", f"{key}={spec.env[key]}"]
+    for mount in spec.mounts:
+        if not mount.source or not mount.target:
+            raise ContainerSpecError(
+                f"a mount needs both a source and a target, got "
+                f"{mount.source!r} -> {mount.target!r}"
+            )
+        argv += ["-v", mount.as_argument()]
+    if spec.workdir:
+        argv += ["-w", spec.workdir]
+    if spec.network:
+        argv += ["--network", spec.network]
+    argv.append(spec.image)
+    argv.extend(spec.command)
+    return argv
+
+
+def run(spec: ContainerSpec, *, runner: Callable[[list[str]], object]) -> ContainerResult:
+    """Build the argv and hand it to *runner*.
+
+    `runner` is anything taking `list[str]` and returning a mapping or object with
+    `exit_code` / `stdout` / `stderr` -- which is exactly what
+    `std:subprocess.run` gives back. Injected rather than imported so this package
+    stays free of an execution dependency, and so a test can supply a fake.
+    """
+    argv = build_argv(spec)
+    raw = runner(argv)
+    return ContainerResult(
+        exit_code=int(_field(raw, "exit_code", 0)),
+        stdout=str(_field(raw, "stdout", "")),
+        stderr=str(_field(raw, "stderr", "")),
+        argv=tuple(argv),
+    )
+
+
+def _field(raw: object, name: str, default: object) -> object:
+    """Read *name* off a mapping or an object.
+
+    Both shapes are accepted because both are what callers have: a Nodus record
+    marshals to a mapping, and a Python caller is likelier to hand over an object.
+    Refusing one of them would make the runner injectable in theory only.
+    """
+    if isinstance(raw, Mapping):
+        return raw.get(name, default)
+    return getattr(raw, name, default)

nodus_container-0.1.0/src/nodus_container.egg-info/PKG-INFO

@@ -0,0 +1,100 @@
+Metadata-Version: 2.4
+Name: nodus-container
+Version: 0.1.0
+Summary: Container execution primitives for Nodus runtimes (Docker, Podman)
+Author: Shawn Knight
+License: MIT
+Project-URL: Homepage, https://github.com/Masterplanner25/Nodus/tree/main/packages/nodus-container
+Project-URL: Repository, https://github.com/Masterplanner25/Nodus
+Project-URL: Issues, https://github.com/Masterplanner25/Nodus/issues
+Keywords: nodus,container,docker,podman,workflow,orchestration
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Provides-Extra: test
+Requires-Dist: pytest>=9.0; extra == "test"
+
+# nodus-container
+
+Container execution for Nodus workflows — launch a container, capture its result,
+without dropping back to bash.
+
+```python
+from nodus_container import ContainerSpec, Mount, build_argv, run
+
+spec = ContainerSpec(
+    image="alpine:3",
+    command=("echo", "hello"),
+    mounts=(Mount(source="/data", target="/data"),),   # read-only by default
+)
+build_argv(spec)
+# ['docker', 'run', '--rm', '-v', '/data:/data:ro', 'alpine:3', 'echo', 'hello']
+```
+
+`run(spec, runner=...)` executes it through a runner you supply — from Nodus,
+that is `std:subprocess.run`. This package never imports a subprocess module.
+
+## Security: read this before granting it
+
+This is an adapter over `subprocess`, and it declares **no capability of its
+own**. A `container` capability would be unenforceable: anything holding
+`subprocess` can already run `docker` directly, so a control beside it would be
+bypassed by the permission the caller already has.
+
+**The enforceable boundary is `allowed_commands`:**
+
+```python
+NodusRuntime(allow_subprocess=True, allowed_commands=["docker"])
+```
+
+Withhold `docker` from that list and container execution is refused. Setting any
+allowlist also refuses `subprocess.shell`, so `sh -c "docker …"` cannot step
+around it.
+
+**What is still not bounded:** `-v /:/host` escapes `allowed_paths`, and
+`--privileged` exists. That is not a gap this package opens —
+[SECURITY_POSTURE.md §5](https://github.com/Masterplanner25/Nodus/blob/main/docs/governance/SECURITY_POSTURE.md)
+already records that a permitted subprocess's binary and arguments are
+unrestricted — but this package makes it a one-liner, which is worth knowing
+before you grant it. Mounts are read-only by default for that reason.
+
+To restrict *arguments*, use a `CapabilityPolicy`: it receives the call's
+arguments, and `build_argv` is pure so the argv a call would make can be
+inspected before it runs.
+
+### Under `nodus serve`, check which nodus-lang you are on
+
+The server's treatment of submitted code changed in
+[#754](https://github.com/Masterplanner25/Nodus/issues/754), and the two
+behaviours are opposites:
+
+- **Through nodus-lang 5.9.0**, code sent to `POST /execute` ran with subprocess,
+  network and environment access permitted, and **no flag could restrict it**. If
+  you are on one of those releases, anything that can reach the port can run
+  `docker` — put the server behind something that authenticates, and treat this
+  package's presence as incidental to that.
+- **After #754 ships**, submitted code is denied those by default and the
+  operator grants them:
+
+  ```bash
+  nodus serve --auth-token "$TOKEN" --allow-subprocess --allowed-commands docker
+  ```
+
+The allowlist is the part worth typing. `--allow-subprocess` alone permits every
+executable on the host.
+
+## Status
+
+Published from the [nodus-lang repository](https://github.com/Masterplanner25/Nodus/tree/main/packages/nodus-container),
+where it is developed alongside the runtime rather than in a repository of its own.
+
+Design and the capability argument in full:
+[NODUS_CONTAINER.md](https://github.com/Masterplanner25/Nodus/blob/main/docs/ecosystem/NODUS_CONTAINER.md).
+Issue: [#85](https://github.com/Masterplanner25/Nodus/issues/85).

nodus_container-0.1.0/src/nodus_container.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+README.md
+pyproject.toml
+src/nodus_container/__init__.py
+src/nodus_container/models.py
+src/nodus_container/runner.py
+src/nodus_container.egg-info/PKG-INFO
+src/nodus_container.egg-info/SOURCES.txt
+src/nodus_container.egg-info/dependency_links.txt
+src/nodus_container.egg-info/requires.txt
+src/nodus_container.egg-info/top_level.txt
+tests/test_nodus_container.py

nodus_container-0.1.0/src/nodus_container.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

nodus_container-0.1.0/src/nodus_container.egg-info/requires.txt

@@ -0,0 +1,3 @@
+
+[test]
+pytest>=9.0

nodus_container-0.1.0/src/nodus_container.egg-info/top_level.txt

@@ -0,0 +1 @@
+nodus_container

nodus_container-0.1.0/tests/test_nodus_container.py

@@ -0,0 +1,145 @@
+"""`nodus-container` scaffold tests (#85).
+
+No test requires a container engine, which is the point of splitting `build_argv`
+from `run`: the argv is a pure function of the spec, and execution is somebody
+else's callable. A live-engine test belongs in this package's own CI, marked and
+skipped when `docker` is absent.
+"""
+
+import pytest
+
+from nodus_container import (
+    ContainerResult,
+    ContainerSpec,
+    ContainerSpecError,
+    Mount,
+    build_argv,
+    run,
+)
+
+
+class TestBuildArgv:
+    def test_the_minimal_spec(self):
+        assert build_argv(ContainerSpec(image="alpine:3")) == [
+            "docker", "run", "--rm", "alpine:3",
+        ]
+
+    def test_the_command_goes_after_the_image(self):
+        """Argv order is not cosmetic: anything after the image is the
+        container's argv, and anything before it is the engine's."""
+        argv = build_argv(ContainerSpec(image="alpine:3", command=("echo", "hi")))
+        assert argv[argv.index("alpine:3") + 1:] == ["echo", "hi"]
+
+    def test_environment_is_sorted(self):
+        """Deterministic, so an argv can be compared in a test, diffed in a trace,
+        and matched by a policy. Insertion order would make all three unreliable."""
+        argv = build_argv(
+            ContainerSpec(image="i", env={"B": "2", "A": "1", "C": "3"})
+        )
+        assert argv[argv.index("-e"):][:6] == ["-e", "A=1", "-e", "B=2", "-e", "C=3"]
+
+    def test_mounts_are_read_only_unless_asked(self):
+        """The one opinion this package holds -- a writable bind mount is the
+        mechanism behind `-v /:/host`, so it has to be typed."""
+        spec = ContainerSpec(image="i", mounts=(Mount(source="/a", target="/b"),))
+        assert "-v" in build_argv(spec)
+        assert "/a:/b:ro" in build_argv(spec)
+
+        writable = ContainerSpec(
+            image="i", mounts=(Mount(source="/a", target="/b", read_only=False),)
+        )
+        assert "/a:/b:rw" in build_argv(writable)
+
+    def test_optional_flags_appear_only_when_set(self):
+        bare = build_argv(ContainerSpec(image="i"))
+        assert "-w" not in bare and "--network" not in bare
+
+        full = build_argv(ContainerSpec(image="i", workdir="/src", network="none"))
+        assert full[full.index("-w") + 1] == "/src"
+        assert full[full.index("--network") + 1] == "none"
+
+    def test_remove_can_be_turned_off(self):
+        assert "--rm" not in build_argv(ContainerSpec(image="i", remove=False))
+
+    def test_podman_takes_the_same_shape(self):
+        assert build_argv(ContainerSpec(image="i", engine="podman"))[0] == "podman"
+
+    @pytest.mark.parametrize(
+        "spec, fragment",
+        [
+            (ContainerSpec(image=""), "needs an image"),
+            (ContainerSpec(image="   "), "needs an image"),
+            (ContainerSpec(image="i", engine="containerd"), "unknown engine"),
+            (
+                ContainerSpec(image="i", mounts=(Mount(source="/a", target=""),)),
+                "needs both a source and a target",
+            ),
+        ],
+    )
+    def test_a_bad_spec_is_refused_where_it_is_written(self, spec, fragment):
+        with pytest.raises(ContainerSpecError) as caught:
+            build_argv(spec)
+        assert fragment in str(caught.value)
+
+
+class TestRun:
+    def test_it_uses_the_injected_runner(self):
+        seen = {}
+
+        def fake(argv):
+            seen["argv"] = argv
+            return {"exit_code": 0, "stdout": "hello\n", "stderr": ""}
+
+        result = run(ContainerSpec(image="alpine:3", command=("echo", "hello")), runner=fake)
+        assert isinstance(result, ContainerResult)
+        assert result.ok and result.stdout == "hello\n"
+        assert seen["argv"][0] == "docker"
+
+    def test_the_argv_is_carried_on_the_result(self):
+        """So a refusal or a surprise can be read back -- which matters most when
+        the refusal came from a policy inspecting the argv."""
+        result = run(ContainerSpec(image="i"), runner=lambda argv: {"exit_code": 0})
+        assert result.argv == ("docker", "run", "--rm", "i")
+
+    def test_a_non_zero_exit_is_reported_not_raised(self):
+        """The same contract `subprocess.run` has: a failing command is a result,
+        not an exception. A spec that cannot become an argv is the exception."""
+        result = run(
+            ContainerSpec(image="i"),
+            runner=lambda argv: {"exit_code": 3, "stderr": "boom"},
+        )
+        assert not result.ok
+        assert result.exit_code == 3 and result.stderr == "boom"
+
+    def test_an_object_runner_works_as_well_as_a_mapping(self):
+        """A Nodus record marshals to a mapping; a Python caller is likelier to
+        return an object. Accepting only one would make the runner injectable in
+        theory only."""
+
+        class Reply:
+            exit_code = 0
+            stdout = "ok"
+            stderr = ""
+
+        assert run(ContainerSpec(image="i"), runner=lambda argv: Reply()).stdout == "ok"
+
+    def test_a_bad_spec_never_reaches_the_runner(self):
+        def explode(argv):  # pragma: no cover - must not be called
+            raise AssertionError("the runner was called with an invalid spec")
+
+        with pytest.raises(ContainerSpecError):
+            run(ContainerSpec(image=""), runner=explode)
+
+
+class TestItDeclaresNoExecutionDependency:
+    def test_nothing_imports_a_subprocess_module(self):
+        """The reason this package declares no capability of its own: it cannot
+        execute anything. If that stops being true, the security argument in
+        `docs/ecosystem/NODUS_CONTAINER.md` stops being true with it."""
+        from pathlib import Path
+
+        package = Path(__file__).resolve().parents[1] / "src" / "nodus_container"
+        for module in sorted(package.glob("*.py")):
+            source = module.read_text(encoding="utf-8")
+            for banned in ("import subprocess", "from subprocess", "os.system", "os.popen"):
+                assert banned not in source, f"{module.name} reaches for {banned}"