dirigent-plugin 0.22.0__tar.gz → 0.23.1__tar.gz

{dirigent_plugin-0.22.0 → dirigent_plugin-0.23.1}/PKG-INFO

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

{dirigent_plugin-0.22.0 → dirigent_plugin-0.23.1}/pyproject.toml

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

{dirigent_plugin-0.22.0 → dirigent_plugin-0.23.1}/pyproject.toml.orig

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

{dirigent_plugin-0.22.0 → dirigent_plugin-0.23.1}/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.22.0 → dirigent_plugin-0.23.1}/src/dirigent_plugin/blocks.py

@@ -147,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.
 
@@ -173,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
 
 
@@ -184,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"
 
@@ -602,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: