docs: model freezes as owned holds

[0xgleb]

Motivation

The scheduled freeze-window implementation in #239 dispatches idempotent
Freeze and Unfreeze toggles. Two overlapping or adjacent windows can
therefore release each other: an earlier window's unfreeze can enable the asset
while a later window still requires the supply gate to remain closed.

Records the architectural decision discovered while reviewing
RAI-1045.

Solution

• Model freeze requirements as typed, independently owned holds in the
  TokenizedAsset aggregate.
• Derive supply availability from whether any hold remains active.
• Give scheduled windows and operator actions distinct stable hold identities.
• Preserve historical replay by treating legacy freeze events as the operator
  hold.
• Record why scheduler-only merging, queue inspection, and delivery ordering do
  not enforce the domain invariant.

This PR contains the proposed ADR only. The implementation is intentionally
stacked as a separate draft so both the decision and its consequences remain
independently reviewable.

Checks

By submitting this for review, I'm confirming I've done the following:

• added comprehensive test coverage for any changes in logic (no runtime logic changes)
• made this PR as small as possible
• linked any relevant issues or PRs

[coderabbitai]

Warning

Review limit reached

@0xgleb, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 19 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: d244b83c-b729-4d75-8b70-99ff7a83f3f5

📥 Commits

Reviewing files that changed from the base of the PR and between e47e0db and fff2221.

📒 Files selected for processing (1)

• adrs/01-model-freezes-as-owned-holds.md

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/model-freezes-as-owned-holds

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[0xgleb]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• fix: reconcile corporate-action mutations durably #282
• docs: consume corporate-action mutations durably #281
• fix: recover orphaned mint jobs after restart #256
• feat: notify corporate-action lifecycle #244
• feat: source the freeze schedule from Alpaca dividend announcements #240
• fix: preserve overlapping freeze windows #255
• docs: model freezes as owned holds #254 👈 (View in Graphite)
• feat: schedule freeze/unfreeze windows via durable apalis jobs #239
• feat: move mint recovery onto durable jobs #208
• feat: run the mint flow's side effects in durable jobs #207
• refactor: extract a reusable durable-job runner #206
• ops: add multichain staging validation runbook and smoke script #219 : 1 other dependent PR (#220 )
• chore: document multichain chain registry env in .env.example #218
• fix: remove unused rsa development dependency #242
• refactor: share per-network vault services #241
• feat: lift corporate-action freeze to underlying scope #235
• feat: partition receipt backfill and reconcile by chain #217
• feat: route redemption detect, Alpaca redeem, and burn through ChainRegistry #215
• feat: route mint vault calls through ChainRegistry #212
• feat: AssetKey aggregate id and network-aware asset lookup #214
• feat: introduce ChainRegistry for multichain #210
• docs: SPEC multi-chain section (gate) #209
• docs: finish Turnkey recovery documentation #264
• ci: preserve workflow and harness hardening #263
• fix: classify mint recovery state #262
• fix: retry receipt inventory conflicts #261
• feat: guard unresolved burn admin recovery #260
• feat: recover persisted burn transactions #257
• fix: refuse ambiguous prior burns #253
• fix: reject burn receipts without block numbers #252
• fix: persist mint transaction intent before broadcast #251
• feat: migrate Turnkey to SIGN_TRANSACTION #249
• fix: preserve transaction ID variants on replay #248
• fix: pin Turnkey signature response parsing #247
• fix: surface per-receipt reconciliation error count and correct reconcile doc #233
• fix: use primary-key lookup in find_by_client_id and reject embedded whitespace in emails #232
• fix: count Alpaca-rejected recoveries as auto-failed and log redemption-flow task panics #231
• docs: correct cqrs.md and recovery guide to match event-sorcery architecture #227
• fix: record mirror balance (not available) when recovering an ITN mint receipt #225 : 1 other dependent PR (#226 )
• fix: retry Alpaca redeem calls and tolerate absent tx_hash in poll responses #224
• fix: keep polling redemptions when Alpaca returns an empty tx_hash #223
• feat: dynamic asset monitoring without a restart #123
• feat: durable mint recovery via apalis job queue #118
• Update SPEC for Removal of Fireblocks, replace with generic signing backend terminology #230
• Update Docs #229
• Remove Fireblocks from NixOS deployment setup #228
• replace fireblocks with turnkey #221
• feat: crash-safe burn idempotency via pre-signed tx #211
• NixOS stack deployment setup #204 : 1 other dependent PR (#234 )
• main

---

How to use the Graphite Merge Queue

Add the label add-to-gt-merge-queue to this PR to add it to the merge queue.

You must have a Graphite account in order to use the merge queue. Sign up using this link.

An organization admin has required the Graphite Merge Queue in this repository.

Please do not merge from GitHub as this will restart CI on PRs being processed by the merge queue.

This stack of pull requests is managed by Graphite. Learn more about stacking.

[graphite-app]

Merge activity

• Jul 24, 1:35 AM UTC: 0xgleb added this pull request to the Graphite merge queue.
• Jul 24, 1:36 AM UTC: CI is running for this pull request on a draft pull request (#290) due to your merge queue CI optimization settings.
• Jul 24, 1:37 AM UTC: Merged by the Graphite merge queue via draft PR: #290.