feat: add jurisdiction gating and per-holder dividend accrual ledger`

[ryzen-xp]

• Close Add jurisdiction tagging on holder records with compliance-gated transfer guard #451
• Close Add dividend accrual ledger so unclaimed revenue compounds per-holder until claim #449

PR Description

Summary

This PR combines #451 and #449 into a single compliance + payout correctness update for Revora-Contracts.

It adds per-holder jurisdiction tagging with an issuer-managed allowlist that gates new share assignments and snapshot share imports, and it introduces a per-holder dividend accrual ledger so already-deposited revenue is claimed using the holder's historical share at accrual time rather than the holder's current share at claim time.

What Changed

Jurisdiction tagging and compliance gating (#451)

• Added per-holder jurisdiction storage and issuer-only management APIs.
• Added per-offering allowed jurisdiction configuration.
• Enforced jurisdiction gating on:
  • set_holder_share
  • meta_set_holder_share
  • apply_snapshot_shares
• Added structured rejection with RevoraError::JurisdictionDisallowed.
• Emitted:
  • jur_set for jurisdiction / allowlist updates
  • jur_reject for blocked share writes or snapshot imports
• Preserved non-retroactive behavior:
  • removing a jurisdiction does not invalidate already-persisted holder shares
  • existing holders can still claim previously recorded entitlements

Dividend accrual ledger (#449)

• Added a cumulative per-offering accrual index and per-holder accrual/checkpoint state.
• deposit_revenue now updates the global accrual index and emits acc_upd.
• Holder share changes are checkpointed so claims use the historical share active when revenue accrued.
• claim and claim previews no longer reprice all pending history using the holder's current share.
• Preserved existing claim semantics:
  • claim delay remains enforced per deposited period
  • partial claims still advance only through processed periods
  • retries remain safe when transfers fail

Important Implementation Note

Issue #449 suggested updating accrual on report_revenue, but in this codebase actual claimable value is created by deposit_revenue, not report_revenue. The accrual index is therefore updated on deposit_revenue so the ledger matches the real payout path.

Why This Matters

Before this PR, a holder's share could be changed before claim and unintentionally reprice already-deposited revenue. After this PR, share changes are forward-looking only, which makes claim outcomes stable, auditable, and compliance-safe.

Testing

Ran:

cargo test --all

Result:

99 passed, 0 failed, 0 ignored
6 doc tests ignored

Added coverage for:

• jurisdiction allowlist storage and events
• disallowed jurisdiction rejection paths
• non-retroactive jurisdiction removal
• issuer transfer migration of jurisdiction config
• historical-share payout correctness after share changes
• zeroing a holder after accrual without burning prior entitlement
• claimable preview parity with historical share schedule
• claim delay behavior with share changes mid-stream

Security Notes

• Jurisdiction configuration is mutable only by the issuer and emits audit events.
• Disallowed jurisdictions are rejected with a structured error and audit trail.
• Removing a jurisdiction does not retroactively block recorded holders.
• Share changes no longer rewrite economic entitlement for already-deposited periods.
• Claim delay and claim cursor invariants remain intact under the new accrual model.

Docs

• Added jurisdiction documentation in docs/jurisdiction-tagging.md
• Added accrual ledger documentation in docs/dividend-accrual-ledger.md
• Updated README.md for new events, behavior, and invariants

[drips-wave]

@ryzen-xp Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits