docs: add node-types page; trim duplicate ASCII diagrams from halt RCA

[luishsr]

Summary

• Adds doc/node-types.md: Validator/Observer/Archive reference (role, config, why it matters), cross-linked from doc/README.md and doc/glossary.md.
• In doc/incidents/2026-06-21-mainnet-halt.md, removes the characters-based pipeline/failure/fix diagrams, which duplicated the existing Mermaid diagrams — Mermaid is now the single source. The one unique data point (observed telemetry) is preserved as a plain note.

Test plan

• Docs only — no code changes. Preview rendered Markdown/Mermaid on GitHub.

[github-actions]

Claude finished @luishsr's task in 2m 25s —— View job

---

PR Review

• Gather context and read changed files
• Review doc/node-types.md
• Review doc/incidents/2026-06-21-mainnet-halt.md
• Review doc/README.md and doc/glossary.md changes
• Post final review

---

This is a well-grounded documentation PR. Code references are specific (file paths + line numbers), cross-links are accurate, and the "Archive is not a code concept" disclaimer in node-types.md:148-150 is exactly the right thing to say. Two issues need fixing before merge; the rest are observations.

---

Issues to fix

1. Stray code fence at end of incident file (doc/incidents/2026-06-21-mainnet-halt.md:108)

The file ends with a lone ``` on line 108 that has no matching opening fence. GitHub's renderer will treat the entire Evidence section's last bullet as being inside an unclosed code block, mangling its display. Fix this →

# line 107 (last bullet, correct)
- fix: `3a71a1a` — `consensus_bus.rs` (`executed_anchor`), ...
# line 108 (delete this)

**2. Mermaid `O --> A` edge implies data flow, but Archive is just a pruning config (`doc/node-types.md:35-36`)**

```mermaid
O -->|"run without --full / --minimal"| A["Archive<br/>..."]

This reads as "Observer streams to Archive," which contradicts the prose that correctly says Archive is an Observer with pruning disabled — not a downstream consumer. The edge direction and label mislead: someone skimming the diagram will infer there are two separate node processes (Observer feeding Archive), when there is actually one process run with different flags.

Suggested fix — use a style note or a subgraph to make Archive a configuration of Observer, or rephrase the edge: Fix this →

---

Observations (no action required, but worth knowing)

doc/incidents/ has no index entry in doc/README.md

The new doc/incidents/ directory isn't linked anywhere from the top-level README. This is the first post-mortem; if more will follow, adding a "Incidents / post-mortems" entry to doc/README.md now would be cleaner than retroactively adding it later. Low priority — fine to do as a follow-up.

node-types.md correctly disclaims "Archive" as a synthesis, not a prior convention

This page is the first place that names "Archive" as a distinct node type — there is no prior doc or code convention to defer to here (node-types.md:147-150)

This transparency is good and matches the stated goal of the PR. No action needed.

All code-path references verified: consensus_bus.rs, certifier.rs, primary.rs, proposer/mod.rs, consensus/state.rs, network/handler.rs, rpc_server_args.rs, persistence.rs, and batch-builder/src/lib.rs all exist at the cited paths. The glossary cross-link (glossary.md:74 → node-types.md) resolves correctly now that the file exists.

---

Summary: Approve after the stray ``` on line 108 is removed and the O --> A Mermaid edge is reworded to avoid implying data-flow between Observer and Archive. Everything else is solid.

[github-actions]

Security Scan - Code

Severity: HIGH, CRITICAL

No vulnerabilities found

View scan results

Report Summary

┌─────────────────────────────────────────────┬────────────┬─────────────────┬───────────────────┐
│                   Target                    │    Type    │ Vulnerabilities │ Misconfigurations │
├─────────────────────────────────────────────┼────────────┼─────────────────┼───────────────────┤
│ Cargo.lock                                  │   cargo    │        0        │         -         │
├─────────────────────────────────────────────┼────────────┼─────────────────┼───────────────────┤
│ crates/testing/fuzz-targets/Cargo.lock      │   cargo    │        0        │         -         │
├─────────────────────────────────────────────┼────────────┼─────────────────┼───────────────────┤
│ crates/testing/fuzz-targets/fuzz/Cargo.lock │   cargo    │        0        │         -         │
├─────────────────────────────────────────────┼────────────┼─────────────────┼───────────────────┤
│ etc/state-sum/Cargo.lock                    │   cargo    │        0        │         -         │
├─────────────────────────────────────────────┼────────────┼─────────────────┼───────────────────┤
│ etc/tps/package-lock.json                   │    npm     │        0        │         -         │
├─────────────────────────────────────────────┼────────────┼─────────────────┼───────────────────┤
│ rayls-contracts/package-lock.json           │    npm     │        0        │         -         │
├─────────────────────────────────────────────┼────────────┼─────────────────┼───────────────────┤
│ etc/chaos-network/Dockerfile                │ dockerfile │        -        │         0         │
├─────────────────────────────────────────────┼────────────┼─────────────────┼───────────────────┤
│ etc/docker-network/Dockerfile               │ dockerfile │        -        │         0         │
├─────────────────────────────────────────────┼────────────┼─────────────────┼───────────────────┤
│ etc/docker-replay/Dockerfile                │ dockerfile │        -        │         0         │
└─────────────────────────────────────────────┴────────────┴─────────────────┴───────────────────┘
Legend:
- '-': Not scanned
- '0': Clean (no security findings detected)

[luishsr]

Outstanding from #48's Definition of Done: per-node machine sizing/cost is still open and needs SRE input — not addressed by this PR. `doc/node-types.md` flags it explicitly under "Open questions" rather than answering it, so it isn't lost, but it should be resolved before this doc is treated as complete guidance for provisioning.

[github-actions]

Claude finished @luishsr's task in 1m 23s —— View job

---

PR Review — follow-up after commit 69ee8ab

• Gather context and read changed files
• Check if stray ``` on line 108 was removed (doc/incidents/2026-06-21-mainnet-halt.md)
• Check if O --> A Mermaid edge was corrected (doc/node-types.md)
• Review new commit content (RPC exposure/public-access diagram)
• Post final review

---

New commit (69ee8ab) — good addition

Adding RPC exposure labels directly into the Mermaid diagram nodes is the right call: it makes the diagram self-contained across all four dimensions (committee membership, voting, state, RPC posture) without requiring readers to cross-reference the table. The per-node labels are accurate:

• RPC: loopback only — not public on Validator matches the prose and code at rpc_server_args.rs:57-58
• RPC: public — accepts tx submission on Observer and RPC: public — plus full history queries on Archive are both consistent with the operator guidance.

---

Issues still open from the previous review

Both items flagged earlier are unaddressed in this commit.

1. Stray ``` on line 108 of the incident file — still present

doc/incidents/2026-06-21-mainnet-halt.md:108 still ends with a lone ``` that has no matching opening fence:

107: - fix: `3a71a1a` — `consensus_bus.rs` (`executed_anchor`), ...
108: ```    ← delete this line

GitHub's renderer treats everything from the "Evidence" section's last bullet onward as inside an unclosed code block, making the evidence list unreadable. Fix this →

2. O --> A edge still implies data flow — still present

The diagram still has:

O -->|"run without --full / --minimal"| A["Archive..."]

This reads as "Observer streams to Archive," implying two separate node processes with a data pipe between them. The prose on node-types.md:159 correctly says "it is an Observer" — the diagram contradicts that. A reader skimming the diagram will infer a topology that doesn't exist.

Suggested fix — use a dotted line and reword the edge so it reads as a configuration variant, not a data-flow hop:

-    O -->|"run without --full / --minimal"| A["Archive<br/>Observer + pruning disabled<br/>full tx/log history<br/>RPC: public — plus full history queries"]
+    O -. "configured as (pruning flag omitted)" .-> A["Archive<br/>Observer + pruning disabled<br/>full tx/log history<br/>RPC: public — plus full history queries"]

Or, more explicitly, wrap Archive in a subgraph as a config variant of Observer. Fix this →

---

Summary: The new commit improves the diagram and addresses the Issue #48 completeness requirement. The two blocking issues (stray ``` and misleading edge direction) still need to land before merge.