BE-856: atlas: rewrite the crate documentation

[indietyp]

🌟 What is the purpose of this PR?

Rewrite the atlas crate's documentation so that it states contracts instead of narrating motives. The documentation across the crate describes component roles and design intent and leaves the contracts unstated. Few fallible functions carry an errors section or a panics section, and crate terms appear as bare words a reader has to guess at. After this change a reader in a diff hunk sees what an item is, what it returns on failure, when it panics, and a link on the first use of every crate term.

For review, the properties this stands on:

• Every sentence beside a piece of code is true of that code. A statement the code itself already makes leaves rather than getting reworded, so a comment that survives says something the code does not.
• Every function returning a result documents its errors and every panicking path its condition.
• cargo doc builds with every intra-doc link resolving.

Comment lines, plus twelve #[expect(rustdoc::broken_intra_doc_links)] attributes on links whose targets arrive in later changes. Each attribute leaves with the change that adds its target, and no code moves.

🔍 What does this change?

• Module and item documentation across src/, the five bench targets under benches/, and the IdSlice doc in libs/@local/hashql/core/src/id/slice.rs.
• A summary line states what the item is. Missing errors and panics sections get written. The first use of a crate term in a paragraph links to the item that defines it. An in-crate example on a crate-private item carries ignore and says why.
• Prose that explains a design's motive or a component's importance leaves. What stays is the contract, and the reason for a choice where the code does not show it.

❓ How to test this?

1. RUSTDOCFLAGS='-D warnings' cargo doc -p hash-graph-atlas --no-deps --all-features builds.
2. Open the rendered docs at lib.rs and follow one module down to its items. Every linked term resolves and every fallible function has an errors section.

Pre-Merge Checklist 🚀

🚢 Has this modified a publishable library?

This PR:

• does not modify any publishable blocks or libraries, or modifications do not need publishing

📜 Does this require a change to the docs?

The changes in this PR:

• are internal and do not require a docs change

🕸️ Does this require a change to the Turbo Graph?

The changes in this PR:

• do not affect the execution graph

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
hash	Ready	Preview	Sep 14, 2026 9:19pm UTC
petrinaut	Ready	Preview	Sep 14, 2026 9:19pm UTC
petrinaut-docs	Ready	Preview	Sep 14, 2026 9:19pm UTC

1 Skipped Deployment

Project	Deployment	Actions	Updated
hashdotdesign-tokens	Ignored	Preview	Sep 14, 2026 9:19pm UTC

[codecov]

Codecov Report

❌ Patch coverage is 61.53846% with 5 lines in your changes missing coverage. Please review.
✅ Project coverage is 71.13%. Comparing base (a845aa4) to head (bfa3985).

Files with missing lines	Patch %	Lines
libs/@local/graph/atlas/src/cli/dump.rs	0.00%	4 Missing ⚠️
libs/@local/graph/atlas/src/cli/shell.rs	0.00%	1 Missing ⚠️

Additional details and impacted files

@@                                      Coverage Diff                                       @@
##           bm/be-851-atlas-remove-the-single-generation-serving-layer    #9706      +/-   ##
==============================================================================================
+ Coverage                                                       65.71%   71.13%   +5.41%     
==============================================================================================
  Files                                                            1712     1308     -404     
  Lines                                                          182323   134980   -47343     
  Branches                                                         7529     5835    -1694     
==============================================================================================
- Hits                                                           119816    96017   -23799     
+ Misses                                                          61086    37854   -23232     
+ Partials                                                         1421     1109     -312     

Flag	Coverage Δ
apps.hash-ai-worker-ts	1.99% <ø> (ø)
apps.hash-api	?
apps.hash-graph	13.62% <ø> (ø)
local.hash-backend-utils	3.27% <ø> (ø)
local.hash-graph-sdk	10.02% <ø> (ø)
local.hash-isomorphic-utils	12.22% <ø> (ø)
rust.antsi	?
rust.harpc-codec	?
rust.harpc-net	?
rust.hash-graph-api	19.71% <ø> (ø)
rust.hash-graph-atlas	81.07% <61.53%> (+0.15%)	⬆️
rust.hash-graph-authentication	?
rust.hash-graph-authorization	?
rust.hash-graph-postgres-store	?
rust.hash-graph-types	?
rust.hash-graph-validation	?
rust.hash-middleware	?
rust.hashql-ast	89.63% <ø> (ø)
rust.hashql-compiletest	28.39% <ø> (ø)
rust.hashql-core	78.92% <ø> (ø)
rust.hashql-diagnostics	?
rust.hashql-eval	79.82% <ø> (ø)
rust.hashql-hir	89.09% <ø> (ø)
rust.hashql-mir	87.92% <ø> (ø)
rust.hashql-syntax-jexpr	94.04% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[codspeed-hq]

Merging this PR will not alter performance

⚠️ 6 benchmarks measured no execution time

Nothing ran under measurement, usually because the compiler removed the code under test. These results are not comparable, so they count as unchanged.

Preventing compiler optimizations

✅ 80 untouched benchmarks
⏩ 18 skipped benchmarks¹

Performance Changes

	Benchmark	BASE	HEAD	Efficiency
⚠️	as_constant	< 1 ns	< 1 ns	N/A
⚠️	constant_equal	< 1 ns	< 1 ns	N/A
⚠️	constant_not_equal	< 1 ns	< 1 ns	N/A
⚠️	access	< 1 ns	< 1 ns	N/A
⚠️	runtime_equal	< 1 ns	< 1 ns	N/A
⚠️	runtime_not_equal	< 1 ns	< 1 ns	N/A

---

_{Comparing bm/be-856-atlas-rewrite-the-crate-documentation (bfa3985) with bm/be-851-atlas-remove-the-single-generation-serving-layer (a845aa4)}

Footnotes

1. 18 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

[cursor]

PR Summary

Low Risk
Changes are documentation and comments only; no production logic or API surface changes appear in the diff.

Overview
This PR rewrites Atlas documentation (crate modules, five bench targets, and a small hashql-core IdSlice note) so items describe what they do, when they panic, and what errors mean, instead of design narrative.

Module and item docs gain Errors and Panics sections where fallible or panicking APIs lacked them. First-use intra-doc links tie crate terms to their definitions; in-crate examples on private types are marked ignore with a short reason. Bench crate docs are expanded to document env vars (ATLAS_*, MATH_BENCH_EVENT, MINER_BENCH_POINTS, etc.), measurement semantics, and calibration report ordering.

Prose in allocator, bitset (compressed/dense formats and zerocopy validation), bench, and cli (dump/fit/postgres/report flags and defaults) is tightened to contract language. A few inline comments and one corpus label in backfill_walk docs are corrected for accuracy. Twelve temporary #[expect(rustdoc::broken_intra_doc_links)] attributes are called out in the PR description as pending link targets in follow-ups.

^{Reviewed by Cursor Bugbot for commit bfa3985. Bugbot is set up for automated code reviews on this repo. Configure here.}

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.