feat(event): add published-prefix SPSC primitives and failure-atomic admission (ADR-0006..0009) - #1861
Merged
Merged
Conversation
Contributor
|
ECC bundle files are already tracked in this repository. Skipping generation of another bundle PR. |
|
Caution Review failedThe pull request is closed. ℹ️ Recent review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: ⛔ Files ignored due to path filters (1)
📒 Files selected for processing (27)
📝 WalkthroughWalkthroughChangesEvent fabric prototypes
Estimated code review effort: 4 (Complex) | ~60 minutes Sequence Diagram(s)sequenceDiagram
participant Producer
participant SpscRing
participant Consumer
participant PublishedSlabReader
Producer->>SpscRing: try_push descriptor
Consumer->>SpscRing: try_pop descriptor
Consumer->>PublishedSlabReader: resolve descriptor
PublishedSlabReader-->>Consumer: validated payload
Suggested reviewers: ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
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 |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces the aegis-event crate (lib/event), which implements high-performance, unwired v2 event primitives for the target data plane, including a cache-padded SPSC ring buffer, a safe sealed-page oracle, and an append-only published-prefix slab page. These additions are accompanied by extensive documentation updates, including proposed ADRs (0006, 0007, and 0008), benchmarks, and unit/integration tests. The reviewer suggested a valuable improvement to enforce the SPSC ring capacity constraints at compile time using const assertions instead of runtime checks, which would simplify the public API.
Important
The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.
Comment on lines
+211
to
+222
| fn validate_capacity<const N: usize>() -> Result<(), RingConfigError> { | ||
| if N == 0 { | ||
| return Err(RingConfigError::ZeroCapacity); | ||
| } | ||
| if !N.is_power_of_two() { | ||
| return Err(RingConfigError::NotPowerOfTwo { capacity: N }); | ||
| } | ||
| if (N as u128) >= (1_u128 << 63) { | ||
| return Err(RingConfigError::SequenceAmbiguous { capacity: N }); | ||
| } | ||
| Ok(()) | ||
| } |
There was a problem hiding this comment.
The runtime check validate_capacity is called on every instantiation of SpscRing. Since N is a const generic parameter, we can enforce these constraints at compile time using a const assertion. This would turn potential runtime errors into compile-time errors, simplifying the public API by allowing SpscRing::new to return Self directly instead of a Result (though keeping the Result for backwards compatibility or transition is also fine).
const _ASSERT_VALID_CAPACITY: () = {
assert!(N > 0, "SPSC ring capacity must be non-zero");
assert!(N.is_power_of_two(), "SPSC ring capacity must be a power of two");
assert!(N < (1 << 63), "SPSC ring capacity must be smaller than 2^63");
};
fn validate_capacity<const N: usize>() -> Result<(), RingConfigError> {
Ok(())
}
lavkushry
changed the title
lavkushry
changed the title
This was referenced Jul 13, 2026
lavkushry
added a commit
that referenced
this pull request
Jul 14, 2026
Conformance scan findings: the workspace tree omitted lib/event (present on main since #1861 under Proposed ADRs), and 'introduced only through accepted ADRs' contradicted the ADR index rule that Proposed ADRs permit unwired prototypes — which is exactly how lib/event exists today.
lavkushry
added a commit
that referenced
this pull request
Jul 14, 2026
* feat(event): add ADR-0010 rotating admission prototype (unwired) RotatingAdmissionChannel<N, P>: one SPSC descriptor ring spanning a continuous sequence across a bounded series of published-prefix page epochs (generation tag = epoch as u32, at most P live). - rotation only on typed page/descriptor-full results and only before ring reservation; ADR-0009's [P]->[R]->[C] phase discipline unchanged - typed PageQuotaExhausted backpressure with zero page/ring mutation when all P slots are outstanding (quota check precedes the seal) - reclamation via one consumer->producer released-epoch Release/Acquire edge; the frame lease's mutable borrow of the consumer proves no payload borrow survives a release - successor readers travel a bounded SPSC handoff ring whose publication happens-before the epoch's first data-ring descriptor; an absent handoff at a seam is terminal, never transient - seam-strengthened terminal semantics: epoch-boundary committed-count shortfall, generation skip, handoff identity mismatch, orphaned final prefix all fail closed; caught-unwind rotation faults leave a retained producer terminal Disclosed prototype deviations (ADR §Prototype notes): rebind allocates one bounded page per rotation (in-place reuse precedes shadow); P is a power of two >= 2; construction rejects a nonzero arena_generation. Evidence: 11 native unit tests (rotation at byte/descriptor exhaustion with sequence/generation continuity, quota refusal + recovery with nothing mutated, seam shortfall, generation skip, faulted orphan, clean aggregate end, post-seal unwind, alignment), 10k-event cross-thread rotation stress + pool-bound test (wired into the ASan/TSan CI lanes as --test rotating), a bounded Loom seam model (seal/handoff/[R]/[E] interleavings; the initial unbounded-poll model was rewritten after it demonstrably exploded Loom's state space), full Miri, all-features clippy. Status honesty: ADR-0010 remains Proposed; the fabric remains target with no shadow traffic and no performance claim. * docs: align CLAUDE.md with the shipped tree and ADR vocabulary Conformance scan findings: the workspace tree omitted lib/event (present on main since #1861 under Proposed ADRs), and 'introduced only through accepted ADRs' contradicted the ADR index rule that Proposed ADRs permit unwired prototypes — which is exactly how lib/event exists today. * docs: correct code_tour gateway layout to the real src/src tree Conformance scan: the onboarding tour pointed agents at settings.rs, axum_app.rs, tonic_app.rs, handlers/, middleware.rs and startup.rs — none of which exist. The actual gateway binary is src/src/ with main.rs, routes/, and grpc.rs; the thin-adapter law those names illustrated lives in docs/architecture.md §5 and is unchanged.
3 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds the unwired
aegis-eventprototype crate (lib/event/) implementing the Week-4 roadmap deliverables under four new Proposed ADRs, in two commits:Commit 1 —
9d7208e(ADR-0006..0008 primitives)ring.rs,descriptor.rs).slab.rs).published_slab.rs).Commit 2 —
5d4c491(ADR-0009 failure-atomic admission)admission.rs).try_admitpublishes page-then-ring with no fallible work between the publication phases; a caught unwind closes the page, Release-storesFAULTED, closes the ring, and resumes the panic — a retained producer is terminal, never an atomically open poisoned lane.CleanEnd.Sendbut deliberately notSync; frame leases are neitherSendnorSync— enforced bycompile_faildoc-tests.Status honesty (per
docs/architecture.mdvocabulary)currentonly as isolated, unwired code + tests. The production event fabric remainstarget— noshadowtraffic, no production wiring, cannot carry protected evidence, and no performance claims are made.Implementation_Status.md(v2 migration ledger),MIGRATION_MATRIX.md(post-audit delta against frozen baselinef027d07),ROADMAP.md,current-vs-roadmap.md,ARCHITECTURE.md,docs/LLD.md, ADR index,README.md,mkdocs.yml.CI
New jobs gate the crate:
event-concurrency(native + all-features tests, Loom models, all-feature clippy, exact runtime dependency-allowlist assertion, bench compile check),event-miri, andevent-sanitizers(ASan/TSan matrix; Miri remains the Rust UB/provenance gate — nightly has noundefinedsanitizer for Rust). The admission suite is wired into all three lanes.Test plan
All re-verified locally on the final state of both commits:
cargo fmt --all -- --check,cargo clippy -p aegis-event --all-targets --all-features -- -D warningscargo test -p aegis-eventand--all-features(incl. retained-producer caught-unwind tests at every publication phase, corrupt-descriptor and terminal-state fail-closed fixtures)cargo test -p aegis-event --features loom loom_(incl. validation-failure vs reserved-publication race model)cargo +nightly miri test -p aegis-event(incl. allcompile_faildoc-tests)-Zbuild-std) onadmission+published_slabintegration suitescargo check --workspace,node scripts/validate-docs.mjs(0 errors/warnings),node scripts/audit-doc-quality.mjs --checkevent-concurrency,event-miri,event-sanitizerslanes green on this PR