feat(event): add failure-atomic slab/ring admission boundary (ADR-0009) - #1862
Conversation
Composite volatile admission channel binding one published-prefix page to one SPSC descriptor ring, under Proposed ADR-0009: - try_admit publishes page-then-ring with no fallible work between the page publication and ring publication phases; a caught unwind closes the page, Release-stores FAULTED, closes the ring, and resumes the panic so a retained producer is terminal, never an atomically open poisoned lane - consumer validation fails closed: sequence gap/duplicate/reorder, arena identity, payload range, and CRC faults withhold the tail, disconnect the producer, and poison the consumer; ring invariant errors Release-close the ring before surfacing - malformed terminal closure states (clean-without-page-close, unknown raw state, count mismatches in either direction) never report CleanEnd - endpoints are Send but deliberately not Sync; frame leases are neither Send nor Sync (compile_fail doc-tests enforce all of it) Evidence: retained-producer caught-unwind tests at every publication phase, corrupt-descriptor and terminal-state fixtures, Loom models including a validation-failure vs reserved-publication race, full Miri, ASan/TSan clean on the final state, zero-allocation admission bench, and CI lanes extended for the admission suite. Status honesty: ADR-0009 is Proposed; the fabric remains target, unwired, with no performance claims (Implementation_Status ledger, MIGRATION_MATRIX delta, ROADMAP, LLD updated in the same change).
macOS resolves Installation.md case-insensitively, the Linux CI runner does not — these three links failed the demo-guardrails docs validation on every PR since #1858 landed.
Replace the community blanket rust.lang.security.unsafe-usage rule (excluded via --exclude-rule) with rust-unsafe-outside-reviewed-crates, which still blocks any unsafe outside lib/event. The event-fabric crates (ADR-0006..0009) carry isolated, SAFETY-documented unsafe gated by the event-concurrency, event-miri and event-sanitizers CI lanes, per the CONTRIBUTING unsafe evidence standard and docs/architecture.md §8. Verified with semgrep 1.169 locally: the scoped rule fires on unsafe outside lib/event, stays silent inside it, and --exclude-rule suppresses the registry rule (finding count 1 -> 0 on a synthetic case). Approved by operator (scoped rule swap chosen over per-site nosemgrep annotations).
|
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 selected for processing (25)
📝 WalkthroughWalkthroughChangesThe PR adds a process-local Event admission prototype
Estimated code review effort: 5 (Critical) | ~120 minutes Sequence Diagram(s)sequenceDiagram
participant Producer
participant SlabPage
participant Ring
participant Consumer
Producer->>SlabPage: validate and append payload
Producer->>Ring: publish descriptor
Consumer->>Ring: claim descriptor
Consumer->>SlabPage: validate descriptor and payload
Consumer->>Ring: commit lease and advance tail
Possibly related PRs
Suggested reviewers: ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Warning Tools execution failed with the following error: Failed to run tools: 13 INTERNAL: Received RST_STREAM with code 2 (Internal server error) 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 implements a failure-atomic single-page slab/ring admission prototype (VolatileAdmissionChannel) under the proposed ADR-0009, introducing SPSC ring permit/claim APIs, benchmarks, and extensive test coverage. The documentation has been thoroughly updated to reflect these changes. Feedback on the changes highlights a critical issue in the Semgrep configuration, where the exclusion pattern for 'lib/event/*' needs to be recursive ('lib/event/**') to avoid failing SAST checks on unsafe blocks in subdirectories.
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.
| - pattern: unsafe fn $F(...) { ... } | ||
| paths: | ||
| exclude: | ||
| - "lib/event/*" |
There was a problem hiding this comment.
The glob pattern lib/event/* is non-recursive in Semgrep and will only exclude files directly under the lib/event/ directory (such as Cargo.toml). It will not exclude files in subdirectories like lib/event/src/ring.rs, which will cause Semgrep to fail on the unsafe blocks in those files. Use lib/event/** to recursively exclude the entire directory.
- "lib/event/**"
Summary
Follow-up to #1861 (which merged before this work was pushed to its branch — these three commits are rebased onto main).
ADR-0009 — failure-atomic slab/ring admission (
lib/event/src/admission.rs, Proposed): composite volatile channel binding one published-prefix page to one SPSC descriptor ring.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.CI-gate fixes (both were failing on #1861 and will fail on every PR until landed):
docs:threeInstallation.mdlinks in the World-Class HLD/LLD break on Linux's case-sensitive filesystem (pre-existing from docs(architecture): add bare-metal Thread-Per-Core blueprint (HLD/LLD/migration matrix) #1858) — fixed toinstallation.md.ci(sast):the community blanketrust.lang.security.unsafe-usagerule blocks on anyunsaferepo-wide, including the ADR-gated event crate's isolated,// SAFETY:-documented unsafe. Replaced withrust-unsafe-outside-reviewed-crates, which still blocks unsafe everywhere exceptlib/event(gated by the event-concurrency / event-miri / event-sanitizers lanes). Verified with semgrep 1.169 locally: fires outsidelib/event, silent inside it, and--exclude-rulesuppresses the registry rule. Operator-approved trade-off (scoped rule swap over per-sitenosemgrepannotations).Status honesty (per
docs/architecture.mdvocabulary)ADR-0009 is Proposed; the admission prototype is
currentonly as isolated, unwired code + tests. The production event fabric remainstarget— noshadowtraffic, no performance claims.Implementation_Status.md,MIGRATION_MATRIX.md,ROADMAP.md,ARCHITECTURE.md,docs/LLD.md, and the ADR index are updated in the same change.Test plan
All verified locally on the final state:
cargo fmt --all -- --check,cargo clippy -p aegis-event --all-targets --all-features -- -D warningscargo test -p aegis-eventand--all-features(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.compile_faildoc-tests)-Zbuild-std) onadmission+published_slabsuitescargo check --workspace,node scripts/validate-docs.mjs,node scripts/audit-doc-quality.mjs --checkSummary by CodeRabbit
New Features
Documentation
Tests & Security