dr-exec 0.1.1__py3-none-any.whl

dr_exec/__init__.py

@@ -0,0 +1,227 @@
+"""Public dr-exec v1 capability and data-contract surface."""
+
+from dr_exec.cancel import CancelToken
+from dr_exec.declare import (
+    Budgets,
+    ByteBudget,
+    CountBudget,
+    DurationBudget,
+    EnvGrant,
+    EnvGrantRecord,
+    EnvVar,
+    ExecutionJob,
+    ExecutionTarget,
+    ExecutorSelfBudgets,
+    FiniteByteLimit,
+    FiniteCountLimit,
+    FiniteDurationLimit,
+    FiniteOutput,
+    OutputBudget,
+    PayloadRetentionBudget,
+    StreamRetentionBudget,
+    TrustedCommandTarget,
+    UnbudgetedLimit,
+    UnbudgetedOutput,
+    UntrustedCommandTarget,
+    UntrustedPythonTarget,
+)
+from dr_exec.errors import DeclarationError, ExecutorFailure, RecordLoadError
+from dr_exec.executor import ProcessExecutor
+from dr_exec.fake import FakeExecutor
+from dr_exec.kinds import (
+    BudgetAxis,
+    CapacitySource,
+    ContainmentProfile,
+    EnvGrantKind,
+    ExecutionPoolState,
+    ExecutionTargetKind,
+    FailureOwner,
+    LimitKind,
+    OutcomeKind,
+    OutputOverflowPolicy,
+    ProtocolFailureCode,
+    RecordReceiptKind,
+    RecordState,
+    RuntimeKind,
+)
+from dr_exec.names import AttemptId, ExecutionId, JobId
+from dr_exec.pool import (
+    AutoPoolCapacity,
+    EffectivePoolCapacity,
+    ExecutionCompletion,
+    ExecutionPool,
+    ExecutionPoolConfig,
+    ExecutionSubmission,
+    FixedPoolCapacity,
+    PoolCapacity,
+)
+from dr_exec.protocols import Executor, RunStore, Runtime
+from dr_exec.record import (
+    BudgetExceededOutcome,
+    BudgetExceededOutcomeRecord,
+    CancelledOutcome,
+    CancelledOutcomeRecord,
+    CompletedExecution,
+    CompleteRecordReceipt,
+    DegradedRecordReceipt,
+    ExecutionAttribution,
+    ExecutionAttributionRecord,
+    ExecutionMeasurements,
+    ExecutionOutcome,
+    ExecutionOutcomeRecord,
+    ExecutionResult,
+    ExecutionResultRecord,
+    ExecutionTargetRecord,
+    ExitedOutcome,
+    ExitedOutcomeRecord,
+    FakeRecordReceipt,
+    FinalizedRecord,
+    OutputArtifactRecord,
+    OutputArtifactRecords,
+    PayloadOutputRecords,
+    PayloadOutputs,
+    PreparedRecord,
+    ProcessRecord,
+    ProtocolFailedOutcome,
+    ProtocolFailedOutcomeRecord,
+    RealRecordReceipt,
+    RecordingFailure,
+    RecordReceipt,
+    RetainedPayloadStream,
+    RetainedPayloadStreamRecord,
+    RunDeclaration,
+    RunningRecord,
+    RunRecord,
+    RunRecordHeader,
+    SignaledOutcome,
+    SignaledOutcomeRecord,
+    SpawnAbsentOutcome,
+    SpawnAbsentOutcomeRecord,
+    SpawnFailedOutcome,
+    SpawnFailedOutcomeRecord,
+    TrustedCommandTargetRecord,
+    UntrustedCommandTargetRecord,
+    UntrustedPythonTargetRecord,
+)
+from dr_exec.runtime import (
+    IsolatedHostPythonRuntime,
+    PreparedPythonProcess,
+    RuntimeRecord,
+)
+from dr_exec.store import (
+    DirectoryRunStore,
+    FinalizableRun,
+    PreparedRun,
+    RunningRun,
+)
+
+__all__ = [
+    "AttemptId",
+    "AutoPoolCapacity",
+    "BudgetAxis",
+    "BudgetExceededOutcome",
+    "BudgetExceededOutcomeRecord",
+    "Budgets",
+    "ByteBudget",
+    "CancelToken",
+    "CancelledOutcome",
+    "CancelledOutcomeRecord",
+    "CapacitySource",
+    "CompleteRecordReceipt",
+    "CompletedExecution",
+    "ContainmentProfile",
+    "CountBudget",
+    "DeclarationError",
+    "DegradedRecordReceipt",
+    "DirectoryRunStore",
+    "DurationBudget",
+    "EffectivePoolCapacity",
+    "EnvGrant",
+    "EnvGrantKind",
+    "EnvGrantRecord",
+    "EnvVar",
+    "ExecutionAttribution",
+    "ExecutionAttributionRecord",
+    "ExecutionCompletion",
+    "ExecutionId",
+    "ExecutionJob",
+    "ExecutionMeasurements",
+    "ExecutionOutcome",
+    "ExecutionOutcomeRecord",
+    "ExecutionPool",
+    "ExecutionPoolConfig",
+    "ExecutionPoolState",
+    "ExecutionResult",
+    "ExecutionResultRecord",
+    "ExecutionSubmission",
+    "ExecutionTarget",
+    "ExecutionTargetKind",
+    "ExecutionTargetRecord",
+    "Executor",
+    "ExecutorFailure",
+    "ExecutorSelfBudgets",
+    "ExitedOutcome",
+    "ExitedOutcomeRecord",
+    "FailureOwner",
+    "FakeExecutor",
+    "FakeRecordReceipt",
+    "FinalizableRun",
+    "FinalizedRecord",
+    "FiniteByteLimit",
+    "FiniteCountLimit",
+    "FiniteDurationLimit",
+    "FiniteOutput",
+    "FixedPoolCapacity",
+    "IsolatedHostPythonRuntime",
+    "JobId",
+    "LimitKind",
+    "OutcomeKind",
+    "OutputArtifactRecord",
+    "OutputArtifactRecords",
+    "OutputBudget",
+    "OutputOverflowPolicy",
+    "PayloadOutputRecords",
+    "PayloadOutputs",
+    "PayloadRetentionBudget",
+    "PoolCapacity",
+    "PreparedPythonProcess",
+    "PreparedRecord",
+    "PreparedRun",
+    "ProcessExecutor",
+    "ProcessRecord",
+    "ProtocolFailedOutcome",
+    "ProtocolFailedOutcomeRecord",
+    "ProtocolFailureCode",
+    "RealRecordReceipt",
+    "RecordLoadError",
+    "RecordReceipt",
+    "RecordReceiptKind",
+    "RecordState",
+    "RecordingFailure",
+    "RetainedPayloadStream",
+    "RetainedPayloadStreamRecord",
+    "RunDeclaration",
+    "RunRecord",
+    "RunRecordHeader",
+    "RunStore",
+    "RunningRecord",
+    "RunningRun",
+    "Runtime",
+    "RuntimeKind",
+    "RuntimeRecord",
+    "SignaledOutcome",
+    "SignaledOutcomeRecord",
+    "SpawnAbsentOutcome",
+    "SpawnAbsentOutcomeRecord",
+    "SpawnFailedOutcome",
+    "SpawnFailedOutcomeRecord",
+    "StreamRetentionBudget",
+    "TrustedCommandTarget",
+    "TrustedCommandTargetRecord",
+    "UnbudgetedLimit",
+    "UnbudgetedOutput",
+    "UntrustedCommandTarget",
+    "UntrustedCommandTargetRecord",
+    "UntrustedPythonTarget",
+    "UntrustedPythonTargetRecord",
+]

dr_exec/_bootstrap.py

@@ -0,0 +1,206 @@
+"""Fixed isolated invocation shape and the library-owned child wrapper.
+
+The interpreter is always invoked as ``<executable> -I -c <source>``. The
+consumer's ``driver_source`` never reaches argv, a shell, or an import
+path: the library-owned wrapper carries it as one embedded string literal
+bound to a fixed name.
+
+The wrapper runs inside an isolated host interpreter that is not required
+to have dr-exec importable, so its body is stdlib-only and reproduces the
+pinned canonical JSON profile directly. It opens the protected descriptor
+before any domain code, reads the request through EOF, validates it,
+resolves ``dr_exec_main``, and writes LF-terminated canonical frames.
+
+Failure ownership is split at the wrapper boundary. A missing or
+non-callable entrypoint, a source-load failure, and a callback failure are
+payload-owned: the wrapper stops without a completion frame, so the parent
+observes an incomplete stream with every previously accepted output
+preserved. A protected-writer failure is executor-owned machinery failure.
+"""
+
+from __future__ import annotations
+
+# Child-observable literals. The invocation shape, the entrypoint name,
+# the embedded-source binding, and the protected descriptor number are
+# pinned; changing any of them is a standing-contract revision, not an
+# implementation detail.
+ISOLATED_INVOCATION_ARGUMENTS = ("-I", "-c")
+DRIVER_ENTRYPOINT_NAME = "dr_exec_main"
+DRIVER_SOURCE_BINDING = "DR_EXEC_DRIVER_SOURCE"
+PROTOCOL_DESCRIPTOR = 3
+
+# The wrapper body, stdlib-only and self-contained. It reads its own
+# module globals and never inspects argv or the environment. The pinned
+# child-observable literals are not spelled here: they are rendered from
+# the module constants above, which are their single source.
+_WRAPPER_BODY = '''
+import hashlib as _dr_exec_hashlib
+import json as _dr_exec_json
+import os as _dr_exec_os
+import sys as _dr_exec_sys
+
+_DR_EXEC_IDENTITY_FIELDS = {"schema", "schema_version", "payload"}
+
+
+def _dr_exec_canonical(value):
+    """Render the pinned canonical JSON profile as exact UTF-8 bytes."""
+    return _dr_exec_json.dumps(
+        value,
+        sort_keys=True,
+        separators=(",", ":"),
+        ensure_ascii=True,
+        allow_nan=False,
+    ).encode("utf-8")
+
+
+def _dr_exec_strict(value, path):
+    """Accept only strict JSON values; reject anything else by path."""
+    if value is None or isinstance(value, (str, bool, int)):
+        return
+    if isinstance(value, float):
+        if value != value or value in (float("inf"), float("-inf")):
+            raise ValueError("non-finite number at " + path)
+        return
+    if isinstance(value, list):
+        for index, item in enumerate(value):
+            _dr_exec_strict(item, path + "[" + str(index) + "]")
+        return
+    if isinstance(value, dict):
+        for key, item in value.items():
+            if not isinstance(key, str):
+                raise ValueError("non-string key at " + path)
+            _dr_exec_strict(item, path + "." + key)
+        return
+    raise ValueError("unsupported value at " + path)
+
+
+def _dr_exec_identity(document, origin):
+    """Validate the exact three-field Identity Document shape."""
+    if not isinstance(document, dict):
+        raise ValueError(origin + " must be an object")
+    if set(document) != _DR_EXEC_IDENTITY_FIELDS:
+        raise ValueError(origin + " must have exactly the identity fields")
+    if not isinstance(document["schema"], str):
+        raise ValueError(origin + " schema must be a string")
+    version = document["schema_version"]
+    if isinstance(version, bool) or not isinstance(version, int):
+        raise ValueError(origin + " schema_version must be an integer")
+    _dr_exec_strict(document["payload"], origin + ".payload")
+    return document
+
+
+def _dr_exec_read_request():
+    """Read stdin through EOF and validate the canonical request."""
+    data = _dr_exec_sys.stdin.buffer.read()
+    try:
+        decoded = _dr_exec_json.loads(data.decode("utf-8"))
+    except (UnicodeDecodeError, ValueError) as error:
+        raise ValueError("request is not strict JSON") from error
+    document = _dr_exec_identity(decoded, "request")
+    if _dr_exec_canonical(document) != data:
+        raise ValueError("request bytes are not canonical JSON bytes")
+    return document, data
+
+
+class _DrExecProtocolWriter:
+    """The protected fd 3 writer, owned by the library, not the payload.
+
+    The descriptor is duplicated and the original closed at construction,
+    so the handle survives domain code that replaces language-level
+    stdout or stderr, and the payload cannot reach the protected stream
+    through the well-known descriptor number. Every frame is flushed
+    before its call returns, so a later payload crash cannot lose an
+    output the parent already accepted.
+    """
+
+    def __init__(self, descriptor):
+        self._stream = _dr_exec_os.fdopen(_dr_exec_os.dup(descriptor), "wb")
+        _dr_exec_os.close(descriptor)
+        self._sequence = 0
+        self._closed = False
+
+    def prelude(self, request_bytes):
+        digest = _dr_exec_hashlib.sha256(request_bytes).hexdigest()
+        self._frame({
+            "version": 1,
+            "kind": "prelude",
+            "request_id_sha256": digest,
+        })
+
+    def emit(self, document):
+        validated = _dr_exec_identity(document, "output document")
+        self._frame({
+            "version": 1,
+            "kind": "output",
+            "sequence": self._sequence,
+            "document": {
+                "schema": validated["schema"],
+                "schema_version": validated["schema_version"],
+                "payload": validated["payload"],
+            },
+        })
+        self._sequence += 1
+
+    def complete(self):
+        self._frame({
+            "version": 1,
+            "kind": "complete",
+            "output_count": self._sequence,
+        })
+        self._closed = True
+        self._stream.close()
+
+    def _frame(self, frame):
+        if self._closed:
+            raise ValueError("the protected stream is already complete")
+        self._stream.write(_dr_exec_canonical(frame) + b"\\n")
+        self._stream.flush()
+
+
+def _dr_exec_bootstrap():
+    writer = _DrExecProtocolWriter(_DR_EXEC_PROTOCOL_DESCRIPTOR)
+    request, request_bytes = _dr_exec_read_request()
+    writer.prelude(request_bytes)
+    namespace = {"__name__": "dr_exec_driver"}
+    exec(DR_EXEC_DRIVER_SOURCE, namespace)
+    entrypoint = namespace.get(_DR_EXEC_ENTRYPOINT_NAME)
+    if not callable(entrypoint):
+        raise ValueError(
+            "driver_source must define a callable " + _DR_EXEC_ENTRYPOINT_NAME
+        )
+    entrypoint(request, writer.emit)
+    writer.complete()
+
+
+_dr_exec_bootstrap()
+'''
+
+
+def driver_wrapper_source(driver_source: str, /) -> str:
+    """Return the library-owned wrapper source embedding ``driver_source``.
+
+    ``driver_source`` is embedded through ``repr``, so arbitrary consumer
+    text -- quotes, backslashes, and newlines included -- stays one inert
+    string literal in the wrapper rather than executable wrapper syntax.
+    The pinned child-observable literals are rendered from the module
+    constants, so the child can only ever observe their one spelling.
+    """
+    if "\0" in driver_source:
+        raise ValueError("driver_source must not contain NUL")
+    return "\n".join(
+        (
+            f"{DRIVER_SOURCE_BINDING} = {driver_source!r}",
+            f"_DR_EXEC_PROTOCOL_DESCRIPTOR = {PROTOCOL_DESCRIPTOR}",
+            f"_DR_EXEC_ENTRYPOINT_NAME = {DRIVER_ENTRYPOINT_NAME!r}",
+            _WRAPPER_BODY,
+        )
+    )
+
+
+__all__ = [
+    "DRIVER_ENTRYPOINT_NAME",
+    "DRIVER_SOURCE_BINDING",
+    "ISOLATED_INVOCATION_ARGUMENTS",
+    "PROTOCOL_DESCRIPTOR",
+    "driver_wrapper_source",
+]

dr_exec/_declaration.py

@@ -0,0 +1,131 @@
+"""The declaration rules every executor applies, production or fake.
+
+These are the checks that read only the declaration itself: the bytes the
+child would receive against the declared input budget, and whether argv[0]
+has a defensible meaning under the declared environment grant. They depend
+on no host, no runtime, and no process, so one implementation serves both
+`ProcessExecutor` and `FakeExecutor` and the two cannot drift into
+accepting different declarations.
+
+Host support is deliberately *not* here. Refusing an unsupported platform
+is a statement about where a containment claim holds, not about whether a
+declaration is well-formed, and only the production path makes that claim.
+
+The Python target's transport bytes are the canonical request document,
+which the declaration already carries in full: the runtime chooses the
+interpreter invocation but never the request, so the input length measured
+here is the same length the engine measures after preparation.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from dr_exec._protocol import request_transport_bytes
+from dr_exec.declare import (
+    EnvGrant,
+    ExecutionJob,
+    FiniteByteLimit,
+    TrustedCommandTarget,
+    UntrustedCommandTarget,
+    UntrustedPythonTarget,
+)
+from dr_exec.errors import DeclarationError
+
+
+def granted_environment(grant: EnvGrant, /) -> dict[str, str]:
+    """Materialize the exact environment the child receives.
+
+    Values were snapshotted when the grant was constructed, so nothing
+    here consults the parent's live environment: the grant is the whole
+    inherited state.
+    """
+    return {variable.name: variable.value for variable in grant.variables}
+
+
+def declared_input_bytes(job: ExecutionJob, /) -> bytes:
+    """Return the exact bytes the declaration would send on child stdin."""
+    match job.target:
+        case TrustedCommandTarget() | UntrustedCommandTarget():
+            return job.target.stdin
+        case UntrustedPythonTarget():
+            return request_transport_bytes(job.target.request)
+
+
+def validate_input_budget(job: ExecutionJob, stdin_bytes: bytes, /) -> None:
+    """Compare declared input length with the budget before any spawn.
+
+    Input bounds are the one workload axis checked before a child exists,
+    so an over-budget input never costs a spawn.
+    """
+    budget = job.budgets.input_bytes
+    limit = budget.max_bytes if isinstance(budget, FiniteByteLimit) else None
+    if limit is not None and len(stdin_bytes) > limit:
+        raise DeclarationError(
+            f"declared input of {len(stdin_bytes)} bytes exceeds the "
+            f"{limit}-byte input budget"
+        )
+
+
+def validate_command_resolvability(
+    argv: tuple[str, ...],
+    environment: dict[str, str],
+    /,
+) -> None:
+    """Refuse an argv[0] the granted environment gives no meaning.
+
+    Absent a granted ``PATH``, only an absolute executable resolves; a
+    relative executable with no granted ``PATH`` has no defensible meaning
+    and is a declaration error rather than a spawn attempt that would
+    consult the parent's ambient search path.
+
+    A granted ``PATH`` resolves only through absolute entries, because the
+    child changes to its scratch directory before ``exec``: a relative hit
+    would name nothing the search found, and reading it against the
+    parent's location is the ambient cwd this package never consults. An
+    empty entry is the same case spelled shorter, since it means the
+    current directory.
+
+    A name that resolves nowhere is not refused here: production leaves
+    that to the spawn, which reports absence as an outcome rather than
+    raising.
+    """
+    name = argv[0]
+    if Path(name).is_absolute():
+        return
+    granted_path = environment.get("PATH")
+    if granted_path is None:
+        raise DeclarationError(
+            "a relative executable requires a granted PATH: " + name
+        )
+    for entry in granted_path.split(os.pathsep):
+        if not Path(entry).is_absolute():
+            raise DeclarationError(
+                "a granted PATH resolves only through absolute entries: "
+                + entry
+            )
+
+
+def validate_declaration(job: ExecutionJob, /) -> None:
+    """Apply every host-independent declaration rule, in engine order."""
+    validate_input_budget(job, declared_input_bytes(job))
+    match job.target:
+        case TrustedCommandTarget() | UntrustedCommandTarget():
+            validate_command_resolvability(
+                job.target.argv, granted_environment(job.env)
+            )
+        case UntrustedPythonTarget():
+            # The runtime owns this invocation and resolved its absolute
+            # executable at construction, so there is no caller-declared
+            # argv[0] to resolve.
+            return
+
+
+__all__ = [
+    "declared_input_bytes",
+    "granted_environment",
+    "validate_command_resolvability",
+    "validate_declaration",
+    "validate_input_budget",
+]