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

eal/collection_identity.py

@@ -0,0 +1,28 @@
+"""Identity checks shared by ordinary and formal assessment of stored collections."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+from .evaluator import canonical_digest
+
+
+class CollectionIdentityValidator:
+    """Reject a collection whose source or context differs from the assessment."""
+
+    def validate(self, collection: Mapping[str, Any], *, source_digest: str,
+                 context: Mapping[str, Any]) -> dict[str, dict]:
+        if not isinstance(collection, Mapping):
+            raise ValueError("Stored collection must be a JSON object")
+        if collection.get("source_digest") != source_digest:
+            raise ValueError("Collection differs from the assessment source")
+        if canonical_digest(collection.get("context")) != canonical_digest(context):
+            raise ValueError("Collection differs from the assessment context")
+        records = collection.get("records")
+        if not isinstance(records, dict) or any(
+            not isinstance(name, str) or not isinstance(record, dict)
+            for name, record in records.items()
+        ):
+            raise ValueError("Collection records must map evidence IDs to observations")
+        return records

eal/collection_scheduler.py

@@ -0,0 +1,72 @@
+"""Bounded collection scheduling under operator-declared independence.
+
+An arbitrary collector can change remote state or depend on another collector.
+Only consecutive acquisitions explicitly approved for parallel execution may
+overlap. Serial acquisitions form barriers in the requested order.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from concurrent.futures import FIRST_COMPLETED, ThreadPoolExecutor, wait
+from contextvars import copy_context
+from typing import TypeVar
+
+
+T = TypeVar("T")
+
+
+class CollectionScheduler:
+    """Run independent collections concurrently with a fixed in-flight bound."""
+
+    def __init__(self, max_workers: int = 4):
+        if type(max_workers) is not int or not 1 <= max_workers <= 32:
+            raise ValueError("max_workers must be an integer from 1 through 32")
+        self.max_workers = max_workers
+
+    def run(self, evidence_names: Sequence[str], is_parallel_safe: Callable[[str], bool],
+            collect_one: Callable[[str], T]) -> dict[str, T]:
+        """Collect each requested ID once and return results in request order.
+
+        The classifier is supplied by the trusted host after resolving the
+        current operator binding. It must return false on resolution errors so
+        ``collect_one`` can retain the established failed-observation record.
+        """
+        names = tuple(evidence_names)
+        if len(set(names)) != len(names):
+            raise ValueError("Evidence identifiers must be unique")
+        results: dict[str, T] = {}
+        independent: list[str] = []
+
+        def flush() -> None:
+            if not independent:
+                return
+            if len(independent) == 1 or self.max_workers == 1:
+                for name in independent:
+                    results[name] = collect_one(name)
+            else:
+                # Keep a fixed number of calls in flight. Refill each freed
+                # slot without waiting for a slower call in the same group.
+                with ThreadPoolExecutor(max_workers=min(self.max_workers, len(independent))) as executor:
+                    remaining = iter(independent)
+                    in_flight = {}
+                    for _ in range(min(self.max_workers, len(independent))):
+                        name = next(remaining)
+                        in_flight[executor.submit(copy_context().run, collect_one, name)] = name
+                    while in_flight:
+                        finished, _ = wait(in_flight, return_when=FIRST_COMPLETED)
+                        for future in finished:
+                            results[in_flight.pop(future)] = future.result()
+                            name = next(remaining, None)
+                            if name is not None:
+                                in_flight[executor.submit(copy_context().run, collect_one, name)] = name
+            independent.clear()
+
+        for name in names:
+            if is_parallel_safe(name):
+                independent.append(name)
+            else:
+                flush()
+                results[name] = collect_one(name)
+        flush()
+        return {name: results[name] for name in names}

eal/command_process.py

@@ -0,0 +1,118 @@
+"""Launch and cancel a collector supervisor through an owned pipe."""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from collections.abc import Iterator, Mapping, Sequence
+from dataclasses import dataclass, field
+import json
+import os
+from pathlib import Path
+import subprocess
+import sys
+
+from .acquisition_coordination import inherited_acquisition_descriptor
+from .command_supervisor import MAX_CONFIG_BYTES
+
+
+@dataclass(frozen=True)
+class CollectorStatus:
+    """Report the collector's exit independently of supervisor termination."""
+
+    returncode: int
+    timed_out: bool
+
+
+@dataclass
+class SupervisedCommand:
+    """Expose collector status separately from the supervising process status."""
+
+    process: subprocess.Popen[bytes]
+    status_descriptor: int
+    _status: CollectorStatus | None = field(default=None, init=False, repr=False)
+
+    def collector_status(self) -> CollectorStatus:
+        if self._status is not None:
+            return self._status
+        if self.process.returncode is None:
+            raise RuntimeError("The command supervisor has not exited")
+        encoded = os.read(self.status_descriptor, 128)
+        if not encoded:
+            if self.process.returncode != 0:
+                self._status = CollectorStatus(self.process.returncode, False)
+                return self._status
+            raise RuntimeError("The command supervisor returned no collector status")
+        try:
+            result = json.loads(encoded)
+        except ValueError:
+            raise RuntimeError("Invalid collector status from command supervisor") from None
+        if (not isinstance(result, dict) or set(result) != {"returncode", "timed_out"}
+                or type(result["returncode"]) is not int
+                or not -127 <= result["returncode"] <= 255
+                or type(result["timed_out"]) is not bool):
+            raise RuntimeError("Invalid collector status from command supervisor")
+        self._status = CollectorStatus(result["returncode"], result["timed_out"])
+        return self._status
+
+
+@contextmanager
+def supervised_command(argv: Sequence[str], *, workspace: Path,
+                       environ: Mapping[str, str], timeout: float) -> Iterator[SupervisedCommand]:
+    configuration = json.dumps({"argv": list(argv), "environment": dict(environ)},
+                               ensure_ascii=False, allow_nan=False).encode("utf-8")
+    if len(configuration) > MAX_CONFIG_BYTES:
+        raise ValueError("Command supervisor configuration exceeds its byte limit")
+    owner_read = owner_write = config_read = config_write = status_read = status_write = -1
+    process = None
+    try:
+        owner_read, owner_write = os.pipe()
+        config_read, config_write = os.pipe()
+        status_read, status_write = os.pipe()
+        lease = inherited_acquisition_descriptor()
+        inherited = (owner_read, config_read, status_write)
+        if lease is not None:
+            inherited += (lease,)
+        supervisor = Path(__file__).with_name("command_supervisor.py")
+        process = subprocess.Popen(
+            [sys.executable, "-I", str(supervisor), str(owner_read),
+             str(lease if lease is not None else -1), str(config_read),
+             str(status_write), str(timeout)],
+            cwd=workspace, env={}, stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE, stderr=subprocess.PIPE,
+            start_new_session=True, pass_fds=inherited,
+        )
+        os.close(owner_read)
+        owner_read = -1
+        os.close(config_read)
+        config_read = -1
+        os.close(status_write)
+        status_write = -1
+        with os.fdopen(config_write, "wb") as stream:
+            config_write = -1
+            stream.write(configuration)
+        yield SupervisedCommand(process, status_read)
+    finally:
+        # EOF also occurs automatically if the application is killed. The
+        # independently running supervisor cleans the group while owning
+        # the shared lease, then exits and releases its descriptor.
+        if owner_write >= 0:
+            os.close(owner_write)
+        if owner_read >= 0:
+            os.close(owner_read)
+        if config_read >= 0:
+            os.close(config_read)
+        if config_write >= 0:
+            os.close(config_write)
+        if status_write >= 0:
+            os.close(status_write)
+        if process is not None:
+            try:
+                process.wait(timeout=5)
+            finally:
+                for stream in (process.stdin, process.stdout, process.stderr):
+                    if stream is not None:
+                        stream.close()
+                if status_read >= 0:
+                    os.close(status_read)
+        elif status_read >= 0:
+            os.close(status_read)

eal/command_supervisor.py

@@ -0,0 +1,112 @@
+"""Stop and reap one collector process group before releasing its inherited lease.
+
+This executable helper receives an ownership-pipe descriptor, an optional
+acquisition descriptor, a timeout and the trusted argv. Its stdin, stdout,
+stderr, working directory and environment pass directly to the collector.
+"""
+
+from __future__ import annotations
+
+import ctypes
+import json
+import os
+import select
+import signal
+import subprocess
+import sys
+import time
+
+
+MAX_CONFIG_BYTES = 4 * 1024 * 1024
+
+
+def _adopt_descendants() -> None:
+    if sys.platform.startswith("linux"):
+        # Reap orphaned group members ourselves instead of relying on a
+        # container's PID 1 to reap them before the next acquisition.
+        library = ctypes.CDLL(None, use_errno=True)
+        if library.prctl(36, 1, 0, 0, 0) != 0:  # PR_SET_CHILD_SUBREAPER
+            raise OSError(ctypes.get_errno(), "Cannot supervise collector descendants")
+
+
+def _stop_group(process: subprocess.Popen) -> None:
+    try:
+        os.killpg(process.pid, signal.SIGKILL)
+    except ProcessLookupError:
+        pass
+    process.wait()
+    # Linux adopts the descendants above; other POSIX init processes reap
+    # them. Retain the lease while any member of this group still exists.
+    while True:
+        try:
+            while os.waitpid(-process.pid, os.WNOHANG)[0]:
+                pass
+        except ChildProcessError:
+            pass
+        try:
+            os.killpg(process.pid, 0)
+        except ProcessLookupError:
+            return
+        time.sleep(0.01)
+
+
+def main() -> None:
+    owner = int(sys.argv[1])
+    lease = int(sys.argv[2])
+    configuration = int(sys.argv[3])
+    status = int(sys.argv[4])
+    deadline = time.monotonic() + float(sys.argv[5])
+    stopping = False
+
+    def request_stop(signum, frame):
+        nonlocal stopping
+        stopping = True
+
+    for signum in (signal.SIGTERM, signal.SIGINT, signal.SIGHUP):
+        signal.signal(signum, request_stop)
+    process = None
+    returncode = 127
+    timed_out = False
+    try:
+        _adopt_descendants()
+        with os.fdopen(configuration, "rb") as stream:
+            encoded = stream.read(MAX_CONFIG_BYTES + 1)
+        if len(encoded) > MAX_CONFIG_BYTES:
+            raise ValueError("Command supervisor configuration exceeds its byte limit")
+        settings = json.loads(encoded)
+        if stopping or select.select([owner], [], [], 0)[0]:
+            return
+        process = subprocess.Popen(settings["argv"], env=settings["environment"],
+                                   stdin=sys.stdin, stdout=sys.stdout,
+                                   stderr=sys.stderr, start_new_session=True)
+        while not stopping and time.monotonic() < deadline:
+            if process.poll() is not None:
+                returncode = process.returncode
+                break
+            if select.select([owner], [], [], 0.05)[0]:
+                stopping = True
+        else:
+            timed_out = not stopping
+    except OSError as error:
+        print(str(error), file=sys.stderr)
+    except (ValueError, KeyError, TypeError):
+        print("Invalid command supervisor configuration", file=sys.stderr)
+    finally:
+        if process is not None:
+            _stop_group(process)
+            returncode = process.returncode
+        try:
+            os.write(status, json.dumps({"returncode": returncode,
+                                       "timed_out": timed_out}).encode("ascii"))
+        except BrokenPipeError:
+            pass
+        finally:
+            os.close(status)
+        os.close(owner)
+        if lease >= 0:
+            os.close(lease)
+    raise SystemExit(0)
+
+
+if __name__ == "__main__":
+    main()