docs(comments): sweep em dashes from source comments, test prose, and manifest

Same treatment for the prose the compiler carries: doc and line comments
across src/ and tests/, test assertion and error-message strings (prose
surfaces: the tunnel-map registration/establish errors, the key-source
decode payload, assertion messages), scripts/matrix.sh comment lines,
the fuzz sidecar's comments and README (corpus seeds untouched), and the
Cargo.toml comment headers plus the crates.io description. The AGENTS.md
no-em-dash rule (convention 14) now holds for the whole tracked tree.

Verification: repo-wide git grep is clean (single exempt hit: the
verification command's own search pattern), cargo test (18 suites, zero
failures, default and per-feature builds via scripts/matrix.sh), clippy
--all-targets -D warnings and clippy all-features, fmt --check, doc
--no-deps, and the fuzz corpus gate (fuzz/shared, 11 tests) all green.
This commit is contained in:
glm-5.3-flash committed 2026-11-04 20:28:05 +00:00
1 parent f4b5f896b4
commit 1e583ab55b
55 files changed
+1756 -1751

No files matched your search

+29 -29
View File
@@ -1,4 +1,4 @@
//! The exit-currency module — mapping.md §Exit chunk's derivation
//! The exit-currency module: mapping.md §Exit chunk's derivation
//! contract (rules 1–6, normative) as code, *shared by both
//! directions* (`w4-op-rows` extracted it out of `tty_map.rs`, whose
//! server-side session rows were its first and only consumer).
@@ -12,27 +12,27 @@
//! exactly one SSH exit report shape, **never widened**.
//! - **The client direction** (`w4-op-rows`): the SSH exit report →
//! the family `i32` code ([`signal_code_from_name`] and the
//! direct `u32 → i32` identity) — the exact inverse arm, riding the
//! direct `u32 → i32` identity), the exact inverse arm riding the
//! same table. The mirror consumes the convention as-is, including
//! its one collision (the `−1` sentinel vs a genuine SIGHUP —
//! its one collision (the `−1` sentinel vs a genuine SIGHUP;
//! mapping.md rule 3's symmetric-fidelity cost).
//!
//! No widening in either arm: the chunk is not enriched, the wire
//! report is not enriched, and the *core_dumped* bool is never
//! asserted (alktty discards it — nothing better is knowable).
//! asserted (alktty discards it; nothing better is knowable).
//!
//! ## The server arm's rules (mapping.md, normative)
//!
//! 1. `code ≥ 0` → `exit-status(N)`.
//! 2. negative `−N`, N ≥ 2 → `exit-signal(name)` via the crate-local
//! **Unix signum→name table** ([`SIGNAL_NAMES`]). Server-side
//! work — the signal semantics belong to the serving platform
//! work: the signal semantics belong to the serving platform
//! where the backend reaps. Deliberately *not* derived from
//! alktty's `signal_from_name` inverse, which is a forward
//! name→number map for the control row, not a derivation table.
//! `core_dumped` is **never asserted** — SSH's `exit-signal` bool
//! `core_dumped` is **never asserted**; SSH's `exit-signal` bool
//! stays false on every row.
//! 3. `−1` → `exit-status(255)`, never a signal claim — the
//! 3. `−1` → `exit-status(255)`, never a signal claim: the
//! could-not-determine sentinel collides with the SIGHUP encoding
//! on the pipe path, accepted symmetrically per the mapping:
//! neither a fabricated signal for a wait failure nor a real one.
@@ -41,13 +41,13 @@
//! 5. **The PTY-path fidelity limit (upstream)**: portable-pty 0.9
//! reaps a signal-terminated Unix child as a plain code (the
//! signal number is unrecoverable through its trait surface), so
//! signal-terminated PTY sessions arrive as `exit-status(1)` — a
//! signal-terminated PTY sessions arrive as `exit-status(1)`, a
//! documented alktty/portable-pty ask; this table in practice
//! sees the *pipe* path's negative encoding only. Faithful
//! `exit-signal` there needs the alktty backend to conform to its
//! own ADR's negative-code convention; alkssh's contract adapts
//! automatically.
//! 6. Unmapped negatives → rule 3 (`exit-status(255)`) — the mapping
//! 6. Unmapped negatives → rule 3 (`exit-status(255)`); the mapping
//! never invents a name (defensive case: the convention's
//! producers are `−1` and `−signum` only).
//!
@@ -56,26 +56,26 @@
//! 1. `exit-status(N)` → the family code `N` (direct identity).
//! 2. `exit-signal(name)` → the family code `−N` via the same
//! [`SIGNAL_NAMES`] table read backwards
//! ([`signal_code_from_name`]) — the mapping never invents a
//! ([`signal_code_from_name`]); the mapping never invents a
//! signum.
//! 3. A name with no table entry → `−1` (the sentinel; the same
//! honest could-not-determine semantic rule 3 consumes on the
//! server arm — including a genuine SIGHUP, whose mirror rides
//! server arm, including a genuine SIGHUP, whose mirror rides
//! `−1` by the same accepted collision).
//! 4. No exit report at all ends a session with none — the
//! 4. No exit report at all ends a session with none, the
//! no-exit-chunk close family's mirror ("reports nothing",
//! mapping.md): the caller observes the session's end, never a
//! fabricated code.
/// One SSH exit report shape derived from an exit chunk —
/// One SSH exit report shape derived from an exit chunk;
/// [`derive_exit`]'s outcome.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[cfg(feature = "session")]
pub(crate) enum ExitReport {
/// `exit-status(N)` — codes ≥ 0, the `−1` sentinel, and every
/// `exit-status(N)`: codes ≥ 0, the `−1` sentinel, and every
/// unmapped negative (rules 1, 3, 4, 6).
Status(u32),
/// `exit-signal(name)` — a mapped negative `−N`, N ≥ 2 (rule 2).
/// `exit-signal(name)`: a mapped negative `−N` where N ≥ 2 (rule 2).
/// The name is the table's value, never an invention.
Signal(&'static str),
}
@@ -83,11 +83,11 @@ pub(crate) enum ExitReport {
/// The crate-local Unix signum→name table (server arm rule 2 / client
/// arm rule 2): the 1–31 conventional Unix signals, as the exit
/// chunk's producers encode them (`−signum`) and as the wire's
/// `exit-signal` senders name them. Server-side work — the signal
/// `exit-signal` senders name them. Server-side work: the signal
/// semantics belong to the serving platform where the backend reaps.
/// Deliberately **not** derived from alktty's `signal_from_name` (a
/// forward name→number map for the control row, not a derivation
/// table; deliberately narrower too — it exists for what a front-end
/// table; deliberately narrower too, existing for what a front-end
/// sends, not for what a child can die by).
pub(crate) const SIGNAL_NAMES: &[(u32, &str)] = &[
(1, "HUP"),
@@ -124,7 +124,7 @@ pub(crate) const SIGNAL_NAMES: &[(u32, &str)] = &[
];
/// The derivation contract's whole decision procedure (the §module
/// docs' rules 1–6 — normative).
/// docs' rules 1–6; normative).
#[cfg(feature = "session")]
pub(crate) fn derive_exit(code: i32) -> ExitReport {
match code {
@@ -143,7 +143,7 @@ pub(crate) fn derive_exit(code: i32) -> ExitReport {
/// The client arm's inverse read (§module docs, rules 1–3): the SSH
/// `exit-signal` sender's name → the family exit-code convention's
/// value (`−signum`), `−1` for a name with no table entry (the
/// sentinel — the mapping never invents a signum; a genuine SIGHUP
/// sentinel; the mapping never invents a signum, and a genuine SIGHUP
/// rides it by the same accepted collision).
pub(crate) fn signal_code_from_name(name: &str) -> i32 {
match SIGNAL_NAMES.iter().find(|(_, n)| *n == name) {
@@ -155,7 +155,7 @@ pub(crate) fn signal_code_from_name(name: &str) -> i32 {
/// The table's name → russh's `Sig` vocabulary (the
/// `exit_signal_request` parameter). russh's known set rides its
/// variant names; anything else rides `Sig::Custom` (RFC 4254 §6.10's
/// signal-name encoding — vanilla clients parse arbitrary names).
/// signal-name encoding, since vanilla clients parse arbitrary names).
#[cfg(feature = "session")]
pub(crate) fn sig_from_name(name: &str) -> russh::Sig {
match name {
@@ -177,7 +177,7 @@ pub(crate) fn sig_from_name(name: &str) -> russh::Sig {
/// The SSH signal row's name translation: russh's `Sig` → the name
/// string alktty's control vocabulary carries (the uppercase names;
/// `Custom` carrying its own). Names flow to the backend verbatim —
/// `Custom` carrying its own). Names flow to the backend verbatim,
/// no alkssh-side filter (mapping.md §the control rows; the client
/// arm's `exit-signal` consumption reads through this before
/// [`signal_code_from_name`]).
@@ -207,7 +207,7 @@ mod tests {
use russh::Sig;
/// - *Contract stamp:* mapping.md §Exit chunk rule 1 (`code ≥ 0`
/// → `exit-status(N)` — the chunk carries the whole truth for
/// → `exit-status(N)`; the chunk carries the whole truth for
/// clean exits).
#[test]
fn non_negative_codes_map_to_exit_status() {
@@ -218,8 +218,8 @@ mod tests {
}
/// - *Contract stamp:* mapping.md §Exit chunk rule 2 (negative
/// `−N`, N ≥ 2 → `exit-signal(name)` via the table — the POC-3
/// §D.2 live evidence: `−15` → `exit-signal("TERM")`).
/// `−N`, N ≥ 2 → `exit-signal(name)` via the table; the POC-3
/// §D.2 live evidence is `−15` → `exit-signal("TERM")`).
#[test]
fn negative_signals_map_through_the_table() {
for (signum, name) in SIGNAL_NAMES.iter().skip(1) {
@@ -230,7 +230,7 @@ mod tests {
}
/// - *Contract stamp:* mapping.md §Exit chunk rule 3 (`−1` →
/// `exit-status(255)`, never a signal claim — the sentinel/
/// `exit-status(255)`, never a signal claim; the sentinel/
/// SIGHUP collision accepted symmetrically).
#[test]
fn the_sentinel_is_not_a_signal() {
@@ -238,7 +238,7 @@ mod tests {
}
/// - *Contract stamp:* mapping.md §Exit chunk rule 6 (unmapped
/// negatives → rule 3 — the mapping never invents a name).
/// negatives → rule 3; the mapping never invents a name).
#[test]
fn unmapped_negatives_report_255() {
for code in [i32::MIN, -33, -32, -100, -1_000_000] {
@@ -246,7 +246,7 @@ mod tests {
}
}
/// - *Contract stamp:* the table bound — every entry is the
/// - *Contract stamp:* the table bound: every entry is the
/// conventional Unix signal set 1–31, sorted, names unique and
/// uppercase (the vocabulary the derivation table promises).
#[test]
@@ -282,7 +282,7 @@ mod tests {
}
}
/// The client arm's mirror row — runnable in every build the arm
/// The client arm's mirror row, runnable in every build the arm
/// compiles in (session or git; the git-only builds carry the client
/// rows too).
#[cfg(test)]
@@ -290,7 +290,7 @@ mod tests {
mod client_arm_rows {
use super::SIGNAL_NAMES;
/// - *Contract stamp:* the client arm (§module docs' rules 1–3) —
/// - *Contract stamp:* the client arm (§module docs' rules 1–3),
/// the inverse read through the same table, never widened:
/// mapped names ride `−signum`, unmapped names ride the `−1`
/// sentinel (the mapping never invents a signum).