Merge branch 'main' into 1207_short_circuit_on_participant_network_partition

Author: metalurgical

AGENTS.md

@@ -120,6 +120,11 @@ See `docs/engineering-standards.md` for the full rationale and additional testin
 ### Arithmetic in Tests
 Do not suggest using `checked_add`, `checked_mul`, `checked_sub`, `saturating_add`, or similar checked/saturating arithmetic in test code — this includes `#[cfg(test)]` modules, integration test crates, and e2e test crates. Raw arithmetic operators (`+`, `-`, `*`, `/`) are fine in tests — overflow will cause a panic, which is the desired behavior in tests.
 
+### Trait Naming
+Traits should model a single capability, and be named after the action, not as an agent noun derived from it: `ReadContractState`, not `ContractStateReader`. This follows std-idiomatic patterns (`From*`/`Into*`/`To*` conversions). This applies to new traits and opportunistic renames, existing traits may deviate from this principle.
+
+See `docs/engineering-standards.md` §Name capability traits after the action for the full rationale and a `Don't` / `Do` example.
+
 ### Code Comments
 Default to writing no comments. Add one only in case one of the following applies:
 - the *why* is non-obvious: an invariant, a constraint, a surprising behavior;
@@ -131,8 +136,12 @@ Avoid comments that are:
 - explaining common knowledge or terminology;
 - burdening the reader with non-relevant information;
 
+AI-generated code tends to arrive with obvious comments: restating what the next line does, labeling steps (`// setup`, `// send the request`), or narrating the edit that produced the code. Strip these before submitting. Keep a comment only if it says something the code cannot; if a reader can reconstruct it from the names and types on the same screen, delete it. This applies doubly in tests, where the `// Given` / `// When` / `// Then` structure already tells the story.
+
 Prefer concise comments, using correct terminology.
 
+In doc comments, reference other items with rustdoc intra-doc links (`` [`Foo`] ``), not plain `` `Foo` `` backticks. CI rejects broken links in everything rustdoc documents (test code is outside its view), and only linked references are checked at all; a plain backtick reference rots silently when the item is renamed. A backticked word that merely looks like an item (an algorithm name, a type from a crate we do not depend on, a `cfg(test)` item invisible to rustdoc) stays a plain code span.
+
 See `docs/engineering-standards.md` §Write helpful code comments for the full rationale and a `Don't` / `Do` example.
 
 ## Test Terminology

Cargo.lock

@@ -127,7 +127,7 @@ fn load_measurements(
     }
 }
 
-/// Parse a `TcbInfo`-format JSON into `ExpectedMeasurements`, replicating
+/// Parse a [`TcbInfo`]-format JSON into [`ExpectedMeasurements`], replicating
 /// the same logic as the `include_measurements!()` proc macro at runtime.
 fn parse_measurements_from_json(json: &str) -> anyhow::Result<ExpectedMeasurements> {
     let tcb_info: TcbInfo = serde_json::from_str(json).context("invalid TcbInfo JSON")?;

crates/attestation-cli/src/verify.rs

@@ -11,7 +11,7 @@ use serde::{Deserialize, Serialize, de::IgnoredAny};
 /// `deny_unknown_fields` makes verification fail closed: every key dstack can emit into
 /// `app-compose.json` must be modeled here, so a field added by a future dstack version is rejected
 /// until it is reviewed and modeled, rather than silently ignored. Fields are mirrored from
-/// dstack's `AppCompose` (`dstack-types/src/lib.rs`) plus the script keys read directly via `jq`
+/// dstack's [`AppCompose`] (`dstack-types/src/lib.rs`) plus the script keys read directly via `jq`
 /// during boot (`pre_launch_script`, `init_script`, `bash_script`). Fields without a security
 /// implication are modeled only to absorb their key; they are not validated.
 #[derive(Debug, Deserialize)]

crates/attestation/src/app_compose.rs

@@ -48,8 +48,8 @@ pub struct AcceptedDstackAttestation {
     /// The accepted measurement set this attestation matched.
     pub measurements: ExpectedMeasurements,
     /// Informational advisory IDs (e.g. `INTEL-DOC-10000` post-ESU) surfaced by
-    /// Intel's PCS alongside an `UpToDate` TCB status. They are not a security
-    /// failure — `UpToDate` is the sole security gate; these advisories convey
+    /// Intel's PCS alongside an [`UpToDate`](tee_verifier_interface::TcbStatus::UpToDate) TCB status. They are not a security
+    /// failure — [`UpToDate`](tee_verifier_interface::TcbStatus::UpToDate) is the sole security gate; these advisories convey
     /// platform lifecycle information.
     pub advisory_ids: Vec<String>,
 }
@@ -156,7 +156,7 @@ impl DstackAttestation {
         })
     }
 
-    /// Full local verification: runs `dcap_qvl::verify::verify` and then the
+    /// Full local verification: runs [`dcap_qvl::verify::verify`] and then the
     /// post-DCAP checks via [`Self::verify_with_report`].
     #[cfg(feature = "local-verify")]
     pub fn verify_locally(
@@ -169,7 +169,7 @@ impl DstackAttestation {
         self.verify_with_report(&report, expected_report_data, accepted_measurements)
     }
 
-    /// Runs only the DCAP step (`dcap_qvl::verify::verify`) and returns the
+    /// Runs only the DCAP step ([`dcap_qvl::verify::verify`]) and returns the
     /// resulting report as the `tee-verifier-interface` mirror — the same value
     /// the `tee-verifier` contract returns on-chain.
     #[cfg(feature = "local-verify")]
@@ -261,7 +261,7 @@ impl DstackAttestation {
     ///      check below.
     ///   2. `INTEL-DOC-NNNNN`: informational lifecycle markers (e.g. `INTEL-DOC-10000`
     ///      after a product's Extended Servicing Updates date). These may appear with
-    ///      `UpToDate` and do not indicate a vulnerability; they are returned so the
+    ///      [`UpToDate`](tee_verifier_interface::TcbStatus::UpToDate) and do not indicate a vulnerability; they are returned so the
     ///      caller can log/expose them.
     fn verify_tcb_status(report: &VerifiedReport) -> Result<Vec<String>, VerificationError> {
         (report.status == EXPECTED_QUOTE_STATUS)

crates/attestation/src/attestation.rs

@@ -1,6 +1,6 @@
 //! Quote collateral (Intel certificates + TCB info) used to verify a quote.
 //!
-//! `Collateral` is re-exported from `tee-verifier-interface`, not redefined,
+//! [`Collateral`] is re-exported from `tee-verifier-interface`, not redefined,
 //! so it has a single canonical definition.
 //!
 //! The `test-utils` JSON parser below lives here, not in the wire crate:

crates/attestation/src/collateral.rs

@@ -229,7 +229,7 @@ mod tests {
     use rstest::rstest;
     use serde_json;
 
-    /// `TcbInfo` holds both `HexBytes<48>` and `HexBytes<32>`; schema
+    /// [`TcbInfo`] holds both `HexBytes<48>` and `HexBytes<32>`; schema
     /// generation panics if their declarations collide.
     #[cfg(feature = "borsh-schema")]
     #[test]

crates/attestation/src/tcb_info.rs

@@ -37,8 +37,8 @@ impl ReadContractState for RpcContractStateReader {
 #[error("contract state view call failed: {0}")]
 pub struct RpcError(String);
 
-/// `reqwest` writes the request url, which is where an api key lives, into both the `Display` and
-/// the `Debug` of its errors, so its own text is dropped in favour of the causes below it, which do
+/// `reqwest` writes the request url, which is where an api key lives, into both the [`Display`](std::fmt::Display) and
+/// the [`Debug`] of its errors, so its own text is dropped in favour of the causes below it, which do
 /// not know the url. Every other variant carries text `near_kit` authored itself.
 fn describe(err: &NearKitError) -> String {
     match err {

crates/backup-cli/src/adapters/contract_state_rpc.rs

@@ -18,7 +18,7 @@ pub fn running_state_with_epoch(epoch_id: u64) -> ProtocolContractState {
     ProtocolContractState::Running(running)
 }
 
-/// What contract initialization leaves behind: `Running`, but without any key yet.
+/// What contract initialization leaves behind: [`Running`], but without any key yet.
 pub fn running_state_without_domains() -> ProtocolContractState {
     let mut running = running_contract_state();
     running.keyset.epoch_id = EpochId::new(0);

crates/backup-cli/src/test_utils.rs

@@ -8,13 +8,14 @@ use crate::event_subscriber::block_events::BlockContext;
 use crate::event_subscriber::metrics::{MPC_BLOCKS_INDEXED, MPC_FINALIZED_BLOCKS_INDEXED};
 use near_contract_transport::BlockHeight;
 
+#[expect(rustdoc::private_intra_doc_links)]
 /// Tracks the topology of the recent blocks, using the blocks given by the indexer.
 ///
 /// This class provides two important functionalities:
 ///  - Converts a stream of optimistic blocks from the indexer into a stream of finalized
 ///    blocks.
-///  - For each block added via `add_block`, it returns a `BlockStatusHandle` that can be
-///    used to observe that block's current `BlockStatus` (non-canonical, canonical or final).
+///  - For each block added via `add_block`, it returns a [`BlockStatusHandle`] that can be
+///    used to observe that block's current [`BlockStatus`] (non-canonical, canonical or final).
 ///
 /// This class provides the following invariants (provided the requirements listed below are met):
 ///  - A block that is final will never be reverted to non-final;
@@ -51,10 +52,10 @@ use near_contract_transport::BlockHeight;
 /// Despite the assumptions we make on the indexer's behavior, this class guarantees not to panic
 /// even if the indexer violates these assumptions in arbitrary ways.
 ///
-/// Note that the `RecentBlocksTracker` is removing blocks aggressively. A block is removed if one
+/// Note that the [`RecentBlocksTracker`] is removing blocks aggressively. A block is removed if one
 /// of the following conditions is met:
 ///  - The block sits on a dead fork and can't ever be finalized;
-///  - The block is outside of the recency window `RecentBlocksTracker::window_size`
+///  - The block is outside of the recency window [`RecentBlocksTracker::window_size`]
 ///
 /// Cleanup takes place after every `add_block` in two methods:
 ///  - `maybe_update_final_head` owns **dead-fork cleanup**. When a new final block is established,
@@ -120,10 +121,11 @@ pub struct RecentBlocksTracker {
 pub enum BlockStatus {
     /// The block is optimistically included in the chain, but it is not on the canonical chain.
     OptimisticButNotCanonical = 0,
+    #[expect(rustdoc::private_intra_doc_links)]
     /// The block is optimistically included in the chain, and it is on the canonical chain,
     /// but it is not yet part of the final chain.
     /// Note that if two chains tie for canonical height, the first one seen is considered the
-    /// canonical chain (c.f. `RecentBlocksTracker::update_canonical_head`).
+    /// canonical chain (c.f. [`RecentBlocksTracker::update_canonical_head`]).
     OptimisticAndCanonical = 1,
     /// The block is finalized by the blockchain.
     /// It is an ancestor (including self) of the latest final block.
@@ -208,7 +210,7 @@ pub struct AddBlockResult {
 struct BlockNode {
     hash: CryptoHash,
     height: BlockHeight,
-    /// Indicates the finality status of this block. Held as `Arc`.
+    /// Indicates the finality status of this block. Held as [`Arc`].
     /// A [`BlockStatusHandle`] is handed out via [`AddBlockResult::block_status`] to consumers,
     /// allowing them to observe status changes and detect pruning.
     status: Arc<AtomicBlockStatus>,
@@ -369,7 +371,7 @@ impl RecentBlocksTracker {
 
     /// Advance the final head, mark its ancestors as final, and drop every
     /// subtree that BFT-safety guarantees can no longer be on the final chain.
-    /// See `RecentBlocksTracker` for the picture of which subtrees this catches.
+    /// See [`RecentBlocksTracker`] for the picture of which subtrees this catches.
     ///
     /// Returns the newly finalized blocks in ascending height order.
     fn maybe_update_final_head(&mut self, potential_final_head: CryptoHash) -> Vec<Arc<BlockNode>> {
@@ -511,7 +513,7 @@ impl RecentBlocksTracker {
 
     /// Recency-window prune. Drops every node below `min_height_to_keep` and
     /// promotes the first in-window descendant on each branch to a new root.
-    /// See `RecentBlocksTracker` for the picture; dead-fork cleanup happens in
+    /// See [`RecentBlocksTracker`] for the picture; dead-fork cleanup happens in
     /// `maybe_update_final_head`, not here.
     fn prune_old_blocks(&mut self) {
         let Some(min_height_to_keep) = self.minimum_height_to_keep() else {