Accept randomness ADR

[punk6529]

Summary

• Adds docs/adr/0005-randomness.md as the accepted randomness design for public-beta work.
• Defines provider-backed async randomness, canonical request lifecycle state, provider/randomizer epoch validation, deterministic retry limits, seed/hash storage policy, metadata pending behavior, and weak-helper production scoping.
• Updates the ADR index, roadmap P0 randomness entry, Slither weak-prng rows, test matrix, and autonomous run state with issue traceability.

Issues

• Closes [P0-RAND-ADR] Decide randomness provider model and retire or contain weak block-based helpers #14 once merged.
• Links follow-up implementation issues [P0-RAND-001] Harden randomizer requests and callbacks #37 through [P0-RAND-007] Decide and implement raw random words versus derived hash storage policy #43.

Validation

• rg -n "^#|^##|^###" docs\adr\0005-randomness.md docs\adr\README.md ops\ROADMAP.md ops\SLITHER_BASELINE.md ops\AUTONOMOUS_RUN.md
• rg -n "P0-RAND-ADR|issues/14|issues/37|issues/38|issues/39|issues/40|issues/41|issues/42|issues/43|0005-randomness|randomizerEpoch|RandomizerNXT|XRandoms|weak-prng|zero hash|Zero derived|on-chain metadata|RandomnessRequested|RandomnessFulfilled|FailedPostProcessing" docs\adr\0005-randomness.md docs\adr\README.md ops\ROADMAP.md ops\SLITHER_BASELINE.md ops\AUTONOMOUS_RUN.md
• rg -n "[^\x00-\x7F]" docs\adr\0005-randomness.md docs\adr\README.md ops\ROADMAP.md ops\SLITHER_BASELINE.md ops\AUTONOMOUS_RUN.md returned no matches.
• git diff --check
• git diff --cached --check
• make check passed with 17 tests and known compiler/NatSpec warnings.
• powershell -ExecutionPolicy Bypass -File scripts\check.ps1 passed with 17 tests and known compiler/NatSpec warnings.

Notes

Claude review may not run automatically in this repository, so I will add an explicit review-request comment after opening the PR.

Summary by CodeRabbit

• Documentation
  • Added a new Architecture Decision Record for production randomness (accepted) detailing request lifecycle, validation rules, observability, rollout and test requirements.
  • Updated ADR index, ADR tracking, roadmap, operations logs, and baseline docs to reflect the randomness ADR, related tasks, test matrix expansions, and current repository state.

[claude]

⚠️ Code review skipped — your organization's overage spend limit has been reached.

Code review is billed via overage credits. To resume reviews, an organization admin can raise the monthly limit at claude.ai/admin-settings/claude-code.

Once credits are available, push a new commit or reopen this pull request to trigger a review.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 91d9928b-09b8-4d76-a70e-c9a5e37d6f49

📥 Commits

Reviewing files that changed from the base of the PR and between 8b84c74 and 5a95055.

📒 Files selected for processing (1)

• ops/AUTONOMOUS_RUN.md

---

📝 Walkthrough

Walkthrough

Adds and accepts ADR 0005 defining asynchronous provider-backed randomness with explicit request lifecycle, strict callback validation, provider eligibility/exclusions, canonical seed/hash storage and metadata rules; updates roadmap P0-RAND-001 requirements and test matrix, revises Slither baseline wording, and records ADR acceptance in ops/state documents.

Changes

Randomness ADR 0005 Specification and Alignment

Layer / File(s)	Summary
ADR 0005 Randomness Specification docs/adr/0005-randomness.md	Accepted ADR defining asynchronous provider-backed randomness with explicit request lifecycle (pending/fulfilled/stale/failed), callback validation rules (request/provider/token/collection/epoch/seed/hash), provider eligibility (VRF-preferred; arRNG conditional; block-derived excluded from production), collection-level epoch/migration policy, canonical derived seed/hash domain separation and storage policy, metadata pending vs final rendering tied to request state, burned-token callback rules, payment/reserve accounting constraints, required events and views, implementation requirements, P0 test list, rollout/migration steps, and open follow-ups.
Roadmap P0-RAND-001 Hardening Requirements and Test Matrix ops/ROADMAP.md	Expands P0-RAND-001 to require strict request lifecycle tracking and views, fulfillment-by-request-id semantics, explicit pending/failed states, provider epoch/migration observability, removal/isolation of weak helper randomness from production, lifecycle events and views, extended negative test cases (unknown/wrong request/provider/token/collection/epoch, zero derived seed/hash), and tightened acceptance criteria and test matrix entries.
Slither Baseline Documentation ops/SLITHER_BASELINE.md	Rewords the weak-prng baseline rows for XRandoms.randomNumber() and randomWord() updating the Resolution and Required test narratives to reflect ADR decisions.
ADR Acceptance Status and Project State Tracking docs/adr/README.md, ops/AUTONOMOUS_RUN.md	Marks ADR 0005 as Accepted in ADR README. Updates autonomous-run and PR worklog state to record PR #36 as merged, set codex/randomness-adr as active branch, introduce Randomness ADR PR #44 work item with created issues and validation checklist, and extend Decision Log with PR #36 merge and Randomness ADR startup steps.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related issues

• [P0-RAND-007] Decide and implement raw random words versus derived hash storage policy #43: ADR 0005 defines derived seed/hash storage and metadata rules matching issue questions about storing raw random words vs derived hashes.
• [P0-RAND-005] Define and test randomizer migration with pending requests #41: ADR 0005 specifies collection-level epoch and migration/staleness policy relevant to migration-with-pending-requests tests.
• [P0-RAND-001] Harden randomizer requests and callbacks #37: ADR 0005 provides the canonical request/fulfillment lifecycle and validation rules required by the P0-RAND-001 implementation issue.

Possibly related PRs

• 6529-Collections/6529Stream#3: Related edits to roadmap and autonomous-run control-plane documents; this PR continues roadmap/ops alignment for randomness.
• 6529-Collections/6529Stream#32: Related via payment/reserve accounting alignment between ADR 0005 and ADR 0003 definitions.
• 6529-Collections/6529Stream#16: Earlier work creating/propagating P0-RAND-ADR and baseline artifacts referenced/extended by this PR.

Poem

🐰 I hopped a doc for randomness clear,
Requests and callbacks now hold near,
Weak helpers shelved in test-only shade,
VRF paths brighten the production glade,
Roadmap and baseline aligned — a tidy cheer!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'Accept randomness ADR' is concise and directly reflects the main change: the acceptance and inclusion of the new randomness ADR design document.
Linked Issues check	✅ Passed	The PR fulfills issue #14 objectives: it creates and accepts ADR 0005 with provider model, request lifecycle states, callback validation rules, weak helper scoping, deterministic retry policy, and updates roadmap/Slither baseline docs.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to documenting the randomness design: new ADR file, ADR index update, ops roadmap/state/baseline refinements, and test matrix alignment for follow-up implementation work.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/randomness-adr

---

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

[punk6529]

@claude please review this PR.

Focus areas:

• whether ADR 0005 covers the real randomness/callback risks in StreamCore, RandomizerVRF, RandomizerRNG, RandomizerNXT, and XRandoms
• whether the provider-backed request lifecycle, randomizer epoch, stale callback, retry, seed storage, metadata pending, and weak-helper production-scope decisions are internally consistent
• whether the roadmap/test matrix/Slither baseline updates are issue-ready for follow-up implementation PRs

This is documentation/design only; no Solidity behavior changes are intended in this PR.