runningtab 0.1.0.dev3__py3-none-any.whl

runningtab/__init__.py

@@ -0,0 +1,3 @@
+"""Keeping a company's books in ERPNext: the tooling that applies a books directory's chart, bank feed and close."""
+
+__version__ = "0.0.1"

runningtab/access.py

@@ -0,0 +1,419 @@
+"""Policy for the books bot: exactly what it may touch, and the one thing it may submit.
+
+The bot's role holds create/write for drafting and the chart of accounts, and
+submit on Bank Transaction alone; cancel and amend are written as "0"
+everywhere, and so is submit on every other doctype. The server is asked to
+confirm all of it before a key is stored.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+from typing import Any, Protocol
+
+from icedcoffee_sync.frappe.access import (
+    ApiKeyPair,
+    PermissionGrant,
+    RoleChange,
+    SubmitProbe,
+    UserChange,
+    ensure_role,
+    ensure_user,
+    generate_keys,
+    grant,
+    granted_flags_effective,
+    probe_submit,
+    prohibited_flags_allowed,
+    revoke_grants_except,
+)
+from icedcoffee_sync.frappe.client import SiteConfig
+
+from runningtab.forecast.names import CASH_FORECAST
+
+# Which role and user each identity is comes from the books directory's
+# `books.toml` (`runningtab.books`); what each may touch is fixed here, and
+# `bot_policy`/`reader_policy` put the two together.
+
+# The one doctype the bot may submit. A Bank Transaction posts nothing to the
+# general ledger on submit -- ERPNext writes the GL entries when a person
+# reconciles it to a voucher -- and the Bank Reconciliation Tool only sees
+# submitted rows, so the Mercury ingest submits the rows it creates and
+# "machines draft, humans post" still holds in substance. Every other
+# submittable doctype commits money on submit and stays draft-only.
+BOT_SUBMITS: frozenset[str] = frozenset({"Bank Transaction"})
+
+# Never granted: cancel or amend on any doctype, and submit outside
+# BOT_SUBMITS. No DocType grant either: a role permission on DocType does not
+# take effect (measured live), and nothing here reads meta.
+GRANTS: tuple[PermissionGrant, ...] = (
+    PermissionGrant("Account", frozenset({"read", "write", "create", "delete"})),
+    PermissionGrant("Company", frozenset({"read", "write"})),
+    # `runningtab.period.fence` pushes Books Closed Through and its bypass role to
+    # permission level 1, so the ordinary permlevel-0 Company read above no
+    # longer reaches them. The Mercury ingest reads `accounts_frozen_till_date`
+    # every run to leave a closed quarter's rows to a person, so the bot is
+    # granted read at that level too -- read only, so the fence still proves
+    # the bot cannot write it.
+    PermissionGrant("Company", frozenset({"read"}), permlevel=1),
+    PermissionGrant("GL Entry", frozenset({"read"})),
+    PermissionGrant("Journal Entry", frozenset({"read", "write", "create"})),
+    PermissionGrant("Purchase Invoice", frozenset({"read", "write", "create"})),
+    PermissionGrant("Bank Transaction", frozenset({"read", "write", "create", "submit"})),
+    PermissionGrant("Supplier", frozenset({"read", "write", "create"})),
+    PermissionGrant("File", frozenset({"read", "write", "create"})),
+    # A forecast is written once and never changed: create without write or
+    # delete. Its child tables inherit the parent's permissions.
+    PermissionGrant(CASH_FORECAST, frozenset({"read", "create"})),
+)
+
+# Exactly what `coa plan` reads and nothing else: the accounts, the company
+# they hang off, and which accounts carry ledger entries.
+#
+# GL Entry read is a deliberate decision, not an oversight, so that reviews
+# stop re-raising it: plan needs only to know WHETHER an account has entries,
+# and asking that cheaply (`list("GL Entry", filters=[["account","=",...]],
+# limit=1)`) means read on the ledger. Narrowing it would take a whitelisted
+# method on the site and a custom Frappe app to hold it. Reading the whole
+# ledger is accepted on purpose: the reader is the tooling that keeps these
+# books, reading the books it keeps.
+READER_GRANTS: tuple[PermissionGrant, ...] = (
+    PermissionGrant("Account", frozenset({"read"})),
+    PermissionGrant("Company", frozenset({"read"})),
+    # `runningtab.period.fence` pushes Books Closed Through and its bypass role to
+    # permission level 1, so the ordinary permlevel-0 Company read above no
+    # longer reaches them. `status` and `health` still need to read
+    # `accounts_frozen_till_date`, so the reader is granted read at that level
+    # too -- as the bot is in `GRANTS`, for the Mercury ingest. Removing
+    # either grant makes that credential's lock read refuse by name
+    # (`runningtab.period.lock.read_visible_lock`).
+    PermissionGrant("Company", frozenset({"read"}), permlevel=1),
+    PermissionGrant("GL Entry", frozenset({"read"})),
+    # Read by `runningtab period export`: the ledger's parties, the fiscal years,
+    # and the vouchers whose attachments a private-file download is checked
+    # against.
+    PermissionGrant("Fiscal Year", frozenset({"read"})),
+    PermissionGrant("Customer", frozenset({"read"})),
+    PermissionGrant("Journal Entry", frozenset({"read"})),
+    PermissionGrant("Purchase Invoice", frozenset({"read"})),
+    PermissionGrant("Payment Entry", frozenset({"read"})),
+    PermissionGrant("Sales Invoice", frozenset({"read"})),
+    PermissionGrant("Bank Transaction", frozenset({"read"})),
+    PermissionGrant("File", frozenset({"read"})),
+    PermissionGrant("Supplier", frozenset({"read"})),
+    # Version ships read to System Manager and Administrator only
+    # (frappe/core/doctype/version/version.json); the reader inherits
+    # neither, so this is explicit. `runningtab.period.lock.lock_history` reads
+    # it to name who moved Books Closed Through and when -- status names who
+    # reopened a quarter.
+    PermissionGrant("Version", frozenset({"read"})),
+)
+
+# Every mutating flag, on every doctype the writing bot can reach. Read access
+# is worthless as a boundary unless the absence of write access is proven
+# rather than assumed: a role inherited from somewhere else, or a stray grant
+# left on the user, would otherwise pass unnoticed.
+#
+# The list is deliberately wider than the reader's own grants. Checking only
+# the doctypes we granted would prove nothing about an inherited permission on
+# one we did not, and an inherited permission is the whole thing this check
+# exists to catch. Every flag that changes a document is listed -- cancel and
+# amend included, which a "can it write" check reads past too easily.
+MUTATING_PTYPES: frozenset[str] = frozenset({"write", "create", "delete", "submit", "cancel", "amend"})
+READER_PROHIBITED: dict[str, frozenset[str]] = dict.fromkeys(
+    (
+        "Account",
+        "Company",
+        "GL Entry",
+        "Journal Entry",
+        "Purchase Invoice",
+        "Bank Transaction",
+        "Supplier",
+        "File",
+        "Fiscal Year",
+        "Customer",
+        "Payment Entry",
+        "Sales Invoice",
+        "Version",
+    ),
+    MUTATING_PTYPES,
+)
+
+# What the reader can do that we did not grant and cannot take away here.
+#
+# MEASURED on the live site 2026-08-27, not inferred: the reader's role grants
+# File nothing, the server reports create/write/delete on File as allowed, and
+# a real insert SUCCEEDED (then was deleted again). Frappe hands this to
+# authenticated users so attachments work; taking it away means editing a
+# role's permissions for the whole site, and `DocPerm` is not even readable
+# over REST to find out which role supplies it.
+#
+# Recorded here rather than dropped from the check, so that verification keeps
+# reporting it every run instead of quietly narrowing what "read-only" claims.
+# It reaches no account, no ledger entry and no company record -- but it is
+# write access, and calling the reader "unable to write anything" would be a
+# lie.
+READER_INHERITED_WRITES: dict[str, frozenset[str]] = {"File": frozenset({"create", "write", "delete"})}
+
+
+@dataclasses.dataclass(frozen=True)
+class Policy:
+    """One identity on the books site: its role, its user, and what that role may touch."""
+
+    role: str
+    user: str
+    first_name: str
+    grants: tuple[PermissionGrant, ...]
+
+
+def bot_policy(role: str, user: str, first_name: str) -> Policy:
+    """The writing bot: `GRANTS`, held by the role and user the books name."""
+    return Policy(role, user, first_name, GRANTS)
+
+
+def reader_policy(role: str, user: str, first_name: str) -> Policy:
+    """The reader: `READER_GRANTS`, held by the role and user the books name."""
+    return Policy(role, user, first_name, READER_GRANTS)
+
+
+# Frappe permissions are per doctype and per flag: the insert-based probe
+# proves submit on Journal Entry only, so every prohibited flag is checked on
+# every submittable doctype the bot is granted.
+SUBMITTABLE_DOCTYPES: frozenset[str] = frozenset({"Journal Entry", "Purchase Invoice", "Bank Transaction"})
+PROHIBITED_PTYPES: frozenset[str] = frozenset({"submit", "cancel", "amend"})
+
+# Cash Forecast is not submittable; what must be refused is changing or
+# removing a forecast once the bot has created it.
+FORECAST_PROHIBITED: frozenset[str] = frozenset({"write", "delete"})
+
+
+def prohibited_ptypes_for(doctype: str) -> frozenset[str]:
+    """The committing flags the bot must be denied on `doctype`: all three, less submit where it is granted."""
+    if doctype in BOT_SUBMITS:
+        return PROHIBITED_PTYPES - {"submit"}
+    return PROHIBITED_PTYPES
+
+
+class KeyRotationFailedError(RuntimeError):
+    """`generate_keys` failed after it may already have rotated the live secret.
+
+    The call has no dry-run and no read-back, so a timeout looks the same as
+    a request that never arrived; assume the rotation landed.
+    """
+
+
+@dataclasses.dataclass(frozen=True)
+class ProvisionReport:
+    """What `provision` changed, and the bot's freshly minted credential."""
+
+    role_created: bool
+    role_desk_access_repaired: bool
+    role_disabled_repaired: bool
+    grants: dict[str, list[tuple[str, str]]]
+    revoked: list[str]
+    user: UserChange
+    keys: ApiKeyPair
+
+
+class _ProvisionClient(Protocol):
+    """The slice of `Client` provisioning needs."""
+
+    def get(self, doctype: str, name: str) -> Any: ...
+    def insert(self, doctype: str, doc: dict[str, Any]) -> Any: ...
+    def update(self, doctype: str, name: str, doc: dict[str, Any]) -> Any: ...
+    def call(self, dotted_path: str, params: dict[str, Any] | None = None) -> Any: ...
+
+
+def _grant_label(doctype: str, permlevel: int) -> str:
+    """`"<doctype>"` at permlevel 0, `"<doctype> (permlevel N)"` otherwise.
+
+    The spelling `revoke_grants_except` already uses for a revoked row. Every
+    dict this module keys per grant uses it too: two grants on the same
+    doctype at different permlevels -- the bot's and the reader's Company
+    grants both are, now -- must never collapse onto one key and silently
+    drop one of the two findings.
+    """
+    return doctype if permlevel == 0 else f"{doctype} (permlevel {permlevel})"
+
+
+def provision(client: _ProvisionClient, policy: Policy) -> ProvisionReport:
+    """Create or repair `policy`'s role and user to exactly what it describes, and mint a fresh key.
+
+    Idempotent up to the key: grants are rewritten in full, stray grants and
+    roles revoked, a disabled role or user re-enabled. A role without desk
+    access makes the user a Website User, which the REST API serves fine.
+    """
+    role: RoleChange = ensure_role(client, policy.role)
+    sent = {_grant_label(g.doctype, g.permlevel): grant(client, policy.role, g) for g in policy.grants}
+    revoked = revoke_grants_except(client, policy.role, keep=frozenset((g.doctype, g.permlevel) for g in policy.grants))
+    user = ensure_user(client, policy.user, first_name=policy.first_name, roles=frozenset({policy.role}))
+    try:
+        keys = generate_keys(client, policy.user)
+    except Exception as exc:
+        raise KeyRotationFailedError(str(exc)) from exc
+    return ProvisionReport(
+        role_created=role.created,
+        role_desk_access_repaired=role.desk_access_repaired,
+        role_disabled_repaired=role.disabled_repaired,
+        grants=sent,
+        revoked=revoked,
+        user=user,
+        keys=keys,
+    )
+
+
+def prohibited_flags_report(config: SiteConfig) -> dict[str, list[str]]:
+    """{doctype: [flag, ...]} for every prohibited flag the server still allows this credential.
+
+    Submit on Bank Transaction is granted, not prohibited, and `missing_grants_report`
+    is what proves the server honours it. Cash Forecast is checked for write and
+    delete, which the bot must never hold.
+    """
+    leaked: dict[str, list[str]] = {}
+    for doctype in sorted(SUBMITTABLE_DOCTYPES):
+        flags = prohibited_flags_allowed(config, doctype=doctype, ptypes=prohibited_ptypes_for(doctype))
+        allowed = sorted(ptype for ptype, value in flags.items() if value)
+        if allowed:
+            leaked[doctype] = allowed
+    flags = prohibited_flags_allowed(config, doctype=CASH_FORECAST, ptypes=FORECAST_PROHIBITED)
+    if allowed := sorted(ptype for ptype, value in flags.items() if value):
+        leaked[CASH_FORECAST] = allowed
+    return leaked
+
+
+def missing_grants_report(config: SiteConfig, grants: tuple[PermissionGrant, ...] = GRANTS) -> dict[str, list[str]]:
+    """{label: [flag, ...]} for every permlevel-0 granted flag the server does not honour.
+
+    A grant above permlevel 0 is left out entirely here -- never asked about,
+    never reported missing. `granted_flags_effective` asks
+    `frappe.client.has_permission`, which has no permlevel of its own: it
+    cannot tell a permlevel-1 DocPerm row's presence from a permlevel-0 grant
+    already on the same doctype, so treating its answer as proof for a
+    permlevel-1 grant would be a check that always reads "effective" whether
+    or not the row exists -- a false green. `skipped_grants` names these
+    instead, and what actually proves them is a live round trip of the
+    field's value through the credential (`tests/test_live_fence.py`), not a
+    doctype-level yes/no.
+    """
+    missing: dict[str, list[str]] = {}
+    for g in grants:
+        if g.permlevel > 0:
+            continue
+        flags = granted_flags_effective(config, doctype=g.doctype, ptypes=g.ptypes)
+        not_effective = sorted(ptype for ptype, value in flags.items() if not value)
+        if not_effective:
+            missing[_grant_label(g.doctype, g.permlevel)] = not_effective
+    return missing
+
+
+def skipped_grants(grants: tuple[PermissionGrant, ...] = GRANTS) -> list[str]:
+    """Labels of the grants `missing_grants_report` cannot check -- see its docstring.
+
+    Static over `grants` alone: which grants sit above permlevel 0 is known
+    before anything is asked of the server, so this makes no network call.
+    """
+    return [_grant_label(g.doctype, g.permlevel) for g in grants if g.permlevel > 0]
+
+
+def reader_prohibited_report(config: SiteConfig) -> tuple[dict[str, list[str]], dict[str, list[str]]]:
+    """Which mutating flags the server still allows a reader: (unexpected, known-inherited).
+
+    Split rather than merged so the known ones stay visible on every run
+    without failing it, and anything new fails immediately instead of hiding
+    among them.
+    """
+    leaked: dict[str, list[str]] = {}
+    inherited: dict[str, list[str]] = {}
+    for doctype, ptypes in sorted(READER_PROHIBITED.items()):
+        flags = prohibited_flags_allowed(config, doctype=doctype, ptypes=ptypes)
+        allowed = {ptype for ptype, value in flags.items() if value}
+        known = READER_INHERITED_WRITES.get(doctype, frozenset())
+        if expected := sorted(allowed & known):
+            inherited[doctype] = expected
+        if unexpected := sorted(allowed - known):
+            leaked[doctype] = unexpected
+    return leaked, inherited
+
+
+def check_reader_credential(config: SiteConfig) -> CredentialCheck:
+    """Prove a reader credential can read what plan needs and cannot write anything.
+
+    No submit probe: the probe works by inserting a Journal Entry, which a
+    reader may not create at all, so its refusal would prove nothing about
+    submit. Asking the server which flags it honours is the whole check here,
+    and `probe` is recorded as refused because a credential that cannot create
+    cannot submit either.
+
+    Raises `CredentialCheckError` (naming the stage) when a check cannot run.
+    """
+    try:
+        leaked, inherited = reader_prohibited_report(config)
+    except Exception as exc:
+        raise CredentialCheckError("prohibited", exc) from exc
+    probe = SubmitProbe(refused=True, can_create=False, submit_flag=False)
+    if leaked:
+        return CredentialCheck(probe=probe, leaked=leaked, inherited=inherited)
+    try:
+        missing = missing_grants_report(config, READER_GRANTS)
+    except Exception as exc:
+        raise CredentialCheckError("grants", exc) from exc
+    return CredentialCheck(probe=probe, leaked=leaked, missing=missing, inherited=inherited)
+
+
+class CredentialCheckError(RuntimeError):
+    """A credential check could not run; `stage` says which one."""
+
+    def __init__(self, stage: str, cause: Exception) -> None:
+        super().__init__(f"{stage}: {cause}")
+        self.stage = stage
+        self.cause = cause
+
+
+@dataclasses.dataclass(frozen=True)
+class CredentialCheck:
+    """The server's verdict on a credential, stage by stage; later stages are None once one fails."""
+
+    probe: SubmitProbe
+    leaked: dict[str, list[str]] | None = None
+    missing: dict[str, list[str]] | None = None
+    # Allowed, expected, and not a failure -- see READER_INHERITED_WRITES.
+    inherited: dict[str, list[str]] | None = None
+
+    @property
+    def passed(self) -> bool:
+        """True only when the probe's submit was refused, no prohibited flag leaked, and every grant is effective.
+
+        For the bot that means submit denied on Journal Entry and Purchase
+        Invoice, cancel and amend denied everywhere, and submit on Bank
+        Transaction actually honoured -- a grant on paper the server ignores
+        would fail the ingest on its first row.
+        """
+        return self.probe.refused and self.leaked == {} and self.missing == {}
+
+
+def check_credential(config: SiteConfig, company: str) -> CredentialCheck:
+    """Prove a credential is scoped as policy says, stopping at the first stage that fails.
+
+    Raises `CredentialCheckError` (naming the stage) when a check cannot run;
+    an `OrphanProbeDocumentError` from the probe propagates as itself.
+    """
+    from icedcoffee_sync.frappe.access import OrphanProbeDocumentError
+
+    try:
+        probe = probe_submit(config, company=company)
+    except OrphanProbeDocumentError:
+        raise
+    except Exception as exc:
+        raise CredentialCheckError("probe", exc) from exc
+    if not probe.refused:
+        return CredentialCheck(probe=probe)
+    try:
+        leaked = prohibited_flags_report(config)
+    except Exception as exc:
+        raise CredentialCheckError("prohibited", exc) from exc
+    if leaked:
+        return CredentialCheck(probe=probe, leaked=leaked)
+    try:
+        missing = missing_grants_report(config)
+    except Exception as exc:
+        raise CredentialCheckError("grants", exc) from exc
+    return CredentialCheck(probe=probe, leaked=leaked, missing=missing)

runningtab/books.py

@@ -0,0 +1,225 @@
+"""The books directory: whose books runningtab is keeping, and everything it reads about them.
+
+runningtab is the tool; the books are data it is pointed at. A books
+directory holds the chart (`chart.coa`), the Mercury account map
+(`mercury.toml`), the forecast (`forecast.toml`), the QuickBooks import map
+(`qbo.toml`), and `books.toml`, which says where the ledger is and which
+identities and secrets reach it.
+
+There is no default directory and no fallback to one inside the package:
+`--books DIR` or `RUNNINGTAB_BOOKS` names it, or the command refuses. A
+silent fallback would plan against books nobody meant, and every difference
+it reported would look real.
+
+`books.toml` is read strictly. An unknown key is refused by its dotted name,
+and so is a missing one, because a typo that quietly became a default is the
+kind of mistake nobody notices until the ledger does.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import os
+import pathlib
+import re
+import tomllib
+from collections.abc import Mapping
+from typing import Any
+
+from runningtab.access import Policy, bot_policy, reader_policy
+from runningtab.site import Site, Target, normalised_host
+
+BOOKS_ENV = "RUNNINGTAB_BOOKS"
+BOOKS_FILE = "books.toml"
+CHART_FILE = "chart.coa"
+MERCURY_FILE = "mercury.toml"
+FORECAST_FILE = "forecast.toml"
+QBO_FILE = "qbo.toml"
+_DATA_FILES = (CHART_FILE, MERCURY_FILE, FORECAST_FILE, QBO_FILE)
+
+# One path segment: the name namespaces the Mercury ingest's local state.
+_NAME = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_-]*$")
+
+# Every key `books.toml` may hold, and its type. All of them are required.
+_STR = "a string"
+_STR_LIST = "a list of strings"
+_SCHEMA: dict[str, Any] = {
+    "name": _STR,
+    "chart_doc": _STR,
+    "site": {"host": _STR, "test_hosts": _STR_LIST},
+    "secrets": {
+        "project": _STR,
+        "books": _STR,
+        "books_readonly": _STR,
+        "mercury": _STR,
+        "test_admin": _STR,
+    },
+    "record_buckets": {"books": _STR, "test": _STR},
+    "bot": {"role": _STR, "user": _STR, "first_name": _STR},
+    "reader": {"role": _STR, "user": _STR, "first_name": _STR},
+    "fence": {"probe_role": _STR},
+}
+
+
+class BooksError(ValueError):
+    """No books directory was named, or the one named is not a set of books runningtab can read."""
+
+
+@dataclasses.dataclass(frozen=True)
+class Books:
+    """One loaded books directory."""
+
+    directory: pathlib.Path
+    # Names the books in what runningtab writes for a person (the period
+    # package's manifest) and namespaces its local state.
+    name: str
+    # `docs/chart-of-accounts.md`-style page whose account tables
+    # `runningtab chart render-doc` regenerates from the chart.
+    chart_doc: pathlib.Path
+    site: Site
+    # The record buckets a closed quarter's package is written to, one per
+    # target, so a caller never spells a bucket name itself.
+    record_buckets: Mapping[Target, str]
+    bot: Policy
+    reader: Policy
+    # The role `runningtab.period.fence` writes as Company's bypass role while
+    # proving the fence holds. Held by nobody; see that module.
+    fence_probe_role: str
+
+    @property
+    def chart_path(self) -> pathlib.Path:
+        """The chart of accounts."""
+        return self.directory / CHART_FILE
+
+    @property
+    def mercury_path(self) -> pathlib.Path:
+        """Which chart account and Bank Account each Mercury account is."""
+        return self.directory / MERCURY_FILE
+
+    @property
+    def forecast_path(self) -> pathlib.Path:
+        """The expected cash movements `runningtab forecast` reads."""
+        return self.directory / FORECAST_FILE
+
+    @property
+    def qbo_path(self) -> pathlib.Path:
+        """What QuickBooks Online needs to know about the chart."""
+        return self.directory / QBO_FILE
+
+
+def resolve_books(flag: pathlib.Path | None, environ: Mapping[str, str] = os.environ) -> Books:
+    """Load the books directory `--books` names, else the one `RUNNINGTAB_BOOKS` names, else refuse.
+
+    Raises:
+        BooksError: Neither names a directory, or the one named does not load.
+    """
+    if flag is not None:
+        return load_books(flag)
+    named = environ.get(BOOKS_ENV, "")
+    if not named:
+        raise BooksError(
+            f"no books directory named: pass --books DIR or set {BOOKS_ENV}. "
+            "runningtab has no default books, so that it never plans against books nobody meant."
+        )
+    return load_books(pathlib.Path(named))
+
+
+def load_books(directory: pathlib.Path) -> Books:
+    """Read `directory/books.toml` and check the directory holds every file runningtab reads.
+
+    Raises:
+        BooksError: Naming the file, key or host that is wrong.
+    """
+    directory = directory.resolve()
+    books_file = directory / BOOKS_FILE
+    try:
+        text = books_file.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise BooksError(f"{books_file}: cannot read the books directory's {BOOKS_FILE}: {exc}") from exc
+    missing = [name for name in _DATA_FILES if not (directory / name).is_file()]
+    if missing:
+        raise BooksError(f"books directory {directory} is missing: {', '.join(missing)}")
+    try:
+        data = tomllib.loads(text)
+    except tomllib.TOMLDecodeError as exc:
+        raise BooksError(f"{books_file} is not valid TOML: {exc}") from exc
+    problems = _schema_problems(data, _SCHEMA, prefix="")
+    if problems:
+        raise BooksError(f"{books_file}:\n  " + "\n  ".join(problems))
+    return _books(directory, books_file, data)
+
+
+def _schema_problems(data: Mapping[str, Any], schema: Mapping[str, Any], *, prefix: str) -> list[str]:
+    """Every unknown, missing or wrongly typed key under `prefix`, by its dotted name."""
+    problems: list[str] = []
+    for key in sorted(data.keys() - schema.keys()):
+        problems.append(f"{prefix}{key}: unknown key")
+    for key, expected in schema.items():
+        where = f"{prefix}{key}"
+        if key not in data:
+            problems.append(f"{where}: missing")
+            continue
+        value = data[key]
+        if isinstance(expected, dict):
+            if isinstance(value, dict):
+                problems.extend(_schema_problems(value, expected, prefix=f"{where}."))
+            else:
+                problems.append(f"{where}: must be a table")
+        elif expected == _STR and not (isinstance(value, str) and value.strip()):
+            problems.append(f"{where}: must be {_STR}, not empty")
+        elif expected == _STR_LIST and not (
+            isinstance(value, list) and all(isinstance(item, str) and item.strip() for item in value)
+        ):
+            problems.append(f"{where}: must be {_STR_LIST}")
+    return problems
+
+
+def _books(directory: pathlib.Path, books_file: pathlib.Path, data: Mapping[str, Any]) -> Books:
+    """Build `Books` from data `_schema_problems` already passed, refusing what only makes sense together."""
+    name = data["name"]
+    if not _NAME.match(name):
+        raise BooksError(f"{books_file}: name {name!r} must be letters, digits, '-' and '_' only; it names a directory")
+    site_data, secrets = data["site"], data["secrets"]
+    site = Site(
+        host=site_data["host"],
+        test_hosts=frozenset(site_data["test_hosts"]),
+        secret_project=secrets["project"],
+        books_secret=secrets["books"],
+        books_readonly_secret=secrets["books_readonly"],
+        mercury_secret=secrets["mercury"],
+        test_admin_secret=secrets["test_admin"],
+    )
+    # The allowlist exists so that an alias of the ledger is refused. A list
+    # that names the ledger itself would let `--target test` reach it.
+    ledger = normalised_host(site.host)
+    if any(normalised_host(host) == ledger for host in site.test_hosts):
+        raise BooksError(
+            f"{books_file}: site.test_hosts names the books host {site.host}; "
+            "the test target must never be able to reach the ledger"
+        )
+    bot, reader = data["bot"], data["reader"]
+    if bot["user"] == reader["user"] or bot["role"] == reader["role"]:
+        raise BooksError(
+            f"{books_file}: bot and reader must be different users with different roles; "
+            "the reader's whole point is a credential that cannot write"
+        )
+    # `runningtab.period.fence` writes this role as the one allowed past a
+    # closed quarter, so it must be held by nobody. Frappe gives every user
+    # "Guest" and "All", and the bot and reader hold their own roles.
+    probe_role = data["fence"]["probe_role"]
+    if probe_role in {"Guest", "All", bot["role"], reader["role"]}:
+        raise BooksError(
+            f"{books_file}: fence.probe_role {probe_role!r} is a role somebody holds; "
+            "it must be one nobody is ever granted"
+        )
+    buckets = data["record_buckets"]
+    return Books(
+        directory=directory,
+        name=name,
+        chart_doc=(directory / data["chart_doc"]).resolve(),
+        site=site,
+        record_buckets={Target.BOOKS: buckets["books"], Target.TEST: buckets["test"]},
+        bot=bot_policy(bot["role"], bot["user"], bot["first_name"]),
+        reader=reader_policy(reader["role"], reader["user"], reader["first_name"]),
+        fence_probe_role=probe_role,
+    )