domainkit 0.2.0__tar.gz → 0.3.0__tar.gz

{domainkit-0.2.0 → domainkit-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: domainkit
-Version: 0.2.0
+Version: 0.3.0
 Summary: A Django-style framework for domain-driven FastAPI services.
 License-Expression: MIT
 License-File: LICENSE
@@ -16,6 +16,7 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
 Classifier: Typing :: Typed
+Provides-Extra: immudb
 Provides-Extra: metrics
 Provides-Extra: postgres
 Provides-Extra: sqlite
@@ -26,6 +27,7 @@ Requires-Dist: alembic (>=1.20.0,<2.0.0)
 Requires-Dist: asyncpg (>=0.31.0,<0.32.0) ; extra == "postgres"
 Requires-Dist: fastapi (>=0.141.1,<0.142.0)
 Requires-Dist: httpx2 (>=2.13.0,<3.0.0) ; extra == "testing"
+Requires-Dist: immudb-py (>=1.5.0,<1.6.0) ; extra == "immudb"
 Requires-Dist: opentelemetry-api (>=1.45.1,<2.0.0) ; extra == "tracing"
 Requires-Dist: prometheus-client (>=0.26.0,<0.27.0) ; extra == "metrics"
 Requires-Dist: pydantic (>=2.14.1,<3.0.0)
@@ -46,17 +48,22 @@ A Django-style framework for domain-driven FastAPI services. It provides:
 - settings modules and installed domains
 - `manage.py` commands and migrations
 - DDD building blocks, with the layer rules between them enforced
-- optional apps for reliable messaging, audit trails, and idempotent requests
+- several databases: domains routed to their own, sharding by key,
+  PostgreSQL range partitioning, and immudb ledgers for evidence
+- optional apps for reliable messaging, audit trails, idempotent requests,
+  and tamper-evident evidence
 
 ```bash
-pip install "domainkit[postgres]"     # extras: postgres, sqlite, metrics, tracing, testing
+pip install "domainkit[postgres]"     # extras: postgres, sqlite, immudb, metrics, tracing, testing
 ```
 
 ## Documentation
 
 - [docs/reference.md](https://github.com/karimmattar/domainkit/blob/main/docs/reference.md): settings, middleware, errors,
   observability, testing, commands, and extension points
-- [docs/contrib.md](https://github.com/karimmattar/domainkit/blob/main/docs/contrib.md): messaging, audit, and idempotency
+- [docs/databases.md](https://github.com/karimmattar/domainkit/blob/main/docs/databases.md): several databases, routing,
+  sharding, partitioning, and ledgers
+- [docs/contrib.md](https://github.com/karimmattar/domainkit/blob/main/docs/contrib.md): messaging, audit, idempotency, and evidence
 - [docs/versioning.md](https://github.com/karimmattar/domainkit/blob/main/docs/versioning.md): compatibility, deprecations, and releases
 - [docs/adr/](https://github.com/karimmattar/domainkit/tree/main/docs/adr): the decisions behind the design
 - [CHANGELOG.md](https://github.com/karimmattar/domainkit/blob/main/CHANGELOG.md) and [SECURITY.md](https://github.com/karimmattar/domainkit/blob/main/SECURITY.md)

{domainkit-0.2.0 → domainkit-0.3.0}/README.md

@@ -5,17 +5,22 @@ A Django-style framework for domain-driven FastAPI services. It provides:
 - settings modules and installed domains
 - `manage.py` commands and migrations
 - DDD building blocks, with the layer rules between them enforced
-- optional apps for reliable messaging, audit trails, and idempotent requests
+- several databases: domains routed to their own, sharding by key,
+  PostgreSQL range partitioning, and immudb ledgers for evidence
+- optional apps for reliable messaging, audit trails, idempotent requests,
+  and tamper-evident evidence
 
 ```bash
-pip install "domainkit[postgres]"     # extras: postgres, sqlite, metrics, tracing, testing
+pip install "domainkit[postgres]"     # extras: postgres, sqlite, immudb, metrics, tracing, testing
 ```
 
 ## Documentation
 
 - [docs/reference.md](https://github.com/karimmattar/domainkit/blob/main/docs/reference.md): settings, middleware, errors,
   observability, testing, commands, and extension points
-- [docs/contrib.md](https://github.com/karimmattar/domainkit/blob/main/docs/contrib.md): messaging, audit, and idempotency
+- [docs/databases.md](https://github.com/karimmattar/domainkit/blob/main/docs/databases.md): several databases, routing,
+  sharding, partitioning, and ledgers
+- [docs/contrib.md](https://github.com/karimmattar/domainkit/blob/main/docs/contrib.md): messaging, audit, idempotency, and evidence
 - [docs/versioning.md](https://github.com/karimmattar/domainkit/blob/main/docs/versioning.md): compatibility, deprecations, and releases
 - [docs/adr/](https://github.com/karimmattar/domainkit/tree/main/docs/adr): the decisions behind the design
 - [CHANGELOG.md](https://github.com/karimmattar/domainkit/blob/main/CHANGELOG.md) and [SECURITY.md](https://github.com/karimmattar/domainkit/blob/main/SECURITY.md)

{domainkit-0.2.0 → domainkit-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "domainkit"
-version = "0.2.0"
+version = "0.3.0"
 description = "A Django-style framework for domain-driven FastAPI services."
 readme = "README.md"
 license = "MIT"
@@ -35,6 +35,8 @@ postgres = ["asyncpg (>=0.31.0,<0.32.0)"]
 sqlite = ["aiosqlite (>=0.22.1,<0.23.0)"]
 metrics = ["prometheus-client (>=0.26.0,<0.27.0)"]
 tracing = ["opentelemetry-api (>=1.45.1,<2.0.0)"]
+# Ledgers for evidence (WORM): immudb's SDK, with its verified operations.
+immudb = ["immudb-py (>=1.5.0,<1.6.0)"]
 # The domainkit.testing pytest plugin; Starlette's TestClient needs httpx2.
 testing = ["pytest (>=9.1.1,<10.0.0)", "httpx2 (>=2.13.0,<3.0.0)"]
 
@@ -104,6 +106,11 @@ mypy_path = "src:."
 files = ["src", "domainkit_tests"]
 exclude = ["/management/templates/", "/mutants/"]
 
+# immudb-py and grpcio ship no type information.
+[[tool.mypy.overrides]]
+module = ["immudb", "immudb.*", "grpc", "grpc.*", "ecdsa", "ecdsa.*"]
+ignore_missing_imports = true
+
 [tool.pytest.ini_options]
 testpaths = ["domainkit_tests"]
 pythonpath = ["."]

{domainkit-0.2.0 → domainkit-0.3.0}/src/domainkit/apps/config.py

@@ -11,6 +11,7 @@ from pydantic import BaseModel
 from domainkit.exceptions import ImproperlyConfigured
 
 if TYPE_CHECKING:
+    from domainkit.db.routing import DatabaseRouter
     from domainkit.ddd import DeferredTask, DomainEvent, UnitOfWork
 
 CONFIG_MODULE = "apps"
@@ -100,6 +101,15 @@ class DomainConfig:
     ) -> None:
         """Add rows to a committing SQL unit of work (outbox, audit trail)."""
 
+    def databases(self, router: "DatabaseRouter") -> frozenset[str]:
+        """The targets that hold this domain's tables (see ``DATABASE_ROUTING``).
+
+        By default, the domain's routing target. Apps whose rows must commit
+        with every domain's data (the outbox, the audit trail) return every
+        hosting target; apps without tables return none.
+        """
+        return frozenset({router.target_for(self.label)})
+
 
 def _import_domain(name: str) -> ModuleType:
     """Import a domain package, explaining a missing one."""

{domainkit-0.2.0 → domainkit-0.3.0}/src/domainkit/apps/registry.py

@@ -123,6 +123,13 @@ class DomainRegistry:
                 + ", ".join(_describe_unknown(name, known) for name in unknown)
                 + ". Declare them in a domain's settings_class or SETTINGS_CLASS."
             )
+        labels = list(self._configs)
+        if unrouted := sorted(set(current.DATABASE_ROUTING) - set(labels)):
+            raise ImproperlyConfigured(
+                "DATABASE_ROUTING names domains that are not installed: "
+                + ", ".join(_describe_unknown(label, labels) for label in unrouted)
+                + "."
+            )
 
 
 def _describe_unknown(name: str, known: list[str]) -> str:

{domainkit-0.2.0 → domainkit-0.3.0}/src/domainkit/conf/__init__.py

@@ -20,7 +20,9 @@ from domainkit.conf.env import Env
 from domainkit.conf.global_settings import (
     DEFAULT_DB_ALIAS,
     DatabaseConfig,
+    LedgerConfig,
     Settings,
+    ShardConfig,
 )
 from domainkit.conf.lazy import (
     SETTINGS_MODULE_VARIABLE,
@@ -46,7 +48,9 @@ __all__ = [
     "SETTINGS_MODULE_VARIABLE",
     "UNSET",
     "DatabaseConfig",
+    "LedgerConfig",
     "Settings",
+    "ShardConfig",
     "configure",
     "describe_errors",
     "load_settings",

{domainkit-0.2.0 → domainkit-0.3.0}/src/domainkit/conf/global_settings.py

@@ -9,6 +9,7 @@ so a misspelled setting fails at startup instead of being silently ignored.
 from collections.abc import Callable
 from pathlib import Path
 from typing import Any, Final, Literal, Self
+from urllib.parse import urlsplit
 
 from pydantic import (
     BaseModel,
@@ -51,6 +52,11 @@ def is_network_database(url: str) -> bool:
     return not url.split(":", 1)[0].split("+", 1)[0].startswith("sqlite")
 
 
+LEDGER_SCHEMES: Final = frozenset({"immudb", "memory"})
+"""URL schemes of ledgers (``LEDGERS``); ``DATABASES`` refuses them."""
+IMMUDB_PORT: Final = 3322
+
+
 class DatabaseConfig(BaseModel):
     """One ``DATABASES`` entry: an SQLAlchemy async URL plus connection options."""
 
@@ -95,6 +101,108 @@ class DatabaseConfig(BaseModel):
             raise ValueError("SSLCERT and SSLKEY must be set together")
         return self
 
+    @model_validator(mode="after")
+    def check_not_a_ledger(self) -> Self:
+        """Point ledger URLs to ``LEDGERS``, where they belong."""
+        scheme = urlsplit(self.URL.get_secret_value()).scheme.split("+", 1)[0]
+        if scheme in LEDGER_SCHEMES:
+            raise ValueError(f"{scheme}:// is a ledger; configure it in LEDGERS")
+        return self
+
+
+class LedgerConfig(BaseModel):
+    """One ``LEDGERS`` entry: write once, read many, verified on the client.
+
+    Ledgers hold evidence (see ``domainkit.contrib.evidence``). They are never
+    migrated and never take part in a unit of work.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    URL: SecretStr
+    """``immudb://user:password@host:3322/database``, or ``memory://`` for tests."""
+    TLS_CA: Path | None = None
+    """CA certificate that signed the server's; setting it enables TLS."""
+    SERVER_SIGNING_KEY: Path | None = None
+    """Public key the server signs its states with (immudb ``--signingKey``)."""
+    TIMEOUT: float = Field(default=10.0, gt=0)
+    """Seconds each ledger call may take."""
+
+    @model_validator(mode="after")
+    def check_url(self) -> Self:
+        """Accept immudb URLs with a host, or the in-memory ledger."""
+        parts = urlsplit(self.URL.get_secret_value())
+        if parts.scheme not in LEDGER_SCHEMES:
+            raise ValueError("a ledger URL starts with immudb:// or memory://")
+        if parts.scheme == "immudb" and not parts.hostname:
+            raise ValueError("an immudb URL needs a host: immudb://user:pw@host/db")
+        return self
+
+    @property
+    def scheme(self) -> str:
+        """``immudb`` or ``memory``."""
+        return urlsplit(self.URL.get_secret_value()).scheme
+
+
+class ShardConfig(BaseModel):
+    """One ``SHARDS`` group: SQL databases that share a schema, split by key.
+
+    A shard key hashes to one of ``BUCKETS`` buckets, and each bucket belongs
+    to one database. Moving buckets between databases is how a group grows.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    DATABASES: tuple[str, ...] = Field(min_length=1)
+    """The group's SQL aliases; ``makemigrations`` compares against the first."""
+    BUCKETS: int = Field(default=4096, ge=1, le=1_048_576)
+    """Number of hash buckets. Never change it once the group holds data."""
+    RANGES: dict[str, tuple[tuple[int, int], ...]] = Field(default_factory=dict)
+    """Inclusive bucket ranges per alias; default: equal ranges in list order."""
+    PINNED: dict[str, str] = Field(default_factory=dict)
+    """Shard keys (as text) always routed to an alias, such as a large tenant."""
+
+    @model_validator(mode="after")
+    def check_layout(self) -> Self:
+        """Every bucket has exactly one owner, and pins stay inside the group."""
+        if len(set(self.DATABASES)) != len(self.DATABASES):
+            raise ValueError("a shard group lists an alias twice")
+        if len(self.DATABASES) > self.BUCKETS:
+            raise ValueError("BUCKETS must be at least the number of DATABASES")
+        if outside := sorted(set(self.PINNED.values()) - set(self.DATABASES)):
+            raise ValueError(f"PINNED names aliases outside the group: {outside}")
+        if not self.RANGES:
+            return self
+        if set(self.RANGES) != set(self.DATABASES):
+            raise ValueError("RANGES must give ranges for exactly the group's aliases")
+        owned = sorted(
+            (low, high) for ranges in self.RANGES.values() for low, high in ranges
+        )
+        expected = 0
+        for low, high in owned:
+            if low != expected or high < low:
+                raise ValueError(
+                    f"RANGES must cover buckets 0-{self.BUCKETS - 1} once each; "
+                    f"bucket {expected} is missing or overlapped"
+                )
+            expected = high + 1
+        if expected != self.BUCKETS:
+            raise ValueError(
+                f"RANGES must cover buckets 0-{self.BUCKETS - 1} once each; "
+                f"they end at {expected - 1}"
+            )
+        return self
+
+    def ranges(self) -> dict[str, tuple[tuple[int, int], ...]]:
+        """Bucket ranges per alias: ``RANGES``, or equal contiguous ranges."""
+        if self.RANGES:
+            return dict(self.RANGES)
+        count, buckets = len(self.DATABASES), self.BUCKETS
+        return {
+            alias: ((index * buckets // count, (index + 1) * buckets // count - 1),)
+            for index, alias in enumerate(self.DATABASES)
+        }
+
 
 class Settings(BaseModel):
     """Validated, read-only settings; extra names are checked at ``setup()``."""
@@ -120,8 +228,15 @@ class Settings(BaseModel):
     """``module:attribute`` that ``runserver`` serves."""
 
     DATABASES: dict[str, DatabaseConfig] = Field(default_factory=dict)
+    """SQL databases by alias; if any are set, ``default`` is required."""
+    LEDGERS: dict[str, LedgerConfig] = Field(default_factory=dict)
+    """Ledgers by alias: write once, read many (``immudb://``, ``memory://``)."""
+    SHARDS: dict[str, ShardConfig] = Field(default_factory=dict)
+    """Shard groups by name; route a domain to one in ``DATABASE_ROUTING``."""
+    DATABASE_ROUTING: dict[str, str] = Field(default_factory=dict)
+    """Domain label to target: a SQL alias or a shard group; others use default."""
     MIGRATIONS_DIR: Path = Field(default_factory=lambda: project_root() / "migrations")
-    """Where ``makemigrations`` writes revision files."""
+    """Revisions of ``default``; any other target uses ``MIGRATIONS_DIR/<target>``."""
     LOGGING: dict[str, Any] = Field(default_factory=_minimal_logging)
     """``logging.config.dictConfig`` mapping applied by ``setup()``."""
 
@@ -171,8 +286,7 @@ class Settings(BaseModel):
     @model_validator(mode="after")
     def check_consistency(self) -> Self:
         """Reject combinations that are unsafe or would fail later at runtime."""
-        if self.DATABASES and DEFAULT_DB_ALIAS not in self.DATABASES:
-            raise ValueError(f"DATABASES must define the {DEFAULT_DB_ALIAS!r} alias")
+        self._check_databases()
         if len(set(self.INSTALLED_DOMAINS)) != len(self.INSTALLED_DOMAINS):
             raise ValueError("INSTALLED_DOMAINS contains duplicates")
         if self.CORS_ALLOW_CREDENTIALS and "*" in self.CORS_ALLOWED_ORIGINS:
@@ -183,6 +297,34 @@ class Settings(BaseModel):
             self._check_deployment()
         return self
 
+    def _check_databases(self) -> None:
+        """Validate aliases, shard groups, and routing targets together."""
+        sql = self.DATABASES
+        if sql and DEFAULT_DB_ALIAS not in sql:
+            raise ValueError(f"DATABASES must define the {DEFAULT_DB_ALIAS!r} alias")
+        sharded: dict[str, str] = {}
+        for group, shards in self.SHARDS.items():
+            if group in self.DATABASES:
+                raise ValueError(f"shard group {group!r} has the name of an alias")
+            for alias in shards.DATABASES:
+                if alias not in sql or alias == DEFAULT_DB_ALIAS:
+                    raise ValueError(
+                        f"shard group {group!r}: {alias!r} must be a SQL alias "
+                        f"other than {DEFAULT_DB_ALIAS!r}"
+                    )
+                if alias in sharded:
+                    raise ValueError(
+                        f"{alias!r} is in shard groups {sharded[alias]!r} and {group!r}"
+                    )
+                sharded[alias] = group
+        for label, target in self.DATABASE_ROUTING.items():
+            if target in self.SHARDS or (target in sql and target not in sharded):
+                continue
+            raise ValueError(
+                f"DATABASE_ROUTING[{label!r}] = {target!r} must name a shard group "
+                "or a SQL alias outside the shard groups"
+            )
+
     def _check_deployment(self) -> None:
         """Enforce the security baseline for staging and production."""
         where = f"in {self.ENVIRONMENT}"
@@ -203,3 +345,16 @@ class Settings(BaseModel):
         for message, violates in rules.items():
             if aliases := sorted(a for a, db in self.DATABASES.items() if violates(db)):
                 raise ValueError(f"{message} {where} for {aliases}")
+        ledger_rules: dict[str, Callable[[LedgerConfig], bool]] = {
+            "memory:// ledgers are for tests; use immudb": lambda ledger: (
+                ledger.scheme == "memory"
+            ),
+            "ledgers need TLS_CA (TLS)": lambda ledger: ledger.TLS_CA is None,
+            "ledgers need SERVER_SIGNING_KEY (signed states)": lambda ledger: (
+                ledger.SERVER_SIGNING_KEY is None
+            ),
+        }
+        for message, violates_ledger in ledger_rules.items():
+            ledgers = self.LEDGERS.items()
+            if aliases := sorted(a for a, db in ledgers if violates_ledger(db)):
+                raise ValueError(f"{message} {where} for LEDGERS {aliases}")

{domainkit-0.2.0 → domainkit-0.3.0}/src/domainkit/contrib/audit/apps.py

@@ -5,6 +5,7 @@ from typing import cast
 
 from domainkit.apps import DomainConfig, registry
 from domainkit.db import SqlAlchemyUnitOfWork
+from domainkit.db.routing import DatabaseRouter, router
 from domainkit.ddd import DeferredTask, DomainEvent, UnitOfWork
 
 from .recorder import event_rows, write
@@ -18,6 +19,11 @@ class AuditConfig(DomainConfig):
     verbose_name = "Audit trail"
     settings_class = AuditSettings
 
+    def ready(self) -> None:
+        """Check where explicit records go."""
+        config = registry.settings(AuditSettings)
+        router.require_standalone(config.DATABASE, "AUDIT.DATABASE")
+
     async def stage(
         self,
         uow: UnitOfWork,
@@ -26,7 +32,11 @@ class AuditConfig(DomainConfig):
     ) -> None:
         """Add one audit row per committed event (unless excluded)."""
         config = registry.settings(AuditSettings)
-        sql_uow = cast(SqlAlchemyUnitOfWork, uow)
-        if not config.EVENTS or sql_uow.database != config.DATABASE:
+        if not config.EVENTS:
             return
+        sql_uow = cast(SqlAlchemyUnitOfWork, uow)
         await write(sql_uow.session, event_rows(events, config))
+
+    def databases(self, router: DatabaseRouter) -> frozenset[str]:
+        """Every hosting target: events are audited where they commit."""
+        return frozenset(router.hosting_targets())

{domainkit-0.2.0 → domainkit-0.3.0}/src/domainkit/contrib/audit/management/commands/auditlog.py

@@ -21,9 +21,20 @@ class Command(BaseCommand):
         parser.add_argument("--actor")
         parser.add_argument("--action")
         parser.add_argument("--limit", type=int, default=50)
+        parser.add_argument(
+            "--database",
+            help="the alias to read (default: AUDIT.DATABASE); events are audited "
+            "in the database where they commit",
+        )
 
     async def handle(
-        self, *, actor: str | None, action: str | None, limit: int, **options: object
+        self,
+        *,
+        actor: str | None,
+        action: str | None,
+        limit: int,
+        database: str | None,
+        **options: object,
     ) -> None:
         """Print one line per entry."""
         config = registry.settings(AuditSettings)
@@ -32,7 +43,8 @@ class Command(BaseCommand):
             statement = statement.where(audit_log.c.actor == actor)
         if action:
             statement = statement.where(audit_log.c.action == action)
-        async with connections.engine(config.DATABASE).connect() as connection:
+        alias = database or config.DATABASE
+        async with connections.engine(alias).connect() as connection:
             rows = (await connection.execute(statement.limit(limit))).all()
         for row in rows:
             self.write(

domainkit-0.3.0/src/domainkit/contrib/evidence/__init__.py

@@ -0,0 +1,60 @@
+"""Evidence: facts kept on a ledger, provably unchanged (see ADR 0011).
+
+Install ``domainkit.contrib.evidence``, configure a ledger, and record::
+
+    LEDGERS = {"evidence": {"URL": "immudb://user:pw@immudb:3322/evidence"}}
+
+    store = evidence_store()
+    receipt = await store.record(
+        Evidence(kind="kyc.document_verified", subject="customer:42",
+                 facts={"result": "match"}, artifacts={"passport": sha256(data)})
+    )
+    await store.verify(receipt)
+
+Inside a use case, ``defer_evidence(uow, evidence)`` records it through the
+outbox once the change commits.
+"""
+
+from domainkit.apps import registry
+from domainkit.contrib.evidence.model import (
+    Evidence,
+    EvidenceConflict,
+    EvidenceNotFound,
+    EvidenceReceipt,
+    EvidenceTampered,
+    RecordedEvidence,
+    sha256,
+)
+from domainkit.contrib.evidence.settings import EvidenceSettings
+from domainkit.contrib.evidence.store import (
+    EvidenceStore,
+    LedgerEvidenceStore,
+    evidence_key,
+    subject_digest,
+)
+from domainkit.ledger import ledgers
+
+
+def evidence_store() -> EvidenceStore:
+    """The configured store, on the ledger ``EVIDENCE.LEDGER`` names."""
+    config = registry.settings(EvidenceSettings)
+    return LedgerEvidenceStore(
+        ledgers[config.LEDGER], namespace=config.NAMESPACE, max_bytes=config.MAX_BYTES
+    )
+
+
+__all__ = [
+    "Evidence",
+    "EvidenceConflict",
+    "EvidenceNotFound",
+    "EvidenceReceipt",
+    "EvidenceSettings",
+    "EvidenceStore",
+    "EvidenceTampered",
+    "LedgerEvidenceStore",
+    "RecordedEvidence",
+    "evidence_key",
+    "evidence_store",
+    "sha256",
+    "subject_digest",
+]

domainkit-0.3.0/src/domainkit/contrib/evidence/apps.py

@@ -0,0 +1,29 @@
+"""Install ``domainkit.contrib.evidence`` to record evidence on a ledger."""
+
+from importlib import import_module
+
+from domainkit.apps import DomainConfig, registry
+from domainkit.db.routing import DatabaseRouter
+from domainkit.ledger import ledgers
+
+from .settings import EvidenceSettings
+
+MESSAGING = "domainkit.contrib.messaging"
+
+
+class EvidenceConfig(DomainConfig):
+    """Check the evidence ledger; register durable recording with messaging."""
+
+    label = "evidence"
+    verbose_name = "Evidence"
+    settings_class = EvidenceSettings
+
+    def ready(self) -> None:
+        """Fail fast unless ``EVIDENCE.LEDGER`` names a ledger."""
+        ledgers.config(registry.settings(EvidenceSettings).LEDGER)
+        if registry.is_installed(MESSAGING):
+            import_module(f"{self.name}.tasks")
+
+    def databases(self, router: DatabaseRouter) -> frozenset[str]:
+        """None: evidence lives on a ledger, not in a SQL database."""
+        return frozenset()

domainkit-0.3.0/src/domainkit/contrib/evidence/management/__init__.py

@@ -0,0 +1 @@
+"""Evidence commands."""

domainkit-0.3.0/src/domainkit/contrib/evidence/management/commands/__init__.py

@@ -0,0 +1 @@
+"""``evidence``."""

domainkit-0.3.0/src/domainkit/contrib/evidence/management/commands/evidence.py

@@ -0,0 +1,50 @@
+"""``evidence``: list a subject's evidence, or verify one record."""
+
+from argparse import ArgumentParser
+
+from domainkit.contrib.evidence import EvidenceTampered, evidence_store
+from domainkit.management import BaseCommand, CommandError
+
+
+class Command(BaseCommand):
+    """Read evidence back from the ledger, verified."""
+
+    help = "List a subject's evidence, or verify one record by key."
+
+    def add_arguments(self, parser: ArgumentParser) -> None:
+        """Accept a subject to list, or a key to verify."""
+        mode = parser.add_mutually_exclusive_group(required=True)
+        mode.add_argument("--subject", help="list the evidence about this subject")
+        mode.add_argument("--verify", metavar="KEY", help="verify the record under KEY")
+        parser.add_argument("--limit", type=int, default=50)
+
+    async def handle(
+        self,
+        *,
+        subject: str | None,
+        verify: str | None,
+        limit: int,
+        **options: object,
+    ) -> None:
+        """Print one line per record, or the verified record."""
+        store = evidence_store()
+        if verify is not None:
+            recorded = await store.get(verify)
+            try:
+                await store.verify(recorded.receipt)
+            except EvidenceTampered as exc:
+                raise CommandError(str(exc)) from exc
+            evidence = recorded.evidence
+            self.write(
+                f"Intact: {evidence.kind} about {evidence.subject} at "
+                f"{evidence.recorded_at:%Y-%m-%d %H:%M:%S}, {recorded.receipt.digest}, "
+                f"transaction {recorded.receipt.transaction}."
+            )
+            return
+        # The required option group guarantees a subject when not verifying.
+        for recorded in await store.for_subject(subject or "", limit=limit):
+            state = "intact" if recorded.intact else "WRITTEN AGAIN"
+            self.write(
+                f"{recorded.receipt.key}  {recorded.evidence.kind}  "
+                f"{recorded.evidence.recorded_at:%Y-%m-%d %H:%M:%S}  {state}"
+            )