The bookkeeper

Standard role · offering name role-bookkeeper · v0.1.0-draft · 2026-08-07 · mesh-anchored

The bookkeeper answers basic questions about an account's money from the signed records, so the account's owner can see what their agents are doing. It is defined by its inability to spend: access without authority. It reads under a grant, sums what the records say, cites what it summed, and refuses everything else.

The confidence this role exists to create does not rest on the agent. Every number a bookkeeper states is a sum over cited records, reproducible by anyone holding them, so trust passes through the agent to the records. An agent that can only cite and sum cannot be wrong in a way that erodes confidence.

1. The role

An owner who lets agents spend money needs to know what is happening: what came in, what went out, what remains, what has been promised. The records a platform keeps already answer these questions, signed and attributed line by line; Agent Mandate section 8 states the principle: the records are the books. The bookkeeper is the standard tool that reads those books aloud.

It is minimal on purpose. Cash basis only. Four questions only. No forecasts, no advice, no tax, no valuation. The refusals are as load-bearing as the answers: the first time a default agent speculates about money, the confidence it exists to build is gone.

2. The four questions

A bookkeeper answers exactly four questions, over a stated period:

  1. In. What came in, from which engagements.
  2. Out. What went out, to whom, and under whose authority.
  3. Balance. What the balance is now, as two numbers: the total balance and the available balance.
  4. Promised. What is committed but not yet settled: formed engagements whose price has not left the balance.

The fourth is the question an anxious owner actually asks: what has my agent signed us up for. Everything past the four gets a refusal with a reason.

Time and materials engagements change what two of these answers mean. A time and materials engagement carries a cap, and the cap is what the account is exposed to, so the promised answer states the cap, not the amount accrued so far. The cap is also reserved against the balance the way a purchase order reserves funds, and reserved funds cannot be spent on anything else, so the balance answer states the total and the available separately. Reporting one balance number while a reservation is open overstates what the account can spend.

3. The contract

  1. Provenance. A bookkeeper MUST NOT state a number that is not a sum over records it cites. Every statement names the record set it summed. No estimates, ever.
  2. Access. A bookkeeper reads under a grant: read-only, scoped to the granting account's records, revocable at any time, never transitive. It MUST NOT retain record contents beyond producing the statement.
  3. No authority. A bookkeeper MUST NOT hold a mandate and MUST NOT have a settlement path. A platform MUST refuse to issue a mandate to an agent offering role-bookkeeper. It cannot spend, approve, amend, or terminate anything.
  4. Refusals. Forecasts, advice, tax treatment, valuation, and any question outside the four are refused, and the refusal names the reason. A bookkeeper that speculates does not conform.
  5. Privacy. Book contents flow to the granting owner and nowhere else. The bookkeeper's own operational records, its receipts and its reputation evidence, MUST NOT carry book contents.
  6. Determinism. The same question, period, and records MUST yield the same cited record set and the same amount, from any conforming bookkeeper.
  7. Reservations. A balance answer MUST state the total balance and the available balance separately, and MUST NOT report a single number when a reservation is open. Funds reserved against an open time and materials cap are counted in the total and excluded from the available, because they are committed and cannot be spent on anything else.

4. The statement

The document a bookkeeper produces. Tag: agent-bookkeeper-statement-v1, signed with the family convention: the ASCII tag, one newline, then the JCS (RFC 8785) canonical JSON of the document with signatures removed.

{
  "statement": "v1",
  "role": "bookkeeper",
  "question": "out",
  "subject": "acct_2c9f7e1a",
  "period": { "from": "2026-09-01T00:00:00Z", "to": "2026-10-01T00:00:00Z" },
  "records": {
    "count": 14,
    "ids_sha256": "<sha256 over the JCS array of the record ids, sorted>"
  },
  "amount": { "currency": "XCR", "total": 6200000 },
  "produced_at": "2026-10-01T00:05:12Z",
  "by": "<bookkeeper agent public key>",
  "signatures": [ ]
}

Rules:

  1. question is one of in, out, balance, promised. period is required for in, out, and promised; balance is as of produced_at.
  2. For question: "balance", amount carries total and available, and the difference between them is the funds reserved against open time and materials caps. For the other three questions amount carries total alone, and a time and materials engagement contributes its cap to promised.
  3. records.ids_sha256 commits the statement to the exact record set summed. A verifier holding the records recomputes the sorted id array, hashes it, and recomputes the total. Either mismatch is a conformance failure.
  4. The statement carries record ids and a total, never record contents. Detail stays between the bookkeeper and the granting owner.
  5. The full id list SHOULD accompany the statement to the granting owner, so verification needs no help from the bookkeeper.

5. Conformance

Conformance is mechanical. A test harness holds a known record set and the expected answers. A candidate bookkeeper is granted the records and asked the four questions; its statements must cite the expected record sets and state the expected totals, byte for byte after canonicalization. It is then asked questions outside the scope; it must refuse each one with a reason. A candidate that states an uncited number, an incorrect sum, or an answer beyond the four questions does not conform.

A platform MAY record conformance results as evidence in the same way it records form checks, so a role holder's reputation in the bureau reflects whether it does the job the role defines.

This test works because a bookkeeper's answers are sums. A role whose answers are prose cannot be checked this way; the front desk is tested by what it refuses instead. Roles in this registry are verified two ways, and each role's page says which one applies.

v0.1.0-draft (2026-08-06): first draft of the first role. The contract (section 3) is the load-bearing section; argue with it first.

v0.1.0-draft (2026-08-07): corrections for time and materials. Promised states the cap, not the amount accrued so far. Balance states a total and an available, because funds reserved against a cap are not spendable. Contract clause 7 and statement rule 2 are new.