dirigent-plugin 0.17.2__tar.gz → 0.17.3__tar.gz

{dirigent_plugin-0.17.2 → dirigent_plugin-0.17.3}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: dirigent-plugin
-Version: 0.17.2
+Version: 0.17.3
 Summary: The dirigent plugin contract: block specs, protocols, and markers.
 License-Expression: LicenseRef-Proprietary
 License-File: LICENSE
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.13
-Requires-Dist: dirigent-common==0.17.2
+Requires-Dist: dirigent-common==0.17.3
 Requires-Dist: httpx2>=2.12.0
 Requires-Dist: pluginkit>=0.5.0
 Requires-Dist: pydantic>=2.13.5

{dirigent_plugin-0.17.2 → dirigent_plugin-0.17.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "dirigent-plugin"
-version = "0.17.2"
+version = "0.17.3"
 description = "The dirigent plugin contract: block specs, protocols, and markers."
 readme = "README.md"
 requires-python = ">=3.13"
@@ -11,7 +11,7 @@ classifiers = [
     "Programming Language :: Python :: 3.13",
 ]
 dependencies = [
-    "dirigent-common==0.17.2",
+    "dirigent-common==0.17.3",
     "httpx2>=2.12.0",
     "pluginkit>=0.5.0",
     "pydantic>=2.13.5",

{dirigent_plugin-0.17.2 → dirigent_plugin-0.17.3}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "dirigent-plugin"
-version = "0.17.2"
+version = "0.17.3"
 description = "The dirigent plugin contract: block specs, protocols, and markers."
 readme = "README.md"
 requires-python = ">=3.13"
@@ -11,7 +11,7 @@ classifiers = [
     "Programming Language :: Python :: 3.13",
 ]
 dependencies = [
-    "dirigent-common==0.17.2",
+    "dirigent-common==0.17.3",
     "httpx2>=2.12.0",
     "pluginkit>=0.5.0",
     "pydantic>=2.13.5",

{dirigent_plugin-0.17.2 → dirigent_plugin-0.17.3}/src/dirigent_plugin/__init__.py

@@ -10,6 +10,7 @@ from dirigent_plugin.blocks import (
     AnySensor,
     BlockFailure,
     ByteSink,
+    Capture,
     ConnectionKind,
     ConnectionRef,
     Contribution,
@@ -74,6 +75,7 @@ __all__ = [
     "BLOCK_ID_PATTERN",
     "BlockFailure",
     "ByteSink",
+    "Capture",
     "ConnectionKind",
     "ConnectionRef",
     "Contribution",

{dirigent_plugin-0.17.2 → dirigent_plugin-0.17.3}/src/dirigent_plugin/blocks.py

@@ -367,6 +367,13 @@ class ByteSink(Protocol):
         ...
 
 
+class Capture(ByteSink, Protocol):
+    """The write end of a captured stream, carrying the URI the engine wrote it under."""
+
+    uri: str
+    """Where the whole of the stream is being written, which is what the block's output carries."""
+
+
 class Logger(Protocol):
     """The scoped, batched log writer a block is handed; it produces run-visible entries."""
 
@@ -572,6 +579,17 @@ class StepContext(Protocol):
         """Return the run-scoped URI prefix for intermediate artifacts."""
         ...
 
+    def capture(self, name: str, *, content_type: str = "text/plain") -> AbstractAsyncContextManager[Capture]:
+        """Open the storage object a stream this block captures is written to.
+
+        The engine names the object under the run's scratch prefix, after the step, the
+        fan-out item and the attempt, so two attempts of one step never write over each
+        other, and opens it with the content type given. A block writes the stream through
+        the sink as it arrives and puts the sink's ``uri`` in its output; a block never names
+        a storage URI of its own.
+        """
+        ...
+
     @property
     def work(self) -> Path:
         """Return the run's directory on this worker's own filesystem, made on first read.
@@ -613,9 +631,10 @@ class Operator[ConfigT: BaseModel, OutputT: BaseModel](ABC):
     async def fetch(self, handle: RemoteHandle, config: ConfigT, ctx: StepContext) -> OutputT:
         """Retrieve the result after a probe reported SUCCEEDED; safe to call again.
 
-        The only thing that ends an attempt is the transaction recording its outcome, and a
-        worker that dies between fetching and that commit leaves the attempt to be claimed,
-        probed and fetched again. So this is at-least-once: retrieve, do not consume.
+        What comes back is committed on its own before the outcome settles the attempt, so a
+        replay finds the result and never asks for it twice. A worker that dies between
+        fetching and that commit leaves the attempt to be claimed, probed and fetched again,
+        so this is still at-least-once: retrieve, do not consume.
         """
         raise NotImplementedError(f"{type(self).__name__} returned a RemoteHandle but does not implement fetch()")