docs: Closing the Books pattern guide + runnable contrast (#139)

[joeldsouzax]

Summary

Closes #139 — the final card in the Tier 1: Table Stakes milestone. Documents the "Closing the Books" event-sourcing pattern as the preferred alternative to aggregate snapshots, with an executable contrast to back the prose.

• Kernel guide module (crates/nexus/src/closing_the_books.rs) — a doc-only //! module shipped on docs.rs next to aggregate/events. Explains the pattern (bounded streams + a first-class summary event carrying minimum state forward), contrasts it with snapshots grounded in nexus's real behaviour (schema_version is a cache key, not a migration engine — no upcasting path for snapshot bytes), and gives honest "when NOT to use it" caveats.
• Runnable example (examples/closing-the-books/) — builds the same cash-register domain two ways and prints the contrast:
  • long-lived CashRegister: one stream, replays all 5001 events to read the current float;
  • bounded CashierShift streams: the current shift replays only 11 events, with final_float (110) carried forward into a brand-new shift stream.
  • Both aggregates reuse the same generic record / replay_stream helpers; 4 AggregateFixture tests cover the CloseShift overage/shortage/guard logic.
• Discoverability — a clickable intra-doc pointer from nexus-store's Snapshotting decorator down to nexus::closing_the_books (the kernel can't link up to the store), and the older 2026-04-10-snapshot-design.md now points at the shipped guide instead of the bare issue number.

Design intent: nexus ships no "close stream"/"archive"/"delete" API — Closing the Books is a modeling discipline (a new stream is just AggregateRoot::new(new_id); the summary is an ordinary DomainEvent).

Test Plan

• nix flake check green on every commit (pre-commit hook)
• cargo test -p nexus-example-closing-the-books — 4/4 fixture tests pass
• cargo run -p nexus-example-closing-the-books — prints 5001-vs-11 event contrast; carried float 110 → recovered float 5100
• cargo doc resolves the nexus::closing_the_books intra-doc link from the snapshot decorator
• cargo clippy --all-targets on the example is warning-clean (reasoned allow for the project-banned saturating_sub nudge)
• All three snapshot-behaviour claims in the guide independently verified against nexus-store source

🤖 Generated with Claude Code