docs: describe the shape and what enforces each boundary

[iamsiddhesh-dev]

The third of the three submission deliverables — public repo, pitch video,
architecture doc. Everything it describes now exists, which is why it was worth
waiting to write.

Deliberately narrow, because three documents already exist and overlapping them
would make all four worse. README has the result. DECISIONS has the alternatives
that were rejected. FAILURES has the ten things this got wrong. ARCHITECTURE has
the shape.

What it contains

The dependency graph, one diagram. world knows nothing about agent; agent
knows nothing about world; eval and web know about both and neither knows
about them.

One payment, end to end — as a Mermaid sequence diagram across all eight
participants, from webhook to RECOVERED | STOPPED. Every arrow is a function call
a reader can follow.

Four boundaries, each with the mechanism that enforces it. This is the section
that earns the document. An architecture doc that lists boundaries is describing
intentions, so each one names what makes it true and the test that fails if it is
removed:

• the wall → an AST test over recoup/agent/**, in CI
• the adapter seam → two protocols, and a constructor that refuses to exist against
  a live key
• the compliance gate → a veto that runs after the policy and can only subtract,
  with load-time validation of every config key that names something in code
• the LLM boundary → five batched calls, each a fallback, each degrading to
  deterministic behaviour

The ledger as the spine, including the actual DDL — two triggers, two indexes —
and what is deliberately not stored: three fields removed after measuring that
they were ~45% of the file.

A degradation table. Eight rows: no key, no key and no cache, provider 5xx,
malformed output, no run, no cache dir, no Razorpay key, a live key. The
through-line is that nothing in the recovery path may depend on a network service
being reachable.

Where to start reading — a table mapping "if you want to check X" to the file
that answers it, ending with python -m recoup reproduce.

Verified rather than remembered

Every factual claim was checked against the code before committing, not written
from memory:

• module and line counts read from git ls-files
• 7 event kinds and MAX_DECISIONS_PER_PAYMENT = 12 imported and printed
• all seven protocol methods asserted present on PaymentsAdapter and Notifier
• the live-mode guard exercised — constructing with an rzp_live_ key raises
  TestModeViolation
• all 18 backticked paths and every markdown link resolved against the filesystem
• the Mermaid diagram actually rendered in a browser against Mermaid 10.9.1,
  confirming it parses and lays out with all eight participants, rather than
  assuming the syntax was right

That last one caught nothing, but "the architecture doc has a broken diagram at the
top" is a bad way to open a submission.

Also

README said FAILURES had "eight things", stale since two entries were added. Now ten,
and ARCHITECTURE is linked from the reading list.

Verification

pytest — 487 passed. ruff check . clean. No code changed.