dr-exec 0.1.1__tar.gz

dr_exec-0.1.1/PKG-INFO

@@ -0,0 +1,55 @@
+Metadata-Version: 2.3
+Name: dr-exec
+Version: 0.1.1
+Summary: Contract-driven local process execution
+Author: Danielle Rothermel
+Author-email: Danielle Rothermel <danielle.rothermel@gmail.com>
+Requires-Dist: dr-serialize==0.1.1
+Requires-Dist: dr-store>=0.1.1
+Requires-Dist: pydantic==2.13.4
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# dr-exec
+
+Contract-driven local process execution.
+
+## Status
+
+The complete v1 surface is implemented:
+
+- identity and serialization — canonical secret-safe projections, the strict
+  bounded read path, and role-specific versioned identities;
+- the isolated-host Python runtime with its fixed `-I` probe and the
+  library-owned child wrapper;
+- the protected protocol — request transport, frame codec, the
+  prelude/output/completion state machine, and finite executor self-budgets;
+- durable recording — `DirectoryRunStore` over the pinned Document
+  Directory, with typed lifecycle handles, receipts, and strict load
+  validation;
+- the single-run engine behind `ProcessExecutor.run` — spawn through
+  teardown for trusted-command, untrusted-command, and untrusted-Python
+  targets, with budget enforcement, best-effort attribution, and the
+  mandatory record lifecycle;
+- `FakeExecutor`, which enforces the same declaration rules and carries an
+  explicit fake receipt, plus the shared behavioral conformance suite both
+  executors pass;
+- the bounded execution pool — one scheduler core behind
+  `ProcessExecutor.run_many`, `ProcessExecutor.open_pool`, and
+  `ExecutionPool.run_stream`, with one shared resident bound over running
+  and completed-but-undelivered submissions, completion-order delivery,
+  backpressure on intake, cancellation, drain, and abort.
+
+Execution runs on macOS; the engine refuses other platforms at the
+declaration boundary, and the tests that need real process semantics are
+marked accordingly.
+
+- Exact public API: [`src/dr_exec/__init__.py`](src/dr_exec/__init__.py)
+- Stable capability boundaries:
+  [`src/dr_exec/protocols.py`](src/dr_exec/protocols.py)
+- Planned behavioral contracts:
+  [`docs/v1-plan/contracts.toml`](docs/v1-plan/contracts.toml)
+- Design and qualification mechanics:
+  [`docs/v1-plan/v1-design.md`](docs/v1-plan/v1-design.md)
+- Shared serialization capabilities delivered by the dr-serialize pin:
+  [`docs/v1-plan/dr-serialize-additions.md`](docs/v1-plan/dr-serialize-additions.md)

dr_exec-0.1.1/README.md

@@ -0,0 +1,43 @@
+# dr-exec
+
+Contract-driven local process execution.
+
+## Status
+
+The complete v1 surface is implemented:
+
+- identity and serialization — canonical secret-safe projections, the strict
+  bounded read path, and role-specific versioned identities;
+- the isolated-host Python runtime with its fixed `-I` probe and the
+  library-owned child wrapper;
+- the protected protocol — request transport, frame codec, the
+  prelude/output/completion state machine, and finite executor self-budgets;
+- durable recording — `DirectoryRunStore` over the pinned Document
+  Directory, with typed lifecycle handles, receipts, and strict load
+  validation;
+- the single-run engine behind `ProcessExecutor.run` — spawn through
+  teardown for trusted-command, untrusted-command, and untrusted-Python
+  targets, with budget enforcement, best-effort attribution, and the
+  mandatory record lifecycle;
+- `FakeExecutor`, which enforces the same declaration rules and carries an
+  explicit fake receipt, plus the shared behavioral conformance suite both
+  executors pass;
+- the bounded execution pool — one scheduler core behind
+  `ProcessExecutor.run_many`, `ProcessExecutor.open_pool`, and
+  `ExecutionPool.run_stream`, with one shared resident bound over running
+  and completed-but-undelivered submissions, completion-order delivery,
+  backpressure on intake, cancellation, drain, and abort.
+
+Execution runs on macOS; the engine refuses other platforms at the
+declaration boundary, and the tests that need real process semantics are
+marked accordingly.
+
+- Exact public API: [`src/dr_exec/__init__.py`](src/dr_exec/__init__.py)
+- Stable capability boundaries:
+  [`src/dr_exec/protocols.py`](src/dr_exec/protocols.py)
+- Planned behavioral contracts:
+  [`docs/v1-plan/contracts.toml`](docs/v1-plan/contracts.toml)
+- Design and qualification mechanics:
+  [`docs/v1-plan/v1-design.md`](docs/v1-plan/v1-design.md)
+- Shared serialization capabilities delivered by the dr-serialize pin:
+  [`docs/v1-plan/dr-serialize-additions.md`](docs/v1-plan/dr-serialize-additions.md)

dr_exec-0.1.1/pyproject.toml

@@ -0,0 +1,46 @@
+[project]
+name = "dr-exec"
+version = "0.1.1"
+description = "Contract-driven local process execution"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "dr-serialize==0.1.1",
+    "dr-store>=0.1.1",
+    "pydantic==2.13.4",
+]
+
+[[project.authors]]
+name = "Danielle Rothermel"
+email = "danielle.rothermel@gmail.com"
+
+[build-system]
+requires = ["uv_build>=0.11.25,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.4.2",
+    "ruff>=0.16.1",
+    "ty>=0.0.65",
+]
+
+[tool.ruff]
+include = [
+    "scripts/**/*.py",
+    "src/**/*.py",
+    "tests/**/*.py",
+]
+line-length = 79
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "--strict-markers --strict-config"
+
+[tool.ty.src]
+include = [
+    "scripts",
+    "src",
+    "tests",
+]
+exclude = ["nbs"]

dr_exec-0.1.1/pyproject.toml.orig

@@ -0,0 +1,37 @@
+[project]
+name = "dr-exec"
+version = "0.1.1"
+description = "Contract-driven local process execution"
+readme = "README.md"
+authors = [
+    { name = "Danielle Rothermel", email = "danielle.rothermel@gmail.com" }
+]
+requires-python = ">=3.12"
+dependencies = [
+    "dr-serialize==0.1.1",
+    "dr-store>=0.1.1",
+    "pydantic==2.13.4",
+]
+
+[build-system]
+requires = ["uv_build>=0.11.25,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.4.2",
+    "ruff>=0.16.1",
+    "ty>=0.0.65",
+]
+
+[tool.ruff]
+include = ["scripts/**/*.py", "src/**/*.py", "tests/**/*.py"]
+line-length = 79
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "--strict-markers --strict-config"
+
+[tool.ty.src]
+include = ["scripts", "src", "tests"]
+exclude = ["nbs"]

dr_exec-0.1.1/src/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-0.1.1/src/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",
+]