Docs drift sweep: post-v0.5.10 audit follow-up (#45)

[StreamDemon]

Summary

Docs-only drift sweep implementing the post-v0.5.10 full-docs audit (issue #45). Every fix is spec-authoritative: LANGUAGE_SPEC.md wins, the doc page moves. No docs/spec-plans/ files, no scripts/, and no AGENTS.md files are touched (a parallel PR owns AGENTS.md).

Scope changes since the issue was filed. Spec v0.5.11 (contextual keywords, grammar repair) and v0.5.12 (semantic reconciliation, ActorId Debug, struct literals) merged while this issue was open, which changes the disposition of five items:

• Items 7, 20, 30 — absorbed by v0.5.12. Verified on main: docs/guide/actors-and-concurrency.md and docs/runbooks/actor-debugging.md already format ActorId with {:?}, and docs/stdlib/test.md:124 already reads Err(ActorError::Dead) with the panic message read from the dead snapshot (DeathCause::RuntimeFailure { panic }). No edits needed.
• Item 32 — absorbed by v0.5.12. docs/stdlib/chain.md:62 already reads version-neutrally ("No delegatecall (not yet specified; ...)").
• Item 37 — legalized by v0.5.11. docs/examples/rest-api.md:58 uses .send(...) in method-call position, which is an ordinary identifier under the contextual-keyword rules (§2.3/§2.7: send is a keyword only as the first token of a send-statement). No edit needed.
• Item 9 — deferred. The guide's log::info/log::warn/log::error usage is not a contradiction (std::log exists, native/wasm targets); growing docs/stdlib/log.md beyond its stub is stdlib API design work, not drift, and is left for a dedicated issue.

Spec-side notes surfaced by this sweep (no spec edits smuggled in):

• Item 12: the deleted "No references in public function parameters" bullet in onchain-overview.md has no basis in §11. If that rule is actually intended for on-chain pub functions, it needs a spec amendment — flagging here rather than keeping unsourced doc prose.
• Item 14: the deleted dynamic-length-key rule in storage-and-state.md is not stated in §11.1a (Sploosh Map keys are currently value-typed, so the rule was unreachable anyway). If String/bytes keys land later, §11.1a should gain the Solidity raw-bytes-concat rule first.
• Item 35: the spec's own §6.4 load_config example shares the From-path hole fixed in cli-tool.md — it propagates fs::read(...).context(...)? into an AppError that declares no fs-error variant, and the fs error type itself is never named anywhere in the spec or docs/stdlib/fs.md. Spec-side finding only; not edited here.

Per-item disposition

Items	Disposition
1–6, 8 (guides)	Fixed
10–15 (web3)	Fixed
16–19 (runbooks)	Fixed
21–24 (reference)	Fixed
25–29, 31, 33 (stdlib)	Fixed
34–36 (migration/examples)	Fixed
7, 20, 30, 32	Absorbed by v0.5.12 (verified on main)
37	No edit needed (legalized by v0.5.11 contextual send)
9	Deferred (stdlib log API design, not drift)

Closes #45

Test plan

• Re-grepped every fixed pattern across docs/ (excluding docs/spec-plans/); all zero hits: recv channel_, spawn async fetch_data, JoinHandle<Result<, Pre-1153 forks are not supported, No references in public function parameters, value-typed in v0.4.4, Dynamic-length keys, deferred to v0.5.0, for all public actor method parameters, in v0.5.5, keccak256(key ++ slot), onchain module, must return .Result, wake with Err(SendError::Dead), tx.send("hello".into());. The single remaining println hit is from-rust.md's Rust-side mapping column (correct as-is).
• Positive greps confirm added content: SendError::Dead arm + per-sender FIFO line in the actors guide, Shared<T> pointer in the ownership runbook, onchain-prohibition sentence in net.md/io.md, vacant in compiler-errors.md, W0010 pointer in math.md, Blake3 in crypto.md, i128/u128 + assert re-export in test.md, targets line in collections.md, trunc_sat rules in type-conversion-rules.md.
• Every edited code sample sanity-checked against current §16 grammar (struct literals, contextual keywords, spawn async block) and the cited spec sections (§3.11, §6.3/§6.4, §8.2, §8.5, §8.6, §8.9, §8.11/§8.11a, §11.1a, §11.2, §11.3a, §13.0, §13.2, §13.3.6/§13.3.8, §14.3, §18.4).
• python scripts/check_prompt_budget.py exits 0 (pre-existing WARN tier on _CORE at 99.0%; no PROMPT files touched by this PR).

🤖 Generated with Claude Code

---

Summary by cubic

Docs drift sweep aligning guides, web3, runbooks, reference, stdlib, and examples with the spec after v0.5.10 (incl. v0.5.11–v0.5.12). Completes the post‑v0.5.10 docs audit in #45.

• Bug Fixes

  • Actors/channels: send/recv now return Result in examples; send_timeout includes SendError::Dead; per‑sender FIFO stated; select uses pattern = expr.
  • Async: spawn async { ... } with inner .await; JoinHandle<T> typing fixed; print(format(...)) replaces println.
  • On‑chain: forbid async/.await and Shared<T>; std::io/std::net marked unavailable; removed the unsupported “no refs in public params” rule.
  • Web3: nested maps use keccak256(abi.encode(key, map_slot)); reentrancy guard notes SLOAD/SSTORE fallback; event ABI note updated; EVM/SVM table marks ctx::caller()/ctx::self_address() as universal.

• Refactors

  • @mailbox semantics clarified: full mailbox blocks; on death, plain send drops and returns (), send_timeout returns Err(SendError::Dead), request/reply returns Err(ActorError::Dead); citation corrected to §8.11.
  • Type conversion rules add non‑finite float→int trunc_sat; compiler error guide adds “compile warning” kind and vacant status.
  • Stdlib docs: targets called out (std::collections, std::math ints vs floats), on‑chain bans for std::io/std::net; math notes W0010 for off‑chain u256; crypto mentions Blake3; test adds i128/u128 and assert.
  • Examples: CLI tool derives Deserialize, wires From<fs::FsError>, and clones before matching; hello world softens main return wording.

^{Written for commit 91930f7. Summary will update on new commits.}

[cubic-dev-ai]

2 issues found across 23 files

Confidence score: 5/5

• In docs/examples/cli-tool.md, using unqualified FsError instead of fs::FsError can confuse readers copying the example and lead to avoidable compile/type-resolution errors in their own code — align it with json::JsonError/use std::fs; before merging.
• In docs/reference/attributes.md, the §8.11a citation points to the wrong subsection, which could misdirect users on death-while-blocked mailbox semantics and cause incorrect implementation assumptions — update the reference to the correct section before merging.

Architecture diagram

sequenceDiagram
    participant Dev as Developer
    participant Doc as Doc Site
    participant Spec as LANGUAGE_SPEC.md
    participant Compiler as Compiler
    participant Runtime as Runtime
    participant OnChain as On-Chain VM
    participant OffChain as Off-Chain Runtime
    
    Note over Dev,OffChain: Docs Drift Audit Post-v0.5.10
    
    Dev->>Doc: Edit docs/ files (23 files)
    Dev->>Spec: Reference authoritative spec sections
    
    Note over Doc,Spec: Cross-target build constraints
    
    Doc->>Compiler: Enforce on-chain restrictions
    Compiler->>OnChain: Block std::io, std::net
    Compiler->>OnChain: Block async/.await, Shared<T>
    Compiler->>OnChain: Block actor/spawn/send intrinsics
    Compiler->>OffChain: Allow std::math floats, @fast_math
    Compiler->>OffChain: Emit W0010 for u256 emulation
    
    Note over Doc,Compiler: Actor & concurrency (spec §8)
    
    Doc->>Runtime: Define mailbox semantics
    Runtime->>Runtime: Lock across .await points
    Runtime->>Runtime: Per-sender FIFO ordering
    alt Destination dies while sender blocked
        Runtime->>Dev: Plain send: drop & return ()
        Runtime->>Dev: send_timeout: Err(SendError::Dead)
        Runtime->>Dev: request/reply: Err(ActorError::Dead)
    end
    
    Note over Doc,Compiler: Type system & conversions (spec §3)
    
    Spec->>Doc: Float->int trunc_sat rules
    Doc->>Compiler: Non-finite -> 0/MAX/MIN
    Spec->>Doc: i128/u128 type support
    Doc->>Compiler: Register types in stdlib test
    
    Note over Doc,OnChain: Storage layout (spec §11)
    
    Spec->>Doc: Nested map key derivation
    Doc->>OnChain: keccak256(abi.encode(key, map_slot))
    Spec->>Doc: Remove dynamic-length key rule
    Spec->>Doc: Value-typed keys only
    
    Note over Doc,Runtime: Reentrancy guard (spec §11.3a)
    
    Doc->>OnChain: Pre-1153 fallback to SLOAD/SSTORE
    OnChain->>OnChain: Journal provides unwind-on-revert
    Doc->>OnChain: Flag never observable across transactions
    
    Note over Doc,Compiler: Diagnostic codes (spec §18)
    
    Doc->>Compiler: Add compile warning kind
    Compiler->>Doc: Classify W<NNNN> codes
    Doc->>Compiler: Add vacant status
    Compiler->>Doc: E1114 slot reserved never reassigned
    
    Note over Doc,OffChain: Stdlib API surface
    
    Doc->>OffChain: std::collections all targets
    Doc->>OffChain: std::crypto Blake3 planned
    Doc->>OffChain: std::test re-exports assert
    Doc->>OffChain: assert_eq/ne/matches test-prelude only

Loading

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

0 issues found across 2 files (changes from recent commits).

<sub>Requires human review: Contains structural changes to documentation, including code samples, cross-references, and type conversion rules. These involve domain knowledge about the spec, grammar, and correctness of examples, which require human review to ensure accuracy.

Re-trigger cubic</sub>