dirigent-plugin 0.16.6__tar.gz → 0.17.0__tar.gz

{dirigent_plugin-0.16.6 → dirigent_plugin-0.17.0}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: dirigent-plugin
-Version: 0.16.6
+Version: 0.17.0
 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.16.6
+Requires-Dist: dirigent-common==0.17.0
 Requires-Dist: httpx2>=2.12.0
 Requires-Dist: pluginkit>=0.5.0
 Requires-Dist: pydantic>=2.13.5

{dirigent_plugin-0.16.6 → dirigent_plugin-0.17.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "dirigent-plugin"
-version = "0.16.6"
+version = "0.17.0"
 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.16.6",
+    "dirigent-common==0.17.0",
     "httpx2>=2.12.0",
     "pluginkit>=0.5.0",
     "pydantic>=2.13.5",

{dirigent_plugin-0.16.6 → dirigent_plugin-0.17.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "dirigent-plugin"
-version = "0.16.6"
+version = "0.17.0"
 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.16.6",
+    "dirigent-common==0.17.0",
     "httpx2>=2.12.0",
     "pluginkit>=0.5.0",
     "pydantic>=2.13.5",

{dirigent_plugin-0.16.6 → dirigent_plugin-0.17.0}/src/dirigent_plugin/__init__.py

@@ -22,12 +22,14 @@ from dirigent_plugin.blocks import (
     OperatorSpec,
     ProbeResult,
     ProbeStatus,
+    Reference,
     RemoteHandle,
     RunId,
     RunRefused,
     Runs,
     RunSnapshot,
     RunState,
+    SchemaRef,
     Sensor,
     SensorSpec,
     ShellString,
@@ -50,6 +52,7 @@ from dirigent_plugin.markers import (
     extension_point,
     formatters,
 )
+from dirigent_plugin.runners import ProgramRunner, RunnerEngine
 from dirigent_plugin.transforms import (
     ConvertConfig,
     Converter,
@@ -92,13 +95,17 @@ __all__ = [
     "ProbeResult",
     "ProbeStatus",
     "ProgramConfig",
+    "ProgramRunner",
+    "Reference",
     "RemoteHandle",
     "RunId",
     "RunRefused",
     "RunSnapshot",
     "RunState",
+    "RunnerEngine",
     "Runs",
     "SURFACE_ID_PATTERN",
+    "SchemaRef",
     "Sensor",
     "SensorSpec",
     "SHELL_VARIABLES_FIELD",

{dirigent_plugin-0.16.6 → dirigent_plugin-0.17.0}/src/dirigent_plugin/blocks.py

@@ -6,7 +6,7 @@ from contextlib import AbstractAsyncContextManager
 from datetime import datetime, timedelta
 from enum import StrEnum
 from pathlib import Path
-from typing import Annotated, Any, ClassVar, Final, Protocol, cast
+from typing import Annotated, Any, ClassVar, Final, Literal, Protocol, cast
 from uuid import UUID
 
 import httpx2
@@ -15,13 +15,14 @@ from pydantic import BaseModel, ConfigDict, Field, GetJsonSchemaHandler, JsonVal
 from pydantic.json_schema import JsonSchemaValue, SkipJsonSchema
 from pydantic_core import CoreSchema
 
-from dirigent_common import API_VERSION, SHELL_MEDIA_TYPE, BlockModel, HealthReport, JsonMap
+from dirigent_common import API_VERSION, SHELL_MEDIA_TYPE, BlockModel, HealthReport, Issue, JsonMap, Message
+from dirigent_plugin.messages import (
+    DUPLICATE_ID,
+    UNSUPPORTED_API_VERSION,
+)
 
 type RunId = UUID
 
-#: A connection is referenced by name, never by id, so documents stay portable.
-type ConnectionRef = str
-
 #: A JSON Schema format checker: a predicate that returns True when a value satisfies the
 #: format, False when it does not, and may instead raise to signal the value is invalid --
 #: exactly what ``jsonschema.FormatChecker.checks`` registers.
@@ -50,12 +51,15 @@ class ErrorClass(StrEnum):
 
 
 class BlockFailure(Exception):
-    """A failure a block reports deliberately, carrying its own error classification."""
-
-    def __init__(self, message: str, *, error_class: ErrorClass = ErrorClass.UNKNOWN) -> None:
-        """Record the message and the class the engine should retry (or not retry) on."""
-        super().__init__(message)
-        self.message = message
+    """A failure a block reports deliberately, carrying its code and its classification."""
+
+    def __init__(self, message: Message, /, *, error_class: ErrorClass = ErrorClass.UNKNOWN, **params: Any) -> None:
+        """Render the catalogued message and record the class the engine retries (or not) on."""
+        rendered = message.render(**params)
+        super().__init__(rendered)
+        self.code = message.code
+        self.message = rendered
+        self.params: JsonMap = dict(params)
         self.error_class = error_class
 
     def __str__(self) -> str:
@@ -132,6 +136,43 @@ class ShellString:
         return published
 
 
+class Reference:
+    """Marks a config field whose value is the code of another thing this instance holds.
+
+    It publishes ``x-dirigent-ref`` carrying what the code names, and a form generated from the
+    schema draws that thing under the field. It is a bare class rather than a model: annotation
+    metadata pydantic recognises as a model would be read as the field's schema, and a marker
+    must stay invisible to validation.
+    """
+
+    __slots__ = ("kind",)
+
+    def __init__(self, kind: Literal["connection", "schema"]) -> None:
+        """Record what a value of the marked field names."""
+        self.kind = kind
+
+    def __repr__(self) -> str:
+        """Render the marker the way it is written."""
+        return f"Reference({self.kind!r})"
+
+    def __get_pydantic_json_schema__(
+        self,
+        schema: CoreSchema,
+        handler: GetJsonSchemaHandler,
+    ) -> JsonSchemaValue:
+        """Publish what the marked field's code names, leaving what it validates untouched."""
+        published = handler(schema)
+        published["x-dirigent-ref"] = self.kind
+        return published
+
+
+#: A connection is referenced by code, never by id, so documents stay portable.
+type ConnectionRef = Annotated[str, Reference("connection")]
+
+#: A schema is referenced by code: one the instance holds, or one the document carries.
+type SchemaRef = Annotated[str, Reference("schema")]
+
+
 #: What the engine names the variables it substitutes a shell string's references out into.
 SHELL_VARIABLE_PREFIX: Final = "DIRIGENT_V"
 
@@ -353,8 +394,12 @@ class Storage(Protocol):
         """Stream the object at a URI, closeable so a reader that stops early releases it."""
         ...
 
-    def open_write(self, uri: str) -> AbstractAsyncContextManager[ByteSink]:
-        """Open a streamed writer for a URI."""
+    def open_write(self, uri: str, *, content_type: str | None = None) -> AbstractAsyncContextManager[ByteSink]:
+        """Open a streamed writer for a URI.
+
+        The backend records the content type on the object where its store can hold one, and
+        ignores it where it cannot.
+        """
         ...
 
     async def stat(self, uri: str) -> StatResult | None:
@@ -392,9 +437,9 @@ class RunState(StrEnum):
 class RunRefused(BlockFailure):
     """The instance refused to start the run a block asked for."""
 
-    def __init__(self, message: str) -> None:
+    def __init__(self, message: Message, /, **params: Any) -> None:
         """Carry the reason, classified as the configuration error it always is."""
-        super().__init__(message, error_class=ErrorClass.REJECTED)
+        super().__init__(message, error_class=ErrorClass.REJECTED, **params)
 
 
 class StartedRun(BaseModel):
@@ -578,10 +623,10 @@ class Operator[ConfigT: BaseModel, OutputT: BaseModel](ABC):
         """Best-effort, idempotent cancellation; False means the remote could not be told."""
         return False
 
-    def check_config(self, config: BaseModel) -> list[str]:
+    def check_config(self, config: BaseModel) -> list[Issue]:
         """List the extra refusals this block makes at apply, beyond what its schema says.
 
-        Each string is shown against the step's config location, so a document is refused
+        Each issue is shown against the step's config location, so a document is refused
         before it is stored rather than the first time it runs.
         """
         return []
@@ -603,10 +648,10 @@ class Sensor[ConfigT: BaseModel, OutputT: BaseModel](ABC):
         """Observe the world once, read-only and briefly; NotYet is not a failure."""
         ...
 
-    def check_config(self, config: BaseModel) -> list[str]:
+    def check_config(self, config: BaseModel) -> list[Issue]:
         """List the extra refusals this block makes at apply, beyond what its schema says.
 
-        Each string is shown against the step's config location, so a document is refused
+        Each issue is shown against the step's config location, so a document is refused
         before it is stored rather than the first time it runs.
         """
         return []
@@ -642,8 +687,12 @@ class StorageBackend(ABC):
         ...
 
     @abstractmethod
-    def open_write(self, uri: str) -> AbstractAsyncContextManager[ByteSink]:
-        """Open a streamed writer for a URI."""
+    def open_write(self, uri: str, *, content_type: str | None = None) -> AbstractAsyncContextManager[ByteSink]:
+        """Open a streamed writer for a URI.
+
+        The backend records the content type on the object where its store can hold one, and
+        ignores it where it cannot.
+        """
         ...
 
     @abstractmethod
@@ -711,7 +760,7 @@ class Contribution(BaseModel):
     def _check_api_version(cls, value: int) -> int:
         """Reject a contribution written against a different revision of this contract."""
         if value != API_VERSION:
-            raise ValueError(f"unsupported api_version {value}; this host speaks {API_VERSION}")
+            raise ValueError(UNSUPPORTED_API_VERSION.render(version=value, host_version=API_VERSION))
         return value
 
     @model_validator(mode="after")
@@ -734,7 +783,7 @@ def _require_unique(label: str, values: list[str]) -> None:
     seen: set[str] = set()
     for value in values:
         if value in seen:
-            raise ValueError(f"duplicate {label} {value!r} in contribution")
+            raise ValueError(DUPLICATE_ID.render(label=label, value=repr(value)))
         seen.add(value)
 
 

dirigent_plugin-0.17.0/src/dirigent_plugin/messages.py

@@ -0,0 +1,39 @@
+"""Every refusal the block contract itself makes, catalogued under the ``plugin`` prefix."""
+
+from dirigent_common import Catalogue
+
+PLUGIN = Catalogue("plugin")
+
+TRANSFORM_FAILED = PLUGIN.define("transform_failed", "{detail}")
+
+PROGRAM_REFUSED = PLUGIN.define("program_refused", "{detail}")
+
+ELEMENT_FAILED = PLUGIN.define("element_failed", "element {index}: {detail}")
+
+FILTER_ANSWER = PLUGIN.define(
+    "filter_answer",
+    "{block} answered {answer} for element {index}, and a filter's answer is true or false",
+)
+
+UNSUPPORTED_PAIR = PLUGIN.define(
+    "unsupported_pair",
+    "{block} does not convert {source_format} to {target_format} ({supported})",
+)
+
+NOT_AN_ARRAY = PLUGIN.define(
+    "not_an_array",
+    "{block} {promise}, so its input has to be a JSON array, and this one is {described}",
+)
+
+NOTHING_TO_CONVERT = PLUGIN.define("nothing_to_convert", "there is nothing at {uri} to convert")
+
+
+# What a config refuses at validation. Pydantic owns the code a validator's refusal reaches
+# the wire under, so these are rendered into the ``ValueError`` it wraps.
+
+UNSUPPORTED_API_VERSION = PLUGIN.define(
+    "unsupported_api_version",
+    "unsupported api_version {version}; this host speaks {host_version}",
+)
+
+DUPLICATE_ID = PLUGIN.define("duplicate_id", "duplicate {label} {value} in contribution")

dirigent_plugin-0.17.0/src/dirigent_plugin/runners.py

@@ -0,0 +1,255 @@
+"""The runner protocol: a program engine whose programs are compiled and run in a process of its own.
+
+An engine that computes inside a C extension holding the interpreter's lock holds the
+worker's event loop from a thread as firmly as from the loop itself, and a thread cannot be
+cancelled: the step's timeout never fires, the lease heartbeat never runs, and the sweeper
+hands the attempt to another worker while this one is still computing. Such an engine names
+the ``command`` that starts a runner, and its programs run there, where killing the process
+is what ends them.
+
+A runner reads one JSON object per line and answers one JSON object per line, one reply per
+request and in the order the requests arrived:
+
+- ``{"kind": "compile", "id": ..., "program": ...}``, answered with ``{"ok": true}``, or
+  with ``{"error": "..."}`` carrying the runner's own message about a program it refuses.
+  A program that compiled is held under the id it was named by.
+- ``{"kind": "run", "id": ..., "value": ...}``, answered with ``{"outputs": [...]}``, the
+  stream the program produced, or with ``{"error": "..."}``.
+- ``{"kind": "forget", "id": ...}``, answered with ``{"ok": true}``: the program is released.
+
+A step's program therefore crosses the pipe once, however many elements it is run over. The
+pipe closing is how the parent says it is done.
+"""
+
+import asyncio
+import atexit
+import json
+import subprocess
+from collections.abc import Callable, Sequence
+from contextvars import ContextVar
+from typing import IO, Any, ClassVar, cast
+from uuid import uuid4
+
+from pydantic import BaseModel, JsonValue
+
+from dirigent_common import Issue
+from dirigent_plugin.messages import PROGRAM_REFUSED
+from dirigent_plugin.transforms import Engine, ProgramConfig, TransformError
+
+#: What a step is told when the process running its program stopped on its own. It is not a
+#: TransformError, because nothing about the program says it will happen again.
+RUNNER_STOPPED = "the process running the program stopped before it answered"
+
+
+class ProgramRunner:
+    """One runner process, and the two pipes a program and its outputs cross."""
+
+    def __init__(self, command: Sequence[str]) -> None:
+        """Start the process the command names and hold the pipes it is spoken to over."""
+        self.command = tuple(command)
+        self.process = subprocess.Popen(
+            self.command,
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+        )
+        # Popen types both pipes as optional; both were asked for.
+        self._to = cast("IO[bytes]", self.process.stdin)
+        self._from = cast("IO[bytes]", self.process.stdout)
+        self._compiled: set[str] = set()
+
+    @property
+    def alive(self) -> bool:
+        """Whether this process is still there to run a program."""
+        return self.process.poll() is None
+
+    def compile(self, source: str) -> str:
+        """Compile one program in this process and hand back the id it is run by."""
+        identifier = uuid4().hex
+        self._exchange({"kind": "compile", "id": identifier, "program": source})
+        # Held only once it has compiled, so a refused program is never one to forget.
+        self._compiled.add(identifier)
+        return identifier
+
+    def run(self, identifier: str, value: JsonValue) -> list[JsonValue]:
+        """Run the program compiled under an id over one value and read the outputs it produced."""
+        answered = self._exchange({"kind": "run", "id": identifier, "value": value})
+        return cast("list[JsonValue]", answered["outputs"])
+
+    def forget(self, identifier: str) -> None:
+        """Release one compiled program."""
+        self._compiled.discard(identifier)
+        self._exchange({"kind": "forget", "id": identifier})
+
+    def release(self) -> None:
+        """Forget every program compiled here, so a runner outliving a step keeps none of them.
+
+        A runner that has stopped took its programs with it, and there is nothing to say to
+        a closed pipe.
+        """
+        if not self.alive:
+            self._compiled.clear()
+            return
+        for identifier in sorted(self._compiled):
+            self.forget(identifier)
+
+    def kill(self) -> None:
+        """End whatever is running, which is the only way to stop a program, and close it out.
+
+        Waiting is what makes the process dead rather than dying, so the pool sees at once
+        that this one is not to be handed out again; a killed process is reaped at once.
+        Closing the pipes waits for the read a step's thread is still blocked in, which the
+        kill has just ended, and leaves no descriptor behind for a collection to complain of.
+        """
+        self.process.kill()
+        self.process.wait()
+        self._to.close()
+        self._from.close()
+
+    def _exchange(self, request: dict[str, Any]) -> dict[str, Any]:
+        """Send one request, read the one reply to it, and raise what the runner refused."""
+        try:
+            self._to.write(json.dumps(request).encode() + b"\n")
+            self._to.flush()
+            reply = self._from.readline()
+        except OSError as error:
+            raise RuntimeError(RUNNER_STOPPED) from error
+        if not reply:
+            # A killed process, which is how a cancelled step ends its program, and how a
+            # program that ran the process out of memory ends itself.
+            raise RuntimeError(RUNNER_STOPPED)
+        answered = cast("dict[str, Any]", json.loads(reply))
+        refusal = answered.get("error")
+        if refusal is not None:
+            raise TransformError(cast("str", refusal))
+        return answered
+
+
+class _Runners:
+    """The runner processes this worker keeps: one per command, and one per step running at a time.
+
+    A step holds one for as long as its program runs and gives it back after, so two steps
+    never meet on one pipe. A process is started when there is none to hand out and then
+    lives on, because starting one costs more than every program a step runs through it; it
+    ends when the worker does, its pipe closing under it. A process that was killed is not
+    handed out again.
+    """
+
+    def __init__(self) -> None:
+        """Start with no processes; the first step that needs one starts it."""
+        self._idle: dict[tuple[str, ...], list[ProgramRunner]] = {}
+
+    async def take(self, command: Sequence[str]) -> ProgramRunner:
+        """Hand out an idle process for a command, starting one off the event loop when there is none."""
+        idle = self._idle.setdefault(tuple(command), [])
+        while idle:
+            runner = idle.pop()
+            if runner.alive:
+                return runner
+        starting = asyncio.ensure_future(asyncio.to_thread(ProgramRunner, command))
+        try:
+            return await asyncio.shield(starting)
+        except asyncio.CancelledError:
+            # A step can be cancelled while its process is still starting. The start is
+            # shielded so the process is finished and kept, rather than left running for a
+            # step that is already gone.
+            starting.add_done_callback(self._started)
+            raise
+
+    def give_back(self, runner: ProgramRunner) -> None:
+        """Take a process back for the next step that runs its command, unless it was killed."""
+        if runner.alive:
+            self._idle.setdefault(runner.command, []).append(runner)
+
+    def shutdown(self) -> None:
+        """Kill every idle process, so none is left running when this one exits."""
+        for idle in self._idle.values():
+            while idle:
+                idle.pop().kill()
+
+    def _started(self, starting: "asyncio.Future[ProgramRunner]") -> None:
+        """Keep a process whose step gave up on it while it was starting."""
+        if not starting.cancelled() and starting.exception() is None:
+            self.give_back(starting.result())
+
+
+#: The runner processes this worker keeps. One pool for every engine, keyed by the command
+#: that starts a runner: a step holds a runner, not a verb.
+_RUNNERS = _Runners()
+
+atexit.register(_RUNNERS.shutdown)
+
+#: The runner the step running on this task talks to. A program is compiled and run from
+#: inside the thread offload() hands the step's work to, which is where the engine reads it.
+_RUNNING: ContextVar[ProgramRunner] = ContextVar("dirigent_program_runner")
+
+
+def _running() -> ProgramRunner:
+    """The runner this step holds, which only a step running through offload() has."""
+    try:
+        return _RUNNING.get()
+    except LookupError as error:
+        missing = "a runner engine is called through offload(), which takes the process its program runs in"
+        raise RuntimeError(missing) from error
+
+
+class RunnerEngine(Engine):
+    """A program engine whose programs are compiled and run in a runner process.
+
+    The engine supplies the command that starts one and the source its runner compiles; the
+    step holds one runner for its whole run, its program is compiled there once, every
+    element is run through the id that compile answered with, and the id is forgotten when
+    the runner is given back.
+
+    The three program verbs are what this is for: ``convert`` has no program, so a codec
+    engine has no runner either.
+    """
+
+    command: ClassVar[Sequence[str]]
+    """What starts one runner process for this engine."""
+
+    def source(self, program: str) -> str:
+        """The source the runner compiles: the author's program, wrapped as the engine needs it."""
+        return program
+
+    def check_program(self, program: str) -> None:
+        """Refuse a bad program at apply by raising TransformError, where an engine can read its own language.
+
+        There is no runner outside a step, so an engine that cannot parse its language on
+        the worker leaves a bad program to be refused when the step compiles it.
+        """
+        return
+
+    def compile(self, program: str) -> object:
+        """Compile the program in the runner this step holds and hand back the id it is run by."""
+        return _running().compile(self.source(program))
+
+    def outputs(self, compiled: object, value: JsonValue) -> list[JsonValue]:
+        """Run a compiled program over one value in this step's runner and read its outputs."""
+        return _running().run(cast("str", compiled), value)
+
+    async def offload[T](self, work: Callable[[], T]) -> T:
+        """Hold a runner for the step, and kill it if the step is cancelled or times out."""
+        runner = await _RUNNERS.take(self.command)
+        token = _RUNNING.set(runner)
+        try:
+            return await asyncio.to_thread(work)
+        except asyncio.CancelledError:
+            # Cancelling the await does not stop the thread: it is inside a blocking read,
+            # and killing the process is both what ends the program and what lets that read
+            # return, so nothing is left running behind a step that has already failed.
+            runner.kill()
+            raise
+        finally:
+            _RUNNING.reset(token)
+            runner.release()
+            _RUNNERS.give_back(runner)
+
+    def check_config(self, config: BaseModel) -> list[Issue]:
+        """Check the program at apply, where the engine's own reading of it is all there is."""
+        if not isinstance(config, ProgramConfig):
+            return []
+        try:
+            self.check_program(config.program)
+        except TransformError as error:
+            return [Issue.of(PROGRAM_REFUSED, detail=str(error))]
+        return []

{dirigent_plugin-0.16.6 → dirigent_plugin-0.17.0}/src/dirigent_plugin/transforms.py

@@ -30,7 +30,7 @@ from typing import Any, ClassVar, Final, cast
 
 from pydantic import BaseModel, Field, JsonValue
 
-from dirigent_common import BlockModel, StorageUri
+from dirigent_common import BlockModel, Issue, JsonMap, StorageUri
 from dirigent_plugin.blocks import (
     BlockFailure,
     ErrorClass,
@@ -39,6 +39,15 @@ from dirigent_plugin.blocks import (
     RemoteHandle,
     StepContext,
 )
+from dirigent_plugin.messages import (
+    ELEMENT_FAILED,
+    FILTER_ANSWER,
+    NOT_AN_ARRAY,
+    NOTHING_TO_CONVERT,
+    PROGRAM_REFUSED,
+    TRANSFORM_FAILED,
+    UNSUPPORTED_PAIR,
+)
 
 #: How much is handed to a storage sink at a time.
 CHUNK_BYTES: Final = 64 * 1024
@@ -181,17 +190,17 @@ class Transformer(Engine, Operator[ProgramConfig, TransformOutput], ABC):
         try:
             result = await self.offload(lambda: self.apply(self.compile(config.program), config.input))
         except TransformError as error:
-            raise BlockFailure(str(error), error_class=ErrorClass.REJECTED) from error
+            raise BlockFailure(TRANSFORM_FAILED, error_class=ErrorClass.REJECTED, detail=str(error)) from error
         return TransformOutput(value=result)
 
-    def check_config(self, config: BaseModel) -> list[str]:
+    def check_config(self, config: BaseModel) -> list[Issue]:
         """Compile the program at apply, so a bad one is refused before the document is stored."""
         if not isinstance(config, ProgramConfig):
             return []
         try:
             self.compile(config.program)
         except TransformError as error:
-            return [str(error)]
+            return [Issue.of(PROGRAM_REFUSED, detail=str(error))]
         return []
 
 
@@ -253,7 +262,7 @@ class Mapper(Engine, Operator[ProgramConfig, TransformOutput], ABC):
         try:
             compiled = self.compile(program)
         except TransformError as error:
-            raise BlockFailure(str(error), error_class=ErrorClass.REJECTED) from error
+            raise BlockFailure(TRANSFORM_FAILED, error_class=ErrorClass.REJECTED, detail=str(error)) from error
         return self._map_each(compiled, elements)
 
     def _map_each(self, compiled: object, elements: list[JsonValue]) -> list[JsonValue]:
@@ -263,17 +272,19 @@ class Mapper(Engine, Operator[ProgramConfig, TransformOutput], ABC):
             try:
                 mapped.append(self.apply(compiled, element))
             except TransformError as error:
-                raise BlockFailure(f"element {index}: {error}", error_class=ErrorClass.REJECTED) from error
+                raise BlockFailure(
+                    ELEMENT_FAILED, error_class=ErrorClass.REJECTED, index=index, detail=str(error)
+                ) from error
         return mapped
 
-    def check_config(self, config: BaseModel) -> list[str]:
+    def check_config(self, config: BaseModel) -> list[Issue]:
         """Compile the program at apply, so a bad one is refused before the document is stored."""
         if not isinstance(config, ProgramConfig):
             return []
         try:
             self.compile(config.program)
         except TransformError as error:
-            return [str(error)]
+            return [Issue.of(PROGRAM_REFUSED, detail=str(error))]
         return []
 
 
@@ -335,7 +346,7 @@ class Filterer(Engine, Operator[ProgramConfig, TransformOutput], ABC):
         try:
             compiled = self.compile(program)
         except TransformError as error:
-            raise BlockFailure(str(error), error_class=ErrorClass.REJECTED) from error
+            raise BlockFailure(TRANSFORM_FAILED, error_class=ErrorClass.REJECTED, detail=str(error)) from error
         return [self._verdict(compiled, element, index) for index, element in enumerate(elements)]
 
     def _verdict(self, compiled: object, element: JsonValue, index: int) -> bool:
@@ -345,22 +356,27 @@ class Filterer(Engine, Operator[ProgramConfig, TransformOutput], ABC):
             # engine is held to it.
             answer = cast("object", self.keep(compiled, element))
         except TransformError as error:
-            raise BlockFailure(f"element {index}: {error}", error_class=ErrorClass.REJECTED) from error
+            raise BlockFailure(
+                ELEMENT_FAILED, error_class=ErrorClass.REJECTED, index=index, detail=str(error)
+            ) from error
         if not isinstance(answer, bool):
             raise BlockFailure(
-                f"{self.spec.id} answered {answer!r} for element {index}, and a filter's answer is true or false",
+                FILTER_ANSWER,
                 error_class=ErrorClass.REJECTED,
+                block=self.spec.id,
+                answer=repr(answer),
+                index=index,
             )
         return answer
 
-    def check_config(self, config: BaseModel) -> list[str]:
+    def check_config(self, config: BaseModel) -> list[Issue]:
         """Compile the program at apply, so a bad one is refused before the document is stored."""
         if not isinstance(config, ProgramConfig):
             return []
         try:
             self.compile(config.program)
         except TransformError as error:
-            return [str(error)]
+            return [Issue.of(PROGRAM_REFUSED, detail=str(error))]
         return []
 
 
@@ -402,33 +418,37 @@ class Converter(Engine, Operator[ConvertConfig, ConvertOutput], ABC):
 
     async def execute(self, config: ConvertConfig, ctx: StepContext) -> ConvertOutput | RemoteHandle:
         """Refuse an unsupported pair, then re-encode the source object onto the target."""
-        unsupported = self._pair_refusal(config.from_format, config.to_format)
+        unsupported = self._unsupported(config.from_format, config.to_format)
         if unsupported is not None:
-            raise BlockFailure(unsupported, error_class=ErrorClass.REJECTED)
+            raise BlockFailure(UNSUPPORTED_PAIR, error_class=ErrorClass.REJECTED, **unsupported)
         source = await _read(ctx, config.source)
         try:
             produced = await self.offload(
                 lambda: self.convert(source, source_format=config.from_format, target_format=config.to_format)
             )
         except TransformError as error:
-            raise BlockFailure(str(error), error_class=ErrorClass.REJECTED) from error
+            raise BlockFailure(TRANSFORM_FAILED, error_class=ErrorClass.REJECTED, detail=str(error)) from error
         written = await _write(ctx, config.target, produced)
         return ConvertOutput(source=config.source, target=config.target, bytes_written=written)
 
-    def check_config(self, config: BaseModel) -> list[str]:
+    def check_config(self, config: BaseModel) -> list[Issue]:
         """Refuse a format pair this engine has no codec for, at apply."""
         if not isinstance(config, ConvertConfig):
             return []
-        unsupported = self._pair_refusal(config.from_format, config.to_format)
-        return [] if unsupported is None else [unsupported]
+        unsupported = self._unsupported(config.from_format, config.to_format)
+        return [] if unsupported is None else [Issue.of(UNSUPPORTED_PAIR, **unsupported)]
 
-    def _pair_refusal(self, source_format: str, target_format: str) -> str | None:
-        """Word the refusal of a pair this engine does not support, naming the ones it does."""
+    def _unsupported(self, source_format: str, target_format: str) -> JsonMap | None:
+        """Name the params of a pair this engine does not support, or nothing when it does."""
         if (source_format, target_format) in self.pairs:
             return None
         listed = ", ".join(f"{one} to {other}" for one, other in sorted(self.pairs))
-        supported = listed or "this engine converts nothing"
-        return f"{self.spec.id} does not convert {source_format} to {target_format} ({supported})"
+        return {
+            "block": self.spec.id,
+            "source_format": source_format,
+            "target_format": target_format,
+            "supported": listed or "this engine converts nothing",
+        }
 
 
 def _elements(value: JsonValue, spec_id: str, promise: str) -> list[JsonValue]:
@@ -436,8 +456,11 @@ def _elements(value: JsonValue, spec_id: str, promise: str) -> list[JsonValue]:
     if isinstance(value, list):
         return value
     raise BlockFailure(
-        f"{spec_id} {promise}, so its input has to be a JSON array, and this one is {_named(value)}",
+        NOT_AN_ARRAY,
         error_class=ErrorClass.REJECTED,
+        block=spec_id,
+        promise=promise,
+        described=_named(value),
     )
 
 
@@ -458,7 +481,7 @@ def _named(value: JsonValue) -> str:
 async def _read(ctx: StepContext, uri: str) -> bytes:
     """Read the object whole, refusing a URI that holds nothing."""
     if await ctx.storage.stat(uri) is None:
-        raise BlockFailure(f"there is nothing at {uri} to convert", error_class=ErrorClass.REJECTED)
+        raise BlockFailure(NOTHING_TO_CONVERT, error_class=ErrorClass.REJECTED, uri=uri)
     chunks: list[bytes] = []
     async for chunk in ctx.storage.open_read(uri):
         chunks.append(chunk)