runningtab 0.1.0.dev3__py3-none-any.whl

runningtab/period/qbo_map.py

@@ -0,0 +1,174 @@
+"""What QuickBooks Online needs to know about our chart, from `qbo.toml`.
+
+Explicit per account rather than a rule on root and account type: 62 lines a
+person can read beat an engine whose output they have to predict.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import pathlib
+import tomllib
+from collections.abc import Sequence
+from typing import Any
+
+from icedcoffee_sync.apply.model import DesiredAccount
+
+from runningtab.period import PeriodError
+
+CLEARING_ACCOUNT_NAME = "QBO Import Clearing"
+
+# What a [builtin] entry's `role` may say, and the ERPNext fact on the chart
+# account it names that must then be true -- the cross-check
+# `validate_qbo_map` runs so that an entry naming the wrong QBO built-in (the
+# two swapped, say) is refused instead of quietly posting balances to the
+# wrong QuickBooks account.
+BUILTIN_ROLES = frozenset({"receivable", "payable", "retained_earnings"})
+
+
+@dataclasses.dataclass(frozen=True)
+class BuiltinAccount:
+    """A chart account QBO already carries by default: its QBO name, and which of the three builtins it is."""
+
+    name: str
+    role: str  # one of BUILTIN_ROLES
+
+
+@dataclasses.dataclass(frozen=True)
+class QboMap:
+    types: dict[str, frozenset[str]]
+    accounts: dict[str, tuple[str, str]]
+    builtin: dict[str, BuiltinAccount]
+    clearing: tuple[str, str]
+
+
+def _table(data: dict[str, Any], key: str) -> dict[str, Any]:
+    value = data.get(key)
+    if not isinstance(value, dict):
+        raise PeriodError(f"qbo.toml has no [{key}] table")
+    return value
+
+
+def _expect_list_of_str(value: Any, where: str, problems: list[str]) -> list[str] | None:
+    if isinstance(value, list) and all(isinstance(item, str) for item in value):
+        return value
+    problems.append(f"{where}: expected a list of strings, got {value!r}")
+    return None
+
+
+def _expect_str(value: Any, where: str, problems: list[str]) -> str:
+    """Return `value` if it is a string, else record the problem and return a placeholder.
+
+    The placeholder is never read: every caller only uses the return value
+    after `parse_qbo_map` has raised on a non-empty `problems`.
+    """
+    if isinstance(value, str):
+        return value
+    problems.append(f"{where}: expected a string, got {value!r}")
+    return ""
+
+
+def parse_qbo_map(text: str) -> QboMap:
+    """Parse `qbo.toml`, or raise `PeriodError` naming every malformed entry at once.
+
+    A hand edit that gets a shape wrong -- a bare string where `[Type, Detail
+    Type]` belongs, a one-element list, a number -- must be refused by name,
+    not silently misread or left to crash on a raw Python `IndexError` or
+    `TypeError` a person editing the file would never connect to their typo.
+    """
+    data: dict[str, Any] = tomllib.loads(text)
+    problems: list[str] = []
+
+    types: dict[str, frozenset[str]] = {}
+    for key, value in _table(data, "types").items():
+        detail_types = _expect_list_of_str(value, f"[types] {key!r}", problems)
+        if detail_types is not None:
+            types[str(key)] = frozenset(detail_types)
+
+    accounts: dict[str, tuple[str, str]] = {}
+    for key, value in _table(data, "accounts").items():
+        if isinstance(value, list) and len(value) == 2 and all(isinstance(item, str) for item in value):
+            accounts[str(key)] = (value[0], value[1])
+        else:
+            problems.append(f"[accounts] {key!r}: expected [Type, Detail Type], got {value!r}")
+
+    builtin: dict[str, BuiltinAccount] = {}
+    for key, value in _table(data, "builtin").items():
+        if not isinstance(value, dict):
+            problems.append(f"[builtin] {key!r}: expected {{name = ..., role = ...}}, got {value!r}")
+            continue
+        name = _expect_str(value.get("name"), f"[builtin] {key!r} 'name'", problems)
+        role = _expect_str(value.get("role"), f"[builtin] {key!r} 'role'", problems)
+        if role and role not in BUILTIN_ROLES:
+            problems.append(f"[builtin] {key!r} 'role': {role!r} is not one of {sorted(BUILTIN_ROLES)}")
+        builtin[str(key)] = BuiltinAccount(name, role)
+
+    clearing_raw = _table(data, "clearing")
+    clearing_type = _expect_str(clearing_raw.get("type"), "[clearing] 'type'", problems)
+    clearing_detail = _expect_str(clearing_raw.get("detail"), "[clearing] 'detail'", problems)
+
+    if problems:
+        raise PeriodError("qbo.toml is malformed:\n  " + "\n  ".join(problems))
+
+    return QboMap(types, accounts, builtin, (clearing_type, clearing_detail))
+
+
+def load_qbo_map(path: pathlib.Path) -> QboMap:
+    return parse_qbo_map(path.read_text(encoding="utf-8"))
+
+
+_ROLE_MATCHES: dict[str, Any] = {
+    "receivable": lambda a: a.account_type == "Receivable",
+    "payable": lambda a: a.account_type == "Payable",
+    "retained_earnings": lambda a: a.root_type == "Equity",
+}
+
+
+def _builtin_role_problems(qmap: QboMap, by_number: dict[str, DesiredAccount]) -> list[str]:
+    """A problem per [builtin] entry whose chart account isn't actually its `role`'s ERPNext type.
+
+    `role` names which of QBO's three built-in accounts a chart account
+    stands in for; independently of what its `name` says, the account must
+    actually be that role's type -- otherwise the two could have been
+    swapped (Receivable given Payable's role, say) with nothing else in this
+    file catching it, and balances would post to the wrong QuickBooks
+    account despite `check_replay` passing (it only checks the kit
+    reproduces itself, not that qbo.toml named the right accounts to begin
+    with).
+    """
+    problems: list[str] = []
+    for number, entry in sorted(qmap.builtin.items()):
+        account = by_number.get(number)
+        matches = _ROLE_MATCHES.get(entry.role)
+        if account is None or matches is None:
+            continue  # already reported by the "not in chart.coa" or role-enum check
+        if not matches(account):
+            actual = account.account_type or account.root_type
+            problems.append(f"{number} ({actual!r}): [builtin] role {entry.role!r} does not match")
+    return problems
+
+
+def validate_qbo_map(qmap: QboMap, chart: Sequence[DesiredAccount]) -> None:
+    """Refuse, naming every problem, a map the import kit could not be built from."""
+    by_number = {a.number: a for a in chart}
+    postable = {a.number for a in chart if not a.is_group}
+    problems: list[str] = []
+    for number in sorted(postable - qmap.accounts.keys() - qmap.builtin.keys()):
+        problems.append(f"{number} {by_number[number].name}: no entry in [accounts] or [builtin]")
+    for number in sorted(qmap.accounts.keys() & qmap.builtin.keys()):
+        problems.append(f"{number}: in both [accounts] and [builtin]")
+    for number in sorted((qmap.accounts.keys() | qmap.builtin.keys()) - postable):
+        problems.append(f"{number}: not a postable account in chart.coa")
+    for number, (qtype, detail) in sorted([*qmap.accounts.items(), ("clearing", qmap.clearing)]):
+        if detail not in qmap.types.get(qtype, frozenset()):
+            problems.append(f"{number}: {qtype!r} / {detail!r} is not a Type and Detail Type listed in [types]")
+    problems.extend(_builtin_role_problems(qmap, by_number))
+    names = (
+        [by_number[n].name for n in qmap.accounts if n in by_number]
+        + [entry.name for entry in qmap.builtin.values()]
+        + [CLEARING_ACCOUNT_NAME]
+    )
+    for name in sorted({n for n in names if names.count(n) > 1}):
+        problems.append(f"{name!r}: more than one account would import under this name")
+    if problems:
+        raise PeriodError("qbo.toml cannot build the import kit:\n  " + "\n  ".join(problems))

runningtab/period/quarter.py

@@ -0,0 +1,90 @@
+"""Calendar quarters, and the ERPNext Fiscal Year each must sit inside."""
+
+from __future__ import annotations
+
+import dataclasses
+import datetime as dt
+import re
+from collections.abc import Sequence
+
+from runningtab.period import PeriodError
+
+_QUARTER = re.compile(r"(?P<year>\d{4})Q(?P<number>[1-4])")
+
+
+@dataclasses.dataclass(frozen=True, order=True)
+class Quarter:
+    """One calendar quarter, named the way the command line takes it: `2026Q3`."""
+
+    year: int
+    number: int
+
+    @classmethod
+    def parse(cls, text: str) -> Quarter:
+        # `\d{4}` matches "0000"; `dt.date`'s minimum year is 1, so "0000Q1"
+        # parsed clean and only failed later, with a bare ValueError, the
+        # first time something touched `.start` or `.end`.
+        match = _QUARTER.fullmatch(text)
+        if match is None or int(match["year"]) < 1:
+            raise PeriodError(f"{text!r} is not a quarter; write it as YYYYQn, e.g. 2026Q3")
+        return cls(int(match["year"]), int(match["number"]))
+
+    @classmethod
+    def containing(cls, date: dt.date) -> Quarter:
+        """The quarter `date` falls in."""
+        return cls(date.year, (date.month - 1) // 3 + 1)
+
+    @property
+    def previous(self) -> Quarter:
+        """The quarter just before this one."""
+        if self.number == 1:
+            return Quarter(self.year - 1, 4)
+        return Quarter(self.year, self.number - 1)
+
+    @property
+    def label(self) -> str:
+        return f"{self.year}Q{self.number}"
+
+    @property
+    def start(self) -> dt.date:
+        return dt.date(self.year, 3 * self.number - 2, 1)
+
+    @property
+    def end(self) -> dt.date:
+        if self.number == 4:
+            return dt.date(self.year, 12, 31)
+        return dt.date(self.year, 3 * self.number + 1, 1) - dt.timedelta(days=1)
+
+    def has_ended(self, today: dt.date) -> bool:
+        return today > self.end
+
+
+@dataclasses.dataclass(frozen=True)
+class FiscalYear:
+    """An ERPNext Fiscal Year: P&L accounts reset at its start."""
+
+    name: str
+    start: dt.date
+    end: dt.date
+
+
+def fiscal_year_for(quarter: Quarter, years: Sequence[FiscalYear]) -> FiscalYear:
+    """The one Fiscal Year that wholly contains `quarter`.
+
+    Refuses a quarter no year holds, one split across two, and more than one
+    candidate -- the opening balance of every P&L account depends on the
+    answer, so it is never guessed.
+    """
+    holding = [y for y in years if y.start <= quarter.start and quarter.end <= y.end]
+    if len(holding) == 1:
+        return holding[0]
+    if len(holding) > 1:
+        names = ", ".join(sorted(y.name for y in holding))
+        raise PeriodError(f"{quarter.label} sits in more than one ERPNext Fiscal Year: {names}")
+    touching = [y for y in years if y.start <= quarter.end and quarter.start <= y.end]
+    if touching:
+        raise PeriodError(
+            f"{quarter.label} does not fall within a single Fiscal Year; it spans "
+            f"{', '.join(sorted(y.name for y in touching))}"
+        )
+    raise PeriodError(f"{quarter.label}: no ERPNext Fiscal Year covers it; create one first")

runningtab/period/readiness.py

@@ -0,0 +1,146 @@
+"""What blocks a quarter's close.
+
+A hard stop is a fact ERPNext already holds: an entry parked in suspense, a
+Bank Transaction the reconciliation report has not zeroed out, or a draft
+Journal Entry or Purchase Invoice dated in the quarter that can never be
+submitted once the quarter closes. `runningtab health` uses the same readers; this
+just asks them one quarter at a time and names each finding as a `Blocker` the
+close command can print or refuse on.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+from collections.abc import Sequence
+from decimal import ROUND_HALF_UP, Decimal
+from typing import Any, Protocol
+
+from runningtab.period.csvfmt import money
+from runningtab.period.ledger import GLRow
+from runningtab.period.quarter import Quarter
+
+_DRAFT_DOCTYPES = ("Journal Entry", "Purchase Invoice")
+_CENT = Decimal("0.01")
+
+
+class _Reader(Protocol):
+    def iter_all(self, doctype: str, **kwargs: Any) -> Any: ...
+
+
+@dataclasses.dataclass(frozen=True)
+class Blocker:
+    """One thing that must be resolved in ERPNext before the quarter can close."""
+
+    kind: str
+    doctype: str
+    name: str
+    detail: str
+
+
+def _order(blocker: Blocker) -> tuple[str, str]:
+    return (blocker.kind, blocker.name)
+
+
+def _amount(value: object) -> Decimal:
+    """A currency field from a raw ERPNext row, safe for `runningtab.period.csvfmt.money`.
+
+    The client parses JSON with the standard library, so this arrives as a
+    float; going through `Decimal(str(value))` rather than `Decimal(value)`
+    keeps the float's own binary repr noise out of the arithmetic -- the same
+    guard `ledger._money` uses -- and quantizing to the cent ERPNext actually
+    stores money at is what lets `money`, which refuses anything not already
+    a whole number of cents, accept the result.
+    """
+    return Decimal(str(value)).quantize(_CENT, rounding=ROUND_HALF_UP)
+
+
+def _suspense_blockers(rows: Sequence[GLRow], suspense_account: str, quarter: Quarter) -> list[Blocker]:
+    """Every row from the same ledger read the package builds from that landed on suspense, dated in the quarter.
+
+    Reusing `rows` rather than a second, separately-filtered GL Entry query
+    means this can never disagree with what the package itself will contain.
+    """
+    return [
+        Blocker(
+            kind="suspense",
+            doctype="GL Entry",
+            name=row.name,
+            detail=(
+                f"{row.voucher_type} {row.voucher_no} posted {money(row.net)} to suspense "
+                f"on {row.posting_date.isoformat()}"
+            ),
+        )
+        for row in rows
+        if row.account == suspense_account and quarter.start <= row.posting_date <= quarter.end
+    ]
+
+
+def _unreconciled_blockers(client: _Reader, company: str, quarter: Quarter) -> list[Blocker]:
+    """Submitted Bank Transactions dated in the quarter ERPNext has not fully allocated.
+
+    ERPNext marks a Bank Transaction "Reconciled" only once it is submitted
+    (`docstatus = 1`) and its `unallocated_amount` reaches zero or below
+    (erpnext/accounts/doctype/bank_transaction/bank_transaction.py:85-91);
+    this filters on exactly that.
+    """
+    rows = client.iter_all(
+        "Bank Transaction",
+        fields=["name", "date", "unallocated_amount"],
+        filters=[
+            ["company", "=", company],
+            ["docstatus", "=", 1],
+            ["date", ">=", quarter.start.isoformat()],
+            ["date", "<=", quarter.end.isoformat()],
+            ["unallocated_amount", ">", 0],
+        ],
+        order_by="name asc",
+    )
+    return [
+        Blocker(
+            kind="unreconciled",
+            doctype="Bank Transaction",
+            name=str(row["name"]),
+            detail=f"{money(_amount(row['unallocated_amount']))} unallocated on {row['date']}",
+        )
+        for row in rows
+    ]
+
+
+def _draft_blockers(client: _Reader, company: str, quarter: Quarter, doctype: str) -> list[Blocker]:
+    """Draft (`docstatus = 0`) documents of `doctype` dated in the quarter.
+
+    A draft dated in a quarter that has closed can never be submitted, so
+    leaving one there strands whatever work it represents.
+    """
+    rows = client.iter_all(
+        doctype,
+        fields=["name", "posting_date"],
+        filters=[
+            ["company", "=", company],
+            ["docstatus", "=", 0],
+            ["posting_date", ">=", quarter.start.isoformat()],
+            ["posting_date", "<=", quarter.end.isoformat()],
+        ],
+        order_by="name asc",
+    )
+    return [
+        Blocker(
+            kind="draft",
+            doctype=doctype,
+            name=str(row["name"]),
+            detail=f"draft {doctype} dated {row['posting_date']}",
+        )
+        for row in rows
+    ]
+
+
+def read_blockers(
+    client: _Reader, company: str, quarter: Quarter, suspense_account: str, rows: Sequence[GLRow]
+) -> list[Blocker]:
+    """Everything that must be resolved in ERPNext before `quarter` can close, sorted by (kind, name)."""
+    blockers = [
+        *_suspense_blockers(rows, suspense_account, quarter),
+        *_unreconciled_blockers(client, company, quarter),
+        *[blocker for doctype in _DRAFT_DOCTYPES for blocker in _draft_blockers(client, company, quarter, doctype)],
+    ]
+    return sorted(blockers, key=_order)

runningtab/period/record.py

@@ -0,0 +1,247 @@
+"""The record bucket: where a closed quarter's package lives once `period close` hands it off.
+
+Storage under a retention policy (each books directory names its buckets in `books.toml`)
+means an object, once written, cannot be overwritten or deleted until it ages
+out. `Record` is the narrow surface that fact needs: list what is there, read
+an object, create one -- and only ever create, never update. `GcsRecord` is
+the real bucket; tests exercise the same functions against a plain dict, so
+the revision numbering and read-back logic run with no credentials and no
+network.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import re
+from typing import Protocol
+
+from runningtab.period import PeriodError
+from runningtab.period.manifest import lock_version_of
+from runningtab.period.quarter import Quarter
+
+# `<abbr>/<quarter>/SHA256SUMS` is revision 1; `<abbr>/<quarter>/revN/SHA256SUMS`
+# is revision N. The abbr is stripped by the caller before matching, since
+# `stored_packages` already scoped the listing to it.
+_STORED_SUMS = re.compile(r"^(?P<quarter>\d{4}Q[1-4])/(?:rev(?P<rev>\d+)/)?SHA256SUMS$")
+
+
+@dataclasses.dataclass(frozen=True)
+class StoredPackage:
+    """One complete package found in the bucket: which quarter, which revision, and where its objects sit."""
+
+    quarter: Quarter
+    revision: int
+    prefix: str
+
+
+class SuspectPackage(PeriodError):
+    """`SHA256SUMS` was written but did not read back intact, so a package that may be bad is listed as complete.
+
+    Every content file had already read back intact, but `stored_packages`
+    now lists this prefix, and nothing here can delete it. A retry would
+    only be refused as "already has a stored package", so the message names
+    the prefix as suspect and sends the person to `runningtab period status`,
+    which compares what is stored against the ledger.
+    """
+
+
+class Record(Protocol):
+    """What the record bucket needs to offer. `GcsRecord` is the real one; tests use a plain dict."""
+
+    def list_names(self, prefix: str) -> list[str]:
+        """Every object name starting with `prefix`."""
+        ...
+
+    def read(self, name: str) -> bytes:
+        """The object's whole content."""
+        ...
+
+    def create(self, name: str, data: bytes) -> None:
+        """Write a new object. Raises `PeriodError` if `name` already exists -- this never overwrites."""
+        ...
+
+
+class GcsRecord:
+    """`Record` against a real GCS bucket, under a retention policy or not.
+
+    `google.cloud.storage` is imported here, inside the class, and nowhere
+    else in this module -- so the unit suite, which only ever exercises a
+    dict-backed `Record`, never needs credentials or reaches the network.
+    """
+
+    def __init__(self, bucket_name: str) -> None:
+        from google.cloud import storage
+
+        self.bucket_name = bucket_name
+        self._client = storage.Client()
+        self._bucket = self._client.bucket(bucket_name)
+
+    def list_names(self, prefix: str) -> list[str]:
+        return [blob.name for blob in self._client.list_blobs(self._bucket, prefix=prefix)]
+
+    def read(self, name: str) -> bytes:
+        return self._bucket.blob(name).download_as_bytes()
+
+    def create(self, name: str, data: bytes) -> None:
+        # `if_generation_match=0` -- generation 0 means "no live object of
+        # this name" -- is the server-side precondition that makes this
+        # never overwrite, even under a race with another writer.
+        from google.api_core.exceptions import PreconditionFailed
+
+        try:
+            self._bucket.blob(name).upload_from_string(data, if_generation_match=0)
+        except PreconditionFailed as exc:
+            raise PeriodError(f"{name!r} already exists in {self.bucket_name!r}; refusing to overwrite") from exc
+
+
+def stored_packages(record: Record, abbr: str) -> list[StoredPackage]:
+    """Every complete package stored for `abbr`, found by locating each `SHA256SUMS` object.
+
+    `SHA256SUMS` is the last object `upload_package` writes, so a package
+    still being written -- or one that failed partway -- has no `SHA256SUMS`
+    yet and is invisible here, exactly as it should be: nothing lists it as
+    available until it is actually complete.
+    """
+    packages = []
+    for name in record.list_names(f"{abbr}/"):
+        match = _STORED_SUMS.fullmatch(name.removeprefix(f"{abbr}/"))
+        if match is None:
+            continue
+        quarter = Quarter.parse(match["quarter"])
+        revision = int(match["rev"]) if match["rev"] else 1
+        prefix = f"{abbr}/{quarter.label}/" if revision == 1 else f"{abbr}/{quarter.label}/rev{revision}/"
+        packages.append(StoredPackage(quarter, revision, prefix))
+    return sorted(packages, key=lambda p: (p.quarter, p.revision))
+
+
+def latest(stored: list[StoredPackage]) -> dict[Quarter, StoredPackage]:
+    """The highest-revision `StoredPackage` for each quarter present in `stored`."""
+    result: dict[Quarter, StoredPackage] = {}
+    for package in stored:
+        current = result.get(package.quarter)
+        if current is None or package.revision > current.revision:
+            result[package.quarter] = package
+    return result
+
+
+def _prefix_for(abbr: str, quarter: Quarter, revision: int) -> str:
+    """`<abbr>/<quarter>/` for revision 1, `<abbr>/<quarter>/revN/` for any other -- the one place this format
+    is spelled. `next_prefix` and `revision_of` are its only two callers, one building it and one reading it
+    back, so the two can never drift apart the way a second, independent parse of the same shape could.
+    """
+    return f"{abbr}/{quarter.label}/" if revision == 1 else f"{abbr}/{quarter.label}/rev{revision}/"
+
+
+def next_prefix(record: Record, abbr: str, quarter: Quarter) -> str:
+    """Where the next revision of `quarter`'s package belongs.
+
+    Probes each candidate prefix in turn -- `<abbr>/<quarter>/`, then
+    `rev2/`, `rev3/`, ... -- and returns the first one holding no object at
+    all. `stored_packages` calls a prefix with no `SHA256SUMS` "not there,"
+    but a half-failed `upload_package` can still have left content objects
+    under it, and this function must not repeat that prefix: the bucket is
+    under a retention policy, those objects cannot be deleted until they age out, and a retry that
+    recomputed the same prefix would have every `create` refuse against them
+    forever. Checking `record.list_names` directly, rather than trusting
+    `stored_packages`, is what makes a retry land on the next free revision
+    instead.
+    """
+    revision = 1
+    while True:
+        prefix = _prefix_for(abbr, quarter, revision)
+        if not record.list_names(prefix):
+            return prefix
+        revision += 1
+
+
+_REVISION_SUFFIX = re.compile(r"rev(\d+)/$")
+
+
+def revision_of(prefix: str, abbr: str, quarter: Quarter) -> int:
+    """The revision `next_prefix(record, abbr, quarter)` encoded into a `prefix` it returned.
+
+    A caller that renders `MANIFEST.md`'s revision field needs the exact
+    number the prefix it is about to write under names -- this is the one
+    place that reads the layout `next_prefix` writes, so the two can never
+    silently disagree about what a bare prefix versus a `revN/` one means.
+    """
+    if prefix == _prefix_for(abbr, quarter, 1):
+        return 1
+    match = _REVISION_SUFFIX.search(prefix)
+    if match is None or prefix != _prefix_for(abbr, quarter, int(match[1])):
+        raise PeriodError(f"{prefix!r} is not a {abbr!r}/{quarter.label} revision prefix")
+    return int(match[1])
+
+
+def upload_package(record: Record, prefix: str, files: dict[str, bytes]) -> None:
+    """Write every object in `files` under `prefix`, `SHA256SUMS` last, proving each one landed intact first.
+
+    Every content file is created, then read back and checked before
+    `SHA256SUMS` is ever written: a content file that fails its read-back
+    raises immediately, with `SHA256SUMS` still unwritten, so a corrupt
+    package never becomes visible as complete to `stored_packages`.
+    `SHA256SUMS` itself is then created and read back the same way; a
+    mismatch there raises `SuspectPackage`, since by then the package is
+    already listed as complete. The
+    read-back is not paranoia: a write GCS acknowledged is still only a
+    claim about what is in the bucket, and a package an accountant trusts on
+    a wrong claim is worse than one that fails loudly here instead.
+    """
+    content = {path: data for path, data in files.items() if path != "SHA256SUMS"}
+    for path, data in content.items():
+        record.create(f"{prefix}{path}", data)
+    mismatched = [f"{prefix}{path}" for path, data in content.items() if record.read(f"{prefix}{path}") != data]
+    if mismatched:
+        raise PeriodError(f"uploaded but did not read back intact: {', '.join(sorted(mismatched))}")
+    if "SHA256SUMS" in files:
+        sums_name = f"{prefix}SHA256SUMS"
+        record.create(sums_name, files["SHA256SUMS"])
+        if record.read(sums_name) != files["SHA256SUMS"]:
+            raise SuspectPackage(
+                f"{sums_name} was written but did not read back intact, so {prefix!r} is now listed as a stored "
+                f"package that may not be what was sent; treat {prefix!r} as suspect and run `runningtab period status` "
+                "to compare it with the ledger"
+            )
+
+
+def read_lock_version(record: Record, stored: StoredPackage) -> str:
+    """The Company Version a stored package's `MANIFEST.md` says locked its quarter.
+
+    A stored package is always a final close, so a manifest with no lock
+    record is refused by name rather than read as "no lock".
+    """
+    name = f"{stored.prefix}MANIFEST.md"
+    try:
+        text = record.read(name).decode()
+    except UnicodeDecodeError as exc:
+        raise PeriodError(f"{name} is not valid UTF-8: {exc}") from exc
+    version = lock_version_of(text)
+    if version is None:
+        raise PeriodError(f"{name} records no lock (no Company Version line)")
+    return version
+
+
+def read_sums(record: Record, stored: StoredPackage) -> dict[str, str]:
+    """`path -> hex digest`, parsed from the stored package's `SHA256SUMS` (the standard `sha256sum` two-space format).
+
+    The bucket is under a retention policy and `upload_package` writes this object
+    itself, so a malformed read is unlikely -- but unlikely is not never,
+    and the ruling is that every read failure is a named refusal, not a
+    traceback that loses whatever else `period status`/`health` already
+    found.
+    """
+    name = f"{stored.prefix}SHA256SUMS"
+    try:
+        text = record.read(name).decode()
+    except UnicodeDecodeError as exc:
+        raise PeriodError(f"{name} is not valid UTF-8: {exc}") from exc
+    result = {}
+    for lineno, line in enumerate(text.splitlines(), start=1):
+        if not line:
+            continue
+        try:
+            digest, path = line.split("  ", 1)
+        except ValueError:
+            raise PeriodError(f"{name} line {lineno} is not `<sha256>  <path>`: {line!r}") from None
+        result[path] = digest
+    return result