Lint marker debt: 7 unwired-dead-code-untracked sites need real tracking refs + 1 crate-name-collision (koinon)

[forkwright]

Finding

kanon lint now enforces WORKFLOW/unwired-dead-code-untracked (error severity) — every #[allow(dead_code)]/#[expect(dead_code, reason = "...")] must carry a #NNN tracking reference or one of the closed-benign markers (RAII/held/keeps-alive/guard/test-fixture/schema-contract) in its reason. This rule postdates the akroasis#261 baseline (which does not cover it), so it is currently live-blocking kanon gate --stamp independent of any baseline expiry. 7 of the 12 flagged sites are genuinely forward-looking/awaiting-integration code (not test-only), so they need a real tracking ref rather than a benign marker. The other 5 (test-only or an existing tracked gap) are handled inline in the same pass as this issue — see akroasis#244 (kerykeion/store_forward.rs) and the test-fixture marker sites.

Evidence

kanon lint . --min-severity error @ main (8506c10), 2026-07-16 — the 7 sites this issue tracks:

• crates/akroasis/src/main.rs:7 — mod mesh; suppression says "mesh helpers used by daemon; unused in CLI binary build". Verified: format_node_row, build_status_table, build_nodes_table, format_gateway_health have zero production callers anywhere in the tree (grep -rn across all crates) — only exercised by mesh::mod's own unit tests. No daemon/server crate currently calls them; print_status/print_nodes render hardcoded placeholder tables instead of calling these helpers. The "used by daemon" claim does not hold against current tree state.
• crates/akroasis/src/main.rs:60 — Config.config_path field, reason "reserved for future CLI options" — no consumer exists yet.
• crates/syntonia/src/baofeng/constants.rs:8 — protocol constants gated #![cfg_attr(not(feature = "hardware-serial"), expect(dead_code, ...))]; permanently "dead" in any build without the feature.
• crates/syntonia/src/baofeng/variant.rs:5 — same feature-gate pattern for the variant API.
• crates/syntonia/src/hardware/warnings.rs:66,94,113 — collect_scan_warnings, collect_detection_warnings, port_access_denied, reason "crate-local warning helpers are staged for the akroasis hardware backend" — no hardware backend currently calls them.

Why this matters

Dead-code suppressions without a live tracking ref are exactly the pattern that hid the already-filed unwired-capability gaps in this repo (akroasis#235, #236, #238, #244 all began as an unremarked #[allow(dead_code)]). The rule exists to stop that recurring silently. Right now these 7 sites fail the letter of the rule (no ref, no accurate benign marker) while also being real instances of the pattern the rule is designed to catch — the main.rs:7 mesh case in particular has a reason string that is no longer true against current tree state.

Desired correction

Per site, one of:

• Wire the code into a real caller and drop the suppression, or
• Confirm the code is genuinely staged for a specific, named future integration and reference this issue's number in the reason string (already done for the sites above as part of the pass that filed this issue).

Track resolution here; close individual sites out via the kanon lint --refs-live sweep once each is either wired or the reason is otherwise satisfied.

Done when: kanon lint . --min-severity error shows zero WORKFLOW/unwired-dead-code-untracked findings whose reason cites this issue AND either the code has been wired into a real caller or the "staged for future work" framing has been confirmed still accurate.

Note — separate finding, same lint pass

VOCAB/crate-name-collision (warning, non-blocking): crates/koinon/Cargo.toml — the akroasis workspace's koinon crate ("κοινόν — common/shared types for the Akroasis workspace") collides in name with the standalone fleet repo koinon. kanon lint flags this as fixable only by adding a distinct_concepts block to kanon's hub-words.toml (fleet-wide config, lives in the kanon repo, not akroasis) or renaming one of the two. This is a cross-repo naming call outside a single-repo lint fix and is left for an explicit naming decision rather than resolved unilaterally here.

[forkwright]

Severity correction: VOCAB/crate-name-collision is warning-severity, but empirically it still fails kanon gate --stamp (the gate's kanon lint step treats any open finding — warning included — as a step failure, at least via this invocation path; the CLI's own --strict-warnings flag description implies warnings shouldn't block by default, but that's not what the gate step showed in practice). Confirmed by running the full gate on a branch that has zero other lint findings: kanon lint step FAILed solely on this one warning.

Practical implication: no PR on akroasis can currently earn a full Gate-Passed stamp until this is resolved (rename crates/koinon or add the distinct_concepts block to kanon's hub-words.toml), independent of the akroasis#261 baseline and the dead-code markers this issue tracks. Worth prioritizing accordingly.

[forkwright]

The gate found a sixth-and-more cluster: the whole serial auto-detect path is unwired

PR #355 adds --features syntonia/hardware-serial to the check and nextest gate stages — code that, as that PR notes, was compiled and tested by zero gate stage before. Its full-gate-build now fails, and the failure is not a defect in the PR: it is six dead-code errors that were simply never visible because nothing ever compiled that path.

error: constant `BAUD_RATE` is never used              crates/syntonia/src/baofeng/constants.rs:19
error: constant `IDENT_RETRY_DELAY` is never used      crates/syntonia/src/baofeng/constants.rs:80
error: trait `SerialPort` is never used                crates/syntonia/src/baofeng/detect.rs:21
error: variant `VariantIdentification` is never constructed  crates/syntonia/src/baofeng/detect.rs:81
error: function `auto_detect` is never used            crates/syntonia/src/baofeng/detect.rs:114
error: function `try_magic` is never used              crates/syntonia/src/baofeng/detect.rs:129

These are not six unrelated markers. They are one coherent capability — the baofeng serial auto-detect and radio-identification path (auto_detect → try_magic → VariantIdentification, over the SerialPort trait, using BAUD_RATE and IDENT_RETRY_DELAY). It is implemented, it compiles under the feature, and it has no production caller.

Why this belongs on #264 rather than a new issue

This is the same class this issue already names — a capability the codebase documents as unwired instead of tracking. The difference is that #264's seven sites were found by the lint marker; these six were invisible to every check until #355 turned the feature on. Same debt, discovered by a different instrument.

What it means for #355

#355 is not wrong and should not be "fixed" by dropping the feature from the gate — that would restore the blindness it removed. The decision it forces is the one this issue exists to make, and it is a product decision rather than a lint one: is serial auto-detect a shipped capability or not?

• If yes: wire auto_detect into a caller (CLI/API) and the dead-code errors resolve themselves.
• If not yet: annotate the six with #[expect(dead_code, reason = "...")] citing this issue, so the unwiredness is tracked rather than merely asserted in the code. fix(gate): compile and test hardware-serial feature in gate stages #355's author already took exactly this stance for the clippy half, deferring it here "to avoid forcing an unrelated dead-code product decision."

Either way #355 stays as the thing that made this visible. Recorded during an op-pause; not actioned, because wiring-or-not is a scope call rather than a mechanical fix.

[forkwright]

Two operator decisions, and one of them turns out to already be implemented.

Serial auto-detect: not a shipped capability — track as unwired. Already satisfied.

The 2026-08-03 comment framed this as a live choice: wire auto_detect into a caller, or annotate the
six sites as tracked-unwired. The decision is the second. Checking before implementing it, the
annotation is already in the tree and is better than what that comment asked for.

baofeng/detect.rs carries a module-level marker covering the whole cluster:

#![cfg_attr(not(test), expect(dead_code, reason = "baofeng serial auto-detect path
    (SerialPort trait, auto_detect/try_magic handshake, VariantIdentification
    error variant) — implemented but has zero production callers;
    tracked in akroasis#264"))]

Three things it gets right that a mechanical annotation would not. It is one marker for one
coherent capability rather than five copies of the same reason, because the trait, the handshake and
the error variant are a single unwired cluster. It is scoped not(test), because under #[cfg(test)]
the mock-backed tests are real callers and an unconditional expect would come back unfulfilled —
itself an error under -D warnings. And BAUD_RATE and IDENT_RETRY_DELAY carry their own
suppressions, because they are dead with the feature on as well as off, so the module marker does
not reach them.

Confirmed against the tree rather than inferred: kanon lint . --all at origin/main reports zero
WORKFLOW/unwired-dead-code-untracked findings. This half of the issue is closed on its merits.

koinon name collision: rename akroasis's crate

The other decision. VOCAB/crate-name-collision and NAMING/no-fleet-collision are two of the 26 rows
in #261's baseline, and the alternative — a distinct_concepts block in kanon's hub-words.toml —
was rejected for the right reason: both crates are described as common/shared types, so they are not
distinct concepts and declaring them so would be a suppression dressed as a fact.

That leaves the rename as the honest correction, and it is the only remaining work this issue owns.
Taking it next. The replacement name is a GNOMON question rather than a mechanical one, so I will
settle that against the standard and the fleet's taken names before touching anything — a foundational
crate name is visible for as long as the crate exists, and this is the one chance to pick it
deliberately.

[forkwright]

Verified the 7 tracked sites against the current tree rather than against this
issue's July snapshot.

All 7 now carry a tracking ref, which satisfies the letter of
WORKFLOW/unwired-dead-code-untracked:

Site	Reason
akroasis/src/main.rs:11	mesh table/status helpers await daemon integration
akroasis/src/main.rs:63	config fields reserved for future CLI options
syntonia/src/baofeng/constants.rs:12	protocol constants, hardware-serial only
syntonia/src/baofeng/variant.rs:9	variant API, hardware-serial only
syntonia/src/hardware/warnings.rs:70,98,117	staged for the akroasis hardware backend

The "still staged" framing is accurate, and I checked rather than assumed.
Every named helper has zero references outside its own defining file:
format_node_row, build_status_table, build_nodes_table,
format_gateway_health, collect_scan_warnings, collect_detection_warnings,
port_access_denied — all 0 consumers elsewhere in crates/. Nothing has been
wired since this issue was filed, so no reason string has gone stale in the way
the original main.rs:7 one had.

What is still weak. The Desired correction asks that staged code reference
a specific, named future integration. These reasons name a direction
("awaits daemon integration", "staged for the akroasis hardware backend") but
not a consumer that anyone can check. That is the difference between a
suppression that expires when something lands and one that can sit forever while
still reading as accurate — which is the pattern this rule exists to catch.

There are live issues that would each consume one of these groups (mesh
helpers, the hardware warning helpers, the hardware-serial protocol layer).
Repointing each reason at its actual consumer is the remaining work here, and it
makes every suppression falsifiable: when that issue lands, the suppression is
provably wrong and must go.

Taking that as a follow-up in this lane, separate from the crate-rename change
so each stays reviewable.

[forkwright]

One of the 7 sites turned out to be hiding a live defect rather than staged
work: main.rs:63's Config. Filed as issue 461 with executed evidence — the
config is loaded and discarded, so any AKROASIS_* environment variable aborts
the CLI before dispatch, while the single accepted key config_path is inert.

That is worth noting here because the suppression's reason ("config fields
reserved for future CLI options") was accurate about the field and silent
about the surface. Accuracy at the site is not the same as the site being
harmless, which is the limit of what a tracking-ref rule can catch on its own.

Mapping for the remaining sites, derived by reading each consumer rather than by
matching titles:

• main.rs:11 (mesh table/status helpers) → 83. The helpers need a
  NodeDb and a GatewayBridge; the CLI has neither and says so in three
  explicit constants (LIVE_TRANSPORT_MESSAGE, LIVE_NODES_MESSAGE,
  LIVE_TOPOLOGY_MESSAGE). Issue 83 is the Meshtastic protobuf and connection
  layer that supplies them.
• baofeng/constants.rs:12, baofeng/variant.rs:9 → 79. Both are
  hardware-serial gated and consumed only by the protocol module; issue 79 is
  the UV-5RM/BF-F8HP protocol qualification that names the same magic bytes and
  variant handling.
• hardware/warnings.rs:70,98,117 → 410. HardwareWarning is re-exported
  but constructed nowhere outside its own file, while akroasis's detect path
  (radio/serial_hardware.rs) already calls detect_radios without surfacing
  warnings. Issue 410 owns the caller-initiated detect/open/handshake path where
  they belong.

Repointing each reason at its consumer makes the suppression falsifiable: when
that issue lands, the suppression is provably wrong and must be removed. Today
each names a direction instead, which nothing can ever contradict.

Holding the edits until PR 460 merges — it touches hardware/warnings.rs and
baofeng/codec.rs, so doing both at once would collide.

[forkwright]

Closing. Every clause verified against merged main at 8c9ca31, not against
the branches that claimed them.

Done when, clause by clause.

"zero WORKFLOW/unwired-dead-code-untracked findings whose reason cites this
issue" — zero findings cite 264, because no reason does any more. Each of the 7
now names the issue whose landing disproves it: main.rs:11 → 83,
baofeng/{constants,variant}.rs → 79, hardware/warnings.rs ×3 → 410,
main.rs:63 → 461. The rule itself reports nothing repo-wide.

"either wired into a real caller or the staged framing confirmed still
accurate" — confirmed by measurement rather than by reading the reasons.
format_node_row, build_status_table, build_nodes_table,
format_gateway_health, collect_scan_warnings, collect_detection_warnings
and port_access_denied each have zero references outside their defining file,
so nothing had been wired since this issue was filed and no reason had gone
stale the way the original main.rs:7 one had.

The Note (VOCAB/crate-name-collision). Resolved by the rename, not by a
distinct_concepts entry. The collision was not incidental — the crate held the
workspace vocabulary and the evidence about what was done under one
"common types" label — so it split into stoicheion and tekmerion (#460).
Both names verified absent from the 31-row canonical registry and from the
naming corpus before use. The two koinon baseline entries this issue's own
text described as "deferred to a fleet naming decision" are gone with it.

State of the repo now: kanon lint . --min-severity error exits 0 with zero
error findings. That is past what this issue asked — it also clears a
RUST/indexing-slicing in kryphos/storage.rs that arrived with #449 and that
CI's clippy structurally cannot catch, since indexing_slicing is an
allow-by-default restriction lint.

What this issue deliberately does not carry forward. One site turned out to
be hiding a live defect rather than staged work: Config is loaded and
discarded, so AKROASIS_* variables abort unrelated commands. That is 461, with
its own evidence and a design decision attached, and it is not closed here.