docs: add full contract reference for tholos-v2

[Theophilus131]

close #99 

What

Adds docs/src/CONTRACT_V2.md, a complete reference for contracts/tholos-v2's
public interface — types, every function, the full Error enum, the event
table, security notes, and persistent-storage TTL behavior — in the same
structure CONTRACT.md already uses for v1.

Why

v1 has full reference docs; v2 only had a lightweight lifecycle table in
INTEGRATION.md (signatures + one-liners, no error variants, no event
table, no security/TTL notes) even though v2's lifecycle
(assert_outcome → withdraw, plus set_paused_v2/cancel_round) is now
fully implemented. This closes that documentation gap.

Structure choice

Went with a separate CONTRACT_V2.md (option 1 in the issue) rather than
extending CONTRACT.md with a v2 section — v2's interface is large enough
(11 functions, 36 errors, 12 events) that folding it into the existing
296-line v1 doc would make both harder to scan. Registered under
docs/src/SUMMARY.md as a nested entry under the existing v1 "Contract
Reference" item.

Verification

Every function signature, error variant, event field, and behavioral claim
was checked line-by-line against contracts/tholos-v2/src/lib.rs (not
just copied from doc comments) while writing this. In particular:

• get_resolution/get_position both surface AssertionNotFound for a
  missing record (not a dedicated error), matched from the source.
• settle and withdraw fetch AssertionV2 before Resolution and use
  NotResolved/NoCreditToWithdraw specifically for the
  UncontestedFinalize case, which never has a Resolution — documented
  as such rather than assumed.
• The PhaseV2::Reveal / terminal_cause distinction (a majority can
  lock while phase stays Reveal) is called out explicitly, since it's
  easy to get wrong from the type alone.

Checklist

• docs/src/CONTRACT_V2.md added, same structure as CONTRACT.md
• docs/src/SUMMARY.md updated so mdbook build includes the new page
• Cross-checked against contracts/tholos-v2/src/lib.rs, not restated
  from doc comments

[collinsezedike]

One general note not tied to a single line: INTEGRATION.md's existing "Lifecycle at a glance" section fully duplicates this doc's lifecycle/function content, with no cross-reference either way. Worth linking one to the other so they don't silently drift.

[collinsezedike]

The diagram lists register as a trigger for the lazy Registration → Reveal transition, but register never calls open_reveal_phase. After the deadline it just returns Error::RegistrationClosed (see test_register_after_deadline_fails). Only reveal and resolve_outcome open reveal phase.

[collinsezedike]

This edge is mislabeled two ways. "Strict majority locked" doesn't by itself cause the phase transition, your own prose right below this diagram says phase stays Reveal after a majority locks. And reveal itself can also close Reveal → Resolved in the same call when it's the last outstanding weight, not just resolve_outcome.

[collinsezedike]

This row says AdminCancelled only applies to a Registration/Reveal-phase assertion, but cancel_round also handles a still-Pending assertion (refunding the asserter's bond directly). Your own Functions section for cancel_round describes that Pending path correctly, this table row contradicts it.

[collinsezedike]

AssertionNotFound doesn't cover a missing credit. get_credit returns 0 via unwrap_or(0), and withdraw returns NoCreditToWithdraw for a zero balance, not AssertionNotFound. Drop "credit" from this row.

[collinsezedike]

These four "7 days" references (here, InvalidRevealDuration, InvalidChallengeWindow, and the initialize prose) point at three separately-defined constants in lib.rs that just happen to share a value today. Worth naming them individually, like the TTL section does with INSTANCE_BUMP_AMOUNT, so a future change to just one doesn't leave the others silently stale.

[collinsezedike]

This says cancel_round doesn't move tokens, but it does, it refunds the asserter's bond directly (same acquire/transfer/release pattern as withdraw) when the assertion is still Pending. It shouldn't be grouped with reveal/resolve_outcome/settle here.

[collinsezedike]

This PR's diff shows this line changing even though nothing here should differ, it's a UTF-8 BOM getting silently added to the file start. Probably an editor artifact. Worth stripping before merge, it's noise unrelated to the PR's purpose.

[collinsezedike]

Hey @Theophilus131, just checking in on this one, still no rush. There's a review with a few concrete mismatches to fix, let me know if anything's unclear or if you'd like a hand.