dirigent-plugin 0.21.0__tar.gz → 0.23.0__tar.gz

{dirigent_plugin-0.21.0 → dirigent_plugin-0.23.0}/PKG-INFO

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

{dirigent_plugin-0.21.0 → dirigent_plugin-0.23.0}/pyproject.toml

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

{dirigent_plugin-0.21.0 → dirigent_plugin-0.23.0}/pyproject.toml.orig

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

{dirigent_plugin-0.21.0 → dirigent_plugin-0.23.0}/src/dirigent_plugin/__init__.py

@@ -3,6 +3,7 @@
 from dirigent_plugin.blocks import (
     BLOCK_ID_PATTERN,
     MARK_LIMIT,
+    REFERENCE_KEYWORD,
     SHELL_VARIABLE_PREFIX,
     SHELL_VARIABLES_FIELD,
     SURFACE_ID_PATTERN,
@@ -45,6 +46,7 @@ from dirigent_plugin.blocks import (
     classify_default,
     mark_refusal,
     merge_contributions,
+    reference_fields,
     shell_string_fields,
 )
 from dirigent_plugin.markers import (
@@ -112,6 +114,7 @@ __all__ = [
     "RunnerEngine",
     "Runs",
     "SURFACE_ID_PATTERN",
+    "REFERENCE_KEYWORD",
     "SchemaRef",
     "Sensor",
     "SensorSpec",
@@ -136,5 +139,6 @@ __all__ = [
     "formatters",
     "mark_refusal",
     "merge_contributions",
+    "reference_fields",
     "shell_string_fields",
 ]

{dirigent_plugin-0.21.0 → dirigent_plugin-0.23.0}/src/dirigent_plugin/blocks.py

@@ -16,7 +16,16 @@ 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, Issue, JsonMap, Message
+from dirigent_common import (
+    API_VERSION,
+    SHELL_MEDIA_TYPE,
+    BlockModel,
+    Catalogue,
+    HealthReport,
+    Issue,
+    JsonMap,
+    Message,
+)
 from dirigent_plugin.messages import (
     DUPLICATE_ID,
     INVALID_MARK,
@@ -138,6 +147,14 @@ class ShellString:
         return published
 
 
+#: What :class:`Reference` publishes, and what reading one back looks for.
+REFERENCE_KEYWORD: Final = "x-dirigent-ref"
+
+#: The only pointer shape a block's own config schema writes, which pydantic emits for a
+#: field whose type is a named alias.
+_LOCAL_DEFS: Final = "#/$defs/"
+
+
 class Reference:
     """Marks a config field whose value is the code of another thing this instance holds.
 
@@ -164,7 +181,7 @@ class Reference:
     ) -> JsonSchemaValue:
         """Publish what the marked field's code names, leaving what it validates untouched."""
         published = handler(schema)
-        published["x-dirigent-ref"] = self.kind
+        published[REFERENCE_KEYWORD] = self.kind
         return published
 
 
@@ -175,6 +192,55 @@ type ConnectionRef = Annotated[str, Reference("connection")]
 type SchemaRef = Annotated[str, Reference("schema")]
 
 
+def _pointed_at(shape: dict[str, Any], pool: dict[str, Any]) -> dict[str, Any] | None:
+    """The definition a local ``$ref`` names, or nothing where it names none."""
+    pointer = shape.get("$ref")
+    if not isinstance(pointer, str) or not pointer.startswith(_LOCAL_DEFS):
+        return None
+    target = pool.get(pointer.removeprefix(_LOCAL_DEFS))
+    return cast("dict[str, Any]", target) if isinstance(target, dict) else None
+
+
+def _shapes(shape: dict[str, Any], pool: dict[str, Any]) -> list[dict[str, Any]]:
+    """One field's own shape, the definition it points at, and each branch of a union."""
+    found: list[dict[str, Any]] = [shape]
+    target = _pointed_at(shape, pool)
+    if target is not None:
+        found.append(target)
+    for option in cast("list[Any]", shape.get("anyOf") or []):
+        if not isinstance(option, dict):
+            continue
+        branch = cast("dict[str, Any]", option)
+        found.append(branch)
+        pointed = _pointed_at(branch, pool)
+        if pointed is not None:
+            found.append(pointed)
+    return found
+
+
+def reference_fields(schema: JsonMap, kind: str) -> set[str]:
+    """Name the config fields a block publishes as references to one kind of thing.
+
+    A block says which of its strings hold a code, so nothing here guesses from a value: a
+    code and a value of the same shape are not told apart by looking. The marker rides on the
+    field's own shape or on the definition that shape points at, because a field typed as a
+    named alias is published as a ``$ref``.
+    """
+    properties = schema.get("properties")
+    if not isinstance(properties, dict):
+        return set()
+    held = schema.get("$defs")
+    pool = cast("dict[str, Any]", held) if isinstance(held, dict) else {}
+    named: set[str] = set()
+    for field, declared in cast("dict[str, Any]", properties).items():
+        if not isinstance(declared, dict):
+            continue
+        shapes = _shapes(cast("dict[str, Any]", declared), pool)
+        if any(one.get(REFERENCE_KEYWORD) == kind for one in shapes):
+            named.add(str(field))
+    return named
+
+
 #: What the engine names the variables it substitutes a shell string's references out into.
 SHELL_VARIABLE_PREFIX: Final = "DIRIGENT_V"
 
@@ -364,7 +430,13 @@ class ContainerResult(BaseModel):
 
 
 class AlertMessage(BaseModel):
-    """What an alert rule hands a notifier: the event, a rendered summary, and links back."""
+    """What an alert rule hands a notifier: the event, a rendered summary, and links back.
+
+    The subject and the body are the rule author's own template rendered over the run, so they
+    are that author's words in that author's language and carry no code. What dirigent itself
+    said is ``error_code`` and ``error_params``: the refusal the run ended with, which a
+    notifier with a catalogue can render in the language of wherever it delivers.
+    """
 
     event: str = Field(min_length=1)
     subject: str = Field(min_length=1)
@@ -372,6 +444,10 @@ class AlertMessage(BaseModel):
     run_id: RunId | None = None
     pipeline: str | None = None
     url: str | None = None
+    error_code: str | None = None
+    """The dotted code of the refusal the alerted run ended with, when it ended with one."""
+    error_params: dict[str, JsonValue] = Field(default_factory=dict)
+    """The specifics that refusal rendered, for a re-render in another language."""
     context: dict[str, JsonValue] = Field(default_factory=dict)
 
 
@@ -493,6 +569,10 @@ class RunSnapshot(BaseModel):
     total_steps: int = Field(default=0, ge=0)
     finished_steps: int = Field(default=0, ge=0)
     error: str | None = None
+    error_code: str | None = None
+    """The dotted code of the refusal this run ended with, when it ended with one."""
+    error_params: JsonMap = Field(default_factory=dict)
+    """The specifics that refusal rendered, for a re-render in another language."""
 
     @property
     def progress(self) -> float | None:
@@ -524,8 +604,12 @@ class Runs(Protocol):
         """Describe a run this instance holds, or return None when it holds no such run."""
         ...
 
-    async def cancel(self, run_id: RunId, *, reason: str) -> bool:
-        """Cancel a run; False means it had already settled and there was nothing to stop."""
+    async def cancel(self, run_id: RunId, reason: Message, /, **params: Any) -> bool:
+        """Cancel a run; False means it had already settled and there was nothing to stop.
+
+        The reason is a catalogued message, so the cancelled run carries a code and whoever
+        reads it renders their own sentence rather than this block's English.
+        """
         ...
 
 
@@ -575,7 +659,12 @@ class StepContext(Protocol):
         ...
 
     def schema(self, code: str) -> JsonMap:
-        """Resolve a named JSON Schema the instance holds by code; an unknown code fails the step."""
+        """Resolve one of the JSON Schemas this run holds by code; any other code fails the step.
+
+        A run holds the body of every schema its document named when it was created, so a
+        stored schema edited mid-run does not change what the rest of that run checks
+        against. A code the document does not name is not one the run holds.
+        """
         ...
 
     def format_checker(self) -> FormatChecker:
@@ -837,7 +926,7 @@ type AnySensor = Sensor[Any, Any]
 
 
 class Contribution(BaseModel):
-    """Everything one plugin adds, across all six surfaces, gathered by the host at startup."""
+    """Everything one plugin adds, across all seven surfaces, gathered by the host at startup."""
 
     model_config = ConfigDict(arbitrary_types_allowed=True, frozen=True)
 
@@ -852,6 +941,14 @@ class Contribution(BaseModel):
     ``format: <name>`` then asserts wherever the contributing pack is installed, and stays a
     passing annotation on an instance without it."""
 
+    labels: list[Catalogue] = Field(default_factory=list[Catalogue])
+    """The message catalogues this plugin refuses out of, so a surface can render its codes.
+
+    A pack's refusal reaches a browser under the pack's own code, and the browser holds no table
+    for it. Contributing the catalogue is what puts one there: the host serves every code and its
+    template, and a renderer that knows the code says its own sentence rather than repeating the
+    English this process happened to mint."""
+
     @field_validator("api_version")
     @classmethod
     def _check_api_version(cls, value: int) -> int:
@@ -868,6 +965,7 @@ class Contribution(BaseModel):
         _require_unique("notifier id", [notifier.id for notifier in self.notifiers])
         _require_unique("connection kind id", [connection.id for connection in self.connection_kinds])
         _require_unique("format", list(self.formats))
+        _require_unique("label prefix", [catalogue.prefix for catalogue in self.labels])
         return self
 
     @model_validator(mode="after")
@@ -901,6 +999,7 @@ def merge_contributions(contributions: list[Contribution]) -> Contribution:
         "storage_backends": [],
         "notifiers": [],
         "connection_kinds": [],
+        "labels": [],
     }
     for contribution in contributions:
         for surface, collected in merged.items():