[codex] Add event and indexer reconstruction spec

[punk6529]

Summary

Closes #398.

Adds the INT-005 event and indexer reconstruction spec for 6529Stream integration consumers. The guide documents canonical source artifacts, log identity, indexed entities, event-to-state processing, required read-after-event calls, collection/token/drop/auction/payment/randomizer/metadata/governance reconstruction, confirmation/reorg policy, full-rescan recovery, and known event/read gaps.

Also adds a dedicated checker/test pair and wires the new guide into the integrations README, release-readiness dashboard, local gates, CI, release manifest governance docs, release artifacts README, changelog, execution backlog, and generated release artifacts.

Validation

• python -m py_compile scripts\check_events_and_indexing.py scripts\test_events_and_indexing.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
• python scripts\test_events_and_indexing.py
• python scripts\check_events_and_indexing.py
• make events-and-indexing-check
• 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_risk_register.py --check
• 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_changelog_check.py / python scripts\check_changelog.py
• bash -n scripts/check.sh
• PowerShell parser check for scripts\check.ps1
• git diff --check
• make check

Notes

This is documentation, tooling, and release-artifact wiring only. It does not change Solidity runtime behavior or claim live indexer, marketplace, public-beta, or production readiness.

[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 2 hours, 18 minutes, and 16 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: 8be73cf3-9d27-4982-9578-040a55dab8aa

📥 Commits

Reviewing files that changed from the base of the PR and between 2dba644 and f32baf4.

📒 Files selected for processing (26)

• .github/workflows/ci.yml
• CHANGELOG.md
• Makefile
• docs/integrations/README.md
• docs/integrations/events-and-indexing.md
• docs/metadata.md
• docs/release-policy.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_events_and_indexing.py
• scripts/check_integrations_readme.py
• scripts/check_release_readiness.py
• scripts/generate_release_manifest.py
• scripts/test_events_and_indexing.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/event-indexer-reconstruction-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.

[6529bot]

6529bot crypto security analysis - 96a4b0c

Verdict: No security findings.

This PR adds documentation (docs/integrations/events-and-indexing.md), a Markdown checker/test pair, Makefile/CI/PowerShell gate wiring, and regenerated release-manifest/checksum/risk-register artifacts. No Solidity, signing, auth, or runtime web3 code is changed.

I reviewed the changed files for the crypto/security surface in scope:

• The new doc itself is appropriately scoped: it carries the pre-audit/local-baseline disclaimers, does not claim production readiness or live-indexer evidence, and correctly treats replay state as derived from consumed/cancelled storage, signer epoch, domain separation, and deadline rather than from EIP-712 encoding alone. The reorg/confirmation-depth and read-after-event guidance is conservative and does not introduce exploitable guidance (e.g., it explicitly warns that failed withdrawals must not erase credit and that forced ETH has no receipt event).
• scripts/check_events_and_indexing.py parses untrusted-ish local Markdown but operates read-only, resolves link targets via normalize_repo_path with an explicit repo-root containment check (relative_to) that rejects path escapes (scripts/check_events_and_indexing.py:154-160), and performs no shell-out, deserialization, or network I/O. No injection/SSRF/path-traversal exposure.
• Regenerated checksum/manifest artifacts (SHA256SUMS, release-checksums.json, release-manifest.json, bytecode-release-proof.json, risk-register.json) are internally consistent: the new release-manifest.json hash a99bfb89… matches across the checksum bundle and bytecode proof, and the new doc entry hash 28f943b2… is recorded. No secret material or token leakage in the diff.

No realistic exploit path exists in the changed code.

[6529bot]

6529bot general PR review - 96a4b0c

Verdict: Good to merge.

This PR adds a documentation-only slice (INT-005 event/indexer reconstruction spec) plus a checker/test pair and gate wiring. No production code paths are touched. I reviewed the new Python checker and gate integration for correctness.

Nice-to-have

• scripts/check_events_and_indexing.py:283 — Collection, Token, Auction, and Approval are extremely generic REQUIRED_PHRASES. Because matching is a case-insensitive substring over the whole doc, these will almost never fail meaningfully and could mask a regression where the intended entity/event table content is removed but the word still appears in prose. Consider anchoring these to the entity table or event-group context (e.g. require `Approval` as a backticked token, or require the row text) so the checker actually protects the intended structure.
• docs/integrations/events-and-indexing.md:281 (Auction state table) — The doc cross-references StreamAuctions.retrieveAuctionEndTime(tokenId) and StreamMinter.getAuctionEndTime(tokenId), but the linked auction contract source is smart-contracts/AuctionContract.sol. If StreamAuctions/StreamMinter are real on-chain names, fine; if they are aliases, an indexer engineer following the "Source of Truth" links may not find these symbols. Worth a one-line note mapping the documented contract names to the actual source files to avoid confusion.
• scripts/check_events_and_indexing.py normalized_link_target strips both # (anchor) and ? (query) but the LINK_RE already excludes whitespace/closing paren; this is fine, but note the checker only verifies that required targets are present and exist — it does not verify the relative ../../ depth is correct. A wrong-depth link that happens to resolve to an existing file elsewhere would pass. Low risk for this curated doc, but a future copy/paste could slip through.

No correctness, security, or data-integrity issues found. The release-manifest/checksum/risk-register hash updates are consistent across SHA256SUMS, release-checksums.json, release-manifest.json, and bytecode-release-proof.json, and the new gate is wired into Makefile, check.sh, check.ps1, and CI consistently.

[6529bot]

6529bot follow-up commit review - 16e1d5e

Verdict: No new findings

This follow-up commit (2dba644→16e1d5e) only updates ops/AUTONOMOUS_RUN.md and ops/EXECUTION_BACKLOG.md status bookkeeping plus the regenerated risk-register/manifest hashes already covered. The substantive doc, checker, and gate wiring are unchanged from the prior reviewed head (96a4b0c), which I already reviewed in both the general and security passes.

The prior nice-to-have findings (generic REQUIRED_PHRASES like Collection/Token/Auction/Approval, and the StreamAuctions/StreamMinter vs AuctionContract.sol naming note) still stand but were already raised and are not regressions. The release-manifest/checksum/risk-register hash chain remains internally consistent across SHA256SUMS, release-checksums.json, release-manifest.json, and bytecode-release-proof.json.

No new correctness, security, or readiness-boundary issues introduced.

[6529bot]

6529bot follow-up commit review - f32baf4

Verdict: No new findings

This is the same head (f32baf4) and substantive content I reviewed in the prior general/security/follow-up passes. The diff since the prior same-lane marker (16e1d5e) only re-presents the already-reviewed doc, checker, test, gate wiring, and the internally-consistent release-manifest/checksum/risk-register hash chain.

The prior nice-to-have findings still stand but are not regressions and were already raised:

• Generic REQUIRED_PHRASES (Collection, Token, Auction, Approval) match as case-insensitive substrings over the whole doc and won't meaningfully fail (scripts/check_events_and_indexing.py:283).
• StreamAuctions/StreamMinter symbol names in the auction state/read tables vs the AuctionContract.sol source link could confuse an indexer engineer following the "Source of Truth" links (docs/integrations/events-and-indexing.md).

The release-manifest/checksum/risk-register hash chain remains internally consistent across SHA256SUMS, release-checksums.json, release-manifest.json, and bytecode-release-proof.json (new release-manifest.json a99bfb89…, new doc entry 28f943b2…). Makefile, check.sh, check.ps1, and CI wiring for the new gate are consistent. No new correctness, security, or readiness-boundary issues introduced.

[punk6529]

Followed up on the 6529bot nice-to-haves in f32baf4:

• Anchored generic checker phrases to table/event-token shapes (| Collection |, | Token |, | Auction |, backticked approval events).
• Added the StreamAuctions / StreamMinter source-file mapping note and linked smart-contracts/StreamMinter.sol from the source-of-truth table.
• Added path-like Markdown link-label validation plus a regression test for labels that resolve elsewhere.

Focused checks and generated-artifact drift checks passed locally after the follow-up; CI is green on the latest head.