docs(architecture): add bare-metal Thread-Per-Core blueprint (HLD/LLD/migration matrix) - #1858
Conversation
…/migration matrix) Cherry-picked from the parallel architecture/documentation pass, rebased onto current main (includes the merged tool-broker extraction and node-sensor real-host proof) -- bins/aegis-node-sensor/tests/real_host_integration.rs is intentionally left untouched at its already-merged (5-test) version; this commit only touches architecture/documentation files. - ARCHITECTURE.md: Thread-Per-Core HLD, SPSC topology, NUMA/copy budgets, capacity equations, and benchmark contract (<1ms p99 covers warm deterministic authorization compute; durable approval/receipt commits are a separate, explicitly out-of-scope path). - docs/LLD.md: HCMT physical format, WAL/recovery, Gorilla/Roaring encodings, CoreReactor/SPSC skeletons, Aho/HNSW/PQ/ONNX/eBPF/UI designs, protobuf and FlatBuffer schemas, exact Cargo pins. - MIGRATION_MATRIX.md: repository-backed audit, concurrency inventory, component mappings, preservation ledger, deletion gates, cutover sequence. - README.md/CONTRIBUTING.md/ROADMAP.md: bare-metal product positioning (targets kept explicitly separate from measured SQLite performance), ADR/unsafe-Rust/lock-free/SIMD/zero-copy/benchmark/security requirements, 36-week phased program. - docs/architecture.md, AGENTS.md, CLAUDE.md, doc indexes, MkDocs nav, and validation tooling aligned to the new documents. This is a blueprint/documentation deliverable, not the runtime implementation described in it. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
|
Warning Review limit reached
Next review available in: 14 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (18)
✨ Finishing Touches🧪 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 |
|
ECC bundle files are already tracked in this repository. Skipping generation of another bundle PR. |
![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 a comprehensive architectural transition for AegisAgent toward a performance-first v2 target, featuring thread-per-core reactors, SPSC rings, and Hybrid Columnar Merge Trees (HCMT). The changes are detailed in the newly added ARCHITECTURE.md, MIGRATION_MATRIX.md, and docs/LLD.md files, alongside updates to core documentation, contributing guidelines, and the project roadmap. The review feedback highlights critical inconsistencies within the new low-level design (docs/LLD.md), specifically naming discrepancies for the tenant snapshot struct, conflicting trait definitions for the authorization service, and a missing constant definition for MAX_BROWSER_BATCH_BYTES in the limits section.
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.
| pub policy_set: cedar_policy::PolicySet, | ||
| pub aho_generation: u64, | ||
| pub emergency_epoch: u64, | ||
| pub expires_mono_ns: u64, |
There was a problem hiding this comment.
There is a naming inconsistency for the snapshot struct. In section 6, it is defined as TenantPolicySnapshot, but in section 25.1 and the class diagram, it is referred to as TenantControlSnapshot. Please unify the struct name across all sections to maintain consistency.
| pub trait AuthorizeService { | ||
| fn authorize( | ||
| &mut self, | ||
| ctx: &AuthenticatedContext, | ||
| request: &AuthorizeCommand, | ||
| deadline: Deadline, | ||
| ) -> Result<AuthorizeOutcome, AegisError>; |
There was a problem hiding this comment.
There are two different trait definitions for the authorization service in this document: AuthorizationService (defined in section 4.2 as an async trait returning AuthorizeResponse) and AuthorizeService (defined in section 7 as a synchronous trait returning AuthorizeOutcome). Please clarify their distinct roles or unify them into a single trait to prevent implementation drift.
| # Browser WASM | ||
| wasm-bindgen = "=0.2.126" | ||
| js-sys = "=0.3.103" | ||
| web-sys = "=0.3.103" |
There was a problem hiding this comment.
The constant MAX_BROWSER_BATCH_BYTES is used here to validate the input length, but it is missing from the 2. Constants and hard limits section. Please add it to the constants list in section 2 to ensure all hard limits are documented in one place.
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.
…9) (#1862) * feat(event): add failure-atomic slab/ring admission boundary (ADR-0009) 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). * docs: fix case-sensitive installation.md links in World-Class HLD/LLD 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. * ci(sast): scope the unsafe-usage gate — block repo-wide except lib/event 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).
Summary
A blueprint/documentation deliverable (not a runtime implementation) proposing a bare-metal, Thread-Per-Core architecture direction, explicitly benchmark-gated: <1ms p99 covers warm deterministic authorization compute only — protected actions still await durable approval/receipt commits, which remain a separate, out-of-scope path in this document.
ARCHITECTURE.md— Thread-Per-Core HLD, SPSC topology, NUMA/copy budgets, capacity equations, and the benchmark contract.docs/LLD.md— HCMT physical format, WAL/recovery, Gorilla/Roaring encodings, CoreReactor/SPSC skeletons, Aho/HNSW/PQ/ONNX/eBPF/UI designs, protobuf and FlatBuffer schemas, exact Cargo pins.MIGRATION_MATRIX.md— repository-backed audit, concurrency inventory, component mappings, preservation ledger, deletion gates, cutover sequence.README.md/CONTRIBUTING.md/ROADMAP.md— bare-metal product positioning (targets kept explicitly separate from measured SQLite performance), ADR/unsafe-Rust/lock-free/SIMD/zero-copy/benchmark/security requirements, a 36-week phased program.docs/architecture.md,AGENTS.md,CLAUDE.md, doc indexes, MkDocs nav, and validation tooling aligned to the new documents.Rebased onto current
main(includes the merged tool-broker extraction #1856 and node-sensor real-host proof #1857).bins/aegis-node-sensor/tests/real_host_integration.rshad been incidentally swept into the original commit this was cherry-picked from — it's deliberately left untouched here at its already-merged (5-test) version; this PR only touches architecture/documentation files.This completes the requested architectural blueprint — not the subsequent 36-week runtime implementation it describes.
Test plan
scripts/validate-docs.mjs): 0 errors, 0 warnings.rs/Cargo.tomlfiles are touched (docs-only change)🤖 Generated with Claude Code