Add payment invariant baseline

[punk6529]

Summary

• Add StreamPaymentsInvariantTest, a bounded sequence fuzz harness for the current first-party payment surfaces.
• Exercise mixed fixed-price mint, auction mint/bid/settlement, curator claim, withdrawal, emergency withdrawal, randomizer reserve, and forced-balance surplus operations.
• Assert category totals, totalOwed() views, balance coverage, randomizer reserves, and emergencyWithdrawable() views after every generated action.
• Update roadmap/status/test/Slither traceability for the new Gate D payment invariant baseline while keeping future shared-ledger abstraction work open.

Closes #8.

Validation

• forge test --match-path test\StreamPaymentsInvariant.t.sol -vvv passed: 1 fuzz test, 256 runs.
• make check passed: 188 tests.
• powershell -ExecutionPolicy Bypass -File scripts\check.ps1 passed: 188 tests.
• forge fmt --check test\StreamPaymentsInvariant.t.sol passed.
• git diff --check passed.
• Markdown heading scan passed for roadmap/status/test/Slither docs.
• Slither confirmation: 693 total findings, 4 High, 19 Medium, with high/medium unchanged; arbitrary-send-eth=0, reentrancy-eth=0, reentrancy-no-eth=0 after scoped test-harness suppressions documented in ops/SLITHER_BASELINE.md.

Summary by CodeRabbit

• New Features

  • Added a bounded-sequence payment invariant baseline that exercises mixed operations (mints, auctions, curator flows, reserves, forced balances, emergency withdrawals) and validates ledger coherence after each step.

• Tests

  • Introduced an automated invariant harness that runs seed-derived operation sequences and asserts payment-category totals, contract balance coverage, and emergency-withdrawable constraints.

• Documentation

  • Updated blockers, status, roadmap, and static-analysis baseline to reflect the new invariant coverage and remaining gaps.

[claude]

Claude Code Review

This repository is configured for manual code reviews. Comment @claude review to trigger a review and subscribe this PR to future pushes, or @claude review once for a one-time review.

_{Tip: disable this comment in your organization's Code Review settings.}

[punk6529]

@coderabbitai 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: 09d582c3-0a9e-4205-a3b4-dd2570863682

📥 Commits

Reviewing files that changed from the base of the PR and between 54597ea and 5b25559.

📒 Files selected for processing (2)

• ops/AUTONOMOUS_RUN.md
• test/StreamPaymentsInvariant.t.sol

✅ Files skipped from review due to trivial changes (1)

• ops/AUTONOMOUS_RUN.md

🚧 Files skipped from review as they are similar to previous changes (1)

• test/StreamPaymentsInvariant.t.sol

---

📝 Walkthrough

Walkthrough

Adds a 24-step bounded payment-sequence fuzz invariant harness (test/StreamPaymentsInvariant.t.sol) and updates docs, roadmap, Slither baseline, test README, and autonomous run state to record the new invariant baseline and related metadata.

Changes

Payment Invariant Baseline

Layer / File(s)	Summary
Bounded Payment Sequence Invariant Test Harness test/StreamPaymentsInvariant.t.sol	StreamPaymentsInvariantTest runs a fixed 24-step bounded fuzz with seed-derived handler actions (fixed-price, auction, curator, randomizer, forced-balance, emergency-withdraw operations). PaymentsInvariantHandler deploys/wires system contracts and exposes action methods; after each step three invariants are asserted: category-total coherence, contract balance coverage of owed/reserved funds, and emergency-withdrawable surplus boundaries. Test-only mocks InvariantDelegation and InvariantArrngController support delegation and randomizer request IDs.
Test Documentation test/README.md	Documents StreamPaymentsInvariant.t.sol bounded sequence fuzz invariant baseline, listing mixed operations and the invariant surfaces asserted after each step (category totals, totalOwed() views, balance coverage, reserves, emergencyWithdrawable()).
Status and Known Blockers Refinement docs/known-blockers.md, docs/status.md	Refines blockers to emphasize StreamDrops reserve-credit recording for fixed-price mints, records that local-ledger fixed-scenario coverage plus a bounded payment sequence invariant baseline exists, and narrows known-blocker tracking to unified pull-payment ledger abstraction, fuller randomizer lifecycle accounting, callback-after-burn policy, and canonical randomizer lifecycle.
Roadmap and Test Matrix Updates ops/ROADMAP.md	Advances Gate D ("Test And Invariant Baseline Complete") to In Progress citing test/StreamPaymentsInvariant.t.sol, marks P0-PAY-001 payment invariants as implemented for current local ledgers, updates Appendix B test-matrix rows for payment ledger totals, withdrawal failure behavior, emergency surplus boundary, randomness reserve accounting, and forced ETH accounting, and reflects Slither finding total update (668→693).
Slither Baseline Integration ops/SLITHER_BASELINE.md	Refreshes Slither baseline timestamp and impact counts, adds a narrative delta attributing increases to test/StreamPaymentsInvariant.t.sol, includes the new test in required-test lists for four arbitrary-send-eth findings, and records scoped source-level suppressions tied to the invariant harness and mocks.
Autonomous Control Plane State ops/AUTONOMOUS_RUN.md	Updates durable run state to set active PR branch to codex/add-payment-invariant-baseline, marks Queue Item 34 merged as PR #76, and records Queue Item 35 / PR #77 as in-progress with worklog, validation notes, and Decision Log entries.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• 6529-Collections/6529Stream#60: Exercises fixed-price mint/credit/withdraw/emergency-withdrawable flows that the new invariant harness validates.
• 6529-Collections/6529Stream#58: Adds auction bid/settle and outbid-refund pull-credit behavior that the invariant harness exercises.
• 6529-Collections/6529Stream#62: Related emergency-withdrawal surplus-bounding semantics validated by the new invariant suite.

Poem

🐰 A bounded sequence of hops and claims,
Through mints and bids and withdrawal frames,
Each surplus checked, each owed amount proved,
Local ledgers balanced, invariants grooved. 🌿💰

🚥 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 PR title 'Add payment invariant baseline' accurately summarizes the main change: introducing StreamPaymentsInvariantTest to establish a bounded-sequence fuzz invariant baseline for payment surfaces.
Linked Issues check	✅ Passed	The PR implements all required coding outcomes from issue #8: adds owed-balance invariants proving contract balance covers owed funds, bounds emergency withdrawals to surplus-only, covers mint/bid/claim/withdraw/forced-ETH scenarios, and updates SLITHER_BASELINE.md with test harness suppressions.
Out of Scope Changes check	✅ Passed	All changes directly support the payment invariant baseline objective: StreamPaymentsInvariant.t.sol implements the fuzz harness, while docs/roadmap/status/Slither updates properly trace the new Gate D baseline evidence.
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/add-payment-invariant-baseline

---

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

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[punk6529]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 2

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

ops/AUTONOMOUS_RUN.md (1)

2883-2961: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Incomplete merge timestamp for PR #76.

Line 2955 records the merge timestamp as 2026-06-10 without the time component, while other completed PRs in this file consistently include both date and time (e.g., line 142 shows 2026-06-09 23:33 UTC). This inconsistency may complicate future chronological tracing of autonomous execution events.

📅 Suggested fix

-- Merged as PR `#76` on `2026-06-10`.
+- Merged as PR `#76` on `2026-06-10 20:18 UTC`.

The timestamp 20:18 UTC is derived from decision log line 3270.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@ops/AUTONOMOUS_RUN.md` around lines 2883 - 2961, Update the merge timestamp
for PR `#76`: replace the date-only "2026-06-10" entry in the "PR `#76`: Prove
vendored library provenance (Queue Item 34)" section with the full UTC datetime
"2026-06-10 20:18 UTC" (use the decision log line 3270 as the source); ensure
the entry format matches other completed PRs like the example "2026-06-09 23:33
UTC" so chronological tracing remains consistent.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@ops/AUTONOMOUS_RUN.md`:
- Line 2962: Update the worklog header "### PR TBD: Add payment invariant
baseline (Queue Item 35)" to reference the actual pull request number used later
in the section; replace "PR TBD" with "PR `#77`" (matching the URL
https://github.com/6529-Collections/6529Stream/pull/77) so the header reads "###
PR `#77`: Add payment invariant baseline (Queue Item 35)" for consistency with
other completed PR entries.

In `@test/StreamPaymentsInvariant.t.sol`:
- Line 45: The test currently reuses actionSeed as rawBid when calling
handler.bidAuction(firstArg, secondArg, actionSeed), which biases bids because
actionSeed is already used to select the action; fix by decoupling bid
generation from action selection: derive a separate bidSeed (e.g., bidSeed =
uint256(keccak256(abi.encode(actionSeed, SOME_CONSTANT))) or use another RNG
input) and compute rawBid from that seed, then clamp it into the expected bid
range before passing it to handler.bidAuction; update the call site to pass this
new rawBid instead of actionSeed and keep references to handler.bidAuction,
actionSeed and rawBid to locate the change.

---

Outside diff comments:
In `@ops/AUTONOMOUS_RUN.md`:
- Around line 2883-2961: Update the merge timestamp for PR `#76`: replace the
date-only "2026-06-10" entry in the "PR `#76`: Prove vendored library provenance
(Queue Item 34)" section with the full UTC datetime "2026-06-10 20:18 UTC" (use
the decision log line 3270 as the source); ensure the entry format matches other
completed PRs like the example "2026-06-09 23:33 UTC" so chronological tracing
remains consistent.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: c98767b2-90df-4707-b62b-9c8b14b234d0

📥 Commits

Reviewing files that changed from the base of the PR and between 4f1e69a and 54597ea.

📒 Files selected for processing (7)

• docs/known-blockers.md
• docs/status.md
• ops/AUTONOMOUS_RUN.md
• ops/ROADMAP.md
• ops/SLITHER_BASELINE.md
• test/README.md
• test/StreamPaymentsInvariant.t.sol

[punk6529]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.