Marten docs: fix stale IRevisioned int->long widening reverted by #4533

[jeremydmiller]

Summary

An early Marten 9 alpha widened IRevisioned.Version from int to long (#3733 / #4377). PR #4533 reverted that before rc.1 — IRevisioned.Version stays int (Marten 8-compatible), and a new ILongVersioned (long) was added for MultiStreamProjection documents whose Version is the global event sequence number. Two docs never got the memo. This is a docs-only fix.

Two fixes

1. docs/migration-guide.md — the "Numeric document revisions widened from int to long" section was entirely stale (it told users to widen every IRevisioned.Version to long). Rewritten to:

   • Lead with the reversal so anyone who read an earlier alpha guide isn't misled.
   • Introduce ILongVersioned with the MultiStreamProjection / global-event-sequence rationale and the Int32 overflow warning.
   • Replace the widen-to-long example with a correct IRevisioned (int, unchanged) / ILongVersioned (long) pair.
   • Every Before | After type in the table was verified against current origin/master source. Only IRevisioned.Version reverted to int; the internal surfaces (DocumentMetadata.CurrentRevision, UpdateRevision/TryUpdateRevision parameters, IRevisionedOperation.Revision, the m.Revision metadata Column<long>) stayed long and are source-compatible via int→long.
   • Dropped the now-false claim that m.Revision.MapTo(...) to an int property throws — RevisionColumn now accepts int or long.
   • References updated to Fix #4526/#4528: revert IRevisioned to int + add ILongVersioned (long) #4533 / Revert IRevisioned to int (V8 signature) + add ILongVersioned (long) support #4526 / Add ILongVersioned support; keep IRevisioned (int) (consume jasperfx#348) #4528 / The default isolation level is set to IsolationLevel.ReadUncommitted on IDocumentSession. Should we make that ReadCommited? #348; Revision needs to be a long and not an int in all usages #3733 / 9.0: widen document Revision int → long (#3733) #4377 are historical.

2. docs/documents/concurrency.md — the embedded sample_versioned_reservation snippet still showed long Version even though its source RevisionedDocuments.cs was already int. Regenerated via mdsnippets (not hand-edited). Unrelated incidental snippet drift in hostbuilder.md / retries.md was reverted to keep this PR focused.

Test plan

• Docs-only — no src/ production changes.
• markdownlint (CI args) clean on both files.
• cspell (CI args, Node 22) clean on both files.
• vitepress build docs renders clean (build complete, no errors).
• grep for residual "widen IRevisioned to long" guidance returns only the new, correct reversal/ILongVersioned content.

Refs #4533, #4526, #4528, #348.

🤖 Generated with Claude Code