> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vinmake.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Trusted responses and honest unavailability

> How GreatBook keeps bad evidence small, visible, and unable to become a reassuring default.

# Trusted responses and honest unavailability

GreatBook does not treat a successful HTTP request as trustworthy accounting evidence.
Every response used by the finance workspace must resolve to trusted data or to an explicit unavailable reason before the screen can make a claim.

The shared rule lives in the GreatBook web repository's `src/lib/trusted-response.ts` and is consumed across the shipped Typewriter, Review, Settlements, Ledger, Accounting, Audit, Files, Planning, and Actions read paths.
It is the boundary that prevents three particularly dangerous UI failures: inventing a replacement record, hiding an unreadable record, and turning unknown data into an empty or reassuring default.

## Refuse only the smallest unsafe scope

| Defect in the server evidence                                                 | What the user sees                                                                   |
| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| one optional or required field is malformed                                   | that field is unavailable; the rest of the row may remain readable                   |
| a non-identity part of one row is malformed                                   | an unreadable row remains in its original list position with its identity and reason |
| a row identity, page envelope, pagination fact, or query binding is malformed | the page is unavailable; GreatBook does not guess which rows belong                  |
| one evidence cluster contradicts itself                                       | that cluster is unavailable; unrelated clusters remain readable                      |
| the dataset or view contradicts itself                                        | the whole view is unavailable                                                        |

Aliases and repeated signals must agree exactly.
For example, two copies of approval evidence do not become stronger by disagreeing: GreatBook quarantines the authorization cluster and makes no approver claim.

## Unknown is not empty

Lists accept the server's `total`, `count`, `limit`, `offset`, `has_more`, and `next_offset` only when those facts reconcile with the returned records and the requested page.
The browser does not derive a total from the rows it happened to receive, invent a continuation offset, remove a malformed row, or call an unreadable response empty.

When a refresh fails, earlier evidence may remain visible only as retained evidence.
It cannot authorize a mutation or navigation until a current response confirms it again.
Likewise, a mutation's transport success is not durable acceptance: the UI requires exact request-bound server evidence, and an unknown outcome stays awaiting confirmation.

<Frame caption="The credential-free demo publishes an unreadable pagination envelope. Audit says the register could not be read and explicitly refuses the all-clear that an empty table would imply.">
  <img src="https://mintcdn.com/vinmake/56mx-KkSKyEFY2E7/images/greatbook/features/trusted-response-audit-unavailable.png?fit=max&auto=format&n=56mx-KkSKyEFY2E7&q=85&s=2313e7d25b4eac277700f9c6938bf40d" alt="The current GreatBook Audit register refusing an unreadable pagination envelope and stating that nothing has been checked" width="1440" height="1080" data-path="images/greatbook/features/trusted-response-audit-unavailable.png" />
</Frame>

<Frame caption="The same rule is scoped independently on the human worklist: lane counts are unavailable, the list makes no empty claim, and the reason remains visible.">
  <img src="https://mintcdn.com/vinmake/56mx-KkSKyEFY2E7/images/greatbook/features/trusted-response-human-tasks-unavailable.png?fit=max&auto=format&n=56mx-KkSKyEFY2E7&q=85&s=f94ebc7e331747002d7b2dfa08ad7e3c" alt="The current GreatBook human worklist refusing a missing demo response rather than showing an empty worklist" width="1440" height="1080" data-path="images/greatbook/features/trusted-response-human-tasks-unavailable.png" />
</Frame>

These are unretouched captures from the current default-branch UI running against its credential-free demo services.
The deliberately incomplete demo responses are useful here because the shipped claim is the refusal itself, not that a live organization has no records.

## Verified at source

* The GreatBook web repository's `src/lib/trusted-response.ts` defines `trusted`, `unavailable`, the five scopes, exact agreement, row identity preservation, and page-position rules.
* Its `docs/crash-safety-check.md` names the customer-facing list contract and the exact totals and continuation facts each list must preserve.
* Merged web PRs `#55`–`#58` apply the boundary to the finance surfaces and canonical settlements.
* Merged backend PR `#100` makes statements fail closed and publishes server-owned totals and continuation for the paged lists.