Grab-bag of small honesty/consistency debts found while validating the documentation against the code (Aug 2026). None are urgent; all are cheap.
1. Mutex wait queue is LIFO while design text claimed FIFO fairness
codegen/src/runtime/mutex.rs:21 (wait_queue: Vec<Arc<GreenThread>>), waiters pushed at mutex.rs:55, woken via wait_queue.pop() at mutex.rs:92 — the most-recent waiter wins, so starvation is possible under contention. Older design docs claimed FIFO ordering "for fairness." Either switch to VecDeque + pop_front, or keep LIFO deliberately and say so. (Docs now describe it neutrally.)
2. Diagnostic codes have been silently reassigned
E003 is now BinaryOpError (ast/src/templates/type_errors/mod.rs:19-24); break/continue-outside-loop moved to E029 ControlFlowError (mod.rs:163-164). E022 is currently unassigned. If codes are meant to be stable enough to document and search for, they should be append-only — reassignment breaks old references. Suggest adopting that policy and reserving retired codes.
3. L008 MissingNewline is defined but never emitted
Template at ast/src/templates/lex_errors/mod.rs:30 and registered at ast/src/templates/mod.rs:145, but nothing in lexer/src/lib.rs ever produces it. Emit it or delete it (and if deleted, see item 2 — retire the code, don't reuse it).
4. Stale code comments that contradict the code
ast/src/types.rs:30 — "Map type scaffolding — parser support exists but no literal syntax or runtime yet": map literals parse and typecheck today.fir/src/lower/closure.rs:7 — doc comment says lambda lowering "returns a dummy value"; it returns a first-class FirExpr::ClosureCreate now.codegen/src/runtime/channel.rs:25 — "capacity (0 = unbounded, default 64)": the code maps <= 0 to 64 (channel.rs:28); nothing is unbounded.
Documentation
The corrected, code-verified descriptions live in the docs site: docs/src/content/docs/concurrency/primitives.mdx (mutex/channel), internals/diagnostics.mdx (code tables), and reference/roadmap.mdx (stale-comment inventory).
Grab-bag of small honesty/consistency debts found while validating the documentation against the code (Aug 2026). None are urgent; all are cheap.
1. Mutex wait queue is LIFO while design text claimed FIFO fairness
codegen/src/runtime/mutex.rs:21(wait_queue: Vec<Arc<GreenThread>>), waiters pushed atmutex.rs:55, woken viawait_queue.pop()atmutex.rs:92— the most-recent waiter wins, so starvation is possible under contention. Older design docs claimed FIFO ordering "for fairness." Either switch toVecDeque+pop_front, or keep LIFO deliberately and say so. (Docs now describe it neutrally.)2. Diagnostic codes have been silently reassigned
E003 is now
BinaryOpError(ast/src/templates/type_errors/mod.rs:19-24); break/continue-outside-loop moved to E029ControlFlowError(mod.rs:163-164). E022 is currently unassigned. If codes are meant to be stable enough to document and search for, they should be append-only — reassignment breaks old references. Suggest adopting that policy and reserving retired codes.3. L008
MissingNewlineis defined but never emittedTemplate at
ast/src/templates/lex_errors/mod.rs:30and registered atast/src/templates/mod.rs:145, but nothing inlexer/src/lib.rsever produces it. Emit it or delete it (and if deleted, see item 2 — retire the code, don't reuse it).4. Stale code comments that contradict the code
ast/src/types.rs:30— "Map type scaffolding — parser support exists but no literal syntax or runtime yet": map literals parse and typecheck today.fir/src/lower/closure.rs:7— doc comment says lambda lowering "returns a dummy value"; it returns a first-classFirExpr::ClosureCreatenow.codegen/src/runtime/channel.rs:25— "capacity (0 = unbounded, default 64)": the code maps<= 0to 64 (channel.rs:28); nothing is unbounded.Documentation
The corrected, code-verified descriptions live in the docs site:
docs/src/content/docs/concurrency/primitives.mdx(mutex/channel),internals/diagnostics.mdx(code tables), andreference/roadmap.mdx(stale-comment inventory).