pirn-core 0.4.0__py3-none-any.whl

pirn/__init__.py

@@ -0,0 +1,92 @@
+"""pirn — a pipeline framework where everything is a knot.
+
+Knot discovery
+--------------
+At import time, pirn calls :meth:`sweet_tea.registry.Registry.fill_registry`
+over its own package tree. Every :class:`pirn.core.knot.Knot` subclass shipped
+with pirn is auto-registered under ``library="pirn"`` with the lowercase
+class name as its registry key (CamelCase, snake_case, and no-underscore
+variations all resolve to the same entry through sweet_tea's
+:meth:`BaseFactory._generate_key_variations`).
+
+This means YAML pipelines can reference any built-in pirn knot by name
+without ``import`` boilerplate::
+
+    nodes:
+      - id: read
+        callable: object_store_read_source
+
+YAML name resolution goes through
+:class:`sweet_tea.abstract_inverter_factory.AbstractInverterFactory[Knot]`
+— sweet_tea's typed factory that returns the class definition (rather than
+instantiating it), so the loader can supply construction kwargs later.
+
+User projects: register your own knots
+--------------------------------------
+If you define your own :class:`Knot` subclasses outside the pirn package
+(e.g. ``my_company.transforms.NormaliseAddresses``), call
+:meth:`Registry.fill_registry` from **your** project's package init so your
+classes are auto-discovered too::
+
+    # my_company/__init__.py
+    from sweet_tea.registry import Registry
+
+    Registry.fill_registry()  # scans my_company/ and registers every class
+
+After that, your knots are resolvable by name from YAML pipelines just like
+pirn's built-ins. To restrict resolution to your library only, look up via
+``AbstractInverterFactory[Knot].create(name, library="my_company")``.
+"""
+
+import warnings
+from importlib.metadata import PackageNotFoundError, version
+
+from sweet_tea.registry import Registry
+from sweet_tea.sweet_tea_warning import SweetTeaWarning
+
+with warnings.catch_warnings():
+    warnings.simplefilter("ignore", SweetTeaWarning)
+    Registry.fill_registry()
+
+try:
+    # Core ships as the ``pirn-core`` distribution but imports as ``pirn``.
+    __version__ = version("pirn-core")
+except PackageNotFoundError:
+    __version__ = "unknown"
+
+# Public API re-exports — users may import from pirn directly.
+# Registry.fill_registry() above must run first; noqa: E402 suppresses the
+# "import not at top of file" warnings that follow from that ordering.
+from pirn._domain_discovery import discover_installed_domains
+from pirn.core.assembler import Assembler
+from pirn.core.disassembler import Disassembler
+from pirn.core.error_policy import ErrorPolicy
+from pirn.core.knot import Knot
+from pirn.core.knot_config import KnotConfig
+from pirn.core.knot_factory import knot
+from pirn.core.parameter import Parameter
+from pirn.core.run_request import RunRequest
+from pirn.core.run_result import RunResult
+from pirn.nodes.loop_sub_tapestry import LoopSubTapestry
+from pirn.nodes.sink import Sink
+from pirn.nodes.source import Source
+from pirn.nodes.sub_tapestry import SubTapestry
+from pirn.tapestry import Tapestry
+
+__all__ = [
+    "Tapestry",
+    "Knot",
+    "KnotConfig",
+    "knot",
+    "Parameter",
+    "RunRequest",
+    "RunResult",
+    "ErrorPolicy",
+    "Assembler",
+    "Disassembler",
+    "Sink",
+    "Source",
+    "SubTapestry",
+    "LoopSubTapestry",
+    "discover_installed_domains",
+]

pirn/_domain_discovery.py

@@ -0,0 +1,83 @@
+"""Discover and import installed pirn domain packages.
+
+Domains ship as standalone distributions (``pirn-signal``, ``pirn-data`` …)
+whose import packages are ``pirn_signal``, ``pirn_data`` … Importing each one
+triggers its ``Registry.fill_registry()`` self-registration, making its knots
+resolvable by bare name through sweet_tea's factory. This module finds which
+domain distributions are installed and imports the corresponding packages.
+"""
+
+from __future__ import annotations
+
+import importlib
+from importlib.metadata import distributions
+from importlib.util import find_spec
+
+
+class _DomainDiscovery:
+    """Locate installed pirn domain import-packages and import them.
+
+    The six domain names are fixed framework data, kept as an instance
+    attribute rather than a module constant. ``pirn`` (core) is intentionally
+    excluded — it self-registers on its own import.
+    """
+
+    def __init__(self) -> None:
+        self._domains: tuple[str, ...] = (
+            "agents",
+            "data",
+            "health",
+            "ml",
+            "oilgas",
+            "signal",
+        )
+
+    def installed_import_names(self) -> tuple[str, ...]:
+        """Return the ``pirn_<x>`` import names whose distribution is installed.
+
+        Introspects installed distributions via
+        :func:`importlib.metadata.distributions`, matching the canonical
+        ``pirn-<domain>`` distribution names, then keeps only those whose
+        import package is actually resolvable on ``sys.path``.
+        """
+        wanted = {f"pirn-{domain}": f"pirn_{domain}" for domain in self._domains}
+        found: set[str] = set()
+        for dist in distributions():
+            dist_name = dist.metadata["Name"]
+            if dist_name is None:
+                continue
+            normalized = dist_name.replace("_", "-").lower()
+            import_name = wanted.get(normalized)
+            if import_name is not None and find_spec(import_name) is not None:
+                found.add(import_name)
+        return tuple(sorted(found))
+
+    def discover(self) -> tuple[str, ...]:
+        """Import every installed domain package; return what was imported.
+
+        Idempotent — re-importing an already-imported module is a no-op.
+        Genuine import errors are not swallowed: they propagate wrapped in an
+        :class:`ImportError` that names the offending package for context.
+        """
+        imported: list[str] = []
+        for import_name in self.installed_import_names():
+            try:
+                importlib.import_module(import_name)
+            except ImportError as exc:
+                raise ImportError(
+                    f"failed to import discovered pirn domain {import_name!r}: {exc}"
+                ) from exc
+            imported.append(import_name)
+        return tuple(imported)
+
+
+def discover_installed_domains() -> tuple[str, ...]:
+    """Import all installed pirn domain packages and return their import names.
+
+    Each imported ``pirn_<x>`` package self-registers its knots via
+    ``Registry.fill_registry()``, so after this call their knots resolve by
+    bare name through sweet_tea's factory (the same path the YAML loader
+    uses). Returns the sorted tuple of import names that were imported. Safe
+    to call repeatedly.
+    """
+    return _DomainDiscovery().discover()

pirn/_migrate/__init__.py

@@ -0,0 +1,13 @@
+"""Import-compatibility codemod for the pirn monolith split (SCD-17).
+
+When pirn was a monolith the six domains lived under ``pirn.domains.<x>``.
+They are now standalone packages that import as ``pirn_<x>`` (for x in
+signal, oilgas, data, ml, agents, health). This package ships a reusable,
+idempotent, deterministic line-based rewriter that updates consumer source
+from the old ``pirn.domains.<x>`` spellings to the new ``pirn_<x>`` ones.
+
+It is exposed to end users as the ``pirn-migrate-imports`` console script
+(see ``pirn._migrate.main``) and reused as the migration tool in SCD-23.
+"""
+
+from __future__ import annotations

pirn/_migrate/import_rewriter.py

@@ -0,0 +1,110 @@
+"""Line-based rewriter for the ``pirn.domains.<x>`` -> ``pirn_<x>`` split.
+
+See :mod:`pirn._migrate` for background. The rewriter is a pure text
+transform: it operates line by line on ``.py`` source, only ever touching
+``import`` / ``from ... import`` statements that reference one of the six
+known domains, and otherwise preserves formatting, indentation and comments
+byte-for-byte. It is idempotent (a rewritten file is a fixed point) and
+deterministic (identical input always yields identical output).
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+
+class ImportRewriter:
+    """Rewrites legacy ``pirn.domains.<x>`` imports to ``pirn_<x>``.
+
+    The set of domains is fixed framework data (the monolith carved out
+    exactly these six packages), so it is stored as a lowercase class
+    attribute rather than a configurable constant. Only these names are
+    ever rewritten; any other ``pirn.domains.<other>`` reference (e.g.
+    ``pirn.domains.extras_loader``) is left untouched.
+    """
+
+    _domains: tuple[str, ...] = (
+        "signal",
+        "oilgas",
+        "data",
+        "ml",
+        "agents",
+        "health",
+    )
+
+    def __init__(self) -> None:
+        domain_alt = "|".join(self._domains)
+        # The captured domain is followed by one of: end-of-token (whitespace,
+        # `.`, `,`, end-of-line) — never another identifier character — so a
+        # non-domain like `pirn.domains.datasource` cannot match `data`.
+        boundary = r"(?![A-Za-z0-9_])"
+
+        # `from pirn.domains import <x>[ as alias]` -> `import pirn_<x>[ as alias]`.
+        # Only handled when the imported name is a single bare domain.
+        self._from_domains_import = re.compile(
+            rf"^(?P<indent>\s*)from\s+pirn\.domains\s+import\s+"
+            rf"(?P<domain>{domain_alt}){boundary}"
+            rf"(?P<alias>\s+as\s+[A-Za-z_][A-Za-z0-9_]*)?\s*$"
+        )
+
+        # `from pirn.domains.<x>[.sub...] import ...` -> `from pirn_<x>[.sub...] import ...`.
+        self._from_submodule = re.compile(
+            rf"^(?P<indent>\s*)from\s+pirn\.domains\."
+            rf"(?P<domain>{domain_alt}){boundary}"
+            rf"(?P<tail>(?:\.[A-Za-z_][A-Za-z0-9_]*)*)\s+import\s"
+        )
+
+        # `import pirn.domains.<x>[.sub...][ as alias]` -> `import pirn_<x>[.sub...][ as alias]`.
+        self._import_module = re.compile(
+            rf"^(?P<indent>\s*)import\s+pirn\.domains\."
+            rf"(?P<domain>{domain_alt}){boundary}"
+            rf"(?P<tail>(?:\.[A-Za-z_][A-Za-z0-9_]*)*)"
+            rf"(?P<rest>\s+as\s+[A-Za-z_][A-Za-z0-9_]*\s*|\s*)$"
+        )
+
+    def rewrite_line(self, line: str) -> str:
+        """Rewrite a single source line, returning it unchanged if no rule applies."""
+        match = self._from_domains_import.match(line)
+        if match is not None:
+            alias = match.group("alias") or ""
+            return f"{match.group('indent')}import pirn_{match.group('domain')}{alias}\n"
+
+        match = self._from_submodule.match(line)
+        if match is not None:
+            end = match.end()
+            head = (
+                f"{match.group('indent')}from pirn_{match.group('domain')}"
+                f"{match.group('tail')} import "
+            )
+            return head + line[end:]
+
+        match = self._import_module.match(line)
+        if match is not None:
+            return (
+                f"{match.group('indent')}import pirn_{match.group('domain')}"
+                f"{match.group('tail')}{match.group('rest')}"
+            )
+
+        return line
+
+    def rewrite_text(self, source: str) -> str:
+        """Rewrite every applicable import line in a source string."""
+        if "pirn.domains." not in source and "pirn.domains " not in source:
+            return source
+        lines = source.splitlines(keepends=True)
+        return "".join(self.rewrite_line(line) for line in lines)
+
+    def rewrite_file(self, path: Path) -> bool:
+        """Rewrite a file in place. Returns ``True`` iff its contents changed."""
+        original = path.read_text(encoding="utf-8")
+        rewritten = self.rewrite_text(original)
+        if rewritten == original:
+            return False
+        path.write_text(rewritten, encoding="utf-8")
+        return True
+
+    def file_needs_rewrite(self, path: Path) -> bool:
+        """Return ``True`` iff the file would change, without writing it."""
+        original = path.read_text(encoding="utf-8")
+        return self.rewrite_text(original) != original

pirn/_migrate/main.py

@@ -0,0 +1,76 @@
+"""CLI for the ``pirn.domains.<x>`` -> ``pirn_<x>`` import codemod (SCD-17).
+
+Exposed as the ``pirn-migrate-imports`` console script. Accepts one or more
+files or directories. Directories are walked recursively for ``.py`` files.
+By default rewrites in place; ``--check`` is a dry run that reports what
+would change and exits non-zero if any file needs rewriting. Output is a
+deterministic, sorted summary.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from pirn._migrate.import_rewriter import ImportRewriter
+
+
+def _collect_py_files(paths: list[str]) -> list[Path]:
+    """Return the sorted, de-duplicated set of ``.py`` files under ``paths``."""
+    found: set[Path] = set()
+    for raw in paths:
+        path = Path(raw)
+        if path.is_dir():
+            found.update(p for p in path.rglob("*.py") if p.is_file())
+        elif path.suffix == ".py" and path.is_file():
+            found.add(path)
+    return sorted(found)
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Entry point for the ``pirn-migrate-imports`` console script."""
+    parser = argparse.ArgumentParser(
+        prog="pirn-migrate-imports",
+        description=(
+            "Rewrite legacy `pirn.domains.<x>` imports to the standalone "
+            "`pirn_<x>` packages (x in signal, oilgas, data, ml, agents, health)."
+        ),
+    )
+    parser.add_argument(
+        "paths",
+        nargs="+",
+        help="Files or directories to rewrite (directories are walked recursively).",
+    )
+    parser.add_argument(
+        "--check",
+        action="store_true",
+        help="Dry run: report files that need rewriting and exit non-zero, writing nothing.",
+    )
+    args = parser.parse_args(argv)
+
+    rewriter = ImportRewriter()
+    files = _collect_py_files(args.paths)
+    changed: list[Path] = []
+
+    for path in files:
+        if args.check:
+            if rewriter.file_needs_rewrite(path):
+                changed.append(path)
+        elif rewriter.rewrite_file(path):
+            changed.append(path)
+
+    verb = "would rewrite" if args.check else "rewrote"
+    for path in changed:
+        print(f"{verb}: {path}")
+
+    if not changed:
+        print(f"no changes — scanned {len(files)} file(s)")
+        return 0
+
+    print(f"{verb} {len(changed)} of {len(files)} file(s)")
+    return 1 if args.check else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

pirn/backends/AGENTIC_USE.md

@@ -0,0 +1,168 @@
+`pirn.backends` provides pluggable implementations of the three storage protocols (`TapestryStore`, `RunHistory`, `DataStore`) and the cloud object store base — it does not execute pipelines or process domain data.
+
+---
+
+## Mental model
+
+Every `Tapestry` holds three backend slots, each independently swappable:
+
+| Slot | Protocol | Stores | Default |
+|------|----------|--------|---------|
+| `store` | `TapestryStore` | Knot registrations (the pipeline definition) | `InMemoryStore` |
+| `history` | `RunHistory` | Run results and per-knot lineage records | `InMemoryHistory` |
+| `data` | `DataStore` | Intermediate values keyed by content hash | `InMemoryDataStore` |
+
+Pass backends to `Tapestry(store=..., history=..., data=...)`. Backends that are not passed default to their in-memory counterparts. The three slots are decoupled — you can persist lineage to SQLite while keeping values in memory.
+
+`SubscribableStore` is a mixin implemented by `InMemoryStore`, `PostgresStore`, and `ValKeyStore`. It adds `subscribe()` for live notifications when knots are registered — required for `WithContinuation` and extensible runs.
+
+---
+
+## Source map
+
+```
+pirn/backends/
+├── base/
+│   ├── tapestry_store.py     TapestryStore        — interface: register, get, all, snapshot
+│   ├── run_history.py        RunHistory           — interface: record_run, get_run, query_lineage_*
+│   ├── data_store.py         DataStore            — interface: put, get, has, delete
+│   ├── subscribable_store.py SubscribableStore    — mixin: subscribe() for live registration events
+│   └── tapestry_snapshot.py  TapestrySnapshot     — frozen Pydantic model: ordered knot id list
+├── in_memory/
+│   ├── in_memory_store.py    InMemoryStore        — TapestryStore + SubscribableStore; default
+│   ├── in_memory_history.py  InMemoryHistory      — RunHistory; default; not persistent
+│   └── in_memory_data_store.py InMemoryDataStore  — DataStore; default; not persistent
+├── sqlite/
+│   ├── sqlite_store.py       SQLiteStore          — TapestryStore backed by SQLite
+│   └── sqlite_history.py     SQLiteHistory        — RunHistory backed by SQLite; durable
+├── postgres/
+│   ├── postgres_store.py     PostgresStore        — TapestryStore + SubscribableStore; asyncpg
+│   └── postgres_history.py   PostgresHistory      — RunHistory backed by Postgres; durable
+├── valkey/
+│   ├── valkey_store.py       ValKeyStore          — TapestryStore + SubscribableStore; Valkey/Redis
+│   └── valkey_data_store.py  ValKeyDataStore      — DataStore backed by Valkey/Redis; pickle-serialised
+├── duckdb.py                 DuckDBHistory        — RunHistory backed by DuckDB; analytical queries
+├── s3.py                     S3DataStore          — DataStore backed by AWS S3; pickle-serialised
+├── gcs.py                    GCSDataStore         — DataStore backed by Google Cloud Storage
+├── azure.py                  AzureBlobDataStore   — DataStore backed by Azure Blob Storage
+└── disk.py                   LocalDiskDataStore   — DataStore backed by local filesystem; pickle-serialised
+```
+
+---
+
+## Canonical pattern
+
+### Development — all in memory (default)
+
+```python
+from pirn import Tapestry, RunRequest
+
+# No backends passed — all three slots use in-memory defaults.
+with Tapestry() as t:
+    ...
+
+result = await t.run(RunRequest())
+```
+
+### Production — durable lineage, in-memory values
+
+```python
+from pirn import Tapestry, RunRequest
+from pirn.backends.sqlite.sqlite_history import SQLiteHistory
+
+history = SQLiteHistory(path="pirn.db")
+
+with Tapestry(history=history) as t:
+    ...
+
+result = await t.run(RunRequest())
+# result.lineage is now persisted across process restarts
+```
+
+### Querying lineage across runs
+
+```python
+records = await history.query_lineage_by_knot_id("my-knot-id")
+for rec in records:
+    print(rec.run_id, rec.outcome, rec.output_hash)
+```
+
+### Persisting intermediate values (S3)
+
+```python
+from pirn.backends.s3 import S3DataStore
+
+data = S3DataStore(bucket="my-pirn-bucket", prefix="runs/")
+with Tapestry(data=data) as t:
+    ...
+```
+
+### Shared tapestry definition (Postgres — multi-process)
+
+```python
+from pirn.backends.postgres.postgres_store import PostgresStore
+from pirn.backends.postgres.postgres_history import PostgresHistory
+
+store   = PostgresStore(dsn="postgresql://user:pass@host/pirn")
+history = PostgresHistory(dsn="postgresql://user:pass@host/pirn")
+
+with Tapestry(store=store, history=history) as t:
+    ...
+```
+
+---
+
+## Anti-patterns
+
+### Using cloud DataStores with untrusted infrastructure
+
+`S3DataStore`, `GCSDataStore`, `AzureBlobDataStore`, and `LocalDiskDataStore` serialise values with `pickle`. Any store writable by an adversary can execute arbitrary code on deserialization. Only use these backends when the backing store is fully access-controlled.
+
+### Assuming `InMemoryHistory` persists across runs
+
+`InMemoryHistory` holds results in a dict for the lifetime of the process. Restarting the process loses all lineage. Use `SQLiteHistory`, `PostgresHistory`, or `DuckDBHistory` for durability.
+
+### Using extensible runs with non-memory `TapestryStore`
+
+`tapestry.run(extensible=True)` (required by `WithContinuation` and `LoopSubTapestry`) calls `get_current_store()` mid-run to register new knots. Only `InMemoryStore`, `PostgresStore`, and `ValKeyStore` (all `SubscribableStore` implementors) support this. `SQLiteStore` does not.
+
+### Scrubbing `DataStore` values and expecting lineage to break
+
+`DataStore` and `RunHistory` are decoupled by design. Deleting a value from the data store removes the payload but leaves the lineage hash record intact. This is intentional for GDPR-style scrubbing.
+
+---
+
+## Constraints and gotchas
+
+- **`SQLiteHistory` runs migrations on first open.** The first `SQLiteHistory(path=...)` call creates the schema. Concurrent first-opens from multiple processes can race — initialise from a single process or use Postgres for multi-process deployments.
+- **`DuckDBHistory` is optimised for analytical queries, not writes.** Use it for offline lineage analysis, not as the primary history backend of a high-throughput pipeline.
+- **`ValKeyDataStore` and `LocalDiskDataStore` are pickle-based.** See anti-pattern above.
+- **`PostgresStore` and `ValKeyStore` implement `SubscribableStore`.** If you need extensible runs in a distributed deployment, these are the only backends that support it.
+- **Backend constructors are synchronous; connections are lazy.** `PostgresStore(dsn=...)` does not open a connection immediately. The first operation opens it. Call `await backend.close()` when done.
+- **`DataStore.has()` is a cheap existence check** — use it before `get()` when a miss is a valid path, rather than catching `KeyError`.
+
+---
+
+## Quick reference
+
+| Task | How |
+|------|-----|
+| Default (dev, no persistence) | `Tapestry()` — all in-memory |
+| Durable lineage (single process) | `Tapestry(history=SQLiteHistory(path="pirn.db"))` |
+| Durable lineage (multi-process) | `Tapestry(history=PostgresHistory(dsn=...))` |
+| Analytical lineage queries | `DuckDBHistory(path="lineage.duckdb")` |
+| Persist intermediate values to S3 | `Tapestry(data=S3DataStore(bucket=..., prefix=...))` |
+| Persist intermediate values to GCS | `Tapestry(data=GCSDataStore(bucket=..., prefix=...))` |
+| Persist intermediate values to Azure | `Tapestry(data=AzureBlobDataStore(container=..., prefix=...))` |
+| Persist intermediate values to disk | `Tapestry(data=LocalDiskDataStore(root=Path("/data")))` |
+| Shared tapestry definition (multi-process) | `Tapestry(store=PostgresStore(dsn=...))` |
+| Shared tapestry + extensible runs | `Tapestry(store=PostgresStore(dsn=...), ...)` — `SubscribableStore` required |
+| Query lineage by knot id | `await history.query_lineage_by_knot_id("my-id")` |
+| Query lineage by output hash | `await history.query_lineage_by_output_hash("sha256:abc...")` |
+| Check if a value is cached | `await data_store.has("sha256:abc...")` |
+| Retrieve a cached value | `await data_store.get("sha256:abc...")` |
+| Scrub a value (GDPR) | `await data_store.delete("sha256:abc...")` — lineage record is preserved |
+
+---
+
+*See also: [pirn AGENTIC_USE.md](../../AGENTIC_USE.md)*

pirn/backends/__init__.py

@@ -0,0 +1,12 @@
+"""Backend implementations for pirn.
+
+Interface base classes live in ``pirn.backends.base``.
+Implementations:
+  - ``pirn.backends.in_memory`` — in-memory (default, single-process)
+  - ``pirn.backends.sqlite`` — SQLite (durable, single-host)
+  - ``pirn.backends.postgres`` — PostgreSQL via asyncpg
+  - ``pirn.backends.valkey`` — ValKey/Redis
+  - ``pirn.backends.duckdb`` — DuckDB (analytics history)
+  - ``pirn.backends.disk`` — local disk data store
+  - ``pirn.backends.s3`` — S3 data store
+"""

pirn/backends/_signer.py

@@ -0,0 +1,92 @@
+"""HMAC-SHA256 payload signing for DataStore backends.
+
+Prevents insecure deserialization of tampered payloads (security finding C-1).
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import os
+
+
+class _Signer:
+    """Signs and verifies cloudpickle payloads with HMAC-SHA256.
+
+    The digest size is fixed at 32 bytes by the SHA256 algorithm.
+    """
+
+    __digest_size = 32
+
+    def __init__(self, key: bytes) -> None:
+        self.__key = key
+
+    @classmethod
+    def from_env(cls, var: str = "PIRN_SIGNING_KEY") -> _Signer:
+        """Construct a _Signer from a base64-encoded key in an environment variable.
+
+        Raises ``ValueError`` if the variable is unset or empty.
+
+        Example::
+
+            import secrets, base64
+            key_b64 = base64.b64encode(secrets.token_bytes(32)).decode()
+            # Set PIRN_SIGNING_KEY=<key_b64> in your environment, then:
+            store = LocalDiskDataStore("/data", signer=_Signer.from_env())
+        """
+        raw = os.environ.get(var)
+        if not raw:
+            raise ValueError(
+                f"Environment variable {var!r} is not set or empty. "
+                "Set it to a base64-encoded signing key before constructing a signed DataStore."
+            )
+        decoded = base64.b64decode(raw)
+        if len(decoded) < 32:
+            raise ValueError(
+                f"Environment variable {var!r} decoded to {len(decoded)} bytes; "
+                "HMAC-SHA256 requires at least 32 bytes of key material. "
+                'Generate a key with: python -c "import secrets,base64; print(base64.b64encode(secrets.token_bytes(32)).decode())"'
+            )
+        return cls(decoded)
+
+    @classmethod
+    def test_signer(cls) -> _Signer:
+        """Return a deterministic signer for unit tests.
+
+        Tests that exercise the signing path use this so they don't need
+        env-var setup or real key material. **Never use in production.**
+        Production signers must come from :meth:`from_env` or a manual
+        construction with a per-deployment key.
+
+        Raises:
+            RuntimeError: If called outside a test or CI environment
+                (i.e. when PIRN_ENV is not set to "test" or "ci").
+        """
+        env = os.environ.get("PIRN_ENV", "").lower()
+        if env not in ("test", "ci"):
+            raise RuntimeError(
+                "_Signer.test_signer() must not be called in production. "
+                "Set PIRN_ENV=test or PIRN_ENV=ci to use this method in a "
+                "test or CI environment. Use _Signer.from_env() for production."
+            )
+        return cls(b"pirn-test-signer-key-not-for-production")
+
+    def sign(self, payload: bytes) -> bytes:
+        """Prepend a 32-byte HMAC-SHA256 signature to payload."""
+        sig = hmac.new(self.__key, payload, hashlib.sha256).digest()
+        return sig + payload
+
+    def verify(self, payload: bytes) -> bytes:
+        """Verify the HMAC-SHA256 signature and return the raw payload.
+
+        Raises ``ValueError`` if the payload is too short or the signature
+        does not match.
+        """
+        if len(payload) < self.__digest_size:
+            raise ValueError("payload too short to contain a signature — possible tampering")
+        sig, raw = payload[: self.__digest_size], payload[self.__digest_size :]
+        expected = hmac.new(self.__key, raw, hashlib.sha256).digest()
+        if not hmac.compare_digest(sig, expected):
+            raise ValueError("HMAC signature mismatch — payload may have been tampered with")
+        return raw