dirigent-common 0.27.0__tar.gz → 0.28.0__tar.gz

{dirigent_common-0.27.0 → dirigent_common-0.28.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dirigent-common
-Version: 0.27.0
+Version: 0.28.0
 Summary: Value types and shared schemas every dirigent package may depend on.
 License-Expression: LicenseRef-Proprietary
 License-File: LICENSE
@@ -10,6 +10,9 @@ Requires-Dist: httpx2>=2.12.0
 Requires-Dist: jinja2>=3.1.6
 Requires-Dist: jsonschema[format-nongpl]>=4.23.0
 Requires-Dist: pydantic>=2.13.5
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: referencing>=0.37.0
+Requires-Dist: regex>=2026.9.29
 Requires-Python: >=3.13
 Description-Content-Type: text/markdown
 

{dirigent_common-0.27.0 → dirigent_common-0.28.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "dirigent-common"
-version = "0.27.0"
+version = "0.28.0"
 description = "Value types and shared schemas every dirigent package may depend on."
 readme = "README.md"
 requires-python = ">=3.13"
@@ -15,6 +15,9 @@ dependencies = [
     "jinja2>=3.1.6",
     "jsonschema[format-nongpl]>=4.23.0",
     "pydantic>=2.13.5",
+    "pyyaml>=6.0.3",
+    "referencing>=0.37.0",
+    "regex>=2026.9.29",
 ]
 
 [build-system]

{dirigent_common-0.27.0 → dirigent_common-0.28.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "dirigent-common"
-version = "0.27.0"
+version = "0.28.0"
 description = "Value types and shared schemas every dirigent package may depend on."
 readme = "README.md"
 requires-python = ">=3.13"
@@ -17,6 +17,9 @@ dependencies = [
     # GPL rfc3987 the plain format extra carries -- safe while the project's own licence is undecided.
     "jsonschema[format-nongpl]>=4.23.0",
     "pydantic>=2.13.5",
+    "pyyaml>=6.0.3",
+    "referencing>=0.37.0",
+    "regex>=2026.9.29",
 ]
 
 [build-system]

{dirigent_common-0.27.0 → dirigent_common-0.28.0}/src/dirigent_common/__init__.py

@@ -5,6 +5,7 @@ more than one package has to agree on: how a document spells a duration or a siz
 name may be, and the small schemas a plugin and the API both name.
 """
 
+from dirigent_common.bounded_yaml import BoundedLoader, YamlExpansionError, bounded_load, bounded_load_all
 from dirigent_common.clients import BaseRedirect, build_client
 from dirigent_common.docstrings import as_markdown
 from dirigent_common.durations import (
@@ -43,7 +44,16 @@ from dirigent_common.names import (
     is_step_name,
     step_name_error,
 )
-from dirigent_common.programs import JQ_MEDIA_TYPE, SHELL_MEDIA_TYPE, SQL_MEDIA_TYPE, TEMPLATE_MEDIA_TYPE
+from dirigent_common.programs import (
+    COMPOSE_MEDIA_TYPE,
+    JQ_MEDIA_TYPE,
+    SHELL_MEDIA_TYPE,
+    SQL_MEDIA_TYPE,
+    TEMPLATE_MEDIA_TYPE,
+)
+from dirigent_common.redaction import REDACTED, scrub, scrub_json, secrets_of, spellings
+from dirigent_common.schema_references import LOCAL_REFERENCES, Unresolvable
+from dirigent_common.schema_values import EvaluationOverrun, ValueValidator, bounded_evaluation
 from dirigent_common.schemas import BlockModel, HealthReport, HttpConnectionConfig
 from dirigent_common.sizes import (
     FILLER,
@@ -62,6 +72,16 @@ from dirigent_common.values import spelled
 from dirigent_common.versions import API_VERSION
 
 __all__ = [
+    "LOCAL_REFERENCES",
+    "REDACTED",
+    "BoundedLoader",
+    "EvaluationOverrun",
+    "Unresolvable",
+    "ValueValidator",
+    "bounded_evaluation",
+    "YamlExpansionError",
+    "bounded_load",
+    "bounded_load_all",
     "base_format_checker",
     "format_checker_with",
     "API_VERSION",
@@ -71,6 +91,7 @@ __all__ = [
     "EMAIL_PATTERN",
     "ENTITY_NAME_MAX_LENGTH",
     "ENTITY_NAME_PATTERN",
+    "COMPOSE_MEDIA_TYPE",
     "JQ_MEDIA_TYPE",
     "SHELL_MEDIA_TYPE",
     "SQL_MEDIA_TYPE",
@@ -115,7 +136,11 @@ __all__ = [
     "parse_duration",
     "parse_size",
     "render",
+    "scrub",
+    "scrub_json",
+    "secrets_of",
     "spelled",
+    "spellings",
     "step_name_error",
     "to_timedelta",
     "raised_detail",

dirigent_common-0.28.0/src/dirigent_common/bounded_yaml.py

@@ -0,0 +1,116 @@
+"""Reading YAML whose aliases cannot expand past a bound once something writes them out.
+
+PyYAML builds an alias as a second reference to one object, so loading a few hundred bytes of
+nested aliases is cheap, and the cost arrives later: a pydantic dump, a digest or ``json.dumps``
+walks every path and expands them to billions of values. So a document is measured before it is
+built, and refused here rather than wherever it is first written out.
+"""
+
+from typing import Any, Final, cast
+
+import yaml
+from pydantic import BaseModel
+
+from dirigent_common.messages import (
+    YAML_ALIAS_CYCLE,
+    YAML_ALIASES_EXPAND_TOO_FAR,
+    YAML_ALIASES_WRITE_TOO_MUCH,
+    YAML_NESTED_TOO_DEEP,
+)
+
+#: How many values a YAML stream's aliases may add once each is written out in place.
+ALIAS_EXPANSION_LIMIT: Final = 100_000
+
+#: How many bytes of scalar text a YAML stream's aliases may add once each is written out in place.
+ALIAS_EXPANSION_BYTES: Final = 16 * 1024 * 1024
+
+
+class YamlExpansionError(yaml.YAMLError):
+    """A YAML stream's aliases go past a bound, a node contains itself, or it nests too deeply."""
+
+
+class _Added(BaseModel):
+    """What the aliases of a YAML stream add once written out, across its documents so far."""
+
+    values: int = 0
+    scalar_bytes: int = 0
+
+
+class BoundedLoader(yaml.SafeLoader):
+    """The safe loader, refusing a document before it is built when its aliases expand too far.
+
+    A document is refused when the aliases of the stream so far would add more than
+    ``ALIAS_EXPANSION_LIMIT`` values or ``ALIAS_EXPANSION_BYTES`` bytes of scalar text once
+    written out. A document's own text is not counted: it is already in the input.
+    """
+
+    def __init__(self, stream: str) -> None:
+        """Start the stream with nothing added by its aliases."""
+        super().__init__(stream)
+        self.added = _Added()
+
+    def construct_document(self, node: yaml.Node) -> Any:
+        """Build the document once its written-out size is known to be bounded."""
+        _hold_expansion(node, self.added)
+        return super().construct_document(node)  # pyright: ignore[reportUnknownMemberType]
+
+
+def _scalar_bytes(node: yaml.Node) -> int:
+    """How many bytes of text one node itself holds, which is nothing unless it is a scalar."""
+    if not isinstance(node, yaml.ScalarNode):
+        return 0
+    return len(cast("str", node.value).encode(errors="replace"))
+
+
+def _hold_expansion(root: yaml.Node, added: _Added) -> None:
+    """Refuse a node graph whose aliases take the stream past a limit, or that contains itself."""
+    sizes: dict[int, tuple[int, int]] = {}
+    open_nodes: set[int] = set()
+    distinct_bytes = 0
+
+    def size(node: yaml.Node) -> tuple[int, int]:
+        nonlocal distinct_bytes
+        key = id(node)
+        if key in sizes:
+            return sizes[key]
+        if key in open_nodes:
+            raise YamlExpansionError(YAML_ALIAS_CYCLE.render())
+        open_nodes.add(key)
+        children: list[yaml.Node] = []
+        if isinstance(node, yaml.SequenceNode):
+            children = cast("list[yaml.Node]", node.value)
+        elif isinstance(node, yaml.MappingNode):
+            pairs = cast("list[tuple[yaml.Node, yaml.Node]]", node.value)
+            children = [child for pair in pairs for child in pair]
+        measured = [size(child) for child in children]
+        own = _scalar_bytes(node)
+        values = 1 + sum(child[0] for child in measured)
+        scalar_bytes = own + sum(child[1] for child in measured)
+        open_nodes.discard(key)
+        sizes[key] = (values, scalar_bytes)
+        distinct_bytes += own
+        if added.values + values - len(sizes) > ALIAS_EXPANSION_LIMIT:
+            raise YamlExpansionError(YAML_ALIASES_EXPAND_TOO_FAR.render(limit=f"{ALIAS_EXPANSION_LIMIT:,}"))
+        if added.scalar_bytes + scalar_bytes - distinct_bytes > ALIAS_EXPANSION_BYTES:
+            raise YamlExpansionError(YAML_ALIASES_WRITE_TOO_MUCH.render(limit=f"{ALIAS_EXPANSION_BYTES:,}"))
+        return sizes[key]
+
+    values, scalar_bytes = size(root)
+    added.values += values - len(sizes)
+    added.scalar_bytes += scalar_bytes - distinct_bytes
+
+
+def bounded_load(text: str, loader: type[BoundedLoader] = BoundedLoader) -> Any:
+    """Read one YAML document, refusing what expands too far or nests past Python's own stack."""
+    try:
+        return yaml.load(text, Loader=loader)  # noqa: S506 - a BoundedLoader is a SafeLoader
+    except RecursionError as error:
+        raise YamlExpansionError(YAML_NESTED_TOO_DEEP.render()) from error
+
+
+def bounded_load_all(text: str, loader: type[BoundedLoader] = BoundedLoader) -> list[Any]:
+    """Read every document of a YAML stream under one bound, refusing as ``bounded_load`` does."""
+    try:
+        return list(yaml.load_all(text, Loader=loader))  # noqa: S506 - a BoundedLoader is a SafeLoader
+    except RecursionError as error:
+        raise YamlExpansionError(YAML_NESTED_TOO_DEEP.render()) from error

dirigent_common-0.28.0/src/dirigent_common/hosts.py

@@ -0,0 +1,13 @@
+"""What a host name says about where it reaches."""
+
+import ipaddress
+
+
+def is_loopback_host(host: str) -> bool:
+    """Whether a host names this machine alone: ``localhost`` or a loopback address, and nothing else."""
+    if host == "localhost":
+        return True
+    try:
+        return ipaddress.ip_address(host).is_loopback
+    except ValueError:
+        return False

{dirigent_common-0.27.0 → dirigent_common-0.28.0}/src/dirigent_common/messages.py

@@ -6,12 +6,13 @@ code and render the same refusal in another language without anything else chang
 """
 
 import re
-from collections.abc import Mapping, Sequence
+from collections.abc import Collection, Mapping, Sequence
 from string import Formatter
 from typing import Any, ClassVar, Final, Self
 
 from pydantic import BaseModel, ConfigDict, Field
 
+from dirigent_common.redaction import scrub
 from dirigent_common.types import JsonMap
 
 #: A message name: lowercase words joined by underscores, and dotted where a family of
@@ -155,6 +156,25 @@ TEMPLATE_FAILED = COMMON.define("template_failed", "{detail}")
 
 NO_JSON_SPELLING = COMMON.define("no_json_spelling", "a value of type {kind} has no JSON spelling")
 
+YAML_ALIASES_EXPAND_TOO_FAR = COMMON.define(
+    "yaml_aliases_expand_too_far",
+    "the YAML's aliases would add more than {limit} values once each is written out; "
+    "write the repeated parts out in the source, or repeat them less",
+)
+
+YAML_ALIASES_WRITE_TOO_MUCH = COMMON.define(
+    "yaml_aliases_write_too_much",
+    "the YAML's aliases would add more than {limit} bytes of text once each is written out; "
+    "write the repeated parts out in the source, or repeat them less",
+)
+
+YAML_ALIAS_CYCLE = COMMON.define(
+    "yaml_alias_cycle",
+    "the YAML holds an alias inside the node it names, and a value cannot be written out that contains itself",
+)
+
+YAML_NESTED_TOO_DEEP = COMMON.define("yaml_nested_too_deep", "the YAML nests too deeply to be read")
+
 VALIDATION = Catalogue("validation")
 
 #: Pydantic names the condition, so the second half of a validation code is its own error
@@ -166,6 +186,11 @@ _PYDANTIC_TEXT: Final = "{msg}"
 #: closest to when the document format knows one.
 EXTRA_FORBIDDEN = VALIDATION.define("extra_forbidden", "unknown key{suggestion}")
 
+#: Text a caller wrote that no database stores as written, refused where it arrives.
+TEXT_UNSTORABLE = VALIDATION.define(
+    "text_unstorable", "holds a NUL character or half a surrogate pair, which cannot be stored; remove it"
+)
+
 
 def _validation_message(error_type: str) -> Message:
     """Name the message one pydantic error type renders through, minting it on first sight."""
@@ -198,15 +223,16 @@ def validation_issues(errors: Sequence[Mapping[str, Any]]) -> list[Issue]:
 RAISED_DETAIL_CHARS: Final = 2000
 
 
-def raised_detail(error: Exception) -> str:
+def raised_detail(error: Exception, *, redact: Collection[str] = ()) -> str:
     """Say what an exception said about itself, falling back to its class when it said nothing.
 
     A Python class name is not a sentence anybody wrote, so it is the last thing left to say
     rather than the first thing said. What comes back is an operator's detail: it belongs in a
     log, in a refusal's params, or in the ``{detail}`` of a message that supplies the sentence
-    around it, and never alone in front of a person.
+    around it, and never alone in front of a person. ``redact`` is scrubbed before the cut, which
+    would otherwise leave a long secret too short to be found.
     """
-    detail = str(error).strip() or type(error).__name__
+    detail = scrub(str(error).strip(), redact) or type(error).__name__
     if len(detail) > RAISED_DETAIL_CHARS:
         return f"{detail[:RAISED_DETAIL_CHARS]} [truncated, {len(detail)} characters]"
     return detail

{dirigent_common-0.27.0 → dirigent_common-0.28.0}/src/dirigent_common/programs.py

@@ -11,5 +11,10 @@ SHELL_MEDIA_TYPE: Final = "text/x-shellscript"
 #: A Jinja template rendering text, as the run report and ``report.render`` take one.
 TEMPLATE_MEDIA_TYPE: Final = "text/x-jinja"
 
-#: One SQL statement, as ``sql.query`` takes one.
+#: A compose file, as ``docker.compose.up`` and ``docker.compose.down`` take one inline. A field
+#: publishing this takes no ``${...}`` reference, at apply or at run.
+COMPOSE_MEDIA_TYPE: Final = "application/x-compose+yaml"
+
+#: One SQL statement, as ``sql.query`` and ``sql.execute`` take one. A field publishing this
+#: takes no ``${...}`` reference, at apply or at run.
 SQL_MEDIA_TYPE: Final = "application/sql"

dirigent_common-0.28.0/src/dirigent_common/redaction.py

@@ -0,0 +1,64 @@
+"""Keeping a sealed value out of text somebody else reads.
+
+An exception says what it was handed, and an HTTP library refusing a header value says it whole.
+Whatever writes such text beside a viewer's reach scrubs it first, with every spelling the value
+takes once a library has quoted it.
+"""
+
+from collections.abc import Collection
+from typing import Final
+
+from pydantic import BaseModel, JsonValue, SecretStr
+
+#: What a scrubbed secret is replaced by, matching the marker the API redacts a connection with.
+REDACTED: Final = "***"
+
+
+def spellings(secret: str) -> set[str]:
+    """Name every way a secret reads in an error: as it is, trimmed, and escaped as ``repr`` escapes it."""
+    written = {
+        secret,
+        secret.strip(),
+        repr(secret)[1:-1],
+        repr(secret.strip())[1:-1],
+        repr(secret.encode("utf-8", "surrogateescape"))[2:-1],
+    }
+    return {one for one in written if one}
+
+
+def secrets_of(config: BaseModel) -> set[str]:
+    """Name every spelling of every secret an opened config holds."""
+    found: set[str] = set()
+    for name in type(config).model_fields:
+        value = getattr(config, name, None)
+        if isinstance(value, SecretStr):
+            found |= spellings(value.get_secret_value())
+    return found
+
+
+def scrub(text: str, secrets: Collection[str] = ()) -> str:
+    """Replace every occurrence of a secret with the redaction marker.
+
+    A tool prints what it was given. ``git`` echoes a remote URL, an ssh command line and,
+    when a credential is wrong, sometimes the credential itself, so a block that hands a
+    process a secret hands this the same strings and nothing reaches a log or a failure
+    message with them still in it. Longest first, so a secret that contains another is
+    replaced whole rather than left in pieces.
+    """
+    for secret in sorted((one for one in secrets if one), key=len, reverse=True):
+        text = text.replace(secret, REDACTED)
+    return text
+
+
+def scrub_json(value: JsonValue, secrets: Collection[str]) -> JsonValue:
+    """Scrub every string in a JSON value, its keys included."""
+    if isinstance(value, str):
+        return scrub(value, secrets)
+    if isinstance(value, list):
+        return [scrub_json(element, secrets) for element in value]
+    if isinstance(value, dict):
+        return {scrub(key, secrets): scrub_json(element, secrets) for key, element in value.items()}
+    return value
+
+
+__all__ = ["REDACTED", "scrub", "scrub_json", "secrets_of", "spellings"]

dirigent_common-0.28.0/src/dirigent_common/schema_references.py

@@ -0,0 +1,16 @@
+"""Where a JSON Schema ``$ref`` may lead: into its own document and the drafts the library ships.
+
+A validator built without a registry retrieves a ``$ref`` it cannot resolve over HTTP, on
+whichever process is validating. A schema is written by whoever can apply a document, so that
+is a request from the server's network to an address they chose. Every validator here is built
+with this registry, which retrieves nothing; the library adds its bundled metaschemas to it.
+"""
+
+from typing import Any, Final
+
+from referencing import Registry
+from referencing.exceptions import Unresolvable
+
+LOCAL_REFERENCES: Final[Registry[Any]] = Registry()
+
+__all__ = ["LOCAL_REFERENCES", "Unresolvable"]

dirigent_common-0.28.0/src/dirigent_common/schema_values.py

@@ -0,0 +1,318 @@
+"""The validator a run's values are checked with, and the bound every evaluation runs under.
+
+Draft 2020-12, saying what the library says, with these differences in how:
+
+* ``uniqueItems`` compares each element's canonical text through a set, under JSON Schema's rule
+  of equality: ``1`` and ``1.0`` are equal, ``true`` and ``1`` are not, and an object's keys have
+  no order.
+* ``unevaluatedItems`` and ``unevaluatedProperties`` look up what was evaluated in a set.
+* ``pattern``, ``patternProperties``, and the patterns ``additionalProperties`` and
+  ``unevaluatedProperties`` read match with the ``regex`` package in its ``re``-compatible mode,
+  which releases the interpreter's lock while it matches and stops at the evaluation's deadline.
+* Every keyword checks the bound :func:`bounded_evaluation` sets before it runs, and raises
+  :class:`EvaluationOverrun` once the deadline has passed or the caller has stopped waiting.
+
+Outside :func:`bounded_evaluation` nothing is bounded.
+"""
+
+import json
+import threading
+import time
+from collections.abc import Callable, Generator, Iterator
+from contextlib import contextmanager
+from contextvars import ContextVar
+from datetime import timedelta
+from functools import lru_cache
+from typing import Any, Final
+
+import regex
+from jsonschema import Draft202012Validator, ValidationError
+from jsonschema.validators import extend as extend_validator  # pyright: ignore[reportUnknownVariableType]
+from pydantic import JsonValue
+
+from dirigent_common.durations import format_duration
+
+#: The keyword signature the library calls: validator, the keyword's value, instance, schema.
+type Keyword = Callable[[Any, Any, Any, Any], Any]
+
+
+class EvaluationOverrun(Exception):
+    """An evaluation that passed its deadline, or whose caller stopped waiting for it."""
+
+    def __init__(self, within: timedelta) -> None:
+        """Name the bound the evaluation passed."""
+        super().__init__(f"the evaluation did not finish within {format_duration(within)}")
+        self.within = within
+
+
+class _Bound:
+    """When the current evaluation must stop, and the event that stops it sooner."""
+
+    __slots__ = ("deadline", "stopped", "within")
+
+    def __init__(self, within: timedelta, stopped: threading.Event | None) -> None:
+        self.within = within
+        self.deadline = time.monotonic() + within.total_seconds()
+        self.stopped = stopped
+
+
+_BOUND: ContextVar[_Bound | None] = ContextVar("dirigent_schema_value_bound", default=None)
+
+
+@contextmanager
+def bounded_evaluation(within: timedelta, stopped: threading.Event | None = None) -> Generator[None]:
+    """Bound every evaluation inside the block to ``within``, and to ``stopped`` staying unset.
+
+    The bound is held in a context variable, so it covers the thread or task that entered the
+    block and nothing else.
+    """
+    token = _BOUND.set(_Bound(within, stopped))
+    try:
+        yield
+    finally:
+        _BOUND.reset(token)
+
+
+def _remaining(bound: _Bound | None) -> float | None:
+    """Seconds an evaluation under ``bound`` has left, or None when it is unbounded.
+
+    Raises:
+        EvaluationOverrun: The deadline has passed, or the caller has stopped waiting.
+    """
+    if bound is None:
+        return None
+    left = bound.deadline - time.monotonic()
+    if left <= 0 or (bound.stopped is not None and bound.stopped.is_set()):
+        raise EvaluationOverrun(bound.within)
+    return left
+
+
+@lru_cache(maxsize=512)
+def _compiled(pattern: str) -> "regex.Pattern[str]":
+    """Compile a schema's pattern with ``re``'s syntax and meaning."""
+    return regex.compile(pattern, regex.VERSION0)
+
+
+def _found(pattern: str, text: str) -> bool:
+    """Whether ``pattern`` matches anywhere in ``text``, within what the evaluation has left.
+
+    The match releases the interpreter's lock while it runs.
+    """
+    bound = _BOUND.get()
+    left = _remaining(bound)
+    try:
+        return _compiled(pattern).search(text, concurrent=True, timeout=left) is not None
+    except TimeoutError as error:
+        raise EvaluationOverrun(bound.within if bound is not None else timedelta(0)) from error
+
+
+def canonical_json(value: JsonValue) -> str:
+    """Write a JSON value so two values have the same text exactly when JSON Schema calls them equal."""
+    if isinstance(value, float) and value.is_integer():
+        return str(int(value))
+    if isinstance(value, list):
+        return "[" + ",".join(canonical_json(element) for element in value) + "]"
+    if isinstance(value, dict):
+        members = sorted(f"{json.dumps(key)}:{canonical_json(element)}" for key, element in value.items())
+        return "{" + ",".join(members) + "}"
+    return json.dumps(value)
+
+
+def _extras(extras: list[Any]) -> tuple[str, str]:
+    """The library's wording for the items or properties a keyword did not expect."""
+    return ", ".join(repr(extra) for extra in extras), "was" if len(extras) == 1 else "were"
+
+
+def _unique_items(validator: Any, wanted: Any, instance: Any, schema: Any) -> Iterator[ValidationError]:
+    """Say what the library's ``uniqueItems`` says, comparing through a set of canonical text."""
+    if not wanted or not validator.is_type(instance, "array"):
+        return
+    seen: set[str] = set()
+    for element in instance:
+        text = canonical_json(element)
+        if text in seen:
+            yield ValidationError(f"{instance!r} has non-unique elements")
+            return
+        seen.add(text)
+
+
+def _pattern(validator: Any, pattern: str, instance: Any, schema: Any) -> Iterator[ValidationError]:
+    """Say what the library's ``pattern`` says."""
+    if validator.is_type(instance, "string") and not _found(pattern, instance):
+        yield ValidationError(f"{instance!r} does not match {pattern!r}")
+
+
+def _pattern_properties(validator: Any, patterns: Any, instance: Any, schema: Any) -> Iterator[ValidationError]:
+    """Say what the library's ``patternProperties`` says."""
+    if not validator.is_type(instance, "object"):
+        return
+    for pattern, subschema in patterns.items():
+        for key, value in instance.items():
+            if _found(pattern, key):
+                yield from validator.descend(value, subschema, path=key, schema_path=pattern)
+
+
+def _additional(instance: Any, schema: Any) -> list[str]:
+    """The keys of ``instance`` neither ``properties`` nor ``patternProperties`` names, in order."""
+    properties = schema.get("properties", {})
+    patterns = list(schema.get("patternProperties", {}))
+    return [key for key in instance if key not in properties and not any(_found(pattern, key) for pattern in patterns)]
+
+
+def _additional_properties(validator: Any, extra: Any, instance: Any, schema: Any) -> Iterator[ValidationError]:
+    """Say what the library's ``additionalProperties`` says."""
+    if not validator.is_type(instance, "object"):
+        return
+    extras = set(_additional(instance, schema))
+    if validator.is_type(extra, "object"):
+        for key in extras:
+            yield from validator.descend(instance[key], extra, path=key)
+    elif not extra and extras:
+        if "patternProperties" in schema:
+            verb = "does" if len(extras) == 1 else "do"
+            joined = ", ".join(repr(key) for key in sorted(extras))
+            patterns = ", ".join(repr(pattern) for pattern in sorted(schema["patternProperties"]))
+            yield ValidationError(f"{joined} {verb} not match any of the regexes: {patterns}")
+        else:
+            listed, verb = _extras(sorted(extras, key=str))
+            yield ValidationError(f"Additional properties are not allowed ({listed} {verb} unexpected)")
+
+
+def _referenced(validator: Any, schema: Any) -> Iterator[tuple[Any, Any]]:
+    """The validator and schema each of ``$ref`` and ``$dynamicRef`` in ``schema`` leads to."""
+    for keyword in ("$ref", "$dynamicRef"):
+        reference = schema.get(keyword)
+        if reference is not None:
+            resolved = validator._resolver.lookup(reference)
+            yield validator.evolve(schema=resolved.contents, _resolver=resolved.resolver), resolved.contents
+
+
+def _is_valid(errors: Iterator[ValidationError]) -> bool:
+    """Whether an iterator of errors yields none."""
+    return next(errors, None) is None
+
+
+def _evaluated_indexes(validator: Any, instance: Any, schema: Any) -> set[int]:
+    """The indexes of ``instance`` that ``schema`` evaluates, as the library finds them."""
+    if validator.is_type(schema, "boolean"):
+        return set()
+    if "items" in schema:
+        return set(range(len(instance)))
+    evaluated: set[int] = set()
+    for referred, contents in _referenced(validator, schema):
+        evaluated |= _evaluated_indexes(referred, instance, contents)
+    if "prefixItems" in schema:
+        evaluated.update(range(len(schema["prefixItems"])))
+    if "if" in schema:
+        if validator.evolve(schema=schema["if"]).is_valid(instance):
+            evaluated |= _evaluated_indexes(validator, instance, schema["if"])
+            if "then" in schema:
+                evaluated |= _evaluated_indexes(validator, instance, schema["then"])
+        elif "else" in schema:
+            evaluated |= _evaluated_indexes(validator, instance, schema["else"])
+    for keyword in ("contains", "unevaluatedItems"):
+        if keyword in schema:
+            checker = validator.evolve(schema=schema[keyword])
+            evaluated.update(index for index, item in enumerate(instance) if checker.is_valid(item))
+    for keyword in ("allOf", "oneOf", "anyOf"):
+        for subschema in schema.get(keyword, ()):
+            if _is_valid(validator.descend(instance, subschema)):
+                evaluated |= _evaluated_indexes(validator, instance, subschema)
+    return evaluated
+
+
+def _evaluated_keys(validator: Any, instance: Any, schema: Any) -> set[str]:
+    """The keys of ``instance`` that ``schema`` evaluates, as the library finds them."""
+    if validator.is_type(schema, "boolean"):
+        return set()
+    evaluated: set[str] = set()
+    for referred, contents in _referenced(validator, schema):
+        evaluated |= _evaluated_keys(referred, instance, contents)
+    properties = schema.get("properties")
+    if validator.is_type(properties, "object"):
+        evaluated |= properties.keys() & instance.keys()
+    for keyword in ("additionalProperties", "unevaluatedProperties"):
+        subschema = schema.get(keyword)
+        if subschema is not None:
+            evaluated.update(key for key, value in instance.items() if _is_valid(validator.descend(value, subschema)))
+    if "patternProperties" in schema:
+        patterns = list(schema["patternProperties"])
+        evaluated.update(key for key in instance if any(_found(pattern, key) for pattern in patterns))
+    for key, subschema in schema.get("dependentSchemas", {}).items():
+        if key in instance:
+            evaluated |= _evaluated_keys(validator, instance, subschema)
+    for keyword in ("allOf", "oneOf", "anyOf"):
+        for subschema in schema.get(keyword, ()):
+            if _is_valid(validator.descend(instance, subschema)):
+                evaluated |= _evaluated_keys(validator, instance, subschema)
+    if "if" in schema:
+        if validator.evolve(schema=schema["if"]).is_valid(instance):
+            evaluated |= _evaluated_keys(validator, instance, schema["if"])
+            if "then" in schema:
+                evaluated |= _evaluated_keys(validator, instance, schema["then"])
+        elif "else" in schema:
+            evaluated |= _evaluated_keys(validator, instance, schema["else"])
+    return evaluated
+
+
+def _unevaluated_items(validator: Any, unevaluated: Any, instance: Any, schema: Any) -> Iterator[ValidationError]:
+    """Say what the library's ``unevaluatedItems`` says."""
+    if not validator.is_type(instance, "array"):
+        return
+    evaluated = _evaluated_indexes(validator, instance, schema)
+    left = [item for index, item in enumerate(instance) if index not in evaluated]
+    if left:
+        listed, verb = _extras(left)
+        yield ValidationError(f"Unevaluated items are not allowed ({listed} {verb} unexpected)")
+
+
+def _unevaluated_properties(validator: Any, unevaluated: Any, instance: Any, schema: Any) -> Iterator[ValidationError]:
+    """Say what the library's ``unevaluatedProperties`` says."""
+    if not validator.is_type(instance, "object"):
+        return
+    evaluated = _evaluated_keys(validator, instance, schema)
+    refused: list[str] = []
+    for key in instance:
+        if key not in evaluated:
+            refused.extend(key for _ in validator.descend(instance[key], unevaluated, path=key, schema_path=key))
+    if not refused:
+        return
+    if unevaluated is False:
+        listed, verb = _extras(sorted(refused, key=str))
+        yield ValidationError(f"Unevaluated properties are not allowed ({listed} {verb} unexpected)")
+    else:
+        listed, verb = _extras(refused)
+        yield ValidationError(
+            f"Unevaluated properties are not valid under the given schema ({listed} {verb} unevaluated and invalid)"
+        )
+
+
+def _watched(keyword: Keyword) -> Keyword:
+    """Run ``keyword`` only while the evaluation's bound holds."""
+
+    def watched(validator: Any, value: Any, instance: Any, schema: Any) -> Any:
+        _remaining(_BOUND.get())
+        return keyword(validator, value, instance, schema)
+
+    return watched
+
+
+_KEYWORDS: Final[dict[str, Keyword]] = {
+    **Draft202012Validator.VALIDATORS,
+    "additionalProperties": _additional_properties,
+    "pattern": _pattern,
+    "patternProperties": _pattern_properties,
+    "unevaluatedItems": _unevaluated_items,
+    "unevaluatedProperties": _unevaluated_properties,
+    "uniqueItems": _unique_items,
+}
+
+#: Draft 2020-12 with those keywords. Naming the version also makes this the class a subschema
+#: naming that ``$schema`` resolves to, which a ``$ref`` back to the root would be.
+ValueValidator: Final[Any] = extend_validator(  # pyright: ignore[reportUnknownVariableType]
+    Draft202012Validator,
+    {name: _watched(keyword) for name, keyword in _KEYWORDS.items()},
+    version="draft2020-12",
+)
+
+__all__ = ["EvaluationOverrun", "ValueValidator", "bounded_evaluation", "canonical_json"]

dirigent_common-0.28.0/src/dirigent_common/storable.py

@@ -0,0 +1,55 @@
+"""Text a database stores as written: no NUL, and no half of a surrogate pair.
+
+PostgreSQL refuses a NUL in text and in JSONB, and no driver encodes half a pair, so text a
+caller writes holding either is refused where it arrives rather than when it is written.
+"""
+
+import re
+from typing import Final, cast
+
+from pydantic_core import PydanticCustomError
+
+from dirigent_common.messages import TEXT_UNSTORABLE
+
+#: The pydantic error type the refusal is raised as, which names its catalogued message.
+UNSTORABLE_KIND: Final = "text_unstorable"
+
+#: A NUL, or half a surrogate pair, which JSON and YAML escapes both reach.
+UNSTORABLE: Final = re.compile("[\x00\ud800-\udfff]")
+
+
+def is_storable(text: str) -> bool:
+    """Report whether a database stores this text as written."""
+    return UNSTORABLE.search(text) is None
+
+
+def refuse_unstorable[T](value: T) -> T:
+    """Pass a value through, refusing text no database stores as written."""
+    if isinstance(value, str) and not is_storable(value):
+        raise PydanticCustomError(UNSTORABLE_KIND, "{sentence}", {"sentence": TEXT_UNSTORABLE.text})
+    return value
+
+
+def unstorable_at(value: object, at: tuple[str | int, ...] = ()) -> list[str]:
+    """Name every place in a parsed document whose key or text no database stores as written.
+
+    A key that holds one is named by the mapping it is in, and what is under it is not read.
+    """
+    if isinstance(value, str):
+        return [] if is_storable(value) else [_where(at)]
+    found: list[str] = []
+    if isinstance(value, dict):
+        for key, inner in cast("dict[object, object]", value).items():
+            if not is_storable(str(key)):
+                found.append(_where(at))
+                continue
+            found.extend(unstorable_at(inner, (*at, str(key))))
+    elif isinstance(value, list):
+        for index, inner in enumerate(cast("list[object]", value)):
+            found.extend(unstorable_at(inner, (*at, index)))
+    return found
+
+
+def _where(at: tuple[str | int, ...]) -> str:
+    """Spell a place in a document the way a validation issue does."""
+    return ".".join(str(part) for part in at) or "(document)"