docs: add validator agent guidance#1322
Conversation
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughThe PR establishes a comprehensive AI-agent guidance system for the repository. The Suggested reviewers
✨ 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 |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@AGENTS.md`:
- Around line 19-25: Remove the forward-references to files that don't exist in
this PR cohort to maintain sync between AGENTS.md and the agents/ directory. In
AGENTS.md (lines 19-25), delete item 6 (the reference to
agents/05_testing-and-validation.md) and item 7 (the reference to
agents/crates/magicblock-chainlink.md), then renumber the remaining items
accordingly. In agents/04_crate-map.md (line 37), remove the note that
references the non-existent agents/crates/magicblock-chainlink.md file. These
forward-references will be re-added when the corresponding files are contributed
in later PR cohorts, ensuring the documentation remains consistent with actual
files in the repository.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: e72d39cb-87e8-4804-a8d6-704a82e40cd3
📒 Files selected for processing (9)
.gitignoreAGENTS.mdagents/00_overview.mdagents/01_validator-goals.mdagents/02_specification.mdagents/03_architecture.mdagents/04_crate-map.mdagents/05_testing-and-validation.mdagents/crates/magicblock-chainlink.md
💤 Files with no reviewable changes (1)
- .gitignore
There was a problem hiding this comment.
♻️ Duplicate comments (1)
AGENTS.md (1)
19-27:⚠️ Potential issue | 🟠 Major | ⚡ Quick winForward-references to non-existent guidance files violate learned synchronization requirements (unresolved cross-doc issue).
Two files reference
agents/05_testing-and-validation.md,agents/06_agent-memory-and-docs.md, andagents/crates/magicblock-chainlink.md, which are not in this PR cohort and therefore do not exist yet. This issue was previously flagged (commit fingerprint943d7a3) and remains unresolved.The learned guidance enforces: "If anything is added to, removed from, renamed, or reorganized inside
./agents/, updateAGENTS.md... so the entrypoint remains accurate." This applies bidirectionally—no file should list documents that do not yet exist in the repository.Root cause: This cohort includes only
agents/00-04.mdand the rootAGENTS.md. Files 05, 06, and theagents/crates/subdirectory are in later cohorts (as documented in the PR stack). Forward-references now create broken links and contradict the synchronization rule.Impact: Readers see references to missing files → broken navigation, confusion about what to read, degraded onboarding UX.
AGENTS.md#L19-L27: Remove the entire numbered items 6, 7, and 8. Keep only items 1–5 (agents/00 through agents/04), then renumber them to 1–5 to stay sequential. Add items 6+ when the corresponding files are contributed in later cohorts.agents/00_overview.md#L36-L37: Remove the references toagents/05_testing-and-validation.mdandagents/06_agent-memory-and-docs.mdfrom the "Which agent doc to read" section. Shorten the list to items that exist in this cohort (agents/00–04). Add back those references when the files exist.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@AGENTS.md` around lines 19 - 27, This PR cohort includes only agents/00-04 and AGENTS.md, but the documentation currently contains forward-references to agents/05_testing-and-validation.md, agents/06_agent-memory-and-docs.md, and agents/crates/magicblock-chainlink.md which do not exist yet, creating broken links. At AGENTS.md lines 19-27, remove the entire numbered items 6, 7, and 8 (the lines referencing the non-existent files), keep only items 1-5 (agents/00 through agents/04), and renumber them sequentially as 1-5. At agents/00_overview.md lines 36-37, remove all references to agents/05_testing-and-validation.md and agents/06_agent-memory-and-docs.md from the "Which agent doc to read" section, shortening the guidance list to only the files that exist in this cohort (agents/00-04). These files should be added back to both locations when the corresponding files are contributed in later cohorts.Source: Learnings
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Duplicate comments:
In `@AGENTS.md`:
- Around line 19-27: This PR cohort includes only agents/00-04 and AGENTS.md,
but the documentation currently contains forward-references to
agents/05_testing-and-validation.md, agents/06_agent-memory-and-docs.md, and
agents/crates/magicblock-chainlink.md which do not exist yet, creating broken
links. At AGENTS.md lines 19-27, remove the entire numbered items 6, 7, and 8
(the lines referencing the non-existent files), keep only items 1-5 (agents/00
through agents/04), and renumber them sequentially as 1-5. At
agents/00_overview.md lines 36-37, remove all references to
agents/05_testing-and-validation.md and agents/06_agent-memory-and-docs.md from
the "Which agent doc to read" section, shortening the guidance list to only the
files that exist in this cohort (agents/00-04). These files should be added back
to both locations when the corresponding files are contributed in later cohorts.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: bcebdd13-7ac4-4249-860c-b1f451cc316e
📒 Files selected for processing (10)
AGENTS.mdagents/00_overview.mdagents/01_validator-goals.mdagents/02_specification.mdagents/03_architecture.mdagents/04_crate-map.mdagents/05_testing-and-validation.mdagents/06_agent-memory-and-docs.mdagents/crates/magicblock-chainlink.mdagents/crates/magicblock-metrics.md
There was a problem hiding this comment.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
agents/04_crate-map.md (1)
33-33:⚠️ Potential issue | 🔴 Critical | ⚡ Quick winRemove
solana-storage-protofrom the workspace crate map; it is an external dependency, not a workspace crate.Line 3 explicitly states the map "focus on workspace crates" and "external Solana/SVM dependencies are omitted."
solana-storage-protodoes not appear in the workspacememberslist inCargo.toml; it is a generated/external dependency for protobuf support. Including it as a workspace crate violates the stated scope and could mislead agents about the actual workspace structure.Delete the entire row for
solana-storage-proto(line 33).🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@agents/04_crate-map.md` at line 33, The crate map in agents/04_crate-map.md incorrectly includes solana-storage-proto as a workspace crate when it is actually an external dependency. According to the document's stated purpose (line 3), the map should only focus on workspace crates and omit external dependencies. Since solana-storage-proto does not appear in the workspace members list in Cargo.toml, remove the entire table row containing the solana-storage-proto entry from the crate map table to align with the documented scope and accurately reflect the actual workspace structure.
♻️ Duplicate comments (1)
AGENTS.md (1)
24-26:⚠️ Potential issue | 🟠 Major | ⚡ Quick win** Forward-references to non-existent files still present—prior review flagged this.**
Lines 24 and 26 reference files that are not part of this PR layer (and per the PR stack, not yet contributed):
- Line 24:
agents/05_testing-and-validation.md(layer 5)- Line 26:
agents/crates/magicblock-chainlink.md,agents/crates/magicblock-api.md,agents/crates/magicblock-accounts.md,agents/crates/magicblock-aml.md,agents/crates/magicblock-aperture.md,agents/crates/magicblock-config.md, andagents/crates/magicblock-metrics.md(layers 7–8)Per the coding guideline from learnings: "If anything is added to, removed from, renamed, or reorganized inside
./agents/, update theAGENTS.mdfile in the same change so the entrypoint remains accurate." AGENTS.md should only list files that exist at merge time. A prior review explicitly requested removal of these forward-references with the note they will be added when those files are contributed in later layers.📍 Proposed fix: Remove forward-references to files not in this layer
- 6. `agents/05_testing-and-validation.md` — required validation workflow, rs-check guidance, and integration test commands. - 7. `agents/06_agent-memory-and-docs.md` — required rules for capturing newly discovered durable behavior, workflows, pitfalls, and documentation corrections. - 8. Relevant crate-specific guide under `agents/crates/` when one exists, such as `agents/crates/magicblock-account-cloner.md` for `magicblock-account-cloner`, `agents/crates/magicblock-accounts.md` for `magicblock-accounts`, `agents/crates/magicblock-aml.md` for `magicblock-aml`, `agents/crates/magicblock-aperture.md` for `magicblock-aperture`, `agents/crates/magicblock-api.md` for `magicblock-api`, `agents/crates/magicblock-chainlink.md` for `magicblock-chainlink`, `agents/crates/magicblock-config.md` for `magicblock-config`, or `agents/crates/magicblock-metrics.md` for `magicblock-metrics`. + 6. `agents/06_agent-memory-and-docs.md` — required rules for capturing newly discovered durable behavior, workflows, pitfalls, and documentation corrections.Then continue with line 28 (renumbered):
+ 7. Relevant crate-specific guides under `agents/crates/` when one exists (added in later cohorts).Or simply remove both items entirely and note in the prose below that additional guidance is available as it is added.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@AGENTS.md` around lines 24 - 26, Remove the list items in AGENTS.md that reference files not yet contributed in this PR layer. Specifically, delete the item referencing `agents/05_testing-and-validation.md` (item 6 in the numbered list) and the item referencing the crate-specific guides under `agents/crates/` (item 8), as these files do not exist at merge time. Per the guideline that AGENTS.md should only list files that exist at merge time and prior review feedback, keep only the reference to files that already exist in this layer, such as `agents/06_agent-memory-and-docs.md`.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Outside diff comments:
In `@agents/04_crate-map.md`:
- Line 33: The crate map in agents/04_crate-map.md incorrectly includes
solana-storage-proto as a workspace crate when it is actually an external
dependency. According to the document's stated purpose (line 3), the map should
only focus on workspace crates and omit external dependencies. Since
solana-storage-proto does not appear in the workspace members list in
Cargo.toml, remove the entire table row containing the solana-storage-proto
entry from the crate map table to align with the documented scope and accurately
reflect the actual workspace structure.
---
Duplicate comments:
In `@AGENTS.md`:
- Around line 24-26: Remove the list items in AGENTS.md that reference files not
yet contributed in this PR layer. Specifically, delete the item referencing
`agents/05_testing-and-validation.md` (item 6 in the numbered list) and the item
referencing the crate-specific guides under `agents/crates/` (item 8), as these
files do not exist at merge time. Per the guideline that AGENTS.md should only
list files that exist at merge time and prior review feedback, keep only the
reference to files that already exist in this layer, such as
`agents/06_agent-memory-and-docs.md`.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: 780b430f-8cca-40b7-8a11-ad5c7d8a8505
📒 Files selected for processing (8)
AGENTS.mdagents/04_crate-map.mdagents/crates/magicblock-account-cloner.mdagents/crates/magicblock-accounts.mdagents/crates/magicblock-aml.mdagents/crates/magicblock-aperture.mdagents/crates/magicblock-api.mdagents/crates/magicblock-config.md
There was a problem hiding this comment.
Actionable comments posted: 4
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
AGENTS.md (1)
19-26:⚠️ Potential issue | 🟠 Major | ⚡ Quick winShared root cause: Forward-references to crate-specific guides that don't exist in this PR cohort.
Both
AGENTS.mdandagents/04_crate-map.mdreference guidance files and crate-specific documentation that are not included in this cohort and will not exist at merge time. This violates the coding guideline thatAGENTS.mdandagents/structure must remain synchronized.
AGENTS.md#L19-L26: Remove items 6–8 from the "Start here" checklist (agents/05_testing-and-validation.md, agents/06_agent-memory-and-docs.md, and all crate-specific guides). These will be re-added when those cohorts are merged.agents/04_crate-map.md#L9-L87: Remove or soften all imperative "See agents/crates/X.md before changing" directives. Replace with plain descriptions or conditional language like "See agents/crates/X.md if it exists." These directives will be restored when the crate guides are contributed.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@AGENTS.md` around lines 19 - 26, Remove forward-references to documentation files that do not exist in this PR cohort. In AGENTS.md at lines 19-26, delete items 6, 7, and 8 from the "Start here" checklist (the references to agents/05_testing-and-validation.md, agents/06_agent-memory-and-docs.md, and all crate-specific guides under agents/crates/). In agents/04_crate-map.md at lines 9-87, remove or soften all imperative directives that reference specific crate guides (such as "See agents/crates/magicblock-account-cloner.md before changing"), replacing them with conditional language like "See agents/crates/X.md if it exists" or simple descriptive text. These items will be re-added when their respective documentation cohorts are merged.Source: Learnings
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@agents/crates/magicblock-table-mania.md`:
- Around line 259-267: Vary the sentence structure in the Related docs sections
across all four affected files to improve readability. In
agents/crates/magicblock-table-mania.md (lines 259-267), reword the six
consecutive bullets starting with `- \`<path>\` for...` to use varied openings
such as "See", "Inspect", "Consult", or "Refer to". In
agents/crates/magicblock-task-scheduler.md (lines 288-301), similarly reword the
eight bullets to mix sentence structures like "See ... for...", "Consult ...
when...", "Inspect ... to understand...". In
agents/crates/magicblock-validator.md (lines 284-295), reword the eleven bullets
with varied openers and consider grouping related items (e.g., combining RPC/API
references under one introductory heading). In
agents/crates/magicblock-version.md (lines 246-254), apply the same rewording
strategy to the five bullets. The goal is to eliminate the monotonous repetition
while maintaining clarity about what each reference provides.
In `@agents/crates/storage-proto.md`:
- Around line 72-74: Reduce the repetitive sentence structure in the module
description (lines 72-74) of the storage-proto.md documentation. Replace the
three parallel sentences that each start with `convert::{module_name}` with
either a cleaner bulleted list format (starting with an introductory phrase like
"The generated modules are:") or consolidate into a single narrative sentence
that lists all three modules (convert::generated, convert::tx_by_addr, and
convert::entries) with their corresponding proto sources without repeating the
`convert::` prefix at the start of each line.
In `@agents/crates/test-kit.md`:
- Around line 315-318: Reduce the repetitive sentence structure in the Related
docs section that contains four consecutive bullet points beginning with " -
`agents/". Restructure the four documentation reference lines to vary how they
are introduced, either by changing the sentence structure of each bullet point
to avoid starting each with "`agents/" or by grouping related references under a
category header with a more concise list format. The revision should maintain
all the documentation references while improving readability and reducing the
repetitive pattern.
- Line 273: The git diff validation command at line 273 in
agents/crates/test-kit.md includes a suspicious path
`prompts/ai/agents/03_batch-crates-plan.md` that appears to be an internal
artifact rather than a real repository file. Remove this path from the
validation command and keep only the legitimate repository files
`agents/04_crate-map.md` and `AGENTS.md` to ensure the documentation-only
validation correctly checks only actual repository files.
---
Outside diff comments:
In `@AGENTS.md`:
- Around line 19-26: Remove forward-references to documentation files that do
not exist in this PR cohort. In AGENTS.md at lines 19-26, delete items 6, 7, and
8 from the "Start here" checklist (the references to
agents/05_testing-and-validation.md, agents/06_agent-memory-and-docs.md, and all
crate-specific guides under agents/crates/). In agents/04_crate-map.md at lines
9-87, remove or soften all imperative directives that reference specific crate
guides (such as "See agents/crates/magicblock-account-cloner.md before
changing"), replacing them with conditional language like "See
agents/crates/X.md if it exists" or simple descriptive text. These items will be
re-added when their respective documentation cohorts are merged.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: 54a15f57-3ca8-479a-80b8-7d79b12b26c1
📒 Files selected for processing (13)
AGENTS.mdagents/04_crate-map.mdagents/crates/magicblock-core.mdagents/crates/magicblock-magic-program-api.mdagents/crates/magicblock-rpc-client.mdagents/crates/magicblock-services.mdagents/crates/magicblock-table-mania.mdagents/crates/magicblock-task-scheduler.mdagents/crates/magicblock-validator-admin.mdagents/crates/magicblock-validator.mdagents/crates/magicblock-version.mdagents/crates/storage-proto.mdagents/crates/test-kit.md
| ## Related docs | ||
|
|
||
| - `agents/02_specification.md` for base-layer settlement, committor, and address lookup table context. | ||
| - `agents/03_architecture.md` for the base-layer settlement crate boundary. | ||
| - `agents/04_crate-map.md` for crate ownership and consumers. | ||
| - `agents/05_testing-and-validation.md` for workspace and integration validation expectations. | ||
| - `agents/crates/magicblock-rpc-client.md` for the RPC wrapper used by all table transactions and remote reads. | ||
| - `test-integration/test-table-mania/` for integration coverage of table lifecycle and reservation behavior. | ||
| - `magicblock-committor-service/src/transaction_preparator/delivery_preparator.rs` for the main runtime call site. |
There was a problem hiding this comment.
🧹 Nitpick | 🔵 Trivial | 💤 Low value
Vary sentence structure in Related docs sections across all new crate guides.
The "Related docs" sections in these new agent guidance documents use repetitive bullet-point patterns, reducing readability. All four files start each bullet with the same structure (- \` for...or- `` — `), creating a monotonous list.
agents/crates/magicblock-table-mania.md#L259-L267: Six consecutive bullets all starting with- \` for.... Reword some to use varied openings likeSee,Inspect,Consult, orRefer to`.agents/crates/magicblock-task-scheduler.md#L288-L301: Eight consecutive bullets with same- \` for...pattern. Consider mixingSee ... for...,Consult ... when...,Inspect ... to understand...`.agents/crates/magicblock-validator.md#L284-L295: Eleven bullets with the same pattern. Vary sentence openers and consider grouping related items (e.g., combine RPC/API references under one intro).agents/crates/magicblock-version.md#L246-L254: Five bullets with the same pattern. Apply the same rewording strategy.
🧰 Tools
🪛 LanguageTool
[style] ~263-~263: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...te boundary. - agents/04_crate-map.md for crate ownership and consumers. - `agent...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~264-~264: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...- agents/05_testing-and-validation.md for workspace and integration validation ex...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~265-~265: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...agents/crates/magicblock-rpc-client.md` for the RPC wrapper used by all table trans...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~266-~266: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ... - test-integration/test-table-mania/ for integration coverage of table lifecycle...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~267-~267: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...tion_preparator/delivery_preparator.rs` for the main runtime call site.
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
📍 Affects 4 files
agents/crates/magicblock-table-mania.md#L259-L267(this comment)agents/crates/magicblock-task-scheduler.md#L288-L301agents/crates/magicblock-validator.md#L284-L295agents/crates/magicblock-version.md#L246-L254
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@agents/crates/magicblock-table-mania.md` around lines 259 - 267, Vary the
sentence structure in the Related docs sections across all four affected files
to improve readability. In agents/crates/magicblock-table-mania.md (lines
259-267), reword the six consecutive bullets starting with `- \`<path>\` for...`
to use varied openings such as "See", "Inspect", "Consult", or "Refer to". In
agents/crates/magicblock-task-scheduler.md (lines 288-301), similarly reword the
eight bullets to mix sentence structures like "See ... for...", "Consult ...
when...", "Inspect ... to understand...". In
agents/crates/magicblock-validator.md (lines 284-295), reword the eleven bullets
with varied openers and consider grouping related items (e.g., combining RPC/API
references under one introductory heading). In
agents/crates/magicblock-version.md (lines 246-254), apply the same rewording
strategy to the five bullets. The goal is to eliminate the monotonous repetition
while maintaining clarity about what each reference provides.
Source: Linters/SAST tools
| - `convert::generated` includes `OUT_DIR/solana.storage.confirmed_block.rs` generated from `confirmed_block.proto`. | ||
| - `convert::tx_by_addr` includes `OUT_DIR/solana.storage.transaction_by_addr.rs` generated from `transaction_by_addr.proto`. | ||
| - `convert::entries` includes `OUT_DIR/solana.storage.entries.rs` generated from `entries.proto`. |
There was a problem hiding this comment.
🧹 Nitpick | 🔵 Trivial | 💤 Low value
Reduce sentence-initial repetition in the public API list (lines 72–74).
The three-line description of generated modules uses parallel structure with convert::{generated, tx_by_addr, entries} starting each sentence, which is valid for a list but reads repetitively. Consider consolidating or using bullets:
The generated modules are:
- `convert::generated` includes ...
- `convert::tx_by_addr` includes ...
- `convert::entries` includes ...
Alternatively, restructure as: "The crate exposes three modules: generated (from confirmed_block.proto), tx_by_addr (from transaction_by_addr.proto), and entries (from entries.proto), each with their generated protobuf types."
🧰 Tools
🪛 LanguageTool
[style] ~74-~74: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...on_by_addr.proto. - convert::entriesincludesOUT_DIR/solana.storage.entries.rs` gen...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@agents/crates/storage-proto.md` around lines 72 - 74, Reduce the repetitive
sentence structure in the module description (lines 72-74) of the
storage-proto.md documentation. Replace the three parallel sentences that each
start with `convert::{module_name}` with either a cleaner bulleted list format
(starting with an introductory phrase like "The generated modules are:") or
consolidate into a single narrative sentence that lists all three modules
(convert::generated, convert::tx_by_addr, and convert::entries) with their
corresponding proto sources without repeating the `convert::` prefix at the
start of each line.
| For documentation-only changes: | ||
|
|
||
| ```bash | ||
| git diff --check -- agents/crates/test-kit.md agents/04_crate-map.md AGENTS.md prompts/ai/agents/03_batch-crates-plan.md |
There was a problem hiding this comment.
Remove or correct the suspicious path in the documentation-only validation command (line 273).
The validation command references prompts/ai/agents/03_batch-crates-plan.md, which appears to be an internal prompt or tooling artifact rather than a repository file. The validation command should only check files in the repository:
- git diff --check -- agents/crates/test-kit.md agents/04_crate-map.md AGENTS.md prompts/ai/agents/03_batch-crates-plan.md
+ git diff --check -- agents/crates/test-kit.md agents/04_crate-map.md AGENTS.mdVerify that agents/04_crate-map.md and AGENTS.md are the correct related files to validate for documentation-only changes in this crate guide.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@agents/crates/test-kit.md` at line 273, The git diff validation command at
line 273 in agents/crates/test-kit.md includes a suspicious path
`prompts/ai/agents/03_batch-crates-plan.md` that appears to be an internal
artifact rather than a real repository file. Remove this path from the
validation command and keep only the legitimate repository files
`agents/04_crate-map.md` and `AGENTS.md` to ensure the documentation-only
validation correctly checks only actual repository files.
| - `agents/03_architecture.md` for execution and local persistence layer boundaries. | ||
| - `agents/04_crate-map.md` for crate ownership and consumers. | ||
| - `agents/05_testing-and-validation.md` for repository validation expectations. | ||
| - `agents/crates/magicblock-core.md` for channel and shared-type boundaries used by the harness. |
There was a problem hiding this comment.
🧹 Nitpick | 🔵 Trivial | 💤 Low value
Reduce sentence-initial repetition in the Related docs section (lines 315–318).
Four consecutive lines begin with " - `agents/", which creates repetitive listing. Consider consolidating or restructuring for variety:
- `agents/02_specification.md` covers delegated/ephemeral access rules and scheduler behavior commonly exercised by tests.
- For execution and local persistence layer boundaries, see `agents/03_architecture.md`.
- Crate ownership and consumer information is in `agents/04_crate-map.md`.
- Repository validation expectations appear in `agents/05_testing-and-validation.md`.
Alternatively, group by topic:
Architecture and validation:
- `agents/02_specification.md` for delegated/ephemeral rules
- `agents/03_architecture.md` for layer boundaries
- `agents/04_crate-map.md` for crate ownership
- `agents/05_testing-and-validation.md` for validation workflows
🧰 Tools
🪛 LanguageTool
[style] ~315-~315: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...exercise. - agents/03_architecture.md for execution and local persistence layer b...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~316-~316: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ... boundaries. - agents/04_crate-map.md for crate ownership and consumers. - `agent...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~317-~317: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...- agents/05_testing-and-validation.md for repository validation expectations. - `...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~318-~318: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...s. - agents/crates/magicblock-core.md for channel and shared-type boundaries used...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@agents/crates/test-kit.md` around lines 315 - 318, Reduce the repetitive
sentence structure in the Related docs section that contains four consecutive
bullet points beginning with " - `agents/". Restructure the four documentation
reference lines to vary how they are introduced, either by changing the sentence
structure of each bullet point to avoid starting each with "`agents/" or by
grouping related references under a category header with a more concise list
format. The revision should maintain all the documentation references while
improving readability and reducing the repetitive pattern.
There was a problem hiding this comment.
Actionable comments posted: 2
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (4)
agents/crates/magicblock-rpc-client.md (1)
223-226:⚠️ Potential issue | 🟠 Major | ⚡ Quick winHonor or remove
_blockhash_valid_timeout.The helper advertises a separate blockhash-valid bound, but the doc says the timeout value is never consulted. That gives callers a false sense of protection on a settlement-critical path.
✏️ Suggested fix
- `wait_for_processed_status` currently accepts a `_blockhash_valid_timeout` parameter but does not actively wait for blockhash validity through that value. It relies on `SignatureConfirmer` timeout behavior plus cached blockhash metadata for better error text. + `wait_for_processed_status` should either honor `blockhash_valid_timeout` or remove it from the contract; a no-op timeout is misleading for callers.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@agents/crates/magicblock-rpc-client.md` around lines 223 - 226, The `wait_for_processed_status` function advertises a `_blockhash_valid_timeout` parameter but does not actually use it for enforcing blockhash validity checks, giving callers a false sense of protection on a critical settlement path. Either implement active waiting for blockhash validity using the timeout parameter value and update the relevant tests to verify this behavior, or remove the `_blockhash_valid_timeout` parameter entirely from the function signature and its documentation to accurately reflect the actual implementation behavior.agents/crates/magicblock-metrics.md (1)
121-126:⚠️ Potential issue | 🟠 Major | ⚡ Quick winSurface
/metricsencoding failures to the scrape caller.Returning an empty 200 body makes exporter bugs indistinguishable from a healthy empty registry, so Prometheus/alerts can miss a metrics outage.
✏️ Suggested wording
- If text encoding fails, it logs a warning and returns an empty metrics body rather than panicking. + If text encoding fails, it logs a warning and fails the scrape so exporter outages are visible to Prometheus and alerting.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@agents/crates/magicblock-metrics.md` around lines 121 - 126, The `/metrics` endpoint currently logs a warning and returns an empty 200 body when text encoding fails, which makes encoding failures indistinguishable from a healthy empty registry and prevents Prometheus from detecting metrics outages. Modify the error handling in the metrics endpoint to return an HTTP error status code (such as 500 Internal Server Error) when text encoding of the metrics registry fails, ensuring the failure is visible to the Prometheus scraper caller instead of silently returning an empty response body.agents/crates/magicblock-chainlink.md (1)
41-49:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winUse fully qualified repo-relative paths in the table.
The bare
src/...andtests/...entries are ambiguous from the repo root and inconsistent with the rest of the guide. That makes copy/paste navigation and grep-based lookup harder for future agents.✏️ Suggested fix
-| `src/chainlink/mod.rs` | Public Chainlink facade, replication-mode wrapper, transaction/account ensure entrypoints, removed-account eviction listener. | -| `src/chainlink/fetch_cloner/` | Main fetch/clone pipeline, delegation handling, subscription-update processing, ATA/eATA projection, pending operation deduplication. | -| `src/remote_account_provider/` | RPC/pubsub provider, subscription ownership, LRU capacity, websocket/gRPC clients, program-account resolution. | -| `src/submux/` | Multiplexes multiple pubsub clients, deduplicates/debounces updates, reconnects clients, fans updates into one stream. | -| `src/cloner/mod.rs` | `Cloner` trait implemented by `magicblock-account-cloner`; request types passed from Chainlink to the clone executor. | -| `src/accounts_bank.rs` | Test/mock-oriented `AccountsBank` helpers for this crate. | -| `src/testing/` | Test support behind `dev-context`. | -| `tests/` | Integration-style Chainlink tests for account ensure, delegation, redelegation, ordering, and race recovery. | +| `magicblock-chainlink/src/chainlink/mod.rs` | Public Chainlink facade, replication-mode wrapper, transaction/account ensure entrypoints, removed-account eviction listener. | +| `magicblock-chainlink/src/chainlink/fetch_cloner/` | Main fetch/clone pipeline, delegation handling, subscription-update processing, ATA/eATA projection, pending operation deduplication. | +| `magicblock-chainlink/src/remote_account_provider/` | RPC/pubsub provider, subscription ownership, LRU capacity, websocket/gRPC clients, program-account resolution. | +| `magicblock-chainlink/src/submux/` | Multiplexes multiple pubsub clients, deduplicates/debounces updates, reconnects clients, fans updates into one stream. | +| `magicblock-chainlink/src/cloner/mod.rs` | `Cloner` trait implemented by `magicblock-account-cloner`; request types passed from Chainlink to the clone executor. | +| `magicblock-chainlink/src/accounts_bank.rs` | Test/mock-oriented `AccountsBank` helpers for this crate. | +| `magicblock-chainlink/src/testing/` | Test support behind `dev-context`. | +| `magicblock-chainlink/tests/` | Integration-style Chainlink tests for account ensure, delegation, redelegation, ordering, and race recovery. |🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@agents/crates/magicblock-chainlink.md` around lines 41 - 49, The markdown table in magicblock-chainlink.md contains ambiguous bare path references like `src/chainlink/mod.rs` and `tests/`. Update all path entries in the table to use fully qualified repo-relative paths by prepending the appropriate path prefix (such as `magicblock-chainlink/` or the full path from the repo root) to each bare `src/...` and `tests/...` entry. This will make the paths unambiguous from the repo root and consistent with the rest of the documentation guide, enabling easier copy/paste navigation and grep-based lookup.agents/crates/magicblock-aperture.md (1)
90-90:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winClarify the WebSocket port rule.
listen.port() + 1cannot also describe the0case. As written, this reads like two different binding rules at once and makes the startup contract ambiguous.✏️ Suggested wording
- `ApertureConfig::listen` binds the HTTP listener. The WebSocket listener uses `listen.port() + 1`; if HTTP port is `0`, WebSocket also binds port `0` and the actual bound ports are available from `JsonRpcServer`. + `ApertureConfig::listen` binds the HTTP listener. When `listen.port()` is `0`, both listeners request OS-assigned ports; otherwise the WebSocket listener uses `listen.port() + 1`. The actual bound ports are available from `JsonRpcServer`.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@agents/crates/magicblock-aperture.md` at line 90, The documentation for ApertureConfig::listen contains contradictory statements about the WebSocket port binding rule. The current text states both that the WebSocket listener uses listen.port() + 1 AND that if HTTP port is 0, WebSocket also binds port 0, which are mutually exclusive. Rewrite the description at line 90 in the magicblock-aperture.md file to clearly state a single, unambiguous rule for how the WebSocket port is determined in all cases. If there is a special case when the HTTP port is 0, explicitly document it as the exception rather than presenting both rules as simultaneously valid, and ensure the actual port discovery mechanism through JsonRpcServer is clearly referenced for resolving the actual bound ports after startup.
♻️ Duplicate comments (1)
agents/crates/test-kit.md (1)
272-274:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winRemove the stray prompt path from the validation example.
prompts/ai/agents/03_batch-crates-plan.mdis not a repository file, so the documentedgit diff --checkcommand will fail when copied verbatim. Please drop it from the example.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@agents/crates/test-kit.md` around lines 272 - 274, The git diff --check command example in the validation documentation includes a file path that does not exist in the repository, which will cause the command to fail when executed. Remove the stray path prompts/ai/agents/03_batch-crates-plan.md from the git diff command so that only valid repository files are referenced, allowing the example command to execute successfully when copied verbatim.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@agents/05_testing-and-validation.md`:
- Around line 147-166: The first two nextest command examples in the
documentation use invalid CLI syntax with the `--test <test_file>` flag, which
is not supported by cargo nextest. In the first nextest example, remove `--test
<test_file>` and pass the test name as a positional argument directly after the
crate specification. In the second nextest example with the `-E` filterset flag,
also remove the invalid `--test <test_file>` portion since the `-E` flag already
handles precise test selection. Leave the third `cargo test` example unchanged
as it is correct. The goal is to provide working nextest commands that match
nextest's actual CLI syntax.
In `@agents/crates/magicblock-version.md`:
- Around line 230-235: The nextest command invocations in the documentation are
using incorrect syntax for specifying test names. Replace the two cargo nextest
run commands to properly pass test names either using the -E 'test(...)' filter
syntax as the primary nextest approach, or alternatively using -- with --exact
flags to pass arguments to the underlying test harness. Specifically, update the
command for the node test to use the correct test_get_version filter/argument
syntax, and update the command for the batches test to use the correct
test_batch_requests filter/argument syntax.
---
Outside diff comments:
In `@agents/crates/magicblock-aperture.md`:
- Line 90: The documentation for ApertureConfig::listen contains contradictory
statements about the WebSocket port binding rule. The current text states both
that the WebSocket listener uses listen.port() + 1 AND that if HTTP port is 0,
WebSocket also binds port 0, which are mutually exclusive. Rewrite the
description at line 90 in the magicblock-aperture.md file to clearly state a
single, unambiguous rule for how the WebSocket port is determined in all cases.
If there is a special case when the HTTP port is 0, explicitly document it as
the exception rather than presenting both rules as simultaneously valid, and
ensure the actual port discovery mechanism through JsonRpcServer is clearly
referenced for resolving the actual bound ports after startup.
In `@agents/crates/magicblock-chainlink.md`:
- Around line 41-49: The markdown table in magicblock-chainlink.md contains
ambiguous bare path references like `src/chainlink/mod.rs` and `tests/`. Update
all path entries in the table to use fully qualified repo-relative paths by
prepending the appropriate path prefix (such as `magicblock-chainlink/` or the
full path from the repo root) to each bare `src/...` and `tests/...` entry. This
will make the paths unambiguous from the repo root and consistent with the rest
of the documentation guide, enabling easier copy/paste navigation and grep-based
lookup.
In `@agents/crates/magicblock-metrics.md`:
- Around line 121-126: The `/metrics` endpoint currently logs a warning and
returns an empty 200 body when text encoding fails, which makes encoding
failures indistinguishable from a healthy empty registry and prevents Prometheus
from detecting metrics outages. Modify the error handling in the metrics
endpoint to return an HTTP error status code (such as 500 Internal Server Error)
when text encoding of the metrics registry fails, ensuring the failure is
visible to the Prometheus scraper caller instead of silently returning an empty
response body.
In `@agents/crates/magicblock-rpc-client.md`:
- Around line 223-226: The `wait_for_processed_status` function advertises a
`_blockhash_valid_timeout` parameter but does not actually use it for enforcing
blockhash validity checks, giving callers a false sense of protection on a
critical settlement path. Either implement active waiting for blockhash validity
using the timeout parameter value and update the relevant tests to verify this
behavior, or remove the `_blockhash_valid_timeout` parameter entirely from the
function signature and its documentation to accurately reflect the actual
implementation behavior.
---
Duplicate comments:
In `@agents/crates/test-kit.md`:
- Around line 272-274: The git diff --check command example in the validation
documentation includes a file path that does not exist in the repository, which
will cause the command to fail when executed. Remove the stray path
prompts/ai/agents/03_batch-crates-plan.md from the git diff command so that only
valid repository files are referenced, allowing the example command to execute
successfully when copied verbatim.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: b235fcfe-3d13-436b-a377-dfa80f87da39
📒 Files selected for processing (24)
agents/00_overview.mdagents/01_validator-goals.mdagents/02_specification.mdagents/03_architecture.mdagents/05_testing-and-validation.mdagents/crates/magicblock-account-cloner.mdagents/crates/magicblock-accounts.mdagents/crates/magicblock-aml.mdagents/crates/magicblock-aperture.mdagents/crates/magicblock-api.mdagents/crates/magicblock-chainlink.mdagents/crates/magicblock-config.mdagents/crates/magicblock-core.mdagents/crates/magicblock-magic-program-api.mdagents/crates/magicblock-metrics.mdagents/crates/magicblock-rpc-client.mdagents/crates/magicblock-services.mdagents/crates/magicblock-table-mania.mdagents/crates/magicblock-task-scheduler.mdagents/crates/magicblock-validator-admin.mdagents/crates/magicblock-validator.mdagents/crates/magicblock-version.mdagents/crates/storage-proto.mdagents/crates/test-kit.md
💤 Files with no reviewable changes (4)
- agents/crates/magicblock-api.md
- agents/crates/magicblock-config.md
- agents/crates/magicblock-aml.md
- agents/crates/magicblock-account-cloner.md
| Prefer `cargo nextest` when available: | ||
|
|
||
| ```bash | ||
| cd test-integration | ||
| RUST_LOG=info cargo nextest run -p <test-crate> --test <test_file> <test_name> --no-capture | ||
| ``` | ||
|
|
||
| Or with an exact nextest expression: | ||
|
|
||
| ```bash | ||
| cd test-integration | ||
| RUST_LOG=info cargo nextest run -p <test-crate> --test <test_file> -E 'test(<exact_test_name>)' --no-capture | ||
| ``` | ||
|
|
||
| Use `cargo test` instead when you need libtest-only flags such as `--test-threads=1` or `--exact`: | ||
|
|
||
| ```bash | ||
| cd test-integration | ||
| RUST_LOG=info cargo test -p <test-crate> --test <test_file> <test_name> -- --test-threads=1 --nocapture | ||
| ``` |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
if cargo nextest run --help >/tmp/nextest-help.txt 2>&1; then
sed -n '1,200p' /tmp/nextest-help.txt
else
printf 'cargo-nextest is not available here; verify the examples locally.\n' >&2
fi
cargo test --help | sed -n '1,160p'Repository: magicblock-labs/magicblock-validator
Length of output: 3646
🌐 Web query:
cargo nextest run CLI flags syntax documentation --test --no-capture
💡 Result:
In cargo-nextest, the --no-capture flag and the --test syntax have specific roles and behaviors: --no-capture The --no-capture flag directs cargo-nextest to run tests serially and disable output capturing [1][2]. When this flag is used, test output (stdout and stderr) is displayed immediately as the tests run, rather than being captured and reported after the test finishes [3][2]. This is useful for debugging and viewing output in real-time [2]. --test (and positional arguments) Unlike cargo test, which uses the --test flag to specify a particular test binary to run, cargo-nextest primarily uses positional arguments and filtersets to select tests [4]. If you want to specify a test binary or a specific test, you typically provide the name as a positional argument [5]. For compatibility with cargo test, cargo-nextest allows passing arguments after a double-dash (--), which are then interpreted in a way similar to cargo test [4]. For example, to pass --skip or --exact arguments, you would use: cargo nextest run -- --skip my_test_name [4] Summary of usage: - To run tests without capturing output: cargo nextest run --no-capture [3] - To filter by specific tests or binaries: Use positional arguments (e.g., cargo nextest run test_name) or the -E / --filterset flag for advanced filtering [4][5]. - To use cargo test-style arguments: Place them after a -- separator (e.g., cargo nextest run -- --exact test_name) [4].
Citations:
- 1: https://nexte.st/docs/running/
- 2: https://nexte.st/docs/integrations/debuggers-tracers/
- 3: https://nexte.st/docs/reporting/
- 4: https://nexte.st/docs/selecting/
- 5: https://raw.githubusercontent.com/laurigates/claude-plugins/main/rust-plugin/skills/cargo-nextest/SKILL.md
🏁 Script executed:
# Search for any nextest usage in the codebase
rg "cargo nextest" --type md --type yml --type yaml --type sh --type bash -A 2 -B 2Repository: magicblock-labs/magicblock-validator
Length of output: 108
🏁 Script executed:
# Check the documentation file itself to see full context
head -200 agents/05_testing-and-validation.md | tail -100Repository: magicblock-labs/magicblock-validator
Length of output: 3550
Fix the cargo nextest examples—they use invalid CLI syntax.
The documented nextest commands use --test <test_file> which is not a valid flag for cargo nextest. According to nextest documentation, test selection uses positional arguments or the -E/--filterset flag, not --test. The first two examples will fail if executed.
Replace:
cargo nextest run -p <test-crate> --test <test_file> <test_name> --no-captureWith (if test_name alone is sufficient):
cargo nextest run -p <test-crate> <test_name> --no-captureOr use nextest's filterset syntax for precise selection:
cargo nextest run -p <test-crate> -E 'test(<exact_test_name>)' --no-captureThe second example similarly needs the --test <test_file> removed since -E already handles test selection. Only the cargo test example (third) is correct.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@agents/05_testing-and-validation.md` around lines 147 - 166, The first two
nextest command examples in the documentation use invalid CLI syntax with the
`--test <test_file>` flag, which is not supported by cargo nextest. In the first
nextest example, remove `--test <test_file>` and pass the test name as a
positional argument directly after the crate specification. In the second
nextest example with the `-E` filterset flag, also remove the invalid `--test
<test_file>` portion since the `-E` flag already handles precise test selection.
Leave the third `cargo test` example unchanged as it is correct. The goal is to
provide working nextest commands that match nextest's actual CLI syntax.
| For RPC-visible changes, also run the relevant Aperture tests: | ||
|
|
||
| ```bash | ||
| cargo nextest run -p magicblock-aperture --test node test_get_version | ||
| cargo nextest run -p magicblock-aperture --test batches test_batch_requests | ||
| ``` |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
# First, check if the file exists and view the context around lines 230-235
fd -t f "magicblock-version.md" | head -20Repository: magicblock-labs/magicblock-validator
Length of output: 116
🏁 Script executed:
# Search for nextest usage patterns in the codebase
rg "cargo nextest" -A 2 -B 2 | head -100Repository: magicblock-labs/magicblock-validator
Length of output: 5595
🏁 Script executed:
# Look for any CI configuration files that might show nextest usage
fd -t f "\.(yml|yaml|sh)$" | xargs rg "nextest" 2>/dev/null | head -50Repository: magicblock-labs/magicblock-validator
Length of output: 62
🌐 Web query:
nextest cargo flags --test parameter syntax documentation
💡 Result:
In cargo-nextest, there are two primary ways to filter by test target (e.g., integration tests or specific binary files): using target-selection flags and using filtersets [1][2][3]. Target-Selection Flags These flags are used to select specific test targets (like libraries, examples, or integration tests) before tests are run [3]. They are similar to those used in standard cargo test [2][3]. Common examples include: --lib: Test only the package's library unit tests [3]. --bin : Test only the specified binary [3]. --example : Test only the specified example [3]. --test : Test only the specified integration test target [3]. --bench : Test only the specified benchmark target [3]. For a complete list of these flags, you can run cargo nextest run --help [2][3]. Filtersets (Advanced Filtering) For more complex selections, nextest provides a domain-specific language (DSL) called filtersets, accessed via the -E or --filterset flag [1][4]. This allows you to filter by package, binary ID, and test kind, and supports operators like regex, glob, and logical operators (and, or, not) [1][5][4]. Examples of filtersets: Run tests by name: -E 'test(my_test_name)' [4] Run by package: -E 'package(my_crate)' [4] Filter by test kind (e.g., lib, bin, test, bench): -E 'kind(test)' [6] Combine expressions: -E 'package(serde) and test(deserialize)' [4] Emulating cargo test --test If your intention is to pass arguments directly to the underlying libtest harness (the standard Rust test runner), you place those arguments after a double-dash (--), just as you would with cargo test [2][7]. Example: cargo nextest run -- --ignored In this syntax, everything after the -- is passed directly to the test binaries [2][7]. Supported libtest-style arguments include: --ignored: Only run ignored tests [2][3]. --skip : Skip tests matching the pattern [2][3]. --exact: Require test names to match the filter exactly [2][3]. --nocapture: Run tests serially and disable output capture [2][3]. top_results: [1][2][3][4]
Citations:
- 1: https://nexte.st/docs/selecting/
- 2: https://nexte.st/docs/running/
- 3: https://nexte.st/docs/listing/
- 4: https://nexte.st/docs/filtersets/
- 5: https://nexte.st/docs/filtersets/reference/
- 6: https://raw.githubusercontent.com/laurigates/claude-plugins/main/rust-plugin/skills/cargo-nextest/SKILL.md
- 7: https://doc.rust-lang.org/stable/cargo/commands/cargo-test.html
🏁 Script executed:
# View the exact file content around lines 230-235 to confirm the snippet
sed -n '225,240p' agents/crates/magicblock-version.mdRepository: magicblock-labs/magicblock-validator
Length of output: 562
Fix the nextest invocation syntax—test names must use filter syntax, not positional arguments.
The test names cannot be passed as loose positional arguments. According to nextest documentation and codebase patterns, they must use the -E 'test(...)' filter syntax:
cargo nextest run -p magicblock-aperture --test node -E 'test(test_get_version)'
cargo nextest run -p magicblock-aperture --test batches -E 'test(test_batch_requests)'Alternatively, use -- to pass arguments to the underlying test harness with --exact:
cargo nextest run -p magicblock-aperture --test node -- --exact test_get_version
cargo nextest run -p magicblock-aperture --test batches -- --exact test_batch_requests🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@agents/crates/magicblock-version.md` around lines 230 - 235, The nextest
command invocations in the documentation are using incorrect syntax for
specifying test names. Replace the two cargo nextest run commands to properly
pass test names either using the -E 'test(...)' filter syntax as the primary
nextest approach, or alternatively using -- with --exact flags to pass arguments
to the underlying test harness. Specifically, update the command for the node
test to use the correct test_get_version filter/argument syntax, and update the
command for the batches test to use the correct test_batch_requests
filter/argument syntax.
1 participant
Summary
Adds a structured AI-agent guidance set for the validator repo so future agents can quickly understand the system goals, protocol invariants, architecture, crate ownership, and validation workflow before making changes.
Details
Agent guidance entrypoint
Adds
AGENTS.mdas the stable entrypoint for agent work. It explains the required acknowledgement flow, points agents at the relevant guidance files, and requires these docs to stay synchronized with behavior when features or architecture change.Repository-level agent docs
Adds focused guidance under
agents/covering:Chainlink crate guide
Adds
agents/crates/magicblock-chainlink.md, a detailed crate-specific guide for the Chainlink account synchronization crate. It documents the major fetch/clone, delegation, subscription, eviction, program loading, ATA/eATA projection, and undelegation-tracking flows, along with pitfalls and invariants agents should preserve.Documentation organization
Renames the initial agent docs to a consistent underscore-based numbering scheme and links the Chainlink crate guide from the crate map and entrypoint so agents can find it before touching Chainlink behavior.
Summary by CodeRabbit