runningtab 0.1.0.dev3__py3-none-any.whl

runningtab/mercury/receipts.py

@@ -0,0 +1,304 @@
+"""The receipt Mercury holds, attached to the Bank Transaction it belongs to.
+
+A Mercury transaction carries the receipts somebody uploaded against it as
+`attachments`, each a presigned S3 URL good for twelve hours. This module
+fetches them and attaches them, private, to that transaction's **Bank
+Transaction** -- the bank's record of the row, which exists for every settled
+transaction, rather than the draft voucher, which exists only for the coded
+ones and which a person may take over or delete. A reviewer reading a draft is
+one hop away: its `remark` ends with the Mercury id the receipt hangs off.
+
+Identity is the attachment UUID out of the S3 path, carried into the `File` as
+`<uuid>-<fileName>`, so a run can compare what is already on the row against
+what Mercury reports without downloading anything. A missing one is fetched and
+uploaded; one already there is left alone.
+
+**Nothing here deletes or replaces a `File`, ever** -- not one this wrote, and
+not one it did not. A receipt a person can see on the bank's record is their
+record, no re-run reproduces it (the URL behind it expired), and Mercury
+dropping an attachment is not a reason to take a document away from somebody.
+A `File` on the row with no UUID prefix is somebody else's and is left alone
+without a report line, for the reason the voucher pass says nothing about a
+draft a person has edited.
+
+The fetch is a GET to S3, not to Mercury's API host, which is why it lives here
+and not on `MercuryClient`: that class's promise is that the only verb it can
+send is GET against one base URL, and an honest promise is better than one with
+an asterisk on it.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import re
+from collections.abc import Iterable
+
+import httpx2
+from icedcoffee_sync.frappe.errors import FrappeError, PermissionError_, RateLimitError
+
+from runningtab.mercury.models import Attachment, Transaction
+from runningtab.mercury.posting import BANK_TRANSACTION, Ledger, PostingError, find_existing, plain_message
+
+FILE = "File"
+
+# What one receipt may weigh. A scanned invoice is a few hundred kilobytes and
+# a phone photograph a few megabytes; twenty is generous for both and small
+# enough that a run cannot be made to buffer something absurd. The stream is
+# measured as it arrives and abandoned at the limit, so an enormous file costs
+# this much traffic and not its own size.
+RECEIPT_SIZE_LIMIT = 20 * 1024 * 1024
+
+# Frappe stores `File.file_name` in a `Data` column, which is 140 characters.
+# A longer name would be refused by the server, or silently cut somewhere we
+# did not choose.
+FILE_NAME_LIMIT = 140
+
+_UUID = r"[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}"
+
+# The `<uuid>-` prefix this module writes, read back off a `File` that is
+# already on the row. Anchored and case-insensitive; a name that does not match
+# was not written here.
+_OURS = re.compile(rf"^(?P<id>{_UUID})-", re.IGNORECASE)
+
+# What Frappe itself strips from a `file_name` on save (`File.set_file_name`
+# removes `/`). The newline is ours: it would break the multipart header this
+# name rides in long before Frappe ever saw it.
+_UNSAFE = re.compile(r"[/\r\n]")
+
+# The name given to an attachment whose own is empty once sanitised. It never
+# stands alone -- the UUID prefix is what identifies the file -- so it only has
+# to be a word rather than a blank.
+_UNNAMED = "receipt"
+
+
+class ReceiptError(RuntimeError):
+    """A receipt could not be fetched. One report line; the run goes on."""
+
+
+class ReceiptTooLargeError(ReceiptError):
+    """The receipt is past `RECEIPT_SIZE_LIMIT` and was abandoned mid-stream."""
+
+
+@dataclasses.dataclass
+class ReceiptReport:
+    """What one receipt pass did. Folded into the run's `IngestReport` by the caller.
+
+    Returned rather than written into `IngestReport` directly so this module
+    has no import back into `ingest`, and so its whole decision table is
+    exercisable without a run.
+    """
+
+    # `<file name> -> <Bank Transaction name>`, one per upload.
+    attached: list[str] = dataclasses.field(default_factory=list)
+    planned: list[str] = dataclasses.field(default_factory=list)
+    attention: list[tuple[str, str]] = dataclasses.field(default_factory=list)
+
+
+def _trimmed(name: str, limit: int) -> str:
+    """A file name cut to `limit`, keeping its extension.
+
+    The extension is what tells a person -- and Frappe's own PDF scan -- what
+    the file is, so it survives and the middle of the name goes.
+    """
+    if len(name) <= limit:
+        return name
+    stem, dot, extension = name.rpartition(".")
+    if dot and len(extension) + 1 < limit:
+        return f"{stem[: limit - len(extension) - 1]}.{extension}"
+    return name[:limit]
+
+
+def file_name_for(attachment: Attachment, identity: str) -> str:
+    """The `File.file_name` one attachment becomes: `<uuid>-<sanitised fileName>`.
+
+    Sanitised the way Frappe would sanitise it, so the name sent is the name
+    that comes back and the comparison on the next run is against what we
+    wrote. The UUID prefix is fixed-width hex and dashes, so the trim to the
+    column's 140 characters can never reach it.
+    """
+    name = _UNSAFE.sub("", attachment.file_name).strip() or _UNNAMED
+    return f"{identity}-{_trimmed(name, FILE_NAME_LIMIT - len(identity) - 1)}"
+
+
+def attachment_id_of(file_name: str) -> str | None:
+    """The attachment UUID a `File` we wrote carries, or None for one we did not."""
+    match = _OURS.match(file_name or "")
+    return match["id"].lower() if match else None
+
+
+class ReceiptFetcher:
+    """Downloads one presigned receipt URL, streamed, with a size cap.
+
+    Its own client rather than the Mercury one: this reaches S3 with the
+    signature in the query string, not Mercury's API host with a bearer token,
+    and the two have no header, base URL or timeout in common.
+
+    A context manager, so the connection pool closes with the run that opened
+    it. Redirects are followed because S3 answers a cross-region read with one.
+    """
+
+    def __init__(
+        self,
+        *,
+        transport: httpx2.BaseTransport | None = None,
+        timeout: float = 60.0,
+        size_limit: int = RECEIPT_SIZE_LIMIT,
+    ) -> None:
+        self.size_limit = size_limit
+        self._http = httpx2.Client(timeout=timeout, transport=transport, follow_redirects=True)
+
+    def __enter__(self) -> ReceiptFetcher:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def close(self) -> None:
+        """Release the underlying connection pool."""
+        self._http.close()
+
+    def fetch(self, url: str) -> bytes:
+        """The receipt's bytes, or `ReceiptError` describing why there are none.
+
+        Everything that can go wrong with one download comes back as one
+        exception type, because the caller does the same thing with all of
+        them: name the row, name the file, and carry on with the rest of the
+        run. Ending the run instead would cost every other receipt in it, and
+        the URLs expire twelve hours after Mercury minted them.
+        """
+        try:
+            with self._http.stream("GET", url) as response:
+                if response.status_code >= 400:
+                    response.read()
+                    raise ReceiptError(f"the receipt URL answered {response.status_code}: {response.text[:200]}")
+                chunks: list[bytes] = []
+                size = 0
+                for chunk in response.iter_bytes():
+                    size += len(chunk)
+                    if size > self.size_limit:
+                        raise ReceiptTooLargeError(
+                            f"the receipt is larger than the {self.size_limit} byte limit; "
+                            "a person downloads it from Mercury and attaches it"
+                        )
+                    chunks.append(chunk)
+        except httpx2.RequestError as exc:
+            raise ReceiptError(f"the receipt could not be fetched: {exc!r}") from exc
+        return b"".join(chunks)
+
+
+def receipts_on(ledger: Ledger, name: str) -> dict[str, str]:
+    """The attachment UUIDs already on one Bank Transaction, mapped to their `File` names.
+
+    Paged with `iter_all` rather than one capped `list`: a read cut short at a
+    page limit looks exactly like "that receipt is not attached yet", which is
+    the answer that uploads a second copy.
+
+    A `File` whose name carries no UUID prefix is not in the result and is not
+    reported. Somebody attached it, or another integration did; it is not this
+    module's business either way.
+    """
+    have: dict[str, str] = {}
+    for row in ledger.iter_all(
+        FILE,
+        fields=["name", "file_name"],
+        filters=[["attached_to_doctype", "=", BANK_TRANSACTION], ["attached_to_name", "=", name]],
+    ):
+        identity = attachment_id_of(str(row.get("file_name") or ""))
+        if identity is not None:
+            have[identity] = str(row.get("name", ""))
+    return have
+
+
+def _attach(
+    ledger: Ledger,
+    transaction: Transaction,
+    attachment: Attachment,
+    row: str,
+    have: dict[str, str],
+    report: ReceiptReport,
+    *,
+    fetcher: ReceiptFetcher,
+    dry_run: bool,
+) -> None:
+    """Put one attachment on one Bank Transaction, or say why it is not there.
+
+    A refusal of this upload is a report line and the run goes on, mirroring
+    `ingest._write`. A site that is rate limiting us and a credential it will
+    not accept are each one problem the whole run has rather than one file's,
+    so they propagate: a line per receipt would bury the single real problem.
+    """
+    identity = attachment.attachment_id
+    if identity is None:
+        report.attention.append((
+            transaction.id,
+            f"the receipt {attachment.file_name!r} has no id in its URL path, so no run can tell it from one "
+            "already attached and every run would attach it again; a person downloads it from Mercury",
+        ))
+        return
+    if identity in have:
+        return
+    name = file_name_for(attachment, identity)
+    if dry_run:
+        report.planned.append(f"attach {name} to {BANK_TRANSACTION} {row} for {transaction.id}")
+        return
+    try:
+        content = fetcher.fetch(attachment.url)
+    except ReceiptError as exc:
+        report.attention.append((transaction.id, f"receipt {name}: {exc}"))
+        return
+    try:
+        # `is_private` stated rather than inherited: a receipt is financial
+        # evidence and has no business behind a world-readable URL.
+        ledger.upload_file(BANK_TRANSACTION, row, name, content, is_private=True)
+    except RateLimitError, PermissionError_:
+        raise
+    except FrappeError as exc:
+        report.attention.append((
+            transaction.id,
+            f"attaching {name} to {BANK_TRANSACTION} {row} refused by the ledger: {plain_message(str(exc))}",
+        ))
+        return
+    have[identity] = name
+    report.attached.append(f"{name} -> {row}")
+
+
+def attach_receipts(
+    transactions: Iterable[Transaction],
+    ledger: Ledger,
+    *,
+    fetcher: ReceiptFetcher,
+    dry_run: bool = False,
+) -> ReceiptReport:
+    """Attach every Mercury receipt its Bank Transaction does not already carry.
+
+    Sweep-shaped, and it has to be, for the reason the GL-code hint sweep and
+    the voucher pass already are: **the attachment list emits no event.** That
+    is an assumption rather than a measurement -- nobody has captured an event
+    for an attachment upload -- but the two neighbouring fields we do know
+    about, the GL code and the note, provably emit none, and if an event does
+    turn out to fire the only cost is that this comparison finds nothing new.
+    It adds no Mercury read: the run already fetched every transaction for the
+    balance invariant.
+
+    Two rows are skipped in silence. One with **no Bank Transaction** has
+    nothing to attach to, and a settled row that failed to post has already
+    produced its own report line from the Bank Transaction path. One whose Bank
+    Transaction is **cancelled** was cancelled by a person deliberately;
+    whatever replaces it is a new row, and the receipt lands there.
+    """
+    report = ReceiptReport()
+    for transaction in transactions:
+        if not transaction.attachments:
+            continue
+        try:
+            existing = find_existing(ledger, transaction.id)
+        except PostingError as exc:
+            report.attention.append((transaction.id, str(exc)))
+            continue
+        if existing is None or int(existing.get("docstatus") or 0) == 2:
+            continue
+        row = str(existing["name"])
+        have = receipts_on(ledger, row)
+        for attachment in transaction.attachments:
+            _attach(ledger, transaction, attachment, row, have, report, fetcher=fetcher, dry_run=dry_run)
+    return report

runningtab/mercury/session.py

@@ -0,0 +1,65 @@
+"""Assembling a `PostingContext` from a live site, the chart, and the mapping.
+
+Kept out of `runningtab.cli` so the wiring is testable without a terminal, and out of
+`posting.py` so that module stays pure enough to exercise against captured
+payloads alone.
+"""
+
+from __future__ import annotations
+
+from icedcoffee_sync.apply.model import DesiredAccount
+from icedcoffee_sync.erpnext.accounts import read_chart
+from icedcoffee_sync.frappe.client import Client
+
+from runningtab.coa import sole_company
+from runningtab.mercury.client import MercuryClient
+from runningtab.mercury.mapping import Mapping, MappingError, validate_against_chart
+from runningtab.mercury.posting import PostingContext
+from runningtab.mercury.vouchers import Chart
+from runningtab.period.lock import read_visible_lock
+from runningtab.site import Profile
+
+
+def posting_context(
+    ledger: Client,
+    *,
+    mapping: Mapping,
+    chart: list[DesiredAccount],
+    bot_user: str,
+    mercury: MercuryClient | None = None,
+    company: str | None = None,
+) -> PostingContext:
+    """Everything a Bank Transaction needs that is not on the transaction.
+
+    Account document names come from the **live site**, not from rendering the
+    chart: an account's document name derives from its number and title, so a
+    site whose chart has not been applied yet would otherwise produce links that
+    look right and resolve to nothing.
+
+    Books Closed Through is read here too, alongside Company -- the one read
+    this module already makes -- so the voucher pass can leave a closed
+    quarter's rows to a person. A bot that cannot see the permlevel-1 lock
+    fields (never re-provisioned with its Company read grant, or a provision
+    that installed the fence and then failed) is refused by name, before
+    anything is posted: Frappe deletes the fields rather than returning them
+    empty, so reading on would treat a closed quarter as open. Nothing else
+    would catch that. ERPNext checks the frozen date only when GL entries
+    are made, on submit, and the ingest saves its vouchers as drafts.
+    """
+    unknown = validate_against_chart(mapping, {a.number for a in chart})
+    if unknown:
+        raise MappingError(f"mercury.toml names accounts the chart does not have: {', '.join(unknown)}")
+    company = company or sole_company(ledger)
+    # First, so a bot that cannot see the lock is refused before any other read.
+    lock = read_visible_lock(ledger, company, Profile.BOT)
+    account_names = {a.number: a.document_name for a in read_chart(ledger, company) if a.number}
+    mercury_names = {a.id: a.name for a in mercury.accounts()} if mercury is not None else {}
+    return PostingContext(
+        company=company,
+        account_names=account_names,
+        mapping=mapping,
+        bot_user=bot_user,
+        chart=Chart.load(chart),
+        mercury_account_names=mercury_names,
+        lock=lock,
+    )

runningtab/mercury/state.py

@@ -0,0 +1,285 @@
+"""Where the ingest keeps its place in the event log.
+
+Three things live here and nothing else: the cursor, the set of event ids
+already applied, and the highest `resourceVersion` seen per resource. SQLite
+rather than a JSON document because the applier commits after each event -- a
+run that dies halfway keeps everything it already applied, instead of losing a
+batch that was going to be written out at the end.
+
+What deliberately does **not** live here is which ERPNext document was posted
+for a Mercury transaction. That lookup is the `mercury_transaction_id` custom
+field on the document itself, so losing this file can never cause a double
+post: it costs a re-read, not a duplicate entry.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import datetime as dt
+import os
+import pathlib
+import sqlite3
+
+# Mercury retains events for 90 days. A cursor older than that may point into a
+# hole the log can no longer fill, and resuming from it would skip whatever
+# happened in the gap without anything looking wrong.
+RETENTION = dt.timedelta(days=90)
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS ingest_identity (
+    id INTEGER PRIMARY KEY CHECK (id = 1),
+    identity TEXT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS ingest_cursor (
+    id INTEGER PRIMARY KEY CHECK (id = 1),
+    event_id TEXT,
+    synced_at TEXT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS seen_event (
+    event_id TEXT PRIMARY KEY,
+    applied_at TEXT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS resource_version (
+    resource_id TEXT PRIMARY KEY,
+    version INTEGER NOT NULL
+);
+"""
+
+
+class NoCursorError(RuntimeError):
+    """Nothing has been snapshotted yet, so there is no place in the log to resume from."""
+
+
+class StaleCursorError(RuntimeError):
+    """The cursor is older than Mercury's retention window; re-snapshot rather than resume."""
+
+
+class StateIdentityError(RuntimeError):
+    """This state file belongs to a different Mercury deployment or ledger."""
+
+
+@dataclasses.dataclass(frozen=True)
+class Cursor:
+    """Where the last run stopped, and when it stopped there.
+
+    `synced_at` is our clock, not the event's. The retention rule needs to know
+    how long ago we last read the log, which is a fact about us; the event's own
+    timestamp field was never recorded by the investigation, and guessing its
+    name to answer a question we can already answer would be a worse trade.
+    """
+
+    event_id: str | None
+    synced_at: dt.datetime
+
+
+def default_state_path(books_name: str, env: str, target: str) -> pathlib.Path:
+    """`$XDG_STATE_HOME/<name>-books/mercury-<env>-<target>.sqlite3`, or the `~/.local/state` fallback.
+
+    One file per set of books, Mercury deployment and ledger, never one shared
+    file. A cursor is a place in one bank's event log, and the rows it
+    accounts for are in one ledger; a snapshot taken against the sandbox and a
+    test site would otherwise look to the production feed like a place it can
+    resume from, and everything before that cursor would be skipped with
+    nothing looking wrong. `books_name` is `books.toml`'s name, lowercased.
+    """
+    root = os.environ.get("XDG_STATE_HOME")
+    base = pathlib.Path(root) if root else pathlib.Path.home() / ".local" / "state"
+    return base / f"{books_name.lower()}-books" / f"mercury-{env}-{target}.sqlite3"
+
+
+class IngestState:
+    """The ingest's place in the log. One writer, committed per call.
+
+    `identity` names the Mercury deployment and ledger this file belongs to,
+    as `"<env>/<target>"`. It is recorded when an empty file is first used and
+    checked on every later open, because `--state` can point at any file the
+    namespaced default path was arranged to keep apart. A file that already
+    holds a cursor but names no deployment is refused rather than adopted:
+    there is nothing to check against, and a file predating the binding is
+    exactly one that may have been written by another deployment. Omitting the
+    identity -- which only tests do -- binds nothing and checks nothing.
+    """
+
+    def __init__(self, path: pathlib.Path, *, identity: str | None = None) -> None:
+        self.path = path
+        path.parent.mkdir(parents=True, exist_ok=True)
+        self._db = sqlite3.connect(path)
+        self._db.executescript(_SCHEMA)
+        self._db.commit()
+        if identity is not None:
+            self._bind(identity)
+
+    def _is_empty(self) -> bool:
+        """Whether this file has nothing to lose: no cursor, no applied events, no versions."""
+        return all(
+            self._db.execute(query).fetchone() is None
+            for query in (
+                "SELECT 1 FROM ingest_cursor WHERE id = 1",
+                "SELECT 1 FROM seen_event LIMIT 1",
+                "SELECT 1 FROM resource_version LIMIT 1",
+            )
+        )
+
+    def _bind(self, identity: str) -> None:
+        """Claim an empty file, or refuse one that belongs to -- or might belong to -- another ingest."""
+        row = self._db.execute("SELECT identity FROM ingest_identity WHERE id = 1").fetchone()
+        if row is not None and row[0] != identity:
+            self.close()
+            raise StateIdentityError(
+                f"{self.path} holds the state of {row[0]} and this run is {identity}; "
+                "a cursor is a place in one bank's log and its rows are in one ledger, so resuming "
+                "from the wrong file would skip everything before an event this deployment never emitted"
+            )
+        if row is not None:
+            return
+        if not self._is_empty():
+            # Claiming a populated file would bless whatever cursor it holds as
+            # this deployment's, which is the confusion the binding exists to
+            # prevent -- and a file predating the binding is exactly one that
+            # may have been written against another deployment.
+            self.close()
+            raise StateIdentityError(
+                f"{self.path} already holds ingest state but names no deployment, so there is "
+                f"nothing to check {identity} against; snapshot into a fresh file rather than "
+                "adopting one whose bank and ledger cannot be established"
+            )
+        self._db.execute("INSERT INTO ingest_identity (id, identity) VALUES (1, ?)", (identity,))
+        self._db.commit()
+
+    def __enter__(self) -> IngestState:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def close(self) -> None:
+        """Close the database handle."""
+        self._db.close()
+
+    # --- cursor -----------------------------------------------------------
+
+    def cursor(self) -> Cursor | None:
+        """Where the last snapshot or sync left off, or None if there has never been one."""
+        row = self._db.execute("SELECT event_id, synced_at FROM ingest_cursor WHERE id = 1").fetchone()
+        if row is None:
+            return None
+        return Cursor(event_id=row[0], synced_at=dt.datetime.fromisoformat(row[1]))
+
+    def record_cursor(self, event_id: str | None, at: dt.datetime) -> None:
+        """Move the cursor to `event_id` as of `at`.
+
+        A None `event_id` is a real state, not a missing one: an account whose
+        event log is empty has been read completely, and the next sync starts
+        from the beginning of the log rather than refusing.
+        """
+        self._db.execute(
+            "INSERT INTO ingest_cursor (id, event_id, synced_at) VALUES (1, ?, ?) "
+            "ON CONFLICT(id) DO UPDATE SET event_id = excluded.event_id, synced_at = excluded.synced_at",
+            (event_id, at.isoformat()),
+        )
+        self._db.commit()
+
+    def require_resumable(self, now: dt.datetime) -> Cursor:
+        """The cursor, if resuming from it can still be complete.
+
+        Raises rather than resuming into a hole: past the retention window the
+        log cannot tell us what we missed, and the honest recovery is another
+        snapshot.
+        """
+        cursor = self.cursor()
+        if cursor is None:
+            raise NoCursorError("no cursor recorded; run `runningtab mercury snapshot` before syncing")
+        age = now - cursor.synced_at
+        if age > RETENTION:
+            raise StaleCursorError(
+                f"last sync was {age.days} days ago and Mercury retains events for {RETENTION.days}; "
+                "the cursor may point into a gap the log can no longer fill -- re-snapshot instead of resuming"
+            )
+        return cursor
+
+    # --- dedup ------------------------------------------------------------
+
+    def has_seen(self, event_id: str) -> bool:
+        """Whether this event id has already been applied. Mercury delivers at-least-once."""
+        return self._db.execute("SELECT 1 FROM seen_event WHERE event_id = ?", (event_id,)).fetchone() is not None
+
+    def mark_seen(self, event_id: str, at: dt.datetime) -> None:
+        """Record an event id as applied, whether it changed anything or not.
+
+        An event skipped by the version guard is still recorded: it has been
+        considered, and reconsidering it on the next delivery would reach the
+        same conclusion more slowly.
+        """
+        self._db.execute(
+            "INSERT INTO seen_event (event_id, applied_at) VALUES (?, ?) ON CONFLICT(event_id) DO NOTHING",
+            (event_id, at.isoformat()),
+        )
+        self._db.commit()
+
+    def seen_count(self) -> int:
+        """How many event ids have been recorded. For `runningtab mercury status`."""
+        return int(self._db.execute("SELECT COUNT(*) FROM seen_event").fetchone()[0])
+
+    # --- ordering ---------------------------------------------------------
+
+    def version_of(self, resource_id: str) -> int | None:
+        """The highest `resourceVersion` applied for a resource, or None."""
+        row = self._db.execute("SELECT version FROM resource_version WHERE resource_id = ?", (resource_id,)).fetchone()
+        return None if row is None else int(row[0])
+
+    def record_version(self, resource_id: str, version: int) -> None:
+        """Raise a resource's high-water mark. Never lowers it: a late replay must not reopen the past."""
+        self._db.execute(
+            "INSERT INTO resource_version (resource_id, version) VALUES (?, ?) "
+            "ON CONFLICT(resource_id) DO UPDATE SET version = MAX(version, excluded.version)",
+            (resource_id, version),
+        )
+        self._db.commit()
+
+
+class DryRunState:
+    """An `IngestState` that remembers for the length of one run and then forgets.
+
+    So a dry run answers the question people actually ask it -- "what would a
+    real run do?" -- rather than a slightly different one. Buffering the writes
+    here instead of branching on `dry_run` at every write means the applier
+    takes the same path either way; the only thing a dry run skips is the
+    ledger write itself.
+    """
+
+    def __init__(self, inner: IngestState) -> None:
+        self._inner = inner
+        self._seen: set[str] = set()
+        self._versions: dict[str, int] = {}
+
+    def cursor(self) -> Cursor | None:
+        return self._inner.cursor()
+
+    def require_resumable(self, now: dt.datetime) -> Cursor:
+        return self._inner.require_resumable(now)
+
+    def record_cursor(self, event_id: str | None, at: dt.datetime) -> None:
+        """Deliberately nothing: a dry run must not move the real cursor."""
+
+    def has_seen(self, event_id: str) -> bool:
+        return event_id in self._seen or self._inner.has_seen(event_id)
+
+    def mark_seen(self, event_id: str, at: dt.datetime) -> None:
+        self._seen.add(event_id)
+
+    def seen_count(self) -> int:
+        return self._inner.seen_count() + len(self._seen)
+
+    def version_of(self, resource_id: str) -> int | None:
+        buffered = self._versions.get(resource_id)
+        recorded = self._inner.version_of(resource_id)
+        if buffered is None:
+            return recorded
+        return buffered if recorded is None else max(buffered, recorded)
+
+    def record_version(self, resource_id: str, version: int) -> None:
+        self._versions[resource_id] = max(self._versions.get(resource_id, version), version)
+
+
+type State = IngestState | DryRunState
+"""What the applier writes its place to: the real file, or a run-scoped buffer."""