tallwright-cloud 1.0.0rc1__py3-none-any.whl

tallwright_cloud/__init__.py

@@ -0,0 +1,85 @@
+# SPDX-License-Identifier: Apache-2.0
+"""tallwright_cloud — Cloud Proof from Python, with the content kept where it is.
+
+    from tallwright_cloud import Tallwright
+
+    client = Tallwright(ingest_url, archive_key, "./tallwright-evidence")
+    client.submit("what the agent was told")                            # context it received
+    client.submit({"slot": "2026-11-03T09:00"}, action_type="appointment.booked")   # an action it took
+
+This package is the recorder: it commits, keeps the evidence, sends, sends again and reads the
+receipt, and nothing built on it does any of that again (https://docs.tallwright.com/adapters). The content
+never leaves the caller's machine: a salted address of it does, and the pair that opens the address is
+kept in the caller's evidence store, in the form the public verifier reads. What the door answers is a
+receipt — a confirmation, not a proof; the proof is the exhibit made once a witness has seen the log,
+checked with the disclosure kept here.
+
+- :class:`Tallwright` records into one Environment: ``capture`` waits for the receipt, ``submit``
+  only for the evidence (``client.py``, ``sender.py``);
+- :class:`Environments` gives each end customer its own client, evidence and key (``environments.py``);
+- :class:`LocalEvidence` and :class:`S3Evidence` keep the evidence (``store.py``);
+- :class:`Account` makes and keeps the Environments themselves, with an account key (``account.py``);
+- :class:`Exhibits` takes the exhibit of a record, with an export key;
+- ``tallwright-cloud`` is the command line (``cli.py``).
+
+See https://docs.tallwright.com/http for the same contract over plain HTTP, and
+https://docs.tallwright.com/python/guarantees for what 1.0 promises and the tests that hold it to that.
+"""
+
+from __future__ import annotations
+
+from .account import Account, AccountError, Environment, EnvironmentExists, Made, Secret
+from .client import Capture, Exhibits, Status, Tallwright
+from .environments import Environments
+from .errors import (
+    AccountClosed,
+    EvidenceError,
+    ExhibitError,
+    ExhibitNotReady,
+    ExportKeyRefused,
+    LinkSpent,
+    LostByTheDoor,
+    NotConfirmed,
+    RecordIdConflict,
+    Refused,
+    TallwrightError,
+    Unauthorized,
+)
+from .ids import gaps
+from .receipt import Receipt
+from .sender import Flushed
+from .store import EvidenceStore, LocalEvidence, S3Evidence
+
+__version__ = "1.0.0rc1"
+
+__all__ = [
+    "Tallwright",
+    "Environments",
+    "Exhibits",
+    "Account",
+    "Capture",
+    "Receipt",
+    "Status",
+    "Flushed",
+    "EvidenceStore",
+    "LocalEvidence",
+    "S3Evidence",
+    "Environment",
+    "Made",
+    "Secret",
+    "gaps",
+    "TallwrightError",
+    "NotConfirmed",
+    "Unauthorized",
+    "AccountClosed",
+    "Refused",
+    "RecordIdConflict",
+    "LostByTheDoor",
+    "EvidenceError",
+    "ExhibitError",
+    "ExhibitNotReady",
+    "LinkSpent",
+    "ExportKeyRefused",
+    "AccountError",
+    "EnvironmentExists",
+]

tallwright_cloud/account.py

@@ -0,0 +1,254 @@
+# SPDX-License-Identifier: Apache-2.0
+"""An account's Environments, made and kept by the vendor's own system (``/v1/environments``).
+
+    account = Account(app_url, account_key)
+    made = account.create("Bäckerei Müller", customer_ref="4711", deployer_label="acme-voice")
+    store_secret("4711", made.key.reveal())          # shown once, here and nowhere else
+
+The account key (``ta_…``) is made by an Owner or Admin on the Settings screen and can do what a person
+on the Environments screen can: make an Environment, list and find them, replace a recording key,
+close one. It is NOT the key an agent records with, and it never belongs in the process that records:
+that process holds one recording key per customer and nothing that makes more.
+
+**A create is safe to repeat, and this package always sends one that is.** ``customer_ref`` is
+required here, though the API takes a create without one: with it, a create the door already did is
+answered 409 with the Environment it made, and nothing is made twice. Without it, an answer lost on
+the way back would leave an Environment nobody knows about. What a lost answer still costs is the key,
+which is shown once: :class:`EnvironmentExists` says whether an earlier attempt of THIS call may have
+made it, and then :meth:`Account.new_key` gives the Environment a key somebody holds.
+
+**Keys come back wrapped.** A recording key in a :class:`Secret`, whose repr shows its face and no
+more, so a log line or an error tracker that records the object records no key.
+"""
+
+from __future__ import annotations
+
+import http.client
+import json
+import time
+from collections.abc import Iterator
+from dataclasses import dataclass
+from typing import Any
+from urllib.parse import quote, urlencode
+
+from . import transport
+from .errors import TallwrightError
+from .ids import checked_ref
+
+#: The answers that decide nothing: the same request is sent again, after the same waits as a capture.
+RETRY = frozenset({408, 425, 429, 500, 502, 503, 504})
+DELAYS = (0.5, 1.0, 2.0)
+_pause = time.sleep
+
+
+class AccountError(TallwrightError):
+    """The account API refused or could not complete a request, in its own sentence where it gave one."""
+
+
+class EnvironmentExists(AccountError):
+    """409: an open Environment for this ``customer_ref`` exists, and nothing was made."""
+
+    def __init__(self, message: str, environment: Environment, *, maybe_ours: bool) -> None:
+        super().__init__(message, status=409)
+        self.environment = environment
+        #: True when an earlier attempt of the same call may have made it, and its key was lost with
+        #: the answer: then ``new_key`` gives it one somebody holds.
+        self.maybe_ours = maybe_ours
+
+
+class Secret:
+    """A key shown once. ``reveal`` it into the secret store; nothing else shows more than its face."""
+
+    __slots__ = ("_value",)
+
+    def __init__(self, value: str) -> None:
+        self._value = transport.Key(value).reveal()
+
+    def reveal(self) -> str:
+        """The key itself, for the one place it is handed to; everything else is shown its first characters."""
+        return self._value
+
+    def __repr__(self) -> str:
+        return f"Secret({self._value[:11]}…)"
+
+
+@dataclass(frozen=True)
+class Environment:
+    """One Environment as the account API shows it."""
+
+    id: str
+    name: str
+    customer_ref: str | None
+    deployer_label: str
+    environment_id: str | None
+    status: str
+    reason: str | None = None
+    created_at: str | None = None
+    closed_at: str | None = None
+
+    @classmethod
+    def read(cls, given: object) -> Environment:
+        """An Environment from one entry of the account API's answer; :class:`AccountError` when it is not one."""
+        if not isinstance(given, dict) or not isinstance(given.get("id"), str) or not isinstance(given.get("status"), str):
+            raise AccountError("the account API answered with something that is not an Environment")
+        def text(key: str) -> str | None:
+            value = given.get(key)
+            return value if isinstance(value, str) else None
+
+        return cls(
+            id=given["id"],
+            name=text("name") or "",
+            customer_ref=text("customer_ref"),
+            deployer_label=text("deployer_label") or "",
+            environment_id=text("environment_id"),
+            status=given["status"],
+            reason=text("reason"),
+            created_at=text("created_at"),
+            closed_at=text("closed_at"),
+        )
+
+
+@dataclass(frozen=True)
+class Made:
+    """An Environment just made, or given a new key: the key is here once, and nowhere else."""
+
+    environment: Environment
+    ingest_url: str
+    key: Secret
+
+
+class Account:
+    """The account API of one account, with its account key: it makes, finds, re-keys and closes Environments.
+
+    The account key never belongs in the process that records; that holds one recording key per customer.
+    """
+
+    def __init__(self, url: str, account_key: str, *, timeout: float = 90.0) -> None:
+        transport.checked_address(url, "the account API")
+        self.url = url.rstrip("/")
+        self._key = transport.Key(account_key)
+        self._timeout = timeout
+
+    def __repr__(self) -> str:
+        return f"Account(url={self.url!r}, account_key={self._key!r})"
+
+    def _call(self, method: str, path: str, body: dict[str, Any] | None = None) -> tuple[int, dict[str, Any], int]:
+        """The status, the JSON body and how many attempts it took; undecided answers are tried again."""
+        # A POST without a body still says so: Content-Length 0, which no proxy has to guess at.
+        data = (b"" if method == "POST" else None) if body is None else json.dumps(body).encode("utf-8")
+        kind = None if body is None else "application/json"
+        last = ""
+        attempts = 0
+        for wait in (0.0, *DELAYS):
+            if wait:
+                _pause(wait)
+            attempts += 1
+            try:
+                status, raw, _ = transport.exchange(
+                    method, self.url + path, self._key, data, kind, self._timeout, transport.MAX_ANSWER
+                )
+            except (OSError, http.client.HTTPException) as failed:
+                last = f"{type(failed).__name__}: {getattr(failed, 'reason', failed)}"
+                continue
+            # Read as the door's answers are: an answer nested past any stack is no answer, not a crash.
+            answer = transport.object_in(raw) or {}
+            if status in RETRY:
+                last = f"it answered {status} ({answer.get('error') or 'no sentence'})"
+                continue
+            return status, answer, attempts
+        raise AccountError(f"{method} {path}: {attempts} attempts, the last: {last}. Nothing is known to have been done")
+
+    def _refused(self, method: str, path: str, status: int, answer: dict[str, Any]) -> AccountError:
+        said = answer.get("error")
+        return AccountError(f"{method} {path}: {status} ({said if isinstance(said, str) else 'without the API sentence'})", status=status)
+
+    def create(self, name: str, *, customer_ref: str, deployer_label: str) -> Made:
+        """Make an Environment for one end customer; its key is in the answer, once.
+
+        ``customer_ref`` is the one :class:`~tallwright_cloud.environments.Environments` keeps the
+        customer's evidence beneath, so it is held to the same rule (``ids.checked_ref``) here, and a
+        ref nothing could record under is refused before anything is made.
+        """
+        if not isinstance(customer_ref, str) or not customer_ref.strip():
+            raise ValueError("customer_ref is required: it is what makes a repeated create safe")
+        checked_ref(customer_ref)
+        body = {"name": name, "customer_ref": customer_ref, "deployer_label": deployer_label}
+        status, answer, attempts = self._call("POST", "/v1/environments", body)
+        if status == 409 and "environment" in answer:
+            existing = Environment.read(answer["environment"])
+            raise EnvironmentExists(
+                f"an Environment for customer_ref {customer_ref!r} exists already ({existing.status}); "
+                "nothing was made"
+                + (
+                    ". An earlier attempt of this call may have made it and lost the answer, and with it "
+                    "the key: new_key(...) gives it a key you then hold"
+                    if attempts > 1
+                    else ""
+                ),
+                existing,
+                maybe_ours=attempts > 1,
+            )
+        if status != 201:
+            raise self._refused("POST", "/v1/environments", status, answer)
+        return self._made(answer)
+
+    def _made(self, answer: dict[str, Any]) -> Made:
+        key, ingest = answer.get("key"), answer.get("ingest_url")
+        if not isinstance(key, str) or not isinstance(ingest, str):
+            raise AccountError("the account API answered without the key or the ingest address")
+        environment = answer.get("environment") or {}
+        if isinstance(environment, dict) and "status" not in environment:
+            environment = {**environment, "status": "live"}
+        return Made(Environment.read(environment), ingest, Secret(key))
+
+    def environments(self, *, status: str | None = None, customer_ref: str | None = None) -> Iterator[Environment]:
+        """Every Environment of the account, page by page, in the order the API keeps them.
+
+        A page goes on only to an offset past its own: a ``next_offset`` that repeats it, goes back or is
+        no number is an :class:`AccountError`, never a loop that asks forever or a listing cut short.
+        """
+        offset = 0
+        while True:
+            query: dict[str, str] = {"limit": "200", "offset": str(offset)}
+            if status is not None:
+                query["status"] = status
+            if customer_ref is not None:
+                query["customer_ref"] = customer_ref
+            path = "/v1/environments?" + urlencode(query)
+            code, answer, _ = self._call("GET", path)
+            if code != 200:
+                raise self._refused("GET", "/v1/environments", code, answer)
+            for given in answer.get("environments") or []:
+                yield Environment.read(given)
+            following = answer.get("next_offset")
+            if following is None:
+                return
+            if not isinstance(following, int) or isinstance(following, bool) or following <= offset:
+                raise AccountError(
+                    f"GET /v1/environments: the API answered next_offset {repr(following)[:40]} to offset "
+                    f"{offset}, which does not move forward, so the listing stops here instead of asking again"
+                )
+            offset = following
+
+    def find(self, customer_ref: str) -> Environment | None:
+        """The open Environment of ``customer_ref``, or None."""
+        for found in self.environments(customer_ref=customer_ref):
+            if found.status != "closed":
+                return found
+        return None
+
+    def new_key(self, environment: str) -> Made:
+        """Replace an Environment's recording key: the old one stops at once, the new one is here once."""
+        path = f"/v1/environments/{quote(environment, safe='')}/key"
+        status, answer, _ = self._call("POST", path)
+        if status != 200:
+            raise self._refused("POST", path, status, answer)
+        return self._made(answer)
+
+    def close(self, environment: str) -> Environment:
+        """Close an Environment when its customer leaves. Its log stays and still exports."""
+        path = f"/v1/environments/{quote(environment, safe='')}/close"
+        status, answer, _ = self._call("POST", path)
+        if status != 200:
+            raise self._refused("POST", path, status, answer)
+        return Environment.read(answer.get("environment") or {})

tallwright_cloud/cli.py

@@ -0,0 +1,333 @@
+# SPDX-License-Identifier: Apache-2.0
+"""``tallwright-cloud``: look at the evidence and the door from a shell, and act on what is pending.
+
+    tallwright-cloud doctor             what stands between this machine and evidence somebody can check
+    tallwright-cloud pending            records sent and never confirmed or refused
+    tallwright-cloud resend [ID ...]    send pending records again, byte for byte (all of this key's when none is named)
+    tallwright-cloud gaps               numbers missing from a session's sequence
+    tallwright-cloud export ID DIR      copy one record's evidence into a folder, for the verifier
+
+The ingest address, the evidence and the key come from ``TALLWRIGHT_INGEST``, ``TALLWRIGHT_EVIDENCE``
+and ``TALLWRIGHT_KEY``, or ``--ingest`` and ``--evidence``. The key is never an argument: an argument is
+visible to every user of the machine in its process list. Evidence in a bucket is
+``s3://bucket/prefix``, read with boto3 and its usual configuration, when boto3 is installed.
+
+The commands read the evidence a client kept and make none: a directory that is not there is said to
+be missing, never created and reported empty. One Environment's evidence is what they read; the store
+``Environments`` writes into holds each customer's beneath its ``customer_ref``, and is said to be one.
+
+Exit codes: 0 nothing stands in the way; 1 something does, and the output says what; 2 the command
+itself was wrong.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+from typing import Any
+
+from . import transport
+from .client import Tallwright
+from .errors import TallwrightError
+from .evidence import DISCLOSURE, LINE, RECEIPT, REFUSED, Evidence
+from .ids import checked_record_id, gaps
+from .store import EvidenceStore, LocalEvidence, S3Evidence, _exclusive, walk
+
+#: The interpreters this package is tested on, in order: its classifiers, and the CI's.
+SUPPORTED = ((3, 11), (3, 12), (3, 13))
+
+
+def _store(where: str | None, *, ephemeral_ok: bool = False) -> EvidenceStore:
+    """The evidence at ``where``, opened as it is: a directory that is not there is not made."""
+    if not where:
+        raise SystemExit("tallwright-cloud: no evidence: --evidence or TALLWRIGHT_EVIDENCE")
+    if where.startswith("s3://"):
+        bucket, _, prefix = where[len("s3://") :].partition("/")
+        try:
+            import boto3  # noqa: PLC0415 - optional, the integrator's
+        except ImportError:
+            raise SystemExit("tallwright-cloud: evidence in a bucket is read with boto3, which is not installed") from None
+        return S3Evidence(boto3.client("s3"), bucket, prefix=prefix)
+    if not Path(where).is_dir():
+        raise FileNotFoundError(
+            f"no evidence directory at {where}: a client makes it when it is made with this path, and these "
+            "commands only read what one kept. Is it the path the client was given?"
+        )
+    return LocalEvidence(where, ephemeral_ok=ephemeral_ok)
+
+
+def _is_record(store: EvidenceStore, name: str) -> bool:
+    """Whether ``name`` is a record's folder: the SDK writes a disclosure and a line into nothing else."""
+    try:
+        return store.read(f"{name}/{DISCLOSURE}") is not None or store.read(f"{name}/{LINE}") is not None
+    except ValueError:  # not a name a record could be kept under
+        return False
+
+
+def _a_customer(store: EvidenceStore) -> str | None:
+    """A ``customer_ref`` whose evidence lies in ``store``, when the store holds customers and not records.
+
+    The first folder at the top that is either decides: a record, and this is one Environment's
+    evidence; a folder whose first entry is a record, and this is the store ``Environments`` writes
+    into, one folder per customer. Anything else is looked past.
+    """
+    for top in Evidence(store).records():
+        if _is_record(store, top):
+            return None
+        inside = [name for name in store.children(top) if not name.startswith(".")]
+        if inside and _is_record(store, f"{top}/{inside[0]}"):
+            return top
+    return None
+
+
+def _records(store: EvidenceStore) -> Evidence:
+    """One Environment's evidence in ``store``; refused, with the folder to name instead, for every customer's."""
+    customer = _a_customer(store)
+    if customer is not None:
+        raise ValueError(
+            f"{store.locate('')} holds each customer's evidence beneath its customer_ref, not records: "
+            f"one customer's is --evidence {store.locate(customer)}"
+        )
+    return Evidence(store)
+
+
+def _key() -> str:
+    key = os.environ.get("TALLWRIGHT_KEY", "")
+    if not key:
+        raise SystemExit("tallwright-cloud: no key: set TALLWRIGHT_KEY (never an argument)")
+    return key
+
+
+def _client(args: argparse.Namespace) -> Tallwright:
+    if not args.ingest:
+        raise SystemExit("tallwright-cloud: no ingest address: --ingest or TALLWRIGHT_INGEST")
+    return Tallwright(args.ingest, _key(), _records(_store(args.evidence, ephemeral_ok=args.ephemeral_ok)).store)
+
+
+def _say(line: str) -> None:
+    print(line)  # noqa: T201
+
+
+def doctor(args: argparse.Namespace) -> int:
+    trouble = 0
+    running = f"{sys.version_info.major}.{sys.version_info.minor}"
+    if (sys.version_info.major, sys.version_info.minor) in SUPPORTED:
+        _say(f"ok      Python {running}")
+    else:  # a note, not a problem: the checks below run on this interpreter and say whether it is in the way
+        lowest, highest = (".".join(map(str, version)) for version in (SUPPORTED[0], SUPPORTED[-1]))
+        _say(f"note    Python {running}: this package is tested on {lowest} to {highest}, not on this one")
+    try:
+        store = _store(args.evidence, ephemeral_ok=args.ephemeral_ok)
+        problems = store.check()
+    except (OSError, ValueError) as failed:
+        problems = [str(failed)]
+        store = None
+    for problem in problems:
+        trouble += 1
+        _say(f"PROBLEM evidence: {problem}")
+    if store is not None and not problems:
+        _say(f"ok      evidence at {store.locate('')} keeps what it is given and never replaces it")
+        customer = _a_customer(store)
+        if customer is not None:
+            _say(
+                f"note    {store.locate('')} holds each customer's evidence beneath its customer_ref: what "
+                f"is pending is counted for one customer, with --evidence {store.locate(customer)}"
+            )
+        else:
+            pending = Evidence(store).pending()
+            _say(f"{'ok     ' if not pending else 'note   '} {len(pending)} record(s) pending in the evidence")
+    if not args.ingest:
+        trouble += 1
+        _say("PROBLEM no ingest address: --ingest or TALLWRIGHT_INGEST")
+        return 1
+    try:
+        endpoint = transport.endpoint(args.ingest)
+    except ValueError as wrong:
+        _say(f"PROBLEM ingest address: {wrong}")
+        return 1
+    try:
+        status, _ = transport.fetch(args.ingest.rstrip("/") + "/healthz", args.timeout, 4096)
+    except OSError as failed:
+        trouble += 1
+        _say(f"PROBLEM the door at {args.ingest} cannot be reached: {type(failed).__name__}: {getattr(failed, 'reason', failed)}")
+        return 1
+    if status == 200:
+        _say(f"ok      the door at {args.ingest} answers, over a certificate this machine trusts")
+    else:
+        trouble += 1
+        _say(f"PROBLEM the door at {args.ingest} answered its liveness probe with {status}")
+    if args.check_key:
+        try:
+            answer = transport.post(endpoint, transport.Key(_key()), b"", args.timeout)
+        except (OSError, ValueError) as failed:
+            trouble += 1
+            _say(f"PROBLEM the key could not be checked: {type(failed).__name__}: {getattr(failed, 'reason', failed)}")
+        else:
+            if answer.status == 200:
+                _say("ok      the door holds this key (an empty batch was sent: nothing was recorded)")
+            else:
+                trouble += 1
+                _say(f"PROBLEM the door answered an empty batch with {answer.status}: {transport.said(answer) or 'no sentence'}")
+    return 1 if trouble else 0
+
+
+def pending(args: argparse.Namespace) -> int:
+    evidence = _records(_store(args.evidence, ephemeral_ok=args.ephemeral_ok))
+    names = evidence.pending() if args.all_keys or not os.environ.get("TALLWRIGHT_KEY") else evidence.pending(transport.Key(_key()).binding())
+    for name in names:
+        _say(name)
+    return 0
+
+
+def resend(args: argparse.Namespace) -> int:
+    if args.adopt and not args.record_ids:
+        _say(
+            "tallwright-cloud resend --adopt: name each record to send with this key. Whether a record "
+            "pending under another key is this Environment's is yours to know, record by record; "
+            "tallwright-cloud pending --all-keys lists them"
+        )
+        return 2
+    client = _client(args)
+    names = args.record_ids or client.pending()
+    others = [] if args.record_ids else sorted(set(Evidence(client.evidence).pending()) - set(names))
+    failed = 0
+    for name in names:
+        try:
+            captured = client.resend(name, adopt=args.adopt)
+        except TallwrightError as problem:
+            failed += 1
+            _say(f"{name}: {type(problem).__name__}: {problem}")
+        else:
+            _say(f"{name}: {captured.receipt.status} at leaf {captured.receipt.leaf_index}")
+    if not names:
+        _say("nothing pending under this key")
+    if others:
+        _say(
+            f"{len(others)} record(s) pending under another key, not sent with this one: tallwright-cloud "
+            "pending --all-keys lists them, and if this key replaced that one for the same Environment, "
+            "tallwright-cloud resend --adopt ID sends each"
+        )
+    return 1 if failed or others else 0
+
+
+def _short_of_the_log(store: EvidenceStore, name: str) -> str:
+    """Why the log is not shown to hold a record kept here, or "" when its receipt is kept."""
+    if store.read(f"{name}/{RECEIPT}") is not None:
+        return ""
+    if store.read(f"{name}/{REFUSED}") is not None:
+        return "refused"
+    return "pending" if store.read(f"{name}/{LINE}") is not None else "never sent"
+
+
+def show_gaps(args: argparse.Namespace) -> int:
+    # A hole is a capture that was numbered and is not in the log. What shows a record in the log here
+    # is its receipt, so a number is a hole when no record of it is kept, and when the record kept was
+    # refused, is pending or was never sent; each is said as what it is.
+    evidence = _records(_store(args.evidence, ephemeral_ok=args.ephemeral_ok))
+    kept = evidence.records()
+    found = {session: dict.fromkeys(missing, "") for session, missing in gaps(kept).items()}
+    for name in kept:
+        for session in gaps([name]):  # once for a name this client minted, <session>.<number>
+            if short := _short_of_the_log(evidence.store, name):
+                found[session][int(name.rpartition(".")[2])] = short
+    holes = 0
+    for session, missing in sorted(found.items()):
+        if missing:
+            holes += len(missing)
+            shown = ", ".join(f"{n} ({missing[n]})" if missing[n] else str(n) for n in sorted(missing)[:20])
+            _say(f"{session}: {len(missing)} missing: {shown}{' …' if len(missing) > 20 else ''}")
+    if holes:
+        _say(
+            "missing: not in the log as far as this evidence shows. A bare number has no record here; "
+            "(refused) the door refused it; (pending) the door has not confirmed it, and resend sends it "
+            "again; (never sent) only its pair was kept"
+        )
+    else:
+        _say(
+            "no hole: up to the highest number of every session, each record's receipt is kept here "
+            "(which says nothing about what was never captured)"
+        )
+    return 1 if holes else 0
+
+
+def _folders(folder: Path) -> None:
+    """``folder`` and each folder above it that is missing, made the owner's alone (0700), as in the store."""
+    missing = []
+    while not folder.exists():
+        missing.append(folder)
+        folder = folder.parent
+    for made in reversed(missing):
+        made.mkdir(mode=0o700, exist_ok=True)
+
+
+def export(args: argparse.Namespace) -> int:
+    store = _records(_store(args.evidence, ephemeral_ok=args.ephemeral_ok)).store
+    name = checked_record_id(args.record_id)
+    if not _is_record(store, name):
+        _say(f"{name}: no such record in {store.locate('')}")
+        return 1
+    target = Path(args.to)
+    copied, disclosed = 0, False
+    for inside in walk(store, name):
+        out = target.joinpath(*inside.split("/")[1:])
+        _folders(out.parent)
+        # The content and the salt, kept as the store keeps them: the owner's alone (0600), and never
+        # over a file already there. Sharing the copy is a person's act, done on purpose.
+        with os.fdopen(_exclusive(out), "wb") as written:
+            written.write(store.read(inside) or b"")
+        copied += 1
+        disclosed = disclosed or inside == f"{name}/{DISCLOSURE}"
+    opened = (
+        f"evidence-verify reads the disclosure at {target / DISCLOSURE}"
+        if disclosed
+        else f"it holds no {DISCLOSURE}, so nobody can open what it commits to"
+    )
+    _say(f"{name}: {copied} file(s) in {target}; {opened}")
+    return 0
+
+
+def parser() -> argparse.ArgumentParser:
+    top = argparse.ArgumentParser(description=__doc__.split("\n\n")[0])
+    common: dict[str, Any] = {}
+    sub = top.add_subparsers(dest="command", required=True)
+    for name, run, help_ in (
+        ("doctor", doctor, "what stands between this machine and evidence somebody can check"),
+        ("pending", pending, "records sent and never confirmed or refused"),
+        ("resend", resend, "send pending records again, byte for byte"),
+        ("gaps", show_gaps, "numbers missing from a session's sequence"),
+        ("export", export, "copy one record's evidence into a folder"),
+    ):
+        command = sub.add_parser(name, help=help_, **common)
+        command.set_defaults(run=run)
+        command.add_argument("--evidence", default=os.environ.get("TALLWRIGHT_EVIDENCE"))
+        command.add_argument("--ephemeral-ok", action="store_true", help="accept evidence on a file system that ends with its container")
+        if name in ("doctor", "resend"):
+            command.add_argument("--ingest", default=os.environ.get("TALLWRIGHT_INGEST"))
+        if name == "doctor":
+            command.add_argument("--timeout", type=float, default=10.0)
+            command.add_argument("--check-key", action="store_true", help="send an empty batch to check the key; records nothing")
+        if name == "pending":
+            command.add_argument("--all-keys", action="store_true", help="also records pending under another key")
+        if name == "resend":
+            command.add_argument("record_ids", nargs="*")
+            command.add_argument("--adopt", action="store_true", help="send the records named, pending under a replaced key, with this one")
+        if name == "export":
+            command.add_argument("record_id")
+            command.add_argument("to")
+    return top
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    args = parser().parse_args(argv)
+    try:
+        return int(args.run(args))
+    except (TallwrightError, OSError, ValueError) as failed:
+        _say(f"tallwright-cloud: {type(failed).__name__}: {failed}")
+        return 1
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())