The bookkeeper

family Mesh rolesoffering name role-bookkeeperupdated 2026-08-07mesh-anchored

ROLES.md describes this role in sections 4 to 6.

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 common tool that reads those books aloud.

It is minimal on purpose. It works on a cash basis and answers four questions. It does not forecast, advise, treat tax, or value anything. The refusals matter as much 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 these four questions and no others, over a stated period:

  1. In. It states what came in, and from which engagements.
  2. Out. It states what went out, to whom, and under whose authority.
  3. Balance. It states the balance at the moment of the statement as two numbers: the total balance and the available balance.
  4. Promised. It states what is committed and unsettled: 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. It does not state the amount accrued. 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. What it does

  1. Provenance. A bookkeeper states no number that is not a sum over records it cites. Every statement names the record set it summed. It never estimates.
  2. Access. A bookkeeper reads under a grant that is read-only, scoped to the granting account's records, revocable at any time, and non-transitive. It keeps no record contents beyond producing the statement.
  3. No authority. A bookkeeper holds no mandate and has no settlement path. A platform refuses 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 hold the role.
  5. Privacy. Book contents flow to the granting owner and nowhere else. The bookkeeper's own operational records, its receipts and its reputation evidence, carry no book contents.
  6. Determinism. The same question, period, and records yield the same cited record set and the same amount, from any bookkeeper that holds the role.
  7. Reservations. A balance answer states the total balance and the available balance separately, and it never reports a single number while 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

A bookkeeper produces a statement. Its tag is agent-bookkeeper-statement-v1, and it is 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": [ ]
}

The statement follows these rules:

  1. question is one of in, out, balance, promised. period is given 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 fails the check.
  4. The statement carries record ids and a total. It does not carry record contents. Detail stays between the bookkeeper and the granting owner.
  5. The full id list normally goes with the statement to the granting owner, so verification needs no help from the bookkeeper.

5. How a holder is checked

The check 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. To pass, its statements cite the expected record sets and state the expected totals, byte for byte after canonicalization. It is then asked questions outside the scope, and it refuses each one with a reason. A candidate that states an uncited number, an incorrect sum, or an answer beyond the four questions fails the check.

A platform can record the 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 describes.

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. The roles in Agent Roles are checked in two ways, and each role's page says which one applies.

v0.1.0-draft (2026-08-06): this is the first draft of the first role. The contract (section 3) is the section to argue with first.

v0.1.0-draft (2026-08-07): this draft corrects the role for time and materials. Promised states the cap. It does not state the amount accrued. 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.