Repository navigation
docs: architecture map with a numbered diagram - #1
Conversation
Add docs/architecture.md: the components, the trust and data boundaries, the path one request or run takes through the system as numbered steps that match the arrows on docs/architecture.svg, and a table of what is proven and where the evidence lives. The README gains an Architecture section that shows the diagram and links the page. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Expand the canvas to 1200 x 952 and resize and reposition nodes and regions for text padding, clear title strips, and consistent nesting margins. Separate collector routes, place badges on clear edge segments, and route all arrows orthogonally with a straight collector-to-trace connection. Wrap four edge labels without cutting words or changing facts. Preserve all 13 nodes, 14 edges, 12 numbered steps, and three notes; no Markdown changes were needed. Retain the supplied renderer's geometry metadata. Validate through four render/gate/image rounds, a final GATE PASS, content and style preservation checks, and exact edge intersection checks. Co-Authored-By: Codex astra <noreply@openai.com>
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 5143166e68
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| 8. **VM ↔ heap.** At every instruction boundary the VM asserts the live stack against the stack map, gives the stress scheduler a chance to collect, then dispatches. All allocation and all reference stores go through `Heap` funnels (`store_pair_field`, `store_ref_array_element`, `store_record_field`, `store_map_entry`, `store_ephemeron_value`). | ||
| 9. **Heap → write barrier.** The heap is one slot vector of objects; an `ObjectId` is a slot index plus a slot-reuse generation in its high bits, so a stale id traps instead of aliasing. `Young` and `Old` are per-object tags on that one vector, not separate memory regions. A store of a young reference into an old object appends the owner to an ordered remembered set. | ||
| 10. **VM → collector (roots).** Roots are the frames and any pending exception (`VM::trace_roots`), the `Handle` slots, and extra roots registered during allocation. | ||
| 11. **Write barrier → collector.** For a minor collection the young targets of the remembered set are roots too, so the old generation is never scanned. |
There was a problem hiding this comment.
This overstates the generational behavior: every minor collection calls enqueue_young_references_from_remembered_set, which scans the reference fields of remembered old owners, and the rewrite phase subsequently visits retained old objects as well. What the collector avoids is tracing the entire old generation for liveness, not scanning old objects altogether; the current wording gives readers an incorrect performance and implementation model.
Useful? React with 👍 / 👎.
| | Deterministic stress: fifteen named schedules (`no_stress` to `combined_mark_compact`); 24 corpora, 115 mutation forms, 2,806 rejection checks with pinned hashes | [`gc-stress-mode.md`](./gc-stress-mode.md), `README.md` | | ||
| | Trace conservation on four measured bundles (90 snapshots, 86 replays, 21,369 events) | `showcase/`, `SCHEMA.md` | | ||
| | Performance baseline on a Debug, assertions-enabled Apple Clang host, informational only | [`perf-baseline.md`](./perf-baseline.md) | | ||
| | Fuzzing: `verify_fuzz` covers the front end and verifier; CI replays the committed corpus as a gate and runs a 90 s discovery pass as advisory, on Ubuntu and macOS with Clang ASan and UBSan | `.github/workflows/ci.yml`, `fuzz/` | |
There was a problem hiding this comment.
The referenced workflow does not run these fuzzing steps on both platforms: .github/workflows/ci.yml defines the corpus replay and 90-second discovery session in a fuzz job whose runs-on is only ubuntu-latest; macOS appears only in the ordinary build-and-test matrix, without the libFuzzer target or sanitizers. As written, this evidence table incorrectly claims macOS coverage for the Clang ASan/UBSan fuzz gate.
Useful? React with 👍 / 👎.
docs: architecture map with a numbered diagram
Adds a reference-architecture drawing and a walkthrough for this repository.
docs/architecture.svg: boxed regions, component icons and numbered arrows, rendered from a JSON spec and checked by a geometry gate (text fits its box with slack for wider fonts; nothing touches or crosses anything else).docs/architecture.md: the numbered path arrow by arrow, the component table, the trust and data boundaries, what is proven and where the evidence lives, and the identifiers the code relies on. Every claim comes from this repository's own README, ADRs and code, and the page says what is not claimed.Two commits: the map, then the geometry pass.