warp-core: tick receipt blocking causality #148
Conversation
Record which applied candidates block rejected rewrites (Paper II poset edges) without changing the decision digest format. Refs #147
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings. WalkthroughThe PR extends TickReceipt to record blocking causality for rewrites rejected due to footprint conflicts by adding per-entry blocker lists. It refactors digest computation into helpers, introduces footprint conflict detection, updates TickReceipt’s constructor and accessor, and adds multi-blocker tests and documentation updates. Decision_digest remains unchanged. Changes
Sequence Diagram(s)sequenceDiagram
participant Scheduler
participant RewriteSet
participant ConflictDetector
participant Receipt
Note over Scheduler,Receipt: Tick execution with blocking-causality tracking
Scheduler->>RewriteSet: drain batch of rewrite candidates
loop per candidate (canonical plan order)
RewriteSet->>ConflictDetector: request conflict check (footprint, reserved set)
alt conflict with reserved entries
ConflictDetector->>ConflictDetector: compute blocker indices (u32)
ConflictDetector->>Receipt: record Rejected entry with blocked_by = [idx...]
else no conflict
ConflictDetector->>RewriteSet: mark candidate reserved/accepted
ConflictDetector->>Receipt: record Applied entry with blocked_by = []
end
end
Note over Receipt: entries aligned with blocked_by vectors (same length)
Scheduler->>Receipt: construct TickReceipt(tx, entries, blocked_by)
Note over Receipt: decision_digest excludes blocked_by metadata
Estimated code review effort🎯 4 (Complex) | ⏱️ ~50 minutes Possibly related PRs
Poem
Pre-merge checks and finishing touches✅ Passed checks (5 passed)
✨ Finishing touches
🧪 Generate unit tests (beta)
📜 Recent review detailsConfiguration used: Organization UI Review profile: ASSERTIVE Plan: Pro 📒 Files selected for processing (4)
🧰 Additional context used📓 Path-based instructions (1)**/*.rs📄 CodeRabbit inference engine (AGENTS.md)
Files:
🧠 Learnings (1)📚 Learning: 2025-12-28T23:14:28.083ZApplied to files:
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
🔇 Additional comments (11)
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. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 7
📜 Review details
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
📒 Files selected for processing (7)
crates/warp-core/src/engine_impl.rscrates/warp-core/src/receipt.rscrates/warp-core/tests/tick_receipt_tests.rsdocs/aion-papers-bridge.mddocs/decision-log.mddocs/execution-plan.mddocs/spec-merkle-commit.md
🧰 Additional context used
📓 Path-based instructions (1)
**/*.rs
📄 CodeRabbit inference engine (AGENTS.md)
**/*.rs: Every public API across crates (warp-core, warp-ffi, warp-wasm, etc.) must carry rustdoc comments that explain intent, invariants, and usage. Treat missing docs as a failing test.
Runcargo clippy --all-targets -- -D missing_docsbefore every PR; CI will expect a zero-warning, fully documented surface.
Every source file must start with exactly:// SPDX-License-Identifier: Apache-2.0and// © James Ross Ω FLYING•ROBOTS <https://github.com/flyingrobots>
Files:
crates/warp-core/src/receipt.rscrates/warp-core/src/engine_impl.rscrates/warp-core/tests/tick_receipt_tests.rs
🧠 Learnings (3)
📚 Learning: 2025-12-28T23:14:28.083Z
Learnt from: CR
Repo: flyingrobots/echo PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-28T23:14:28.083Z
Learning: Every meaningful design choice should land in `docs/` (specs, diagrams, memorials) or other durable repo artifacts (e.g. `docs/decision-log.md`).
Applied to files:
docs/decision-log.md
📚 Learning: 2025-12-28T23:14:28.083Z
Learnt from: CR
Repo: flyingrobots/echo PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-28T23:14:28.083Z
Learning: Start each session by updating *Today's Intent* in `docs/execution-plan.md` and capture milestones, blockers, and decisions in the Decision Log.
Applied to files:
docs/execution-plan.md
📚 Learning: 2025-12-28T23:14:28.083Z
Learnt from: CR
Repo: flyingrobots/echo PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-28T23:14:28.083Z
Learning: When a PR touches non-doc code, update `docs/execution-plan.md` and `docs/decision-log.md` in the same PR.
Applied to files:
docs/execution-plan.md
🧬 Code graph analysis (2)
crates/warp-core/src/engine_impl.rs (2)
crates/warp-core/tests/tick_receipt_tests.rs (2)
compute_plan_digest(26-34)compute_rewrites_digest(36-51)crates/warp-core/src/receipt.rs (3)
blocked_by(79-81)new(32-45)tx(49-51)
crates/warp-core/tests/tick_receipt_tests.rs (4)
crates/warp-core/src/payload.rs (1)
encode_motion_payload(19-25)crates/warp-core/src/ident.rs (2)
make_node_id(37-42)make_type_id(29-34)crates/warp-core/src/engine_impl.rs (2)
scope_hash(426-431)new(74-76)crates/warp-core/src/receipt.rs (4)
new(32-45)blocked_by(79-81)tx(49-51)entries(55-57)
🔇 Additional comments (11)
docs/execution-plan.md (1)
38-43: LGTM — execution plan entry is thorough.The entry accurately captures scope, exit criteria, and evidence for the blocking causality feature. It correctly notes that
decision_digestremains stable and that multi-blocker tests were added.docs/spec-merkle-commit.md (1)
67-70: Excellent clarification on digest scope.This note is critical for implementers and future maintainers: the digest commits only to outcomes, not blocker metadata. This preserves hash stability as rejection explanations evolve. Well-documented.
docs/aion-papers-bridge.md (2)
63-63: Paper II mapping is accurate.The backlog table correctly reflects that tick receipts now implement blocking attribution with the caveat that richer rejection reasons are pending. The touchpoints reference the correct source files.
138-138: Notable gap section correctly describes the blocking witness.The description accurately captures that blocker indices are in canonical plan order and represent a minimal poset edge list. This aligns with the implementation in
engine_impl.rs.docs/decision-log.md (1)
9-9: Decision log entry is comprehensive.The entry clearly documents: (1) what changed (blocking-causality witness), (2) why (Paper II alignment, deterministic debugging), (3) how (indices of applied candidates, canonical plan order), and (4) consequences (tools can surface explanations, commit IDs remain stable). Based on learnings, this follows the project convention for recording design decisions.
crates/warp-core/src/receipt.rs (1)
59-75: Rustdoc is excellent — semantics and invariants are crystal clear.The documentation precisely specifies:
- Indices are into
entries()- Sorted, no duplicates, strictly less than
idx- Empty for
Applied, non-empty forRejected(FootprintConflict)- Not included in digest
This is the documentation standard every public API should meet. As per coding guidelines, treating missing docs as a failing test — this passes with honors.
crates/warp-core/src/engine_impl.rs (3)
197-198: Documentation accurately describes the blocking causality witness.The comment correctly notes this is a "minimal blocking-causality witness / poset edge list, per Paper II". Good alignment with the spec documentation.
392-417: Digest helpers are clean and correctly handle empty cases.Both
compute_plan_digestandcompute_rewrites_digest:
- Return canonical empty digest for empty inputs
- Use consistent length-prefixed encoding
- Hash fields in deterministic order
This matches the spec in
docs/spec-merkle-commit.mdand the test helpers intick_receipt_tests.rs.
220-223: Good:u32::try_fromwith proper error propagation.Unlike the
as u64casts elsewhere, this correctly handles the theoretical case of more thanu32::MAXentries. The error message is clear. This is the right pattern.crates/warp-core/tests/tick_receipt_tests.rs (2)
195-278: Multi-blocker test is thorough and correctly validates the feature.The test:
- Sets up two scopes with distinct nodes
- Creates three rules with carefully chosen IDs for deterministic ordering
- Applies all three, expecting A and B to succeed, C to be rejected
- Verifies C is blocked by exactly [0, 1] (both prior candidates)
This directly validates the PR's core feature: multi-blocker causality tracking. The assertions on lines 271-277 are precise and cover the key invariants.
175-183: Good: existing test updated to verify blocker semantics.The additions correctly assert:
- Applied entries have empty blockers
- Rejected entries have non-empty blockers pointing to the applied candidate(s)
This ensures backwards compatibility while adding coverage for the new feature.
Address CodeRabbit review: enforce receipt invariants in release builds, document scheduler reserve rejection contract, and clarify blocker attribution assumptions. Refs #147
|
Addressed CodeRabbit review items:
Re-ran: cargo test --workspace; cargo clippy --workspace --all-targets -- -D warnings -D missing_docs. |
Closes #147
Implements Paper II “blocking causality” witness for tick receipts:
Tests:
Docs:
Notes: