engineering-argument-language 3.2.3__py3-none-any.whl

eal/store.py

@@ -0,0 +1,272 @@
+"""SQLite storage for immutable collection, observation and reasoning records."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from contextlib import contextmanager
+import json
+import os
+import secrets
+import sqlite3
+import stat
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+from uuid import uuid4
+
+from filelock import FileLock
+
+
+def _check_private_directory(directory: Path) -> None:
+    details = directory.lstat()
+    if not stat.S_ISDIR(details.st_mode):
+        raise PermissionError("The run-store directory must be a regular directory")
+    if os.name == "posix" and (details.st_uid != os.getuid() or details.st_mode & 0o022):
+        raise PermissionError("The run-store directory must be owned by the process and not writable by others")
+
+
+@contextmanager
+def _store_initialisation_lock(database_path: Path, *, timeout: float = 30) -> Iterator[None]:
+    """Coordinate store setup before SQLite or its private identity is opened.
+
+    Keep the lock file in place after release: unlinking it could let another
+    process acquire a different inode while a contender still holds this one.
+    The private parent excludes replacement by other operating-system users.
+    """
+    _check_private_directory(database_path.parent)
+    path = database_path.with_name(database_path.name + ".initialisation.lock")
+    flags = os.O_RDWR | getattr(os, "O_NOFOLLOW", 0)
+    try:
+        descriptor = os.open(path, flags | os.O_CREAT | os.O_EXCL, 0o600)
+    except FileExistsError:
+        # Check before opening an existing object: opening a FIFO or device
+        # can block or have effects before descriptor validation is possible.
+        details = path.lstat()
+        if not stat.S_ISREG(details.st_mode):
+            raise PermissionError("The run-store initialisation lock must be a private regular 0600 file")
+        descriptor = os.open(path, flags)
+    try:
+        details = os.fstat(descriptor)
+        named = path.lstat()
+        if (not stat.S_ISREG(details.st_mode) or not stat.S_ISREG(named.st_mode)
+                or (details.st_dev, details.st_ino) != (named.st_dev, named.st_ino)
+                or stat.S_IMODE(details.st_mode) != 0o600
+                or (os.name == "posix" and details.st_uid != os.getuid())):
+            raise PermissionError("The run-store initialisation lock must be a private regular 0600 file")
+    finally:
+        os.close(descriptor)
+    with FileLock(path, timeout=timeout, mode=0o600):
+        # FileLock owns a separate descriptor. Check the pathname once more
+        # before touching storage; participating processes retain the file.
+        details = path.lstat()
+        if (not stat.S_ISREG(details.st_mode) or stat.S_IMODE(details.st_mode) != 0o600
+                or (os.name == "posix" and details.st_uid != os.getuid())):
+            raise PermissionError("The run-store initialisation lock must be a private regular 0600 file")
+        yield
+
+
+def utc_now() -> str:
+    return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+
+
+def _private_binding_key(database_path: Path) -> bytes:
+    """Atomically establish a private store-local identity key outside SQLite."""
+    parent = database_path.parent
+    _check_private_directory(parent)
+    key_path = database_path.with_name(database_path.name + ".binding-key")
+    temporary = key_path.with_name(key_path.name + "." + secrets.token_hex(16) + ".tmp")
+    descriptor = os.open(temporary, os.O_WRONLY | os.O_CREAT | os.O_EXCL |
+                         getattr(os, "O_NOFOLLOW", 0), 0o600)
+    try:
+        candidate = secrets.token_bytes(32)
+        with os.fdopen(descriptor, "wb") as stream:
+            stream.write(candidate)
+            stream.flush()
+            os.fsync(stream.fileno())
+        try:
+            os.link(temporary, key_path, follow_symlinks=False)
+        except FileExistsError:
+            pass
+    finally:
+        temporary.unlink(missing_ok=True)
+    descriptor = os.open(key_path, os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0))
+    with os.fdopen(descriptor, "rb") as stream:
+        info = os.fstat(stream.fileno())
+        if not stat.S_ISREG(info.st_mode) or info.st_mode & 0o077:
+            raise PermissionError("The run-store binding key must be a private regular file")
+        if os.name == "posix" and info.st_uid != os.getuid():
+            raise PermissionError("The run-store binding key must be owned by the process")
+        key = stream.read(33)
+    if len(key) != 32:
+        raise ValueError("The run-store binding key must contain exactly 32 bytes")
+    return key
+
+
+def _check_private_sqlite_files(database_path: Path, *, create_database: bool = False) -> None:
+    """Refuse readable or replaceable SQLite files before opening the store."""
+    if create_database:
+        try:
+            descriptor = os.open(
+                database_path, os.O_RDWR | os.O_CREAT | os.O_EXCL |
+                getattr(os, "O_NOFOLLOW", 0), 0o600,
+            )
+        except FileExistsError:
+            pass
+        else:
+            os.close(descriptor)
+    for path in (database_path, database_path.with_name(database_path.name + "-wal"),
+                 database_path.with_name(database_path.name + "-shm")):
+        try:
+            descriptor = os.open(path, os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0))
+        except FileNotFoundError:
+            if path == database_path:
+                raise
+            continue
+        with os.fdopen(descriptor, "rb") as stream:
+            details = os.fstat(stream.fileno())
+        if (not stat.S_ISREG(details.st_mode) or stat.S_IMODE(details.st_mode) != 0o600
+                or (os.name == "posix" and details.st_uid != os.getuid())):
+            raise PermissionError(f"SQLite store file must be a private regular 0600 file: {path.name}")
+
+
+class RunStore:
+    def __init__(self, path: str | Path):
+        self.path = Path(path)
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        with _store_initialisation_lock(self.path):
+            self._binding_key = _private_binding_key(self.path)
+            _check_private_sqlite_files(self.path, create_database=True)
+            self._initialise_schema()
+            _check_private_sqlite_files(self.path)
+
+    def _initialise_schema(self) -> None:
+        """Establish the current schema and backfill its index atomically."""
+        with self._connect() as connection:
+            connection.execute("PRAGMA journal_mode=WAL")
+            connection.execute("BEGIN IMMEDIATE")
+            connection.execute(
+                "CREATE TABLE IF NOT EXISTS records "
+                "(id TEXT PRIMARY KEY, kind TEXT NOT NULL, created_at TEXT NOT NULL, payload TEXT NOT NULL)"
+            )
+            connection.execute("CREATE INDEX IF NOT EXISTS records_kind ON records(kind, created_at)")
+            connection.execute(
+                "CREATE TABLE IF NOT EXISTS observation_index "
+                "(sequence INTEGER PRIMARY KEY, record_id TEXT NOT NULL UNIQUE, "
+                "evidence_id TEXT NOT NULL, environment TEXT NOT NULL, "
+                "request_digest TEXT NOT NULL, tool_binding_digest TEXT NOT NULL)"
+            )
+            connection.execute(
+                "CREATE INDEX IF NOT EXISTS observation_identity ON observation_index "
+                "(evidence_id, environment, request_digest, tool_binding_digest, sequence DESC)"
+            )
+            connection.execute(
+                "CREATE TABLE IF NOT EXISTS store_metadata "
+                "(key TEXT PRIMARY KEY, value TEXT NOT NULL)"
+            )
+            indexed = connection.execute(
+                "SELECT value FROM store_metadata WHERE key = 'observation-index-version'"
+            ).fetchone()
+            if indexed is None:
+                # Existing stores predate the index. Scan once, including failed
+                # attempts which deliberately get no reusable index entry.
+                for record_id, encoded in connection.execute(
+                    "SELECT id, payload FROM records WHERE kind = 'observation' ORDER BY rowid"
+                ):
+                    self._index_observation(connection, record_id, json.loads(encoded))
+                connection.execute(
+                    "INSERT INTO store_metadata(key, value) VALUES ('observation-index-version', '1')"
+                )
+            elif indexed[0] != "1":
+                raise ValueError("Unsupported observation index version")
+
+    @contextmanager
+    def _connect(self) -> Iterator[sqlite3.Connection]:
+        """Commit or roll back one operation and close its owned connection."""
+        _check_private_sqlite_files(self.path)
+        connection = sqlite3.connect(self.path, timeout=30)
+        try:
+            _check_private_sqlite_files(self.path)
+            with connection:
+                yield connection
+        finally:
+            connection.close()
+
+    def put(self, kind: str, payload: dict[str, Any], *, record_id: str | None = None) -> str:
+        record_id = record_id or str(uuid4())
+        encoded = json.dumps(payload, ensure_ascii=False, sort_keys=True, allow_nan=False)
+        with self._connect() as connection:
+            connection.execute(
+                "INSERT INTO records(id, kind, created_at, payload) VALUES (?, ?, ?, ?)",
+                (record_id, kind, utc_now(), encoded),
+            )
+            if kind == "observation":
+                self._index_observation(connection, record_id, payload)
+        return record_id
+
+    @staticmethod
+    def _index_observation(connection: sqlite3.Connection, record_id: str, payload: dict[str, Any]) -> None:
+        if payload.get("status") != "ok":
+            return
+        keys = (payload.get("evidence_id"), payload.get("environment"),
+                payload.get("request_digest"), payload.get("tool_binding_digest"))
+        if any(not isinstance(key, str) or not key for key in keys):
+            return
+        connection.execute(
+            "INSERT INTO observation_index(record_id, evidence_id, environment, request_digest, "
+            "tool_binding_digest) VALUES (?, ?, ?, ?, ?)", (record_id, *keys)
+        )
+
+    def put_batch(self, entries: list[tuple[str, dict[str, Any], str | None]]) -> list[str]:
+        """Commit a collection and its observations as one transaction."""
+        if not entries:
+            raise ValueError("entries must not be empty")
+        ids = [record_id or str(uuid4()) for _, _, record_id in entries]
+        encoded = [json.dumps(payload, ensure_ascii=False, sort_keys=True, allow_nan=False)
+                   for _, payload, _ in entries]
+        with self._connect() as connection:
+            for (kind, payload, _), record_id, value in zip(entries, ids, encoded):
+                connection.execute(
+                    "INSERT INTO records(id, kind, created_at, payload) VALUES (?, ?, ?, ?)",
+                    (record_id, kind, utc_now(), value),
+                )
+                if kind == "observation":
+                    self._index_observation(connection, record_id, payload)
+        return ids
+
+    def find_observations(self, *, evidence_id: str, environment: str,
+                          request_digest: str, tool_binding_digest: str,
+                          limit: int = 100) -> list[dict[str, Any]]:
+        """Return exact-acquisition candidates, newest first, for reuse."""
+        if not 1 <= limit <= 1000:
+            raise ValueError("limit must be between 1 and 1000")
+        with self._connect() as connection:
+            rows = connection.execute(
+                "SELECT records.payload FROM observation_index "
+                "JOIN records ON records.id = observation_index.record_id "
+                "WHERE evidence_id = ? AND environment = ? AND request_digest = ? "
+                "AND tool_binding_digest = ? ORDER BY sequence DESC LIMIT ?",
+                (evidence_id, environment, request_digest, tool_binding_digest, limit),
+            ).fetchall()
+        return [json.loads(row[0]) for row in rows]
+
+    def get(self, record_id: str, *, kind: str | None = None) -> dict[str, Any]:
+        with self._connect() as connection:
+            row = connection.execute("SELECT kind, payload FROM records WHERE id = ?", (record_id,)).fetchone()
+        if row is None or (kind is not None and row[0] != kind):
+            raise KeyError(f"No {kind or 'stored'} record with ID {record_id!r}")
+        return json.loads(row[1])
+
+    def list(self, *, kind: str | None = None, limit: int = 100) -> list[dict[str, str]]:
+        if not 1 <= limit <= 1000:
+            raise ValueError("limit must be between 1 and 1000")
+        with self._connect() as connection:
+            if kind is None:
+                rows = connection.execute(
+                    "SELECT id, kind, created_at FROM records ORDER BY rowid DESC LIMIT ?", (limit,)
+                ).fetchall()
+            else:
+                rows = connection.execute(
+                    "SELECT id, kind, created_at FROM records WHERE kind = ? ORDER BY rowid DESC LIMIT ?",
+                    (kind, limit),
+                ).fetchall()
+        return [dict(zip(("id", "kind", "created_at"), row)) for row in rows]

eal/tool_acquisition.py

@@ -0,0 +1,383 @@
+"""Trusted tool bindings and bounded observation acquisition adapters.
+
+The operator registry selects an adapter. EAL source supplies JSON input and
+cannot choose executable paths or file locations. These adapters are not a
+process sandbox.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import hashlib
+import hmac
+import math
+import json
+import os
+import re
+import selectors
+import stat
+import subprocess
+import time
+import tomllib
+from pathlib import Path
+from typing import Any, Mapping
+
+from .command_process import supervised_command
+
+MAX_JSON_DEPTH = 128
+MAX_REQUEST_BYTES = 1024 * 1024
+
+
+def keyed_digest(secret: bytes, domain: bytes, value: Any) -> str:
+    """Public configuration identity without an offline low-entropy value oracle."""
+    from .evaluator import canonical_digest
+
+    if not isinstance(secret, bytes) or len(secret) != 32:
+        raise ValueError("A private 32-byte store key is required")
+    if not isinstance(domain, bytes) or not domain:
+        raise ValueError("A domain separator is required")
+    # Frozen acquisition hash domain, independent of the authored source version.
+    # Retain these bytes so EAL/3 can reuse compatible observation-record/1 data.
+    return hmac.new(secret, b"EAL/2\0" + domain + b"\0" +
+                    bytes.fromhex(canonical_digest(value)), hashlib.sha256).hexdigest()
+
+
+def strict_json(text: str) -> Any:
+    def pairs(items):
+        result = {}
+        for key, value in items:
+            if key in result:
+                raise ValueError(f"Duplicate JSON key {key!r}")
+            result[key] = value
+        return result
+
+    def invalid_constant(value):
+        raise ValueError(f"Non-finite JSON value {value}")
+
+    def finite_float(value):
+        parsed = float(value)
+        if not math.isfinite(parsed):
+            raise ValueError(f"Non-finite JSON value {value}")
+        return parsed
+
+    try:
+        value = json.loads(text, object_pairs_hook=pairs, parse_constant=invalid_constant, parse_float=finite_float)
+        pending = [(value, 0)]
+        while pending:
+            item, depth = pending.pop()
+            if isinstance(item, (dict, list)):
+                if depth >= MAX_JSON_DEPTH:
+                    raise ValueError(f"JSON nesting exceeds {MAX_JSON_DEPTH} container levels")
+                children = item.values() if isinstance(item, dict) else item
+                pending.extend((child, depth + 1) for child in children)
+        # JSON escapes can encode lone UTF-16 surrogates which cannot be stored
+        # or hashed as UTF-8. Reject these before adding values to run records.
+        json.dumps(value, ensure_ascii=False, allow_nan=False).encode("utf-8")
+    except UnicodeError as exc:
+        raise ValueError("JSON strings must contain valid Unicode scalar values") from exc
+    except RecursionError as exc:
+        raise ValueError("JSON nesting exceeds decoder resources") from exc
+    return value
+
+
+def bounded_path(workspace: Path, name: str) -> Path:
+    """Resolve symlinks and refuse traversal outside the configured workspace."""
+    path = (workspace / name).resolve()
+    if not path.is_relative_to(workspace.resolve()):
+        raise ValueError(f"Path is outside the workspace: {name}")
+    return path
+
+
+@dataclasses.dataclass(frozen=True)
+class ToolBinding:
+    name: str
+    kind: str
+    version: str
+    argv: tuple[str, ...] = ()
+    path: str | None = None
+    timeout_seconds: float = 30.0
+    max_output_bytes: int = 1024 * 1024
+    env: Mapping[str, str] = dataclasses.field(default_factory=dict, repr=False)
+    pinned_files: tuple[tuple[str, str], ...] = ()
+    # The operator asserts this collector is read-only and independent of
+    # other simultaneous acquisitions. Arbitrary commands default to serial.
+    parallel_safe: bool = False
+    # None preserves full host inheritance; an explicit list passes only the
+    # named variables that exist, plus the operator's configured env overlay.
+    inherit_env: tuple[str, ...] | None = None
+
+    def effective_environment(self) -> dict[str, str]:
+        if self.inherit_env is None:
+            current = dict(os.environ)
+        else:
+            current = {name: os.environ[name] for name in self.inherit_env if name in os.environ}
+        current.update(self.env)
+        return current
+
+    def process_environment_digest(self, secret: bytes, *,
+                                   effective_env: Mapping[str, str] | None = None) -> str | None:
+        """Identity of the effective command environment without exposing secrets."""
+        if self.kind != "command":
+            return None
+        current = self.effective_environment() if effective_env is None else dict(effective_env)
+        return keyed_digest(secret, b"process-environment", current)
+
+    def binding_digest(self, secret: bytes, *, workspace: Path | None = None) -> str:
+        """Keyed registry identity, checking each operator-pinned file's bytes."""
+        if self.pinned_files and workspace is None:
+            raise ValueError("Pinned collector files require a workspace")
+        for name, expected in self.pinned_files:
+            path = Path(name)
+            path = path.resolve() if path.is_absolute() else bounded_path(workspace, name)
+            try:
+                descriptor = os.open(path, os.O_RDONLY | os.O_NONBLOCK)
+                with os.fdopen(descriptor, "rb") as stream:
+                    details = os.fstat(stream.fileno())
+                    if not stat.S_ISREG(details.st_mode) or details.st_size > 16 * 1024 * 1024:
+                        raise ValueError("Pinned collector file must be a regular file at most 16 MiB")
+                    digest = hashlib.sha256(stream.read(16 * 1024 * 1024 + 1)).hexdigest()
+            except OSError as exc:
+                raise ValueError("Pinned collector file is inaccessible") from exc
+            if digest != expected:
+                raise ValueError("Pinned collector file identity differs from operator configuration")
+        identity = {
+            "name": self.name, "kind": self.kind,
+            "version": self.version, "argv": list(self.argv),
+            "path": self.path, "timeout_seconds": self.timeout_seconds,
+            "max_output_bytes": self.max_output_bytes,
+            "env": dict(self.env), "pinned_files": [{"path": path, "sha256": digest}
+                                                     for path, digest in self.pinned_files]}
+        # Scheduling is a host choice, not a property of a measurement.
+        if self.inherit_env is not None:
+            identity["inherit_env"] = sorted(self.inherit_env)
+        return keyed_digest(secret, b"tool-binding", identity)
+
+
+@dataclasses.dataclass(frozen=True)
+class AcquisitionResult:
+    stdout: bytes = b""
+    stderr: bytes = b""
+    metadata: Mapping[str, Any] = dataclasses.field(default_factory=dict)
+    error: Exception | None = None
+
+
+class ToolRegistry:
+    def __init__(self, bindings: Mapping[str, ToolBinding] | None = None):
+        self.bindings = dict(bindings or {})
+
+    @classmethod
+    def load(cls, path: str | Path) -> "ToolRegistry":
+        with Path(path).open("rb") as stream:
+            document = tomllib.load(stream)
+        if set(document) - {"tools"} or not isinstance(document.get("tools", {}), dict):
+            raise ValueError("The registry must contain only a [tools] table")
+        bindings = {}
+        allowed = {"kind", "version", "argv", "path", "timeout_seconds", "max_output_bytes", "env", "pinned_files", "parallel_safe", "inherit_env"}
+        for name, raw in document.get("tools", {}).items():
+            if not isinstance(raw, dict) or set(raw) - allowed:
+                raise ValueError(f"Unknown registry settings for {name}")
+            if raw.get("kind") not in _ADAPTERS:
+                raise ValueError(f"{name}: kind must be command or json_file")
+            if not isinstance(raw.get("version"), str) or not raw["version"]:
+                raise ValueError(f"{name}: a nonempty version is required")
+            argv = raw.get("argv", [])
+            if not isinstance(argv, list) or not all(isinstance(arg, str) and arg for arg in argv):
+                raise ValueError(f"{name}: argv must contain nonempty strings")
+            if raw["kind"] == "command" and (not argv or "path" in raw):
+                raise ValueError(f"{name}: command requires argv and does not use path")
+            if raw["kind"] == "json_file" and (not isinstance(raw.get("path"), str) or not raw["path"] or argv):
+                raise ValueError(f"{name}: json_file requires a path and does not use argv")
+            timeout = raw.get("timeout_seconds", 30.0)
+            if isinstance(timeout, bool) or not isinstance(timeout, (int, float)) or not math.isfinite(timeout) or not 0 < timeout <= 3600:
+                raise ValueError(f"{name}: timeout_seconds must be finite, positive and at most 3600")
+            limit = raw.get("max_output_bytes", 1024 * 1024)
+            if isinstance(limit, bool) or not isinstance(limit, int) or not 1 <= limit <= 16 * 1024 * 1024:
+                raise ValueError(f"{name}: max_output_bytes must be an integer from 1 through 16777216")
+            env = raw.get("env", {})
+            if not isinstance(env, dict) or not all(isinstance(k, str) and isinstance(v, str) for k, v in env.items()):
+                raise ValueError(f"{name}: env must map strings to strings")
+            parallel_safe = raw.get("parallel_safe", False)
+            if type(parallel_safe) is not bool:
+                raise ValueError(f"{name}: parallel_safe must be a boolean")
+            inherited = raw.get("inherit_env")
+            if inherited is not None:
+                if (raw["kind"] != "command" or not isinstance(inherited, list)
+                        or len(inherited) > 64 or any(
+                            not isinstance(item, str)
+                            or re.fullmatch(r"[A-Za-z_][A-Za-z_0-9]*", item, re.ASCII) is None
+                            for item in inherited)
+                        or len(set(inherited)) != len(inherited)):
+                    raise ValueError(f"{name}: inherit_env requires up to 64 distinct command environment variable names")
+            pinned = raw.get("pinned_files", [])
+            if (not isinstance(pinned, list) or len(pinned) > 32
+                    or any(not isinstance(item, dict) or set(item) != {"path", "sha256"}
+                           or not isinstance(item["path"], str) or not item["path"]
+                           or not isinstance(item["sha256"], str)
+                           or re.fullmatch(r"[0-9a-f]{64}", item["sha256"]) is None for item in pinned)
+                    or len({item["path"] for item in pinned}) != len(pinned)):
+                raise ValueError(f"{name}: pinned_files requires distinct paths and lowercase SHA-256 digests")
+            if raw["kind"] != "command" and pinned:
+                raise ValueError(f"{name}: only command bindings can pin executable files")
+            bindings[name] = ToolBinding(
+                name, raw["kind"], raw["version"], tuple(argv), raw.get("path"), float(timeout), limit, env,
+                tuple((item["path"], item["sha256"]) for item in pinned), parallel_safe,
+                None if inherited is None else tuple(inherited)
+            )
+        return cls(bindings)
+
+    def binding_for(self, name: str, *, version: str) -> ToolBinding:
+        binding = self.bindings.get(name)
+        if binding is None:
+            raise ValueError(f"Tool {name!r} is not in the operator registry")
+        if binding.version != version:
+            raise ValueError("Declared tool version differs from the operator registry")
+        return binding
+
+    def acquire(self, binding: ToolBinding, request: dict, workspace: Path,
+                *, secret: bytes) -> AcquisitionResult:
+        """Choose the trusted adapter selected by the operator's tool binding."""
+        adapter = _ADAPTERS.get(binding.kind)
+        if adapter is None:
+            raise ValueError(f"Unsupported operator tool kind {binding.kind!r}")
+        return adapter(binding, request, workspace, secret)
+
+
+def _request_stop(process: subprocess.Popen) -> None:
+    try:
+        # The supervisor stops the collector group before releasing its lease.
+        process.terminate()
+    except ProcessLookupError:
+        pass
+
+
+def _execute(binding: ToolBinding, request: dict, workspace: Path, secret: bytes) -> tuple[bytes, bytes, int, dict]:
+    """Read bounded stdout/stderr without retaining unbounded subprocess output."""
+    encoded_request = json.dumps(request, sort_keys=True, allow_nan=False).encode("utf-8") + b"\n"
+    if len(encoded_request) > MAX_REQUEST_BYTES:
+        raise ValueError(f"Tool request exceeds {MAX_REQUEST_BYTES} bytes")
+    effective_env = binding.effective_environment()
+    # Arguments may themselves contain credentials. The keyed binding digest
+    # identifies the configured command without copying argv into a record.
+    metadata = {"process_environment_digest": binding.process_environment_digest(
+        secret, effective_env=effective_env)}
+    if os.name != "posix":
+        raise RuntimeError("The bounded command adapter currently requires a POSIX host")
+    with supervised_command(binding.argv, workspace=workspace, environ=effective_env,
+                            timeout=binding.timeout_seconds) as command:
+        process = command.process
+        stdout, stderr = bytearray(), bytearray()
+        deadline = time.monotonic() + binding.timeout_seconds
+        failure = None
+        # Nonblocking stdin matters: an adapter may never consume a large request.
+        try:
+            with selectors.DefaultSelector() as selector:
+                for stream, label in ((process.stdout, "stdout"), (process.stderr, "stderr"), (process.stdin, "stdin")):
+                    os.set_blocking(stream.fileno(), False)
+                    selector.register(stream, selectors.EVENT_WRITE if label == "stdin" else selectors.EVENT_READ, label)
+                remaining_input = memoryview(encoded_request)
+                while selector.get_map():
+                    if time.monotonic() >= deadline:
+                        failure = "timeout"
+                        break
+                    events = selector.select(min(0.1, max(0, deadline - time.monotonic())))
+                    for key, _ in events:
+                        if key.data == "stdin":
+                            try:
+                                written = os.write(key.fd, remaining_input[:65536])
+                                remaining_input = remaining_input[written:]
+                            except BrokenPipeError:
+                                remaining_input = remaining_input[:0]
+                            if not remaining_input:
+                                selector.unregister(key.fileobj)
+                                key.fileobj.close()
+                            continue
+                        chunk = os.read(key.fd, 65536)
+                        if not chunk:
+                            selector.unregister(key.fileobj)
+                            key.fileobj.close()
+                            continue
+                        target = stdout if key.data == "stdout" else stderr
+                        remaining = binding.max_output_bytes - len(stdout) - len(stderr)
+                        target.extend(chunk[:max(0, remaining)])
+                        if len(chunk) > remaining:
+                            failure = "output_limit"
+                            break
+                    if failure:
+                        break
+            if failure:
+                _request_stop(process)
+            try:
+                returncode = process.wait(timeout=max(0.01, deadline - time.monotonic()))
+            except subprocess.TimeoutExpired:
+                failure = failure or "timeout"
+                _request_stop(process)
+                returncode = process.wait(timeout=5)
+        except BaseException:
+            _request_stop(process)
+            process.wait(timeout=5)
+            raise
+        finally:
+            for stream in (process.stdin, process.stdout, process.stderr):
+                if stream and not stream.closed:
+                    stream.close()
+        status = command.collector_status()
+        returncode = status.returncode
+        if status.timed_out and failure is None:
+            failure = "timeout"
+    metadata.update({"returncode": returncode, "output_truncated": failure == "output_limit"})
+    if failure:
+        metadata["execution_error"] = failure
+    return bytes(stdout), bytes(stderr), returncode, metadata
+
+
+def _acquire_command(binding: ToolBinding, request: dict, workspace: Path, secret: bytes) -> AcquisitionResult:
+    stdout, stderr, returncode, metadata = _execute(binding, request, workspace, secret)
+    if metadata.get("execution_error"):
+        error = ValueError(metadata["execution_error"])
+    elif returncode != 0:
+        error = ValueError(f"Tool exited with status {returncode}")
+    else:
+        error = None
+    return AcquisitionResult(stdout, stderr, metadata, error)
+
+
+def _acquire_json_file(binding: ToolBinding, request: dict, workspace: Path, secret: bytes) -> AcquisitionResult:
+    path = bounded_path(workspace, binding.path)
+    metadata = {"file": str(path.relative_to(workspace))}
+    # A FIFO or device can block indefinitely before a bounded read begins.
+    # File imports only accept regular files.
+    try:
+        descriptor = os.open(path, os.O_RDONLY | os.O_NONBLOCK)
+        with os.fdopen(descriptor, "rb") as stream:
+            if not stat.S_ISREG(os.fstat(stream.fileno()).st_mode):
+                raise ValueError("File observations require a regular file")
+            stdout = stream.read(binding.max_output_bytes + 1)
+    except (OSError, ValueError) as exc:
+        return AcquisitionResult(metadata=metadata, error=exc)
+    if len(stdout) > binding.max_output_bytes:
+        metadata["output_truncated"] = True
+        return AcquisitionResult(stdout[:binding.max_output_bytes], metadata=metadata,
+                                 error=ValueError("output_limit"))
+    return AcquisitionResult(stdout, metadata=metadata)
+
+
+_ADAPTERS = {"command": _acquire_command, "json_file": _acquire_json_file}
+
+
+def validate_envelope(stdout: bytes, *, file_import: bool, context: dict,
+                      acquisition: dict) -> dict:
+    """Check observation shape and the declared acquisition identity."""
+    from .evaluator import canonical_digest
+
+    envelope = strict_json(stdout.decode("utf-8"))
+    if not isinstance(envelope, dict) or "value" not in envelope or set(envelope) - {"value", "observed_at", "context", "request", "details"}:
+        raise ValueError("Tool output must be an object with value and optional observed_at, context, request, details")
+    if file_import and not {"observed_at", "context", "request"} <= set(envelope):
+        raise ValueError("File observations require observed_at and context and request; import must preserve age, scope and acquisition identity")
+    if "request" in envelope:
+        if not isinstance(envelope["request"], dict) or canonical_digest(envelope["request"]) != canonical_digest(acquisition):
+            raise ValueError("Observation request differs from the declared acquisition request")
+    if "context" in envelope:
+        if not isinstance(envelope["context"], dict) or canonical_digest(envelope["context"]) != canonical_digest(context):
+            raise ValueError("Observation context differs from the requested context")
+    return envelope