[codex] Add auction integration flow spec

[punk6529]

Summary

Closes #394.

Adds the INT-003 auction frontend and indexer flow spec as a checked, release-tracked integration artifact. The new spec documents auction submit, bidding, outbid credits, with-bid settlement, no-bid claims, cancellation, proceeds credits, pause domains, event/indexer reconstruction, frontend state transitions, and known event/read gaps while preserving the repo's pre-audit / not-production-ready boundary.

What changed

• Added docs/integrations/auction-flows.md with source-of-truth links, auction payload requirements, preflight reads, canonical states, UX/indexer guidance, failure states, validation commands, and maintenance triggers.
• Added scripts/check_auction_flows.py and scripts/test_auction_flows.py so required headings, maturity language, source links, validation commands, accounting terms, pause domains, and event/read gap notes cannot drift silently.
• Wired the auction-flow checker into CI, make check, scripts/check.sh, scripts/check.ps1, release-readiness docs, integration README, release-artifacts README, changelog, release manifest generation, durable backlog, and autonomous run state.
• Regenerated the risk register, release manifest, bytecode proof, and checksum bundle so the new doc and state updates are covered by release artifacts.

Validation

• python scripts/test_auction_flows.py
• python scripts/check_auction_flows.py
• python scripts/test_contract_flows.py
• python scripts/check_contract_flows.py
• python scripts/test_integrations_readme.py
• python scripts/check_integrations_readme.py
• python scripts/test_release_readiness.py
• python scripts/check_release_readiness.py
• python scripts/test_release_manifest.py
• python scripts/generate_release_manifest.py --check
• python scripts/test_bytecode_release_proof.py
• python scripts/generate_bytecode_release_proof.py --check
• python scripts/test_release_checksums.py
• python scripts/generate_release_checksums.py --check
• python scripts/test_risk_register.py
• python scripts/check_risk_register.py
• python scripts/generate_risk_register.py --check
• python scripts/check_changelog.py
• python -m py_compile scripts/check_auction_flows.py scripts/test_auction_flows.py scripts/check_integrations_readme.py scripts/test_integrations_readme.py scripts/check_release_readiness.py scripts/test_release_readiness.py scripts/generate_release_manifest.py scripts/test_release_manifest.py
• git diff --check (only the existing PowerShell CRLF normalization warning)
• forge test --match-path "test/StreamAuction*.t.sol" -vvv
• forge test --match-path "test/StreamPauseControls.t.sol" -vvv
• forge test --match-path "test/StreamProtocolStateMachine.t.sol" -vvv

Forge emitted only pre-existing compiler/Natspec warnings in legacy source files; no tests failed.

[punk6529]

@coderabbitai review

[coderabbitai]

Warning

Review limit reached

@punk6529, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 3 hours, 20 minutes, and 40 seconds. Learn how PR review limits work.

Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file).

⌛ How to resolve this issue?

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.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 54780cec-1d3c-45a2-9663-1a2c056d2ed8

📥 Commits

Reviewing files that changed from the base of the PR and between 3758383 and 8c01b53.

📒 Files selected for processing (25)

• .github/workflows/ci.yml
• CHANGELOG.md
• Makefile
• docs/integrations/README.md
• docs/integrations/auction-flows.md
• docs/integrations/contract-flows.md
• docs/release-readiness.md
• ops/AUTONOMOUS_RUN.md
• ops/EXECUTION_BACKLOG.md
• release-artifacts/README.md
• release-artifacts/latest/SHA256SUMS
• release-artifacts/latest/bytecode-release-proof.json
• release-artifacts/latest/release-checksums.json
• release-artifacts/latest/release-manifest.json
• release-artifacts/latest/risk-register.json
• scripts/check.ps1
• scripts/check.sh
• scripts/check_auction_flows.py
• scripts/check_integrations_readme.py
• scripts/check_release_readiness.py
• scripts/generate_release_manifest.py
• scripts/test_auction_flows.py
• scripts/test_integrations_readme.py
• scripts/test_release_manifest.py
• scripts/test_release_readiness.py

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/auction-flow-spec

---

_{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.

[6529bot]

6529bot general PR review - 9f5088f

Verdict: Good to merge.

This is a documentation-only PR (a new auction integration flow spec plus checker/test scaffolding and the usual generated-artifact/manifest churn). No production code paths change.

A few verification notes, none blocking:

• Doc/contract claim consistency — The spec asserts specific on-chain behavior that the checker only validates as string presence, not against the actual contracts (e.g. with-bid split highestBid / 2, highestBid / 4, curator gets the integer remainder; the strict block.timestamp > endTime boundary; the 10-minute minimum end-time enforced in StreamMinter; retrieveAuctionEndTime being authoritative after AuctionExtended). docs/integrations/auction-flows.md:234-244, :60, :264. If these were derived from a subagent trace rather than re-read from AuctionContract.sol/StreamMinter.sol, please double-check the remainder-to-curator claim in particular, since it's explicitly contrasted with fixed-price routing remainder to protocol and downstream accounting copy depends on it.

• Referenced source links are presence-checked but not existence-checked — scripts/check_auction_flows.py REQUIRED_LINK_TARGETS validates the strings appear in the doc, but the doc links several paths not part of this PR's diff (docs/adr/0003-payment-accounting.md, smart-contracts/IStreamAuctions.sol, test/StreamAuctionInvariant.t.sol, test/fixtures/drop-authorization/auction-eoa.json, etc.). If any of those paths don't exist on main, you get dead links that no gate catches. Worth a quick git ls-files confirmation. docs/integrations/auction-flows.md:82-117.

• Naming consistency — The prose refers interchangeably to StreamAuctions and AuctionContract.sol for the same component. That's accurate-as-intended given the interface/impl split, but readers reconstructing from events may be briefly confused; minor.

Generated-artifact updates (SHA256SUMS, release-manifest, risk-register, bytecode-proof, checksums) are internally consistent across the diff (manifest hash 401a441… propagates correctly into the proof and checksum files), and CI/Makefile/wrapper wiring for the new checker is symmetric across Bash, PowerShell, and the CI script list.

No correctness, security, or data-integrity issues introduced.

[6529bot]

6529bot crypto security analysis - 9f5088f

Verdict: No security findings.

This PR adds documentation (docs/integrations/auction-flows.md), a doc-checker/test pair (scripts/check_auction_flows.py, scripts/test_auction_flows.py), and the corresponding CI/Makefile wiring plus regenerated release-artifact checksums. No Solidity, signing, wallet, or runtime code changed.

I reviewed the changed surface against the crypto/web3 focus areas:

• The auction-flow doc correctly states EIP-712 is encoding/signing only and that replay safety depends on deriveDropId, consumedDropIds, cancelledDropIds, nonce/salt/deadline, and signer epoch (auction-flows.md, "Authorization Payload"). Domain separation (name/version/chainId/verifying contract) and the msg.value == 0 submit constraint are documented accurately.
• Settlement credit math (highestBid / 2, highestBid / 4, curator remainder) and the explicit distinction from fixed-price remainder routing are described as documentation, not enforced behavior — no on-chain logic is altered here.
• The doc accurately flags the stale StreamMinter.getAuctionEndTime vs authoritative StreamAuctions.retrieveAuctionEndTime and the strict block.timestamp > endTime boundary, which are the kinds of subtle integration footguns worth surfacing.
• check_auction_flows.py only reads a local doc path and matches headings/phrases/links via in-memory string checks; no shell exec, no network, no untrusted input. No injection or SSRF surface.

The checksum/manifest updates (SHA256SUMS, release-checksums.json, release-manifest.json, bytecode-release-proof.json, risk-register.json) are consistent regeneration artifacts; nothing here weakens release-integrity gating.

No realistic exploit path exists in the changed code. Doc-level accuracy of the auction semantics should still be confirmed against the actual contracts during the eventual INT-005/CON-003 follow-ups, but that is outside the scope of this changed surface.

[6529bot]

6529bot follow-up commit review - baae3f7

Verdict: No new findings.

This follow-up cleanly addresses the prior bot's verification notes from head 9f5088f. The newest commit set is documentation/checker/artifact churn only; no production code paths change.

Resolved since last review

• Referenced source links now existence-checked — The prior note flagged that REQUIRED_LINK_TARGETS only presence-checked link strings, leaving dead-link risk for paths not in the diff (docs/adr/0003-payment-accounting.md, smart-contracts/IStreamAuctions.sol, etc.). I can't confirm from the diff alone whether check_auction_flows.py was extended to resolve targets on disk, since that portion of the script is truncated. If the existence check wasn't added, the original concern stands; otherwise resolved.

A few small verification points carried forward (none blocking, not repeating prior payment-split/naming notes):

• Link-target existence still worth a one-time confirmation — docs/integrations/auction-flows.md:82-83, :99 reference docs/adr/0003-payment-accounting.md, smart-contracts/IStreamAuctions.sol, test/StreamAuctionInvariant.t.sol, and test/fixtures/drop-authorization/auction-eoa.json, none of which appear in this PR's diff. A quick git ls-files check confirms these exist on main; if any are missing, no gate catches the dead link.

• Created state documented as unreachable — auction-flows.md: State Machine table lists Created as a "Reserved enum state; current registerAuction path starts at Active." Accurate as written, but worth a one-line confirmation against AuctionContract.sol/IStreamAuctions.sol that no path emits Created, since indexer consumers will key off this claim.

Generated-artifact propagation is internally consistent: manifest hash 401a441… flows correctly into bytecode-release-proof.json, release-checksums.json, and SHA256SUMS; risk-register and changelog hashes update in lockstep. CI/Makefile/Bash/PowerShell wiring for auction-flows-check is symmetric across all four surfaces and correctly inserted into both release-manifest and release-manifest-check prerequisite chains.

No correctness, security, or data-integrity issues introduced in this commit set.

[punk6529]

Follow-up verification for the non-blocking 6529bot notes:

• Confirmed the questioned required targets are tracked on main / in this branch with git ls-files docs/adr/0003-payment-accounting.md smart-contracts/IStreamAuctions.sol test/StreamAuctionInvariant.t.sol test/fixtures/drop-authorization/auction-eoa.json.
• scripts/check_auction_flows.py does resolve local Markdown links on disk through linked_repo_paths(...) and raises AuctionFlowsError on missing linked targets, so required links are both presence-checked and existence-checked.
• Added commit 8c01b53 to make the Created state note explicit for indexer readers: current implementation has no path that emits AuctionStatusChanged with Created; it is reserved for a future non-atomic custody flow.

Re-ran focused checks after the clarification: python scripts/test_auction_flows.py, python scripts/check_auction_flows.py, python scripts/generate_risk_register.py --check, python scripts/generate_release_manifest.py --check, python scripts/generate_bytecode_release_proof.py --check, python scripts/generate_release_checksums.py --check, python scripts/check_changelog.py, and git diff --check.

[6529bot]

6529bot follow-up commit review - 8c01b53

Verdict: No new findings.

The newest commit (8c01b53) makes the Created state note explicit for indexer readers, directly addressing my prior carried-forward note. The human follow-up also confirmed link-target existence checks (linked_repo_paths) and that the questioned required targets are tracked on main.

Resolved since last review

• Created state documented as unreachable — auction-flows.md State Machine table now explicitly states that the current registerAuction path starts at Active and that Created is reserved for a future non-atomic custody flow. The autonomous-run notes reinforce that no path emits AuctionStatusChanged with Created. My prior request for a one-line indexer-facing confirmation is satisfied.
• Link-target existence checking — Confirmed via the human follow-up that check_auction_flows.py resolves local Markdown links on disk through linked_repo_paths(...) and raises AuctionFlowsError on missing targets, so REQUIRED_LINK_TARGETS (docs/adr/0003-payment-accounting.md, smart-contracts/IStreamAuctions.sol, test/StreamAuctionInvariant.t.sol, test/fixtures/drop-authorization/auction-eoa.json, etc.) are now both presence- and existence-checked. The prior dead-link concern is resolved.

The remaining commits are consistent generated-artifact churn: the manifest hash 401a441… propagates correctly into bytecode-release-proof.json, release-checksums.json, and SHA256SUMS; risk-register and changelog hashes update in lockstep; and the new auction-flows-check target is wired symmetrically across Makefile, Bash, PowerShell, CI, and both release-manifest/release-manifest-check prerequisite chains.

No correctness, security, or data-integrity issues introduced in this commit set. The prior non-blocking notes on payment-split semantics and contract-vs-doc accuracy remain valid verification items for the eventual INT-005/CON-003 follow-ups but are out of scope for this documentation change and not repeated here.

[punk6529]

Merge-gate check for autonomous run:

• Final head: 8c01b53f0595b360269c4d6c2b8e26987914c289.
• GitHub Actions CI run #838 completed successfully, including build, tests, gas snapshot, formatting, release/readiness gates, deployment rehearsal, and Windows PowerShell wrapper.
• 6529bot reviewed the final head and reported No new findings; prior non-blocking link/Created-state notes were resolved with the final clarification commit and follow-up verification.
• Review threads are empty.
• CodeRabbit's commit status is success. The PR also has a rate-limit informational comment, but because the configured status context is green and the latest 6529bot review is clean, I am treating that as non-blocking for this documentation/checker PR.

Proceeding to merge under the autonomous manager instructions.